Aracılı alma kodunu en son sürüme geçirme

Aracı destekli getirme kodunuz daha eski bir API sürümünü hedefliyorsa, bu makale daha yeni bir sürüme ne zaman ve nasıl geçiş yapacağınızı açıklar. Ayrıca etken alımı destekleyen tüm API sürümleri için yıkıcı ve yıkıcı olmayan değişiklikleri açıklar.

Geçiş yönergeleri, var olan bir çözümü daha yeni bir API sürümünde çalıştırmanıza yardımcı olmak için tasarlanmıştır. Bu makaledeki yönergeler, uygulamanızın önceki gibi çalışması için API düzeyindeki hataya neden olan değişiklikleri gidermenize yardımcı olur. Yeni işlevler ekleme konusunda yardım için Azure Yapay Zeka Arama'daki yeniliklerle başlayın.

Ne zaman geçilmeli?

Agentic retrieval’ı destekleyen sürümlerin çoğu geriye dönük uyumluluğu bozan değişiklikler içeriyordu. API sürüm değerini koruyarak eski kodu değiştirmeden çalıştırmaya devam edebilirsiniz, ancak hata düzeltmeleri, iyileştirmeler ve daha yeni işlevlerden yararlanmak için kodunuzu güncelleştirmeniz gerekir.

Kodunuz bir önizleme sürümünü hedeflediyse, yalnızca kullanım örneğiniz tarafından 2026-04-01tam olarak destekleniyorsa en son kararlı sürüme geçiş yapmanızı öneririz. Eğer yanıt sentezine, asgari olmayan mantık yürütme çabalarına veya döngülü iletilere güveniyorsanız, geçiş yapmaya karar vermeden önce bozan ve bozmayan değişiklikleri gözden geçirin. Bu özellikler önizlemede kalır.

Taşımadan önce

• Değişikliklerin kapsamını anlamak için her sürüm için kritik ve kritik olmayan değişiklikleri gözden geçirin.

• Desteklenen geçiş yolu artımlı. Kodunuz 2025-05-01-preview sürümünü hedefliyorsa, önce 2025-08-01-preview sürümüne geçin, ardından hedef sürümünüze ulaşana kadar sonraki her sürüme sırayla geçmeye devam edin.

• Yan yana geçiş için, önceki sürümün davranışlarını uygulayan benzersiz adlandırılmış nesneler oluşturun. Bu yaklaşım, değişiklikleri geliştirir ve test ederken mevcut nesneleri korur. Bir nesne yerinde güncelleştirmeyi destekliyorsa, sürüme özgü adımlar bu seçeneği çağırır.

• Geçiş yaptığınız her nesne için, yenisini belirtmeden önce mevcut özellikleri gözden geçirebilmeniz için arama hizmetinden geçerli tanımı alarak başlayın.

• Yalnızca geçişiniz tam olarak test edildikten ve dağıtıldıktan sonra eski sürümleri silin.

Nasıl Geçilir?

Bu bölüm, aşağıdaki API sürümleri için geçiş adımlarını kapsar:

• 2026-08-01-önizleme
• 2026-05-01-önizleme
• 2026-04-01
• 2025-11-01-önizleme
• 2025-08-01-önizleme

2026-08-01-önizleme

2026-05-01-preview sürümünden geçiş yapıyorsanız doğrudan 2026-08-01-preview öğesine geçebilirsiniz. Bu geçiş, Work IQ bilgi kaynakları, liste sayfalaması, yanıt işleme, MCP sunucu araçları ve etkilenen üretilen istemci çağrıları için güncellemeler gerektirir.

1. Work IQ bilgi kaynaklarını taşıma
2. Liste sayfalandırmasını güncelle
3. Güncelleştirme alma yanıtının işlenmesi
4. Kodu ve istemcileri güncelleştirme

Work IQ bilgi kaynaklarını taşıma

İş IQ bilgi kaynağını yeni kimlik doğrulama yapılandırmasına geçirmek için:

1. Geçerli tanımını dışarı aktarın.

2. Bilgi Kaynakları - Oluştur veya Güncelleştir'i kullanarak mevcut bilgi kaynağını güncelleştirin veya yan yana geçiş için benzersiz bir adla yeni bir ad oluşturun.

