Azure Yapay Zeka Arama'da en son REST API'ye yükseltme

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.

Veri düzlemi ve denetim düzlemi işlemleri için Arama Hizmeti REST API'lerinin ve Arama Yönetimi REST API'lerinin daha yeni sürümlerine geçiş yapmak için bu makaleyi kullanın.

REST API'lerin en son sürümleri şunlardır:

Hedeflenen işlemler REST API Durum
Veri düzlemi 2026-04-01 Istikrarlı
Veri düzlemi 2026-05-01-preview Önizleme
Kontrol düzlemi 2025-05-01 Istikrarlı
Kontrol düzlemi 2026-03-01-preview Önizleme

Yükseltme yönergeleri, önceden uyumsuzluklar yaratan değişikliklerin üstesinden gelmenizi sağlayan kod değişikliklerine odaklanarak, mevcut kodun daha yeni API sürümünde de önceki sürümlerdekine benzer şekilde çalışmasını sağlar. Kodunuz çalışır durumda olduğunda, daha yeni özellikleri benimsemeye karar vekleyebilirsiniz. Yeni özellikler hakkında daha fazla bilgi edinmek için bkz. Azure Yapay Zeka Arama sürümündeki yenilikler.

Siz en yeni sürüme gelene kadar her sürüm üzerinde çalışarak API sürümlerini sırayla yükseltmenizi öneririz.

2023-07-01-preview vektör desteği için ilk REST API'ydi. Bu API sürümünü kullanmayın. Artık kullanım dışı bırakıldı ve hemen kararlı veya daha yeni önizleme REST API'lerine geçmeniz gerekir.

Not

REST API başvuru belgeleri artık sürümlenmiştir. Sürüme özgü içerik için bir başvuru sayfası açın ve içindekiler tablosunun üzerinde bulunan seçiciyi kullanarak sürümünüzü seçin.

Yükseltme zamanları

Azure Yapay Zeka Arama son çare olarak geriye dönük uyumluluğu bozar. Yükseltme şu durumlarda gereklidir:

  • Kodunuz kullanımdan kaldırılan veya desteklenmeyen bir API sürümüne başvurur ve bir veya daha fazla hataya neden olan değişikliğe tabidir.

  • Api yanıtında tanınmayan özellikler döndürülürse kodunuz başarısız olur. En iyi uygulama olarak, uygulamanız anlamadığı özellikleri görmezden gelmelidir.

  • Kodunuz API isteklerini devam ettiriyor ve bunları yeni API sürümüne yeniden göndermeye çalışıyor. Örneğin, uygulamanız Arama API'sinden döndürülen devamlılık belirteçlerini devam ettirirse bu durum oluşabilir (daha fazla bilgi için @search.nextPageParametersArama API'sinin Başvurusu'nda arayın).

Güncelleme Nasıl Yapılır?

  1. Veri düzlemi sürümünü yükseltiyorsanız yeni API sürümünde yayımlananları gözden geçirin.

  2. api-version İstek üst bilgisinde belirtilen parametresini daha yeni bir sürüme güncelleştirin.

    REST API'lerine doğrudan çağrılar yapan uygulama kodunuzda, mevcut sürümün tüm örneklerini arayın ve yeni sürümle değiştirin. REST çağrısı yapılandırma hakkında daha fazla bilgi için bkz . Hızlı Başlangıç: REST kullanarak tam metin arama.

    bir Azure SDK kullanıyorsanız, her paket REST API'nin belirli bir sürümünü hedefler. Paketinizin hangi REST API sürümünü desteklediğini belirlemek için değişiklik günlüğünü gözden geçirin. En son özelliklere ve API iyileştirmelerine erişmek için en son paket sürümüne güncelleştirin.

  3. Veri düzlemi sürümünü yükseltiyorsanız, bu makalede belgelenen hataya neden olan değişiklikleri gözden geçirin ve geçici çözümleri uygulayın. Kodunuz tarafından kullanılan sürümle başlayın ve en yeni kararlı veya önizleme sürümüne gelene kadar her yeni API sürümü için hataya neden olan değişiklikleri çözün.

Yıkıcı değişiklikler

Aşağıdaki önemli değişiklikler veri işlemleri için geçerlidir.

Temsilci tabanlı alma için önemli değişiklikler

