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

Artikel
06/24/2024

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

2023-11-01 är den senaste stabila versionen.
2024-05-01-preview är den senaste förhandsversionen av API:et.

Uppgraderingsinstruktioner fokuserar på kodändringar som tar dig igenom icke-bakåtkompatibla ändringar från tidigare versioner så att befintlig kod körs på samma sätt som tidigare, men på den nyare API-versionen. När koden är i arbetsordning kan du bestämma om du vill använda nyare funktioner. Mer information om förhandsversionsfunktioner finns i vektorkodexempel och Nyheter.

Vi rekommenderar att du uppgraderar API-versioner i följd och arbetar igenom varje version tills du kommer till den senaste.

2023-07-01-preview var det första REST-API:et för vektorstöd. Använd inte den här API-versionen. Det är nu inaktuellt och du bör migrera till antingen stabila eller nyare REST API:er för förhandsversion omedelbart.

Kommentar

REST API-referensdokumenten är nu versionshanterade. För versionsspecifikt innehåll öppnar du en referenssida och använder sedan väljaren till höger, ovanför innehållsförteckningen, för att välja din version.

När du ska uppgradera

Azure AI Search bryter bakåtkompatibiliteten som en sista utväg. Uppgradering krävs när:

Koden refererar till en tillbakadragen eller icke-stödd API-version och omfattas av en eller flera icke-bakåtkompatibla ändringar. Du måste åtgärda icke-bakåtkompatibla ändringar om kodmålen 2023-07-10-preview för vektorer, 2020-06-01-preview för semantisk rangordning och 2019-05-06 för föråldrade kunskaper och lösningar.
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).

Icke-bakåtkompatibel ändring för klientkod som läser anslutningsinformation

Gäller från och med 29 mars 2024 och gäller för alla REST-API:er som stöds:

GET Skillset, GET Index och GET Indexer returnerar inte längre nycklar eller anslutningsegenskaper i ett svar. Det här är en icke-bakåtkompatibel ändring om du har nedströmskod som läser nycklar eller anslutningar (känsliga data) från ett GET-svar.
Om du behöver hämta administratörs- eller fråge-API-nycklar för söktjänsten använder du REST API:er för hantering.
Om du behöver hämta niska veze för en annan Azure-resurs, till exempel Azure Storage eller Azure Cosmos DB, använder du API:erna för den resursen och publicerade riktlinjer för att hämta informationen.

Icke-bakåtkompatibel ändring för semantisk rangordning

Semantisk rangordning är allmänt tillgänglig i 2023-11-01. Här är de icke-bakåtkompatibla ändringarna för semantisk rangordning från tidigare versioner:

I alla versioner efter 2020-06-01-preview: semanticConfiguration ersätts searchFields som mekanism för att ange vilka fält som ska användas för L2-rangordning.
För alla API-versioner gjorde uppdateringar den 14 juli 2023 till Microsoft-värdbaserade semantiska modeller semantisk rangordning språkagnostisk, vilket effektivt inaktiverade queryLanguage egenskapen. Det finns ingen "icke-bakåtkompatibel ändring" i koden, men egenskapen ignoreras.

Se Migrera från förhandsversion för att överföra koden till att använda semanticConfiguration.

Uppgradera till 2024-05-01-preview

2024-05-01-preview lägger till OneLake-index, stöd för binära vektorer och stöd för fler inbäddningsmodeller.

Om du uppgraderar från 2024-03-01-previewkräver azureopenAIEmbedding-färdigheten nu en modellnamn och dimensionsegenskap.

Sök i din kodbas efter AzureOpenAIEmbedding-referenser .
Ange modelName till "text-embedding-ada-002" och inställt dimensions på "1536".

Uppgradera till 2024-03-01-preview

2024-03-01-preview lägger till smala datatyper, skalbar kvantisering och lagringsalternativ för vektorer.

