Condividi tramite

Creare un indice vettoriale

  • Articolo

In Azure AI Search, un archivio vettoriale ha uno schema di indice che definisce campi vettoriali e non vettoriali, una configurazione vettoriale per algoritmi che creano lo spazio di incorporamento e le impostazioni sulle definizioni di campo vettoriale usate nelle richieste di query. L'API Crea o Aggiorna indice crea l'archivio vettoriale.

Seguire questa procedura per indicizzare i dati vettoriali:

Questo articolo illustra il flusso di lavoro e usa REST per illustrare ogni passaggio. Ogni versione recente dell'API REST aggiunge nuove funzionalità. Dopo aver compreso il flusso di lavoro di base e il contenuto di ogni versione dell'API, continuare con gli esempi di codice di Azure SDK nel repository azure-search-vector-samples per indicazioni sull'uso di queste funzionalità nel codice di test e produzione.

Suggerimento

Usare il portale di Azure per creare un indice vettoriale e provare la vettorializzazione integrata.

Prerequisiti

  • Azure AI Search, in qualsiasi area e a qualsiasi livello di servizio. La maggior parte dei servizi esistenti supporta la ricerca vettoriale. Per i servizi creati prima di gennaio 2019, è presente un piccolo subset che non può creare un indice vettoriale. In questo caso, è necessario creare un nuovo servizio.

  • Incorporamenti di vettori preesistenti nei documenti di origine se si usa la versione disponibile a livello generale degli SDK di Azure e delle API REST. Per ulteriori informazioni, vedere Generare incorporamenti. Un'alternativa è la vettorializzazione integrata (anteprima).

  • È necessario conoscere il limite di dimensioni del modello usato per creare gli incorporamenti e la modalità di calcolo della somiglianza. In Azure OpenAI, per text-embedding-ada-002, la lunghezza del vettore numerico è 1536. La somiglianza viene calcolata usando cosine. I valori validi vanno da 2 a 3072 dimensioni.

  • È necessario avere familiarità con la creazione di un indice. Lo schema deve includere un campo per la chiave del documento, altri campi da cercare o filtrare e altre configurazioni di comportamenti necessari durante l'indicizzazione e le query.

Preparare i documenti per l'indicizzazione

Prima dell'indicizzazione, assemblare un payload del documento che includa campi di dati vettoriali e non vettoriali. La struttura del documento deve essere conforme allo schema dell'indice.

Assicurarsi che i documenti:

  1. Forniscano un campo o una proprietà di metadati che identifichi ogni documento in modo univoco. Tutti gli indici di ricerca richiedono una chiave del documento. Per soddisfare i requisiti della chiave del documento, un documento di origine deve avere un campo o una proprietà in grado di identificarlo in modo univoco all’interno dell'indice. Questo campo di origine deve essere mappato a un campo di indice di tipo Edm.String e key=true nell'indice di ricerca.

  2. Forniscano dati vettoriali (matrice di numeri a virgola mobile a precisione singola) nei campi di origine.

    I campi vettoriali contengono dati numerici generati da modelli di incorporamento, un incorporamento per ciascun campo. È consigliabile incorporare i modelli in Azure OpenAI, ad esempio text-embedding-ada-002 per documenti di testo o l'API REST di recupero immagini per immagini. Sono supportati solo i campi vettoriali di livello superiore dell'indice: i sottocampi vettoriali non sono attualmente supportati.

  3. Forniscano altri campi con contenuto alfanumerico leggibile per la risposta alla query e per scenari di query ibridi che includano la ricerca full-text o la classificazione semantica nella stessa richiesta.

L'indice di ricerca deve includere campi e contenuto per tutti gli scenari di query che si desidera supportare. Si supponga di voler cercare o filtrare i nomi di prodotti, versioni, metadati o indirizzi. In questo caso, la ricerca per somiglianza non è particolarmente utile. La ricerca per parole chiave, la ricerca geografica o i filtri sono una scelta migliore. Un indice di ricerca che includa una raccolta completa di campi di dati vettoriali e non vettoriali offre la massima flessibilità per la costruzione di query e risposte.

Un breve esempio di payload di documenti che include campi vettoriali e non vettoriali è disponibile nella sezione dati del vettore di caricamento di questo articolo.

Aggiungere una configurazione di ricerca vettoriale

Una configurazione vettoriale specifica l'algoritmo di ricerca vettoriale e i parametri usati durante l'indicizzazione per creare informazioni sul "vicino più prossimo" tra i nodi vettoriali:

  • Hierarchical Navigable Small World (HNSW)
  • KNN esaustivo

Se si sceglie HNSW in un campo, è possibile scegliere il KNN esaustivo in fase di query. Ma l'altra direzione non funziona: se si sceglie esaustiva, non è possibile richiedere successivamente la ricerca HNSW perché le strutture di dati aggiuntive che consentono la ricerca approssimativa non esistono.

Per informazioni sulla procedura di migrazione delle versioni da anteprima a stabile, vedere Aggiornare le API REST.

