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

Not

Azure Yapay Zeka Arama Azure portalı, REST API'leri ve Azure SDK’ları aracılığıyla kullanılabilir. Ayrıca kuruluş içeriğini Microsoft Foundry portalındaki aracılar için yeniden kullanılabilir, izin kullanan bilgi bankalarına dönüştüren yönetilen bilgi katmanı Foundry IQ'yu temel alır.

Important

Bu özellikler ve işlevler 2026-05-01-preview REST API'sinin bir parçasıdır. 2026-05-01-preview, Azure aboneliğinizin bir parçası olarak size lisanslanmıştır ve Microsoft Ürün Koşulları, Microsoft Ürünler ve Hizmetler Veri Koruma Eki ("DPA") ve Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları belgelerinde "Önizlemeler" için geçerli olan koşullara tabidir.

2026-05-01-preview, diğer Microsoft hizmetleri ve üçüncü taraf hizmetlerle bağlantıları destekler. Bu hizmetlerin kullanımı ilgili koşullara tabidir ve Azure uyumluluk sınırının dışında veri işleme veya depolamanın yanı sıra Azure uyumluluk sınırına akan verilere neden olabilir.

Verilerinizin kuruluşunuzun uyumluluk ve coğrafi sınırları dışında akıp akmayacağını ve ilgili etkileri ve uygun izinlerin, sınırların ve onayların sağlanıp sağlanmayacağını yönetmek sizin sorumluluğunuzdadır.

Özel kullanım örnekleriniz bağlamında oluşturduğunuz uygulamaları dikkatle gözden geçirmek ve test etmek ve tüm uygun kararları ve özelleştirmeleri yapmak sizin sorumluluğunuzdadır. Bu, metapromptlar, içerik filtreleri veya diğer güvenlik sistemleri gibi sorumlu yapay zeka risk azaltmalarınızı uygulamayı ve uygulamalarınızın uygun kalite, güvenilirlik, güvenlik ve güvenilirlik standartlarını karşılamasını sağlamayı içerir. Daha fazla bilgi için bkz. Azure Yapay Zeka Arama Saydamlık Notu.

Daha önceki bir REST API sürümünü kullanarak aracı alma kodu yazdıysanız, bu makalede daha yeni bir sürüme ne zaman ve nasıl geçiş yapılacağını açıklanmaktadır. 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.

Ipucu

REST yerine Azure SDK’ları mi kullanıyorsunuz? Önemli değişiklikler hakkında bilgi edinmek için bu makaleyi okuyun ve güncellemelerinizi başlatmak için en yeni paketi yükleyin. Başlamadan önce API güncelleştirmelerini onaylamak için SDK değişiklik günlüklerini denetleyin: Python, .NET, JavaScript, Java.

Ne zaman geçilmeli?

Etkin temsil destekleyen her sürüm, önemli değişiklikler getirmiştir. 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 2026-04-01 tarafından tam 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.

Nasıl Geçilir?

  • Desteklenen geçiş yolu artımlı. Kodunuz 2025-05-01-preview sürümünü hedeflediyse, önce 2025-08-01-preview sürümüne ve ardından 2025-11-01-preview sürümüne vb. geçiş yapın.

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

  • "Geçiş", önceki sürümün davranışlarını uygulayan yeni, benzersiz adlandırılmış nesneler oluşturma anlamına gelir. API'de özellikler eklenir veya silinirse mevcut bir nesnenin üzerine yazamazsınız. Yeni nesneler oluşturmanın avantajlarından biri, yeni nesneler geliştirilip test edilirken mevcut nesneleri koruyabilmektir.

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

2025-11-01-preview sürümünden geçiş gerçekleştiriyorsanız doğrudan 2026-04-01 sürümüne geçiş yapabilirsiniz. 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

2026-04-01'de , searchIndexazureBlob, 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
api-key: {{api-key}}
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'de desteklenmez.

  3. Bilgi Kaynakları - Oluşturma veya Güncelleştirme (REST API) kullanarak, benzersiz bir adla, 2026-04-01 API sürümüne ve önceki adımda belirtildiği özellik değerlerine sahip yeni bir bilgi kaynağı oluşturun.

    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
api-key: {{api-key}}
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'yi tutar ve yanıt oluşturma ayarlarını bırakı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
api-key: {{api-key}}
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'de 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 adla yeni bir bilgi tabanı oluşturmak için, 2026-04-01 API sürümüne ve yalnızca desteklenen özelliklere sahip Bilgi Tabanları - Oluştur veya Güncelle (REST API) kullanın.

    PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
api-key: {{api-key}}
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'de desteklenmez.

  • İzleme soruları için, yeni bir anlam niyetiyle yeni bir getirme talebi gönderin. 2026-04-01, devam eden mesajların dökümünü tutmaz.