2026-04-01 aracılı alma için ilk kararlı REST API sürümüdür. dosyasından aşağıdaki hataya neden olan değişiklikleri 2025-11-01-previewtanıtır:

  • Yanıt sentezi, sorgu planlaması ve yapılandırılabilir mantık eforu kaldırılır. Alma yalnızca ayıklayıcı, topraklanmış içeriği döndürür.

  • alma isteğinin şekli değişir: messages yerine intents, ve birkaç parametre yeniden adlandırılır veya kaldırılır.

  • Blob ve OneLake bilgi kaynakları için belge düzeyinde izin filtreleme desteklenmez.

Özellik düzeyindeki değişikliklerin ve geçiş adımlarının tam listesi için bkz. Aracılı alma kodunuzu geçirme.

Bilgi aracılar için kırıcı değişiklikler

Bilgi aracıları2025-05-01-preview tanıtıldı. 2025-08-01-preview içinde targetIndexesyeni bir bilgi kaynağı nesnesiyle değiştirildi ve defaultMaxDocsForReranker diğer API'lerle değiştirildi. 2025-11-01-preview daha fazla önemli değişiklik getirdi.

Özellik düzeyindeki değişikliklerin ve geçiş adımlarının tam listesi için bkz. Aracılı alma kodunuzu geçirme.

Bağlantı bilgilerini okuyan istemci kodu için uyumluluk bozan değişiklikler

29 Mart 2024 tarihinden itibaren geçerli olup desteklenen tüm REST API'ler için geçerlidir:

  • GET Skillset, GET Index ve GET Indexer artık yanıtta anahtar veya bağlantı özellikleri döndürmez. GET isteğinden alınan yanıttan anahtarları veya bağlantıları (hassas veriler) okuyan aşağı akış kodunuz varsa bu, uyumluluğu bozan bir değişikliktir.

  • Arama hizmetiniz için yönetici veya sorgu API anahtarlarını almanız gerekiyorsa Arama Yönetimi REST API'lerini kullanın.

  • Azure Depolama veya Azure Cosmos DB gibi başka bir Azure kaynağının bağlantı dizelerini almanız gerekiyorsa, bilgileri almak için bu kaynağın API'lerini ve yayımlanan kılavuzu kullanın.

Semantik dereceleyici için hataya neden olan değişiklikler

Anlam dereceleyicisi2023-11-01 genel kullanıma sunuldu. Önceki sürümlerdeki uyumsuzluk değişiklikleri şunlardır:

  • 2020-06-01-preview sürümünden sonra semanticConfiguration, searchFields yerine geçerek L2 derecelendirmesi için hangi alanların kullanılacağını belirtme mekanizması olarak kullanılır.

  • Tüm API sürümleri için, 14 Temmuz 2023'te Microsoft tarafından barındırılan anlamsal modellere yapılan güncellemeler, semantik sıralayıcıyı dilden bağımsız hale getirerek queryLanguage özelliğini etkin bir şekilde kullanımdan kaldırdı. Kodda "hataya neden olan değişiklik" yoktur, ancak özelliği yoksayılır.

Önizleme sürümünden geçiş yapmak ve kodunuzu kullanacak şekilde dönüştürmek için bkz. semanticConfiguration.

Veri düzlemi yükseltmeleri

Yükseltme kılavuzu, en son önceki sürümden yükseltme olduğunu varsayar. Kodunuz eski bir API sürümünü temel alırsa, en yeni sürüme ulaşmak için her bir ardışık sürüm aracılığıyla yükseltmenizi öneririz.

2026-05-01-preview sürümüne yükseltme

2026-05-01-preview yeni bilgi kaynağı türleri, alma eylemine yeni parametreler, yeni SharePoint dizin oluşturucu içerik türleri ve ACL seçenekleri ve diğer özellikleri ekler.

2025-11-01-preview sürümünden itibaren protokol düzeyinde geriye dönük uyumluluğu bozan hiçbir değişiklik yoktur. Ancak, aracılı alma için Python veya JavaScript SDK'sını kullanırsanız, alma istemcisi KnowledgeBaseRetrievalClient olarak yeniden adlandırılır ve retrieveKnowledge(...)retrieve(...) ile değiştirilir. SDK geçiş kılavuzu için bkz.: Aracılı alım kodunuzu geçirin.

Diğer tüm mevcut API'ler için hiçbir davranış değişikliği yoktur. Yeni API sürümünde geçiş yapabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2026-04-01 sürümüne yükseltme

