Memigrasikan kode pengambilan agenik ke versi terbaru

Jika kode pengambilan agenik Anda menargetkan versi API sebelumnya, artikel ini menjelaskan kapan dan cara bermigrasi ke versi yang lebih baru. Ini juga menjelaskan perubahan yang merusak dan yang tidak merusak untuk semua versi API yang mendukung agentic retrieval.

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 Yang baru di Pencarian Azure AI.

Kapan harus bermigrasi

Sebagian besar versi yang mendukung pengambilan agenik memperkenalkan perubahan yang melanggar. Anda dapat terus menjalankan kode lama yang tidak berubah dengan mempertahankan nilai versi API, tetapi untuk mendapatkan manfaat dari perbaikan bug, peningkatan, dan fungsionalitas yang lebih baru, Anda harus memperbarui kode Anda.

Jika kode Anda menargetkan versi pratinjau, sebaiknya migrasikan ke versi stabil terbaru hanya jika kasus penggunaan Anda sepenuhnya didukung oleh 2026-04-01. Jika Anda mengandalkan sintesis jawaban, upaya penalaran yang signifikan, atau pesan multi-giliran, tinjau perubahan yang mengganggu dan tidak mengganggu sebelum Anda memutuskan untuk bermigrasi. Kemampuan tersebut masih dalam fase pratinjau.

Sebelum Anda bermigrasi

• Untuk memahami cakupan perubahan, tinjau perubahan yang mempengaruhi kompatibilitas dan yang tidak mempengaruhi kompatibilitas untuk setiap versi.

• Jalur migrasi yang didukung bersifat inkremental. Jika kode Anda menargetkan 2025-05-01-preview, pertama-tama bermigrasi ke 2025-08-01-preview, maka lanjutkan melalui setiap versi berikutnya hingga Anda mencapai versi target Anda.

• Untuk migrasi berdampingan, buat objek bernama unik yang mengimplementasikan perilaku versi sebelumnya. Pendekatan ini mempertahankan objek yang ada saat Anda mengembangkan dan menguji penggantian. Jika objek mendukung pembaruan di tempat, langkah-langkah khusus versi memanggil opsi tersebut.

• 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.

Cara bermigrasi

Bagian ini mencakup langkah-langkah migrasi untuk versi API berikut:

• 2026-08-01-preview
• 2026-05-01-preview
• 2026-04-01
• Pratinjau 11-11-2025
• 2025-08-01-preview

Pratinjau 08-01 2026

Jika Anda bermigrasi dari 2026-05-01-preview, Anda dapat berpindah langsung ke 2026-08-01-preview. Migrasi ini memerlukan pembaruan pada sumber pengetahuan Work IQ, paginasi daftar, pemrosesan respons, alat server MCP, dan panggilan klien yang dihasilkan yang terdampak.

1. Memigrasikan sumber pengetahuan Work IQ
2. Memperbarui halaman daftar
3. Perbarui pemrosesan respons pengambilan
4. Memperbarui kode dan klien

Memigrasikan sumber pengetahuan Work IQ

Untuk memigrasikan sumber pengetahuan Work IQ ke konfigurasi autentikasi baru:

1. Ekspor definisinya saat ini.

2. Perbarui sumber pengetahuan yang ada dengan menggunakan Sumber Pengetahuan - Buat Atau Perbarui, atau buat pengganti dengan nama unik untuk migrasi berdampingan.

3. Gunakan versi API 2026-08-01-preview dan konfigurasikan workIQParameters.entraAppAuthentication. Properti applicationId dan federatedCredentialId diperlukan. Properti tenantId bersifat opsional dan secara default menggunakan tenant layanan pencarian.

4. Jika Anda membuat pengganti, perbarui setiap pangkalan pengetahuan yang mereferensikan sumber pengetahuan sebelumnya untuk menggunakan nama pengganti.

5. Perbarui permintaan pengambilan data untuk menyertakan asersi pengguna dalam header x-ms-query-work-iq-source-authorization.