2023-11-01 è disponibile a livello generale. Supporta una configurazione vettoriale con:

  • vectorSearch.algorithms con parametri per l'indicizzazione e l'assegnazione dei punteggi.
  • vectorSearch.profiles per più combinazioni di configurazioni dell'algoritmo.

Assicurarsi di avere una strategia per vettorializzare il proprio contenuto. La versione stabile non fornisce competenze o vettorizzatori per la codifica predefinita.

  1. Usare l'API Crea o aggiorna indice per creare l'indice.

  2. Aggiungere una sezione vectorSearch nell'indice che specifichi gli algoritmi di ricerca usati per creare lo spazio di incorporamento.

     "vectorSearch": {
     "algorithms": [
         {
             "name": "my-hnsw-config-1",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 4,
                 "efConstruction": 400,
                 "efSearch": 500,
                 "metric": "cosine"
             }
         },
         {
             "name": "my-hnsw-config-2",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 8,
                 "efConstruction": 800,
                 "efSearch": 800,
                 "metric": "cosine"
             }
         },
         {
             "name": "my-eknn-config",
             "kind": "exhaustiveKnn",
             "exhaustiveKnnParameters": {
                 "metric": "cosine"
             }
         }

     ],
     "profiles": [
       {
         "name": "my-default-vector-profile",
         "algorithm": "my-hnsw-config-2"
       }
     ]
 }

    Punti principali:

    • Nome della configurazione. Il nome deve essere univoco all'interno dell'indice.
    • profiles aggiungere un livello di astrazione per includere definizioni più complete. Un profilo viene definito in vectorSearch; quindi, vi viene fatto riferimento tramite il suo nome in ogni campo vettore.
    • "hnsw" e "exhaustiveKnn" sono gli algoritmi Vicino più prossimo approssimativo (ANN) usati per organizzare il contenuto vettoriale durante l'indicizzazione.
    • Il valore predefinito di "m" (conteggio dei collegamenti bidirezionali) è 4. L'intervallo è compreso tra i valori 4 e 10. I valori più bassi dovrebbero restituire un livello inferiore di rumore nei risultati.
    • Il valore predefinito di "efConstruction" è 400. L'intervallo è compreso tra i valori 100 e 1,000. È il numero di vicini più prossimi usati durante l'indicizzazione.
    • Il valore predefinito di "efSearch" è 500. L'intervallo è compreso tra i valori 100 e 1,000. È il numero di vicini più prossimi usati durante la ricerca.
    • Se si sta usando Azure OpenAI, "metric" deve essere "coseno". In caso contrario, usare la metrica di somiglianza associata al modello di incorporamento in uso. I valori supportati sono cosine, dotProduct, euclidean.

Aggiungere un campo vettoriale alla raccolta campi

La raccolta campi deve includere un campo per la chiave del documento, i campi vettoriali e tutti gli altri campi necessari per gli scenari di ricerca ibrida.

I campi vettoriali sono caratterizzati dal tipo di dati, da una dimensions proprietà basata sul modello di incorporamento usato per l'output dei vettori e da un profilo vettoriale.

Usare questa versione se si desiderano solo funzionalità disponibili a livello generale.

  1. Usare l'istruzione Crea o aggiorna indice per creare l'indice.

  2. Definire un campo vettoriale con gli attributi seguenti. È possibile archiviare un oggetto di incorporamento generato per ciascun campo. Per ogni campo vettoriale:

    • type deve trovarsi Collection(Edm.Single) in questa versione dell'API.
    • dimensions è il numero di dimensioni generate dal modello di incorporamento. Per text-embedding-ada-002, è 1536.
    • vectorSearchProfile è il nome di un profilo definito altrove nell'indice.
    • searchable deve essere true.
    • retrievable può essere true o false. True restituisce i vettori non elaborati (1536) come testo normale e utilizza spazio di archiviazione. Impostare su true se si sta passando un risultato vettoriale a un'app downstream.
    • filterable, facetable, sortable devono essere false.

  3. Aggiungere campi non vettoriali filtrabili alla raccolta, come "title" con filterable impostato su true, se si desidera richiamare il prefiltraggio o il postfiltraggio nella query vettoriale.

  4. Aggiungere altri campi che definiscano la sostanza e la struttura del contenuto testuale indicizzato. È necessaria almeno una chiave del documento.

    È anche necessario aggiungere campi che saranno utili nella query o nella risposta. L'esempio seguente mostra campi vettoriali per titolo e contenuto ("titleVector", "contentVector") analoghi ai vettori. Fornisce anche campi per contenuto testuale analogo ("titolo", "contenuto") utile per l'ordinamento, il filtraggio e la lettura in un risultato di ricerca.

    L'esempio seguente mostra la raccolta di campi:

    PUT https://my-search-service.search.windows.net/indexes/my-index?api-version=2023-11-01&allowIndexDowntime=true
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "name": "{{index-name}}",
    "fields": [
        {
            "name": "id",
            "type": "Edm.String",
            "key": true,
            "filterable": true
        },
        {
            "name": "title",
            "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
        },
        {
            "name": "titleVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-default-vector-profile"
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": true,
            "dimensions": 1536,
            "vectorSearchProfile": "my-default-vector-profile"
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "my-hnsw-config-1",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [
            {
                "name": "my-default-vector-profile",
                "algorithm": "my-hnsw-config-1"
            }
        ]
    }
}

