Upgraden naar de nieuwste REST API in Azure AI Search

Artikel
05/21/2024

Gebruik dit artikel om gegevensvlak-aanroepen te migreren naar nieuwere versies van de Search REST API's.

2023-11-01 is de meest recente stabiele versie. Semantische classificatie en ondersteuning voor vectorindexering en query's zijn algemeen beschikbaar in deze versie.

Als u een upgrade uitvoert van 2023-10-01-preview naar 2023-11-01, zijn er geen belangrijke wijzigingen, maar er is één gedragsverschil: de vectorFilterMode standaardinstelling is gewijzigd van postfilter in prefilter voor filterexpressies. Als uw preview-code van 2023-10-01 niet expliciet is ingesteld vectorFilterMode , moet u het nieuwe standaardgedrag begrijpen of expliciet instellen vectorFilterMode op postfilter om het oude gedrag te behouden.
2024-05-01-preview is de meest recente preview-API-versie. Er wordt een binair gegevenstype toegevoegd voor vectorvelden, relevantie-eigenschappen voor betere zoekresultaten, De indexeerfunctie van OneLake-bestanden, meer vectorizers en meer insluitingsvaardigheden. AzureOpenAIEmbedding-vaardigheid wordt bijgewerkt om eigenschappen op te nemen en modelName eigenschappen op te nemendimensions. Het enige compatibiliteitsprobleem met eerdere versies tussen deze preview en de vorige twee previews is nu modelName vereist.
2024-03-01-preview voegt nieuwe gegevenstypen en eigenschappen toe voor compressie, maar is anders volledig achterwaarts compatibel met 2023-10-01-preview. Er zijn geen upgrade-instructies voor het gebruik van deze preview.
2023-10-01-preview is de eerste preview-versie die ingebouwde queryvectorisatie, ingebouwde gegevenssegmentering en vectorisatie tijdens het indexeren heeft toegevoegd (maakt gebruik van de vaardigheid Text Split en Azure OpenAI Embedding skill). Het introduceert belangrijke wijzigingen in vectorconfiguratie in de index- en vectorquery's.
2023-07-01-preview was de eerste REST API voor vectorondersteuning. Het is nu afgeschaft en u moet onmiddellijk migreren naar 2023-11-01 of een van de nieuwere REST API's voor preview.

Notitie

REST API-referentiedocumenten zijn nu geversied. Als u de juiste inhoud wilt ophalen, opent u een referentiepagina en filtert u vervolgens op versie met behulp van de selector boven de inhoudsopgave.

Wanneer moet ik upgraden?

Azure AI Search onderbreekt achterwaartse compatibiliteit als laatste redmiddel. Upgrade is nodig wanneer:

Uw code verwijst naar een buiten gebruik gestelde of afgeschafte API-versie en is onderhevig aan een of meer belangrijke wijzigingen. API-versies die in deze categorie vallen, omvatten 2023-07-10-preview voor vectoren en 2019-05-06 voor verouderde vaardigheden en tijdelijke oplossingen.
Uw code mislukt wanneer niet-herkende eigenschappen worden geretourneerd in een API-antwoord. Als best practice moet uw toepassing eigenschappen negeren die niet worden begrepen.
Uw code bewaart API-aanvragen en probeert deze opnieuw te verzenden naar de nieuwe API-versie. Dit kan bijvoorbeeld gebeuren als uw toepassing vervolgtokens behoudt die zijn geretourneerd door de zoek-API (zoek naar @search.nextPageParameters meer informatie in de naslaginformatie voor de zoek-API).

Belangrijke wijziging voor clientcode die verbindingsgegevens leest

Vanaf 29 maart 2024 geldt dit voor alle ondersteunde REST API's:

GET Skillset, GET Index en GET Indexer retourneren geen sleutels of verbindingseigenschappen meer in een antwoord. Dit is een belangrijke wijziging als u downstreamcode hebt die sleutels of verbindingen (gevoelige gegevens) leest vanuit een GET-antwoord.
Als u beheerders- of query-API-sleutels voor uw zoekservice wilt ophalen, gebruikt u de REST API's van Management.
Als u verbindingsreeks van een andere Azure-resource, zoals Azure Storage of Azure Cosmos DB, moet ophalen, gebruikt u de API's van die resource en gepubliceerde richtlijnen om de informatie te verkrijgen.

