Referensi REST API Azure OpenAI Service

  • Artikel

Artikel ini menyediakan detail tentang titik akhir REST API inferensi untuk Azure OpenAI.

Autentikasi

Azure OpenAI menyediakan dua metode untuk autentikasi. Anda dapat menggunakan Kunci API atau ID Microsoft Entra.

  • Autentikasi Kunci API: Untuk jenis autentikasi ini, semua permintaan API harus menyertakan Kunci API di api-key header HTTP. Mulai Cepat menyediakan panduan tentang cara melakukan panggilan dengan jenis autentikasi ini.

  • Autentikasi ID Microsoft Entra: Anda dapat mengautentikasi panggilan API menggunakan token Microsoft Entra. Token autentikasi disertakan dalam permintaan sebagai header Authorization. Nilai token yang diberikan harus didahului dengan Bearer, contohnya Bearer YOUR_AUTH_TOKEN. Anda dapat membaca panduan cara mengautentikasi dengan MICROSOFT Entra ID.

Penerapan versi REST API

API layanan diterapkan versinya menggunakan parameter kueri api-version. Semua versi mengikuti struktur tanggal YYYY-MM-DD. Contohnya:

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01

Penyelesaian

Dengan operasi Penyelesaian, model menghasilkan satu atau beberapa penyelesaian yang diprediksi berdasarkan perintah yang disediakan. Layanan ini juga dapat mengembalikan kemungkinan token alternatif pada setiap posisi.

Membuat sebuah penyelesaian

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/completions?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran yang Anda pilih saat menyebarkan model.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
prompt string atau array Opsional <\|endoftext\|> Perintah atau permintaan untuk menghasilkan penyelesaian, dikodekan sebagai string, atau array string. <\|endoftext\|> adalah pemisah dokumen yang dilihat model selama pelatihan, jadi jika perintah tidak ditentukan, model menghasilkan seolah-olah dari awal dokumen baru.
max_tokens Integer Opsional 16 Jumlah maksimum token yang akan dihasilkan dalam penyelesaian. Jumlah token perintah Anda ditambah max_tokens tidak dapat melebihi panjang konteks model. Sebagian besar model memiliki panjang konteks 2048 token (kecuali untuk model terbaru, yang mendukung 4096).
temperature number Opsional 1 Suhu pengambilan sampel apa yang akan digunakan, antara 0 dan 2. Nilai yang lebih tinggi berarti model mengambil lebih banyak risiko. Cobalah 0,9 untuk aplikasi yang lebih kreatif dan 0 (argmax sampling) untuk aplikasi dengan jawaban yang jelas. Kami umumnya merekomendasikan untuk mengubah ini atau top_p tetapi tidak keduanya.
top_p number Opsional 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.
logit_bias peta Opsional nihil Ubah kemungkinan token tertentu muncul dalam penyelesaian. Menerima objek json yang memetakan token (ditentukan oleh ID token mereka dalam tokenizer GPT) ke nilai bias terkait dari -100 hingga 100. Anda dapat menggunakan alat pembuat token ini (yang berfungsi untuk GPT-2 dan GPT-3) untuk mengonversi teks ke ID token. Secara matematis, bias ditambahkan ke logit yang dihasilkan oleh model sebelum pengambilan sampel. Efek yang tepat bervariasi per model, tetapi nilai antara -1 dan 1 harus mengurangi atau meningkatkan kemungkinan pemilihan; nilai seperti -100 atau 100 harus menghasilkan larangan atau pilihan eksklusif dari token yang relevan. Sebagai contoh, Anda dapat meneruskan {"50256": -100} untuk mencegah token <|endoftext|> dihasilkan.
user string Opsional Pengidentifikasi unik yang mewakili pengguna akhir Anda, yang dapat membantu memantau dan mendeteksi penyalahgunaan
n Integer Opsional 1 Berapa banyak penyelesaian yang dihasilkan untuk setiap perintah. Catatan: Karena parameter ini menghasilkan banyak penyelesaian, parameter ini dapat dengan cepat menggunakan kuota token Anda. Gunakan dengan hati-hati dan pastikan Anda memiliki pengaturan yang wajar untuk max_tokens dan berhenti.
stream Boolean Opsional Salah Apakah akan kembali melakukan streaming pada kemajuan parsial. Jika diatur, token dikirim sebagai peristiwa yang dikirim server khusus data saat tersedia, dengan aliran dihentikan oleh data: pesan [DONE].
logprobs Integer Opsional nihil Sertakan peluang log pada token logprob yang paling mungkin, serta token yang dipilih. Contohnya, jika logprob adalah 10, API akan mengembalikan daftar 10 token yang paling mungkin. API akan selalu mengembalikan logprob token sampel, sehingga mungkin ada hingga elemen logprobs+1 dalam respons. Parameter ini tidak dapat digunakan dengan gpt-35-turbo.
suffix string Opsional nihil Akhiran yang muncul setelah penyelesaian teks yang disisipkan.
echo Boolean Opsional Salah Gema kembali perintah selain penyelesaian. Parameter ini tidak dapat digunakan dengan gpt-35-turbo.
stop string atau array Opsional nihil Hingga empat urutan di mana API akan berhenti menghasilkan token lebih lanjut. Teks yang dikembalikan tidak akan berisi urutan berhenti. Untuk GPT-4 Turbo dengan Visi, hingga dua urutan didukung.
presence_penalty number Opsional 0 Angka antara -2,0 dan 2,0. Nilai positif mengkhususkan token baru berdasarkan apakah token tersebut muncul dalam teks sejauh ini, meningkatkan kemungkinan model untuk berbicara tentang topik baru.
frequency_penalty number Opsional 0 Angka antara -2,0 dan 2,0. Nilai positif mengkhususkan token baru berdasarkan frekuensi yang ada dalam teks sejauh ini, mengurangi kemungkinan model untuk mengulangi verbatim baris yang sama.
best_of Integer Opsional 1 Menghasilkan penyelesaian best_of sisi server dan mengembalikan "best" (yang memiliki peluang log terendah per token). Hasil tidak dapat dialirkan. Saat digunakan dengan n, best_of mengontrol jumlah penyelesaian kandidat dan n menentukan berapa banyak yang akan dikembalikan – best_of harus lebih besar dari n. Catatan: Karena parameter ini menghasilkan banyak penyelesaian, parameter ini dapat dengan cepat menggunakan kuota token Anda. Gunakan dengan hati-hati dan pastikan Anda memiliki pengaturan yang wajar untuk max_tokens dan berhenti. Parameter ini tidak dapat digunakan dengan gpt-35-turbo.

Contoh permintaan

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/completions?api-version=2024-02-01\
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{
  \"prompt\": \"Once upon a time\",
  \"max_tokens\": 5
}"

Contoh tanggapan

{
    "id": "cmpl-4kGh7iXtjW4lc9eGhff6Hp8C7btdQ",
    "object": "text_completion",
    "created": 1646932609,
    "model": "ada",
    "choices": [
        {
            "text": ", a dark line crossed",
            "index": 0,
            "logprobs": null,
            "finish_reason": "length"
        }
    ]
}

Dalam contoh respons, finish_reason sama dengan stop. Jika finish_reason sama dengan berkonsultasi content_filter dengan panduan pemfilteran konten kami untuk memahami mengapa hal ini terjadi.

Penyematan

Dapatkan representasi vektor dari input tertentu yang dapat dengan mudah digunakan oleh model pembelajaran mesin dan algoritma lainnya.

Catatan

