Eseguire l'aggiornamento all'API REST più recente in Azure AI Search

Articolo
07/05/2024

Usare questo articolo per eseguire la migrazione delle chiamate del piano dati alle versioni più recenti delle API REST di ricerca.

2023-11-01 è la versione stabile più recente.
2024-05-01-preview è la versione più recente dell'API di anteprima.

Le istruzioni di aggiornamento sono incentrate sulle modifiche al codice che consentono di apportare modifiche che causano interruzioni rispetto alle versioni precedenti, in modo che il codice esistente venga eseguito come in precedenza, ma nella versione più recente dell'API. Quando il codice funziona, è possibile decidere se adottare funzionalità più recenti. Per altre informazioni sulle funzionalità di anteprima, vedere Esempi di codice vettoriale e Novità.

È consigliabile aggiornare le versioni dell'API in successione, usando ogni versione fino a quando non si arriva alla versione più recente.

2023-07-01-preview è stata la prima API REST per il supporto dei vettori. Non usare questa versione dell'API. Ora questa versione è deprecata ed è necessario eseguire immediatamente la migrazione a una versione stabile o a qualsiasi delle API REST di anteprima più recenti.

Nota

La documentazione di riferimento dell'API REST è ora sottoposta al controllo delle versioni. Per il contenuto specifico della versione, aprire una pagina di riferimento e quindi usare il selettore che si trova a destra, sopra il sommario, per selezionare la versione.

Quando eseguire l'aggiornamento

Azure AI Search interrompe la compatibilità con le versioni precedenti come ultima risorsa. L'aggiornamento è necessario quando:

Il codice fa riferimento a una versione dell'API ritirata o non supportata ed è soggetto a una o più modifiche che causano un'interruzione. È necessario risolvere le modifiche che causano un'interruzione se il codice contiene 2023-07-10-preview per i vettori, 2020-06-01-preview per la classificazione semantica e 2019-05-06 per competenze e soluzioni alternative obsolete.
Il codice ha esito negativo quando vengono restituite proprietà sconosciute in una risposta API. Come procedura consigliata, l'applicazione deve ignorare le proprietà che non riconosce.
Il codice rende persistenti le richieste API e tenta di inviarle nuovamente alla nuova versione dell'API. Ad esempio, questa situazione può verificarsi se l'applicazione mantiene i token di continuazione restituiti dall'API di ricerca. Per altre informazioni, cercare @search.nextPageParameters nel riferimento all'API di ricerca.

Modifica che causa un'interruzione per il codice client che legge le informazioni di connessione

A partire dal 29 marzo 2024, si applica a tutte le API REST supportate:

GET Skillset, GET Index e GET Indexer non restituiscono più chiavi o proprietà di connessione in una risposta. Si tratta di una modifica che causa un'interruzione se si dispone di codice downstream che legge chiavi o connessioni (dati sensibili) di una risposta GET.
Se è necessario recuperare le chiavi API di query o amministrazione per il servizio di ricerca, usare le API REST di gestione.
Se è necessario recuperare le stringhe di connessione di un'altra risorsa di Azure, ad esempio Archiviazione di Azure o Azure Cosmos DB, usare le API di tale risorsa e il materiale sussidiario pubblicato per ottenere le informazioni.

Modifica che causa un'interruzione per la classificazione semantica

La classificazione semantica è disponibile a livello generale in 2023-11-01. Ecco le modifiche che causano un'interruzione per la classificazione semantica delle versioni precedenti:

In tutte le versioni successive alla 2020-06-01-preview: semanticConfiguration sostituisce searchFields come meccanismo per specificare quali campi usare per la classificazione L2.
Per tutte le versioni dell'API, gli aggiornamenti del 14 luglio 2023 ai modelli semantici ospitati da Microsoft hanno reso la classificazione semantica indipendente dalla linguaggio, eliminando di fatto la proprietà queryLanguage. Nel codice non è presente alcuna modifica che causa un'interruzione, ma la proprietà viene ignorata.

Vedere Eseguire la migrazione dalla versione di anteprima per eseguire la transizione del codice all'utilizzo di semanticConfiguration.

Eseguire l'aggiornamento alla versione 2024-05-01-preview

2024-05-01-preview aggiunge l'indice OneLake, il supporto per i vettori binari e il supporto per altri modelli di incorporamento.

