Condividi tramite

Creare un indice vettoriale

In Ricerca di intelligenza artificiale di Azure è possibile archiviare i vettori in un indice di ricerca e inviare query vettoriali per la corrispondenza in base alla somiglianza semantica. Un indice vettoriale è definito da uno schema di indice con campi vettoriali, campi non di operatore e una sezione di configurazione vettoriale.

Crea o aggiorna l'Index API crea lo store vettoriale. Seguire questa procedura per indicizzare i vettori in Ricerca di intelligenza artificiale di Azure:

  • Iniziare con una definizione di schema di base
  • Aggiungere algoritmi vettoriali e compressione facoltativa
  • Aggiungere le definizioni dei campi vettoriali
  • Caricare dati prevettori come passaggio separato o usare la vettorizzazione integrata per la suddivisione in blocchi e l'incorporamento dei dati durante l'indicizzazione

Questo articolo illustra il flusso di lavoro usando l'API REST per l'illustrazione. Dopo aver compreso il flusso di lavoro di base, continuare con gli esempi di codice di Azure SDK nel repository azure-search-vector-samples per indicazioni sull'uso dei vettori nel codice di test e produzione.

Suggerimento

È anche possibile usare il portale di Azure per creare un indice vettoriale e provare la suddivisione in blocchi e la vettorizzazione dei dati integrati.

Prerequisiti

  • Azure AI Search, in qualsiasi area e a qualsiasi livello. Se si prevede di usare la vettorizzazione integrata con le capacità e i vettorizzatori di Azure AI, la ricerca Azure AI deve essere nella stessa area dei modelli di incorporamento ospitati in Azure AI Vision.

  • I documenti di origine devono avere incorporamenti vettoriali da caricare nell'indice. In alternativa, è possibile usare la vettorizzazione integrata per questo passaggio.

  • È necessario conoscere il limite di dimensioni del modello usato per creare gli incorporamenti in modo da poter assegnare tale limite al campo vettoriale. Per text-embedding-ada-002, le dimensioni sono fisse a 1536. Per text-embedding-3-small o text-embedding-3-large, le dimensioni variano rispettivamente da 1 a 1536 e da 1 a 3072.

  • È anche necessario conoscere la metrica di somiglianza da usare. Per l'incorporamento di modelli in Azure OpenAI, la somiglianza viene calcolata usando cosine.

  • È necessario avere familiarità con la creazione di un indice. Uno schema include sempre un campo per la chiave del documento, i campi usati per la ricerca o i filtri e altre configurazioni per i comportamenti necessari durante l'indicizzazione e le query.

Limitazioni

Per i servizi di ricerca creati prima di gennaio 2019, è presente un piccolo subset che non può creare un indice vettoriale. Se questo vale per l'utente, creare un nuovo servizio per l'uso di vettori.

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 alla raccolta di campi dello schema dell'indice.

Assicurarsi che i documenti di origine forniscano il contenuto seguente:

Contenuto Descrizione
Identificatore univoco Campo o proprietà di metadati che identifica in modo univoco ogni documento. 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à che lo identifica in modo univoco nell'indice. Se si esegue l'indicizzazione di BLOB, potrebbe trattarsi del metadata_storage_path che identifica in modo univoco ogni BLOB. Se si esegue l'indicizzazione da un database, potrebbe trattarsi di chiave primaria. Questo campo di origine deve essere mappato a un campo di indice di tipo Edm.String e key=true nell'indice di ricerca.
Contenuto non vettoriale Fornire altri campi con contenuto leggibile. Contenuto leggibile dagli umani è utile per la risposta alla query e per gli scenari di query ibrida che includono la ricerca a testo completo o la classificazione semantica nella medesima richiesta. Se si usa un modello di completamento della chat, la maggior parte dei modelli come ChatGPT prevede testo leggibile e non accetta vettori non elaborati come input.
Contenuto vettoriale Versione vettorializzata del contenuto non vettoriale. I vettori vengono usati in fase di query. Un vettore è una matrice di numeri a virgola mobile a precisione singola generati da un modello di incorporamento. Ogni campo vettore contiene una matrice generata da un modello di incorporamento, una per campo, in cui il campo è un campo di primo livello (non parte di un tipo annidato o complesso). Per l'integrazione più semplice, è consigliabile usare i modelli di incorporamento in Azure OpenAI, ad esempio un modello text-embedding-3 per i documenti di testo o l'API REST Di recupero immagini per immagini e incorporamenti bidirezionali.