OpenAI saat ini memungkinkan sejumlah besar input array dengan text-embedding-ada-002. Azure OpenAI saat ini mendukung array input hingga 16 untuk text-embedding-ada-002 (Version 2). Keduanya memerlukan batas token input maksimum per permintaan API agar tetap di bawah 8191 untuk model ini.

Membuat penyematan

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/embeddings?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model Anda. Anda diharuskan untuk terlebih dahulu menyebarkan model sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
input string atau array Ya T/A Masukkan teks untuk mendapatkan penyematan, dikodekan sebagai array atau string. Jumlah token input bervariasi tergantung pada model apa yang Anda gunakan. Hanya text-embedding-ada-002 (Version 2) mendukung input array.
user string No Null Pengidentifikasi unik yang mewakili pengguna akhir Anda. Ini akan membantu Azure OpenAI memantau dan mendeteksi penyalahgunaan. Jangan meneruskan pengidentifikasi PII, sebagai gantinya gunakan nilai dengan pseudo-anonim seperti GUID
encoding_format string No float Format untuk mengembalikan penyematan. Dapat berupa float atau base64. Default ke float.

[Ditambahkan dalam 2024-03-01-preview].
dimensions Integer No Jumlah dimensi yang harus dimiliki penyematan output yang dihasilkan. Hanya didukung dalam text-embedding-3 model dan yang lebih baru.

[Ditambahkan dalam 2024-03-01-preview]

Contoh permintaan

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d "{\"input\": \"The food was delicious and the waiter...\"}"

Contoh tanggapan

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... (1024 floats total for ada)
        0.021276434883475304,
      ],
      "index": 0
    }
  ],
  "model": "text-similarity-babbage:001"
}

Penyelesaian obrolan

Buat penyelesaian untuk pesan obrolan dengan model GPT-35-Turbo dan GPT-4.

Membuat penyelesaian obrolan

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/chat/completions?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model Anda. Anda diharuskan untuk terlebih dahulu menyebarkan model sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Ini mengikuti format YYYY-MM-DD atau YYYY-MM-DD-preview.

Versi yang didukung

Badan permintaan

Isi permintaan terdiri dari serangkaian pesan. Model akan menghasilkan respons ke pesan terakhir, menggunakan pesan sebelumnya sebagai konteks.

Parameter Tipe Wajib diisi? Default Deskripsi
messages array Ya T/A Rangkaian pesan yang terkait dengan permintaan penyelesaian obrolan ini. Ini harus menyertakan pesan sebelumnya dalam percakapan. Setiap pesan memiliki role dan content.
role string Ya T/A Menunjukkan siapa yang memberikan pesan saat ini. Bisa ,systemuser,,assistanttool, atau function.
content string atau array Ya T/A Konten pesan. Ini harus berupa string, kecuali dalam skenario berkemampuan Visi. Jika ini adalah bagian user dari pesan, menggunakan GPT-4 Turbo dengan model Visi, dengan versi API terbaru, maka content harus berupa array struktur, di mana setiap item mewakili teks atau gambar:
  • text: teks input direpresentasikan sebagai struktur dengan properti berikut:
    • type = "teks"
    • text = teks input
  • images: gambar input direpresentasikan sebagai struktur dengan properti berikut:
    • type = "image_url"
    • image_url = struktur dengan properti berikut:
      • url = URL gambar
      • (opsional) detail = high, low, atau auto
contentPart object No T/A Bagian dari pesan multi-modal pengguna. Ini bisa berupa jenis teks atau jenis gambar. Jika teks, teks akan menjadi string teks. Jika gambar, itu akan menjadi contentPartImage objek.
contentPartImage object No T/A Mewakili gambar yang diunggah pengguna. Ini memiliki url properti, yang merupakan URL gambar atau data gambar dasar yang dikodekan 64. Ini juga memiliki detail properti yang dapat berupa auto, low, atau high.
enhancements object No T/A Mewakili fitur peningkatan Visi yang diminta untuk obrolan. grounding Memiliki properti dan ocr , masing-masing memiliki properti booleanenabled. Gunakan ini untuk meminta layanan OCR dan/atau layanan deteksi/grounding objek [Parameter pratinjau ini tidak tersedia di 2024-02-01 GA API].
dataSources object No T/A Mewakili data sumber daya tambahan. Data sumber daya Computer Vision diperlukan untuk peningkatan Visi. Ini memiliki type properti, yang seharusnya "AzureComputerVision" dan properti parameters , yang memiliki endpoint properti dan key . String ini harus diatur ke URL titik akhir dan kunci akses sumber daya Computer Vision Anda.

Contoh permintaan

Obrolan teks saja

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-02-01 \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},{"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."},{"role": "user", "content": "Do other Azure AI services support this too?"}]}'

Mengobrol dengan visi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{ "type": "image_url", "image_url": { "url": "https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png", "detail": "high" } }]}]}'

Peningkatan obrolan dengan visi

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{"enhancements":{"ocr":{"enabled":true},"grounding":{"enabled":true}},"dataSources":[{"type":"AzureComputerVision","parameters":{"endpoint":" <Computer Vision Resource Endpoint> ","key":"<Computer Vision Resource Key>"}}],"messages":[{"role":"system","content":"You are a helpful assistant."},{"role":"user","content":[{"type":"text","text":"Describe this picture:"},{"type":"image_url","image_url":"https://learn.microsoft.com/azure/ai-services/computer-vision/media/quickstarts/presentation.png"}]}]}'

Contoh tanggapan

{
    "id": "chatcmpl-6v7mkQj980V1yBec6ETrKPRqFjNw9",
    "object": "chat.completion",
    "created": 1679072642,
    "model": "gpt-35-turbo",
    "usage":
    {
        "prompt_tokens": 58,
        "completion_tokens": 68,
        "total_tokens": 126
    },
    "choices":
    [
        {
            "message":
            {
                "role": "assistant",
                "content": "Yes, other Azure AI services also support customer managed keys.
                    Azure AI services offer multiple options for customers to manage keys, such as
                    using Azure Key Vault, customer-managed keys in Azure Key Vault or
                    customer-managed keys through Azure Storage service. This helps customers ensure
                    that their data is secure and access to their services is controlled."
            },
            "finish_reason": "stop",
            "index": 0
        }
    ]
}

Pemformatan output yang disesuaikan untuk kemudahan membaca, output aktual adalah satu blok teks tanpa hentian baris.

Dalam contoh respons, finish_reason sama dengan stop. Jika finish_reason sama dengan berkonsultasi content_filter dengan panduan pemfilteran konten kami untuk memahami mengapa hal ini terjadi.

Penting

Parameter functions dan function_call telah ditolak dengan rilis 2023-12-01-preview versi API. Penggantian untuk functions adalah tools parameter . Penggantian untuk function_call adalah tool_choice parameter . Panggilan fungsi paralel yang diperkenalkan sebagai bagian 2023-12-01-preview dari hanya didukung dengan gpt-35-turbo (1106) dan gpt-4 (pratinjau 1106) juga dikenal sebagai Pratinjau Turbo GPT-4.