3. 2026-08-01-preview API sürümünü kullanın ve yapılandırınworkIQParameters.entraAppAuthentication. applicationId ve federatedCredentialId özellikleri gereklidir. tenantId özelliği isteğe bağlıdır ve arama hizmetinin kiracısını varsayılan olarak kullanır.

4. Bir değiştirme oluşturduysanız, değiştirme adını kullanmak için önceki bilgi kaynağına başvuran her bilgi bankasını güncelleştirin.

5. Kullanıcı doğrulama beyanını x-ms-query-work-iq-source-authorization üst bilgisinde iletmek için alma isteklerini güncelleştirin.

Kurulum ve örnekler için bkz . İş IQ bilgi kaynağı oluşturma (önizleme).

Liste sayfalamasını güncelleştir

Ofset tabanlı sayfalamayı imleç tabanlı sayfalamayla değiştirmek için:

1. Bilgi kaynağı listesi isteklerinden $skip, $count ve $top öğelerini kaldırın. Sayfa boyutunu denetlemek için 1 ile 3.000 arasında bir değer ayarlayın pageSize . Bunu atlarsanız, hizmet sayfa boyutunu seçer.

2. Ada göre filtrelemek için, searchType ve search ayarlayın. Desteklenen tek searchType değeri prefix’dir; bu aynı zamanda varsayılan değerdir. Aşağıdaki istek, adları ile contosobaşlayan en fazla 100 bilgi kaynağı döndürür.

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

   Başvuru:Bilgi Kaynakları - Liste

3. Yanıt @odata.nextLink içeriyorsa, bu URL'yi döndüğü biçimiyle tam olarak gönderin. Devamlılık durumunu ayrıştırmayın veya değiştirmeyin.

Güncelleştirme alma yanıtının işlenmesi

Yeni Work IQ referansını ve model destekli etkinlik biçimlerini işlemek için:

1. , WorkIQAttributionve seeMoreWebUrlüzerindeki attributionsbağımlılıkları kaldırın. Work IQ başvurusundaki searchSensitivityLabelInfo öğesinden duyarlılık etiketi meta verilerini okuyun.

2. Sorgu planlama, yanıt sentezi ve web özetleme etkinliği kayıtlarında, iç içe geçmiş deploymentId nesnesinden model ve modelName değerlerini okuyun. İç içe geçmiş nesne ve her iki özellik de isteğe bağlıdır.

Aşağıdaki parçalar yanıt şekli değişikliklerini gösterir.

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

içinde 2026-08-01-preview, aynı parçalar aşağıdaki şekli kullanır:

{
  "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>"
      }
    }
  ]
}

2026-08-01-preview için kodu ve istemcileri güncelleştirme

Geçişinizi tamamlamak için:

1. Her bir MCP sunucusu tools öğesinde, resultsProcessing öğesini inclusionMode ile değiştirin. rerank öğesini none öğesine ve reranked öğesini always öğesine eşleyin. Değer rerank varsayılan değerdir. none değeri, yeniden sıralamayı atlar ve aracın temel sonuç sıralamasını korur. Kurulum için bkz. MCP sunucusu bilgi kaynağı için araçları yapılandırma.

2. Azure SDK kullanıyorsanız, destekleyen 2026-08-01-previewbir paket yükleyin ve parametre sırası değişiklikleri için konumsal liste çağrılarını gözden geçirin. HTTP parametreleri ada göre anahtarlandığından REST çağıranları etkilenmez. C# dilinde, gibi GetKnowledgeSourcesAsync(search: ..., pageSize: ...)adlandırılmış bağımsız değişkenleri tercih edin. Python'da, liste seçeneklerini anahtar sözcük bağımsız değişkenleri olarak geçirin.

3. Üretimi güncellemeden önce Work IQ kimlik doğrulamasını ve referanslarını, imleçle sayfalamayı, etkinlik kaydı serileştirmesini çözmeyi, MCP sunucusu sonuç sıralamasını ve oluşturulan istemci çağrılarını test edin.

4. Work IQ için yeni bilgi kaynakları oluşturduysanız, önceki kaynakları yalnızca geçiş tüm testleri başarıyla geçtikten, güncelleştirilmiş uygulamanız dağıtıldıktan ve hiçbir bilgi tabanı eski adları kullanmadıktan sonra silin.