Se si esegue l'aggiornamento da 2024-03-01-preview, la competenza AzureOpenAIEmbedding richiede ora un nome del modello e una proprietà dimensioni.

Cercare nella codebase i riferimenti ad AzureOpenAIEmbedding.
Impostare modelName su "text-embedding-ada-002" e impostare dimensions su "1536".

Eseguire l'aggiornamento alla versione 2024-03-01-preview

2024-03-01-preview aggiunge tipi di dati stretti, quantizzazione scalare e opzioni di archiviazione vettoriali.

Se si esegue l'aggiornamento da 2023-10-01-preview, non vengono apportate modifiche che causano un'interruzione. Tuttavia, esiste una differenza di comportamento: per 2023-11-01 e le anteprime più recenti, l'impostazione predefinita vectorFilterMode è stata modificata da postfiltro al prefiltro per le espressioni di filtro.

Cercare nella codebase i riferimenti a vectorFilterMode.
Se la proprietà è impostata in modo esplicito, non è necessaria alcuna azione. Se è stata usata l'impostazione predefinita, tenere presente che il nuovo comportamento predefinito consiste nel filtrare prima dell'esecuzione della query. Se si vogliono applicare filtri post-query, impostare in modo esplicito vectorFilterMode su postfiltro per mantenere il comportamento precedente.

Eseguire l'aggiornamento alla versione 2023-10-01-preview

2023-10-01-preview è stata la prima versione di anteprima ad aggiungere la suddivisione in blocchi e la vettorizzazione dei dati predefiniti durante l'indicizzazione e la vettorizzazione di query predefinita. Supporta anche l'indicizzazione vettoriale e le query della versione precedente.

Se si esegue l'aggiornamento dalla versione precedente, la sezione successiva include i passaggi.

Eseguire l'aggiornamento da 2023-07-01-preview

Non usare questa versione dell'API. Implementa una sintassi di query vettoriale incompatibile con qualsiasi versione più recente dell'API.

2023-07-01-preview è ora deprecato, quindi non è consigliabile basare il nuovo codice su questa versione, né eseguire l'aggiornamento a questa versione in qualsiasi circostanza. Questa sezione illustra il percorso di migrazione da 2023-07-01-preview a qualsiasi versione più recente dell'API.

Aggiornamento del portale per gli indici vettoriali

Il portale di Azure supporta un percorso di aggiornamento con un clic per gli indici 2023-07-01-preview. Rileva i campi vettoriali e fornisce un pulsante Esegui migrazione.

Il percorso di migrazione è compreso tra 2023-07-01-preview e 2024-05-01-preview.
Gli aggiornamenti sono limitati alle definizioni dei campi vettoriali e alle configurazioni dell'algoritmo di ricerca vettoriale.
Gli aggiornamenti sono unidirezionali. Non è possibile invertire l'aggiornamento. Dopo l'aggiornamento dell'indice, è necessario usare 2024-05-01-preview o versione successiva per eseguire query sull'indice.

Non è disponibile una migrazione del portale per l'aggiornamento della sintassi delle query vettoriali. Per le modifiche alla sintassi delle query, vedere Aggiornamenti del codice.

Prima di selezionare Esegui migrazione, selezionare Modifica JSON per esaminare prima lo schema aggiornato. È necessario trovare uno schema conforme alle modifiche descritte nella sezione Aggiornamento del codice. La migrazione del portale gestisce solo gli indici con una configurazione dell'algoritmo di ricerca vettoriale. Crea un profilo predefinito che esegue il mapping all'algoritmo di ricerca vettoriale 2023-07-01-preview. Gli indici con più configurazioni di ricerca vettoriale richiedono la migrazione manuale.

Aggiornamento del codice per query e indici vettoriali

Il supporto per la ricerca vettoriale è stato introdotto in Creare o aggiornare l'indice (2023-07-01-preview).

L'aggiornamento dalla versione 2023-07-01-preview a qualsiasi versione stabile o di anteprima più recente richiede:

Ridenominazione e ristrutturazione della configurazione del vettore nell'indice
Riscrittura delle query vettoriali

Usare le istruzioni riportate in questa sezione per eseguire la migrazione di campi vettoriali, configurazione e query dalla versione 2023-07-01-preview.

Chiamare GET Index per recuperare la definizione esistente.

