Condividi tramite

Creare una query ibrida in Azure AI Search

  • Articolo

La ricerca ibrida combina testo (parola chiave) e query vettoriali in una singola richiesta di ricerca. Tutte le sottoquery nella richiesta vengono eseguite in parallelo. I risultati vengono uniti e riordinati in base ai nuovi punteggi di ricerca, tramite la Reciprocal Rank Fusion (RRF) per restituire un set di risultati unificato. In molti casi, in base ai test di benchmark, le query ibride con ranking semantico restituiscono i risultati più rilevanti.

In questo articolo viene spiegato come:

  • Configurare una richiesta di base
  • Formulare query ibride con più parametri e filtri
  • Migliorare la pertinenza usando la classificazione semantica o i pesi vettoriali
  • Ottimizzare i comportamenti delle query controllando gli input di testo e vettore

Nota

Novità della versione 2024-09-01-preview è la possibilità di assegnare filtri solo alle sottoquery vettoriali in una richiesta ibrida. In questo modo è possibile ottenere maggiore precisione sulla modalità di applicazione dei filtri. Per altre informazioni, vedere Targeting filters to vector subqueries in questo articolo.For more information, see targeting filters to vector subqueries in this article.

Prerequisiti

Scegliere un'API o uno strumento

  • Esplora ricerche nella portale di Azure (supporta sia la sintassi di ricerca dell'API stabile che quella di anteprima) include una visualizzazione JSON che consente di incollare una richiesta ibrida.

  • Versione stabile 2024-07-01 o una versione recente dell'API di anteprima se si usano funzionalità di anteprima come maxTextRecallSize e countAndFacetMode(preview).

    Per la leggibilità, vengono usati esempi REST per spiegare il funzionamento delle API. È possibile usare un client REST come Visual Studio Code con l'estensione REST per compilare query ibride. Per altre informazioni, vedere Guida introduttiva: Ricerca vettoriale con le API REST.

  • Pacchetti stabili o beta più recenti degli SDK di Azure (vedere log delle modifiche per il supporto delle funzionalità sdk).

Configurare una query ibrida in Esplora ricerche

  1. In Esplora ricerche verificare che la versione dell'API sia 2024-07-01 o una versione dell'API di anteprima più recente.

  2. In Visualizzazione selezionare Visualizzazione JSON in modo che sia possibile incollare una query vettoriale.

  3. Sostituire il modello di query predefinito con una query ibrida, ad esempio l'esempio "Eseguire una query ibrida" a partire dalla riga 539 nella guida introduttiva del vettore. Per brevità, in questo articolo il vettore viene troncato.

    Una query ibrida include una query di testo specificata in search e una query vettoriale specificata in vectorQueries.vector.

    La query di testo e la query vettoriale possono essere equivalenti o divergenti, ma è comune condividere la stessa finalità.

    {
    "count": true,
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "top": 7,
    "vectorQueries": [
        {
            "vector": [0.01944167, 0.0040178085, -0.007816401 ... <remaining values omitted> ], 
            "k": 7,
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true
        }
    ]
}

  4. Seleziona Cerca.

Suggerimento

I risultati della ricerca sono più facili da leggere se si nascondono i vettori. In Opzioni query attivare Nascondi valori vettoriali nei risultati della ricerca.

Richiesta di query ibrida (API REST)

Una query ibrida combina la ricerca di testo e la ricerca vettoriale, in cui il parametro search accetta una stringa di query e vectorQueries.vector accetta la query vettoriale. Il motore di ricerca esegue query full-text e vettoriali in parallelo. L'unione di tutte le corrispondenze viene valutata in base alla rilevanza tramite la Reciprocal Rank Fusion (RRF) e nella risposta viene restituito un singolo set di risultati.

I risultati vengono restituiti in testo normale, inclusi i vettori nei campi contrassegnati come retrievable. Poiché i vettori numerici non sono utili nei risultati della ricerca, scegliere altri campi dell'indice come proxy per la corrispondenza del vettore. Ad esempio, se un indice include i campi "descriptionVector" e "descriptionText", la query può corrispondere a "descriptionVector", ma il risultato della ricerca può visualizzare "descriptionText". Usare il parametro select per specificare solo i campi leggibili dall'utente nei risultati.

L'esempio seguente illustra una configurazione di query ibrida.

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}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "k": 10
        },
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City",
    "top": 10
}