2026-05-01-önizleme

2026-04-01 veya 2025-11-01-preview sürümünden geçiş yapıyorsanız, doğrudan 2026-05-01-preview öğesine geçebilirsiniz. Bu sürümlerden gelen istekler, yanıtlar ve kalıcı nesneler uyumlu kalır. Farklar, ek özellikler ve dil SDK'sı yeniden adlandırmalarıdır.

1. REST isteklerinde API sürümünü olarak 2026-05-01-preview güncelleştirin. SDK istemcileri paketin varsayılan API sürümünü kullanır, bu nedenle serviceVersion bağımsız değişkenini açıkça geçirmeniz gerekmez. Bunun yerine SDK paketine yükseltin 2026-05-01-preview .

2. Python veya JavaScript SDK'sını kullanıyorsanız, alma istemcisini KnowledgeBaseRetrievalClient olarak güncelleştirin ve eski retrieve(...) yerine retrieveKnowledge(...) çağrısı yapın. SDK'nin tam şekil eşlemesi için 2026-05-01-preview için kodu ve istemcileri güncelleştirme konusuna bakın.

3. (İsteğe bağlı) 2026-05-01-preview, kaynak başına ve nihai sonuç için belge sınırları, kalıcı alma varsayılanları, bilgi tabanı CORS’u ve alma yanıtlarındaki Purview hassasiyet etiketi meta verileri gibi yeni özellikleri benimseyin. Mevcut bir çözümün çalışmasını sağlamak için bu özelliklerden hiçbiri gerekli değildir.

2026-05-01-preview için kodu ve istemcileri güncelleştirme

SDK'lar 2026-05-01-preview desteklenen dillerde kod şekli değişikliklerine neden olur:

İstemci yapılarını güncelleştirdikten sonra, geçişi uçtan uca doğrulamak için dizin oluşturan, belgeleri karşıya yükleyen, bilgi kaynağı oluşturan, bilgi tabanı oluşturan, geri getirme isteği gönderen ve kaynakları temizleyen akışın tamamını çalıştırın.

01.04.2026

2025-11-01-preview sürümünden geçiş yapıyorsanız doğrudan 2026-04-01 sürümüne geçebilirsiniz. Dizininiz ve içeriğiniz değişmeden kalır. Yalnızca bilgi bankası şemasını ve alma isteği şeklini güncelleştirmeniz gerekir.

1. Bilgi kaynaklarını aktarma
2. Bilgi bankasını taşıma
3. Alma isteğini güncelle
4. Faturalama onaylarını güncelleştirme
5. Kodu ve istemcileri güncelleştirme

Bilgi kaynaklarını taşıma

içinde 2026-04-01, searchIndex, azureBlob, indexedOneLakeve web bilgi kaynağı türleri genel olarak kullanılabilir. Diğer bilgi kaynağı türleri önizlemede kalır.

1. Geçerli tanımı almak için Bilgi Kaynakları - Get (REST API) kullanın.

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

2. Yanıtta nelerin ileri taşınıp nelerin kaldırılacağını belirleyin:

   • searchIndex ve web için, tüm özellik değerlerini ileri taşıyın.

   • azureBlob ve indexedOneLake içindeki tüm özellik değerlerini koruyun, ancak ingestionPermissionOptions içinden ingestionParameters'yi çıkarın. Bu özellik, 2026-04-01 içinde desteklenmez.

3. Benzersiz bir ada, 2026-04-01 API sürümüne ve önceki adıma ait özellik değerlerine sahip yeni bir bilgi kaynağı oluşturmak için Bilgi Kaynakları - Oluşturma veya Güncelleştirme (REST API) kullanın.

   Aşağıdaki örnekte bir searchIndex bilgi kaynağı gösterilmektedir. , azureBlobve indexedOneLake bilgi kaynakları için webbenzer bir desen kullanın.

   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" }
       ]
     }
   }
   

Bilgi bankasını taşıma

2026-04-01 bilgi bankası, 2025-11-01-preview sürümüne göre daha basit bir şemaya sahiptir: knowledgeSources öğesini korur ve yanıt oluşturma ayarlarını kaldırır. Yeni bir nesne oluşturmadan önce geçerli tanımı gözden geçirin.

