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:
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 birsemanticConfiguration
tanım gerektirir. AsemanticConfiguration
, önceki sürümlerde yerini alırsearchFields
. 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 ayarlanmazsavectorFilterMode
, yeni varsayılan davranışı anladığınızdan veya eski davranışı korumak için postfilter olarak açıkça ayarladığınızdanvectorFilterMode
emin olun.
2023-07-01-preview sürümünden 2023-11-01 sürümüne geçiş adımları şunlardır:
Var olan tanımı almak için Dizin Al'ı çağırın.
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
algorithmConfigurations
algorithms
.algorithmConfigurations
öğesinialgorithms
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" } ] }
vektör alanı tanımlarını değiştirin ve yerine
vectorSearchConfiguration
öğesini yazınvectorSearchProfile
. 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" }
Değişiklikleri göndermek için Oluşturma veya Güncelleştirme Dizini'ni çağırın.
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
öğesinivectorQueries
olarak yeniden adlandırın.- Her vektör sorgusu için öğesini ekleyin
kind
ve olarakvector
ayarlayın. - Her vektör sorgusu için olarak yeniden adlandırın
value
vector
. - İsteğe bağlı olarak, filtre ifadeleri kullanıyorsanız ekleyin
vectorFilterMode
. 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 gibi2020-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 olarakdesc
gö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
:
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"
.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.Veri kaynağı bağlantı dizesi artık yanıtta döndürülmüyor. API sürümlerinden
2019-05-06
ve2019-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.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-version2019-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-Preview
kullanarak aşağıdaki adımlarla düz dizinleri yeni biçime güncelleştirebilirsiniz:
Dizininizi almak için bir GET isteği gerçekleştirin. Zaten yeni biçimdeyse işiniz bitti demektir.
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.
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.