Dela via

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

  • Artikel

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

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 nya funktioner 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 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).

Så här uppgraderar du

  1. Granska viktig information för varje API-version.

  2. Uppdatera parametern api-version , som anges i begärandehuvudet, till en nyare version.

    I programkoden som gör direkta anrop till REST-API:erna söker du efter alla instanser av den befintliga versionen och ersätter den sedan med den nya versionen. Mer information om hur du strukturerar ett REST-anrop finns i Snabbstart: använda REST.

    Om du använder en Azure SDK riktar dessa paket in sig på specifika versioner av REST-API:et. Paketuppdateringar kan sammanfalla med en REST API-uppdatering, men varje SDK är enligt ett eget lanseringsschema som levereras oberoende av Azure AI Search REST API-versioner. Kontrollera ändringsloggen för ditt SDK-paket för att avgöra om en paketversion är avsedd för den senaste REST API-versionen.

  3. Granska de icke-bakåtkompatibla ändringarna som beskrivs i den här artikeln och implementera lösningarna. Börja med den version som används av koden och lös eventuella icke-bakåtkompatibla ändringar för varje nyare API-version tills du kommer till den senaste stabila versionen eller förhandsversionen.

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 anslutningssträng av en annan Azure-resurs, till exempel Azure Storage eller Azure Cosmos DB, använder du API:erna för den resursen och publicerade vägledning för att hämta informationen.

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

Semantisk ranker är allmänt tillgänglig i 2023-11-01. Här är de icke-bakåtkompatibla ändringarna för semantisk ranker 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 rankerspråksagnostisk, 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-11-01-preview

2024-11-01-preview frågeomskrivning, skicklighet i dokumentlayout, nyckellös fakturering för kompetensbearbetning, Markdown-parsningsläge och omskolningsalternativ för komprimerade vektorer.

Om du uppgraderar från 2024-09-01-previewkan du använda de nya förhandsversions-API:erna utan att ändra till befintlig kod.

Den nya versionen introducerar dock syntaxändringar i vectorSearch.compressions:

  • rerankWithOriginalVectors Ersätter medenableRescoring
  • Flyttar defaultOversampling till ett nytt rescoringOptions egenskapsobjekt

Bakåtkompatibilitet bevaras på grund av en intern API-mappning, men vi rekommenderar att du ändrar syntaxen om du använder den nya förhandsversionen. En jämförelse av syntaxen finns i Komprimera vektorer med hjälp av skalär eller binär kvantisering.

Uppgradera till 2024-09-01-preview

2024-09-01-preview lägger till Matryoshka Representation Learning-komprimering (MRL) för modeller för textinbäddning-3, riktad vektorfiltrering för hybridfrågor, information om vektorunderpoäng för felsökning och tokensegmentering för kunskaper om textdelning.

Om du uppgraderar från 2024-05-01-previewkan du använda de nya förhandsversions-API:erna utan att ändra till befintlig kod.

Uppgradera till 2024-07-01

2024-07-01 är en allmän version. De tidigare förhandsversionsfunktionerna är nu allmänt tillgängliga: integrerad segmentering och vektorisering (kompetens för textdelning, AzureOpenAIEmbedding-färdighet), frågevektoriserare baserat på AzureOpenAIEmbedding, vektorkomprimering (skalär kvantisering, binär kvantisering, lagrad egenskap, smala datatyper).

Det finns inga icke-bakåtkompatibla ändringar om du uppgraderar från 2024-05-01-preview till stabil. Om du vill använda den nya stabila versionen ändrar du API-versionen och testar koden.

Det finns icke-bakåtkompatibla ändringar om du uppgraderar direkt från 2023-11-01. Följ stegen som beskrivs för varje nyare förhandsversion för att migrera från 2023-11-01 till 2024-07-01.

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.

  1. Sök i din kodbas efter AzureOpenAIEmbedding-referenser .

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

  1. Sök efter referenser i din kodbas vectorFilterMode .

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

2023-11-01 är en allmän version. De tidigare förhandsversionsfunktionerna är nu allmänt tillgängliga: semantisk rankning, vektorindex och frågestöd.

Det finns inga icke-bakåtkompatibla ändringar från 2023-10-01-preview, men det finns flera icke-bakåtkompatibla ändringar från 2023-07-01-preview till 2023-11-01. Mer information finns i Uppgradera från 2023-07-01-preview.

Om du vill använda den nya stabila versionen ändrar du API-versionen och testar koden.

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

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

  2. Ä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"
      }
    ]
  }

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

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

  5. Ä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:

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

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

  3. Datakällans anslutningssträng returneras inte längre i svaret. Från API-versioner 2019-05-06 och 2019-05-06-Preview 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.

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

  1. Utför en GET-begäran för att hämta ditt index. Om det redan är i det nya formatet är du klar.

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

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

Kommentar

Det går inte att hantera index som skapats med det gamla "platta" formatet från Azure Portal. Uppgradera indexen från den "platta" representationen till "träd"-representationen så snart som möjligt.

Nästa steg

Granska referensdokumentationen för REST API för sökning. Om du stöter på problem kan du be oss om hjälp med Stack Overflow eller kontakta supporten.

tjänsten Search REST API-referens