1. Geçerli tanımı almak için Bilgi Bankaları - Get (REST API) kullanın.

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

2. Yanıtta nelerin ileri taşınıp nelerin kaldırılacağını belirleyin:

   • knowledgeSources Referanslarını not edin. Bunları yeni bilgi bankasına taşıyın.

   • Varsa, , outputModeve answerInstructionsöğesini kaldırınretrievalInstructions. Bu özellikler 2026-04-01 tarafından desteklenmez.

   • Bilgi bankanız bir web bilgi kaynağı kullanıyorsa, models koruyun. Web'den bilgi getirme, model destekli özetlemeyi gerektirir. Diğer tüm bilgi kaynağı türleri için models ifadesini kaldırın.

3. Benzersiz bir ad, API sürümü ve yalnızca desteklenen özelliklerle yeni bir bilgi bankası oluşturmak için 2026-04-01 (REST API) kullanın.

   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}}" }
     ]
   }
   

Alma isteğini güncelleştirme

2026-04-01 Alma isteğinin şekli önizleme sürümünden farklı:

• yerine intentskullanınmessages.

• yerine maxOutputSizeInTokenskullanınmaxOutputSize.

• Varsa, retrievalReasoningEffort ve alwaysQuerySource öğelerini kaldırın. Bu parametreler 2026-04-01 tarafından desteklenmez.

• İzleme soruları için, yeni bir anlam niyetiyle yeni bir getirme talebi gönderin. 2026-04-01, sürekli bir ileti geçmişi tutmaz.

Bilgi tabanı çıktınızı bir sorgu kullanarak test etmek için, 2026-04-01 sürümünü kullanın (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
}

Yanıtın bir 200 OK HTTP kodu varsa, bilgi bankanız bilgi kaynağından içeriği başarıyla almıştır.

Faturalama onaylarını güncelleştirme

2026-04-01 API sürümünden itibaren, aracılı getirme faturalandırma onayı, artık yalnızca anlamsal sıralayıcı faturalandırması için geçerli olan knowledgeRetrieval'den ayrı, buna adanmış bir semanticSearch özelliği tarafından kontrol edilir. knowledgeRetrieval bir yönetim düzlemi özelliğidir, bu nedenle bunu Arama Hizmeti REST API'sini değil Arama Yönetimi REST API'sini kullanarak ayarlarsınız.

En son önizleme sürümünü kullanarak arama hizmetinizde ayarlamak için knowledgeRetrieval (REST API)'yi kullanın.

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"
  }
}

Geçerli değerler ve faturalama ayrıntıları için bkz. Bağımsız alma faturalamasını etkinleştirme veya devre dışı bırakma.

2026-04-01 için kodu ve istemcileri güncelleştirme

Geçişinizi tamamlamak için:

1. API sürümünü kullanmak için istemci çağrılarını güncelleştirin 2026-04-01 .

2. Geçiş sırasında oluşturulan yeni nesnelere başvurmak için kodunuzdaki tüm sabit kodlanmış bilgi bankası veya bilgi kaynağı adlarını güncelleştirin.

3. azureBlob veya indexedOneLake bilgi kaynaklarını taşındıysanız, ilişkili dizin, dizinleyici, veri kaynağı veya beceri kümesine isimle başvuran tüm kodları veya betikleri yeni nesnelere işaret edecek şekilde güncelleyin.

4. Yanıtları almak için işleme yapan kodu güncelleyin. Yanıtlar, activity ve references ile ayıklayıcı topraklama içeriği döndürür, sentezlenmiş yanıtlar değil.

5. Önizleme nesnelerini yalnızca yeni nesneler tam olarak doğrulandıktan ve dağıtıldıktan sonra silin.

2025-11-01-önizleme

2025-08-01-preview sürümünden geçiş gerçekleştiriyorsanız, "bilgi aracısı" "bilgi bankası" olarak yeniden adlandırılır ve birden çok özellik bir nesne tanımındaki farklı nesnelere ve düzeylere yeniden konumlandırılır.

