Frissítés a legújabb REST API-ra az Azure AI Searchben

Cikk
05/21/2024

Ebben a cikkben adatsík-hívásokat migrálhat a Search REST API-k újabb verzióiba.

A 2023-11-01 a legújabb stabil verzió. A vektorindexelés és lekérdezések szemantikai rangsorolása és támogatása ebben a verzióban általánosan elérhető.

Ha a 2023-10-01 előzetes verzióról 2023-11-01-re frissít, nincsenek kompatibilitástörő változások, de van egy viselkedésbeli különbség: az vectorFilterMode alapértelmezett változás a postfilterről előszűrőre változott a szűrőkifejezések esetében. Ha a 2023-10-01 előzetes verziójú kód nem áll be vectorFilterMode explicit módon, győződjön meg arról, hogy ismeri az új alapértelmezett viselkedést, vagy explicit módon postfilterre állítja vectorFilterMode a régi viselkedés megőrzéséhez.
A 2024-05-01-preview az API legújabb verziója. Bináris adattípust ad hozzá a vektormezőkhöz, relevanciatulajdonságokat a jobb keresési eredményekhez, OneLake-fájlok indexelője, több vektorizáló és további beágyazási képességek. Az AzureOpenAIEmbedding képesség frissül a belefoglalásra dimensions és modelName a tulajdonságokra. Most már csak az előzetes verzió és az előző két előzetes verzió modelName kompatibilitási hibája szükséges.
A 2024-03-01 előzetes verzió új adattípusokat és tulajdonságokat ad hozzá a tömörítéshez, de egyébként teljesen visszamenőlegesen kompatibilis a 2023-10-01 előzetes verzióval. Az előzetes verzió használatához nincsenek frissítési utasítások.
A 2023-10-01 előzetes verzió az első előzetes verzió, amely beépített lekérdezésvektorizálást, beépített adatrészletezést és vektorizálást adott hozzá az indexelés során (a Szöveg felosztása és az Azure OpenAI beágyazási képességet használja). Kompatibilitástörő változásokat vezet be a vektorkonfigurációban az indexben és a vektoros lekérdezésekben.
A 2023-07-01 előzetes verzió volt az első REST API a vektortámogatáshoz. Most már elavult, és azonnal át kell telepítenie a 2023-11-01-hez , vagy az újabb előzetes REST API-k bármelyikére.

Feljegyzés

A REST API referencia-dokumentumai már verziószámozottak. A megfelelő tartalom beszerzéséhez nyisson meg egy referencialapot, majd szűrjön verzió szerint a tartalomjegyzék felett található választóval.

Mikor kell frissíteni?

Az Azure AI Search végső megoldásként megszakítja a visszamenőleges kompatibilitást. Frissítésre akkor van szükség, ha:

A kód egy kivezetett vagy elavult API-verzióra hivatkozik, és egy vagy több kompatibilitástörő változásnak van alávetve. Az ebbe a kategóriába tartozó API-verziók közé tartozik a vektorok 2023-07-10-es előzetes verziója , valamint a 2019-05-06-os verzió az elavult készségekért és kerülő megoldásokért.
A kód meghiúsul, ha a rendszer nem felismert tulajdonságokat ad vissza egy API-válaszban. Ajánlott eljárásként az alkalmazásnak figyelmen kívül kell hagynia azokat a tulajdonságokat, amelyeket nem ért.
A kód megőrzi az API-kéréseket, és megpróbálja újraküldni őket az új API-verzióra. Ez például akkor fordulhat elő, ha az alkalmazás megőrzi a Keresési API-ból visszaadott folytatási jogkivonatokat (további információt @search.nextPageParameters a Keresési API-referencia tartalmaz).

Kompatibilitástörő változás a kapcsolati adatokat beolvasó ügyfélkód esetében

2024. március 29-én lép hatályba, és az összes támogatott REST API-ra vonatkozik:

A GET Skillset, a GET Index és a GET Indexer már nem ad vissza kulcsokat vagy kapcsolattulajdonságokat a válaszban. Ez egy kompatibilitástörő változás, ha olyan alsóbb rétegbeli kóddal rendelkezik, amely kulcsokat vagy kapcsolatokat (bizalmas adatokat) olvas be a GET-válaszból.
Ha le kell kérnie a keresési szolgáltatás rendszergazdai vagy lekérdezési API-kulcsait, használja a Felügyeleti REST API-kat.
Ha egy másik Azure-erőforrás, például az Azure Storage vagy az Azure Cosmos DB kapcsolati sztring kell lekérnie, használja az erőforrás API-jait és a közzétett útmutatást az információk beszerzéséhez.

