Upgrade na nejnovější rozhraní REST API ve službě Azure AI Search

Článek
05/06/2024

Tento článek slouží k migraci volání roviny dat do novějších verzí rozhraní REST API služby Search.

2023-11-01 je nejnovější stabilní verze. Sémantické řazení a podpora indexování vektorů a dotazů jsou obecně dostupné v této verzi.
2023-10-01-preview je nejnovější verze Preview. Mezi funkce ve verzi Preview patří integrovaná vektorizace dotazů, předdefinované bloky dat a vektorizace během indexování (používá dovednost Rozdělení textu a dovednosti Vkládání v Azure OpenAI ).
2023-07-01-preview byl první rozhraní REST API pro podporu vektorů. Je teď zastaralý a měli byste okamžitě migrovat na verzi 2023-11-01 nebo 2023-10-01-preview .

Poznámka:

Referenční dokumenty k rozhraní REST API jsou teď verzí. Pokud chcete získat správný obsah, otevřete referenční stránku a potom pomocí selektoru umístěného nad obsahem vyfiltrujte podle verze.

Kdy provést upgrade

Azure AI Search přeruší zpětnou kompatibilitu jako poslední možnost. Upgrade je nezbytný v následujících případech:

Váš kód odkazuje na vyřazenou nebo zastaralou verzi rozhraní API a podléhá jedné nebo několika zásadním změnám. Verze rozhraní API, které spadají do této kategorie, zahrnují vektory 2023-07-10-preview a 2019-05-06.
Váš kód selže, když se v odpovědi rozhraní API vrátí nerozpoznané vlastnosti. Osvědčeným postupem je, že aplikace by měla ignorovat vlastnosti, kterým nerozumí.
Váš kód zachová požadavky rozhraní API a pokusí se je znovu odeslat do nové verze rozhraní API. K tomu může dojít například v případě, že vaše aplikace zachová pokračovací tokeny vrácené z vyhledávacího rozhraní API (další informace najdete @search.nextPageParameters v referenčních informacích k rozhraní API služby Search).

Zásadní změna kódu klienta, který čte informace o připojení

Platnost od 29. března 2024 a platí pro všechna podporovaná rozhraní REST API:

Sada dovedností GET, GET Index a GET Indexer už v odpovědi nevrací klíče ani vlastnosti připojení. Jedná se o zásadní změnu, pokud máte podřízený kód, který čte klíče nebo připojení (citlivá data) z odpovědi GET.
Pokud potřebujete načíst klíče rozhraní API pro správu nebo dotazování na vyhledávací službu, použijte rozhraní REST API pro správu.
Pokud potřebujete načíst připojovací řetězec jiného prostředku Azure, jako je Azure Storage nebo Azure Cosmos DB, použijte rozhraní API tohoto prostředku a publikované doprovodné materiály k získání informací.

Upgrade na verzi 2023-10-01-preview

Tato část vysvětluje cestu migrace z verze 2023-07-01-preview na verzi 2023-10-01-preview. Pokud chcete používat vektorové funkce, které jsou stále ve verzi Public Preview, měli byste migrovat na verzi 2023-10-01-Preview. Pokud funkce Preview nepotřebujete, doporučujeme upgradovat na stabilní verzi 2023–11.01. 2023.

Mezi funkce ve verzi Preview patří:

Vzhledem k tomu, že tyto funkce v předchozích verzích rozhraní API neexistovaly, neexistuje žádná cesta migrace. Informace o tom, jak tyto funkce přidat do kódu, najdete v ukázkách kódu a návodech.

Naproti tomu definice vektorových polí, konfigurace algoritmu vektorového vyhledávání a syntaxe vektorového dotazu, které byly poprvé zavedeny v roce 2023-07-01-preview, se změnily. Syntaxe 2023-10-01-preview pro vektorová pole, algoritmy a vektorové dotazy je identická se syntaxí 2023-11-01. Kroky migrace pro tyto vektorové konstrukce jsou vysvětleny v upgradu na verzi 2023-11-01.

Upgrade portálu pro vektorové indexy

Azure Portal podporuje cestu upgradu jedním kliknutím pro indexy verze 2023-07-01-preview. Portál zjistí vektorová pole verze 2023-07-01-preview a zobrazí tlačítko Migrovat .

Cesta migrace je z verze 2023-07-01-preview na verzi 2023-10-01-preview.
Aktualizace jsou omezené na definice vektorových polí a konfigurace algoritmů vektorové vyhledávání.
Aktualizace jsou jednosměrné. Upgrade nejde vrátit zpět. Po upgradu indexu musíte k dotazování na index použít verzi 2023-10-01-preview nebo novější.

Pro upgrade syntaxe vektorových dotazů neexistuje žádná migrace portálu. Informace o změnách syntaxe dotazů najdete v upgradu na verzi 2023-11-01 .