1. SearchIndex bilgi kaynaklarını güncelleştirme
2. azureBlob bilgi kaynaklarını güncelleştirme
3. Bilgi aracısını bilgi bankasıyla değiştirme
4. Alma isteğini güncelleştirin ve güncelleştirmelerinizi test etmek için bir sorgu gönderin
5. İstemci kodunu güncelleştirme

SearchIndex bilgi kaynağını güncelleştirme

Bu yordam, önceki 2025-08-01 sürümle aynı işlev düzeyinde yeni 2025-11-01-previewsearchIndex bir bilgi kaynağı oluşturur. Temel alınan dizinin kendisi güncelleme gerektirmez.

1. Bilgi kaynağınızı bulmak için tüm bilgi kaynaklarını ada göre listeleyin.

   ### 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. Mevcut özellikleri gözden geçirmek için geçerli tanımı alın.

   ### 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
   

   Yanıt aşağıdaki örneğe benzer olmalıdır.

   {
        "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. Geçişiniz için temel olarak Bir Bilgi Kaynağı Oluştur isteği formüle edin.

   08-01-preview JSON ile başlayın.

   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"
     }
   }
   

   Geçiş için 2025-11-01-preview aşağıdaki güncelleştirmeleri yapın:

   • Bilgi kaynağına yeni bir ad verin.

   • API sürümünü olarak 2025-11-01-previewdeğiştirin.

   • Dizeyi sourceDataSelect olarak yeniden adlandırın sourceDataFields ve sorgulamak istediğiniz her alınabilir alan için ad-değer çiftleri içeren bir dizi olarak değiştirin. Bunlar, klasik sorgudaki yan select tümcesine benzer şekilde arama sonuçlarında döndürülecek alanlardır.

4. Güncelleştirmelerinizi gözden geçirin ve ardından nesneyi oluşturma isteğini gönderin.

   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" }
           ]
       }
   }
   

Artık 2025-11-01-preview için doğru özellik belirtimlerini kullanan, önceki sürümle geriye dönük uyumlu taşınmış bir searchIndex bilgi kaynağına sahipsiniz.

Yanıt, yeni nesnenin tam tanımını içerir. Artık güncelleştirmeler aracılığıyla yapabileceğiniz bu bilgi kaynağı türü için kullanılabilen yeni özellikler hakkında daha fazla bilgi için bkz. Arama dizini bilgi kaynağı oluşturma.

azureBlob bilgi kaynağını güncelleştirme

Bu yordam, önceki 2025-08-01 sürümle aynı işlev düzeyinde yeni 2025-11-01-previewazureBlob bir bilgi kaynağı oluşturur. Yeni bir nesne kümesi oluşturur: veri kaynağı, beceri seti, dizin oluşturucu, dizin.

1. Bilgi kaynağınızı bulmak için tüm bilgi kaynaklarını ada göre listeleyin.

   ### 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. Mevcut özellikleri gözden geçirmek için geçerli tanımı alın.

   ### 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
   

   İş akışınız bir model içeriyorsa yanıt aşağıdaki örneğe benzer olmalıdır. Bir yanıtın, oluşturulan nesnelerin adlarını içerdiğine dikkat edin. Bu nesneler bilgi kaynağından tamamen bağımsızdır ve bilgi kaynaklarını güncelleştirseniz veya silseniz bile çalışır durumda kalır.

    {
      "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. Geçişiniz için temel olarak Bir Bilgi Kaynağı Oluştur isteği formüle edin.

   08-01-preview JSON ile başlayın.

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

   Geçiş için 2025-11-01-preview aşağıdaki güncelleştirmeleri yapın:

   • Bilgi kaynağına yeni bir ad verin.

   • API sürümünü olarak 2025-11-01-previewdeğiştirin.

   • Aşağıdaki alt özellikler için kapsayıcı olarak ekleyin ingestionParameters : "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. Güncelleştirmelerinizi gözden geçirin ve ardından nesneyi oluşturma isteğini gönderin. Dizin oluşturucu işlem hattı için yeni nesneler oluşturulmuştur.

   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"
           }
       }
   }
   

Artık 2025-11-01-preview için doğru özellik belirtimlerini kullanan, önceki sürümle geriye dönük uyumlu taşınmış bir azureBlob bilgi kaynağına sahipsiniz.

