Azure AI Search'te en son REST API'ye yükseltme

Veri düzlemi çağrılarını Arama REST API'sinin daha yeni sürümlerine geçirmek için bu makaleyi kullanın.

• 2023-11-01 en son kararlı sürümdür. Bu sürümde, vektör dizin oluşturma ve sorgular için anlam derecelendirmesi ve desteği genel olarak kullanılabilir.

• 2023-10-01-preview en son önizleme sürümüdür. Önizleme özellikleri yerleşik sorgu vektörleştirme, yerleşik veri öbekleme ve dizin oluşturma sırasında vektörleştirmeyi içerir (Metin Bölme becerisini ve Azure OpenAI Ekleme becerisini kullanır).

• 2023-07-01-preview , vektör desteği için ilk REST API'ydi. Artık kullanım dışıdır ve hemen 2023-11-01 veya 2023-10-01-preview sürümüne geçmeniz gerekir.

Not

REST API başvuru belgeleri artık sürümlenmiştir. Doğru içeriği almak için bir başvuru sayfası açın ve içindekiler tablosunun üzerinde bulunan seçiciyi kullanarak sürüme göre filtreleyin.

Yükseltme zamanları

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

• Kodunuz kullanımdan kaldırılmış veya kullanım dışı bırakılmış bir API sürümüne başvurur ve bir veya daha fazla hataya neden olan değişikliğe tabidir. Bu kategoriye giren API sürümleri vektörler için 2023-07-10-preview ve 2019-05-06 sürümlerini içerir.

• 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 yoksaymalıdır.

• 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.nextPageParameters Arama API'sinin Başvurusu'nda arayın).

Bağlantı bilgilerini okuyan istemci kodunda hataya neden olan değişiklik

29 Mart 2024 tarihinden itibaren geçerlidir ve 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 yanıtından anahtarları veya bağlantıları (hassas veriler) okuyan aşağı akış kodunuz varsa bu hataya neden olan bir değişikliktir.

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

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

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

Bu bölümde 2023-07-01-preview sürümünden 2023-10-01-preview sürümüne geçiş yolu açıklanmaktadır. Genel önizleme aşamasında olan vektör özelliklerini kullanmak istiyorsanız 2023-10-01-preview sürümüne geçmeniz gerekir. Önizleme özelliklerine ihtiyacınız yoksa 2023-11-01 kararlı sürümüne yükseltmenizi öneririz.

Önizleme özellikleri şunlardır:

• yerleşik metinden vektöre dizin oluşturma
• yerleşik metinden vektöre sorgular
• vektör ön filtre modu

Bu özellikler önceki API sürümlerinde mevcut olmadığından geçiş yolu yoktur. Bu özellikleri kodunuza nasıl ekleyeceğinizi öğrenmek için bkz . kod örnekleri ve izlenecek yollar.

Buna karşılık, ilk kez 2023-07-01-preview sürümünde kullanıma sunulan vektör alanı tanımları, vektör arama algoritması yapılandırması ve vektör sorgusu söz dizimi değişmiştir. Vektör alanları, algoritmalar ve vektör sorguları için 2023-10-01-preview söz dizimi, 2023-11-01 söz dizimi ile aynıdır. Bu vektör yapıları için geçiş adımları 2023-11-01'e yükseltmede açıklanmıştı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. Portal, 2023-07-01-preview vektör alanlarını algılar ve bir Geçiş düğmesi sağlar.

• Geçiş yolu 2023-07-01-preview ile 2023-10-01-preview arasıdır.
• 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ü. Yükseltmeyi tersine çeviremezsiniz. Dizin yükseltildikten sonra, dizini sorgulamak için 2023-10-01-preview veya üzerini 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 . 2023-11-01 sürümüne yükseltme.

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

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

Bu sürümde semantik derecelendirme ve vektör arama desteği için hataya neden olan değişiklikler ve davranış farklılıkları vardır.

• Anlam derecelendirmesi genel olarak 2023-11-01'de kullanılabilir. Artık özelliğini kullanmaz queryLanguage . Ayrıca bir semanticConfiguration tanım gerektirir. A semanticConfiguration , önceki sürümlerde yerini alır searchFields . Adımlar için bkz . Önizleme sürümünden geçiş.