Se è possibile prendere una dipendenza da indicizzatori e set di competenze, è consigliabile usare la vettorizzazione integrata che codifica immagini e contenuto testuale durante l'indicizzazione. Le definizioni dei campi sono per i campi vettoriali, ma i dati di origine in ingresso possono essere testo o immagini, che vengono convertiti in matrici vettoriali durante l'indicizzazione.

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 di somiglianza vettoriale non è particolarmente utile. La ricerca di parole chiave, la ricerca geografica o i filtri che iterano sul contenuto verbatim sarebbero una scelta migliore. Un indice di ricerca che include sia campi vettoriali sia non vettoriali offre la massima flessibilità per la costruzione delle query e la composizione delle 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.

Iniziare con un indice di base

Iniziare con uno schema minimo in modo da avere una definizione da usare prima di aggiungere una configurazione vettoriale e campi vettoriali. Un indice semplice potrebbe essere simile all'esempio seguente. Per altre informazioni su uno schema di indice, vedere Creare un indice di ricerca.

Si noti che ha un nome obbligatorio, una chiave del documento obbligatoria ("key": true) e campi per il contenuto leggibile in testo normale. È comune avere una versione leggibile di qualsiasi contenuto che si intende vettorizzare. Ad esempio, se si dispone di un blocco di testo da un file PDF, lo schema dell'indice deve avere un campo per blocchi di testo normale e un secondo campo per blocchi vettorializzati.

Ecco un indice di base con un nome, una raccolta di campi e altri costrutti per una configurazione aggiuntiva.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "example-index",
  "fields": [
    { "name": "documentId", "type": "Edm.String", "key": true, "retrievable": true, "searchable": true, "filterable": true },
    { "name": "myHumanReadableNameField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": true, "facetable": false },
    { "name": "myHumanReadableContentField", "type": "Edm.String", "retrievable": true, "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
  ],
  "analyzers": [ ],
  "scoringProfiles": [ ],
  "suggesters": [ ],
  "vectorSearch": [ ]
}

Aggiungere una configurazione di ricerca vettoriale