Yanıt, yeni nesnenin tam tanımını içerir. Artık güncelleştirmeler aracılığıyla yapabileceğiniz bu bilgi kaynağı türü için kullanılabilen yeni özellikler hakkında daha fazla bilgi için bkz. Blob bilgi kaynağı oluşturma.

Bilgi aracısını bilgi bankasıyla değiştirme

1. Bilgi bankaları bir bilgi kaynağı gerektirir. Başlamadan önce 2025-11-01-preview hedefleyen bir bilgi kaynağına sahip olduğunuzdan emin olun.

2. Mevcut özellikleri gözden geçirmek için geçerli tanımı alın.

   ### 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
   

   Yanıt aşağıdaki örneğe benzer olmalıdır.

   {
     "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. Geçişiniz için temel olarak Bir Bilgi Bankası Oluşturma isteği formüle edin.

   08-01-preview JSON ile başlayın.

   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"
       }
   }
   

   Geçiş için 2025-11-01-preview aşağıdaki güncelleştirmeleri yapın:

   • Uç noktayı değiştirin: /knowledgebases/{{knowledge-base-name}}. Bilgi bankasına benzersiz bir ad verin.

   • API sürümünü olarak 2025-11-01-previewdeğiştirin.

   • Öğeyi silin requestLimits. maxRuntimeInSeconds ve maxOutputSize özellikleri artık doğrudan alma isteğinde belirtilir.

   • Güncelleştirme knowledgeSources:

     • maxSubQueries öğesini silin ve yerine retrievalReasoningEffort koyun (bkz. Alma muhakemesi çabasını ayarlama (önizleme)).

   • alwaysQuerySource, includeReferenceSourceData, includeReferences ve rerankerThreshold öğelerini bir knowledgeSourceParams bölümüne taşıyın.

   • için modelsdeğişiklik yok.

   • Güncelleştirme outputConfiguration:

     • outputConfiguration ile outputMode değiştirin.

     • Öğeyi silin attemptFastPath. Artık yok. Eşdeğer davranış, retrievalReasoningEffort en düşük değere ayarlanarak uygulanır (bkz. Geri getirme akıl yürütme çabasını ayarlama (önizleme)).

     • Mod olarak answerSynthesis ayarlandıysa, geri alma nedenleme çabasını düşük (varsayılan) veya orta olarak ayarladığınızdan emin olun.

   • 2025-11-01-preview ingestionParameters azureBlob bilgi kaynağı oluşturmak için gereksinim olarak ekleyin.

4. Güncelleştirmelerinizi gözden geçirin ve ardından nesneyi oluşturma isteğini gönderin. Dizin oluşturucu işlem hattı için yeni nesneler oluşturulmuştur.

    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."
    }
   

Artık bilgi aracısı yerine bir bilgi bankanız var ve nesne önceki sürümle geriye dönük olarak uyumlu.

Yanıt, yeni nesnenin tam tanımını içerir. Bir bilgi bankasında kullanılabilen ve artık güncelleştirmeler aracılığıyla yapabileceğiniz yeni özellikler hakkında daha fazla bilgi için bkz. Bilgi bankası oluşturma.

2025-11-01-önizleme güncellemeleri için alma işlemini güncelleyin ve test edin

2025-11-01-preview için alma isteği, LLM işlemeyi en aza indiren daha basit bir istek de dahil olmak üzere daha fazla biçimi destekleyecek şekilde değiştirildi. Bu önizleme özelliği hakkında daha fazla bilgi için bkz. Bilgi tabanı kullanarak veri erişimi. Bu bölümde kodunuzun nasıl güncelleştirilecekleri açıklanmaktadır.

1. /agents/retrieve uç noktasını /knowledgebases/retrieve olarak değiştirin.

2. API sürümünü olarak 2025-11-01-previewdeğiştirin.

3. low veya medium alma mantık yürütme çabasını kullanıyorsanız, messages için herhangi bir değişiklik yapmanız gerekmez. messages mantığını kullanıyorsanız minimal öğesini intents ile değiştirin (bkz. Alım için mantık yürütme çabasını ayarlama (önizleme)).

