Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Nota
Fitur ini saat ini dalam pratinjau publik. Pratinjau ini disediakan tanpa perjanjian tingkat layanan dan tidak direkomendasikan untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.
Jika Anda menulis kode pengambilan agenik menggunakan REST API pratinjau awal, artikel ini menjelaskan kapan dan cara bermigrasi ke versi yang lebih baru. Ini juga menjelaskan perubahan yang melanggar dan tidak melanggar untuk semua versi REST API yang mendukung pengambilan agenik.
Instruksi migrasi dimaksudkan untuk membantu Anda menjalankan solusi yang ada pada versi API yang lebih baru. Instruksi dalam artikel ini membantu Anda mengatasi perubahan yang melanggar di tingkat API sehingga aplikasi Anda berjalan seperti sebelumnya. Untuk bantuan dalam menambahkan fungsionalitas baru, mulailah dengan Apa yang baru.
Petunjuk / Saran
Menggunakan Azure SDK alih-alih REST? Baca artikel ini untuk mempelajari tentang perubahan signifikan, lalu instal paket versi pratinjau yang lebih baru untuk memulai pembaruan. Sebelum memulai, periksa log perubahan SDK untuk mengonfirmasi pembaruan API: Python, .NET, JavaScript, Java.
Kapan harus bermigrasi
Setiap versi API baru yang mendukung pengambilan agentik telah memperkenalkan perubahan yang memutus kompatibilitas, dari pratinjau 2025-05-01 asli hingga pratinjau 2025-08-01, hingga pratinjau 2025-11-01 terbaru.
Anda dapat terus menjalankan kode yang lebih lama tanpa pembaruan jika Anda mempertahankan nilai versi API. Namun, untuk mendapatkan manfaat dari perbaikan bug, peningkatan, dan fungsionalitas yang lebih baru, Anda harus memperbarui kode Anda.
Cara bermigrasi
Jalur migrasi yang didukung bersifat inkremental. Jika kode Anda menargetkan versi 2025-05-01-pratinjau, pertama-tama migrasikan ke versi 2025-08-01-pratinjau, lalu migrasikan ke versi 2025-11-01-pratinjau.
Untuk memahami cakupan perubahan, tinjau perubahan yang menyebabkannya rusak dan perubahan yang tidak menyebabkannya rusak untuk setiap versi.
"Migrasi" berarti membuat objek baru bernama unik yang mengimplementasikan perilaku versi sebelumnya. Anda tidak dapat mengganti objek yang ada jika properti ditambahkan atau dihapus pada API. Salah satu keuntungan membuat objek baru adalah kemampuan untuk mempertahankan objek yang ada sementara objek baru dikembangkan dan diuji.
Untuk setiap objek yang Anda migrasikan, mulailah dengan mendapatkan definisi saat ini dari layanan pencarian sehingga Anda dapat meninjau properti yang ada sebelum menentukan yang baru.
Hapus versi lama hanya setelah migrasi Anda sepenuhnya diuji dan disebarkan.
Jika Anda bermigrasi dari pratinjau 2025-08-01, "agen pengetahuan" diganti namanya menjadi "pangkalan pengetahuan," dan beberapa properti dipindahkan ke objek yang berbeda dan ke tingkat berbeda dalam definisi objek.
- Memperbarui sumber pengetahuan searchIndex.
- Perbarui sumber pengetahuan azureBlob.
- Ganti agen pengetahuan dengan pangkalan pengetahuan.
- Perbarui permintaan pengambilan dan kirim kueri untuk menguji pembaruan Anda.
- Perbarui kode klien.
Memperbarui sumber pengetahuan searchIndex
Prosedur ini membuat sumber pengetahuan pratinjau searchIndex 2025-11-01 baru pada tingkat fungsi yang sama dengan versi 2025-08-01 sebelumnya. Indeks yang mendasar itu sendiri tidak memerlukan pembaruan.
Cantumkan semua sumber pengetahuan berdasarkan nama untuk menemukan sumber pengetahuan Anda.
### List all knowledge sources by name GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name api-key: {{api-key}} Content-Type: application/jsonDapatkan definisi saat ini untuk meninjau properti yang ada.
### Get a specific knowledge source GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview api-key: {{api-key}} Content-Type: application/jsonRespons akan terlihat mirip dengan contoh berikut.
{ "name": "search-index-ks", "kind": "searchIndex", "description": "This knowledge source pulls from a search index created using the 2025-08-01-preview.", "encryptionKey": null, "searchIndexParameters": { "searchIndexName": "earth-at-night-idx", "sourceDataSelect": "id, page_chunk, page_number" }, "azureBlobParameters": null }Merumuskan permintaan Buat Sumber Pengetahuan sebagai dasar untuk migrasi Anda.
Mulailah dengan JSON 08-01-preview.
POST {{url}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview api-key: {{key}} Content-Type: application/json { "name": "search-index-ks", "kind": "searchIndex", "description": "A sample search index knowledge source", "encryptionKey": null, "searchIndexParameters": { "searchIndexName": "my-search-index", "sourceDataSelect": "id, page_chunk, page_number" } }Buat pembaruan berikut untuk migrasi pratinjau 2025-11-01:
Beri sumber pengetahuan nama baru.
Ubah versi API menjadi
2025-11-01-preview.Ganti nama
sourceDataSelectmenjadisourceDataFieldsdan ubah string menjadi array dengan pasangan nama-nilai untuk setiap bidang yang dapat diambil yang ingin Anda kueri. Ini adalah bidang yang akan dikembalikan dalam hasil pencarian, miripselectdengan klausa dalam kueri klasik.
Tinjau pembaruan Anda lalu kirim permintaan untuk membuat objek.
PUT {{url}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview api-key: {{key}} Content-Type: application/json { "name": "search-index-ks-11-01", "kind": "searchIndex", "description": "knowledge source migrated to 2025-11-01-preview", "encryptionKey": null, "searchIndexParameters": { "searchIndexName": "my-search-index", "sourceDataFields": [ { "name": "id" }, { "name": "page_chunk" }, { "name": "page_number" } ] } }
Anda sekarang memiliki sumber pengetahuan yang dimigrasikan searchIndex yang kompatibel mundur dengan versi sebelumnya, menggunakan spesifikasi properti yang benar untuk pratinjau 2025-11-01.
Respons mencakup definisi lengkap objek baru. Untuk informasi selengkapnya tentang properti baru yang tersedia untuk jenis sumber pengetahuan ini, yang sekarang dapat Anda lakukan melalui pembaruan, lihat Cara membuat sumber pengetahuan indeks pencarian.
Memperbarui sumber pengetahuan azureBlob
Prosedur ini membuat sumber pengetahuan pratinjau azureBlob 2025-11-01 baru pada tingkat fungsi yang sama dengan versi 2025-08-01 sebelumnya. Ini membuat sekumpulan objek baru yang dihasilkan: sumber data, keterampilan, pengindeks, indeks.
Cantumkan semua sumber pengetahuan berdasarkan nama untuk menemukan sumber pengetahuan Anda.
### List all knowledge sources by name GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name api-key: {{api-key}} Content-Type: application/jsonDapatkan definisi saat ini untuk meninjau properti yang ada.
### Get a specific knowledge source GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview api-key: {{api-key}} Content-Type: application/jsonRespons mungkin terlihat mirip dengan contoh berikut jika alur kerja Anda menyertakan model. Perhatikan bahwa respons menyertakan nama objek yang dihasilkan. Objek-objek ini sepenuhnya independen dari sumber pengetahuan dan tetap beroperasi bahkan jika Anda memperbarui atau menghapus sumber pengetahuan mereka.
{ "name": "azure-blob-ks", "kind": "azureBlob", "description": "A sample azure blob knowledge source.", "encryptionKey": null, "searchIndexParameters": null, "azureBlobParameters": { "connectionString": "<redacted>", "containerName": "blobcontainer", "folderPath": null, "disableImageVerbalization": false, "identity": null, "embeddingModel": { "name": "embedding-model", "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "<redacted>", "deploymentId": "text-embedding-3-large", "apiKey": "<redacted>", "modelName": "text-embedding-3-large", "authIdentity": null }, "customWebApiParameters": null, "aiServicesVisionParameters": null, "amlParameters": null }, "chatCompletionModel": { "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "<redacted>", "deploymentId": "gpt-4o-mini", "apiKey": "<redacted>", "modelName": "gpt-4o-mini", "authIdentity": null } }, "ingestionSchedule": null, "createdResources": { "datasource": "azure-blob-ks-datasource", "indexer": "azure-blob-ks-indexer", "skillset": "azure-blob-ks-skillset", "index": "azure-blob-ks-index" } } }Merumuskan permintaan Buat Sumber Pengetahuan sebagai dasar untuk migrasi Anda.
Mulailah dengan JSON 08-01-preview.
POST {{url}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview api-key: {{key}} Content-Type: application/json { "name": "azure-blob-ks", "kind": "azureBlob", "description": "A sample azure blob knowledge source.", "encryptionKey": null, "azureBlobParameters": { "connectionString": "<redacted>", "containerName": "blobcontainer", "folderPath": null, "disableImageVerbalization": false, "identity": null, "embeddingModel": { "name": "embedding-model", "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "<redacted>", "deploymentId": "text-embedding-3-large", "apiKey": "<redacted>", "modelName": "text-embedding-3-large", "authIdentity": null }, "customWebApiParameters": null, "aiServicesVisionParameters": null, "amlParameters": null }, "chatCompletionModel": null, "ingestionSchedule": null } }Buat pembaruan berikut untuk migrasi pratinjau 2025-11-01:
Beri sumber pengetahuan nama baru.
Ubah versi API menjadi
2025-11-01-preview.Tambahkan
ingestionParameterssebagai kontainer untuk properti anak berikut:"embeddingModel", ,"chatCompletionModel","ingestionSchedule""contentExtractionMode".
Tinjau pembaruan Anda lalu kirim permintaan untuk membuat objek. Objek baru yang dihasilkan dibuat untuk alur pengindeks.
PUT {{url}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview api-key: {{key}} Content-Type: application/json { "name": "azure-blob-ks", "kind": "azureBlob", "description": "A sample azure blob knowledge source", "encryptionKey": null, "azureBlobParameters": { "connectionString": "{{blob-connection-string}}", "containerName": "blobcontainer", "folderPath": null, "ingestionParameters": { "embeddingModel": { "kind": "azureOpenAI", "azureOpenAIParameters": { "deploymentId": "text-embedding-3-large", "modelName": "text-embedding-3-large", "resourceUri": "{{aoai-endpoint}}", "apiKey": "{{aoai-key}}" } }, "chatCompletionModel": null, "disableImageVerbalization": false, "ingestionSchedule": null, "contentExtractionMode": "minimal" } } }
Anda sekarang memiliki sumber pengetahuan yang dimigrasikan azureBlob yang kompatibel dengan versi sebelumnya, menggunakan spesifikasi properti yang benar untuk pratinjau 2025-11-01.
Respons mencakup definisi lengkap objek baru. Untuk informasi selengkapnya tentang properti baru yang tersedia untuk jenis sumber pengetahuan ini, yang sekarang dapat Anda lakukan melalui pembaruan, lihat Cara membuat sumber pengetahuan Azure Blob.
Ganti agen pengetahuan dengan pangkalan pengetahuan
Pangkalan pengetahuan memerlukan sumber pengetahuan. Pastikan Anda memiliki sumber pengetahuan yang menargetkan pratinjau 2025-11-01 sebelum memulai.
Dapatkan definisi saat ini untuk meninjau properti yang ada.
### Get a knowledge agent by name GET {{search-endpoint}}/agents/earth-at-night?api-version=2025-08-01-preview api-key: {{api-key}} Content-Type: application/jsonRespons mungkin terlihat mirip dengan contoh berikut.
{ "name": "earth-at-night", "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.", "retrievalInstructions": null, "requestLimits": null, "encryptionKey": null, "knowledgeSources": [ { "name": "earth-at-night", "alwaysQuerySource": null, "includeReferences": null, "includeReferenceSourceData": null, "maxSubQueries": null, "rerankerThreshold": 2.5 } ], "models": [ { "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "<redacted>", "deploymentId": "gpt-5-mini", "apiKey": "<redacted>", "modelName": "gpt-5-mini", "authIdentity": null } } ], "outputConfiguration": { "modality": "answerSynthesis", "answerInstructions": null, "attemptFastPath": false, "includeActivity": null } }Merumuskan permintaan Buat Pangkalan Pengetahuan sebagai dasar untuk migrasi Anda.
Mulailah dengan JSON 08-01-preview.
PUT {{url}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview HTTP/1.1 api-key: {{key}} Content-Type: application/json { "name": "earth-at-night", "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.", "retrievalInstructions": null, "encryptionKey": null, "knowledgeSources": [ { "name": "earth-at-night", "alwaysQuerySource": null, "includeReferences": null, "includeReferenceSourceData": null, "maxSubQueries": null, "rerankerThreshold": 2.5 } ], "models": [ { "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "<redacted>", "apiKey": "<redacted>", "deploymentId": "gpt-5-mini", "modelName": "gpt-5-mini" } } ], "outputConfiguration": { "modality": "answerSynthesis" } }Buat pembaruan berikut untuk migrasi pratinjau 2025-11-01:
Ganti titik akhir:
/knowledgebases/{{your-object-name}}. Beri pangkalan pengetahuan nama yang unik.Ubah versi API menjadi
2025-11-01-preview.Hapus
requestLimits. PropertimaxRuntimeInSecondsdanmaxOutputSizesekarang ditentukan pada objek permintaan pengambilan secara langsungPerbarui
knowledgeSources:Hapus
maxSubQueriesdan ganti dengan 'upayaPenalaranPengambilan' (lihat Mengatur upaya penalaran pengambilan).Pindahkan
alwaysQuerySource,includeReferenceSourceData,includeReferences, danrerankerThresholdke bagianknowledgeSourcesParamsdari tindakan pengambilan.
Tidak ada perubahan untuk
models.Perbarui
outputConfiguration:Ganti
outputConfigurationdenganoutputMode.Hapus
attemptFastPath. Sudah tidak ada lagi. Perilaku yang setara diimplementasikan melaluiretrievalReasoningEffortdiatur ke minimum (lihat Mengatur upaya penalaran pengambilan).Jika modalitas diatur ke
answerSynthesis, pastikan Anda mengatur upaya penalaran pengambilan ke rendah (default) atau sedang.
Tambahkan
ingestionParameterssebagai persyaratan untuk membuat sumber pengetahuan pratinjau azureBlob 2025-11-01.
Tinjau pembaruan Anda lalu kirim permintaan untuk membuat objek. Objek baru yang dihasilkan dibuat untuk alur pengindeks.
PUT {{url}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}} api-key: {{key}} Content-Type: application/json { "name": "earth-at-night-11-01", "description": "A sample knowledge base at the same functional level as the previous knowledge agent.", "retrievalInstructions": null, "encryptionKey": null, "knowledgeSources": [ { "name": "earth-at-night-ks" } ], "models": [ { "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "<redacted>", "apiKey": "<redacted>", "deploymentId": "gpt-5-mini", "modelName": "gpt-5-mini" } } ], "retrievalReasoningEffort": null, "outputMode": "answerSynthesis", "answerInstructions": "Provide a concise and accurate answer based on the retrieved information.", }
Anda sekarang memiliki basis pengetahuan, bukan agen pengetahuan, dan objek kompatibel ke belakang dengan versi sebelumnya.
Respons mencakup definisi lengkap objek baru. Untuk informasi selengkapnya tentang properti baru yang tersedia untuk pangkalan pengetahuan, yang sekarang dapat Anda lakukan melalui pembaruan, lihat Cara membuat pangkalan pengetahuan.
Memperbarui dan menguji proses pengambilan untuk pembaruan pratinjau 2025-11-01
Permintaan pengambilan data dimodifikasi untuk pratinjau 2025-11-01 untuk mendukung lebih banyak bentuk, termasuk permintaan yang lebih sederhana yang meminimalkan pemrosesan model bahasa berskala besar (LLM). Untuk informasi selengkapnya tentang pengambilan data dalam pratinjau ini, lihat Mengambil data menggunakan basis pengetahuan. Bagian ini menjelaskan cara memperbarui kode Anda.
/agents/retrieveUbah titik akhir menjadi/knowledgebases/retrieve.Ubah versi API menjadi
2025-11-01-preview.Tidak ada perubahan
messagesyang diperlukan jika Anda menggunakanlowataumediumretrievalReasoningEffort. Ganti pesan denganintentjika Anda menggunakanminimalpenalaran (lihat Mengatur upaya penalaran pengambilan).Ubah
knowledgeSourceParamsuntuk menyertakan properti apa pun yang dihapus dari agen:rerankerThreshold,alwaysQuerySource,includeReferenceSourceData,includeReferences.Tambahkan
retrievalReasoningEffortyang diatur keminimumjika Anda sedang menggunakanattemptFastPath. Jika Anda menggunakanmaxSubQueries, itu tidak ada lagi.retrievalReasoningEffortGunakan pengaturan untuk menentukan pemrosesan subkueri (lihat Mengatur upaya penalaran pengambilan).
Untuk menguji keluaran basis pengetahuan Anda dengan kueri, gunakan pratinjau 2025-11-01 dari Pengambilan Pengetahuan - Ambil (REST API).
### Send a query to the knowledge base
POST {{url}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
api-key: {{key}}
Content-Type: application/json
{
"messages": [
{
"role": "user",
"content": [
{ "type": "text", "text": "What are some light sources on the ocean at night" }
]
}
],
"includeActivity": true,
"retrievalReasoningEffort": { "kind": "medium" },
"outputMode": "answerSynthesis",
"maxRuntimeInSeconds": 30,
"maxOutputSize": 6000
}
Jika respons memiliki 200 OK kode HTTP, pangkalan pengetahuan Anda berhasil mengambil konten dari sumber pengetahuan.
Memperbarui kode dan klien untuk pratinjau 2025-11-01
Untuk menyelesaikan migrasi Anda, ikuti langkah-langkah pembersihan berikut:
Hanya untuk sumber pengetahuan Azure Blob, perbarui klien untuk menggunakan indeks baru. Jika Anda memiliki kode atau skrip yang menjalankan pengindeks atau mereferensikan sumber data, indeks, atau set keterampilan, pastikan Anda memperbarui referensi ke objek baru.
Ganti semua referensi agen dengan
knowledgeBasesdalam file konfigurasi, kode, skrip, dan pengujian.Perbarui panggilan klien untuk menggunakan pratinjau 2025-11-01.
Hapus atau regenerasi definisi cache yang dibuat menggunakan bentuk lama.
Perubahan khusus versi
Bagian ini mencakup perubahan yang melanggar dan tidak melanggar untuk versi REST API berikut:
Pratinjau 2025-11-01
Untuk meninjau dokumentasi referensi REST API untuk versi ini, pastikan versi API pratinjau 2025-11-01 dipilih di filter di bagian atas halaman.
Agen pengetahuan diganti namanya menjadi pangkalan pengetahuan.
Rute Sebelumnya Rute Baru /agents/knowledgebases/agents/agent-name/knowledgebases/knowledge-base-name/agents/agent-name/retrieve/knowledgebases/knowledge-base-name/retrieveAgen pengetahuan (basis)
outputConfigurationdiganti namanya menjadioutputModedan diubah dari objek menjadi enumerator string. Beberapa properti terpengaruh:-
includeActivitydipindahkan darioutputConfigurationke objek permintaan pengambilan secara langsung. -
attemptFastPathinoutputConfigurationdihapus sepenuhnya. Upaya penalaran baruminimalmenjadi penggantinya.
-
Agen pengetahuan (basis)
requestLimitsdihapus. Properti turunan darimaxRuntimeInSecondsdanmaxOutputSizedipindahkan langsung ke objek permintaan pengambilan.Parameter agen pengetahuan (basis)
knowledgeSourcessekarang hanya mencantumkan nama sumber pengetahuan yang digunakan oleh pangkalan pengetahuan. Properti anak lain yang dulu berada di bawahknowledgeSourcesdipindahkan ke propertiknowledgeSourceParamsdari objek permintaan pengambilan.rerankerThresholdalwaysQuerySourceincludeReferenceSourceDataincludeReferences
Properti
maxSubQueriessudah tidak ada. Penggantinya adalah properti usaha penalaran pengambilan data yang baru.Objek permintaan pengambilan agen pengetahuan (dasar): Catatan aktivitas
semanticRerankerdiganti dengan jenis catatan aktivitasagenticReasoning.Sumber pengetahuan untuk
azureBlobdansearchIndex: properti tingkat atas untukidentity,embeddingModel,chatCompletionModeldisableImageVerbalization, daningestionSchedulesekarang menjadi bagian dari objekingestionParameterspada sumber pengetahuan. Semua sumber pengetahuan yang memanfaatkan indeks pencarian memilikiingestionParametersobjek.Hanya untuk
searchIndexsumber pengetahuan:sourceDataSelectdiganti namanya menjadisourceDataFieldsdan merupakan array yang menerimafieldNamedanfieldToSearch.
2025-08-01-preview
Untuk meninjau dokumentasi referensi REST API untuk versi ini, pastikan versi API pratinjau 2025-08-01 dipilih di filter di bagian atas halaman.
Memperkenalkan sumber pengetahuan sebagai cara baru untuk menentukan sumber data, mendukung
searchIndex(satu atau beberapa indeks) danazureBlobjenis. Untuk informasi selengkapnya, lihat Membuat sumber pengetahuan indeks pencarian dan Membuat sumber pengetahuan blob.Membutuhkan alih-alih
knowledgeSourcestargetIndexesdalam definisi agen. Untuk langkah-langkah migrasi, lihat Cara bermigrasi.defaultMaxDocsForRerankerMenghapus dukungan. Properti ini sebelumnya ada ditargetIndexes, tetapi tidak ada penggantian dalamknowledgeSources.
2025-05-01-preview
Versi REST API ini memperkenalkan pengambilan agen dan agen pengetahuan. Setiap definisi agen memerlukan targetIndexes array yang menentukan satu indeks dan properti opsional, seperti defaultRerankerThreshold dan defaultIncludeReferenceSourceData.
Untuk meninjau dokumentasi referensi REST API untuk versi ini, pastikan versi API pratinjau 2025-05-01 dipilih di filter di bagian atas halaman.