Uppgradera till det senaste REST-API:et i Azure AI Search

Artikel
04/19/2024

Använd den här artikeln om du vill migrera dataplansanrop till nyare versioner av REST API för sökning.

2023-11-01 är den senaste stabila versionen. Semantisk rangordning och stöd för indexering och frågevektorer är allmänt tillgängliga i den här versionen.
2023-10-01-preview är den senaste förhandsversionen. Förhandsgranskningsfunktioner inkluderar inbyggd frågevektorisering, inbyggd datasegmentering och vektorisering under indexering (använder färdigheten Textdelning och Azure OpenAI-inbäddning ). Se kodexempel och genomgångar för hjälp med nya funktioner.
2023-07-01-preview var det första REST API:et för vektorstöd. Det är nu inaktuellt och du bör migrera till antingen 2023-11-01 eller 2023-10-01-preview omedelbart.

Kommentar

API-referensdokumenten är nu versionshanterade. Om du vill hämta rätt innehåll öppnar du en referenssida och filtrerar sedan efter version med väljaren ovanför innehållsförteckningen.

Så här uppgraderar du

Azure AI Search bryter bakåtkompatibiliteten som en sista utväg. Det här avsnittet innehåller instruktioner som hjälper dig att ändra befintlig kod som inte körs i en nyare version. Uppgradering krävs när:

Koden refererar till en tillbakadragen eller inaktuell API-version och omfattas av en eller flera av de icke-bakåtkompatibla ändringarna. API-versioner som ingår i den här kategorin inkluderar 2023-07-10-preview för vektorer och 2019-05-06.
Koden misslyckas när okända egenskaper returneras i ett API-svar. Som bästa praxis bör ditt program ignorera egenskaper som det inte förstår.
Koden bevarar API-begäranden och försöker skicka dem till den nya API-versionen igen. Detta kan till exempel inträffa om ditt program bevarar fortsättningstoken som returneras från sök-API:et (mer @search.nextPageParameters information finns i sök-API-referensen).

Uppgradera till 2023-10-01-preview

Den här versionen är identisk med 2023-11-01 men har extra funktioner i offentlig förhandsversion: inbyggt frågevektoriserare och vektorförfilterläge. Om du vill använda dessa funktioner bör du uppgradera till den senaste förhandsversionen.

Vektorsökningsalgoritmkonfigurationen i ett sökindex är identisk med 2023-11-01. Följ anvisningarna i nästa avsnitt för att åtgärda icke-bakåtkompatibla ändringar från förhandsversionen 2023-07-01.

Uppgradera till 2023-11-01

Den här versionen har icke-bakåtkompatibla ändringar och beteendeskillnader för stöd för semantisk rangordning och vektorsökning.

Semantisk rangordning är allmänt tillgänglig och använder inte längre egenskapen queryLanguage . Det kräver också en semanticConfiguration definition.

Om du vill uppgradera från 2020-06-30-preview skapar du en semanticConfiguration för att ersätta searchFields. Se Migrera från förhandsversion för steg.
Stöd för vektorsökning introducerades i Skapa eller uppdatera index (2023-07-01-preview).

Om du vill uppgradera från 2023-07-01-preview byter du namn på och omstrukturerar vektorkonfigurationen i indexet och skriver om vektorfrågesyntaxen med hjälp av anvisningarna i det här avsnittet.

Om du vill uppgradera från 2023-10-01-preview finns det inga icke-bakåtkompatibla ändringar, men det finns en beteendeskillnad: standardinställningen vectorFilterMode ändrades från postfilter till förfilter för filteruttryck. Om din 2023-10-01-förhandsversionskod inte anges vectorFilterMode explicit kontrollerar du att du förstår det nya beteendet eller ställer in läget på postfilter för att behålla det gamla beteendet.

Dricks

