Creare una query vettoriale in Azure AI Search

Se si ha un indice vettoriale in Azure AI Search, questo articolo illustra come:

• Campi vettoriali di query
• Eseguire query su più campi vettoriali contemporaneamente
• Impostare pesi vettoriali
• Query con vettorizzazione integrata
• Impostare le soglie per escludere i risultati con punteggio basso (anteprima)

Questo articolo usa REST per l'illustrazione. Per esempi di codice in altri linguaggi, vedere il repository GitHub azure-search-vector-samples per soluzioni end-to-end che includono query vettoriali.

È possibile usare Esplora ricerche nel portale di Azure.

Prerequisiti

• Azure AI Search, in qualsiasi area e a qualsiasi livello.

• Indice vettoriale in Azure AI Search. Verificare la presenza di una sezione vectorSearch nell'indice per confermare un indice vettoriale.

• Facoltativamente, aggiungere un vettorizzatore all'indice per la conversione predefinita da testo a vettore o da immagine a vettore durante le query.

• Visual Studio Code con un client REST e dati di esempio se si vuole eseguire questi esempi autonomamente. Per iniziare a usare il client REST, vedere Avvio rapido: Azure AI Search utilizzando REST.

Convertire un input di stringa di query in un vettore

Per eseguire una query su un campo vettoriale, la query stessa deve essere un vettore.

Un approccio utile a convertire la stringa di query di testo di un utente nella relativa rappresentazione vettoriale consiste nel chiamare una libreria o un'API di incorporamento nel codice dell'applicazione. Come procedura consigliata, usare sempre gli stessi modelli di incorporamento usati per generare incorporamenti nei documenti di origine. È possibile trovare esempi di codice che illustrano come generare incorporamenti nel repository azure-search-vector-samples.

Un secondo approccio consiste nell'usare la vettorizzazione integrata, al momento disponibile a livello generale, per fare in modo che Azure AI Search gestisca gli input e gli output di vettorizzazione delle query.

Di seguito è riportato un esempio di API REST di una stringa di query inviata a una distribuzione di un modello di incorporamento OpenAI di Azure:

POST https://{{openai-service-name}}.openai.azure.com/openai/deployments/{{openai-deployment-name}}/embeddings?api-version={{openai-api-version}}
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "input": "what azure services support generative AI'"
}

Per una chiamata riuscita al modello distribuito, la risposta prevista è 202.

Il campo "incorporamento" nel corpo della risposta è la rappresentazione vettoriale della stringa di query "input". A scopo di test, copiare il valore della matrice "incorporamento" presente in "vectorQueries.vector" in una richiesta di query usando la sintassi illustrata nelle sezioni successive.

La risposta effettiva per questa chiamata POST al modello distribuito include 1536 incorporamenti, qui tagliati solo per i primi vettori al fine di garantirne la leggibilità.

{
    "object": "list",
    "data": [
        {
            "object": "embedding",
            "index": 0,
            "embedding": [
                -0.009171937,
                0.018715322,
                ...
                -0.0016804502
            ]
        }
    ],
    "model": "ada",
    "usage": {
        "prompt_tokens": 7,
        "total_tokens": 7
    }
}

In questo approccio, il codice dell'applicazione è responsabile della connessione a un modello, della generazione di incorporamenti e della gestione della risposta.

Richiesta di query vettoriale

Questa sezione illustra la struttura di base di una query vettoriale. È possibile usare il portale di Azure, le API REST o gli SDK di Azure per formulare una query vettoriale. Se si esegue la migrazione dal 2023-07-01-Preview, sono state apportate modifiche di rilievo. Per informazioni dettagliate, vedere Eseguire l'aggiornamento all'API REST più recente.

2024-07-01

2024-07-01 è la versione stabile dell'API REST per Search POST. Questa versione supporta:

• vectorQueries è il costrutto per la ricerca vettoriale.
• vectorQueries.kind impostato su vector per una matrice di vettori o su text se l'input è una stringa e si dispone di un vettore.
• vectorQueries.vector è query (rappresentazione vettoriale di testo o immagine).
• vectorQueries.weight (facoltativo) specifica il peso relativo di ogni query vettoriale inclusa nelle operazioni di ricerca (vedere Ponderazione vettoriale).
• exhaustive (facoltativo) richiama KNN completo in fase di query, anche se il campo viene indicizzato per HNSW.

Nell'esempio seguente il vettore è una rappresentazione di questa stringa: "what Azure services support full text search" (quali servizi Azure supportano la ricerca full text?). La query è destinata al campo contentVector. La query restituisce i risultati k. Il vettore effettivo ha 1536 incorporamenti, quindi viene tagliato in questo esempio per favorirne la leggibilità.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector",
            "weight": 0.5,
            "k": 5
        }
    ]
}