Parameter Tipe Wajib diisi? Default Deskripsi
messages array Diperlukan Kumpulan pesan konteks yang terkait dengan permintaan penyelesaian obrolan ini. Penggunaan umum dimulai dengan pesan obrolan untuk peran Sistem yang memberikan instruksi untuk perilaku asisten, diikuti dengan pesan alternatif antara peran Pengguna dan Asisten.
temperature number Opsional 1 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. Kami umumnya merekomendasikan untuk mengubah ini atau top_p tetapi tidak keduanya.
n Integer Opsional 1 Berapa banyak pilihan penyelesaian obrolan yang akan dihasilkan untuk setiap pesan input.
stream Boolean Opsional salah Jika diatur, delta pesan parsial akan dikirim, seperti di ChatGPT. Token akan dikirim sebagai peristiwa yang dikirim server khusus data saat tersedia, dengan aliran dihentikan oleh pesan data: [DONE] ."
stop string atau array Opsional nihil Hingga 4 urutan di mana API akan berhenti menghasilkan token lebih lanjut.
max_tokens Integer Opsional Inf Jumlah maksimum token yang diizinkan untuk jawaban yang dihasilkan. Secara default, jumlah token yang dapat dikembalikan model adalah (4096 - token prompt).
presence_penalty number Opsional 0 Angka antara -2,0 dan 2,0. Nilai positif mengkhususkan token baru berdasarkan apakah token tersebut muncul dalam teks sejauh ini, meningkatkan kemungkinan model untuk berbicara tentang topik baru.
frequency_penalty number Opsional 0 Angka antara -2,0 dan 2,0. Nilai positif mengkhususkan token baru berdasarkan frekuensi yang ada dalam teks sejauh ini, mengurangi kemungkinan model untuk mengulangi verbatim baris yang sama.
logit_bias object Opsional nihil Ubah kemungkinan token tertentu muncul dalam penyelesaian. Menerima objek json yang memetakan token (ditentukan oleh ID token mereka di tokenizer) ke nilai bias terkait dari -100 hingga 100. Secara matematis, bias ditambahkan ke logit yang dihasilkan oleh model sebelum pengambilan sampel. Efek yang tepat bervariasi per model, tetapi nilai antara -1 dan 1 harus mengurangi atau meningkatkan kemungkinan pemilihan; nilai seperti -100 atau 100 harus menghasilkan larangan atau pilihan eksklusif dari token yang relevan.
user string Opsional Pengidentifikasi unik yang mewakili pengguna akhir Anda, yang dapat membantu Azure OpenAI memantau dan mendeteksi penyalahgunaan.
function_call Opsional [Deprecated in 2023-12-01-preview replacement parameter is tools_choice]Mengontrol bagaimana model merespons panggilan fungsi. "none" berarti model tidak memanggil fungsi, dan merespons pengguna akhir. auto berarti model dapat memilih antara pengguna akhir atau memanggil fungsi. Menentukan fungsi tertentu melalui {"name": "my_function"} memaksa model untuk memanggil fungsi tersebut. "none" adalah default ketika tidak ada fungsi yang ada. auto adalah default jika fungsi ada. Parameter ini memerlukan versi API 2023-07-01-preview
functions FunctionDefinition[] Opsional [Deprecated in 2023-12-01-preview replacement paremeter is tools] Daftar fungsi yang digunakan model untuk menghasilkan input JSON. Parameter ini memerlukan versi API 2023-07-01-preview
tools string (Jenis alat. Hanya function didukung.) Opsional Daftar alat yang dapat dipanggil model. Saat ini, hanya fungsi yang didukung sebagai alat. Gunakan ini untuk menyediakan daftar fungsi yang dapat dihasilkan oleh model input JSON. Parameter ini memerlukan versi API 2023-12-01-preview
tool_choice string atau objek Opsional tidak ada yang default ketika tidak ada fungsi yang ada. auto adalah default jika fungsi ada. Mengontrol fungsi (jika ada) mana yang dipanggil oleh model. Tidak ada berarti model tidak akan memanggil fungsi dan sebaliknya menghasilkan pesan. auto berarti model dapat memilih antara menghasilkan pesan atau memanggil fungsi. Menentukan fungsi tertentu melalui {"type: "function", "function": {"name": "my_function"}} memaksa model untuk memanggil fungsi tersebut. Parameter ini memerlukan versi API atau yang lebih 2023-12-01-preview baru.

ChatMessage

Satu pesan yang diatribusikan peran dalam interaksi penyelesaian obrolan.

Nama Tipe Deskripsi
konten string Teks yang terkait dengan payload pesan ini.
function_call FunctionCall Nama dan argumen fungsi yang harus dipanggil, seperti yang dihasilkan oleh model.
nama string Penulis name pesan ini. name diperlukan jika peran adalah function, dan itu harus menjadi nama fungsi yang responsnya ada di content. Dapat berisi a-z, A-Z, 0-9, dan garis bawah, dengan panjang maksimum 64 karakter.
role ChatRole Peran yang terkait dengan payload pesan ini

ChatRole

Deskripsi tujuan yang dimaksudkan dari pesan dalam interaksi penyelesaian obrolan.

Nama Tipe Deskripsi
assistant string Peran yang memberikan respons terhadap input yang diinstruksikan sistem dan diminta pengguna.
fungsi string Peran yang menyediakan hasil fungsi untuk penyelesaian obrolan.
sistem string Peran yang menginstruksikan atau mengatur perilaku asisten.
pengguna string Peran yang menyediakan input untuk penyelesaian obrolan.

Fungsi

Ini digunakan dengan tools parameter yang ditambahkan dalam versi 2023-12-01-previewAPI .

Nama Tipe Deskripsi
description string Deskripsi tentang apa yang dilakukan fungsi, digunakan oleh model untuk memilih kapan dan cara memanggil fungsi
nama string Nama fungsi yang akan dipanggil. Harus a-z, A-Z, 0-9, atau berisi garis bawah dan tanda hubung, dengan panjang maksimum 64
parameter object Parameter yang diterima fungsi, dijelaskan sebagai objek Skema JSON. Lihat referensi Skema JSON untuk dokumentasi tentang format."

FunctionCall-Tidak digunakan lagi

Nama dan argumen fungsi yang harus dipanggil, seperti yang dihasilkan oleh model. Ini memerlukan versi API 2023-07-01-preview

Nama Tipe Deskripsi
arguments string Argumen untuk memanggil fungsi dengan, seperti yang dihasilkan oleh model dalam format JSON. Model tidak selalu menghasilkan JSON yang valid, dan mungkin membuat parameter yang tidak ditentukan oleh skema fungsi Anda. Validasi argumen dalam kode Anda sebelum memanggil fungsi Anda.
nama string Nama fungsi yang akan dipanggil.

FunctionDefinition-Deprecated

Definisi fungsi yang ditentukan pemanggil yang dapat dipanggil penyelesaian obrolan sebagai respons terhadap input pengguna yang cocok. Ini memerlukan versi API 2023-07-01-preview

Nama Tipe Deskripsi
description string Deskripsi tentang apa yang dilakukan fungsi. Model menggunakan deskripsi ini saat memilih fungsi dan menginterpretasikan parameternya.
nama string Nama fungsi yang akan dipanggil.
parameter Parameter yang diterima fungsi, dijelaskan sebagai objek Skema JSON.

Ekstensi penyelesaian

Ekstensi untuk penyelesaian obrolan, misalnya Azure OpenAI On Your Data.

Penting

Informasi berikut adalah untuk versi 2023-12-01-preview API. Ini bukan versi API saat ini. Untuk menemukan dokumentasi referensi terbaru, lihat Referensi Azure OpenAI On Your Data.

Menggunakan ekstensi penyelesaian obrolan

POST {your-resource-name}/openai/deployments/{deployment-id}/extensions/chat/completions?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model Anda. Anda diharuskan untuk terlebih dahulu menyebarkan model sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Contoh permintaan

Anda dapat membuat permintaan menggunakan Azure AI Search, Azure Cosmos DB untuk MongoDB vCore, Pinecone, dan Elasticsearch. Untuk informasi selengkapnya, lihat Azure OpenAI On Your Data.

curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "max_tokens": 1000,
    "top_p": 1.0,
    "dataSources": [
        {
            "type": "AzureCognitiveSearch",
            "parameters": {
                "endpoint": "YOUR_AZURE_COGNITIVE_SEARCH_ENDPOINT",
                "key": "YOUR_AZURE_COGNITIVE_SEARCH_KEY",
                "indexName": "YOUR_AZURE_COGNITIVE_SEARCH_INDEX_NAME"
            }
        }
    ],
    "messages": [
        {
            "role": "user",
            "content": "What are the differences between Azure Machine Learning and Azure AI services?"
        }
    ]
}
'
Azure Cosmos DB untuk MongoDB vCore
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-06-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
    "temperature": 0,
    "top_p": 1.0,
    "max_tokens": 800,
    "stream": false,
    "messages": [
        {
            "role": "user",
            "content": "What is the company insurance plan?"
        }
    ],
    "dataSources": [
        {
            "type": "AzureCosmosDB",
            "parameters": {
                "authentication": {
                    "type": "ConnectionString",
                    "connectionString": "mongodb+srv://onyourdatatest:{password}$@{cluster-name}.mongocluster.cosmos.azure.com/?tls=true&authMechanism=SCRAM-SHA-256&retrywrites=false&maxIdleTimeMS=120000"
                },
                "databaseName": "vectordb",
                "containerName": "azuredocs",
                "indexName": "azuredocindex",
                "embeddingDependency": {
                    "type": "DeploymentName",
                    "deploymentName": "{embedding deployment name}"
                },
                "fieldsMapping": {
                    "vectorFields": [
                        "contentvector"
                    ]
                }
            }
        }
    ]
}
'
Elasticsearch
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "Elasticsearch",
      "parameters": {
        "endpoint": "{search endpoint}",
        "indexName": "{index name}",
        "authentication": {
          "type": "KeyAndKeyId",
          "key": "{key}",
          "keyId": "{key id}"
        }
      }
    }
  ]
}
Pembelajaran Mesin Azure
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "AzureMLIndex",
      "parameters": {
        "projectResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.MachineLearningServices/workspaces/{workspace-id}",
        "name": "my-project",
        "version": "5"
      }
    }
  ]
}
'
Pinecone
curl -i -X POST YOUR_RESOURCE_NAME/openai/deployments/YOUR_DEPLOYMENT_NAME/extensions/chat/completions?api-version=2023-12-01-preview \
-H "Content-Type: application/json" \
-H "api-key: YOUR_API_KEY" \
-d \
'
{
  "messages": [
    {
      "role": "system",
      "content": "you are a helpful assistant that talks like a pirate"
    },
    {
      "role": "user",
      "content": "can you tell me how to care for a parrot?"
    }
  ],
  "dataSources": [
    {
      "type": "Pinecone",
      "parameters": {
        "authentication": {
          "type": "APIKey",
          "apiKey": "{api key}"
        },
        "environment": "{environment name}",
        "indexName": "{index name}",
        "embeddingDependency": {
          "type": "DeploymentName",
          "deploymentName": "{embedding deployment name}"
        },
        "fieldsMapping": {
          "titleField": "title",
          "urlField": "url",
          "filepathField": "filepath",
          "contentFields": [
            "content"
          ],
          "contentFieldsSeparator": "\n"
        }
      }
    }
  ]
}
'

