Eseguire l'aggiornamento all'API REST più recente in Ricerca di intelligenza artificiale di Azure

  • Articolo

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

Nota

La documentazione di riferimento dell'API REST è ora disponibile per il controllo delle versioni. Per ottenere il contenuto corretto, aprire una pagina di riferimento e quindi filtrare in base alla versione usando il selettore che si trova sopra il sommario.

Quando eseguire l'aggiornamento

Ricerca di intelligenza artificiale di Azure 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 deprecata ed è soggetta a una o più modifiche di rilievo. Le versioni API che rientrano in questa categoria includono 2023-07-10-preview per vettori e 2019-05-06.

  • 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 e 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) da una risposta GET.

  • Se è necessario recuperare chiavi API di amministrazione o query per il servizio di ricerca, usare le API REST di gestione.

  • Se è necessario recuperare stringa di connessione di un'altra risorsa di Azure, ad esempio Archiviazione di Azure o Azure Cosmos DB, usare le API della risorsa e le indicazioni pubblicate per ottenere le informazioni.

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

Questa sezione illustra il percorso di migrazione da 2023-07-01-preview a 2023-10-01-preview. È consigliabile eseguire la migrazione a 2023-10-01-preview se si vogliono usare le funzionalità vettoriali ancora in anteprima pubblica. Se non sono necessarie le funzionalità di anteprima, è consigliabile eseguire l'aggiornamento alla versione stabile 2023-11-01.

Le funzionalità di anteprima includono:

Poiché queste funzionalità non esistevano nelle versioni precedenti dell'API, non esiste alcun percorso di migrazione. Per informazioni su come aggiungere queste funzionalità al codice, vedere esempi di codice e procedure dettagliate.

Al contrario, le definizioni dei campi vettoriali, la configurazione dell'algoritmo di ricerca vettoriale e la sintassi delle query vettoriali introdotte per la prima volta nel 2023-07-01-preview sono state modificate. La sintassi 2023-10-01-preview per i campi vettoriali, gli algoritmi e le query vettoriali è identica alla sintassi 2023-11-01. I passaggi di migrazione per questi costrutti vettoriali sono illustrati nell'aggiornamento a 2023-11-01.

Aggiornamento del portale per gli indici vettoriali

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

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

Non è disponibile alcuna migrazione del portale per l'aggiornamento della sintassi delle query vettoriali. Per le modifiche alla sintassi delle query, vedere l'aggiornamento alla versione 2023-11-01 .

Prima di selezionare Esegui migrazione, selezionare Modifica JSON per esaminare prima lo schema aggiornato. È necessario trovare uno schema conforme alle modifiche descritte nell'aggiornamento a 2023-11-01. 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 alla versione 2023-11-01

Questa versione presenta modifiche di rilievo e differenze comportamentali per il supporto della classificazione semantica e della ricerca vettoriale.

  • La classificazione semantica è disponibile a livello generale nel 2023-11-01. Non usa più la queryLanguage proprietà . Richiede anche una semanticConfiguration definizione. Un semanticConfiguration oggetto searchFields sostituisce nelle versioni precedenti. Per la procedura, vedere Eseguire la migrazione dalla versione di anteprima.

  • Il supporto per la ricerca vettoriale è stato introdotto in Create or Update Index (2023-07-01-preview). L'aggiornamento dalla versione 2023-07-01-preview richiede la ridenominazione e la ristrutturazione della configurazione del vettore nell'indice. Richiede anche la riscrittura delle query vettoriali. Usare le istruzioni riportate in questa sezione per eseguire la migrazione di campi vettoriali, configurazione e query.

    Se si esegue l'aggiornamento da 2023-10-01-preview a 2023-11-01, non sono presenti modifiche di rilievo, ma esiste una differenza di comportamento: l'impostazione vectorFilterMode predefinita è stata modificata dal filtro postfiltro al prefiltro per le espressioni di filtro. Se il codice 2023-10-01-preview non è impostato vectorFilterMode in modo esplicito, assicurarsi di comprendere il nuovo comportamento predefinito o esplicito impostato su vectorFilterMode postfilter per mantenere il comportamento precedente.

Ecco i passaggi per la migrazione dal 2023-07-01-preview al 2023-11-01:

  1. Chiamare Get Index per recuperare la definizione esistente.

  2. Modificare la configurazione della ricerca vettoriale. 2023-11-01 introduce il concetto di profili vettoriali che raggruppano configurazioni correlate al vettore con un nome. Rinomina algorithmConfigurationsalgorithmsanche .

    • 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 essi.

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

  3. 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. Altre proprietà dei campi vettoriali rimangono invariate. Ad esempio, non possono essere filtrabili, ordinabili o visibili, né 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"
  }

  4. Chiamare Crea o Aggiorna indice per pubblicare le modifiche.

  5. Modificare Search 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.
    • Facoltativamente, aggiungere vectorFilterMode se si usano espressioni di filtro. Il valore predefinito è prefiltro per gli indici creati dopo il 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 api 2023-11-01.