Punti principali:

  • La stringa di query vettoriale viene specificata tramite la proprietà vectorQueries.vector. La query viene eseguita sul campo "DescriptionVector". Impostare kind su "vector" per indicare il tipo di query. Facoltativamente, impostare exhaustive su true per eseguire una query sul contenuto completo del campo vettore.

  • La ricerca di parole chiave viene specificata tramite la proprietà search. Tale ricerca viene eseguita in parallelo con la query vettoriale.

  • k determina il numero di corrispondenze vicine più prossime restituite dalla query vettoriale e fornite al classificatore RRF.

  • top determina il numero di corrispondenze restituite nella risposta all-up. In questo esempio, la risposta include 10 risultati, supponendo che siano presenti almeno 10 corrispondenze nei risultati unificati.

Ricerca ibrida con filtro

In questo esempio viene aggiunto un filtro, che viene applicato ai campi non vettoriali filterable dell'indice di ricerca.

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}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "vectorFilterMode": "postFilter",
    "filter": "ParkingIncluded",
    "top": "10"
}

Punti principali:

  • I filtri vengono applicati al contenuto dei campi filtrabili. In questo esempio il campo ParkingIncluded è un valore booleano e viene contrassegnato come filterable nello schema dell'indice.

  • Nelle query ibride, i filtri possono essere applicati prima dell'esecuzione della query per ridurne la superficie, oppure dopo l'esecuzione della query per tagliare i risultati. "preFilter" è l'impostazione predefinita. Per usare postFilter, impostare la modalità di elaborazione del filtro come illustrato in questo esempio.

  • Quando si esegue il post-filtro dei risultati della query, il numero di risultati potrebbe essere minore di top-n.

Ricerca ibrida con filtri destinati alle sottoquery vettoriali (anteprima)

Usando 2024-09-01-preview, è possibile eseguire l'override di un filtro globale sulla richiesta di ricerca applicando un filtro secondario destinato solo alle sottoquery vettoriali in una richiesta ibrida.

Questa funzionalità fornisce un controllo granulare assicurando che i filtri influiscano solo sui risultati della ricerca vettoriale, lasciando invariati i risultati della ricerca basata su parole chiave.

Il filtro di destinazione esegue completamente l'override del filtro globale, inclusi tutti i filtri usati per la ricerca di sicurezza o geospaziale. Nei casi in cui sono necessari filtri globali, ad esempio il taglio della sicurezza, è necessario includere in modo esplicito questi filtri nel filtro di primo livello e in ogni filtro a livello di vettore per garantire che vengano applicati in modo coerente la sicurezza e altri vincoli.

Per applicare filtri vettoriali di destinazione:

  • Usare l'api REST documenti di ricerca più recente in anteprima o un pacchetto beta di Azure SDK che fornisce la funzionalità.

  • Modificare una richiesta di query, aggiungendo un nuovo vectorQueries.filterOverride set di parametri a un'espressione di filtro OData.

Ecco un esempio di query ibrida che aggiunge un override del filtro. Il filtro globale "Rating gt 3" viene sostituito in fase di esecuzione dal filtroOvrride.

POST https://{{search-service-name}}.search.windows.net/indexes/{{index-name}}/docs/search?api-version=2024-09-01=preview

{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "exhaustive": true,
            "filterOverride": "Address/City eq 'Seattle'",
            "k": 10
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Address/City, Rating",
    "filter": "Rating gt 3"
    "debug": "vector",
    "top": 10
}

Supponendo che sia stato abilitato il classificatore semantico e che la definizione dell'indice includa una configurazione semantica, è possibile formulare una query che includa la ricerca vettoriale e la ricerca di parole chiave, con una classificazione semantica del set di risultati unificato. Facoltativamente, è possibile aggiungere sottotitoli e risposte.

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}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "top": "50"
}

Punti principali:

  • Il classificatore semantico accetta fino a 50 risultati dalla risposta unificata.

  • "queryType" e "semanticConfiguration" sono obbligatori.

  • "sottotitoli" e "risposte" sono facoltativi. I valori vengono estratti dal testo verbatim nei risultati. Viene restituita una risposta solo se i risultati includono contenuti che presentano le caratteristiche di una risposta alla query.

Ricerca semantica ibrida con filtro