Contoh tanggapan

{
    "id": "12345678-1a2b-3c4e5f-a123-12345678abcd",
    "model": "",
    "created": 1684304924,
    "object": "chat.completion",
    "choices": [
        {
            "index": 0,
            "messages": [
                {
                    "role": "tool",
                    "content": "{\"citations\": [{\"content\": \"\\nAzure AI services are cloud-based artificial intelligence (AI) services...\", \"id\": null, \"title\": \"What is Azure AI services\", \"filepath\": null, \"url\": null, \"metadata\": {\"chunking\": \"orignal document size=250. Scores=0.4314117431640625 and 1.72564697265625.Org Highlight count=4.\"}, \"chunk_id\": \"0\"}], \"intent\": \"[\\\"Learn about Azure AI services.\\\"]\"}",
                    "end_turn": false
                },
                {
                    "role": "assistant",
                    "content": " \nAzure AI services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. [doc1]. Azure Machine Learning is a cloud service for accelerating and managing the machine learning project lifecycle. [doc1].",
                    "end_turn": true
                }
            ]
        }
    ]
}
Parameter Jenis Wajib diisi? Default Deskripsi
messages array Diperlukan nihil Pesan untuk menghasilkan penyelesaian obrolan, dalam format obrolan.
dataSources array Diperlukan Sumber data yang akan digunakan untuk fitur Azure OpenAI On Your Data.
temperature number Opsional 0 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. Kami umumnya merekomendasikan untuk mengubah ini atau top_p tetapi tidak keduanya.
top_p number Opsional 1 Alternatif untuk pengambilan sampel dengan suhu, yang disebut pengambilan sampel nukleus, di mana model mempertimbangkan hasil token dengan top_p massa probabilitas. 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.
stream Boolean Opsional salah Jika diatur, delta pesan parsial dikirim, seperti di ChatGPT. Token dikirim sebagai peristiwa yang dikirim server khusus data saat tersedia, dengan aliran dihentikan oleh pesan "messages": [{"delta": {"content": "[DONE]"}, "index": 2, "end_turn": true}]
stop string atau array Opsional nihil Hingga dua urutan di mana API akan berhenti menghasilkan token lebih lanjut.
max_tokens Integer Opsional 1000 Jumlah maksimum token yang diizinkan untuk jawaban yang dihasilkan. Secara default, jumlah token yang dapat dikembalikan model adalah 4096 - prompt_tokens.

Parameter berikut dapat digunakan di dalam parameters bidang di dalam dataSources.

Parameter Jenis Wajib diisi? Default Deskripsi
type string Wajib nihil Sumber data yang akan digunakan untuk fitur Azure OpenAI On Your Data. Untuk Azure AI Cari nilainya adalah AzureCognitiveSearch. Untuk Azure Cosmos DB untuk MongoDB vCore, nilainya adalah AzureCosmosDB. Untuk Elasticsearch, nilainya adalah Elasticsearch. Untuk Azure Pembelajaran Mesin, nilainya adalah AzureMLIndex. Untuk Pinecone, nilainya adalah Pinecone.
indexName string Wajib nihil Indeks pencarian yang akan digunakan.
inScope Boolean Opsional benar Jika ditetapkan, nilai ini membatasi respons khusus untuk konten data dasar.
topNDocuments number Opsional 5 Menentukan jumlah dokumen dengan skor teratas dari indeks data Anda yang digunakan untuk menghasilkan respons. Anda mungkin ingin meningkatkan nilai saat Anda memiliki dokumen pendek atau ingin memberikan lebih banyak konteks. Ini adalah parameter dokumen yang diambil di studio Azure OpenAI.
semanticConfiguration string Opsional nihil Konfigurasi pencarian semantik. Hanya diperlukan ketika queryType diatur ke semantic atau vectorSemanticHybrid.
roleInformation string Opsional nihil Memberikan instruksi model tentang bagaimana perilakunya dan konteks yang harus dirujuknya saat menghasilkan respons. Sesuai dengan "Pesan Sistem" di Azure OpenAI Studio. Lihat Menggunakan data Anda untuk informasi selengkapnya. Ada batas token 100, yang diperhitungkan dalam batas token keseluruhan.
filter string Opsional nihil Pola filter yang digunakan untuk membatasi akses ke dokumen sensitif
embeddingEndpoint string Opsional nihil URL titik akhir untuk penyebaran model penyematan Ada, umumnya dari format https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/embeddings?api-version=2023-05-15. Gunakan dengan embeddingKey parameter untuk pencarian vektor di luar jaringan privat dan titik akhir privat.
embeddingKey string Opsional nihil Kunci API untuk penyebaran model penyematan Ada. Gunakan dengan embeddingEndpoint untuk pencarian vektor di luar jaringan privat dan titik akhir privat.
embeddingDeploymentName string Opsional nihil Nama penyebaran model penyematan Ada dalam sumber daya Azure OpenAI yang sama. Digunakan alih-alih embeddingEndpoint dan embeddingKey untuk pencarian vektor. Hanya boleh digunakan ketika embeddingEndpoint parameter dan embeddingKey didefinisikan. Ketika parameter ini disediakan, Azure OpenAI On Your Data menggunakan panggilan internal untuk mengevaluasi model ada embedding, daripada memanggil titik akhir Azure OpenAI. Ini memungkinkan Anda menggunakan pencarian vektor di jaringan privat dan titik akhir privat. Penagihan tetap sama apakah parameter ini ditentukan atau tidak. Tersedia di wilayah tempat model penyematan tersedia mulai dari versi 2023-06-01-preview API dan yang lebih baru.
strictness number Opsional 3 Mengatur ambang batas untuk mengategorikan dokumen yang relevan dengan kueri Anda. Menaikkan nilai berarti ambang batas yang lebih tinggi untuk relevansi dan memfilter dokumen yang lebih kurang relevan untuk respons. Mengatur nilai ini terlalu tinggi dapat menyebabkan model gagal menghasilkan respons karena dokumen terbatas yang tersedia.