Belangrijke wijziging voor semantische rangschikking

Semantische rangschikking is algemeen beschikbaar in 2023-11-01. In tegenstelling tot eerdere REST API-versies wordt de queryLanguage eigenschap niet meer gebruikt. Er is ook een semanticConfiguration definitie vereist die de searchFields in eerdere versies vervangt. Zie Migreren van preview-versie om uw code over te schakelen naar de algemeen beschikbare versie of naar een nieuwere preview-versie.

Upgrade van 2023-07-01-preview

In deze sectie wordt het migratiepad uitgelegd van 2023-07-01-preview naar een nieuwere API-versie. Er zijn verschillende belangrijke wijzigingen van 2023-07-01-preview naar een nieuwere versie, maar alleen kleine compatibiliteitsproblemen tussen de nieuwere API-versies die volgen.

Upgrade-instructies richten zich op codewijzigingen waarmee u wijzigingen die fouten veroorzaken in eerdere versies, zodat bestaande code hetzelfde wordt uitgevoerd als voorheen, maar op de nieuwere API-versie. Zodra uw code in de werkvolgorde is, kunt u beslissen of u nieuwere functies wilt gebruiken. Zie voorbeelden van vectorcode en wat is er nieuw voor meer informatie over preview-functies.

Portalupgrade voor vectorindexen

Azure Portal ondersteunt een upgradepad met één klik voor indexen van 2023-07-01-preview. De portal detecteert vectorvelden 2023-07-01-preview en biedt een knop Migreren .

Migratiepad is van 2023-07-01-preview tot 2023-10-01-preview.
Updates zijn beperkt tot vectorvelddefinities en configuraties van vectorzoekalgoritmen.
Updates zijn in één richting. U kunt de upgrade niet omkeren. Zodra de index is bijgewerkt, moet u 2023-10-01-preview of hoger gebruiken om een query uit te voeren op de index.

Er is geen portalmigratie voor het upgraden van vectorquerysyntaxis. Zie code-upgrades voor wijzigingen in querysyntaxis.

Voordat u Migreren selecteert, selecteert u JSON bewerken om eerst het bijgewerkte schema te controleren. U moet een schema vinden dat voldoet aan de wijzigingen die worden beschreven in de sectie code-upgrade . Portalmigratie verwerkt alleen indexen met één vectorzoekalgoritmenconfiguratie. Er wordt een standaardprofiel gemaakt dat wordt toegewezen aan het algoritme 2023-07-01-preview vectorzoekopdrachten. Voor indexen met configuraties voor meervoudige vectorzoekopdrachten is handmatige migratie vereist.

Code-upgrade voor vectorindexen en query's

Vector search-ondersteuning is geïntroduceerd in Create or Update Index (2023-07-01-preview).

Voor een upgrade van 2023-07-01-preview naar een nieuwere stabielere of preview-versie is vereist:

De vectorconfiguratie in de index hernoemen en herstructureren
Uw vectorquery's herschrijven

Gebruik de instructies in deze sectie om vectorvelden, configuratie en query's te migreren van 2023-07-01-preview.

Roep Get Index aan om de bestaande definitie op te halen.

Wijzig de vectorzoekconfiguratie. In 2023-11-01 en latere versies wordt het concept van vectorprofielen geïntroduceerd die vectorgerelateerde configuraties bundelen onder één naam. Nieuwere versies wijzigen ook in algorithmConfigurationsalgorithms.

Wijzig de naam van algorithmConfigurations in algorithms. Dit is alleen een hernoeming van de matrix. De inhoud is compatibel met eerdere versies. Dit betekent dat uw bestaande HNSW-configuratieparameters kunnen worden gebruikt.
Voeg profileseen naam en een algoritmeconfiguratie voor elke naam toe.

Vóór de migratie (2023-07-01-preview):

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

Na migratie (2023-11-01):

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

