Creare una query vettoriale in Azure AI Search

Se si dispone di un indice vector in Azure AI Search, 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 Azure SDK nel repository azure-search-vector-samples, che fornisce soluzioni end-to-end che includono query vettoriali.

È anche possibile usare Search Explorer nel portale di Azure.

Prerequisiti

  • Un servizio Azure AI Search in qualsiasi area e in qualsiasi livello.

  • Indice vettoriale. Verificare la presenza di una sezione vectorSearch nell'indice.

  • Facoltativamente, aggiungere un vettorizzatore al tuo indice per la conversione da testo a vettore o da immagine a vettore integrata durante le query.

  • Visual Studio Code con un client REST e dati di esempio per eseguire questi esempi autonomamente. Per iniziare a usare il client REST, vedere Avvio rapido: Ricerca full-text con 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 per 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 mostrano come generare incorporamenti nel repository azure-search-vector-samples.

Un secondo approccio consiste nell'"usare la vettorizzazione integrata, ora generalmente disponibile, affinché 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 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'"
}

La risposta prevista è 202 per una chiamata riuscita al modello distribuito.

Il embedding campo nel corpo della risposta è la rappresentazione vettoriale della stringa inputdi query . Ai fini del test, copiare il valore dell'array embedding nel vectorQueries.vector in una richiesta di query, usando la sintassi illustrata nelle sezioni successive.

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 vettoriale di interrogazione

Questa sezione illustra la struttura di base di una query vettoriale. È possibile usare il portale di Azure, le API REST o il Azure SDK per formulare una query vettoriale.

Se stai eseguendo la migrazione dal 2023-07-01-Preview, ci sono modifiche critiche. 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 impostato 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 risultati 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 k risultati. 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 di query sono costituite da tutti i campi retrievable per impostazione predefinita. Tuttavia, è comune limitare i risultati della ricerca a un subset di retrievable campi elencandoli in un'istruzione select .

In una query vettoriale valutare attentamente se è necessario vettoriare i campi in una risposta. I campi vettoriali non sono leggibili agli esseri umani, quindi se si invia una risposta a una pagina Web, è consigliabile scegliere campi non vettoriali che rappresentano il risultato. Ad esempio, se la query viene eseguita su contentVector, è possibile restituire content .

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 vengono 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 chiave:

  • k determina il numero di risultati vicini più vicini 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 uno o più 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 entrambi tutti i retrievable campi o i campi presenti in una clausola select. Durante l'esecuzione di query vettoriali, la corrispondenza viene eseguita solo sui dati vettoriali. Tuttavia, una risposta può includere qualsiasi retrievable campo 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
        }
    ]
}

Più query vettoriali

La ricerca vettoriale su più query invia più query attraverso vari campi vettoriali nell'indice di ricerca. Questo tipo di query viene comunemente usato con modelli come CLIP per la ricerca multimodale, dove lo stesso modello può vettorializzare sia il testo che le immagini.

L'esempio di query seguente cerca la somiglianza sia in myImageVector che in myTextVector, ma invia due embedding delle query rispettive, ognuno eseguendosi 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 rappresenta una query distinta.
  • fields specifica il campo vettore di destinazione.
  • k è il numero di corrispondenze adiacenti più vicine 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. È consigliabile usare l'API REST stabile 2025-09-01 API REST, Esplora ricerche o pacchetti di Azure SDK 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 di connessione a un modello di embedding usato in fase di query.

Il supporto di Search Explorer include la vettorizzazione integrata durante la fase di query. Se l'indice contiene campi vettoriali e ha un vettore, è possibile usare la conversione da testo a vettore predefinita.

  1. Passare al servizio di ricerca nel portale Azure.

  2. Nel menu a sinistra selezionare Gestione della ricerca>Indici, e quindi selezionare l'indice.

  3. Selezionare la scheda Profili vettoriali per confermare che avete un vettorizzatore.

    Screenshot di un'impostazione del vettorizzatore 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 vettore 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 ricerca 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 k parametro , che determina il numero di corrispondenze restituite nei risultati. Il motore di ricerca restituisce sempre k il numero 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 insensate o fuori tema, soprattutto se non si usano istruzioni per impostare i limiti. I risultati meno rilevanti hanno un punteggio di somiglianza peggiore, ma sono ancora i vettori "più vicini" se non c'è nulla di più vicino. 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 le query solo vettoriali.
  • "top": n risultati per le 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 usati 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 somiglianza

Metrica di somiglianza specificata nella sezione indice vectorSearch per una query solo vettoriale. I valori validi sono cosine, euclideane dotProduct.

I modelli di incorporamento di Azure OpenAI usano la somiglianza del coseno, quindi se si utilizzano i modelli di incorporamento di Azure OpenAI, cosine è la metrica consigliata. Altre metriche di classificazione supportate includono 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 solo 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 weight parametro di query 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. I pesi vengono assegnati alle query vettoriali. La prima query ha un peso di 0,5 o metà, riducendone l'importanza nella ricerca. 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" 
    }

Il peso del vettore si applica solo ai vettori. La query di testo in questo esempio, "hello world", ha un peso neutro implicito pari a 1,0. In una query ibrida, tuttavia, è 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 dei vicini più prossimi restituisce sempre i k vicini richiesti, è possibile ottenere più corrispondenze a basso punteggio per soddisfare il requisito numerico 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. Il filtraggio avviene prima che i risultati siano fusi dagli insiemi di richiamo diversi.

Questo parametro è in fase di anteprima. È consigliabile usare la versione di anteprima più recente di Documenti - Post di ricerca (API REST).

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=2025-11-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 gli esempi di codice di query vettoriali in Python, C# o JavaScript.

  • Last updated on