Parameter Pencarian Azure AI

Parameter berikut digunakan untuk Azure AI Search.

Parameter Jenis Wajib diisi? Default Deskripsi
endpoint string Wajib nihil Hanya Pencarian Azure AI. Titik akhir sumber data.
key string Wajib nihil Hanya Pencarian Azure AI. Salah satu kunci admin Azure AI Search untuk layanan Anda.
queryType string Opsional sederhana Menunjukkan opsi kueri mana yang digunakan untuk Pencarian Azure AI. Jenis yang tersedia: simple, , semanticvector, vectorSimpleHybrid, vectorSemanticHybrid.
fieldsMapping dictionary Opsional untuk Azure AI Search. nihil menentukan bidang mana yang ingin Anda petakan saat menambahkan sumber data Anda.

Parameter berikut digunakan di dalam authentication bidang , yang memungkinkan Anda menggunakan Azure OpenAI tanpa akses jaringan publik.

Parameter Jenis Wajib diisi? Default Deskripsi
type string Wajib nihil Jenis Autentikasi.
managedIdentityResourceId string Wajib nihil ID sumber daya identitas terkelola yang ditetapkan pengguna untuk digunakan untuk autentikasi. 
"authentication": {
  "type": "UserAssignedManagedIdentity",
  "managedIdentityResourceId": "/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{resource-name}"
},

Parameter berikut digunakan di dalam fieldsMapping bidang .

Parameter Jenis Wajib diisi? Default Deskripsi
titleField string Opsional nihil Bidang dalam indeks Anda yang berisi judul asli setiap dokumen.
urlField string Opsional nihil Bidang dalam indeks Anda yang berisi URL asli dari setiap dokumen.
filepathField string Opsional nihil Bidang dalam indeks Anda yang berisi nama file asli dari setiap dokumen.
contentFields dictionary Opsional nihil Bidang dalam indeks Anda yang berisi konten teks utama dari setiap dokumen.
contentFieldsSeparator string Opsional nihil Pemisah untuk bidang konten. Gunakan \n secara default. 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n"
}

Parameter berikut digunakan di dalam parameter opsional embeddingDependency , yang berisi detail sumber vektorisasi yang didasarkan pada nama penyebaran model penyematan internal di sumber daya Azure OpenAI yang sama.

Parameter Jenis Wajib diisi? Default Deskripsi
deploymentName string Opsional nihil Jenis sumber vektorisasi yang akan digunakan.
type string Opsional nihil Nama penyebaran model penyematan, terletak dalam sumber daya Azure OpenAI yang sama. Ini memungkinkan Anda menggunakan pencarian vektor tanpa kunci API Azure OpenAI dan tanpa akses jaringan publik Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parameter Azure Cosmos DB for MongoDB vCore

Parameter berikut digunakan untuk Azure Cosmos DB untuk MongoDB vCore.

Parameter Jenis Wajib diisi? Default Deskripsi
type (ditemukan di dalam authentication) string Wajib nihil Azure Cosmos DB untuk MongoDB vCore saja. Autentikasi yang akan digunakan Untuk. Azure Cosmos Mongo vCore, nilainya adalah ConnectionString
connectionString string Wajib nihil Azure Cosmos DB untuk MongoDB vCore saja. string koneksi yang akan digunakan untuk mengautentikasi Akun Azure Cosmos Mongo vCore.
databaseName string Wajib nihil Azure Cosmos DB untuk MongoDB vCore saja. Nama database Azure Cosmos Mongo vCore.
containerName string Wajib nihil Azure Cosmos DB untuk MongoDB vCore saja. Nama kontainer Azure Cosmos Mongo vCore dalam database.
type (ditemukan di dalamembeddingDependencyType) string Wajib nihil Menunjukkan dependensi model penyematan.
deploymentName (ditemukan di dalamembeddingDependencyType) string Wajib nihil Nama penyebaran model penyematan.
fieldsMapping dictionary Diperlukan untuk Azure Cosmos DB untuk MongoDB vCore. nihil Pemetaan kolom data indeks. Saat Anda menggunakan Azure Cosmos DB untuk MongoDB vCore, nilai vectorFields diperlukan, yang menunjukkan bidang yang menyimpan vektor.

Parameter berikut digunakan di dalam parameter opsional embeddingDependency , yang berisi detail sumber vektorisasi yang didasarkan pada nama penyebaran model penyematan internal di sumber daya Azure OpenAI yang sama.

Parameter Jenis Wajib diisi? Default Deskripsi
deploymentName string Opsional nihil Jenis sumber vektorisasi yang akan digunakan.
type string Opsional nihil Nama penyebaran model penyematan, terletak dalam sumber daya Azure OpenAI yang sama. Ini memungkinkan Anda menggunakan pencarian vektor tanpa kunci API Azure OpenAI dan tanpa akses jaringan publik Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parameter Elasticsearch

Parameter berikut digunakan untuk Elasticsearch.

Parameter Jenis Wajib diisi? Default Deskripsi
endpoint string Wajib nihil Titik akhir untuk menyambungkan ke Elasticsearch.
indexName string Wajib nihil Nama indeks Elasticsearch.
type (ditemukan di dalam authentication) string Wajib nihil Autentikasi yang akan digunakan. Untuk Elasticsearch, nilainya adalah KeyAndKeyId.
key (ditemukan di dalam authentication) string Wajib nihil Kunci yang digunakan untuk terhubung ke Elasticsearch.
keyId (ditemukan di dalam authentication) string Wajib nihil ID kunci yang akan digunakan. Untuk Elasticsearch.

Parameter berikut digunakan di dalam fieldsMapping bidang .