Kompatibilitástörő változás a szemantikai rangsorolásban

Szemantikai rangsor általánosan elérhető 2023-11-01. A korábbi REST API-verziókkal ellentétben már nem használja a tulajdonságot queryLanguage . Emellett olyan definíciót semanticConfiguration is igényel, amely felülírja a searchFields korábbi verziók korábbi verzióit. Lásd: Migrálás az előzetes verzióról az általánosan elérhető verzióra vagy egy újabb verzióra való áttéréshez.

Frissítés a 2023.07.01-i előzetes verzióról

Ez a szakasz a 2023-07-01-es verziójú migrálási útvonalat ismerteti bármely újabb API-verzióra. A 2023-07-01-es előzetes verziótól kezdve számos kompatibilitástörő változás történt az újabb verziókra, de csak kisebb kompatibilitási problémák vannak az újabb API-verziók között.

A frissítési utasítások olyan kódmódosításokra összpontosítanak, amelyek átvezetik a korábbi verziók kompatibilitástörő módosításain, így a meglévő kód ugyanúgy fut, mint korábban, de az újabb API-verzión. Ha a kód működése rendben van, eldöntheti, hogy újabb funkciókat vezet-e be. Az előzetes verziójú funkciókkal kapcsolatos további információkért tekintse meg a vektorkódmintákat és az újdonságokat.

Portálfrissítés vektorindexekhez

Az Azure Portal támogatja a 2023-07-01 előzetes verziójú indexek egykattintásos frissítési útvonalát. A portál észleli a 2023-07-01 előzetes verziójú vektormezőket, és biztosít egy Migrálás gombot.

A migrálási útvonal 2023.07.01-előzetes verzióról a 2023-10-01 előzetes verzióra mutat.
Frissítések a vektormező-definíciókra és a vektorkeresési algoritmus konfigurációira korlátozódnak.
Frissítések egyirányúak. A frissítés nem vonható vissza. Az index frissítése után a 2023-10-01-preview vagy újabb verziót kell használnia az index lekérdezéséhez.

A vektoros lekérdezés szintaxisának frissítéséhez nincs portálmigrálás. A lekérdezésszintaxis változásait a kódfrissítések között tekintheti meg.

A Migrálás kiválasztása előtt válassza a JSON szerkesztése lehetőséget a frissített séma áttekintéséhez. Olyan sémát kell találnia, amely megfelel a kódfrissítési szakaszban leírt módosításoknak. A portálmigrálás csak egy vektorkeresési algoritmus konfigurációjával kezeli az indexeket. Létrehoz egy alapértelmezett profilt, amely megfelel a 2023-07-01-preview vektorkeresési algoritmusnak. A több vektoros keresési konfigurációval rendelkező indexek manuális migrálást igényelnek.

Vektorindexek és lekérdezések kódfrissítése

A vektorkeresés támogatása a Létrehozás vagy frissítés indexben (2023-07-01-preview) jelent meg.

A 2023-07-01-es verzióról bármely újabb stabil vagy előzetes verzióra való frissítéshez a következőre van szükség:

A vektorkonfiguráció átnevezése és átszervezése az indexben
Vektoros lekérdezések újraírása

Az ebben a szakaszban található utasításokat követve migrálhatja a vektormezőket, a konfigurációt és a lekérdezéseket a 2023-07-01 előzetes verzióból.

Hívja meg az Index lekérése parancsot a meglévő definíció lekéréséhez.

Módosítsa a vektorkeresés konfigurációját. A 2023-11-01-01-s és újabb verziók bemutatják a vektorprofilok fogalmát, amelyek egy név alatt kötik össze a vektorokkal kapcsolatos konfigurációkat. Az újabb verziók is átnevezve algorithmConfigurations lesznek.algorithms

Nevezze át algorithmConfigurations erre: algorithms. Ez csak a tömb átnevezése. A tartalom visszafelé kompatibilis. Ez azt jelenti, hogy a meglévő HNSW konfigurációs paraméterek használhatók.
Adjon hozzá profilesegy nevet és egy algoritmuskonfigurációt mindegyikhez.