Om du uppgraderar från 2023-10-01-previewfinns det inga icke-bakåtkompatibla ändringar. Det finns dock en beteendeskillnad: för 2023-11-01 och nyare förhandsversioner har standardinställningen vectorFilterMode ändrats från postfilter till förfilter för filteruttryck.

Sök efter referenser i din kodbas vectorFilterMode .
Om egenskapen uttryckligen anges krävs ingen åtgärd. Om du använde standardinställningen bör du vara medveten om att det nya standardbeteendet är att filtrera före frågekörning. Om du vill filtrera efter frågan ställer du uttryckligen in vectorFilterMode på postfilter för att behålla det gamla beteendet.

Uppgradera till 2023-10-01-preview

2023-10-01-preview var den första förhandsversionen som lade till inbyggd datasegmentering och vektorisering under indexering och inbyggd frågevektorisering. Den stöder även vektorindexering och frågor från den tidigare versionen.

Om du uppgraderar från den tidigare versionen innehåller nästa avsnitt stegen.

Uppgradera från 2023-07-01-preview

Använd inte den här API-versionen. Den implementerar en vektorfrågassyntax som inte är kompatibel med nyare API-versioner.

2023-07-01-preview är nu inaktuell, så du bör inte basera ny kod på den här versionen, och du bör inte heller uppgradera till den här versionen under några omständigheter. I det här avsnittet beskrivs migreringssökvägen från 2023-07-01-preview till en nyare API-version.

Portaluppgradering för vektorindex

Azure-portalen stöder en uppgraderingssökväg med ett klick för 2023-07-01-preview index. Den identifierar vektorfält och innehåller knappen Migrera .

Migreringssökvägen är från 2023-07-01-preview till 2024-05-01-preview.
Uppdateringar är begränsade till konfigurationer av vektorfält och vektorsökningsalgoritmer.
Uppdateringar är enkelriktade. Du kan inte ångra uppgraderingen. När indexet har uppgraderats måste du använda 2024-05-01-preview eller senare för att fråga indexet.

Det finns ingen portalmigrering för uppgradering av vektorfrågesyntax. Se koduppgraderingar för ändringar av frågesyntax.

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 avsnittet om koduppgradering . Portalmigrering hanterar endast index med en vektorsökningsalgoritmkonfiguration. Den skapar en standardprofil som mappar till vektorsökningsalgoritmen 2023-07-01-preview . Index med flera vektorsökningskonfigurationer kräver manuell migrering.

Koduppgradering för vektorindex och frågor

Stöd för vektorsökning introducerades i Skapa eller uppdatera index (2023-07-01-preview).

Uppgradering från 2023-07-01-preview till en nyare stabil version eller förhandsversion kräver:

Byta namn på och omstrukturera vektorkonfigurationen i indexet
Skriva om dina vektorfrågor

Använd anvisningarna i det här avsnittet för att migrera vektorfält, konfiguration och frågor från 2023-07-01-preview.

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

Ändra vektorsökningskonfigurationen. 2023-11-01och senare versioner introducerar begreppet vektorprofiler som paketering av vektorrelaterade konfigurationer under ett namn. Nyare versioner 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": {
    "algorithms": [
      {
        "name": "myHnswConfig",
        "kind": "hnsw",
        "hnswParameters": {
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500,
          "metric": "cosine"
        }
      }
    ],
    "profiles": [
      {
        "name": "myHnswProfile",
        "algorithm": "myHnswConfig"
      }
    ]
  }

Ä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å vector.
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 2023-11-01 en stabil API-version eller nyare förhandsversioner av API:et.

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 bryter på 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 Edm.DateTimeOffset formatet: 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 på 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 niska veze returneras inte längre i svaret. Från API-versioner 2019-05-06 och 2019-05-06-Preview framåt returnerar datakällans API inte längre niska veze 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 niska veze 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-versionen 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 du 2019-05-06 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-versionen 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-versionen 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-versionen 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-versionen 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-versionen 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 det platta formatet 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.