Parameter Jenis Wajib diisi? Default Deskripsi
titleField string Opsional nihil Bidang dalam indeks Anda yang berisi judul asli setiap dokumen.
urlField string Opsional nihil Bidang dalam indeks Anda yang berisi URL asli dari setiap dokumen.
filepathField string Opsional nihil Bidang dalam indeks Anda yang berisi nama file asli dari setiap dokumen.
contentFields dictionary Opsional nihil Bidang dalam indeks Anda yang berisi konten teks utama dari setiap dokumen.
contentFieldsSeparator string Opsional nihil Pemisah untuk bidang konten. Gunakan \n secara default.
vectorFields dictionary Opsional nihil Nama bidang yang mewakili data vektor 
"fieldsMapping": {
  "titleField": "myTitleField",
  "urlField": "myUrlField",
  "filepathField": "myFilePathField",
  "contentFields": [
    "myContentField"
  ],
  "contentFieldsSeparator": "\n",
  "vectorFields": [
    "myVectorField"
  ]
}

Parameter berikut digunakan di dalam parameter opsional embeddingDependency , yang berisi detail sumber vektorisasi yang didasarkan pada nama penyebaran model penyematan internal di sumber daya Azure OpenAI yang sama.

Parameter Jenis Wajib diisi? Default Deskripsi
deploymentName string Opsional nihil Jenis sumber vektorisasi yang akan digunakan.
type string Opsional nihil Nama penyebaran model penyematan, terletak dalam sumber daya Azure OpenAI yang sama. Ini memungkinkan Anda menggunakan pencarian vektor tanpa kunci API Azure OpenAI dan tanpa akses jaringan publik Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parameter Azure Pembelajaran Mesin

Parameter berikut digunakan untuk Azure Pembelajaran Mesin.

Parameter Jenis Wajib diisi? Default Deskripsi
projectResourceId string Wajib nihil ID sumber daya proyek.
name string Wajib nihil Nama nama proyek Azure Pembelajaran Mesin.
version (ditemukan di dalam authentication) string Wajib nihil Versi indeks vektor Azure Pembelajaran Mesin.

Parameter berikut digunakan di dalam parameter opsional embeddingDependency , yang berisi detail sumber vektorisasi yang didasarkan pada nama penyebaran model penyematan internal di sumber daya Azure OpenAI yang sama.

Parameter Jenis Wajib diisi? Default Deskripsi
deploymentName string Opsional nihil Jenis sumber vektorisasi yang akan digunakan.
type string Opsional nihil Nama penyebaran model penyematan, terletak dalam sumber daya Azure OpenAI yang sama. Ini memungkinkan Anda menggunakan pencarian vektor tanpa kunci API Azure OpenAI dan tanpa akses jaringan publik Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Parameter pinecone

Parameter berikut digunakan untuk Pinecone.

Parameter Jenis Wajib diisi? Default Deskripsi
type (ditemukan di dalam authentication) string Wajib nihil Autentikasi yang akan digunakan. Untuk Pinecone, nilainya adalah APIKey.
apiKey (ditemukan di dalam authentication) string Wajib nihil Kunci API untuk Pinecone.
environment string Wajib nihil Nama lingkungan Pinecone.
indexName string Wajib nihil Nama indeks Pinecone.
embeddingDependency string Wajib nihil Dependensi penyematan untuk pencarian vektor.
type (ditemukan di dalam embeddingDependency) string Wajib nihil Jenis dependensi. Untuk Pinecone, nilainya adalah DeploymentName.
deploymentName (ditemukan di dalam embeddingDependency) string Wajib nihil Nama penyebaran.
titleField (ditemukan di dalam fieldsMapping) string Wajib nihil Nama bidang indeks yang akan digunakan sebagai judul.
urlField (ditemukan di dalam fieldsMapping) string Wajib nihil Nama bidang indeks yang akan digunakan sebagai URL.
filepathField (ditemukan di dalam fieldsMapping) string Wajib nihil Nama bidang indeks yang akan digunakan sebagai jalur file.
contentFields (ditemukan di dalam fieldsMapping) string Wajib nihil Nama bidang indeks yang harus diperlakukan sebagai konten.
vectorFields dictionary Opsional nihil Nama bidang yang mewakili data vektor
contentFieldsSeparator (ditemukan di dalam fieldsMapping) string Wajib nihil Pemisah untuk bidang konten Anda. Gunakan \n secara default.

Parameter berikut digunakan di dalam parameter opsional embeddingDependency , yang berisi detail sumber vektorisasi yang didasarkan pada nama penyebaran model penyematan internal di sumber daya Azure OpenAI yang sama.

Parameter Jenis Wajib diisi? Default Deskripsi
deploymentName string Opsional nihil Jenis sumber vektorisasi yang akan digunakan.
type string Opsional nihil Nama penyebaran model penyematan, terletak dalam sumber daya Azure OpenAI yang sama. Ini memungkinkan Anda menggunakan pencarian vektor tanpa kunci API Azure OpenAI dan tanpa akses jaringan publik Azure OpenAI. 
"embeddingDependency": {
  "type": "DeploymentName",
  "deploymentName": "{embedding deployment name}"
},

Memulai pekerjaan penyerapan (pratinjau)

Tip

Yang JOB_NAME Anda pilih akan digunakan sebagai nama indeks. Ketahui batasan untuk nama indeks.

curl -i -X PUT https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/JOB_NAME?api-version=2023-10-01-preview \ 
-H "Content-Type: application/json" \ 
-H "api-key: YOUR_API_KEY" \ 
-H "searchServiceEndpoint: https://YOUR_AZURE_COGNITIVE_SEARCH_NAME.search.windows.net" \ 
-H "searchServiceAdminKey: YOUR_SEARCH_SERVICE_ADMIN_KEY" \ 
-H  "storageConnectionString: YOUR_STORAGE_CONNECTION_STRING" \ 
-H "storageContainer: YOUR_INPUT_CONTAINER" \ 
-d '{ "dataRefreshIntervalInMinutes": 10 }'

Contoh tanggapan

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "running", 
    "warnings": [], 
    "progress": { 
        "stageProgress": [ 
            { 
                "name": "Preprocessing", 
                "totalItems": 100, 
                "processedItems": 100 
            }, 
            { 
                "name": "Indexing", 
                "totalItems": 350, 
                "processedItems": 40 
            } 
        ] 
    } 
}

Parameter Header

Parameter Jenis Wajib diisi? Default Deskripsi
searchServiceEndpoint string Wajib nihil Titik akhir sumber daya pencarian tempat data akan diserap.
searchServiceAdminKey string Opsional nihil Jika disediakan, kunci digunakan untuk mengautentikasi dengan searchServiceEndpoint. Jika tidak disediakan, identitas sumber daya Azure OpenAI yang ditetapkan sistem akan digunakan. Dalam hal ini, identitas yang ditetapkan sistem harus memiliki penetapan peran "Kontributor Layanan Pencarian" pada sumber daya pencarian.
storageConnectionString string Wajib nihil string koneksi untuk akun penyimpanan tempat data input berada. Kunci akun harus disediakan di string koneksi. Ini akan terlihat seperti DefaultEndpointsProtocol=https;AccountName=<your storage account>;AccountKey=<your account key>
storageContainer string Wajib nihil Nama kontainer tempat data input berada.
embeddingEndpoint string Opsional nihil Tidak diperlukan jika Anda menggunakan pencarian semantik atau hanya kata kunci. Diperlukan jika Anda menggunakan vektor, hibrid, atau hibrid + pencarian semantik
embeddingKey string Opsional nihil Kunci titik akhir penyematan. Ini diperlukan jika titik akhir penyematan tidak kosong.
url string Opsional nihil Jika URL tidak null, url yang disediakan dirayapi ke dalam kontainer penyimpanan yang disediakan lalu diserap sesuai.

Parameter Isi