4. "knowledgeSourceParams öğesini ajandan kaldırılan rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences gibi tüm özellikleri yeniden içerir hale getirmek için düzenleyin."

5. Eğer retrievalReasoningEffort kullanıyorsanız minimum'ı attemptFastPath olarak ekleyin. Eğer maxSubQueries kullanıyorduysanız, artık yok. Alt sorgu işlemeyi belirtmek için retrievalReasoningEffort ayarını kullanın (bkz. Alma akıl yürütme çabasını ayarlama (önizleme)).

Bilgi tabanınızın çıktısını bir sorgu kullanarak test etmek için 2025-11-01-preview öğesinin kullanın.

### 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
}

Yanıtın bir 200 OK HTTP kodu varsa, bilgi bankanız bilgi kaynağından içeriği başarıyla almıştır.

2025-11-01-preview için kodu ve istemcileri güncelleştirme

Geçişinizi tamamlamak için şu temizleme adımlarını izleyin:

1. Yalnızca blob bilgi kaynakları için istemcileri yeni dizini kullanacak şekilde güncelleştirin. Dizin oluşturucu çalıştıran veya bir veri kaynağına, dizine veya beceri kümesine başvuran kodunuz veya betiğiniz varsa, başvuruları yeni nesnelere güncelleştirdiğinizden emin olun.

2. Yapılandırma dosyaları, kod, betikler ve testlerdeki tüm aracı başvurularını knowledgeBases ile değiştirin.

3. İstemci çağrılarını 2025-11-01-preview kullanacak şekilde güncelleyin.

4. Eski şekiller kullanılarak oluşturulan önbelleğe alınmış tanımları temizleyin veya yeniden oluşturun.

2025-08-01-önizleme

2025-05-01-preview kullanarak bir bilgi aracısı oluşturduysanız, aracınızın tanımı satır içi targetIndexes dizi ve isteğe bağlı defaultMaxDocsForReranker bir özellik içerir.

2025-08-01-preview API sürümünden itibaren, yeniden kullanılabilir bilgi kaynakları targetIndexes yerine geçer ve defaultMaxDocsForReranker artık desteklenmez. Bu önemli değişiklikler, şunları yapmanızı gerektirir:

1. Geçerli targetIndexes yapılandırmayı alma
2. Eşdeğer bir bilgi kaynağı oluşturma
3. Aracıyı knowledgeSources yerine targetIndexes kullanacak şekilde güncelleyin
4. Alma işlemini test etmek için sorgu gönderme
5. targetIndexes kullanan kodu kaldırın ve istemcileri güncelleyin

Geçerli yapılandırmayı alma

Aracınızın tanımını 2025-05-01-preview almak için Bilgi Aracıları - Get (REST API) kullanın.

@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}}

Yanıt aşağıdaki örneğe benzer olmalıdır. indexNameGelecek adımlarda kullanmak üzere , defaultRerankerThresholdve defaultIncludeReferenceSourceData değerlerini kopyalayın. defaultMaxDocsForReranker kullanım dışı bırakıldığından değerini yoksayabilirsiniz.

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

Bilgi kaynağı oluşturma

Bir searchIndex bilgi kaynağı oluşturmak için, 2025-08-01-preview öğesinin kullanın. Daha önce kopyaladığınız değere ayarlayın searchIndexName .

@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"
        }
    }

Önceki örnek, bir dizini temsil eden bir bilgi kaynağı oluşturur, ancak birden çok dizini veya bir Azure blobu hedefleyebilirsiniz. Daha fazla bilgi için bkz. Bilgi kaynağı oluşturma.

Ajanı güncelle

Aracınızın tanımındaki knowledgeSources öğesini targetIndexes ile değiştirmek için 2025-08-01-preview öğesinin kullanın. rerankerThreshold ve includeReferenceSourceData etiketlerini daha önce kopyaladığınız değerlere ayarlayın.

### 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
            }
        ]
    }

Önceki örnek tanımı tek bir bilgi kaynağına başvuracak şekilde güncelleştirir, ancak birden çok bilgi kaynağını hedefleyebilirsiniz. Diğer özellikleri de, örneğin alwaysQuerySource, alma davranışını denetlemek için kullanabilirsiniz. Daha fazla bilgi için bkz. Bilgi aracısı oluşturma.