Untuk penyiapan dan contoh, lihat Membuat sumber pengetahuan Work IQ (pratinjau).

Memperbarui paginasi daftar

Untuk mengganti halaman berbasis offset dengan halaman berbasis kursor:

1. Hapus $top, $skip, dan $count dari permintaan daftar sumber pengetahuan. Atur pageSize dari 1 hingga 3.000 untuk mengontrol ukuran halaman. Jika Anda menghilangkannya, layanan akan memilih ukuran halaman.

2. Untuk memfilter menurut nama, atur search dan searchType. Satu-satunya nilai yang didukung searchType adalah prefix, yang juga merupakan default. Permintaan berikut mengembalikan hingga 100 sumber pengetahuan yang namanya dimulai dengan contoso.

   GET {{search-endpoint}}/knowledgesources?api-version=2026-08-01-preview&pageSize=100&search=contoso&searchType=prefix
   Authorization: Bearer {{search-access-token}}
   

   Referensi:Sumber Pengetahuan - Daftar

3. Jika respons berisi @odata.nextLink, kirim URL tersebut persis seperti yang dikembalikan. Jangan mengurai atau memodifikasi status kelanjutannya.

Pembaruan pemrosesan respons pengambilan

Untuk memproses referensi Work IQ baru dan bentuk aktivitas yang didukung model:

1. Hapus dependensi pada attributions, WorkIQAttribution, dan seeMoreWebUrl. Baca metadata label sensitivitas dari searchSensitivityLabelInfo pada referensi Work IQ.

2. Dalam rekaman aktivitas perencanaan kueri, sintesis jawaban, dan ringkasan web, baca modelName dan deploymentId dari objek berlapis model . Objek berlapis dan kedua properti bersifat opsional.

Fragmen berikut menunjukkan perubahan bentuk respons.

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "attributions": [
        {
          "seeMoreWebUrl": "<attribution-url>"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "modelName": "<model-name>"
    }
  ]
}

Dalam 2026-08-01-preview, fragmen yang sama menggunakan bentuk berikut:

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "searchSensitivityLabelInfo": {
        "displayName": "<label-name>",
        "sensitivityLabelId": "<label-id>"
      }
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "model": {
        "modelName": "<model-name>",
        "deploymentId": "<deployment-id>"
      }
    }
  ]
}

Perbarui kode dan klien untuk 2026-08-01-preview

Untuk menyelesaikan migrasi Anda:

1. Pada setiap item server tools MCP, ganti inclusionMode dengan resultsProcessing. Petakan reranked ke rerank dan always ke none. Nilai rerank adalah bawaan. Nilai none melewati proses pemeringkatan ulang dan mempertahankan urutan hasil asli dari alat tersebut. Untuk penyiapan, lihat Mengonfigurasi alat untuk sumber pengetahuan server MCP.

2. Jika Anda menggunakan Azure SDK, instal paket yang mendukung 2026-08-01-preview, dan tinjau panggilan daftar posisi untuk perubahan urutan parameter. Penelepon REST tidak terpengaruh karena parameter HTTP di-key berdasarkan nama. Di C#, lebih suka argumen bernama, seperti GetKnowledgeSourcesAsync(search: ..., pageSize: ...). Di Python, berikan opsi daftar sebagai argumen kata kunci.

3. Uji autentikasi dan referensi Work IQ, paginasi kursor, deserialisasi rekaman aktivitas, pengurutan hasil server MCP, dan panggilan klien yang dihasilkan sebelum Anda memperbarui lingkungan produksi.

4. Jika Anda membuat sumber pengetahuan Work IQ pengganti, hapus sumber sebelumnya hanya setelah migrasi melewati semua pengujian, aplikasi yang diperbarui disebarkan, dan tidak ada pangkalan pengetahuan yang mereferensikan nama sebelumnya.

2026-05-01-preview