Aggiungere quindi una configurazione "vectorSearch" allo schema. È utile specificare prima una configurazione, prima delle definizioni dei campi, perché i profili definiti qui diventano parte della definizione del campo vettoriale. Nello schema, la configurazione vettoriale viene in genere inserita dopo la raccolta di campi, ad esempio dopo "analyzers", "scoringProfiles"e "suggesters" (anche se l'ordine non è rilevante).

Una configurazione vettoriale include:

  • vectorSearch.algorithms utilizzato durante l'indicizzazione per creare informazioni sul "vicino più vicino" tra i nodi vettoriali.
  • vectorSearch.compressions per la quantizzazione scalare o binaria, il sovracampionamento e la ricategorizzazione con vettori originali.
  • vectorSearch.profiles per specificare più combinazioni di configurazioni di algoritmo e compressione.

2024-07-01 è disponibile a livello generale. Supporta una configurazione vettoriale con:

  • Algoritmo Mondo Piccolo Navigabile Gerarchico (HNSW)
  • Algoritmo K-Nearest Neighbor (KNN) completo
  • Compressione scalare
  • Compressione binaria (disponibile solo nel 2024-07-01 e nei pacchetti azure SDK più recenti)
  • Sovracampionamento
  • Ricategorizzazione con vettori originali

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 per l'indicizzazione, non è possibile richiedere successivamente la ricerca HNSW perché le strutture di dati aggiuntive che abilitano la ricerca approssimativa non esistono.

Assicurarsi di avere una strategia per vettorializzare il proprio contenuto. È consigliabile usare la vettorizzazione integrata e i vettorizzatori in fase di query per la codifica incorporata.

  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": {
     "compressions": [
         {
             "name": "scalar-quantization",
             "kind": "scalarQuantization",
             "rerankWithOriginalVectors": true,
             "defaultOversampling": 10.0,
                 "scalarQuantizationParameters": {
                     "quantizedDataType": "int8"
                 }
         },
         {
             "name": "binary-quantization",
             "kind": "binaryQuantization",
             "rerankWithOriginalVectors": true,
             "defaultOversampling": 10.0
         }
     ],
     "algorithms": [
         {
             "name": "hnsw-1",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 4,
                 "efConstruction": 400,
                 "efSearch": 500,
                 "metric": "cosine"
             }
         },
         {
             "name": "hnsw-2",
             "kind": "hnsw",
             "hnswParameters": {
                 "m": 8,
                 "efConstruction": 800,
                 "efSearch": 800,
                 "metric": "hamming"
             }
         },
         {
             "name": "eknn",
             "kind": "exhaustiveKnn",
             "exhaustiveKnnParameters": {
                 "metric": "euclidean"
             }
         }

     ],
     "profiles": [
       {
         "name": "vector-profile-hnsw-scalar",
         "compression": "scalar-quantization",
         "algorithm": "hnsw-1"
       }
     ]
 }

    Punti principali:

    • I nomi per ogni configurazione di compressione, algoritmo e profilo devono essere univoci per il tipo all'interno dell'indice.

    • vectorSearch.compressions può essere scalarQuantization o binaryQuantization. La quantizzazione scalare comprime i valori a virgola mobile in tipi di dati più ristretti. La quantizzazione binaria converte float in valori binari a 1 bit.

    • vectorSearch.compressions.rerankWithOriginalVectors usa i vettori originali non compressi per ricalcolare la somiglianza e ricategorizzare i risultati principali restituiti dalla query di ricerca iniziale. I vettori non compressi sono presenti nell'indice di ricerca anche se stored è false. Questa proprietà è facoltativa. Il valore predefinito è vero.

    • vectorSearch.compressions.defaultOversampling considera un set più ampio di potenziali risultati per compensare la riduzione delle informazioni dalla quantizzazione. La formula per i risultati potenziali è costituita dak nella query, con un moltiplicatore di sovracampionamento. Ad esempio, se la query specifica un k di 5 e se il sovracampionamento è 20, la query richiede di fatto 100 documenti per l'uso durante la ricategorizzazione, usando il vettore originale non compresso a tale scopo. Vengono forniti solo i primi k risultati riclassificati. Questa proprietà è facoltativa. Il valore predefinito è 4.

    • vectorSearch.compressions.scalarQuantizationParameters.quantizedDataTypeDeve essere impostato su int8. Questo è l'unico tipo di dati primitivo attualmente supportato. Questa proprietà è facoltativa. Il valore predefinito è int8.

    • vectorSearch.algorithms sono "hnsw" o "exhaustiveKnn". Questi sono gli algoritmi di vicinato approssimato (ANN) utilizzati per organizzare il contenuto vettoriale durante l'indicizzazione.

    • vectorSearch.algorithms.m è il numero di collegamenti bidirezionali. Il valore predefinito è 4. L'intervallo è compreso tra i valori 4 e 10. I valori più bassi dovrebbero restituire un livello inferiore di rumore nei risultati.

    • vectorSearch.algorithms.efConstruction è il numero di vicini più prossimi usati durante l'indicizzazione. Il valore predefinito è 400. L'intervallo è compreso tra i valori 100 e 1,000.

    • "vectorSearch.algorithms.efSearch è il numero di vicini più prossimi usati durante la ricerca. Il valore predefinito è 500. L'intervallo è compreso tra i valori 100 e 1,000.

    • Se si sta usando Azure OpenAI, vectorSearch.algorithms.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, hamming (usato per l’indicizzazione di dati binari).

    • vectorSearch.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. Si tratta di una combinazione di configurazioni di compressione e algoritmo. Questa è la proprietà che si assegna a un campo vettoriale e determina l'algoritmo e la compressione dei campi.

Aggiungi un campo vettoriale alla collezione di campi

Dopo aver creato una configurazione vettoriale, è possibile aggiungere un campo vettore alla raccolta di campi. Tenere presente che la raccolta di campi deve includere un campo per la chiave del documento, i campi vettoriali e tutti gli altri campi non vettoriali necessari per gli scenari di ricerca ibrida o il completamento del modello di chat nei carichi di lavoro RAG.