2025-08-01-preview güncelleştirmeleri için geri alma işlemini test edin

Aracınızın çıktısını bir sorguyla test etmek için 2025-08-01-preview seçeneğini kullanın.

### 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"
                    }
                ]
            }
        ]
    }

Yanıtın bir 200 OK HTTP kodu varsa, aracınız bilgi kaynağından içeriği başarıyla almıştır.

2025-08-01-preview için kodu ve istemcileri güncelleştirme

Geçişinizi tamamlamak için şu temizleme adımlarını izleyin:

• Yapılandırma dosyaları, kod, betikler ve testlerdeki tüm targetIndexes başvurularını knowledgeSources ile değiştirin.
• İstemci çağrılarını 2025-08-01-preview kullanacak şekilde güncelleyin.
• Eski şekil kullanılarak oluşturulan önbelleğe alınmış aracı tanımlarını temizleyin veya yeniden oluşturun.

Sürüme özgü değişiklikler

Bu bölüm, aşağıdaki API sürümleri için geriye dönük uyumluluğu bozan ve bozmayan değişiklikleri kapsar:

• 2026-08-01-önizleme
• 2026-05-01-önizleme
• 2026-04-01
• 2025-11-01-önizleme
• 2025-08-01-önizleme
• 2025-05-01-önizleme

2026-08-01-önizleme

Bu 2026-08-01-preview sürüm, 2026-05-01-preview sürümünü temel alır ve Work IQ bilgi kaynaklarını, ofset tabanlı liste sayfalamasını, model destekli etkinlik kayıtlarını, MCP sunucu sonuçlarının işlenmesini veya konumsal oluşturulmuş istemci çağrılarını kullanan uygulamalar için geriye dönük uyumluluğu bozan değişiklikler içerir.

Bu sürüme ilişkin REST API başvuru belgelerini gözden geçirmek için sayfanın üst kısmındaki API sürümü filtresini seçin 2026-08-01-preview .

2026-05-01-önizleme

2026-05-01-preview daha önce kalıcı olan özellikleri kaldırmadan 2025-11-01-preview üzerine bilgi bankası, bilgi kaynağı ve alma özellikleri ekler. Önceki önizleme sürümlerinde oluşturduğunuz mevcut bilgi bankaları ve bilgi kaynakları çalışmaya devam eder. Bu sürüm çoğunlukla yeni işlevleri kullanıma sunar ve yalnızca önizlemeye yönelik birkaç sınırı geri alır.

Bu sürüme ilişkin REST API başvuru belgelerini gözden geçirmek için sayfanın üst kısmındaki API sürümü filtresini seçin 2026-05-01-preview .

01.04.2026

2026-04-01 etmen tabanlı geri getirme için ilk kararlı API sürümüdür. Minimum, ayıklayıcı bir alma sözleşmesi oluşturur ve önizleme dönemi ileti tabanlı sorgu planlama ve yanıt sentezi özelliklerini kaldırır.

Bu sürüme ilişkin REST API başvuru belgelerini gözden geçirmek için sayfanın üst kısmındaki API sürümü filtresini seçin 2026-04-01 .

2025-11-01-önizleme

Bu sürüme ilişkin REST API başvuru belgelerini gözden geçirmek için sayfanın üst kısmındaki API sürümü filtresini seçin 2025-11-01-preview .

2025-08-01-önizleme

Bu sürüme ilişkin REST API başvuru belgelerini gözden geçirmek için sayfanın üst kısmındaki API sürümü filtresini seçin 2025-08-01-preview .

2025-05-01-önizleme

Bu API sürümü, aracı tabanlı bilgi getirme ve bilgi ajanları sunar. Her aracı tanımı, tek bir dizin ve ve targetIndexesgibi defaultRerankerThreshold isteğe bağlı özellikleri belirten bir defaultIncludeReferenceSourceData dizi gerektirir.

Bu sürüme ilişkin REST API başvuru belgelerini gözden geçirmek için sayfanın üst kısmındaki API sürümü filtresini seçin 2025-05-01-preview .

İlgili içerik

• Azure Yapay Zeka Arama'te Agentic retrieval
• Bilgi bankası oluşturma
• Bilgi bankasını sorgulama