Jika Anda bermigrasi dari 2026-04-01 atau 2025-11-01-preview, Anda dapat langsung berpindah ke 2026-05-01-preview. Permintaan, respons, dan objek yang dipertahankan dari versi tersebut tetap kompatibel. Perbedaannya adalah fitur aditif dan penggantian nama SDK bahasa.

1. Perbarui versi API ke 2026-05-01-preview pada permintaan REST. Klien SDK menggunakan versi API default paket, sehingga Anda tidak perlu meneruskan argumen eksplisit serviceVersion . Sebagai gantinya, tingkatkan ke paket SDK 2026-05-01-preview.

2. Jika Anda menggunakan SDK Python atau JavaScript, perbarui klien retrieve ke KnowledgeBaseRetrievalClient dan panggil retrieve(...) alih-alih retrieveKnowledge(...) versi lama. Untuk pemetaan struktur SDK lengkap, lihat Perbarui kode dan klien untuk 2026-05-01-preview.

3. (Opsional) Gunakan fitur baru 2026-05-01-preview, seperti pengambilan yang mempertimbangkan kebaruan, batas jumlah dokumen per sumber dan hasil akhir, default pengambilan yang dipertahankan, CORS basis pengetahuan, dan metadata label sensitivitas Purview dalam respons pengambilan. Tidak ada fitur ini yang diperlukan untuk menjaga solusi yang ada tetap berfungsi.

Perbarui kode dan klien untuk 2026-05-01-preview

2026-05-01-preview SDK memperkenalkan perubahan bentuk kode di seluruh bahasa yang didukung:

Setelah Anda memperbarui bentuk klien, jalankan alur penuh yang membuat indeks, mengunggah dokumen, membuat sumber pengetahuan, membuat pangkalan pengetahuan, mengeluarkan permintaan pengambilan, dan membersihkan sumber daya untuk mengonfirmasi migrasi secara menyeluruh.

2026-04-01

Jika Anda bermigrasi dari 2025-11-01-preview, Anda dapat bermigrasi langsung ke 2026-04-01. Indeks dan konten Anda tetap tidak berubah. Anda hanya perlu memperbarui skema basis pengetahuan dan struktur permintaan pengambilan.

1. Memigrasikan sumber pengetahuan
2. Memigrasikan pangkalan pengetahuan
3. Perbarui permintaan pengambilan
4. Memperbarui persetujuan penagihan
5. Memperbarui kode dan klien

Memigrasikan sumber pengetahuan

Dalam 2026-04-01, searchIndex, azureBlob, indexedOneLake, dan web jenis sumber pengetahuan umumnya tersedia. Jenis sumber pengetahuan lainnya tetap dalam pratinjau.

1. Gunakan Sumber Pengetahuan - Dapatkan (REST API) untuk mendapatkan definisi saat ini.

   GET {{search-endpoint}}/knowledge-sources/{{knowledge-source-name}}?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. Dalam respons, identifikasi apa yang harus dibawa ke depan dan apa yang harus dihapus:

   • Untuk searchIndex dan web, teruskan semua nilai properti.

   • Untuk azureBlob dan indexedOneLake, teruskan semua nilai properti, tetapi hilangkan ingestionPermissionOptions dari ingestionParameters. Properti ini tidak didukung di 2026-04-01.

3. Gunakan Sumber Pengetahuan - Buat Atau Perbarui (REST API) untuk membuat sumber pengetahuan baru dengan nama unik, 2026-04-01 versi API, dan nilai properti dari langkah sebelumnya.

   Berikut contoh menunjukkan sumber pengetahuan searchIndex. Gunakan pola serupa untuk azureBlob, , indexedOneLakedan web sumber pengetahuan.

   PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
     "name": "{{new-knowledge-source-name}}",
     "description": "Knowledge source backed by a search index.",
     "kind": "searchIndex",
     "searchIndexParameters": {
       "searchIndexName": "{{index-name}}",
       "sourceDataFields": [
         { "name": "id" },
         { "name": "page_chunk" },
         { "name": "page_number" }
       ]
     }
   }
   