Než vyberete Možnost Migrovat, vyberte Upravit JSON a nejprve zkontrolujte aktualizované schéma. Měli byste najít schéma, které odpovídá změnám popsaným v upgradu na verzi 2023-11-01. Migrace portálu zpracovává indexy pouze s konfigurací jednoho algoritmu vektorového vyhledávání. Vytvoří výchozí profil, který se mapuje na algoritmus vektorového vyhledávání ve verzi 2023-07-01-preview. Indexy s konfigurací více vektorových vyhledávání vyžadují ruční migraci.

Upgrade na 11. 11. 2023

Tato verze obsahuje zásadní změny a rozdíly v chování pro sémantické řazení a podporu hledání vektorů.

Sémantické hodnocení je obecně dostupné v 11.11.2023. Vlastnost už nepoužívá queryLanguage . Vyžaduje také definici semanticConfiguration . searchFields Nahradí semanticConfiguration se v předchozích verzích. Postup najdete v tématu Migrace z verze Preview.
Podpora vektorového vyhledávání byla zavedena ve verzi Create or Update Index (2023-07-01-preview). Upgrade z verze 2023-07-01-preview vyžaduje přejmenování a restrukturalizaci konfigurace vektoru v indexu. Vyžaduje také přepsání vektorových dotazů. Pomocí pokynů v této části můžete migrovat vektorová pole, konfiguraci a dotazy.

Pokud upgradujete z verze 2023-10-01-preview na verzi 2023-11-01, neexistují žádné zásadní změny, ale existuje jeden rozdíl chování: vectorFilterMode výchozí změna z postfilteru na předfiltr pro výrazy filtru. Pokud váš kód verze 2023-10-01-preview explicitně nenastaví vectorFilterMode , ujistěte se, že rozumíte novému výchozímu chování nebo explicitně nastavíte vectorFilterMode postfilter pro zachování starého chování.

Tady je postup migrace z verze 2023-07-01-preview na verzi 2023-11-01:

Volání získat index pro načtení existující definice.

Upravte konfiguraci vektorového vyhledávání. 2023-11-01 zavádí koncept vektorových profilů , které sbalují konfigurace související s vektory pod jedním názvem. Přejmenuje algorithmConfigurations se také na algorithms.

Přejmenujte algorithmConfigurations na algorithms. Jedná se pouze o přejmenování pole. Obsah je zpětně kompatibilní. To znamená, že můžete použít stávající parametry konfigurace HNSW.
Přidejte profiles, zadejte název a konfiguraci algoritmu pro každý z nich.

Před migrací (2023-07-01-preview):

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

Po migraci (2023-11-01):

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

Upravte definice vektorových polí a nahraďte vectorSearchConfiguration ho .vectorSearchProfile Ujistěte se, že se název profilu přeloží na novou definici vektorového profilu, a ne na název konfigurace algoritmu. Vlastnosti jiných vektorových polí zůstávají beze změny. Nemůžou být například filtrovatelné, řaditelné ani fasetové, ani používat analyzátory nebo normalizátory nebo mapy synonym.

Před (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"
  }

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

Voláním příkazu Vytvořit nebo aktualizovat index publikujte změny.

Upravte funkci POST vyhledávání a změňte syntaxi dotazu. Tato změna rozhraní API umožňuje podporu typů dotazů polymorfních vektorů.

Přejmenujte vectors na vectorQueries.
Pro každý vektorový dotaz přidejte kind, nastavte ho na vector.
Pro každý vektorový dotaz přejmenujte value na vector.
Volitelně můžete přidat vectorFilterMode , pokud používáte výrazy filtru. Výchozí filtr je pro indexy vytvořené po 10. 10. 2023. Indexy vytvořené před tímto datem podporují pouze postfilter bez ohledu na to, jak nastavíte režim filtru.

Před (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"
}

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

Tento postup dokončí migraci na verzi rozhraní API z 11. 11. 2023.

Upgrade na 30. 6. 2020

V této verzi je jedna zásadní změna a několik rozdílů v chování. Mezi obecně dostupné funkce patří:

Úložiště znalostí, trvalé úložiště rozšířeného obsahu vytvořeného prostřednictvím sad dovedností, vytvořené pro podřízenou analýzu a zpracování prostřednictvím jiných aplikací. Úložiště znalostí se vytváří prostřednictvím rozhraní REST API služby Azure AI Search, ale nachází se ve službě Azure Storage.

Změna způsobující chybu

Kód napsaný proti dřívějším verzím rozhraní API se přeruší 2020-06-30 , pokud kód obsahuje následující funkce:

Všechny Edm.Date literály (datum složené z rok-měsíc-den, například 2020-12-12) ve výrazech filtru musí odpovídat Edm.DateTimeOffset formátu: 2020-12-12T00:00:00Z. Tato změna byla nezbytná ke zpracování chybných nebo neočekávaných výsledků dotazu kvůli rozdílům v časovém pásmu.

Změny chování

Algoritmus řazení BM25 nahrazuje předchozí algoritmus řazení novější technologií. Služby vytvořené po roce 2019 tento algoritmus používají automaticky. U starších služeb je nutné nastavit parametry tak, aby používaly nový algoritmus.
Seřazené výsledky pro hodnoty null se v této verzi změnily, přičemž hodnoty null se zobrazují jako první, pokud je asc řazení a poslední, pokud je descřazení . Pokud jste napsali kód pro zpracování řazení hodnot null, mějte na paměti tuto změnu.