2026-04-01 en son kararlı REST API sürümüdür. Genel kullanılabilirlik için aracılı alma, bilgi kaynaklarını seçme ve çeşitli beceri ve özellikleri teşvik eder.

Yükseltmeden önce, aşağıdaki 2026-04-01 hataya neden olan değişikliklerden herhangi birinin kodunuz için geçerli olup olmadığını denetleyin:

  • GenAI İstemi beceri tanımından altı özellik kaldırılır: httpMethod, timeout, batchSize, degreeOfParallelism, , httpHeadersve authResourceId. Yükseltmeden önce bu özellikleri kaldırın. Bu özellikleri içeren tanımlar hata 400 Bad Request döndürür.

  • Aracısal erişim şimdi kendi faturalama onayını gerektirir. Eğer semanticSearch=standard şu anda varsa, yükseltmeden önce knowledgeRetrieval=standard açıkça ayarlamanız gerekir. Daha fazla bilgi için bakınız Etkin getirme faturalamasını etkinleştirme veya devre dışı bırakma.

  • Aracılı alma kodunuz öğesini 2025-11-01-preview2026-04-01 hedeflediyse, çeşitli önizleme özelliklerini kaldırır ve amaç girişi, ayıklayıcı çıkış ve en düşük mantık etrafında alma işlemini standartlaştırır. Daha fazla bilgi için, Aracılı alma kodunuzu taşıma bölümüne bakın.

Diğer tüm mevcut API'ler için hiçbir davranış değişikliği yoktur. Yeni API sürümünde geçiş yapabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2025-11-01-preview sürümüne yükseltme

2025-11-01-preview tarafından 2025-08-01-preview içinde uygulandığı şekliyle aracılı alma işlemlerine yönelik aşağıdaki önemli değişiklikleri tanıtır:

  • agents ile knowledgebasesdeğiştirilir. Bilgi kaynaklarıyla ilgili çeşitli özellikler, bilgi tabanı tanımından çıkarılıp alma işlemine taşındı.

  • Bilgi kaynağı özellikleri yeniden düzenlenip dizin oluşturucu işlem hattı oluşturan bilgi kaynakları için yeni ingestionParameters bir nesne uygulanır.

Özellik düzeyindeki değişikliklerin ve geçiş adımlarının tam listesi için bkz. Aracılı alma kodunuzu geçirme.

Diğer tüm mevcut API'ler için hiçbir davranış değişikliği yoktur. Yeni API sürümünde geçiş yapabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2025-09-01 sürümüne yükseltme

2025-09-01 OneLake dizin oluşturucu, Belge Düzeni becerisi ve diğer API'ler için genel kullanılabilirlik ekleyen kararlı bir REST API sürümüdür.

2024-07-01 sürümünden yükseltme yapıyorsanız ve herhangi bir önizleme özelliği kullanmıyorsanız, hataya neden olan hiçbir değişiklik yoktur. Yeni kararlı sürümü kullanmak için API sürümünü değiştirin ve kodunuzu test edin.

2025-08-01-preview sürümüne yükseltme

2025-08-01-preview kullanılarak 2025-05-01-preview oluşturulan bilgi aracılarında aşağıdaki bozucu değişiklikleri tanıtır:

  • targetIndexes ile knowledgeSourcesdeğiştirilir.
  • Değiştirme olmadan defaultMaxDocsForReranker kaldırır.

Aksi takdirde, mevcut API'lerde davranış değişikliği olmaz. Yeni API sürümünde geçiş yapabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2025-05-01-preview sürümüne yükseltme

2025-05-01-preview yeni özellikler sağlar, ancak mevcut API'lerde davranış değişikliği yoktur. Yeni API sürümünde geçiş yapabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2025-03-01-preview sürümüne yükseltme

2025-03-01-preview yeni özellikler sağlar, ancak mevcut API'lerde davranış değişikliği yoktur. Yeni API sürümünde geçiş yapabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2024-11-01-preview sürümüne yükseltme

2024-11-01-preview sorgu yeniden yazma, Belge Düzeni yeteneği, beceri işleme için anahtarsız faturalama, Markdown ayrıştırma modu ve sıkıştırılmış vektörler için yeniden puanlama seçenekleri.

2024-09-01-preview sürümünden yükseltiyorsanız, yeni API sürümünü değiştirip yerine koyabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