2024-05-01-preview

2024-05-01-preview è la versione più recente dell'API di anteprima per Search POST. Supporta la stessa sintassi di query vettoriale di 2024-07-01, con parametri aggiuntivi per la ricerca ibrida e soglie minime per escludere risultati più deboli.

Questa anteprima aggiunge:

• threshold per escludere i risultati con punteggio basso.
• Hybridsearch.MaxTextRecallSize per un maggiore controllo sugli input di una query ibrida.

Nell'esempio seguente il vettore è una rappresentazione di questa stringa: "what Azure services support full text search" (quali servizi Azure supportano la ricerca full text?). La query è destinata al campo contentVector. La query restituisce i risultati k. Il vettore effettivo ha 1536 incorporamenti, quindi viene tagliato in questo esempio per favorirne la leggibilità.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-05-01-preview
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "hybridSearch": {
        "maxTextRecallSize": 100,
        "countAndFacetMode": "countAllResults"
        }
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "contentVector",
            "k": 5,
            "exhaustive": true,
            "weight": 2,
            "threshold": {
                "kind": "vectorSimilarity",
                "value": 0.8
            },

        }
    ]

Azure portal

Usare Esplora ricerche per formulare una query vettoriale. Esplora ricerche include una visualizzazione Query e una visualizzazione JSON. Se si dispone di un vettorizzatore, è possibile usare visualizzazione Query (vedere Query con vettorizzazione integrata per i passaggi).

In caso contrario, se non si dispone di un vettorizzatore, è necessario usare la visualizzazione JSON e formulare la query vettoriale in JSON, incollando in una matrice vettoriale come input della query.

1. Accedere al portale di Azure e trovare il servizio di ricerca.

2. In Gestione della ricerca e Indici selezionare l'indice.

   

3. In Esplora ricerche, in Visualizza, selezionare Visualizzazione JSON.

   

4. Per impostazione predefinita, l'API di ricerca è 2024-05-01-preview. È possibile scegliere un'altra versione dell'API.

5. Incollare una query vettoriale JSON, quindi selezionare Cerca.

   

Risposta di query vettoriale

In Azure AI Search, le risposte alle query sono costituite da tutti i campi retrievable per impostazione predefinita. Tuttavia, è comune limitare i risultati della ricerca a un subset di campi retrievable elencandoli in un'istruzione select.

In una query vettoriale valutare attentamente se è necessario effettuare la vettorizzazione dei campi in una risposta. I campi vettoriali non sono leggibili, quindi se si esegue il push di una risposta a una pagina web, è consigliabile scegliere campi non vettoriali che siano rappresentativi del risultato. Ad esempio, se la query viene eseguita su contentVector, sarebbe invece possibile avere content come risposta.

Se si desidera avere campi vettoriali nel risultato, di seguito è riportato un esempio della struttura di risposta. contentVector è una matrice di stringhe di incorporamenti, qui ritagliata per brevità. Il punteggio di ricerca indica la pertinenza. Per il contesto sono inclusi altri campi non vettoriali.

{
    "@odata.count": 3,
    "value": [
        {
            "@search.score": 0.80025613,
            "title": "Azure Search",
            "category": "AI + Machine Learning",
            "contentVector": [
                -0.0018343845,
                0.017952163,
                0.0025753193,
                ...
            ]
        },
        {
            "@search.score": 0.78856903,
            "title": "Azure Application Insights",
            "category": "Management + Governance",
            "contentVector": [
                -0.016821077,
                0.0037742127,
                0.016136652,
                ...
            ]
        },
        {
            "@search.score": 0.78650564,
            "title": "Azure Media Services",
            "category": "Media",
            "contentVector": [
                -0.025449317,
                0.0038463024,
                -0.02488436,
                ...
            ]
        }
    ]
}

Punti principali:

• k determina il numero di risultati vicini più prossimi restituiti, in questo caso tre. Le query vettoriali restituiscono sempre k risultati, presupponendo che esistano almeno k documenti, anche se sono presenti documenti con scarsa somiglianza, perché l'algoritmo trova eventuali k vicini più prossimi al vettore della query.

• L'oggetto @search.score è determinato dall'algoritmo di ricerca vettoriale.

• I campi nei risultati della ricerca sono tutti campi retrievable o i campi di una clausola select. Durante l'esecuzione di query vettoriali, la corrispondenza viene eseguita solo sui dati vettoriali. Tuttavia, una risposta può includere qualsiasi campo retrievable in un indice. Poiché non esiste alcuna funzionalità per la decodifica di un risultato di un campo vettoriale, l'inclusione di campi di testo non visibile è utile per i valori che sono leggibili.