Caricare i dati vettoriali per l'indicizzazione

Il contenuto fornito per l'indicizzazione deve essere conforme allo schema di indice e includere un valore stringa univoco per la chiave del documento. I dati prevettorializzati vengono caricati in uno o più campi vettoriali, che possono coesistere con altri campi contenenti contenuto alfanumerico.

È possibile usare metodologie push o pull per l'inserimento dati.

Usare Documents - Index per caricare dati vettoriali e non di operatore in un indice. Le API push per l'indicizzazione sono identiche in tutte le versioni stabili e di anteprima. Usare una delle API seguenti per caricare i documenti:

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/index?api-version=2023-11-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "value": [
        {
            "id": "1",
            "title": "Azure App Service",
            "content": "Azure App Service is a fully managed platform for building, deploying, and scaling web apps. You can host web apps, mobile app backends, and RESTful APIs. It supports a variety of programming languages and frameworks, such as .NET, Java, Node.js, Python, and PHP. The service offers built-in auto-scaling and load balancing capabilities. It also provides integration with other Azure services, such as Azure DevOps, GitHub, and Bitbucket.",
            "category": "Web",
            "titleVector": [
                -0.02250031754374504,
                 . . . 
                        ],
            "contentVector": [
                -0.024740582332015038,
                 . . .
            ],
            "@search.action": "upload"
        },
        {
            "id": "2",
            "title": "Azure Functions",
            "content": "Azure Functions is a serverless compute service that enables you to run code on-demand without having to manage infrastructure. It allows you to build and deploy event-driven applications that automatically scale with your workload. Functions support various languages, including C#, F#, Node.js, Python, and Java. It offers a variety of triggers and bindings to integrate with other Azure services and external services. You only pay for the compute time you consume.",
            "category": "Compute",
            "titleVector": [
                -0.020159931853413582,
                . . .
            ],
            "contentVector": [
                -0.02780858241021633,
                 . . .
            ],
            "@search.action": "upload"
        }
        . . .
    ]
}

Controllare l'indice per il contenuto vettoriale

A fini di convalida, è possibile eseguire query sull'indice usando Esplora ricerche nel portale di Azure o una chiamata API REST. Poiché Azure AI Search non è in grado di convertire un vettore in testo leggibile, provare a restituire campi dallo stesso documento come riscontro della corrispondenza. Ad esempio, se la query vettoriale è destinata al campo "titleVector", è possibile selezionare "title" per i risultati della ricerca.

Perché siano inclusi nei risultati, i campi devono essere attribuiti come "retrievable".

È possibile usare Esplora ricerche per eseguire query su un indice. Esplora ricerche ha due visualizzazioni: Visualizzazione query (predefinita) e Visualizzazione JSON.

  • Usare la visualizzazione JSON per le query vettoriali, incollando in una definizione JSON della query vettoriale che si vuole eseguire.

  • Usare la vista query predefinita per ottenere rapida conferma che l'indice contenga vettori. La vista query è per la ricerca full-text. Anche se non è possibile usarla per le query vettoriali, è possibile inviare una ricerca vuota (search=*) per verificare la presenza di contenuto. Il contenuto di tutti i campi, inclusi i campi vettoriali, viene restituito come testo normale.

Aggiornare un archivio vettoriale

Per aggiornare un archivio vettoriale, modificare lo schema e, se necessario, ricaricare i documenti per popolare nuovi campi. Le API per gli aggiornamenti dello schema includono Creare o aggiornare l'indice (REST), CreateOrUpdateIndex in Azure SDK per .NET, create_or_update_index in Azure SDK per Python e metodi simili in altri SDK di Azure.

Le linee guida standard per l'aggiornamento di un indice sono illustrate in Eliminare e ricompilare un indice.

I punti chiave includono:

  • L'eliminazione e la ricompilazione sono spesso necessarie per aggiornamenti ed eliminazione di campi esistenti.

  • Tuttavia, è possibile aggiornare uno schema esistente con le modifiche seguenti, senza che sia necessaria alcuna ricompilazione:

    • Aggiungere nuovi campi a una raccolta campi.
    • Aggiungere nuove configurazioni vettoriali assegnate ai nuovi campi, ma non ai campi esistenti che sono già stati vettorializzati.
    • Modificare "retrievable" (i valori sono true o false) in un campo esistente. I campi vettoriali devono essere ricercabili e recuperabili, ma se si vuole disabilitare l'accesso a un campo vettoriale in situazioni in cui l'eliminazione e la ricompilazione non sono fattibili, è possibile impostare recuperabile su false.

Passaggi successivi

Come passaggio successivo, è consigliabile Eseguire query sui dati vettoriali in un indice di ricerca.

Gli esempi di codice nel repository azure-search-vector illustrano flussi di lavoro end-to-end che includono definizione dello schema, vettorizzazione, indicizzazione e query.

È disponibile codice demo per Python, C# e JavaScript.