Modificare la configurazione di ricerca vettoriale. 2023-11-01 e versioni successive introducono il concetto di profili vettoriali che raggruppano configurazioni correlate al vettore con un nome. Le versioni più recenti rinominano anche algorithmConfigurations in algorithms.

Rinomina algorithmConfigurations in algorithms. Si tratta solo di una ridenominazione della matrice. Il contenuto è compatibile con le versioni precedenti. Ciò significa che è possibile usare i parametri di configurazione HNSW esistenti.
Aggiungere profiles, assegnando un nome e una configurazione dell'algoritmo per ognuno di loro.

Prima della migrazione (2023-07-01-preview):

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

Dopo la migrazione (2023-11-01):

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

Modificare le definizioni dei campi vettoriali sostituendo vectorSearchConfiguration con vectorSearchProfile. Assicurarsi che il nome del profilo venga risolto in una nuova definizione del profilo vettoriale e non nel nome di configurazione dell'algoritmo. Le altre proprietà dei campi vettoriali rimangono invariate. Ad esempio, non sono filtrabili, ordinabili o visibili, né possono usare analizzatori o normalizzatori o mappe sinonimiche.

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

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

Chiamare Crea o aggiorna indice per pubblicare le modifiche.

Modificare Cerca POST per modificare la sintassi della query. Questa modifica dell'API abilita il supporto per i tipi di query vettoriali polimorfici.

Rinomina vectors in vectorQueries.
Per ogni query vettoriale, aggiungere kind, impostandolo su vector.
Per ogni query vettoriale, rinominare value in vector.
Se si desidera, aggiungere vectorFilterMode se si usano espressioni di filtro. Il valore predefinito è prefiltro per gli indici creati dopo 2023-10-01. Gli indici creati prima di tale data supportano solo il postfiltro, indipendentemente dalla modalità di impostazione del filtro.

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

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

Questi passaggi completano la migrazione alla versione dell'API stabile 2023-11-01 o alle versioni delle API di anteprima più recenti.

Aggiornamento a 2020-06-30

In questa versione sono presenti una modifica che causa un'interruzione e diverse differenze comportamentali. Le funzionalità disponibili a livello generale includono:

Archivio conoscenze, l'archiviazione permanente di contenuti arricchiti creati tramite set di competenze, per l'analisi downstream e l'elaborazione tramite altre applicazioni. Un archivio conoscenze viene creato tramite le API REST di Azure AI Search, ma si trova in Archiviazione di Azure.

Modifica

Il codice scritto in base alle versioni precedenti dell'API si interrompe in 2020-06-30 e versioni successive se il codice contiene le funzionalità seguenti:

Qualsiasi valore letterale Edm.Date (una data composta da anno-mese-giorno, ad esempio 2020-12-12) nelle espressioni di filtro deve seguire il formato Edm.DateTimeOffset: 2020-12-12T00:00:00Z. Questa modifica è stata necessaria per gestire risultati di query errati o imprevisti a causa di differenze di fuso orario.

Modifiche del comportamento

L'algoritmo di classificazione BM25 sostituisce l'algoritmo di classificazione precedente con la tecnologia più recente. I servizi creati dopo il 2019 usano automaticamente questo algoritmo. Per i servizi meno recenti, è necessario impostare i parametri per l'uso del nuovo algoritmo.
I risultati ordinati per i valori Null sono stati modificati in questa versione, con valori Null visualizzati per primi se l'ordinamento è asc e per ultimi se l'ordinamento è desc. Se è stato scritto un codice per gestire l'ordinamento dei valori Null, tenere presente questa modifica.

Aggiornamento a 2019-05-06

Le funzionalità rese disponibili a livello generale in questa versione dell'API includono:

Completamento automatico, una funzionalità typeahead che completa un input di termine parzialmente specificato.
Tipi complessi, che forniscono supporto nativo per i dati degli oggetti strutturati nell'indice di ricerca.
Modalità di analisi JsonLines, parte dell'indicizzazione di BLOB di Azure, crea un documento di ricerca per entità JSON separata da una nuova riga.
L'arricchimento tramite intelligenza artificiale fornisce l'indicizzazione che usa i motori di arricchimento tramite intelligenza artificiale dei Servizi di Azure AI.

Modifiche di rilievo