Più campi vettoriali

È possibile impostare la proprietà "vectorQueries.fields" su più campi vettoriali. La query vettoriale viene eseguita su ogni campo vettore specificato nell'elenco fields. Quando si eseguono query su più campi vettoriali, assicurarsi che ognuno di essi contenga incorporamenti dallo stesso modello di incorporamento e che la query venga generata anch’essa dallo stesso modello di incorporamento.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "exhaustive": true,
            "fields": "contentVector, titleVector",
            "k": 5
        }
    ]
}

Query vettoriali multiple

La ricerca vettoriale multiquery invia query multiple tra più campi vettoriali nell'indice di ricerca. Un esempio comune di questa richiesta di query si ha quando si utilizzano modelli come CLIP per una ricerca vettoriale multimodale, in cui lo stesso modello può vettorializzare il contenuto di immagini e di testo

L'esempio di query che segue cerca la somiglianza sia in myImageVector che in myTextVector, ma invia rispettivamente due diverse incorporazioni di query, ciascuna delle quali viene eseguita in parallelo. Questa query produce un risultato che viene valutato utilizzando la Reciprocal Rank Fusion (RRF).

• vectorQueries fornisce una matrice di query vettoriali.
• vector contiene i vettori di immagine e i vettori di testo nell'indice di ricerca. Ogni istanza costituisce una query separata.
• fields specifica il campo vettoriale di destinazione.
• k è il numero di corrispondenze vicine più prossime da includere nei risultati.

{
    "count": true,
    "select": "title, content, category",
    "vectorQueries": [
        {
            "kind": "vector",
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "myimagevector",
            "k": 5
        },
        {
            "kind": "vector"
            "vector": [
                -0.002222222,
                0.018708462,
                -0.013770515,
            . . .
            ],
            "fields": "mytextvector",
            "k": 5
        }
    ]
}

I risultati della ricerca includono una combinazione di testo e immagini, presupponendo che l'indice di ricerca includa un campo per il file di immagine (un indice di ricerca non archivia le immagini).

Query con vettorizzazione integrata

In questa sezione viene illustrata una query vettoriale che richiama la vettorizzazione integrata che converte un testo o una query di immagine in un vettore. È consigliabile usare l'API REST stabile 2024-07-01, Esplora ricerche o pacchetti dell'SDK Azure più recenti per questa funzionalità.

Un prerequisito è un indice di ricerca con un vettorizzatore configurato e assegnato a un campo vettoriale. Il vettorizzatore fornisce informazioni sulla connessione a un modello di incorporazione utilizzato al momento della query.

Azure portal

Esplora ricerche supporta la vettorizzazione integrata in fase di query. Se l'indice contiene campi vettoriali e dispone di un vettore, è possibile usare la conversione da testo a vettore predefinita.

1. Accedere al portale di Azure con l'account Azure e andare al servizio Azure AI Search.

2. Nel menu a sinistra, espandere Gestione ricerca>Indicie selezionare l'indice. Esplora ricerche è la prima scheda della pagina dell'indice.

3. Controllare Profili vettoriali per verificare di avere un vettore.

   

4. In Esplora ricerche, è possibile immettere una stringa di testo nella barra di ricerca predefinita nella visualizzazione Query. Il vettorizzatore predefinito converte la stringa in un vettore, esegue la ricerca e restituisce i risultati.

   In alternativa, è possibile selezionare Visualizza>visualizzazione JSON per visualizzare o modificare la query. Se sono presenti vettori, Esplora ricerche configura automaticamente una query vettoriale. È possibile usare la visualizzazione JSON per selezionare i campi usati nella ricerca e nella risposta, aggiungere filtri o costruire query più avanzate, ad esempio ibride. Un esempio JSON viene fornito nella scheda API REST di questa sezione.

REST API

1. Usare Index - GET per restituire la definizione dell'indice e verificare la presenza di una configurazione del vettore. Cercare vectorizers nella definizione dell'indice. Deve specificare un modello di incorporamento distribuito.

2. Usare Search - POST per la richiesta di query.

   • kindDeve essere impostato su text.
   • text deve avere una stringa di testo. Viene passato al vettorizzatore assegnato al campo vettoriale.
   • fields è il campo vettoriale da cercare.
   • k è il numero di corrispondenze vettoriali da restituire.

Di seguito è riportato un semplice esempio di query vettorializzata in fase di query. La stringa di testo viene vettorializzata e quindi utilizzata per eseguire una query nel campo descriptionVector.

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-01
{
    "select": "title, genre, description",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector",
            "k": 5
        }
    ]
}