Memigrasikan pangkalan pengetahuan

Pangkalan 2026-04-01 pengetahuan memiliki skema yang lebih sederhana daripada 2025-11-01-preview versinya: menyimpan knowledgeSources dan menghilangkan pengaturan pembuatan jawaban. Tinjau definisi saat ini sebelum Anda membuat objek baru.

1. Gunakan Pangkalan Pengetahuan - Dapatkan (REST API) untuk mendapatkan definisi saat ini.

   GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. Dalam respons, identifikasi apa yang harus dibawa ke depan dan apa yang harus dihapus:

   • Perhatikan referensi knowledgeSources. Teruskan ini ke pangkalan pengetahuan baru.

   • Jika ada, hapus outputMode, answerInstructions, dan retrievalInstructions. Properti ini tidak didukung dalam 2026-04-01.

   • Jika pangkalan pengetahuan Anda menggunakan web sumber pengetahuan, simpan models. Pengambilan web memerlukan ringkasan berbasis model. Untuk semua jenis sumber pengetahuan lainnya, hapus models.

3. Gunakan Pangkalan Pengetahuan - Buat Atau Perbarui (REST API) untuk membuat pangkalan pengetahuan baru dengan nama unik, 2026-04-01 versi API, dan hanya properti yang didukung.

   PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   
   {
     "name": "{{new-knowledge-base-name}}",
     "description": "Minimal knowledge base for search index retrieval.",
     "knowledgeSources": [
       { "name": "{{new-knowledge-source-name}}" }
     ]
   }
   

Pembaruan permintaan pengambilan data

Permintaan pengambilan 2026-04-01 memiliki struktur yang berbeda dari versi pratinjau:

• Gunakan intents alih-alih messages.

• Gunakan maxOutputSizeInTokens alih-alih maxOutputSize.

• Jika ada, hapus retrievalReasoningEffort dan alwaysQuerySource. Parameter ini tidak didukung di 2026-04-01.

• Untuk pertanyaan tindak lanjut, kirim permintaan pencarian baru dengan maksud semantik baru. 2026-04-01 tidak menyimpan transkrip pesan secara berkelanjutan.

Untuk menguji output pangkalan pengetahuan Anda dengan kueri, gunakan 2026-04-01 versi Pengambilan Pengetahuan - Ambil (REST API).

POST {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}/retrieve?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{query-text}}"
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "{{new-knowledge-source-name}}",
      "kind": "searchIndex",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.5
    }
  ],
  "maxRuntimeInSeconds": 30,
  "maxOutputSizeInTokens": 6000
}

Jika respons memiliki 200 OK kode HTTP, pangkalan pengetahuan Anda berhasil mengambil konten dari sumber pengetahuan.

Memperbarui persetujuan penagihan

Mulai dari versi API 2026-04-01, persetujuan penagihan untuk retrieval agentik diatur oleh properti khusus bernama knowledgeRetrieval yang terpisah dari semanticSearch, yang kini hanya berlaku untuk penagihan semantic ranker. knowledgeRetrieval adalah properti sarana manajemen, jadi Anda mengaturnya melalui REST API Manajemen Pencarian, bukan REST API Layanan Pencarian.

Gunakan versi pratinjau terbaru Layanan - Buat Atau Perbarui (REST API) untuk mengatur knowledgeRetrieval pada layanan pencarian Anda.

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{management-access-token}}

{
  "properties": {
    "knowledgeRetrieval": "standard"
  }
}

Untuk nilai dan detail penagihan yang valid, lihat Aktifkan atau nonaktifkan penagihan penelusuran agen.

Memperbarui kode dan klien untuk 2026-04-01

Untuk menyelesaikan migrasi Anda:

1. Perbarui panggilan klien untuk menggunakan 2026-04-01 versi API.