Ancak, yeni sürüm, vectorSearch.compressions’nin söz diziminde değişiklikler sunar.

  • şununla değiştirir:rerankWithOriginalVectorsenableRescoring
  • defaultOversampling bir özelliği, yeni bir rescoringOptions nesnesine taşır.

İç API eşlemesi nedeniyle geriye dönük uyumluluk korunur, ancak yeni önizleme sürümünü benimsediyseniz söz dizimini değiştirmenizi öneririz. Söz diziminin karşılaştırması için bkz. Skaler veya ikili niceleme kullanarak vektörleri sıkıştırma.

2024-09-01-preview sürümüne yükseltme

2024-09-01-preview metin yerleştirme-3 modelleri için Matryoshka Temsili Öğrenmesi (MRL) sıkıştırması, karma sorgular için hedefli vektör filtreleme, hata ayıklama için vektör alt puan ayrıntıları ve Metin Bölme becerisi için belirteç öbekleme ekler.

2024-05-01-preview sürümünden yükseltiyorsanız, yeni API sürümünü değiştirip yerine koyabilirsiniz ve kodunuz öncekiyle aynı şekilde çalışır.

2024-07-01 sürümüne yükseltme

2024-07-01 genel bir sürümdür. Eski önizleme özellikleri genel kullanıma sunuldu: tümleşik öbekleme ve vektörleştirme (Metin Bölme becerisi, AzureOpenAIEmbedding becerisi), AzureOpenAIEmbedding tabanlı sorgu vektörleştiricisi, vektör sıkıştırma (skaler niceleme, ikili niceleme, depolanan özellik, dar veri türleri).

2024-05-01-preview'den kararlı sürüme yükseltirseniz kırılma değişikliği yoktur. Yeni kararlı sürümü kullanmak için API sürümünü değiştirin ve kodunuzu test edin.

Eğer doğrudan 2023-11-01 sürümünden yükseltme yaparsanız uyumsuz değişiklikler vardır. sürümünden 2023-11-012024-07-01sürümüne geçirebilmek için her yeni önizleme için açıklanan adımları izleyin.

2024-05-01-preview sürümüne yükseltme

2024-05-01-preview Microsoft OneLake, ikili vektörler ve daha fazla ekleme modeli için bir dizin oluşturucu ekler.

2024-03-01-preview'den yükseltme yapıyorsanız, AzureOpenAIEmbedding becerisi artık bir model adı ve boyutlar özelliği gerektirmektedir.

  1. Kod tabanınızda AzureOpenAIEmbedding referanslarını arayın.

  2. modelName "text-embedding-ada-002" olarak ayarlayın ve dimensions "1536" olarak ayarlayın.

2024-03-01-preview sürümüne yükseltme

2024-03-01-preview dar veri türleri, skaler niceleme ve vektör depolama seçenekleri ekler.

2023-10-01-preview'den yükseltme yapıyorsanız, uyumsuzluk oluşturan değişiklikler yoktur. Ancak bir davranış farkı vardır: 2023-11-01 ve daha yeni önizlemeler için, vectorFilterModefiltre ifadeleri için varsayılan değer postfilter'dan önfiltreye değiştirildi.

  1. Kod tabanınızda vectorFilterMode başvurular arayın.

  2. Özellik açıkça ayarlanırsa hiçbir eylem gerekmez. Varsayılan değere bağlıysanız, yeni varsayılan davranış sorgu yürütmeden önce filtrelemektir. Sorgu sonrası filtreleme istiyorsanız, eski davranışı korumak için açıkça postfilter olarak ayarlayın vectorFilterMode .

2023-11-01 sürümüne yükseltme

2023-11-01 genel bir sürümdür. Eski önizleme özellikleri genel kullanıma sunuldu: anlamsal derece oluşturucu ve vektör desteği.

2023-10-01-preview kaynağından kaynaklanan hiçbir uyumsuz değişiklik yoktur, ancak 2023-07-01-preview'den 2023-11-01'ye birden fazla uyumsuz değişiklik vardır. Daha fazla bilgi için bkz. 2023-07-01-preview sürümünden yükseltme.

Yeni kararlı sürümü kullanmak için API sürümünü değiştirin ve kodunuzu test edin.

2023-10-01-preview sürümüne yükseltme

2023-10-01-preview ilk dizin oluşturma sırasında yerleşik veri öbekleme ve vektörleştirme ve yerleşik sorgu vektörleştirmesi ekleyen önizleme sürümüdür. Ayrıca vektör dizin oluşturmayı ve önceki sürümden gelen sorguları destekler.

