Sdílet prostřednictvím

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

  • Článek

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

Pokyny k upgradu se zaměřují na změny kódu, které vám pomůžou provést zásadní změny z předchozích verzí, aby stávající kód běžel stejně jako předtím, ale na novější verzi rozhraní API. Jakmile je váš kód v pracovním pořadí, můžete se rozhodnout, jestli se mají používat novější funkce. Další informace o funkcích ve verzi Preview najdete v ukázkách vektorových kódů a novinkách.

Doporučujeme postupně upgradovat verze rozhraní API, projít si jednotlivé verze, dokud se nedostanete na nejnovější verzi.

2023-07-01-preview byla první rozhraní REST API pro podporu vektorů. Tuto verzi rozhraní API nepoužívejte. Už je zastaralý a měli byste migrovat na stabilní nebo novější rozhraní REST API verze Preview okamžitě.

Poznámka:

Referenční dokumenty k rozhraní REST API jsou teď verzí. Pro obsah specifický pro konkrétní verzi otevřete referenční stránku a pak pomocí selektoru umístěného vpravo nad obsahem vyberte svou verzi.

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 nepodporovanou verzi rozhraní API a podléhá jedné nebo více zásadním změnám. Pokud cílíte 2023-07-10-preview na vektory, sémantické řazení a 2019-05-06 zastaralé dovednosti a alternativní řešení, 2020-06-01-preview musíte řešit zásadní změny.

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

Změna způsobující chybu pro sémantické řazení

Sémantické hodnocení je obecně dostupné v 2023-11-01. Tady jsou zásadní změny sémantického hodnocení z předchozích verzí:

  • Ve všech verzích po 2020-06-01-preview: semanticConfiguration nahrazuje searchFields jako mechanismus pro určení polí, která se mají použít pro hodnocení L2.

  • U všech verzí rozhraní API se aktualizace aktualizují 14. července 2023 na sémantické modely hostované Microsoftem, které jsou nezávislé na sémantickém řazení jazyka a efektivně vyřadí queryLanguage z provozu vlastnost. V kódu není žádná změna způsobující chybu, ale vlastnost se ignoruje.

Přečtěte si téma Migrace z verze Preview a přechod kódu na použití semanticConfiguration.

Upgrade na verzi 2024-05-01-preview

2024-05-01-preview přidá index OneLake, podporu binárních vektorů a podporu pro další vložené modely.

Pokud upgradujete z 2024-03-01-preview, dovednost AzureOpenAIEmbedding teď vyžaduje vlastnost názvu modelu a dimenze.

  1. Vyhledejte v základu kódu odkazy na AzureOpenAIEmbedding .

  2. Nastavte modelName na text-embedding-ada-002 a nastavte dimensions na 1536.

Upgrade na verzi 2024-03-01-preview

2024-03-01-preview přidává úzké datové typy, skalární kvantování a možnosti úložiště vektorů.

Pokud provádíte upgrade z 2023-10-01-preview, žádné zásadní změny. Existuje však jeden rozdíl v chování: u 2023-11-01 novějších náhledů vectorFilterMode se výchozí změna z postfilteru na předfiltr pro výrazy filtru.

  1. Vyhledejte odkazy v vectorFilterMode základu kódu.

  2. Pokud je vlastnost explicitně nastavená, nevyžaduje se žádná akce. Pokud jste použili výchozí nastavení, mějte na paměti, že nové výchozí chování je filtrovat před spuštěním dotazu. Pokud chcete filtrovat po dotazu, explicitně nastavte vectorFilterMode postfilter, aby se zachovalo staré chování.

Upgrade na verzi 2023-10-01-preview

2023-10-01-preview byla první verze Preview pro přidání předdefinovaných bloků dat a vektorizace během indexování a předdefinované vektorizace dotazů. Podporuje také indexování vektorů a dotazy z předchozí verze.

Pokud upgradujete z předchozí verze, další část obsahuje kroky.

Upgrade z verze 2023-07-01-preview

Tuto verzi rozhraní API nepoužívejte. Implementuje syntaxi vektorového dotazu, která není kompatibilní s žádnou novější verzí rozhraní API.

2023-07-01-preview je nyní zastaralý, takže byste neměli založit nový kód na této verzi, ani byste neměli upgradovat na tuto verzi za žádných okolností. Tato část vysvětluje cestu migrace z 2023-07-01-preview jakékoli novější verze rozhraní API.

Upgrade portálu pro vektorové indexy

Azure Portal podporuje cestu upgradu jedním kliknutím pro 2023-07-01-preview indexy. Detekuje vektorová pole a poskytuje tlačítko Migrovat .

  • Cesta migrace je z 2023-07-01-preview do 2024-05-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 je nutné k dotazování indexu použít 2024-05-01-preview nebo později.

Pro upgrade syntaxe vektorových dotazů neexistuje žádná migrace portálu. Podívejte se na upgrady kódu pro změny syntaxe dotazů.

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 části upgrade kódu. 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 2023-07-01-preview vyhledávání. Indexy s konfigurací více vektorových vyhledávání vyžadují ruční migraci.

Upgrade kódu pro vektorové indexy a dotazy

Podpora vektorového vyhledávání byla zavedena ve verzi Create or Update Index (2023-07-01-preview).

Upgrade z 2023-07-01-preview jakékoli novější stabilní verze nebo verze Preview vyžaduje:

  • Přejmenování a restrukturalizace konfigurace vektoru v indexu
  • Přepsání vektorových dotazů

Pokyny v této části použijte k migraci vektorových polí, konfigurace a dotazů z 2023-07-01-preview.

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

  2. Upravte konfiguraci vektorového vyhledávání. 2023-11-01 a novější verze představují koncept vektorových profilů , které sbalují konfigurace související s vektory pod jedním názvem. Novější verze se také přejmenová na algorithmConfigurationsalgorithms.

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

  3. 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"
  }

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

  5. 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í hodnota je předfiltrována pro indexy vytvořené po 2023-10-01. 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 2023-11-01 stabilní verzi rozhraní API nebo novější verze rozhraní API ve verzi Preview.

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:

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

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

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

  4. 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-version 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:

  1. Proveďte požadavek GET pro načtení indexu. Pokud už je v novém formátu, máte hotovo.

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

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

Poznámka:

Na webu Azure Portal není možné spravovat indexy vytvořené pomocí starého "plochého" formátu. Upgradujte své indexy z "ploché" reprezentace na reprezentaci "strom" v nejbližším pohodlí.

Další kroky

Projděte si referenční dokumentaci k rozhraní REST API služby Search. Pokud narazíte na problémy, požádejte nás o pomoc na Stack Overflow nebo se obraťte na podporu.

Referenční informace k rozhraní REST API Search