1. Memperkenalkan Assistants API OpenAI

1.1 Definisi dan Tujuan dari Assistants API

Assistants API memungkinkan pengembang untuk membangun asisten kecerdasan buatan dalam aplikasi mereka sendiri. Dengan mendefinisikan perintah kustom dan memilih model, asisten dapat menggunakan model, tools, dan pengetahuan untuk merespons pertanyaan pengguna. Saat ini, Assistants API mendukung tiga jenis tools: Code Interpreter, Pemulihan, dan Pemanggilan Fungsi.

1.2 Aplikasi dari Assistants API

Assistants API cocok untuk berbagai skenario yang memerlukan dukungan AI interaktif. Contohnya:

  • Dukungan Pelanggan: Otomatis menjawab pertanyaan umum untuk mengurangi beban kerja layanan pelanggan manusia.
  • Pendidikan Online: Menjawab pertanyaan siswa dan memberikan dukungan pembelajaran yang disesuaikan.
  • Analisis Data: Menganalisis file data yang diunggah pengguna, menghasilkan laporan, dan visualisasi grafik.
  • Rekomendasi Terpersonalisasi: Memberikan saran dan layanan yang dipersonalisasi berdasarkan interaksi historis pengguna.

1.3 Konsep Inti dari Assistants

Core Concepts

Objek inti Assistants API meliputi Assistant, Thread, dan Message. Berikut adalah pengenalan detail tentang objek-objek tersebut dan fungsinya:

Assistant

Objek Assistant dibangun di atas model OpenAI dan dapat memanggil tools asisten kecerdasan buatan. Anda dapat menyesuaikan instruksi Assistant untuk menyesuaikan kepribadian dan fungsinya. Contohnya, Anda dapat membuat Assistant yang disebut "Analis Data" yang menganalisis data dan menghasilkan grafik menggunakan tool "code_interpreter".

Thread

Objek Thread mewakili sesi percakapan antara pengguna dan Assistant. Anda dapat membuat Thread untuk setiap pengguna dan menambahkan pesan ke dalamnya saat pengguna berinteraksi dengan Assistant. Objek Thread efektif menyimpan riwayat pesan dan memotong pesan saat diperlukan untuk mematuhi batas panjang konteks model.

Message

Objek Message dapat dibuat oleh pengguna atau Assistant. Pesan dapat berisi teks, gambar, dan file lainnya. Pesan disimpan sebagai daftar di Thread. Dalam penggunaan API yang sebenarnya, pengembang dapat menambahkan pesan pengguna ke Thread dan memicu respon Assistant sesuai kebutuhan.

Run

Objek Run mewakili eksekusi permintaan asisten, memanggil asisten berdasarkan konten pesan dalam Thread. Asisten memanfaatkan konfigurasinya dan pesan-pesan Thread untuk mengeksekusi tugas dengan memanggil model dan tools. Sebagai bagian dari run, asisten menambahkan pesan ke thread.

2. Proses Pengembangan Assistants API

2.1 Buat Asisten Anda sendiri

Untuk membuat Asisten, Anda perlu mengirim permintaan ke API dengan instruksi, nama model, dan konfigurasi tool. Berikut adalah contoh sederhana membuat asisten tutor matematika pribadi:

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Kamu adalah tutor matematika pribadi. Tulis dan jalankan kode untuk menjawab pertanyaan matematika.",
    "name": "Tutor Matematika",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4"
  }'

Parameter API:

  • instructions - instruksi sistem yang memberi tahu asisten apa yang harus dilakukan.
  • name - nama asisten.
  • tools - mendefinisikan tool mana yang dapat digunakan oleh asisten. Setiap asisten dapat memiliki hingga 128 tools. Jenis tool saat ini dapat berupa code_interpreter, pemulihan, atau fungsi.
  • model - model mana yang harus digunakan oleh asisten?

Setelah berhasil membuat Asisten, Anda akan menerima ID Asisten.

2.2 Buat Thread Sesi

Sebuah Thread mewakili percakapan, dan kami merekomendasikan membuat Thread sesi untuk setiap pengguna saat mereka memulai percakapan. Anda dapat membuat Thread sebagai berikut:

curl https://api.openai.com/v1/threads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d ''

Setelah membuat Thread, Anda akan menerima ID Thread.

2.3 Menambahkan Pesan ke Thread

Anda dapat menambahkan pesan ke Thread tertentu, yang berisi teks dan secara opsional memungkinkan pengguna mengunggah file. Contohnya:

curl https://api.openai.com/v1/threads/{thread_id}/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
      "role": "user",
      "content": "Saya perlu menyelesaikan persamaan ini `3x + 11 = 14`. Bisakah kamu membantu saya?"
    }'

Parameter API:

  • thread_id - merepresentasikan ID percakapan thread, yang dapat Anda peroleh ketika membuat Thread.

Isi body permintaan API adalah pesan pengguna, biasanya mewakili pertanyaan pengguna, mirip dengan struktur pesan dari model percakapan.

2.4 Menjalankan Asisten untuk Menghasilkan Tanggapan

Untuk membuat asisten merespons pesan pengguna, Anda perlu membuat Run. Ini memungkinkan asisten untuk membaca Thread dan memutuskan apakah akan menggunakan alat (jika diaktifkan) atau hanya menggunakan model untuk menjawab pertanyaan dengan baik.

Catatan: Sampai pada titik ini, asisten belum merespons pertanyaan pengguna. Hanya ketika Anda memanggil API Run, asisten kecerdasan buatan akan merespons pertanyaan pengguna.

curl https://api.openai.com/v1/threads/{thread_id}/runs \
  -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "assistant_id": "assistant_id",
    "instructions": "Alamatkan pengguna sebagai Jane Doe. Pengguna memiliki akun premium."
  }'

Parameter API:

  • thread_id - merepresentasikan ID percakapan thread, yang dapat Anda peroleh ketika membuat Thread.
  • assistant_id - merepresentasikan ID asisten, yang dapat Anda peroleh ketika membuat Asisten.
  • instructions - instruksi asisten yang dapat menggantikan instruksi yang diatur saat membuat Asisten.

Permintaan API yang berhasil akan mengembalikan ID Run.

2.5 Memeriksa Status Pengejaran Asisten

Setelah memulai tugas (Run) dalam Asisten, eksekusi tugasnya bersifat asinkron. Ini berarti kita perlu secara teratur memeriksa status Run untuk menentukan apakah sudah selesai. Untuk memeriksa status Run, dapat dilakukan dengan melakukan permintaan HTTP menggunakan CURL. Berikut adalah penjelasan khusus tentang proses ini.

Contoh Permintaan CURL:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Penjelasan Parameter API:

  • https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123: Ini adalah URL permintaan API, di mana thread_abc123 adalah pengidentifikasi unik dari thread (Thread), dan run_abc123 adalah pengidentifikasi unik dari Run.

Contoh Isi Balasan API Body:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "completed",
  "created_at": 1699073585,
  ...
}

Penjelasan Parameter Balasan API:

  • id: Pengidentifikasi unik dari Run.
  • object: Menunjukkan jenis objek yang dikembalikan, yang di sini adalah thread.run.
  • status: Status Run, nilai-nilai yang mungkin meliputi queued, in_progress, completed, requires_action, failed, dll.
  • created_at: Timestamp kapan Run dibuat.

2.6 Mendapatkan Hasil Tanggapan Asisten

Setelah Run Asisten selesai, kita dapat membaca hasil tanggapan Asisten dengan memeriksa pesan-pesan yang ditambahkan ke thread (Thread). Berikut adalah demonstrasi bagaimana melakukan permintaan melalui CURL dan penjelasan detail tentang parameter API.

Tips: Mirip dengan percakapan dengan Asisten, ketika Asisten selesai memproses pertanyaan pengguna, Asisten akan menambahkan pesan ke thread percakapan (Thread). Oleh karena itu, kita hanya perlu menanyakan pesan terbaru dalam thread percakapan (Thread) untuk mendapatkan tanggapan Asisten.

Contoh Permintaan CURL:

curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1"

Penjelasan Parameter API:

  • https://api.openai.com/v1/threads/thread_abc123/messages: URL permintaan dari API, di mana thread_abc123 adalah pengenal unik dari benang (Thread).
  • Sama seperti header permintaan yang digunakan untuk memeriksa status Run sebelumnya, termasuk informasi otentikasi dan informasi versi API.

Contoh Hasil Respon Asisten:

Pada contoh ini, pengguna menanyakan pertanyaan matematika kepada Asisten, dan Asisten menambahkan Pesan respon ke Thread setelah memprosesnya.