Azure-portalen stöder en uppgraderingssökväg med ett klick för index för förhandsversionen av 2023-07-01. Portalen identifierar index för 2023-07-01-preview och innehåller en migreringsknapp . Innan du väljer Migrera väljer du Redigera JSON för att granska det uppdaterade schemat först. Du bör hitta ett schema som överensstämmer med de ändringar som beskrivs i det här avsnittet. Portalmigrering hanterar endast index med en vektorsökningsalgoritmkonfiguration, vilket skapar en standardprofil som mappar till algoritmen. Index med flera konfigurationer kräver manuell migrering.

Här följer stegen för att migrera från 2023-07-01-preview:

Anropa Hämta index för att hämta den befintliga definitionen.

Ändra vektorsökningskonfigurationen. Det här API:et introducerar begreppet *vektorprofiler som kombinerar vektorrelaterade konfigurationer under ett namn. Den byter också namn algorithmConfigurations till algorithms.

Byt namn på algorithmConfigurations till algorithms. Det här är bara ett namnbyte på matrisen. Innehållet är bakåtkompatibelt. Det innebär att dina befintliga HNSW-konfigurationsparametrar kan användas.
Lägg till profilesoch ge ett namn och en algoritmkonfiguration för var och en.

Före migreringen (2023-07-01-preview):

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

Efter migreringen (2023-11-01):

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

Ändra definitioner för vektorfält och ersätt vectorSearchConfiguration med vectorSearchProfile. Kontrollera att profilnamnet matchar en ny vektorprofildefinition och inte algoritmkonfigurationsnamnet. Andra egenskaper för vektorfält förblir oförändrade. De kan till exempel inte vara filterbara, sorterbara eller fasettbara eller använda analysverktyg eller normaliserare eller synonymkartor.

Före (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"
  }

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

Anropa Skapa eller uppdatera index för att publicera ändringarna.

Ändra Sök POST för att ändra frågesyntaxen. Den här API-ändringen möjliggör stöd för polymorfa vektorfrågetyper.

Byt namn på vectors till vectorQueries.
För varje vektorfråga lägger du till kindoch ställer in den på "vektor".
För varje vektorfråga byter du namn value till vector.
Du kan också lägga till vectorFilterMode om du använder filteruttryck. Standardvärdet är förfilter för index som skapats efter 2023-10-01. Index som skapats före det datumet stöder endast postfilter, oavsett hur du ställer in filterläget.

Före (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"
}

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

De här stegen slutför migreringen till API-versionen 2023-11-01.

Uppgradera till 2020-06-30

I den här versionen finns det en icke-bakåtkompatibel ändring och flera beteendeskillnader. Allmänt tillgängliga funktioner är:

Kunskapslager, beständig lagring av berikat innehåll som skapats via kompetensuppsättningar, skapat för nedströmsanalys och bearbetning via andra program. Ett kunskapslager skapas via REST-API:er för Azure AI Search, men det finns i Azure Storage.

Icke-bakåtkompatibel ändring

Kod som skrivits mot tidigare API-versioner bryts 2020-06-30 och senare om koden innehåller följande funktioner:

Alla Edm.Date-literaler (ett datum som består av år-månad-dag, till exempel 2020-12-12) i filteruttryck måste följa formatet Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Den här ändringen var nödvändig för att hantera felaktiga eller oväntade frågeresultat på grund av tidszonsskillnader.

Funktionalitetsförändringar

BM25-rangordningsalgoritmen ersätter den tidigare rankningsalgoritmen med nyare teknik. Tjänster som skapats efter 2019 använder den här algoritmen automatiskt. För äldre tjänster måste du ange parametrar för att använda den nya algoritmen.
Ordnade resultat för null-värden har ändrats i den här versionen, med null-värden som visas först om sorteringen är asc och sist om sorteringen är desc. Om du har skrivit kod för att hantera hur nullvärden sorteras bör du vara medveten om den här ändringen.

Uppgradera till 2019-05-06

Funktioner som blev allmänt tillgängliga i den här API-versionen är:

Automatisk komplettering är en typeahead-funktion som slutför en delvis angiven terminmatning.
Komplexa typer ger inbyggt stöd för strukturerade objektdata i sökindex.
JsonLines-parsningslägen, som är en del av Azure Blob-indexering, skapar ett sökdokument per JSON-entitet som avgränsas med en ny rad.
AI-berikande tillhandahåller indexering som använder AI-berikande motorer i Azure AI-tjänster.