Parameter Jenis Wajib diisi? Default Deskripsi
dataRefreshIntervalInMinutes string Wajib 0 Interval refresh data dalam hitungan menit. Jika Anda ingin menjalankan satu pekerjaan penyerapan tanpa jadwal, atur parameter ini ke 0.
completionAction string Opsional cleanUpAssets Apa yang harus terjadi pada aset yang dibuat selama proses penyerapan setelah penyelesaian pekerjaan. Nilai yang valid adalah cleanUpAssets atau keepAllAssets. keepAllAssets meninggalkan semua aset perantara untuk pengguna yang tertarik untuk meninjau hasil menengah, yang dapat membantu untuk men-debug aset. cleanUpAssets menghapus aset setelah penyelesaian pekerjaan.
chunkSize int Opsional 1024 Angka ini mendefinisikan jumlah maksimum token di setiap gugus yang dihasilkan oleh alur penyerapan.

Mencantumkan pekerjaan penyerapan (pratinjau)

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

Contoh tanggapan

{ 
    "value": [ 
        { 
            "id": "test-1", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "succeeded", 
            "warnings": [] 
        }, 
        { 
            "id": "test-2", 
            "dataRefreshIntervalInMinutes": 10, 
            "completionAction": "cleanUpAssets", 
            "status": "failed", 
            "error": { 
                "code": "BadRequest", 
                "message": "Could not execute skill because the Web Api request failed." 
            }, 
            "warnings": [] 
        } 
    ] 
}

Mendapatkan status pekerjaan penyerapan (pratinjau)

curl -i -X GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/extensions/on-your-data/ingestion-jobs/YOUR_JOB_NAME?api-version=2023-10-01-preview \ 
-H "api-key: YOUR_API_KEY"

Contoh isi respons

{ 
    "id": "test-1", 
    "dataRefreshIntervalInMinutes": 10, 
    "completionAction": "cleanUpAssets", 
    "status": "succeeded", 
    "warnings": [] 
}

Pembuatan gambar

Meminta gambar yang dihasilkan (DALL-E 3)

Buat dan ambil batch gambar dari keterangan teks.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model DALL-E 3 Anda seperti MyDalle3. Anda diharuskan untuk terlebih dahulu menyebarkan model DALL-E 3 sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
prompt string Wajib Deskripsi teks gambar yang diinginkan. Panjang maksimum adalah 4000 karakter.
n Integer Opsional 1 Jumlah gambar yang akan dihasilkan. Hanya n=1 didukung untuk DALL-E 3.
size string Opsional 1024x1024 Ukuran gambar yang dihasilkan. Harus salah satu dari 1792x1024, , 1024x1024atau 1024x1792.
quality string Opsional standard Kualitas gambar yang dihasilkan. Harus hd atau standard.
response_format string Opsional url Format di mana gambar yang dihasilkan dikembalikan Harus ( url URL yang menunjuk ke gambar) atau b64_json (kode dasar 64-byte dalam format JSON).
style string Opsional vivid Gaya gambar yang dihasilkan. Harus natural atau vivid (untuk gambar hiper-realistis / dramatis).
user string Opsional Pengidentifikasi unik yang mewakili pengguna akhir Anda, yang dapat membantu memantau dan mendeteksi penyalahgunaan.

Contoh permintaan

curl -X POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/images/generations?api-version=2023-12-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "prompt": "An avocado chair",
    "size": "1024x1024",
    "n": 1,
    "quality": "hd", 
    "style": "vivid"
  }'

Contoh tanggapan

Operasi mengembalikan 202 kode status dan objek JSON yang GenerateImagesResponse berisi ID dan status operasi.

{ 
    "created": 1698116662, 
    "data": [ 
        { 
            "url": "url to the image", 
            "revised_prompt": "the actual prompt that was used" 
        }, 
        { 
            "url": "url to the image" 
        },
        ...
    ]
}

Meminta gambar yang dihasilkan (pratinjau DALL-E 2)

Hasilkan batch gambar dari keterangan teks.

POST https://{your-resource-name}.openai.azure.com/openai/images/generations:submit?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
prompt string Wajib Deskripsi teks gambar yang diinginkan. Panjang maksimum adalah 1000 karakter.
n Integer Opsional 1 Jumlah gambar yang akan dihasilkan. Harus antara 1 dan 5.
size string Opsional 1024 x 1024 Ukuran gambar yang dihasilkan. Harus salah satu dari 256x256, , 512x512atau 1024x1024.

Contoh permintaan

curl -X POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/images/generations:submit?api-version=2023-06-01-preview \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
"prompt": "An avocado chair",
"size": "512x512",
"n": 3
}'

Contoh tanggapan

Operasi mengembalikan 202 kode status dan objek JSON yang GenerateImagesResponse berisi ID dan status operasi.

{
  "id": "f508bcf2-e651-4b4b-85a7-58ad77981ffa",
  "status": "notRunning"
}

Mendapatkan hasil gambar yang dihasilkan (pratinjau DALL-E 2)

Gunakan API ini untuk mengambil hasil operasi pembuatan gambar. Pembuatan gambar saat ini hanya tersedia dengan api-version=2023-06-01-preview.

GET https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
operation-id string Wajib GUID yang mengidentifikasi permintaan pembuatan gambar asli.

Versi yang didukung

Contoh permintaan

curl -X GET "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Contoh tanggapan

Setelah berhasil, operasi mengembalikan 200 kode status dan OperationResponse objek JSON. Bidang status bisa ( "notRunning" tugas diantrekan tetapi belum dimulai), "running", , "succeeded", "canceled" (tugas telah kehabisan waktu), "failed", atau "deleted". Status succeeded menunjukkan bahwa gambar yang dihasilkan tersedia untuk diunduh di URL yang diberikan. Jika beberapa gambar dihasilkan, URL mereka semuanya dikembalikan di result.data bidang .

{
  "created": 1685064331,
  "expires": 1685150737,
  "id": "4b755937-3173-4b49-bf3f-da6702a3971a",
  "result": {
    "data": [
      {
        "url": "<URL_TO_IMAGE>"
      },
      {
        "url": "<URL_TO_NEXT_IMAGE>"
      },
      ...
    ]
  },
  "status": "succeeded"
}

Menghapus gambar yang dihasilkan dari server (pratinjau DALL-E 2)

Anda dapat menggunakan ID operasi yang dikembalikan oleh permintaan untuk menghapus gambar yang sesuai dari server Azure. Gambar yang dihasilkan secara otomatis dihapus setelah 24 jam secara default, tetapi Anda dapat memicu penghapusan sebelumnya jika Anda mau.

DELETE https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
operation-id string Wajib GUID yang mengidentifikasi permintaan pembuatan gambar asli.

Versi yang didukung

Contoh permintaan

curl -X DELETE "https://{your-resource-name}.openai.azure.com/openai/operations/images/{operation-id}?api-version=2023-06-01-preview"
-H "Content-Type: application/json"
-H "Api-Key: {api key}"

Respons

Operasi mengembalikan 204 kode status jika berhasil. API ini hanya berhasil jika operasi dalam status akhir (bukan running).

Ucapan ke Teks

Anda dapat menggunakan model Whisper di Azure OpenAI Service untuk transkripsi ucapan ke teks atau terjemahan ucapan. Untuk informasi selengkapnya tentang menggunakan model Whisper, lihat mulai cepat dan gambaran umum model Whisper.

Meminta transkripsi ucapan ke teks

Mentranskripsikan file audio.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/transcriptions?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model Whisper Anda seperti MyWhisperDeployment. Anda diharuskan untuk terlebih dahulu menyebarkan model Whisper sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Nilai ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
file file Ya T/A Objek file audio (bukan nama file) untuk ditranskripsikan, dalam salah satu format berikut: flac, , , mp4mp3, mpgampeg, , m4a, ogg, wav, atau webm.