I campi vettoriali sono caratterizzati dal tipo di dati, da una dimensions proprietà basata sul modello di incorporamento usato per restituire i vettori e da un profilo vettoriale creato in un passaggio precedente.

2024-07-01 è disponibile a livello generale.

  1. Utilizzare Crea o Aggiorna Indice per creare l'indice e aggiungere un campo vettore alla raccolta di campi.

    {
  "name": "example-index",
  "fields": [
    {
        "name": "contentVector",
        "type": "Collection(Edm.Single)",
        "searchable": true,
        "retrievable": false,
        "stored": false,
        "dimensions": 1536,
        "vectorSearchProfile": "vector-profile-1"
    }
  ]
}

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

    • type deve essere un tipo di dati vettoriale. Collection(Edm.Single) è il più comune per l'incorporamento dei modelli.
    • dimensions è il numero di dimensioni generate dal modello di incorporamento. Per text-embedding-ada-002, è fisso a 1536. Per la serie di modelli text-embedding-3, è disponibile un intervallo di valori. Se si usa la vettorializzazione integrata e una competenza di incorporamento per generare vettori, assicurarsi che questa proprietà sia impostata sullo stesso valore delle dimensioni usato dalla competenza di incorporamento.
    • vectorSearchProfile è il nome di un profilo definito altrove nell'indice.
    • searchable deve essere vero.
    • retrievable può essere true o false. True restituisce i vettori non elaborati (1.536 di essi) come testo normale e utilizza lo spazio di archiviazione. Impostare su true se si sta passando un risultato vettoriale a un'app downstream.
    • stored può essere true o false. Determina se per il recupero viene archiviata una copia aggiuntiva di vettori. Per altre informazioni, vedere Ridurre le dimensioni dei vettori.
    • 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=2024-07-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,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        },
        {
            "name": "content",
            "type": "Edm.String",
            "searchable": true,
            "retrievable": true
        },
        {
            "name": "contentVector",
            "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-1"
        }
    ],
    "vectorSearch": {
        "algorithms": [
            {
                "name": "hnsw-1",
                "kind": "hnsw",
                "hnswParameters": {
                    "m": 4,
                    "efConstruction": 400,
                    "efSearch": 500,
                    "metric": "cosine"
                }
            }
        ],
        "profiles": [
            {
                "name": "vector-profile-1",
                "algorithm": "hnsw-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 pre-vettorizzati vengono caricati in uno o più campi vettoriali, che possono coesistere con altri campi contenenti contenuti non vettoriali.

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

Usare Documenti - Indice per caricare in un indice dati vettoriali e non vettoriali. 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=2024-07-01

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

Eseguire una query nell'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 "recuperabili".

  • Esaminare gli indici in Gestione della ricerca>Indici per visualizzare le dimensioni complessive dell’indice e le dimensioni dell’indice vettoriale. Una dimensione dell'indice vettoriale positiva indica che sono presenti vettori.

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

    • Impostare Opzioni query>Nascondere i valori vettoriali nei risultati della ricerca per ottenere risultati più leggibili.

    • Usare la visualizzazione JSON per le query vettoriali. È possibile incollare in una definizione JSON della query vettoriale da eseguire oppure usare la conversione da testo a vettore o da immagine a vettore incorporata se l'indice ha un'assegnazione di vettore. Per ulteriori informazioni sulla ricerca di immagini, consulta Guida introduttiva: Ricerca di immagini in Esplora ricerche.

    • Usare la vista query predefinita per ottenere rapida conferma che l'indice contenga vettori. La vista query è per la ricerca di testo completo. 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.

Per altre informazioni, vedere Creare una query vettoriale.

Aggiornare un archivio vettoriale

Per aggiornare un archivio vettoriale, modificare lo schema e 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 completa dell'indice sono spesso necessarie per gli aggiornamenti e l'eliminazione dei campi esistenti.

  • È possibile apportare alcune modifiche senza requisiti di ricompilazione:

    • Aggiungere nuovi campi a una raccolta di campi.
    • Aggiungere nuove configurazioni vettoriali, assegnate ai nuovi campi, ma non ai campi esistenti già 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-samples illustrano flussi di lavoro end-to-end che includono definizione dello schema, vettorizzazione, indicizzazione e query.

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