Condividi tramite

Creare una query vettoriale in Azure AI Search

Se si dispone di un indice vettoriale in Ricerca di intelligenza artificiale di Azure, questo articolo illustra come:

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 soluzioni end-to-end che includono query vettoriali.

È possibile usare Esplora ricerche nel portale di Azure.

Prerequisiti

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, ora disponibile a livello generale, per consentire a Ricerca di intelligenza artificiale di Azure di gestire 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 embedding campo nel corpo della risposta è la rappresentazione vettoriale della stringa inputdi query . Ai fini del test, copiare il valore dell'array embedding in vectorQueries.vector in una richiesta di query utilizzando la sintassi mostrata nelle sezioni seguenti.

La risposta effettiva a questa chiamata POST al modello distribuito include 1.536 incorporamenti. Per la leggibilità, questo esempio mostra solo i primi vettori.

{
    "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 altre informazioni, vedere Eseguire l'aggiornamento all'API REST più recente.

La versione stabile supporta:

  • vectorQueries è il costrutto per la ricerca vettoriale.
  • vectorQueries.kind impostare su vector per una matrice di vettori o text se l'input è una stringa e se si dispone di un vettorizzatore.
  • vectorQueries.vector è la query (rappresentazione vettoriale del testo o di un'immagine).
  • vectorQueries.exhaustive (facoltativo) richiama KNN completo in fase di query, anche se il campo viene indicizzato per HNSW.
  • vectorQueries.fields (facoltativo) è destinato a campi specifici per l'esecuzione di query (fino a 10 per query).
  • vectorQueries.weight (facoltativo) specifica il peso relativo di ogni query vettoriale inclusa nelle operazioni di ricerca. Per altre informazioni, vedere Ponderazione vettoriale.
  • vectorQueries.k è il numero di corrispondenze da restituire.

Nell'esempio seguente il vettore è una rappresentazione di questa stringa: "what Azure services support full text search". La query è destinata al campo contentVector e restituisce i risultati k. Il vettore effettivo ha 1.536 incorporamenti, che vengono tagliati in questo esempio per la leggibilità.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-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
        }
    ]
}

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 facili da comprendere, quindi se invii una risposta a una pagina Web, è consigliabile scegliere campi non vettoriali che rappresentano il risultato. Ad esempio, se la query viene eseguita su contentVector, sarebbe invece possibile avere content come risposta.

Se si vogliono campi vettoriali nel risultato, di seguito è riportato un esempio della struttura di risposta. contentVector è una matrice di stringhe di incorporamenti, che vengono tagliati in questo esempio per la leggibilità. 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 k sempre risultati, presupponendo che esistano almeno k documenti, anche se alcuni documenti presentano una scarsa somiglianza. Ciò è dovuto al fatto che l'algoritmo trova tutti i k vicini più prossimi al vettore di query.

  • L'algoritmo di ricerca vettoriale determina l'oggetto @search.score.

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

Più campi vettoriali

È possibile impostare la vectorQueries.fields proprietà su più campi vettoriali. La query vettoriale viene eseguita su ogni campo vettore specificato nell'elenco fields. È possibile specificare fino a 10 campi.

Quando si eseguono query su più campi vettoriali, assicurarsi che ognuno contenga incorporamenti dallo stesso modello di incorporamento. La query deve essere generata anche dallo stesso modello di incorporamento.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2025-09-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. Questo tipo di query è comunemente usato con modelli come CLIP per la ricerca multimodale, in cui lo stesso modello può vettorizzare sia il testo che le immagini.

L'esempio di query seguente cerca la somiglianza tra myImageVector e myTextVector ma invia due rispettivi embedding delle query, ognuno in esecuzione in parallelo. Il risultato di questa query viene ottenuto usando la fusione di rango reciproca (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
        }
    ]
}

Gli indici di ricerca non possono archiviare immagini. Supponendo che l'indice includa un campo per il file di immagine, i risultati della ricerca includono una combinazione di testo e immagini.

Query con vettorizzazione integrata

Questa sezione illustra una query vettoriale che richiama la vettorizzazione integrata per convertire una query di testo o immagine in un vettore. Per questa funzionalità è consigliabile usare l'API REST stabile 2025-09-01, Search Explorer o i pacchetti Azure SDK più recenti.

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.

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 e trovare il servizio di ricerca.

  2. Nel menu a sinistra, selezionare Gestione ricerche>Indici e quindi selezionare il tuo indice.

  3. Selezionare la scheda Profili vettoriali per verificare di avere un vettorizzatore.

    Screenshot di un'impostazione del vettorozzatore in un indice di ricerca.

  4. Selezionare la scheda Esplora ricerche . Usando la visualizzazione query predefinita, è possibile immettere una stringa di testo nella barra di ricerca. 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 da usare nella ricerca e nella risposta, aggiungere filtri e costruire query più avanzate, ad esempio query ibride. Per un esempio JSON, selezionare la scheda API REST in questa sezione.

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 massimo 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ù vicini e restituisce k sempre risultati, anche se i vicini più vicini non sono simili. È possibile ottenere risultati per query senza senso o fuori tema, soprattutto se non si usano indicazioni per impostare i 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 senza risultati significativi può comunque restituire k risultati, ma il punteggio di somiglianza di ogni risultato sarebbe basso.

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

I parametri di query che influiscono sul conteggio dei risultati includono:

  • "k": n risultati per query unicamente vettoriali.
  • "top": n risultati per delle query ibride che includono un parametro search.

Sia k che top sono facoltativi. Se non specificato, il numero predefinito di risultati in una risposta è 50. È possibile impostare top e skip per scorrere tra più risultati o modificare il valore predefinito.

Algoritmi di classificazione utilizzati in una query vettoriale

La classificazione dei risultati viene calcolata in base a:

  • Metrica di somiglianza.
  • 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.

RRF

Vengono creati più set se la query è destinata a più campi vettoriali, esegue più query vettoriali in parallelo o è 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. 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 altre informazioni, vedere Assegnazione dei punteggi per pertinenza tramite La fusione di rango reciproco.

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 usati per calcolare i punteggi RRF di ogni documento. Il calcolo è un moltiplicatore del weight valore 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=2025-09-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 neutro implicito pari a 1,0. 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 threshold parametro di query che filtra 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 è in fase di anteprima. È consigliabile usare 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 al di sotto kdi .

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

Passaggi successivi

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

  • Last updated on