Batas ukuran file untuk model Whisper di Azure OpenAI Service adalah 25 MB. Jika Anda perlu mentranskripsikan file yang lebih besar dari 25 MB, pecahkan menjadi potongan. Atau Anda dapat menggunakan API transkripsi batch Ucapan Azure AI.

Anda bisa mendapatkan sampel file audio dari repositori Azure AI Speech SDK di GitHub.
language string No Null Bahasa audio input seperti fr. Menyediakan bahasa input dalam format ISO-639-1 meningkatkan akurasi dan latensi.

Untuk daftar bahasa yang didukung, lihat dokumentasi OpenAI.
prompt string No Null Teks opsional untuk memandu gaya model atau melanjutkan segmen audio sebelumnya. Perintah harus cocok dengan bahasa audio.

Untuk informasi selengkapnya tentang perintah termasuk contoh kasus penggunaan, lihat dokumentasi OpenAI.
response_format string No json Format output transkrip, dalam salah satu opsi ini: json, teks, srt, verbose_json, atau vtt.

Nilai defaultnya adalah json.
temperature number No 0 Suhu pengambilan sampel, antara 0 dan 1.

Nilai yang lebih tinggi seperti 0,8 membuat output lebih acak, sementara nilai yang lebih rendah seperti 0,2 membuatnya lebih fokus dan deterministik. Jika diatur ke 0, model menggunakan probabilitas log untuk secara otomatis meningkatkan suhu hingga ambang batas tertentu terpukul.

Nilai default adalah 0.

Contoh permintaan

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/transcriptions?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "language=en" \
  -F "prompt=The transcript contains zoology terms and geographical locations." \
  -F "temperature=0" \
  -F "response_format=srt"

Contoh tanggapan

1
00:00:00,960 --> 00:00:07,680
The ocelot, Lepardus paradalis, is a small wild cat native to the southwestern United States,

2
00:00:07,680 --> 00:00:13,520
Mexico, and Central and South America. This medium-sized cat is characterized by

3
00:00:13,520 --> 00:00:18,960
solid black spots and streaks on its coat, round ears, and white neck and undersides.

4
00:00:19,760 --> 00:00:27,840
It weighs between 8 and 15.5 kilograms, 18 and 34 pounds, and reaches 40 to 50 centimeters

5
00:00:27,840 --> 00:00:34,560
16 to 20 inches at the shoulders. It was first described by Carl Linnaeus in 1758.

6
00:00:35,360 --> 00:00:42,880
Two subspecies are recognized, L. p. paradalis and L. p. mitis. Typically active during twilight

7
00:00:42,880 --> 00:00:48,480
and at night, the ocelot tends to be solitary and territorial. It is efficient at climbing,

8
00:00:48,480 --> 00:00:54,480
leaping, and swimming. It preys on small terrestrial mammals such as armadillo, opossum,

9
00:00:54,480 --> 00:00:56,480
and lagomorphs.

Meminta terjemahan ucapan ke teks

Menerjemahkan file audio dari bahasa lain ke dalam bahasa Inggris. Untuk daftar bahasa yang didukung, lihat dokumentasi OpenAI.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/translations?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model Whisper Anda seperti MyWhisperDeployment. Anda diharuskan untuk terlebih dahulu menyebarkan model Whisper sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Nilai ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
file file Ya T/A Objek file audio (bukan nama file) untuk ditranskripsikan, dalam salah satu format ini: flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, atau webm.

Batas ukuran file untuk model Azure OpenAI Whisper adalah 25 MB. Jika Anda perlu mentranskripsikan file yang lebih besar dari 25 MB, pecahkan menjadi potongan.

Anda dapat mengunduh file audio sampel dari repositori Azure AI Speech SDK di GitHub.
prompt string No Null Teks opsional untuk memandu gaya model atau melanjutkan segmen audio sebelumnya. Perintah harus cocok dengan bahasa audio.

Untuk informasi selengkapnya tentang perintah termasuk contoh kasus penggunaan, lihat dokumentasi OpenAI.
response_format string No json Format output transkrip, dalam salah satu opsi ini: json, teks, srt, verbose_json, atau vtt.

Nilai defaultnya adalah json.
temperature number No 0 Suhu pengambilan sampel, antara 0 dan 1.

Nilai yang lebih tinggi seperti 0,8 membuat output lebih acak, sementara nilai yang lebih rendah seperti 0,2 membuatnya lebih fokus dan deterministik. Jika diatur ke 0, model menggunakan probabilitas log untuk secara otomatis meningkatkan suhu hingga ambang batas tertentu terpukul.

Nilai default adalah 0.

Contoh permintaan

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/translations?api-version=2023-09-01-preview \
  -H "Content-Type: multipart/form-data" \
  -H "api-key: $YOUR_API_KEY" \
  -F file="@./YOUR_AUDIO_FILE_NAME.wav" \
  -F "temperature=0" \
  -F "response_format=json"

Contoh tanggapan

{
  "text": "Hello, my name is Wolfgang and I come from Germany. Where are you heading today?"
}

Teks ke ucapan

Mensintesis teks ke ucapan.

POST https://{your-resource-name}.openai.azure.com/openai/deployments/{deployment-id}/audio/speech?api-version={api-version}

Parameter jalur

Parameter Tipe Wajib diisi? Deskripsi
your-resource-name string Wajib Nama Sumber Daya Azure OpenAI Anda.
deployment-id string Wajib Nama penyebaran model teks ke ucapan Anda seperti MyTextToSpeechDeployment. Anda diharuskan untuk terlebih dahulu menyebarkan model teks ke ucapan (seperti tts-1 atau tts-1-hd) sebelum dapat melakukan panggilan.
api-version string Wajib Versi API yang digunakan untuk operasi ini. Nilai ini mengikuti format YYYY-MM-DD.

Versi yang didukung

Badan permintaan

Parameter Tipe Wajib diisi? Default Deskripsi
model string Ya T/A Salah satu model TTS yang tersedia: tts-1 atau tts-1-hd
input string Ya T/A Teks yang akan dihasilkan audionya. Panjang maksimum adalah 4096 karakter. Tentukan teks input dalam bahasa pilihan Anda.1
voice string Ya T/A Suara yang akan digunakan saat menghasilkan audio. Suara yang didukung adalah alloy, , fableecho, onyx, nova, dan shimmer. Pratinjau suara tersedia di panduan teks ke ucapan OpenAI.

1 Model teks ke ucapan umumnya mendukung bahasa yang sama dengan model Whisper. Untuk daftar bahasa yang didukung, lihat dokumentasi OpenAI.

Contoh permintaan

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/audio/speech?api-version=2024-02-15-preview \
 -H "api-key: $YOUR_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
    "model": "tts-hd",
    "input": "I'm excited to try text to speech.",
    "voice": "alloy"
}' --output speech.mp3

Contoh tanggapan

Ucapan dikembalikan sebagai file audio dari permintaan sebelumnya.

API Manajemen

Azure OpenAI disebarkan sebagai bagian dari layanan Azure AI. Semua layanan Azure AI mengandalkan serangkaian API manajemen yang sama untuk operasi pembuatan, pembaruan, dan penghapusan. API manajemen juga digunakan untuk menyebarkan model dalam sumber daya Azure OpenAI.

Dokumentasi referensi API Manajemen

Langkah berikutnya

Pelajari tentang Model, dan penyempurnaan dengan REST API. Pelajari selengkapnya tentang model yang mendasari yang mendukung Azure OpenAI.