Il codice scritto in base a una versione precedente dell'API si interrompe in 2019-05-06 e versioni successive se il codice contiene le funzionalità seguenti:

Proprietà Type per Azure Cosmos DB. Per gli indicizzatori destinati a un'origine dati API Azure Cosmos DB for NoSQL, modificare "type": "documentdb" in "type": "cosmosdb".
Se la gestione degli errori dell'indicizzatore include riferimenti alla proprietà status, è necessario rimuoverla. Lo stato è stato rimosso dalla risposta di errore perché non forniva informazioni utili.
Le stringhe di connessione dell'origine dati non vengono più restituite nella risposta. Dalle versioni API 2019-05-06 e 2019-05-06-Preview in poi, l'API dell'origine dati non restituisce più le stringhe di connessione nella risposta di qualsiasi operazione REST. Nelle versioni precedenti dell'API, per le origini dati create con POST, Azure AI Search restituiva 201 seguito dalla risposta OData, che conteneva la stringa di connessione in testo normale.
La competenza cognitiva di Riconoscimento entità denominata è stata ritirata. Se viene chiamata la competenza Riconoscimento entità denominata nel codice, la chiamata ha esito negativo. La funzionalità di sostituzione è competenza Riconoscimento entità (V3). Seguire i consigli in Competenze deprecate per eseguire la migrazione a una competenza supportata.

Aggiornamento di tipi complessi

La versione dell'API 2019-05-06 ha aggiunto il supporto formale per i tipi complessi. Se il codice ha implementato consigli precedenti per l'equivalenza dei tipi complessi in 2017-11-11-preview o 2016-09-01-preview, ci sono alcuni limiti nuovi e modificati a partire dalla versione 2019-05-06 di cui è necessario tenere presente:

I limiti relativi alla profondità dei campi secondari e al numero di raccolte complesse per indice sono stati ridotti. Se sono stati creati indici che superano questi limiti usando le versioni API di anteprima, qualsiasi tentativo di aggiornarli o ricrearli usando la versione dell'API 2019-05-06 avrà esito negativo. Se ci si trova in questa situazione, è necessario riprogettare lo schema in modo che si adatti ai nuovi limiti e quindi ricompilare l'indice.
A partire dalla versione API 2019-05-06 è previsto un nuovo limite sul numero di elementi di raccolte complesse per documento. Se sono stati creati indici con documenti che superano questi limiti usando le versioni API di anteprima, qualsiasi tentativo di reindirizzare i dati usando la versione dell'API 2019-05-06 avrà esito negativo. Se ci si trova in questa situazione, è necessario ridurre il numero di elementi di raccolta complessi per documento prima di reindicizzare i dati.

Per altre informazioni, vedere Limiti dei servizi per Azure AI Search.

Come aggiornare una struttura di tipi complessi precedente

Se il codice usa tipi complessi con una delle versioni precedenti dell'API di anteprima, è possibile che sia in uso un formato di definizione dell'indice simile al seguente:

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

Nella versione dell'API 2017-11-11-Preview è stato introdotto un formato più recente simile a un albero per la definizione dei campi di indice. Nel nuovo formato ogni campo complesso ha una raccolta di campi in cui sono definiti i relativi campi secondari. Nella versione API 2019-05-06 viene usato esclusivamente questo nuovo formato e il tentativo di creare o aggiornare un indice usando il formato precedente avrà esito negativo. Se sono stati creati indici usando il formato precedente, sarà necessario usare la versione dell'API 2017-11-11-Preview per aggiornarli al nuovo formato prima che possano essere gestiti usando la versione API 2019-05-06.

È possibile aggiornare gli indici flat al nuovo formato con la procedura seguente usando la versione dell'API 2017-11-11-Preview:

Eseguire una richiesta GET per recuperare l'indice. Se è già nel nuovo formato, è tutto pronto.
Convertire l'indice dal formato flat al nuovo formato. È necessario scrivere il codice per questa attività perché al momento della stesura di questo articolo non è disponibile codice di esempio.
Eseguire una richiesta PUT per aggiornare l'indice al nuovo formato. Evitare di modificare altri dettagli dell'indice, ad esempio la possibilità di cercare/filtrare i campi, perché le modifiche che influiscono sull'espressione fisica dell'indice esistente non sono consentite dall'API Aggiorna indice.