2. Perbarui pangkalan pengetahuan hardcoded atau nama sumber pengetahuan dalam kode Anda untuk mereferensikan objek baru yang dibuat selama migrasi.

3. Jika Anda memigrasikan azureBlob atau indexedOneLake sumber pengetahuan, perbarui kode atau skrip apa pun yang mereferensikan indeks, pengindeks, sumber data, atau set keterampilan terkait berdasarkan nama untuk menunjuk ke objek baru.

4. Perbarui kode yang memproses respons pengambilan. Respons mengembalikan konten grounding ekstraktif dengan activity dan references, bukan jawaban yang disintesis.

5. Hapus objek pratinjau hanya setelah objek baru divalidasi dan disebarkan sepenuhnya.

Pratinjau 01-11-2025

Jika Anda bermigrasi dari pratinjau 2025-08-01, "agen pengetahuan" diganti namanya menjadi "basis pengetahuan," dan beberapa properti dipindahkan ke objek yang berbeda serta tingkat yang berbeda dalam definisi objek.

1. Memperbarui sumber pengetahuan searchIndex
2. Memperbarui sumber pengetahuan azureBlob
3. Ganti agen pengetahuan dengan pangkalan pengetahuan
4. Memperbarui permintaan pengambilan dan mengirim kueri untuk menguji pembaruan Anda
5. Memperbarui kode klien

Memperbarui sumber pengetahuan searchIndex

Prosedur ini membuat sumber pengetahuan baru 2025-11-01-previewsearchIndex pada tingkat fungsi yang sama dengan versi sebelumnya 2025-08-01 . Indeks yang mendasar itu sendiri tidak memerlukan pembaruan.

1. 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
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. Dapatkan 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
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

   Responsnya harus 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
   }
   

3. Merumuskan permintaan Buat Sumber Pengetahuan sebagai dasar untuk migrasi Anda.

   Mulailah dengan format data JSON 08-01-preview.

   POST {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   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"
     }
   }
   

   Lakukan perubahan berikut untuk migrasi 2025-11-01-preview:

   • Beri sumber pengetahuan nama baru.

   • Ubah versi API menjadi 2025-11-01-preview.

   • Ganti nama sourceDataSelect menjadi sourceDataFields dan 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, mirip select dengan klausa dalam kueri klasik.

4. Tinjau pembaruan Anda lalu kirim permintaan untuk membuat objek.

   PUT {{search-endpoint}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   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 searchIndex yang telah dimigrasikan dan tetap kompatibel dengan versi sebelumnya, menggunakan spesifikasi properti yang benar untuk 2025-11-01-preview.

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 baru 2025-11-01-previewazureBlob pada tingkat fungsi yang sama dengan versi sebelumnya 2025-08-01 . Ini membuat sekumpulan objek baru yang dihasilkan: sumber data, keterampilan, pengindeks, indeks.

1. 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
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

2. Dapatkan 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
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

   Jika alur kerja Anda menyertakan model, responsnya harus mirip dengan contoh berikut. 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"
        }
      }
    }
   

3. Merumuskan permintaan Buat Sumber Pengetahuan sebagai dasar untuk migrasi Anda.

   Mulailah dengan format data JSON 08-01-preview.

   POST {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
   Authorization: Bearer {{search-access-token}}
   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
     }
   }
   

   Lakukan perubahan berikut untuk migrasi 2025-11-01-preview:

   • Beri sumber pengetahuan nama baru.

   • Ubah versi API menjadi 2025-11-01-preview.

   • Tambahkan ingestionParameters sebagai kontainer untuk properti anak berikut: "embeddingModel", , "chatCompletionModel", "ingestionSchedule""contentExtractionMode".