Ecco l'ultima query della raccolta. Si tratta della stessa query semantica ibrida dell'esempio precedente, ma con un filtro.

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}}
{
    "vectorQueries": [
        {
            "vector": [
                -0.009154141,
                0.018708462,
                . . . 
                -0.02178128,
                -0.00086512347
            ],
            "fields": "DescriptionVector",
            "kind": "vector",
            "k": 50
        }
    ],
    "search": "historic hotel walk to restaurants and shopping",
    "select": "HotelName, Description, Tags",
    "queryType": "semantic",
    "semanticConfiguration": "my-semantic-config",
    "captions": "extractive",
    "answers": "extractive",
    "filter": "ParkingIsIncluded'",
    "vectorFilterMode": "postFilter",
    "top": "50"
}

Punti principali:

  • La modalità filtro può influire sul numero di risultati disponibili per il reranker semantico. Come procedura consigliata, è preferibile assegnare al classificatore semantico il numero massimo di documenti (50). Se i pre-filtri o i post-filtri sono troppo selettivi, è possibile che si stia depotenziando il classificatore semantico assegnandogli meno di 50 documenti con cui lavorare.

  • Il pre-filtraggio viene applicato prima dell'esecuzione della query. Se il pre-filtro riduce l'area di ricerca a 100 documenti, la query vettoriale viene eseguita sul campo "DescriptionVector" di tali documenti, restituendo le corrispondenze k=50 migliori. I 50 documenti corrispondenti passano quindi all'RRF per i risultati unificati e infine al classificatore semantico.

  • Il post-filtraggio viene applicato dopo l'esecuzione della query. Se k=50 restituisce 50 corrispondenze sul lato della query vettoriale, il post-filtro viene applicato a tali corrispondenze, riducendo così i risultati che soddisfano i criteri del filtro e lasciando meno di 50 documenti da passare al classificatore semantico.

Impostare maxTextRecallSize e countAndFacetMode (anteprima)

In questa sezione viene illustrato come modificare gli input di una query ibrida controllando la quantità di risultati sulla pertinenza basati su BM25 che vengono trasmessi al modello di classificazione ibrida. Il controllo dell'input sulla pertinenza basato su BM25 BM25 offre più opzioni per l'ottimizzazione della pertinenza negli scenari ibridi.

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

Suggerimento

Un'altra opzione da considerare come tecnica supplementare o sostitutiva è la ponderazione vettoriale, che aumenta l'importanza delle query vettoriali nella richiesta.

  1. Usare Search - POST o Search - GET in 2024-05-01-preview per specificare questi parametri.

  2. Aggiungere un oggetto parametro di query hybridSearch per impostare il numero massimo di documenti richiamati tramite i risultati sulla pertinenza basati su BM25 di una query ibrida. Ad esso sono associate due proprietà:

    • maxTextRecallSize specifica il numero di risultati sulla pertinenza basati su BM25 da fornire al classificatore RRF (Reciprocal Rank Fusion) usato nelle query ibride. L'impostazione predefinita è 1.000. Il valore massimo è 10.000.

    • countAndFacetMode segnala i conteggi relativi ai risultati sulla pertinenza basati su BM25 e, nel caso in cui vengano usati, ai facet. L'impostazione predefinita riguarda tutti i documenti che corrispondono alla query. Facoltativamente, è possibile definire l'ambito "count" nel maxTextRecallSize.

  3. Ridurre maxTextRecallSize se la ricerca di similarità vettoriale in genere supera le prestazioni del lato testo della query ibrida.

  4. Generare maxTextRecallSize se si dispone di un indice di grandi dimensioni e l'impostazione predefinita non acquisisce un numero sufficiente di risultati. Con un set di risultati sulla pertinenza basati su BM25 più ampio, è anche possibile impostare top, skipe next per recuperare parti di tali risultati.

Negli esempi REST seguenti vengono illustrati due casi d'uso per l'impostazione di maxTextRecallSize.