Önceki sürümden yükseltme yapıyorsanız, sonraki bölümde adımlar yer alır.

2023-07-01-preview sürümünden yükseltme

Bu API sürümünü kullanmayın. Daha yeni bir API sürümüyle uyumlu olmayan bir vektör sorgusu söz dizimi uygular.

2023-07-01-preview artık kullanım dışıdır, bu nedenle yeni kodunuzu bu sürüm üzerine kurmamalısınız veya hiçbir koşulda bu sürüme yükseltmemeniz gerekir. Bu bölüm, 2023-07-01-preview sürümünden daha yeni bir API sürümüne geçiş yolunu açıklamaktadır.

Vektör dizinleri için portal yükseltmesi

Azure portalı, 2023-07-01-preview dizinleri için tek tıklamayla yükseltme yolunu destekler. Vektör alanlarını algılar ve bir Geçiş düğmesi sağlar.

  • Geçiş yolu 2023-07-01-preview'dan 2024-05-01-preview'yedir.
  • Güncelleştirmeler vektör alanı tanımları ve vektör arama algoritması yapılandırmalarıyla sınırlıdır.
  • Güncelleştirmeler tek yönlü olarak gerçekleştirilir. Yükseltmeyi tersine çeviremezsiniz. Dizin yükseltildikten sonra, dizini sorgulamak için 2024-05-01-preview veya daha sonrasını kullanmanız gerekir.

Vektör sorgusu söz dizimlerini yükseltmek için portal geçişi yoktur. Sorgu söz dizimi değişiklikleri için bkz. kod yükseltmeleri .

Geçir'i seçmeden önce güncelleştirilmiş şemayı gözden geçirmek için JSON Düzenle'yi seçin. Kod yükseltme bölümünde açıklanan değişikliklere uygun bir şema bulmanız gerekir. Portal geçişi yalnızca bir vektör arama algoritması yapılandırmasına sahip dizinleri işler. Vektör arama algoritmasına 2023-07-01-preview eşleyen varsayılan bir profil oluşturur. Birden çok vektör arama yapılandırmasına sahip dizinler el ile geçiş gerektirir.

Vektör dizinleri ve sorgular için kod yükseltme

Vektör arama desteği , Dizin Oluşturma veya Güncelleştirme (2023-07-01-preview) bölümünde sunulmuştur.

sürümünden 2023-07-01-preview daha yeni bir kararlı veya önizleme sürümüne yükseltmek için şunlar gerekir:

  • Dizindeki vektör yapılandırmasını yeniden adlandırma ve yeniden yapılandırma
  • Vektör sorgularınızı yeniden yazma