Pengguna: Saya perlu menyelesaikan persamaan `3x + 11 = 14`. Bisa tolong?
Asisten: Tentu saja, Jane Doe. Untuk menyelesaikan persamaan `(3x + 11 = 14)`, Anda perlu mengisolasi `(x)` di satu sisi persamaan. Biar saya menghitung nilai `(x)` untuk Anda.
Asisten: Solusi dari persamaan `(3x + 11 = 14)` adalah `(x = 1)`.

Setelah mendapatkan hasil respon dari Asisten, dapat disajikan kepada pengguna untuk membantu mereka memahami dan memanfaatkan layanan yang diberikan oleh Asisten.

3. Alat: Alat Bawaan yang Disediakan oleh OpenAI

3.1 Alat Penerjemah Kode

Alat Penerjemah Kode memungkinkan API Asisten untuk menulis dan menjalankan kode Python di lingkungan eksekusi pasir. Alat ini dapat menangani berbagai format data dan file, dan menghasilkan file dengan data dan gambar grafis. Penerjemah Kode memungkinkan Asisten Anda untuk menjalankan kode secara iteratif untuk menyelesaikan masalah pemrograman dan matematika yang kompleks. Ketika kode yang ditulis oleh Asisten gagal dijalankan, dapat mengulangi kode ini dengan mencoba kode yang berbeda hingga kode berjalan dengan sukses.

Mengaktifkan Penerjemah Kode

Untuk mengaktifkan Penerjemah Kode, lewati code_interpreter dalam parameter alat saat membuat objek Asisten:

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Anda adalah guru matematika pribadi. Ketika ditanyai pertanyaan matematika, tulis dan jalankan kode untuk menjawabnya.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-turbo-preview"
  }'

Kemudian, model akan memutuskan kapan untuk memanggil Penerjemah Kode saat runtime berdasarkan sifat permintaan pengguna. Anda dapat memfasilitasi perilaku ini melalui instruksi Asisten (misalnya, "Tulis kode untuk memecahkan masalah ini").

Menggunakan Penerjemah Kode untuk Memproses File

Penerjemah Kode dapat memparas data dari file. Ini berguna ketika Anda ingin menyediakan sejumlah besar data ke Asisten atau memungkinkan pengguna Anda mengunggah file mereka sendiri untuk dianalisis. Perhatikan bahwa file yang diunggah untuk Penerjemah Kode tidak akan diindeks untuk pengambilan. Untuk informasi detail tentang cara mengindeks file untuk pengambilan, lihat bagian Alat Pengambilan di bawah ini.

File yang lulus pada tingkat Asisten dapat diakses oleh semua Run yang terkait dengan Asisten ini:

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v1' \
  -d '{
    "instructions": "Anda adalah guru matematika pribadi. Ketika ditanyai pertanyaan matematika, tulis dan jalankan kode untuk menjawabnya.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo-preview",
    "file_ids": ["file_123abc456"]
  }'

Membaca Gambar dan Berkas yang Dihasilkan oleh Penerjemah Kode

Penerjemah Kode juga dapat menghasilkan berkas dalam API, seperti menghasilkan diagram gambar, berkas CSV, dan berkas PDF. Ada dua jenis berkas yang dihasilkan: gambar dan berkas data (misalnya, berkas CSV dengan data yang dihasilkan oleh Asisten).

Ketika Penerjemah Kode menghasilkan sebuah gambar, Anda dapat menemukan dan mengunduh berkas ini di bidang file_id dari respon Pesan Asisten:

{
    "id": "msg_abc123",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_abc123",
    "role": "assistant",
    "content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  // ...
}

3.2 Alat Pemulihan

Alat Pemulihan meningkatkan kapabilitas Asisten dengan menambahkan pengetahuan dari luar model (seperti informasi produk properti atau dokumen yang diberikan pengguna). Begitu berkas diunggah dan diteruskan ke Asisten, OpenAI secara otomatis akan memotong, mengindeks, menyimpan embedding dokumen Anda, dan menerapkan pencarian vektor untuk mengambil konten relevan untuk menjawab pertanyaan pengguna.

Mengaktifkan Pemulihan

Untuk mengaktifkan pemulihan pada parameter tools Asisten, lewati retrieval:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Anda adalah chatbot dukungan pelanggan. Gunakan basis pengetahuan Anda untuk merespons pertanyaan pelanggan secara efektif.",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
  }'

Unggah Berkas untuk Pemulihan

Mirip dengan Penerjemah Kode, berkas dapat diunggah pada tingkat Asisten atau pada tingkat Pesan individu.

curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/knowledge.pdf"

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Anda adalah chatbot dukungan pelanggan. Gunakan basis pengetahuan Anda untuk merespons pertanyaan pelanggan secara efektif.",
    "name": "Tutor Matematika",
    "tools": [{"type": "retrieval"}],
    "model": "gpt-4-turbo-preview"
    "file_ids": ["file_123abc456"]
  }'

3.3 Alat Pemanggilan Fungsi

Mirip dengan API Penyelesaian Obrolan, API Asisten mendukung pemanggilan fungsi. Pemanggilan fungsi memungkinkan Anda untuk mendeskripsikan fungsi-fungsi kepada Asisten dan cerdas mengembalikan fungsi yang akan dipanggil beserta parameternya. Ketika pemanggilan fungsi berjalan, API Asisten akan memberhentikan eksekusi, dan Anda dapat memberikan hasil dari pemanggilan fungsi untuk melanjutkan eksekusi.

Mendefinisikan Fungsi

Ketika membuat suatu Asisten, Anda dapat mendefinisikan serangkaian fungsi yang dapat dipanggil oleh asisten. Fungsi-fungsi ini perlu dijelaskan secara eksplisit saat membuat objek asisten. Setiap fungsi harus memiliki nama unik, deskripsi, dan spesifikasi parameter.

Berikut ini adalah contoh kode yang menunjukkan bagaimana mendefinisikan dua fungsi menggunakan perintah curl saat membuat suatu asisten:

curl https://api.openai.com/v1/assistants \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "instructions": "Kamu adalah bot ramalan cuaca. Gunakan fungsi-fungsi yang disediakan untuk menjawab pertanyaan.",
    "tools": [{
      "type": "function",
      "function": {
        "name": "getCurrentWeather",
        "description": "Dapatkan kondisi cuaca untuk lokasi tertentu",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Kota dan negara bagian, misalnya, San Francisco, CA"},
            "unit": {"type": "string", "enum": ["c", "f"]}
          },
          "required": ["location"]
        }
      }
    },
    {
      "type": "function",
      "function": {
        "name": "getNickname",
        "description": "Dapatkan nama panggilan untuk sebuah kota",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {"type": "string", "description": "Kota dan negara bagian, misalnya, San Francisco, CA"}
          },
          "required": ["location"]
        }
      }
    }],
    "model": "gpt-4-turbo-preview"
  }'

Membaca Fungsi yang Dipanggil oleh Asisten

Ketika seorang pengguna mengirimkan suatu pesan kepada asisten dan isi pesan tersebut memicu pemanggilan fungsi, Anda perlu membaca informasi dari pemanggilan fungsi ini. Selama proses ini, asisten akan menghasilkan suatu run dengan status requires_action. Pada titik ini, Anda dapat mendapatkan objek Run untuk mendapatkan informasi detail tentang pemanggilan fungsi.

Berikut contoh pengambilan objek Run, yang menunjukkan bagaimana mendapatkan informasi dari pemanggilan fungsi:

{
  "id": "run_abc123",
  "object": "thread.run",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "id": "call_abc123",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "id": "call_abc456",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
  ...
}

Parameter tool_calls berisi informasi pemanggilan fungsi, dan Anda hanya perlu memanggil fungsi yang sesuai dalam program lokal Anda.

Mengirimkan Output Fungsi

Setelah menjalankan pemanggilan fungsi secara lokal dan mendapatkan hasilnya, Anda perlu mengirimkan hasil tersebut ke asisten Assistants sehingga asisten dapat melanjutkan proses permintaan pengguna. Saat mengirimkan output fungsi, Anda perlu memastikan bahwa hasil output terkait dengan pemanggilan fungsi asli.

Berikut contoh kode untuk mengirimkan hasil output fungsi:

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_123/submit_tool_outputs \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "{\"temperature\": \"22\", \"unit\": \"celsius\"}"
      }, 
      {
        "tool_call_id": "call_abc456",
        "output": "{\"nickname\": \"LA\"}"
      }
    ]
  }'

Penjelasan parameter:

  • thread_abc123 mewakili ID percakapan thread
  • run_123 mewakili ID objek Run
  • tool_call_id mewakili ID dari suatu pemanggilan fungsi tertentu, yang diperoleh dari parameter tool_calls sebelumnya.

Setelah berhasil mengirimkan semua hasil output fungsi, status objek Run akan diperbarui lagi, dan asisten akan melanjutkan pemrosesan dan mengembalikan respons akhir kepada pengguna.