Ecco una query ibrida che utilizza la vettorizzazione integrata delle query di testo. Questa query include più campi vettoriali di query, più campi non vettoriali, un filtro e una classificazione semantica. Anche in questo caso, le differenze sono l'oggetto kind della query vettoriale e la stringa text anziché un oggetto vector.

In questo esempio, il motore di ricerca effettua tre chiamate di vettorizzazione ai vettori assegnati a descriptionVector, synopsisVectore authorBioVector nell'indice. I vettori risultanti vengono utilizzati per recuperare i documenti in base ai rispettivi campi. Inoltre, il motore di ricerca esegue una ricerca per parole chiave sulla query search "romanzo giallo ambientato a Londra".

POST https://{{search-service}}.search.windows.net/indexes/{{index}}/docs/search?api-version=2024-07-01
Content-Type: application/json
api-key: {{admin-api-key}}
{
    "search":"mystery novel set in London", 
    "searchFields":"description, synopsis", 
    "semanticConfiguration":"my-semantic-config", 
    "queryType":"semantic",
    "select": "title, author, synopsis",
    "filter": "genre eq 'mystery'",
    "vectorFilterMode": "postFilter",
    "vectorQueries": [
        {
            "kind": "text",
            "text": "mystery novel set in London",
            "fields": "descriptionVector, synopsisVector",
            "k": 5
        },
        {
            "kind": "text"
            "text": "living english author",
            "fields": "authorBioVector",
            "k": 5
        }
    ]
}

I risultati ottenuti da tutte e quattro le query vengono fusi utilizzando il ranking RRF. Il ranking semantico secondario viene invocato sui risultati della ricerca fusi, ma solo sui searchFields, potenziando i risultati che sono più semanticamente allineati ai "search":"mystery novel set in London".

Nota

La vettorizzazione si verifica durante l'indicizzazione e l'esecuzione di query. Se non è necessaria la suddivisione in blocchi di dati e la vettorizzazione nell'indice, è possibile ignorare i passaggi come la creazione di un indicizzatore, un set di competenze e un'origine dati. In questo flusso di lavoro, la vettorizzazione viene usata solo in fase di query per convertire una stringa di testo o un'immagine in un incorporamento. È possibile definire un vettore nell'indice di ricerca per questo passaggio.

Numero di risultati classificati in una risposta di query vettoriale

Una query vettoriale specifica il parametro k, che determina il numero di corrispondenze restituite nei risultati. Il motore di ricerca restituisce sempre il numero k di corrispondenze. Se k è maggiore del numero di documenti nell'indice, il numero di documenti determina il limite superiore di ciò che può essere restituito.

Se si ha familiarità con la ricerca full text, è possibile prevedere zero risultati se l'indice non contiene un termine o una frase. Tuttavia, nella ricerca vettoriale, l'operazione di ricerca identifica i vicini più prossimi e restituisce sempre k risultati, anche se i vicini più prossimi non sono simili. È quindi possibile ottenere risultati per query senza senso o fuori tema, soprattutto se non si utilizzano i suggerimenti per stabilire dei limiti. I risultati meno rilevanti hanno un punteggio di somiglianza peggiore, ma sono comunque i vettori "più vicini" se non c'è nulla di più prossimo. Pertanto, una risposta priva di risultati significativi può comunque restituire k risultati, ma il punteggio di somiglianza di ciascun risultato sarebbe basso.

Un approccio ibrido che include la ricerca full text può attenuare questo problema. Un'altra mitigazione consiste nell'impostare una soglia minima per il punteggio di ricerca, ma solo se la query è una query a vettore singolo puro. Le query ibride non sono adatte alle soglie minime perché gli intervalli RRF risultano molto più piccoli e volatili.

I parametri di query che influenzano il conteggio dei risultati includono:

• "k": n risultati per query unicamente vettoriali
• "top": n risultati per le query ibride che includono un parametro "ricerca"

Sia "k" che "top" sono facoltativi. Non specificato, il numero predefinito di risultati in una risposta è 50. È possibile impostare "top" e "skip" per per sfogliare più risultati o modificare l'impostazione predefinita.

Algoritmi di classificazione utilizzati in una query vettoriale

La classificazione dei risultati viene calcolata in base a:

• Metrica di similarità
• Reciprocal Rank Fusion (RRF) se sono presenti più set di risultati della ricerca.

Metrica di similarità

Metrica di similarità specificata nella sezione vectorSearch dell’indice per una query unicamente vettoriale. I valori validi sono cosine, euclidean e dotProduct.