Vektör alanlarını, yapılandırmayı ve sorgularını 'den 2023-07-01-previewgeçirmek için bu bölümdeki yönergeleri kullanın.

  1. Var olan tanımı almak için Dizin Al'ı çağırın.

  2. Vektör arama yapılandırmasını değiştirin. 2023-11-01 ve sonraki sürümler, vektörle ilgili yapılandırmaları tek bir adla paketleyen vektör profilleri kavramını tanıtır. Daha yeni sürümler algorithmConfigurations'i algorithms olarak da yeniden adlandırır.

    • olarak algorithmConfigurationsyeniden adlandırınalgorithms. Bu yalnızca dizinin yeniden adlandırılmasıdır. İçerikler geriye dönük olarak uyumludur. Bu, mevcut HNSW yapılandırma parametrelerinizin kullanılabileceğini gösterir.

    • her biri için bir ad ve bir algoritma yapılandırması vererek ekleyin profiles.

    Geçiş öncesinde (2023-07-01-preview):

      "vectorSearch": {
    "algorithmConfigurations": [
        {
            "name": "myHnswConfig",
            "kind": "hnsw",
            "hnswParameters": {
                "m": 4,
                "efConstruction": 400,
                "efSearch": 500,
                "metric": "cosine"
            }
        }
    ]}

    Geçiş sonrasında (2023-11-01):

      "vectorSearch": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

  3. vektör alanı tanımlarını değiştirin ve yerine vectorSearchConfiguration öğesini yazın vectorSearchProfile. Profil adının algoritma yapılandırma adını değil yeni bir vektör profili tanımına çözümlediğinden emin olun. Diğer vektör alanı özellikleri değişmeden kalır. Örneğin, filtrelenebilir, sıralanabilir veya modellenebilir olamazlar ya da çözümleyiciler ya da normalleştiriciler ya da eş anlamlı haritalar kullanamazlar.

    Önce (2023-07-01-preview):

      {
      "name": "contentVector",
      "type": "Collection(Edm.Single)",
      "key": false,
      "searchable": true,
      "retrievable": true,
      "filterable": false,  
      "sortable": false,  
      "facetable": false,
      "analyzer": "",
      "searchAnalyzer": "",
      "indexAnalyzer": "",
      "normalizer": "",
      "synonymMaps": "", 
      "dimensions": 1536,
      "vectorSearchConfiguration": "myHnswConfig"
  }

    2023-11-01'den sonra:

      {
    "name": "contentVector",
    "type": "Collection(Edm.Single)",
    "searchable": true,
    "retrievable": true,
    "filterable": false,  
    "sortable": false,  
    "facetable": false,
    "analyzer": "",
    "searchAnalyzer": "",
    "indexAnalyzer": "",
    "normalizer": "",
    "synonymMaps": "", 
    "dimensions": 1536,
    "vectorSearchProfile": "myHnswProfile"
  }

  4. Değişiklikleri göndermek için Oluşturma veya Güncelleştirme Dizini'ni çağırın.

  5. Sorgu söz dizimini değiştirmek için ARAMA POST'unu değiştirin. Bu API değişikliği, çok biçimli vektör sorgu türleri için destek sağlar.

    • olarak vectorsyeniden adlandırınvectorQueries.
    • Her vektör sorgusu için kind ekleyin ve bunu vector olarak ayarlayın.
    • Her vektör sorgusu için value öğesini vector öğesi olarak yeniden adlandırın.
    • İsteğe bağlı olarak, vectorFilterModefiltre ifadeleri kullanıyorsanız ekleyin. Varsayılan değer, sonrasında 2023-10-01oluşturulan dizinler için ön filtredir. Bu tarihten önce oluşturulan dizinler, filtre modunu nasıl ayarladığınızdan bağımsız olarak yalnızca postfilter'ı destekler.

    Önce (2023-07-01-preview):

    {
    "search": "*", //Required by the API but ignored for ranking in vector-only queries
    "vectors": [
      {
        "value": [
            0.103,
            0.0712,
            0.0852,
            0.1547,
            0.1183
        ],
        "fields": "contentVector",
        "k": 5
      }
    ],
    "select": "title, content, category"
}

    2023-11-01'den sonra:

    {
  "search": "*", //Required by the API but ignored for ranking in vector-only queries
  "vectorQueries": [
    {
      "kind": "vector",
      "vector": [
        0.103,
        0.0712,
        0.0852,
        0.1547,
        0.1183
      ],
      "fields": "contentVector",
      "k": 5
    }
  ],
  "vectorFilterMode": "preFilter",
  "select": "title, content, category"
}

Bu adımlar, kararlı API sürümüne veya daha yeni önizleme API sürümlerine 2023-11-01 geçişi tamamlar.

2020-06-30 sürümüne yükseltme

Bu sürümde bir uyumsuzluk yaratan değişiklik ve çeşitli davranışsal farklılıklar vardır. Genel kullanıma sunulan özellikler şunlardır:

  • Bilgi deposu, beceri kümeleri aracılığıyla oluşturulan, diğer uygulamalar aracılığıyla aşağı akış analizi ve işleme için oluşturulan zenginleştirilmiş içeriğin kalıcı olarak depolanması. Azure Yapay Zeka Arama REST API'leri aracılığıyla bir bilgi deposu oluşturulur, ancak bu depo Azure Depolama'da bulunur.

Uygulama bozan değişiklik

Önceki API sürümlerine göre yazılan kod, aşağıdaki işlevleri içeriyorsa, 2020-06-30 ve sonraki sürümlerde bozulur:

  • Filtre ifadelerindeki herhangi bir Edm.Date literali (yıl-ay-gün gibi 2020-12-12) şu Edm.DateTimeOffset biçimini takip etmelidir: 2020-12-12T00:00:00Z. Bu değişiklik, saat dilimi farkları nedeniyle hatalı veya beklenmeyen sorgu sonuçlarını işlemek için gerekliydi.