4. Tinjau pembaruan Anda lalu kirim permintaan untuk membuat objek. Objek baru yang dihasilkan dibuat untuk alur pengindeks.

   PUT {{search-endpoint}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
   Authorization: Bearer {{search-access-token}}
   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 azureBlob yang telah dimigrasikan dan tetap kompatibel dengan versi sebelumnya, menggunakan spesifikasi properti yang benar untuk 2025-11-01-preview.

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 Membuat sumber pengetahuan blob.

Ganti agen pengetahuan dengan pangkalan pengetahuan

1. Pangkalan pengetahuan memerlukan sumber pengetahuan. Pastikan Anda memiliki sumber pengetahuan yang menargetkan 2025-11-01-preview sebelum memulai.

2. 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
   Authorization: Bearer {{search-access-token}}
   Content-Type: application/json
   

   Responsnya harus 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
     }
   }
   

3. Merumuskan permintaan Buat Pangkalan Pengetahuan sebagai dasar untuk migrasi Anda.

   Mulailah dengan format data JSON 08-01-preview.

   PUT {{search-endpoint}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
   Authorization: Bearer {{search-access-token}}
   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"
       }
   }
   

   Lakukan perubahan berikut untuk migrasi 2025-11-01-preview:

   • Ganti titik akhir: /knowledgebases/{{knowledge-base-name}}. Berikan nama yang unik untuk pangkalan pengetahuan.

   • Ubah versi API menjadi 2025-11-01-preview.

   • Hapus requestLimits. Properti maxRuntimeInSeconds dan maxOutputSize sekarang ditentukan langsung pada permintaan pengambilan.

   • Perbarui knowledgeSources:

     • Hapus maxSubQueries dan ganti dengan retrievalReasoningEffort (lihat Mengatur upaya penalaran pengambilan (pratinjau)).

   • Pindahkan alwaysQuerySource, includeReferenceSourceData, includeReferences, dan rerankerThreshold ke bagian knowledgeSourceParams dalam tindakan mengambil.

   • Tidak ada perubahan untuk models.

   • Perbarui outputConfiguration:

     • Ganti outputConfiguration dengan outputMode.

     • Hapus attemptFastPath. Sudah tidak ada lagi. Perilaku yang setara dicapai dengan menetapkan retrievalReasoningEffort ke minimum (lihat Mengatur upaya penalaran untuk pengambilan (pratinjau)).

     • Jika modalitas diatur ke answerSynthesis, pastikan Anda mengatur tingkat usaha penalaran pengambilan ke rendah (default) atau sedang.

   • Tambahkan ingestionParameters sebagai persyaratan untuk membuat 2025-11-01-preview sumber pengetahuan azureBlob.