Il primo esempio riduce maxTextRecallSize a 100, limitando il lato testo della query ibrida a soli 100 documenti. Inoltre, imposta countAndFacetMode per includere solo i risultati di maxTextRecallSize.

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

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world", 
      "hybridSearch": { 
        "maxTextRecallSize": 100, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

Il secondo esempio genera maxTextRecallSize fino a 5.000. Usa inoltre i comandi "top", "skip" e "next" per eseguire il pull dei risultati da set di risultati di grandi dimensioni. In questo caso, la richiesta esegue il pull dei risultati sulla pertinenza basati su BM25 a partire dalla posizione 1.500 alla 2.000 come contributo della query di testo al set di risultati composito RRF.

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

    { 
      "vectorQueries": [ 
        { 
          "kind": "vector", 
          "vector": [1.0, 2.0, 3.0], 
          "fields": "my_vector_field", 
          "k": 10 
        } 
      ], 
      "search": "hello world",
      "top": 500,
      "skip": 1500,
      "next": 500,
      "hybridSearch": { 
        "maxTextRecallSize": 5000, 
        "countAndFacetMode": "countRetrievableResults" 
      } 
    }

Configurare una risposta di query

Quando si configura la query ibrida, prendere in considerazione la struttura della risposta. La risposta è un set di righe bidimensionale. I parametri della query determinano quali campi si trovano in ogni riga e e quante righe sono presenti nella risposta. Il motore di ricerca classifica i documenti corrispondenti e restituisce i risultati più rilevanti.

Campi in una risposta

I risultati della ricerca sono costituiti dai campi retrievable dell'indice di ricerca. Un risultato può essere una delle due opzioni seguenti:

  • Tutti i campi retrievable (impostazione predefinita dell'API REST).
  • I campi elencati in modo esplicito in un parametro "select" della query.

Negli esempi di questo articolo è stata usata un'istruzione "select" per specificare i campi di testo (nonvector) nella risposta.

Nota

I vettori non vengono decodificati in testo leggibile dall'uomo, per cui è consigliabile evitare di restituirli nella risposta. Scegliere invece campi nonvector rappresentativi del documento di ricerca. Ad esempio, se la query è destinata a un campo "DescriptionVector", restituire un campo di testo equivalente se ne è presente uno ("Description") nella risposta.

Numero di risultati

Una query può corrispondere a un numero qualsiasi di documenti, persino a tutti, se i criteri di ricerca sono deboli (ad esempio "search=*" per una query nulla). Poiché raramente è pratico restituire risultati illimitati, è necessario specificare un valore massimo per la risposta complessiva:

  • "top": n risultati per query basate solo su parole chiave (nessun vettore)
  • "k": n risultati per query unicamente vettoriali
  • "top": n risultati per query ibride (con o senza semantica) che includono un parametro "search"

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.

Nota

Se si usa la ricerca ibrida nell'API 2024-05-01-preview, è possibile controllare il numero di risultati della query con parola chiave usando maxTextRecallSize. Combinare questa impostazione con quella di "k" per controllare la rappresentazione di ogni sottosistema di ricerca (parola chiave e vettore).

Risultati del classificatore semantico

Nota

Il classificatore semantico può accettare fino a 50 risultati.

Se si usa il classificatore semantico nell'API 2024-05-01-preview, è consigliabile impostare "k" e "maxTextRecallSize" in modo che la somma sia almeno 50 in totale. È quindi possibile limitare i risultati restituiti all'utente con il parametro "top".

Se si usa il classificatore semantico nelle API precedenti, eseguire le operazioni seguenti:

  • se si esegue la ricerca basata solo su parola chiave (nessun vettore), impostare "top" su 50
  • se si esegue la ricerca ibrida, impostare "k" su 50, per assicurarsi che il classificatore semantico ottenga almeno 50 risultati.

Classifica

Per le query ibride vengono creati più set, con o senza la riclassificazione semantica facoltativa. La classificazione dei risultati viene calcolata in base alla Reciprocal Rank Fusion (RRF).

In questa sezione, si confrontano le risposte tra la ricerca vettoriale singola e la ricerca ibrida semplice per ottenere il risultato migliore. I diversi algoritmi di classificazione, la metrica di similarità di HNSW e RRF in questo caso, producono punteggi con valori diversi. Questo comportamento è impostato a livello di progettazione. II punteggi RRF possono apparire piuttosto bassi, anche con una corrispondenza di similarità elevata. I punteggi inferiori sono una caratteristica dell'algoritmo RRF. In una query ibrida con RRF, nei risultati viene inclusa una parte maggiore del reciproco dei documenti classificati, dato il punteggio relativamente inferiore dei documenti classificati RRF, rispetto alla ricerca vettoriale pura.

Ricerca vettoriale singola: @search.score per i risultati ordinati in base alla similarità del coseno (funzione di distanza di similarità vettoriale predefinita).

{
    "@search.score": 0.8399121,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

Ricerca ibrida: @search.score per i risultati ibridi classificati usando la Reciprocal Rank Fusion.

{
    "@search.score": 0.032786883413791656,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center.",
    "Category": "Luxury",
    "Address": {
    "City": "Arlington"
    }
}

Passaggi successivi

Come passaggio successivo, è consigliabile esaminare il codice demo per Python, C# o JavaScript.