Aggiornamento alla versione 2020-06-30

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

  • Archivio conoscenze, archiviazione permanente di contenuti arricchiti creati tramite set di competenze, creati per l'analisi downstream e l'elaborazione tramite altre applicazioni. Un archivio conoscenze viene creato tramite le API REST di Ricerca intelligenza artificiale di Azure, ma risiede in Archiviazione di Azure.

Modifica

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

  • Qualsiasi Edm.Date valore letterale (una data composta da anno-mese-giorno, ad esempio 2020-12-12) nelle espressioni di filtro deve seguire il Edm.DateTimeOffset formato : 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 una 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 l'ultimo se l'ordinamento è desc. Se è stato scritto codice per gestire l'ordinamento dei valori Null, tenere presente questa modifica.

Aggiornamento alla versione 2019-05-06

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

Modifiche di rilievo

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

  1. Proprietà Type per Azure Cosmos DB. Per gli indicizzatori destinati a un'origine dati dell'API NoSQL per Azure Cosmos DB, passare "type": "documentdb" a "type": "cosmosdb".

  2. Se la gestione degli errori dell'indicizzatore include riferimenti alla status proprietà , è necessario rimuoverlo. Lo stato è stato rimosso dalla risposta di errore perché non fornisce informazioni utili.

  3. Le stringa di connessione dell'origine dati non vengono più restituite nella risposta. Da versioni 2019-05-06 API e 2019-05-06-Preview successive, l'API dell'origine dati non restituisce più stringa di connessione nella risposta di qualsiasi operazione REST. Nelle versioni precedenti dell'API, per le origini dati create con POST, Ricerca di intelligenza artificiale di Azure ha restituito il 201 seguito dalla risposta OData, che conteneva il stringa di connessione in testo normale.

  4. La competenza cognitiva Riconoscimento entità denominata viene ritirata. Se è stata chiamata la competenza Riconoscimento entità nome nel codice, la chiamata ha esito negativo. La funzionalità di sostituzione è Competenza riconoscimento entità (V3). Seguire le indicazioni riportate in Competenze deprecate per eseguire la migrazione a una competenza supportata.

Aggiornamento di tipi complessi

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

  • I limiti relativi alla profondità dei sottocampi 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 2019-05-06 dell'API 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.

  • È previsto un nuovo limite a partire dalla versione 2019-05-06 API per il 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 reindicizzare i dati usando api-version 2019-05-06 avrà esito negativo. Se ci si trova in questa situazione, è necessario ridurre il numero di elementi di raccolta complessi per ogni documento prima di reindicizzare i dati.

Per altre informazioni, vedere Limiti dei servizi per Ricerca di intelligenza artificiale di Azure.

Come aggiornare una struttura di tipi complessi precedente

Se il codice usa tipi complessi con una delle versioni precedenti dell'API di anteprima, è possibile usare 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 2017-11-11-Previewdell'API è stato introdotto un formato simile ad albero più recente 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 questo nuovo formato viene usato esclusivamente 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, è necessario usare la versione 2017-11-11-Preview dell'API 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 2017-11-11-Previewdell'API :

  1. Eseguire una richiesta GET per recuperare l'indice. Se è già nel nuovo formato, l'operazione è stata completata.

  2. Convertire l'indice dal formato flat al nuovo formato. È necessario scrivere codice per questa attività perché al momento della stesura di questo articolo non è disponibile codice di esempio.

  3. Eseguire una richiesta PUT per aggiornare l'indice al nuovo formato. Evitare di modificare altri dettagli dell'indice, ad esempio la ricerca/filtrabilità dei campi, perché le modifiche che influiscono sull'espressione fisica dell'indice esistente non sono consentite dall'API Aggiorna indice.

Nota

Non è possibile gestire gli indici creati con il formato "flat" precedente dal portale di Azure. Aggiornare gli indici dalla rappresentazione "flat" alla rappresentazione "albero" nella prima comodità.

Passaggi successivi

Esaminare la documentazione di riferimento dell'API REST di ricerca. In caso di problemi, chiedere assistenza su Stack Overflow o contattare il supporto tecnico.

Informazioni di riferimento sulle API REST servizio di ricerca