I modelli di incorporazione di OpenAI di Azure utilizzano la similarità del coseno, quindi se si utilizzano i modelli di incorporazione di OpenAI di Azure, cosine è la metrica consigliata. Tra le altre metriche di classificazione supportate vi sono euclidean e dotProduct.

Utilizzare RRF

Vengono creati set multipli se la query si rivolge a più campi vettoriali, se esegue più query vettoriali in parallelo o se la query è un ibrido di ricerca vettoriale e full text, con o senza classificazione semantica.

Durante l'esecuzione della query, una query vettoriale può specificare come destinazione un unico indice vettoriale interno. Pertanto, per più campi vettoriali e più query vettoriali, il motore di ricerca genera più query destinate ai rispettivi indici vettoriali di ogni campo. L'output è un set di risultati classificati per ogni query, che vengono fusi tramite RRF. Per ulteriori informazioni, vedere Punteggio di rilevanza con Reciprocal Rank Fusion (RRF).

Ponderazione vettoriale

Aggiungere un parametro di query weight per specificare il peso relativo di ogni query vettoriale inclusa nelle operazioni di ricerca. Questo valore viene usato quando si combinano i risultati di più elenchi di classificazione prodotti da due o più query vettoriali nella stessa richiesta o dalla parte vettoriale di una query ibrida.

Il valore predefinito è 1,0 e il valore deve essere un numero positivo maggiore di zero.

I pesi vengono utilizzati per calcolare i punteggi di fusione del rango reciproco di ogni documento. Il calcolo è moltiplicatore del valore weight rispetto al punteggio di classificazione del documento all'interno del rispettivo set di risultati.

L'esempio seguente è una query ibrida con due stringhe di query vettoriali e una stringa di testo. Alle query vettoriali vengono assegnati pesi. La prima query è 0,5 o metà del peso, il che ne riduce l'importanza nella richiesta. La seconda query vettoriale è due volte più importante.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-07-01

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_first_vector_field", 
          "k": 10, 
          "weight": 0.5 
        },
        { 
          "kind": "vector", 
          "vector": [4.0, 5.0, 6.0], 
          "fields": "my_second_vector_field", 
          "k": 10, 
          "weight": 2.0
        } 
      ], 
      "search": "hello world" 
    } 

La ponderazione vettoriale si applica solo ai vettori. La query di testo in questo esempio ("hello world") ha un peso implicito di 1,0 o un peso neutro. Tuttavia, in una query ibrida è possibile aumentare o ridurre l'importanza dei campi di testo impostando maxTextRecallSize.

Impostare le soglie per escludere i risultati con punteggio basso (anteprima)

Poiché la ricerca del vicino più prossimo restituisce sempre k vicini richiesti, è possibile ottenere diverse corrispondenze con punteggio basso come parte del requisito di numero k nei risultati della ricerca. Per escludere i risultati della ricerca con punteggio basso, è possibile aggiungere un parametro di query threshold che filtri i risultati in base a un punteggio minimo. L’operazione di filtraggio si verifica prima di fondere i risultati da set di richiami diversi.

Questo parametro è ancora in anteprima. È consigliabile visualizzare in anteprima la versione dell'API REST 2024-05-01-preview.

In questo esempio, tutte le corrispondenze che hanno un punteggio inferiore a 0,8 vengono escluse dai risultati della ricerca vettoriale, anche se il numero di risultati scende sotto k.

POST https://[service-name].search.windows.net/indexes/[index-name]/docs/search?api-version=2024-05-01-preview 
    Content-Type: application/json 
    api-key: [admin key] 

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my-cosine-field", 
          "threshold": { 
            "kind": "vectorSimilarity", 
            "value": 0.8 
          } 
        }
      ]
    }

MaxTextSizeRecall per la ricerca ibrida (anteprima)

Le query vettoriali vengono spesso usate in costrutti ibridi che includono campi non vettoriali. Se si scopre che i risultati classificati con BM25 sono superiori o sotto rappresentati nei risultati di una query ibrida, è possibile impostare maxTextRecallSize per aumentare o diminuire i risultati classificati con BM25 forniti per la classificazione ibrida.

È possibile impostare questa proprietà solo nelle richieste ibride che includono componenti "search" e "vectorQueries".

Questo parametro è ancora in anteprima. È consigliabile visualizzare in anteprima la versione dell'API REST 2024-05-01-preview.

Per altre informazioni, vedere Impostare maxTextRecallSize - Creare una query ibrida.

Passaggi successivi

Come passaggio successivo, esaminare esempi di codice di query vettoriali in Python, C# o JavaScript.