Referensi Assistants API (Pratinjau)
Catatan
-
Pencarian file dapat menyerap hingga 10.000 file per asisten - 500 kali lebih banyak dari sebelumnya. Solusi ini cepat, mendukung kueri paralel melalui pencarian multi-utas, dan fitur pemeringkatan ulang dan penulisan ulang kueri yang ditingkatkan.
- Penyimpanan vektor adalah objek baru di API. Setelah file ditambahkan ke penyimpanan vektor, file secara otomatis diurai, dipotong, dan disematkan, dibuat siap untuk dicari. Penyimpanan vektor dapat digunakan di seluruh asisten dan utas, menyederhanakan manajemen dan penagihan file.
- Kami telah menambahkan dukungan untuk
tool_choiceparameter yang dapat digunakan untuk memaksa penggunaan alat tertentu (seperti pencarian file, penerjemah kode, atau fungsi) dalam eksekusi tertentu.
Artikel ini menyediakan dokumentasi referensi untuk Python dan REST untuk Assistants API (Pratinjau) baru. Panduan langkah demi langkah yang lebih mendalam disediakan dalam panduan memulai.
Membuat asisten
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
Buat asisten dengan model dan instruksi.
Isi permintaan
| Nama | Tipe | Wajib | Deskripsi |
|---|---|---|---|
| model | string | Wajib | Nama penyebaran model model yang akan digunakan. |
| nama | string atau null | Opsional | Nama asisten. Panjang maksimum adalah 256 karakter. |
| description | string atau null | Opsional | Penjabaran dari asisten. Panjang maksimum adalah 512 karakter. |
| petunjuk | string atau null | Opsional | Instruksi sistem yang digunakan asisten. Panjang maksimum adalah 256.000 karakter. |
| alat | array | Opsional | Default ke []. Daftar alat yang diaktifkan pada asisten. Mungkin ada maksimal 128 alat per asisten. Alat saat ini dapat dari jenis code_interpreter, atau function. Deskripsi function dapat maksimal 1.024 karakter. |
| metadata | peta | Opsional | Set 16 pasangan kunci-nilai yang dapat dilampirkan ke objek. Ini dapat berguna untuk menyimpan informasi tambahan tentang objek dalam format terstruktur. Kunci dapat memiliki panjang maksimal 64 karakter dan nilai dapat memiliki panjang maksimal 512 karakter. |
| suhu | angka atau null | Opsional | Default ke 1. Menentukan suhu pengambilan sampel apa yang akan digunakan, antara 0 dan 2. Nilai yang lebih tinggi seperti 0,8 akan membuat output lebih acak, sementara nilai yang lebih rendah seperti 0,2 akan membuatnya lebih fokus dan deterministik. |
| top_p | angka atau null | Opsional | Default ke 1. Alternatif untuk pengambilan sampel dengan suhu, yang disebut pengambilan sampel nukleus, di mana model mempertimbangkan hasil token dengan massa peluang top_p. Jadi 0,1 berarti hanya token yang terdiri dari 10% massa peluang teratas yang dipertimbangkan. Kami umumnya merekomendasikan untuk mengubah ini atau suhu tetapi tidak keduanya. |
| response_format | string atau objek | Opsional | Menentukan format yang harus dihasilkan model. Kompatibel dengan GPT-4 Turbo dan semua model GPT-3.5 Turbo sejak gpt-3.5-turbo-1106. Mengatur parameter ini untuk { "type": "json_object" } mengaktifkan mode JSON, yang menjamin pesan yang dihasilkan model adalah JSON yang valid. Yang penting, saat menggunakan mode JSON, Anda juga harus menginstruksikan model untuk menghasilkan JSON sendiri menggunakan sistem atau pesan pengguna. Tanpa instruksi ini, model dapat menghasilkan aliran spasi kosong yang tidak berujung sampai pembuatan mencapai batas token, yang mengakibatkan permintaan yang berjalan lama dan tampaknya "macet". Selain itu, konten pesan dapat dipotong sebagian jika Anda menggunakan finish_reason="length", yang menunjukkan pembuatan terlampaui max_tokens atau percakapan melebihi panjang konteks maksimum. |
| tool_resources | object | Opsional | Sekumpulan sumber daya yang digunakan oleh alat asisten. Sumber daya khusus untuk jenis alat. Misalnya, alat ini code_interpreter memerlukan daftar ID file, sementara alat ini file_search memerlukan daftar ID penyimpanan vektor. |
jenis response_format
tali
auto merupakan nilai defaultnya.
object
Nilai yang mungkin type : text, json_object, json_schema.
json_schema
| Nama | Tipe | Deskripsi | Default | Diperlukan/Opsional |
|---|---|---|---|---|
description |
string | Deskripsi untuk apa format respons, digunakan oleh model untuk menentukan cara merespons dalam format. | Opsional | |
name |
string | Nama format respons. Harus a-z, A-Z, 0-9, atau berisi garis bawah dan tanda hubung, dengan panjang maksimum 64. | Wajib | |
schema |
object | Skema untuk format respons, dijelaskan sebagai objek Skema JSON. | Opsional | |
strict |
boolean atau null | Apakah akan mengaktifkan kepatuhan skema yang ketat saat menghasilkan output. Jika diatur ke true, model akan selalu mengikuti skema yang tepat yang ditentukan di schema bidang . Hanya subset Skema JSON yang didukung saat strict adalah true. |
salah | Opsional |
properti tool_resources
code_interpreter
| Nama | Tipe | Deskripsi | Default |
|---|---|---|---|
file_ids |
array | Daftar ID file yang disediakan untuk alat code_interpreter. Mungkin ada maksimal 20 file yang terkait dengan alat ini. | [] |
file_search
| Nama | Tipe | Deskripsi | Diperlukan/Opsional |
|---|---|---|---|
vector_store_ids |
array | Penyimpanan vektor yang terpasang pada utas ini. Mungkin ada maksimal 1 penyimpanan vektor yang terpasang pada utas. | Opsional |
vector_stores |
array | Pembantu untuk membuat penyimpanan vektor dengan file_ids dan melampirkannya ke utas ini. Mungkin ada maksimal 1 penyimpanan vektor yang terpasang pada utas. | Opsional |
vector_stores
| Nama | Tipe | Deskripsi | Diperlukan/Opsional |
|---|---|---|---|
file_ids |
array | Daftar ID file yang akan ditambahkan ke penyimpanan vektor. Mungkin ada maksimal 10000 file di penyimpanan vektor. | Opsional |
chunking_strategy |
object | Strategi penggugusan yang digunakan untuk memotong file. Jika tidak diatur, akan menggunakan strategi otomatis. | Opsional |
metadata |
peta | Set 16 pasangan kunci-nilai yang dapat dilampirkan ke penyimpanan vektor. Ini dapat berguna untuk menyimpan informasi tambahan tentang penyimpanan vektor dalam format terstruktur. Kunci dapat memiliki panjang maksimal 64 karakter dan nilai dapat memiliki panjang maksimal 512 karakter. | Opsional |
chunking_strategy
| Nama | Tipe | Deskripsi | Diperlukan/opsional |
|---|---|---|---|
Auto Chunking Strategy |
object | Strategi default. Strategi ini saat ini menggunakan max_chunk_size_tokens dari 800 dan chunk_overlap_tokens dari 400.
type selalu auto |
Wajib |
Static Chunking Strategy |
object |
type Selalu static |
Wajib |
Strategi Penggugusan Statis
| Nama | Tipe | Deskripsi | Diperlukan/Opsional |
|---|---|---|---|
max_chunk_size_tokens |
Integer | Jumlah maksimum token di setiap gugus. Nilai defaultnya adalah 800. Nilai minimum adalah 100 dan nilai maksimumnya adalah 4096. |
Wajib |
chunk_overlap_tokens |
Integer | Jumlah token yang tumpang tindih di antara gugus. Nilai defaultnya adalah 400. Perhatikan bahwa tumpang tindih tidak boleh melebihi setengah dari max_chunk_size_tokens. |
Wajib |
Mengembalikan
Sebuah objek asisten .
Contoh permintaan buat asisten
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
assistant = client.beta.assistants.create(
instructions="You are an AI assistant that can write code to help answer math questions",
model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name.
tools=[{"type": "code_interpreter"}]
)
Mencantumkan asisten
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview
Mengembalikan daftar semua asisten.
Parameter kueri
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
limit |
Integer | Opsional | Batas jumlah objek yang akan dikembalikan. Batas dapat berkisar antara 1 dan 100, dan defaultnya adalah 20. |
order |
string | Opsional - Default ke desc | Urutkan urutan menurut tanda waktu created_at objek. naik untuk urutan naik dan turun untuk urutan turun. |
after |
string | Opsional | Kursor untuk digunakan dalam penomoran halaman.
after adalah ID objek yang menentukan tempat Anda dalam daftar. Misalnya, jika Anda membuat permintaan daftar dan menerima 100 objek, berakhir dengan obj_foo, panggilan berikutnya dapat menyertakan after=obj_foo untuk mengambil halaman berikutnya dari daftar. |
before |
string | Opsional | Kursor untuk digunakan dalam penomoran halaman.
before adalah ID objek yang menentukan tempat Anda dalam daftar. Misalnya, jika Anda membuat permintaan daftar dan menerima 100 objek, berakhir dengan obj_foo, panggilan berikutnya dapat menyertakan before=obj_foo untuk mengambil halaman sebelumnya dari daftar. |
Mengembalikan
Daftar objek asisten
Contoh asisten daftar
from openai import AzureOpenAI
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistants = client.beta.assistants.list(
order="desc",
limit="20",
)
print(my_assistants.data)
Mengambil asisten
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview
Mengambil asisten.
Parameter jalur
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
assistant_id |
string | Wajib | ID asisten yang akan diambil. |
Kembali
Objek asisten yang cocok dengan ID yang ditentukan.
Contoh mengambil asisten
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)
Mengubah asisten
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview
Memodifikasi asisten.
Parameter jalur
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
| assistant_id | string | Wajib | ID asisten tempat file berada. |
Isi Permintaan
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
model |
Opsional | Nama penyebaran model model yang akan digunakan. | |
name |
string atau null | Opsional | Nama asisten. Panjang maksimum adalah 256 karakter. |
description |
string atau null | Opsional | Penjabaran dari asisten. Panjang maksimum adalah 512 karakter. |
instructions |
string atau null | Opsional | Instruksi sistem yang digunakan asisten. Panjang maksimum adalah 32768 karakter. |
tools |
array | Opsional | Default ke []. Daftar alat yang diaktifkan pada asisten. Mungkin ada maksimal 128 alat per asisten. Alat bisa dari jenis code_interpreter, atau fungsi. Deskripsi function dapat maksimal 1.024 karakter. |
metadata |
peta | Opsional | Set 16 pasangan kunci-nilai yang dapat dilampirkan ke objek. Ini dapat berguna untuk menyimpan informasi tambahan tentang objek dalam format terstruktur. Kunci dapat memiliki panjang maksimal 64 karakter dan nilai dapat memiliki panjang maksimal 512 karakter. |
temperature |
angka atau null | Opsional | Default ke 1. Menentukan suhu pengambilan sampel apa yang akan digunakan, antara 0 dan 2. Nilai yang lebih tinggi seperti 0,8 akan membuat output lebih acak, sementara nilai yang lebih rendah seperti 0,2 akan membuatnya lebih fokus dan deterministik. |
top_p |
angka atau null | Opsional | Default ke 1. Alternatif untuk pengambilan sampel dengan suhu, yang disebut pengambilan sampel nukleus, di mana model mempertimbangkan hasil token dengan massa peluang top_p. Jadi 0,1 berarti hanya token yang terdiri dari 10% massa peluang teratas yang dipertimbangkan. Kami umumnya merekomendasikan untuk mengubah ini atau suhu tetapi tidak keduanya. |
response_format |
string atau objek | Opsional | Menentukan format yang harus dihasilkan model. Kompatibel dengan GPT-4 Turbo dan semua model GPT-3.5 Turbo sejak gpt-3.5-turbo-1106. Mengatur parameter ini untuk { "type": "json_object" } mengaktifkan mode JSON, yang menjamin pesan yang dihasilkan model adalah JSON yang valid. Yang penting, saat menggunakan mode JSON, Anda juga harus menginstruksikan model untuk menghasilkan JSON sendiri menggunakan sistem atau pesan pengguna. Tanpa instruksi ini, model dapat menghasilkan aliran spasi kosong yang tidak berujung sampai pembuatan mencapai batas token, yang mengakibatkan permintaan yang berjalan lama dan tampaknya "macet". Selain itu, konten pesan dapat dipotong sebagian jika Anda menggunakan finish_reason="length", yang menunjukkan pembuatan terlampaui max_tokens atau percakapan melebihi panjang konteks maksimum. |
tool_resources |
object | Opsional | Sekumpulan sumber daya yang digunakan oleh alat asisten. Sumber daya khusus untuk jenis alat. Misalnya, alat ini code_interpreter memerlukan daftar ID file, sementara alat ini file_search memerlukan daftar ID penyimpanan vektor. |
Kembali
Objek asisten yang dimodifikasi.
Contoh asisten modifikasi
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
my_updated_assistant = client.beta.assistants.update(
"asst_abc123",
instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
name="HR Helper",
tools=[{"type": "code-interpreter"}],
model="gpt-4", #model = model deployment name
)
print(my_updated_assistant)
Hapus asisten
DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview
Menghapus asisten.
Parameter jalur
| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
assistant_id |
string | Wajib | ID asisten tempat file berada. |
Kembali
Status penghapusan.
Contoh asisten penghapusan
client = AzureOpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
api_version="2024-08-01-preview",
azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
)
response = client.beta.assistants.delete("asst_abc123")
print(response)
Referensi API unggahan file
Asisten menggunakan API yang sama untuk pengunggahan file sebagai penyempurnaan. Saat mengunggah file, Anda harus menentukan nilai yang sesuai untuk parameter tujuan.
Objek asisten
| Bidang | Jenis | Deskripsi |
|---|---|---|
id |
string | Pengidentifikasi, yang dapat dirujuk di titik akhir API. |
object |
string | Jenis objek, yang selalu asisten. |
created_at |
Integer | Tanda waktu Unix (dalam detik) saat asisten dibuat. |
name |
string atau null | Nama asisten. Panjang maksimum adalah 256 karakter. |
description |
string atau null | Penjabaran dari asisten. Panjang maksimum adalah 512 karakter. |
model |
string | Nama nama penyebaran model yang akan digunakan. |
instructions |
string atau null | Instruksi sistem yang digunakan asisten. Panjang maksimum adalah 32768 karakter. |
tools |
array | Daftar alat yang diaktifkan pada asisten. Mungkin ada maksimal 128 alat per asisten. Alat bisa dari jenis code_interpreter, atau fungsi. Deskripsi function dapat maksimal 1.024 karakter. |
metadata |
peta | Set 16 pasangan kunci-nilai yang dapat dilampirkan ke objek. Ini dapat berguna untuk menyimpan informasi tambahan tentang objek dalam format terstruktur. Kunci dapat memiliki panjang maksimal 64 karakter dan nilai dapat memiliki panjang maksimal 512 karakter. |
temperature |
angka atau null | Default ke 1. Menentukan suhu pengambilan sampel apa yang akan digunakan, antara 0 dan 2. Nilai yang lebih tinggi seperti 0,8 akan membuat output lebih acak, sementara nilai yang lebih rendah seperti 0,2 akan membuatnya lebih fokus dan deterministik. |
top_p |
angka atau null | Default ke 1. Alternatif untuk pengambilan sampel dengan suhu, yang disebut pengambilan sampel nukleus, di mana model mempertimbangkan hasil token dengan massa peluang top_p. Jadi 0,1 berarti hanya token yang terdiri dari 10% massa peluang teratas yang dipertimbangkan. Kami umumnya merekomendasikan untuk mengubah ini atau suhu tetapi tidak keduanya. |
response_format |
string atau objek | Menentukan format yang harus dihasilkan model. Kompatibel dengan GPT-4 Turbo dan semua model GPT-3.5 Turbo sejak gpt-3.5-turbo-1106. Mengatur parameter ini untuk { "type": "json_object" } mengaktifkan mode JSON, yang menjamin pesan yang dihasilkan model adalah JSON yang valid. Yang penting, saat menggunakan mode JSON, Anda juga harus menginstruksikan model untuk menghasilkan JSON sendiri menggunakan sistem atau pesan pengguna. Tanpa instruksi ini, model dapat menghasilkan aliran spasi kosong yang tidak berujung sampai pembuatan mencapai batas token, yang mengakibatkan permintaan yang berjalan lama dan tampaknya "macet". Selain itu, konten pesan dapat dipotong sebagian jika Anda menggunakan finish_reason="length", yang menunjukkan pembuatan terlampaui max_tokens atau percakapan melebihi panjang konteks maksimum. |
tool_resources |
object | Sekumpulan sumber daya yang digunakan oleh alat asisten. Sumber daya khusus untuk jenis alat. Misalnya, alat ini code_interpreter memerlukan daftar ID file, sementara alat ini file_search memerlukan daftar ID penyimpanan vektor. |