Davranış değişiklikleri

  • BM25 derecelendirme algoritması , önceki derecelendirme algoritmasını daha yeni teknolojiyle değiştirir. 2019'un ardından oluşturulan hizmetler bu algoritmayı otomatik olarak kullanır. Eski hizmetler için parametreleri yeni algoritmayı kullanacak şekilde ayarlamanız gerekir.

  • Bu sürümde, null değerler için sıralı sonuçlar değişti; sıralama asc olduğunda null değerler önce gelir, sıralama desc olduğunda ise en sona gelir. Null değerlerin nasıl sıralanacağını işlemek için kod yazdıysanız, bu değişikliğe dikkat edin.

2019-05-06 sürümüne yükseltme

Bu API sürümünde genel kullanıma sunulan özellikler şunlardır:

  • Otomatik tamamlama, kısmen belirtilen terim girişini tamamlayan bir tamamlama özelliğidir.
  • Karmaşık türler , arama dizinindeki yapılandırılmış nesne verileri için yerel destek sağlar.
  • JsonLines ayrıştırma modları, Azure Blob dizin oluşturmanın bir parçası olarak JSON varlığı başına yeni bir satırla ayrılmış bir arama belgesi oluşturur.
  • Yapay zeka zenginleştirme, Foundry Tools'un yapay zeka zenginleştirme altyapılarını kullanan dizin oluşturma sağlar.

Yıkıcı değişiklikler

Önceki bir API sürümüne göre yazılan kod, aşağıdaki işlevleri içeriyorsa 2019-05-06 ve sonraki sürümlerde çalışmaz.

  1. Azure Cosmos DB için tür özelliği. Azure Cosmos DB'nin NoSQL API veri kaynağını hedefleyen dizin oluşturucular için, değerini "type": "documentdb" olarak değiştirin.

  2. Dizine ekleyici hata işleme özelliği status referansları içeriyorsa, bunları kaldırmanız gerekir. Yararlı bilgiler sağlamadığından hata yanıtından durumu kaldırdık.

  3. Veri kaynağı bağlantı dizeleri artık yanıtta döndürülmüyor. API sürümlerinden 2019-05-06 ve 2019-05-06-Preview sonrasında, veri kaynağı API'si artık herhangi bir REST işleminin yanıtında bağlantı dizeleri döndürmez. Önceki API sürümlerinde POST kullanılarak oluşturulan veri kaynakları için Azure Yapay Zeka Arama 201 döndürdü ve ardından düz metindeki bağlantı dizesi içeren OData yanıtı geldi.

  4. Adlandırılmış Varlık Tanıma bilişsel becerisi kullanımdan kaldırıldı. Kodunuzda Ad Varlığı Tanıma becerisini çağırdıysanız, çağrı başarısız olur. Değiştirme işlevi Varlık Tanıma Becerisi (V3). Desteklenen bir beceriye geçmek için Kullanım dışı beceriler'deki önerileri izleyin.

Karmaşık türleri yükseltme

API sürümü 2019-05-06, karmaşık türler için resmi destek eklemektedir. Kodunuz 2017-11-11-Preview veya 2016-09-01-Preview sürümlerinde karmaşık tür denkliği için önceki önerileri uyguladıysa, sürümünden 2019-05-06 başlayarak bilmeniz gereken bazı yeni ve değiştirilmiş sınırlar vardır:

  • Alt alan derinliği ve dizin başına karmaşık koleksiyon sayısı sınırları azaltıldı. Önizleme api sürümlerini kullanarak bu sınırları aşan dizinler oluşturduysanız, API sürümünü 2019-05-06 kullanarak bunları güncelleştirme veya yeniden oluşturma girişimleri başarısız olur. Kendinizi bu durumda bulursanız şemanızı yeni sınırlara uyacak şekilde yeniden tasarlamanız ve ardından dizininizi yeniden oluşturmanız gerekir.

  • Api sürümünden 2019-05-06 başlayarak belge başına karmaşık koleksiyonların öğe sayısıyla ilgili yeni bir sınır vardır. Önizleme api sürümlerini kullanarak bu sınırları aşan belgelerle dizinler oluşturduysanız, api-version 2019-05-06 kullanarak bu verileri yeniden dizine ekleme girişimleri başarısız olur. Kendinizi bu durumda bulursanız, verilerinizi yeniden dizine almadan önce belge başına karmaşık koleksiyon öğelerinin sayısını azaltmanız gerekir.