4. Tinjau pembaruan Anda lalu kirim permintaan untuk membuat objek. Objek baru yang dihasilkan dibuat untuk alur pengindeks.

    PUT {{search-endpoint}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
    Authorization: Bearer {{search-access-token}}
    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 sebuah basis pengetahuan alih-alih agen pengetahuan, dan objek tersebut kompatibel 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 pengambilan untuk pembaruan pratinjau versi 2025-11-01.

Permintaan pengambilan dimodifikasi agar 2025-11-01-preview mendukung lebih banyak format, termasuk permintaan yang lebih sederhana yang meminimalkan pemrosesan LLM. Untuk informasi selengkapnya tentang pengambilan data dalam pratinjau ini, silakan lihat Mengambil data menggunakan pangkalan pengetahuan. Bagian ini menjelaskan cara memperbarui kode Anda.

1. /agents/retrieve Ubah titik akhir menjadi /knowledgebases/retrieve.

2. Ubah versi API menjadi 2025-11-01-preview.

3. Tidak diperlukan perubahan pada messages jika Anda menggunakan low atau medium dengan upaya penalaran pengambilan. Ganti messages dengan intents jika Anda menggunakan penalaran minimal (lihat Mengatur upaya penalaran untuk pengambilan (pratinjau)).

4. Ubah knowledgeSourceParams untuk menyertakan properti apa pun yang dihapus dari agen: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

5. Tambahkan retrievalReasoningEffort atur ke minimum jika Anda menggunakan attemptFastPath. Jika Anda menggunakan maxSubQueries, itu tidak ada lagi. Gunakan pengaturan retrievalReasoningEffort untuk menentukan pemrosesan subkueri (lihat Mengatur tingkat upaya penalaran pengambilan (pratinjau)).

Untuk menguji keluaran basis pengetahuan Anda dengan kueri, gunakan fitur 2025-11-01-preview dari Pengambilan Pengetahuan - Ambil (REST API).

### Send a query to the knowledge base
POST {{search-endpoint}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
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 dan menyesuaikan kode serta klien untuk versi pratinjau 2025-11-01

Untuk menyelesaikan migrasi Anda, ikuti langkah-langkah pembersihan berikut:

1. Hanya untuk sumber pengetahuan 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.

2. Ganti semua referensi agen dengan knowledgeBases dalam file konfigurasi, kode, skrip, dan pengujian.

3. Perbarui panggilan klien untuk menggunakan 2025-11-01-preview.

4. Hapus atau regenerasi definisi cache yang dibuat menggunakan bentuk lama.

Pratinjau 01-08-2025

Jika Anda membuat agen pengetahuan menggunakan 2025-05-01-preview, definisi agen Anda mencakup array inline targetIndexes dan properti opsional defaultMaxDocsForReranker.

Mulai dengan versi API 2025-08-01-preview, sumber pengetahuan yang dapat digunakan kembali menggantikan targetIndexes, dan defaultMaxDocsForReranker tidak lagi didukung. Perubahan yang mengganggu ini mengharuskan Anda:

1. Mendapatkan konfigurasi saat ini targetIndexes
2. Membuat sumber pengetahuan yang setara
3. Memperbarui agen untuk digunakan knowledgeSources alih-alih targetIndexes
4. Mengirim kueri untuk menguji pengambilan
5. Menghapus kode yang menggunakan targetIndexes dan memperbarui klien

Dapatkan konfigurasi saat ini

Untuk mengambil definisi agen Anda, gunakan 2025-05-01-preview dari Knowledge Agents - Get (REST API).

@search-endpoint = <search-endpoint>
@agent-name = <agent-name>
@search-access-token = <search-access-token>

### Get agent definition
GET {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    Authorization: Bearer {{search-access-token}}

Responsnya harus mirip dengan contoh berikut. indexNameSalin nilai , defaultRerankerThreshold, dan defaultIncludeReferenceSourceData untuk digunakan dalam langkah-langkah mendatang. defaultMaxDocsForReranker tidak digunakan lagi, sehingga Anda dapat mengabaikan nilainya.

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "my-knowledge-agent",
  "description": "My description of the agent",
  "targetIndexes": [
    {
      "indexName": "my-index",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ]
}

Membuat sumber pengetahuan

Untuk membuat searchIndex sumber pengetahuan, gunakan 2025-08-01-previewSumber Pengetahuan - Buat (REST API). Atur searchIndexName ke nilai yang sebelumnya Anda salin.

@source-name = <source-name>

### Create a knowledge source
PUT {{search-endpoint}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index"
        }
    }

Contoh sebelumnya membuat sumber pengetahuan yang mewakili satu indeks, tetapi Anda dapat menargetkan beberapa indeks atau blob Azure. Untuk informasi selengkapnya, lihat Membuat sumber pengetahuan.

Memperbarui agen

Untuk mengganti targetIndexes dengan knowledgeSources dalam definisi agen Anda, gunakan 2025-08-01-previewAgen Pengetahuan - Buat atau Perbarui (REST API). Atur rerankerThreshold dan includeReferenceSourceData ke nilai yang sebelumnya Anda salin.

### Replace targetIndexes with knowledgeSources
POST {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{agent-name}}",
        "knowledgeSources": [
            {
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5,
                "includeReferenceSourceData": true
            }
        ]
    }

Contoh sebelumnya memperbarui definisi untuk mereferensikan satu sumber pengetahuan, tetapi Anda dapat menargetkan beberapa sumber pengetahuan. Anda juga dapat menggunakan properti lain untuk mengontrol perilaku pengambilan, seperti alwaysQuerySource. Untuk informasi selengkapnya, lihat Membuat agen pengetahuan.

Uji pengambilan untuk pembaruan pratinjau tanggal 2025-08-01

Untuk menguji output agen Anda menggunakan kueri, gunakan 2025-08-01-preview dari Knowledge Retrieval - Retrieve (REST API).

### Send a query to the agent
POST {{search-endpoint}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<query-text>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

Jika respons memiliki 200 OK kode HTTP, agen Anda berhasil mengambil konten dari sumber pengetahuan.

Memperbarui kode dan klien untuk versi pratinjau 2025-08-01

Untuk menyelesaikan migrasi Anda, ikuti langkah-langkah pembersihan berikut:

• Ganti semua targetIndexes referensi dengan knowledgeSources dalam file konfigurasi, kode, skrip, dan pengujian.
• Perbarui panggilan klien untuk menggunakan 2025-08-01-preview.
• Hapus atau regenerasi definisi agen cache yang dibuat menggunakan bentuk lama.

Perubahan khusus versi

Bagian ini mencakup perubahan yang menyebabkan ketidakcocokan dan perubahan yang tidak menyebabkan ketidakcocokan untuk versi API berikut:

• 2026-08-01-preview
• 2026-05-01-preview
• 2026-04-01
• Pratinjau 11-11-2025
• 2025-08-01-preview
• Pratinjau 05-01 2025

Pratinjau 08-01 2026

Versi ini 2026-08-01-preview dibangun pada pratinjau 2026-05-01 dan mencakup perubahan mencolok untuk aplikasi yang menggunakan sumber pengetahuan Work IQ, penomoran daftar berbasis offset, catatan aktivitas yang didukung model, pemrosesan hasil server MCP, atau panggilan klien yang dihasilkan posisi.

Untuk meninjau dokumentasi referensi REST API untuk versi ini, pilih 2026-08-01-preview filter versi API di bagian atas halaman.

2026-05-01-preview

2026-05-01-preview menambahkan basis pengetahuan, sumber pengetahuan, dan fitur pengambilan di atas 2025-11-01-preview tanpa menghapus properti yang sebelumnya disimpan. Pangkalan pengetahuan dan sumber pengetahuan yang ada yang Anda buat di versi pratinjau sebelumnya terus berfungsi. Versi ini terutama menghadirkan fungsionalitas baru dan membatalkan beberapa batasan yang hanya berlaku pada versi pratinjau.

Untuk meninjau dokumentasi referensi REST API untuk versi ini, pilih 2026-05-01-preview filter versi API di bagian atas halaman.

2026-04-01

2026-04-01 adalah versi API stabil pertama untuk retrieval agentik. Ini menetapkan kontrak minimal untuk pengambilan ekstraktif dan dapat menghapus perencanaan kueri berbasis pesan era pratinjau serta kemampuan sintesis jawaban.

Untuk meninjau dokumentasi referensi REST API untuk versi ini, pilih 2026-04-01 filter versi API di bagian atas halaman.

Pratinjau 01-11-2025

Untuk meninjau dokumentasi referensi REST API untuk versi ini, pilih 2025-11-01-preview filter versi API di bagian atas halaman.

Pratinjau 01-08-2025

Untuk meninjau dokumentasi referensi REST API untuk versi ini, pilih 2025-08-01-preview filter versi API di bagian atas halaman.

Pratinjau 05-01 2025

Versi API ini memperkenalkan penelusuran agentik 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, pilih 2025-05-01-preview filter versi API di bagian atas halaman.

Konten terkait

• Pengambilan informasi berbasis Agentic dalam Pencarian Azure AI
• Membuat pangkalan pengetahuan
• Mengkueri pangkalan pengetahuan