Icke-bakåtkompatibla ändringar

Kod som skrivits mot en tidigare API-version bryter 2019-05-06 och senare om den innehåller följande funktioner:

Typegenskap för Azure Cosmos DB. För indexerare som riktar in sig på en Azure Cosmos DB för NoSQL API-datakälla ändrar du "type": "documentdb" till "type": "cosmosdb".
Om indexerarens felhantering innehåller referenser till status egenskapen bör du ta bort den. Vi tog bort status från felsvaret eftersom det inte gav användbar information.
Datakällans anslutningssträng returneras inte längre i svaret. Från API-versionerna 2019-05-06 och 2019-05-06-Preview och senare returnerar datakällans API inte längre anslutningssträng som svar på någon REST-åtgärd. I tidigare API-versioner, för datakällor som skapats med POST, returnerade Azure AI Search 201 följt av OData-svaret, som innehöll anslutningssträng i oformaterad text.
Den kognitiva kunskapen för entitetsigenkänning har dragits tillbaka. Om du har anropat kompetensen Namnentitetsigenkänning i koden misslyckas anropet. Ersättningsfunktioner är V3 (Entity Recognition Skill). Följ rekommendationerna i Inaktuella färdigheter för att migrera till en kompetens som stöds.

Uppgradera komplexa typer

API-version 2019-05-06 har lagt till formellt stöd för komplexa typer. Om koden implementerade tidigare rekommendationer för komplex typjämförelse i 2017-11-11-Preview eller 2016-09-01-Preview finns det några nya och ändrade gränser som börjar i version 2019-05-06 som du måste vara medveten om:

Gränserna för djupet på underfält och antalet komplexa samlingar per index har sänkts. Om du har skapat index som överskrider dessa gränser med api-versionerna för förhandsversionen misslyckas alla försök att uppdatera eller återskapa dem med hjälp av API-version 2019-05-06. Om du befinner dig i den här situationen måste du göra om schemat så att det passar inom de nya gränserna och sedan återskapa ditt index.
Det finns en ny gräns som börjar i api-version 2019-05-06 för antalet element i komplexa samlingar per dokument. Om du har skapat index med dokument som överskrider dessa gränser med api-versionerna för förhandsversionen misslyckas alla försök att indexera om dessa data med api-version 2019-05-06. Om du befinner dig i den här situationen måste du minska antalet komplexa samlingselement per dokument innan du indexerar om dina data.

Mer information finns i Tjänstbegränsningar för Azure AI Search.

Uppgradera en gammal komplex typstruktur

Om din kod använder komplexa typer med en av de äldre förhandsversionerna av API:et kanske du använder ett indexdefinitionsformat som ser ut så här:

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

Ett nyare trädliknande format för att definiera indexfält introducerades i API-version 2017-11-11-Preview. I det nya formatet har varje komplext fält en fältsamling där dess underfält definieras. I API-version 2019-05-06 används det här nya formatet exklusivt och försök att skapa eller uppdatera ett index med det gamla formatet misslyckas. Om du har skapat index med det gamla formatet måste du använda API version 2017-11-11-Preview för att uppdatera dem till det nya formatet innan de kan hanteras med API-version 2019-05-06.

Du kan uppdatera "platta" index till det nya formatet med följande steg med hjälp av API-version 2017-11-11-Preview:

Utför en GET-begäran för att hämta ditt index. Om det redan är i det nya formatet är du klar.
Översätt indexet från formatet "flat" till det nya formatet. Du måste skriva kod för den här uppgiften eftersom det inte finns någon exempelkod tillgänglig vid tidpunkten för den här skrivning.
Utför en PUT-begäran om att uppdatera indexet till det nya formatet. Undvik att ändra annan information om indexet, till exempel sökbarhet/filtrering av fält, eftersom ändringar som påverkar det fysiska uttrycket för det befintliga indexet inte tillåts av API:et för uppdateringsindex.