Vectorvelddefinities wijzigen, vervangen door vectorSearchConfigurationvectorSearchProfile. Zorg ervoor dat de profielnaam wordt omgezet in een nieuwe vectorprofieldefinitie en niet de naam van de algoritmeconfiguratie. Andere vectorveldeigenschappen blijven ongewijzigd. Ze kunnen bijvoorbeeld niet worden gefilterd, gesorteerd of facetbaar, noch analysen of normalizers of synoniemenkaarten gebruiken.

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

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

Roep Create of Update Index aan om de wijzigingen te posten.

Wijzig Search POST om de querysyntaxis te wijzigen. Deze API-wijziging maakt ondersteuning mogelijk voor polymorfe vectorquerytypen.

Wijzig de naam van vectors in vectorQueries.
Voor elke vectorquery voegt u deze toe kinden stelt u deze in op vector.
Voor elke vectorquery wijzigt u de naam value in vector.
Voeg desgewenst toe vectorFilterMode als u filterexpressies gebruikt. De standaardwaarde is voorfilter voor indexen die zijn gemaakt na 2023-10-01. Indexen die vóór die datum zijn gemaakt, ondersteunen alleen postfilter, ongeacht hoe u de filtermodus instelt.

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

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

Met deze stappen voltooit u de migratie naar een stabiele API-versie van 2023-11-01 of nieuwere preview-API-versies.

Upgraden naar 2020-06-30

In deze versie is er één belangrijke wijziging en verschillende gedragsverschillen. Algemeen beschikbare functies zijn onder andere:

Kennisarchief, permanente opslag van verrijkte inhoud die is gemaakt via vaardighedensets, gemaakt voor downstreamanalyse en verwerking via andere toepassingen. Er wordt een kennisarchief gemaakt via AZURE AI Search REST API's, maar deze bevindt zich in Azure Storage.

Wijziging die fouten veroorzaken

Code die is geschreven op basis van eerdere API-versies wordt onderbroken 2020-06-30 en later als code de volgende functionaliteit bevat:

Letterlijke Edm.Date waarden (een datum die bestaat uit een jaarmaanddag, zoals 2020-12-12) in filterexpressies, moeten de Edm.DateTimeOffset volgende notatie hebben: 2020-12-12T00:00:00Z. Deze wijziging was nodig om onjuiste of onverwachte queryresultaten te verwerken vanwege verschillen in tijdzones.

Gedragswijzigingen

BM25-classificatiealgoritmen vervangen het vorige classificatie-algoritme door nieuwere technologie. Services die na 2019 zijn gemaakt, gebruiken dit algoritme automatisch. Voor oudere services moet u parameters instellen om het nieuwe algoritme te gebruiken.
Geordende resultaten voor null-waarden zijn in deze versie gewijzigd, waarbij null-waarden eerst worden weergegeven als de sortering asc en laatste als de sortering is desc. Als u code hebt geschreven om te bepalen hoe null-waarden worden gesorteerd, moet u rekening houden met deze wijziging.

Upgraden naar 2019-05-06

Functies die algemeen beschikbaar zijn in deze API-versie zijn onder andere:

Automatisch aanvullen is een typeahead-functie waarmee een gedeeltelijk opgegeven terminvoer wordt voltooid.
Complexe typen bieden systeemeigen ondersteuning voor gestructureerde objectgegevens in zoekindex.
JsonLines parseringsmodi, onderdeel van Azure Blob-indexering, maakt één zoekdocument per JSON-entiteit die wordt gescheiden door een nieuwe regel.
AI-verrijking biedt indexering die gebruikmaakt van de AI-verrijkingsengines van Azure AI-services.

Wijzigingen die fouten veroorzaken

Code die is geschreven op basis van een eerdere API-versie wordt onderbroken 2019-05-06 en later als deze de volgende functionaliteit bevat:

Typ de eigenschap voor Azure Cosmos DB. Voor indexeerfuncties die zijn gericht op een Azure Cosmos DB for NoSQL API-gegevensbron , wijzigt "type": "documentdb" u in "type": "cosmosdb".
Als de foutafhandeling van de indexeerfunctie verwijzingen naar de status eigenschap bevat, moet u deze verwijderen. We hebben de status verwijderd uit het foutbericht omdat deze geen nuttige informatie biedt.
Gegevensbron verbindingsreeks worden niet meer geretourneerd in het antwoord. Vanaf API-versies 2019-05-06 en 2019-05-06-Preview hoger retourneert de gegevensbron-API geen verbindingsreeks s meer in het antwoord van een REST-bewerking. In eerdere API-versies, voor gegevensbronnen die zijn gemaakt met POST, heeft Azure AI Search 201 geretourneerd, gevolgd door het OData-antwoord, dat de verbindingsreeks in tekst zonder opmaak bevatte.
De cognitieve vaardigheid Entiteitsherkenning wordt buiten gebruik gesteld. Als u de vaardigheid Naamentiteitsherkenning in uw code hebt aangeroepen, mislukt de aanroep. Vervangingsfunctionaliteit is Entity Recognition Skill (V3). Volg de aanbevelingen in afgeschafte vaardigheden om te migreren naar een ondersteunde vaardigheid.

Complexe typen upgraden

API-versie 2019-05-06 heeft formele ondersteuning toegevoegd voor complexe typen. Als uw code eerdere aanbevelingen voor complexe type-equivalentie heeft geïmplementeerd in 2017-11-11-Preview of 2016-09-01-Preview, zijn er enkele nieuwe en gewijzigde limieten vanaf de versie 2019-05-06 waarvan u rekening moet houden:

De limieten voor de diepte van subvelden en het aantal complexe verzamelingen per index zijn verlaagd. Als u indexen hebt gemaakt die deze limieten overschrijden met behulp van de preview-API-versies, mislukt elke poging om ze bij te werken of opnieuw te maken met behulp van de API-versie 2019-05-06 . Als u zich in deze situatie bevindt, moet u uw schema opnieuw ontwerpen om binnen de nieuwe limieten te passen en vervolgens uw index opnieuw te bouwen.
Er is een nieuwe limiet die begint in api-versie 2019-05-06 op het aantal elementen van complexe verzamelingen per document. Als u indexen hebt gemaakt met documenten die deze limieten overschrijden met behulp van de preview-API-versies, mislukt elke poging om die gegevens opnieuw te indexeren met api-versie 2019-05-06 . Als u zich in deze situatie bevindt, moet u het aantal complexe verzamelingselementen per document verminderen voordat u uw gegevens opnieuw indexeert.

Zie Servicelimieten voor Azure AI Search voor meer informatie.

Een oude structuur van een complex type upgraden

Als uw code complexe typen gebruikt met een van de oudere preview-API-versies, gebruikt u mogelijk een indeling voor indexdefinities die er als volgt uitziet:

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

Er is een nieuwere structuur-achtige indeling voor het definiëren van indexvelden geïntroduceerd in de API-versie 2017-11-11-Preview. In de nieuwe indeling heeft elk complex veld een verzameling velden waarin de subvelden worden gedefinieerd. In API-versie 2019-05-06 wordt deze nieuwe indeling uitsluitend gebruikt en mislukt het maken of bijwerken van een index met de oude indeling. Als u indexen hebt gemaakt met de oude indeling, moet u de API-versie 2017-11-11-Preview gebruiken om ze bij te werken naar de nieuwe indeling voordat ze kunnen worden beheerd met API-versie 2019-05-06.

U kunt platte indexen bijwerken naar de nieuwe indeling met behulp van de API-versie 2017-11-11-Preview:

Voer een GET-aanvraag uit om uw index op te halen. Als deze al in de nieuwe indeling staat, bent u klaar.
Vertaal de index van de platte indeling naar de nieuwe indeling. U moet code schrijven voor deze taak omdat er geen voorbeeldcode beschikbaar is op het moment van schrijven.
Voer een PUT-aanvraag uit om de index bij te werken naar de nieuwe indeling. Vermijd het wijzigen van andere details van de index, zoals de doorzoekbaarheid/filterbaarheid van velden, omdat wijzigingen die van invloed zijn op de fysieke expressie van de bestaande index, niet zijn toegestaan door de Update Index-API.