Upgrade na 06. 5. 2019

Mezi obecně dostupné funkce v této verzi rozhraní API patří:

Automatické dokončování je funkce typeahead, která dokončí částečně zadaný vstup termínu.
Komplexní typy poskytují nativní podporu strukturovaných dat objektů v indexu vyhledávání.
Režimy analýzy JsonLines, součást indexování objektů blob v Azure, vytvoří jeden vyhledávací dokument pro každou entitu JSON oddělenou novým řádekem.
Rozšiřování AI poskytuje indexování, které využívá moduly rozšiřování AI služeb Azure AI.

Změny způsobující chyby

Kód napsaný proti dřívější verzi rozhraní API se přeruší 2019-05-06 a později, pokud obsahuje následující funkce:

Vlastnost type pro Azure Cosmos DB U indexerů, které cílí na zdroj dat rozhraní API Služby Cosmos DB for NoSQL, přejděte "type": "documentdb" na "type": "cosmosdb".
Pokud zpracování chyb indexeru obsahuje odkazy na status vlastnost, měli byste ji odebrat. Z odpovědi na chybu jsme odebrali stav, protože nezadávalo užitečné informace.
V odpovědi se už nevracejí připojovací řetězec zdroje dat. Z verzí 2019-05-06 rozhraní API a 2019-05-06-Preview dále už rozhraní API zdroje dat nevrací připojovací řetězec v reakci na jakoukoli operaci REST. V předchozích verzích rozhraní API vrátila služba Azure AI Search pro zdroje dat vytvořené pomocí post 201 odpověď OData, která obsahovala připojovací řetězec ve formátu prostého textu.
Kognitivní dovednost Rozpoznávání entit je vyřazena. Pokud jste ve svém kódu volali dovednost Rozpoznávání názvů entit, volání selže. Náhradní funkce jsou dovednosti pro rozpoznávání entit (V3). Pokud chcete migrovat na podporovanou dovednost, postupujte podle doporučení v zastaralých dovednostech .

Upgrade složitých typů

Verze 2019-05-06 rozhraní API přidala formální podporu pro komplexní typy. Pokud váš kód implementoval předchozí doporučení pro ekvivalenci komplexního typu v roce 2017–11-11-Preview nebo 2016-09-01-Preview, jsou k dispozici některé nové a změněné limity počínaje verzí 2019-05-06 , o kterých je potřeba vědět:

Omezení hloubky dílčích polí a počtu složitých kolekcí na index byly nižší. Pokud jste vytvořili indexy, které tyto limity překračují pomocí verzí API ve verzi Preview, všechny pokusy o aktualizaci nebo opětovné vytvoření pomocí verze 2019-05-06 rozhraní API selžou. Pokud v této situaci zjistíte sami sebe, musíte přepracovat schéma tak, aby vyhovovalo novým limitům, a pak znovu sestavit index.
Pro počet prvků složitých kolekcí v jednotlivých dokumentech začíná nový limit verze rozhraní API 2019-05-06 . Pokud jste vytvořili indexy s dokumenty, které tyto limity překračují pomocí verzí api ve verzi Preview, všechny pokusy o přeindexování těchto dat pomocí verze API 2019-05-06 selžou. Pokud v této situaci zjistíte sami sebe, musíte před opětovnou indexováním dat snížit počet složitých prvků kolekce na dokument.

Další informace najdete v tématu Omezení služeb pro Azure AI Search.

Postup upgradu staré struktury komplexního typu

Pokud váš kód používá složité typy s jednou ze starších verzí rozhraní API ve verzi Preview, můžete použít formát definice indexu, který vypadá takto:

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

Ve verzi 2017-11-11-Previewrozhraní API byl zaveden novější formát podobný stromové struktuře pro definování polí indexu. V novém formátu má každé komplexní pole kolekci polí, ve které jsou definovány jeho dílčí pole. V rozhraní API verze 2019-05-06 se tento nový formát používá výhradně a pokus o vytvoření nebo aktualizaci indexu pomocí starého formátu selže. Pokud máte indexy vytvořené ve starém formátu, budete je muset použít k aktualizaci verze rozhraní API 2017-11-11-Preview na nový formát, aby bylo možné je spravovat pomocí rozhraní API verze 2019-05-06.

Ploché indexy můžete aktualizovat do nového formátu pomocí následujících kroků pomocí verze 2017-11-11-Previewrozhraní API:

Proveďte požadavek GET pro načtení indexu. Pokud už je v novém formátu, máte hotovo.
Přeloží index z plochého formátu do nového formátu. Pro tento úkol musíte napsat kód, protože v době psaní tohoto textu není k dispozici žádný vzorový kód.
Proveďte požadavek PUT na aktualizaci indexu na nový formát. Vyhněte se změnám jiných podrobností indexu, jako jsou prohledávatelnost a filtrování polí, protože rozhraní API pro aktualizaci indexu nepovoluje změny, které ovlivňují fyzický výraz existujícího indexu.