Migrálás előtt (2023-07-01-preview):

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

Migrálás után (2023-11-01):

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

Módosítsa a vektormező-definíciókat, és cserélje le vectorSearchConfiguration a következőre vectorSearchProfile: . Győződjön meg arról, hogy a profilnév egy új vektorprofil-definícióra lesz feloldva, nem pedig az algoritmus konfigurációs nevére. A vektormező egyéb tulajdonságai változatlanok maradnak. Nem lehet például szűrhető, rendezhető vagy facetable, és nem használhat elemzőket, normalizálókat vagy szinonimatérképeket.

Előtte (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"
  }

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

A módosítások közzétételéhez hívja meg az Index létrehozása vagy frissítése parancsot.
Módosítsa a Search POST függvényt a lekérdezés szintaxisának módosításához. Ez az API-módosítás lehetővé teszi a polimorf vektoros lekérdezéstípusok támogatását.
- Nevezze át vectors erre: vectorQueries.
- Minden vektoros lekérdezéshez adja hozzá kind, és állítsa be a következőre vector: .
- Minden vektoros lekérdezéshez nevezze át value a következőt vector: .
- Ha szűrőkifejezéseket használ, adja hozzávectorFilterMode. Az alapértelmezett előszűrő a 2023.10.01. után létrehozott indexekhez. Az adott dátum előtt létrehozott indexek csak a szűrő mód beállításától függetlenül támogatják a postfiltert.
Előtte (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"
}
```
After (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"
}
```

Ezek a lépések befejezik a migrálást a 2023-11-01-es stabil API-verzióra vagy újabb előzetes API-verziókra.

Frissítés 2020.06.30-ra

Ebben a verzióban egy kompatibilitástörő változás és számos viselkedésbeli különbség van. Általánosan elérhető funkciók:

Tudástár, a készségkészleteken keresztül létrehozott gazdagított tartalom állandó tárolása, amelyet az alsóbb rétegbeli elemzéshez és más alkalmazásokon keresztüli feldolgozáshoz hoztak létre. A tudástár az Azure AI Search REST API-kkal jön létre, de az Azure Storage-ban található.

Kompatibilitástörő változás

A korábbi API-verziókra írt kód a 2020-06-30 következő funkciókat tartalmazza:

A Edm.Date szűrőkifejezésekben szereplő konstansoknak (például 2020-12-12egy év-hónap napból álló dátumnak) a Edm.DateTimeOffset következő formátumot kell követnie: 2020-12-12T00:00:00Z. Ez a módosítás szükséges volt a hibás vagy váratlan lekérdezési eredmények kezeléséhez az időzónák eltérései miatt.

Viselkedésbeli változások

A BM25 rangsorolási algoritmus az előző rangsorolási algoritmust újabb technológiára cseréli. A 2019 után létrehozott szolgáltatások automatikusan használják ezt az algoritmust. Régebbi szolgáltatások esetén paramétereket kell beállítania az új algoritmus használatához.
A null értékek rendezett eredményei megváltoztak ebben a verzióban, és a null értékek jelennek meg először, ha a rendezés és asc az utolsó, ha a rendezés.desc Ha a null értékek rendezésének kezelésére kódot írt, vegye figyelembe ezt a változást.

Frissítés 2019.05.06-ra

Az API-verzióban általánosan elérhetővé vált funkciók a következők:

Az automatikus kiegészítés egy typeahead funkció, amely egy részben megadott kifejezésbevitelt hajt végre.
Az összetett típusok natív támogatást nyújtanak a strukturált objektumadatokhoz a keresési indexben.
Az Azure Blob-indexelés részét képező JsonLines-elemzési módok JSON-entitásonként egy keresési dokumentumot hoznak létre, amelyet egy új vonal választ el egymástól.
Az AI-bővítés olyan indexelést biztosít, amely az Azure AI-szolgáltatások AI-dúsítási motorjait használja.

Kompatibilitástörő változások

Egy korábbi API-verzióra írt kód be- és letörik 2019-05-06 , ha az a következő funkciókat tartalmazza:

Írja be az Azure Cosmos DB tulajdonságát. Az Azure Cosmos DB for NoSQL API-adatforrást megcélzó indexelők esetében váltson a "type": "documentdb" következőre"type": "cosmosdb": .
Ha az indexelő hibakezelése hivatkozik a status tulajdonságra, távolítsa el. Eltávolítottuk az állapotot a hibaválaszból, mert nem adott meg hasznos információkat.
Az adatforrás kapcsolati sztring a válasz már nem adja vissza. Az API-verzióktól 2019-05-062019-05-06-Preview kezdve az adatforrás API már nem ad vissza kapcsolati sztring a REST-műveletek válaszában. A korábbi API-verziókban a POST használatával létrehozott adatforrások esetében az Azure AI Search 201-et adott vissza, majd az OData-választ, amely egyszerű szövegben tartalmazta a kapcsolati sztring.
A nevesített entitásfelismerési kognitív képesség megszűnik. Ha a kódban a Név entitásfelismerési képességet hívta meg, a hívás sikertelen lesz. A helyettesítő funkció az Entity Recognition Skill (V3). Kövesse az elavult készségekre vonatkozó javaslatokat a támogatott készségekre való migráláshoz.

Összetett típusok frissítése

Az API-verzió 2019-05-06 formális támogatást adott az összetett típusokhoz. Ha a kód a 2017-11-11-Preview vagy a 2016-09-01-Preview verzióban implementálta az összetett típusú egyenértékűségre vonatkozó korábbi javaslatokat, néhány új és módosított korlátot 2019-05-06 kell figyelembe vennie:

Az almezők mélységére és az indexenkénti összetett gyűjtemények számára vonatkozó korlátok csökkentek. Ha olyan indexeket hozott létre, amelyek túllépik ezeket a korlátokat az előzetes verziójú API-verziók használatával, az API-verzióval 2019-05-06 való frissítésre vagy újbóli létrehozására tett kísérletek sikertelenek lesznek. Ha ebben a helyzetben találja magát, újra kell terveznie a sémát, hogy megfeleljen az új korlátoknak, majd újra kell építenie az indexet.
Az API-verzió 2019-05-06 új korlátot szab a dokumentumonkénti összetett gyűjtemények elemeinek számával kapcsolatban. Ha az előzetes verziójú api-verziók használatával olyan dokumentumokkal hozott létre indexeket, amelyek túllépik ezeket a korlátokat, az api-verzióval 2019-05-06 végzett újraindexelés sikertelen lesz. Ha ebben a helyzetben találja magát, az adatok újraindexelése előtt csökkentenie kell a dokumentumonkénti összetett gyűjteményelemek számát.

További információkért tekintse meg az Azure AI Search szolgáltatáskorlátait.

Régi komplex típusú struktúra frissítése

Ha a kód összetett típusokat használ az egyik régebbi előzetes verziójú API-verzióval, előfordulhat, hogy az alábbihoz hasonló indexdefiníciós formátumot használ:

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

Az API-verzióban 2017-11-11-Previewegy újabb faszerű formátum jelent meg az indexmezők meghatározásához. Az új formátumban minden összetett mező rendelkezik egy mezőgyűjteménysel, amelyben az almezők definiálva vannak. Az API 2019-05-06-os verziójában ez az új formátum kizárólag ezt a formátumot használja, és nem sikerül létrehozni vagy frissíteni egy indexet a régi formátum használatával. Ha a régi formátum használatával létrehozott indexek, az API-verzióval 2017-11-11-Preview frissítenie kell őket az új formátumra, mielőtt azok kezelhetők lennének az API 2019-05-06-os verziójával.

A lapos indexeket az új formátumra frissítheti a következő lépésekkel az API-verzió 2017-11-11-Previewhasználatával:

Get kérést hajthat végre az index lekéréséhez. Ha már az új formátumban van, akkor elkészült.
Fordítsa le az indexet az egysíkú formátumról az új formátumra. Ehhez a feladathoz kódokat kell írnia, mivel az íráskor nem áll rendelkezésre mintakód.
PUT-kérés végrehajtása az index új formátumra való frissítéséhez. Ne módosítsa az index egyéb részleteit, például a mezők kereshetőségét/szűrhetőségét, mert a meglévő index fizikai kifejezését befolyásoló módosításokat az Update Index API nem engedélyezi.