Condividi tramite

Creare un indice vettoriale

In Ricerca di intelligenza artificiale di Azure è possibile usare Create or Update Index (API REST) per archiviare i vettori in un indice di ricerca. Un indice vettoriale è definito da uno schema di indice con campi vettoriali, campi non di operatore e una sezione di configurazione vettoriale.

Quando si crea un indice vettoriale, si crea in modo implicito uno spazio di incorporamento che funge da corpus per le query vettoriali. Lo spazio di incorporamento è costituito da tutti i campi vettoriali popolati con incorporamenti dallo stesso modello di incorporamento. In fase di query, il sistema confronta la query vettoriale con i vettori indicizzati, restituendo risultati in base alla somiglianza semantica.

Per indicizzare i vettori in Ricerca di intelligenza artificiale di Azure, seguire questa procedura:

  • Iniziare con una definizione di schema di base.
  • Aggiungere algoritmi vettoriali e compressione facoltativa.
  • Aggiungere definizioni di campo vettoriale.
  • 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 usa 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 , che fornisce 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

  • Un servizio ricerca di intelligenza artificiale di Azure in qualsiasi area e in 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. È anche possibile usare la vettorizzazione integrata per questo passaggio.

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

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

  • È necessario sapere come creare un indice. Uno schema include sempre un campo per la chiave del documento, i campi per la ricerca o i filtri e altre configurazioni per i comportamenti necessari durante l'indicizzazione e le query.

Limitazioni

Alcuni servizi di ricerca creati prima di gennaio 2019 non possono 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. Il contenuto leggibile è utile per la risposta alle query e per le query ibride che includono la ricerca a testo completo o la classificazione semantica nella stessa interrogazione. 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 Rappresentazione vettorializzata del contenuto nonvector da usare 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 dal modello. Esiste un'incorporamento per campo, dove il campo è un campo di primo livello (non parte di un tipo annidato o complesso). Per una semplice integrazione, è consigliabile incorporare modelli in Azure OpenAI, come text-embedding-3 per documenti di testo o l'API REST di recupero immagini per immagini e incorporamenti multimodali.

Se è possibile usare indicizzatori e set di competenze, prendere in considerazione la vettorizzazione integrata, che codifica immagini e testo 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.

Per un breve esempio di payload di documenti che include campi vettoriali e non vettoriali, vedere la sezione load vector data 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 l'indice 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 i blocchi vettorializzati.

Ecco un indice di base con un "name", una raccolta "fields" e altri costrutti per una configurazione aggiuntiva.

POST https://[servicename].search.windows.net/indexes?api-version=[api-version] 
{
  "name": "example-index",
  "description": "This is an 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 "vectorSearch" configurazione allo schema. È utile specificare 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". Tuttavia, l'ordine non è importante.

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.

Di seguito sono riportati i passaggi:

  1. Usare l'API REST Create or Update Index 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",
             "scalarQuantizationParameters": {
                 "quantizedDataType": "int8"
                 },
             "rescoringOptions": {
                 "enableRescoring": true,
                 "defaultOversampling": 10,
                 "rescoreStorageMethod": "preserveOriginals"
             }
         },
         {
             "name": "binary-quantization",
             "kind": "binaryQuantization",
             "rescoringOptions": {
                 "enableRescoring": true,
                 "defaultOversampling": 10,
                 "rescoreStorageMethod": "discardOriginals"
         }
         }
     ],
     "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.rescoringOptions 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.rescoringOptions.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 è 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.

    • vectorSearch.algorithms.metric deve essere cosine se si usa Azure OpenAI. In caso contrario, usare la metrica di somiglianza associata al modello di incorporamento in uso. I valori supportati sono cosine, dotProduct, euclideane hamming (usati per l'indicizzazione di dati binari).

    • vectorSearch.profiles aggiungere un livello di astrazione per includere definizioni più complete. Un profilo viene definito in vectorSearch e a cui viene fatto riferimento in base al nome in ogni campo vettore. Si tratta di una combinazione di configurazioni di compressione e algoritmo. Questa proprietà viene assegnata 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 di controllo 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.

  1. Usare l'API REST Crea o Aggiorna indice per creare l'indice e aggiungere un campo vettoriale 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 vector. 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, facetablee sortable devono essere false.

  3. Aggiungere campi non vettoriali filtrabili alla raccolta, ad esempio title con filterable impostato su true, se si vuole richiamare pre-filtri, post-filtri o post-filtri restrittivi (anteprima) 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 i campi vettoriali per titolo e contenuto (titleVector e contentVector) equivalenti ai vettori. Fornisce inoltre campi per contenuto testuale equivalente (title e content) utili per l'ordinamento, il filtro 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=2025-09-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.

Per l'inserimento dati, è possibile usare metodologie push o pull.

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=2025-09-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 titleVector campo, è possibile selezionare title per i risultati della ricerca.

I campi devono essere attribuiti come retrievable da includere nei risultati.

  • 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 una definizione JSON della query vettoriale da eseguire. Se l'indice ha un'assegnazione di vettore, è anche possibile usare la conversione da testo a vettore o da immagine a vettore predefinita. 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 a 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 indice vettoriale

Per aggiornare un indice 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.

Per indicazioni standard sull'aggiornamento di un indice, vedere Aggiornare o 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 le modifiche seguenti 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.
    • Modifica 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 creare una query vettoriale.

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.

  • Last updated on