Bilgi bankası çıkışınızı bir sorguyla test etmek için Bilgi Alma - Alma (REST API) uygulamasının 2026-04-01 sürümünü kullanın.

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

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{your-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.

2026-04-01'den itibaren knowledgeRetrieval'dan ayrı olan özel semanticSearch özelliği aracısal alma faturalama onayını kontrol eder; bu özellik artık sadece anlamsal sıralayıcı faturalama için kullanılır. 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/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{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. İstemci çağrılarını 2026-04-01 API sürümünü kullanacak şekilde güncelleştirin.

  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.

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

Bu bölümde, aşağıdaki REST API sürümleri için hataya neden olan ve bölünemeyen değişiklikler yer almaktadır:

2026-05-01-önizleme

2026-05-01-preview, önceden kalıcı hale getirilmiş özellikleri kaldırmadan 2025-11-01-preview temeline ek olarak bilgi bankası, bilgi kaynağı ve geri getirme ö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 2026-05-01-preview API sürümü filtresini seçin.

2025-11-01-preview ile 2026-05-01-preview arasında hataya neden olan hiçbir değişiklik yoktur. API sürümünü 2026-05-01-preview olarak değiştirdiğinizde 2025-11-01-preview'ı hedefleyen mevcut istekler çalışmaya devam eder.

2026-05-01-preview desteğiyle birlikte sunulan dil SDK'ları, SDK katmanında kırıcı nitelikte olan kod yapısı değişiklikleri getirir. SDK’nin tam şekil eşlemesi için 2026-05-01-preview için kodu ve istemcileri güncelleştirme konusuna bakın.

01.04.2026

2026-04-01, aracılı alma 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 2026-04-01 API sürümü filtresini seçin.

Aşağıdaki değişiklikler hem bilgi bankası şemasını hem de alma isteğini etkiler:

  • retrievalReasoningEffort kaldırılır. Önceden low veya medium mantık eforuyla yapılandırılmış bilgi bankaları 2026-04-01 ile uyumlu değildir ve yeniden oluşturulmalıdır.

  • outputMode kaldırılır. Geri alma işlemi, varsayılan olarak çıkarımsal dayanaklı içerik döndürür. Yanıt sentezi desteklenmez.

Aşağıdaki değişiklikler yalnızca alma isteğini etkiler:

  • intents öğesinin yerini alır messages.

  • alwaysQuerySource, knowledgeSourceParams öğesinden kaldırılır.

  • maxOutputSize olarak yeniden adlandırılır maxOutputSizeInTokens.

  • Konuşma durumu istekler arasında korunmaz. messages tabanlı çoklu dönüşlü desen desteklenmemektedir.

Aşağıdaki değişiklik, azureBlob ve indexedOneLake bilgi kaynaklarını etkiler:

  • ingestionPermissionOptions, ingestionParameters öğesinden kaldırılır. azureBlob ve indexedOneLake bu özelliği içeren bilgi kaynaklarının bu özellik olmadan yeniden oluşturulması gerekir.

Not

Kaldırılan alanların gönderilmesi bir 400 Bad Request HTTP kodu döndürür. Alma isteği artık bu sürümde bulunmayan alanları bırakmaz veya tolere etmez.

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 2025-11-01-preview API sürümü filtresini seçin.

  • Bilgi aracısı bilgi bankası olarak yeniden adlandırılır.

    Önceki yol Yeni yol
    /agents /knowledgebases
    /agents/agent-name /knowledgebases/knowledge-base-name
    /agents/agent-name/retrieve /knowledgebases/knowledge-base-name/retrieve

  • Bilgi aracısı (temel) outputConfiguration olarak yeniden adlandırılır outputMode ve nesneden dize numaralandırıcısına değiştirilir. Birkaç özellik etkilenir:

    • includeActivity, doğrudan alma isteği nesnesine outputConfiguration konumundan taşınır.
    • attemptFastPath outputConfiguration'den tamamen çıkarılmıştır. Yeni minimal akıl yürütme çabası bunun yerine geçer.

  • Bilgi aracısı (temel) requestLimits kaldırılır. maxRuntimeInSeconds ve maxOutputSize öğelerinin alt özellikleri doğrudan alma isteği nesnesine taşınır.

  • Bilgi aracısı (temel) knowledgeSources parametreleri artık yalnızca bilgi bankası tarafından kullanılan bilgi kaynağının adlarını listelemektedir. Altında knowledgeSources bulunan diğer alt özellikler, alma isteği nesnesinin knowledgeSourceParams özelliklerine taşındı.

    • rerankerThreshold
    • alwaysQuerySource
    • includeReferenceSourceData
    • includeReferences

    Özellik maxSubQueries artık mevcut değil. Yeni geri çağırma mantığı çabası özelliği, onun yerini alır.

  • Bilgi aracısı (temel) alma isteği nesnesi: semanticReranker Etkinlik kaydı, etkinlik kayıt türüyle agenticReasoning değiştirilir.

  • Hem azureBlob hem de searchIndex için bilgi kaynakları: identity, embeddingModel, chatCompletionModel, disableImageVerbalization ve ingestionSchedule için üst düzey özellikler artık bilgi kaynağındaki bir ingestionParameters nesnesinin parçasıdır. Arama dizininden çeken tüm bilgi kaynaklarının bir ingestionParameters nesnesi vardır.

  • Yalnızca bilgi kaynakları için searchIndex: sourceDataSelect, sourceDataFields olarak yeniden adlandırılır ve fieldName ve fieldToSearch kabul eden bir dizidir.

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 2025-08-01-preview API sürümü filtresini seçin.

  • Veri kaynaklarını tanımlamanın yeni yolu olarak bilgi kaynaklarını tanıtır ve hem (bir veya birden çok dizin) hem searchIndex de azureBlob türleri destekler. Daha fazla bilgi için bkz . Arama dizini bilgi kaynağı oluşturma ve Blob bilgi kaynağı oluşturma.

  • Aracı tanımları knowledgeSources yerine targetIndexes gerektirir. Geçiş adımları için bkz. Geçirme.

  • defaultMaxDocsForReranker desteğini kaldırır. Bu özellik daha önce içinde targetIndexes vardı, ancak knowledgeSources içinde bir yedeği yoktur.

2025-05-01-önizleme

Bu REST API sürümü, ajan tabanlı alma ve bilgi etmenlerini tanıtır. 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 2025-05-01-preview API sürümü filtresini seçin.

İlgili içerik

  • Last updated on