• Vektör arama desteği, Dizin Oluşturma veya Güncelleştirme (2023-07-01-preview) bölümünde sunulmuştur. 2023-07-01-preview sürümünden yükseltme için dizindeki vektör yapılandırmasını yeniden adlandırmak ve yeniden yapılandırmak gerekir. Ayrıca vektör sorgularınızın yeniden yazılmasını da gerektirir. Vektör alanlarını, yapılandırmayı ve sorguları geçirmek için bu bölümdeki yönergeleri kullanın.

  2023-10-01-preview sürümünden 2023-11-01 sürümüne yükseltiyorsanız hataya neden olan hiçbir değişiklik yoktur, ancak bir davranış farkı vardır: vectorFilterMode varsayılan değer filtre sonrası ifadelerden filtre öncesi filtreye değiştirildi. 2023-10-01-preview kodunuz açıkça ayarlanmazsa vectorFilterMode , yeni varsayılan davranışı anladığınızdan veya eski davranışı korumak için postfilter olarak açıkça ayarladığınızdan vectorFilterMode emin olun.

2023-07-01-preview sürümünden 2023-11-01 sürümüne geçiş adımları şunlardır:

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, vektörle ilgili yapılandırmaları tek bir adla paketleyen vektör profilleri kavramını tanıtır. Ayrıca olarak yeniden adlandırılır algorithmConfigurationsalgorithms.

   • algorithmConfigurations öğesini algorithms olarak yeniden adlandırın. 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"
     }
   

   Sonra (2023-11-01):

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

   • vectors öğesini vectorQueries olarak yeniden adlandırın.
   • Her vektör sorgusu için öğesini ekleyin kindve olarak vectorayarlayın.
   • Her vektör sorgusu için olarak yeniden adlandırın valuevector.
   • İsteğe bağlı olarak, filtre ifadeleri kullanıyorsanız ekleyinvectorFilterMode. Varsayılan değer, 2023-10-01 sonrasında oluş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": (this parameter is ignored in vector search),
       "vectors": [
         {
           "value": [
               0.103,
               0.0712,
               0.0852,
               0.1547,
               0.1183
           ],
           "fields": "contentVector",
           "k": 5
         }
       ],
       "select": "title, content, category"
   }
   

   Sonra (2023-11-01):

   {
     "search": "(this parameter is ignored in vector search)",
     "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 2023-11-01 API sürümüne geçişi tamamlar.

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

Bu sürümde bir hataya neden olan değişiklik ve çeşitli davranış 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 AI Search REST API'leri aracılığıyla bir bilgi deposu oluşturulur ancak Azure Depolama'de bulunur.

Hataya neden olan değişiklik

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

• Filtre ifadelerindeki tüm Edm.Date değişmez değerlerin (yıl-ay-gün gibi 2020-12-12) biçimine uyması Edm.DateTimeOffset gerekir: 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 ise önce null değerler, sıralama ise son olarak descgörüntülenir. 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 tür başlığı özelliğidir.
• Karmaşık türler , arama dizinindeki yapılandırılmış nesne verileri için yerel destek sağlar.
• Azure Blob dizin oluşturmanın bir parçası olan JsonLines ayrıştırma modları, JSON varlığı başına yeni bir satırla ayrılmış bir arama belgesi oluşturur.
• Yapay zeka zenginleştirme , Azure yapay zeka hizmetlerinin yapay zeka zenginleştirme altyapılarını kullanan dizin oluşturma sağlar.

Hataya neden olan değişiklikler

Önceki bir API sürümüne göre yazılan kod, aşağıdaki işlevleri içeriyorsa ve sonrasında sonlanır 2019-05-06 :

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

2. Dizin oluşturucu hata işleme özelliğine status başvurular içeriyorsa, bunu kaldırmanız gerekir. Yararlı bilgiler sağlamadığından hata yanıtından durumu kaldırdık.

3. Veri kaynağı bağlantı dizesi 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ı dizesi döndürmez. Önceki API sürümlerinde POST kullanılarak oluşturulan veri kaynakları için Azure AI Search 201 döndürdü ve ardından düz metin olarak 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) işlevidir. 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 eklendi. 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 AI Search 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çimiyle oluşturulan dizinleri yönetmek mümkün değildir. Lütfen dizinlerinizi "düz" gösterimden en erken kolaylıkta "ağaç" gösterimine yükseltin.

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