Daha fazla bilgi için bkz. Azure Yapay Zeka Arama için Hizmet Sınırları.

Eski bir karmaşık tür yapısını yükseltme

Kodunuz eski önizleme API sürümlerinden biriyle karmaşık türler kullanıyorsa, şuna benzer bir dizin tanımı biçimi kullanıyor olabilirsiniz:

{
  "name": "hotels",  
  "fields": [
    { "name": "HotelId", "type": "Edm.String", "key": true, "filterable": true },
    { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
    { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
    { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true, "analyzer": "tagsAnalyzer" },
    { "name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true },
    { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address", "type": "Edm.ComplexType" },
    { "name": "Address/StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true },
    { "name": "Address/City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Address/Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true },
    { "name": "Location", "type": "Edm.GeographyPoint", "filterable": true, "sortable": true },
    { "name": "Rooms", "type": "Collection(Edm.ComplexType)" }, 
    { "name": "Rooms/Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene" },
    { "name": "Rooms/Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "fr.lucene" },
    { "name": "Rooms/Type", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/BaseRate", "type": "Edm.Double", "filterable": true, "facetable": true },
    { "name": "Rooms/BedOptions", "type": "Edm.String", "searchable": true },
    { "name": "Rooms/SleepsCount", "type": "Edm.Int32", "filterable": true, "facetable": true },
    { "name": "Rooms/SmokingAllowed", "type": "Edm.Boolean", "filterable": true, "facetable": true },
    { "name": "Rooms/Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "facetable": true, "analyzer": "tagsAnalyzer" }
  ]
}

API sürümünde dizin alanlarını tanımlamak için daha yeni bir ağaç benzeri biçim kullanıma sunulmuştur 2017-11-11-Preview. Yeni biçimde, her karmaşık alanın alt alanlarının tanımlandığı bir alan koleksiyonu vardır. API sürüm 2019-05-06'da bu yeni biçim yalnızca kullanılır ve eski biçimi kullanarak dizin oluşturmaya veya güncelleştirmeye çalışmak başarısız olur. Eski biçim kullanılarak oluşturulmuş dizinleriniz varsa, API sürümü 2017-11-11-Preview 2019-05-06 kullanılarak yönetilmeden önce bunları yeni biçime güncelleştirmek için API sürümünü kullanmanız gerekir.

API sürümünü 2017-11-11-Previewkullanarak aşağıdaki adımlarla düz dizinleri yeni biçime güncelleştirebilirsiniz:

  1. Dizininizi almak için bir GET isteği gerçekleştirin. Zaten yeni biçimdeyse işiniz bitti demektir.

  2. Dizini düz biçimden yeni biçime çevirin. Bu yazma sırasında kullanılabilir örnek kod olmadığından bu görev için kod yazmanız gerekir.

  3. Dizini yeni biçime güncelleştirmek için bir PUT isteği gerçekleştirin. Dizin API'sinin mevcut dizinin fiziksel ifadesini etkileyen değişikliklere izin verilmediğinden, alanların aranabilirliği/filtrelenebilirliği gibi diğer dizin ayrıntılarını değiştirmekten kaçının.

Not

Azure portalından eski "düz" biçimle oluşturulan dizinleri yönetmek mümkün değildir. Dizinlerinizi "düz" gösterimden en erken kolaylıkta "ağaç" gösterimine yükseltin.

Kontrol düzlemi (control plane) güncellemeleri

Şunlar için geçerlidir:2014-07-31-Preview, 2015-02-28ve 2015-08-19

listQueryKeys Eski Arama Yönetimi API'sinin sürümlerinde GET isteği artık kullanım dışıdır. POST isteğini kullanmak için en son kararlı denetim düzlemi API sürümüne listQueryKeysgeçiş yapmanızı öneririz.

  1. Mevcut kodda parametresini api-version en son sürüme (2025-05-01 ) değiştirin.

  2. GET isteğini POST olarak yeniden çerçevelendir:

    POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/listQueryKeys?api-version=2025-05-01
Authorization: Bearer {{token}}

  3. Azure SDK kullanıyorsanız en son sürüme yükseltmeniz önerilir.

Sonraki adımlar

ARAMA REST API'sinin başvuru belgelerini gözden geçirin. Sorunlarla karşılaşırsanız Stack Overflow hakkında yardım isteyin veya desteğe başvurun.

Arama hizmeti REST API Başvurusu

  • Last updated on