Eseguire query su un indice di ricerca vettoriale

Questa pagina descrive come eseguire query su un indice di ricerca vettoriale, tra cui paginazione, filtri e reranking.

Per esempio, consulta i notebook che illustrano come creare ed eseguire query su endpoint e indici di ricerca vettoriale in Notebook di ricerca vettoriale di esempio. Per informazioni di riferimento, vedere le informazioni di riferimento Python SDK.

Installazione

Per usare l'SDK di ricerca vettoriale, è necessario installarlo nel notebook. Usare il codice seguente per installare il pacchetto:

%pip install databricks-vectorsearch
dbutils.library.restartPython()

Usare quindi il comando seguente per importare VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Per informazioni sull'autenticazione, vedere Protezione dei dati e autenticazione.

Come eseguire query su un indice di ricerca vettoriale

È possibile eseguire query sull'indice di ricerca vettoriale solo usando Python SDK, l'API REST o la funzione SQL vector_search() per intelligenza artificiale.

Il tipo di query predefinito è ann (vicinanza più prossima approssimativa). Per informazioni dettagliate sui diversi algoritmi di recupero, vedere Algoritmi di recupero.

• Per eseguire una ricerca ibrida di somiglianza con parole chiave, impostare il parametro query_type su hybrid. Con la ricerca ibrida, vengono incluse tutte le colonne di metadati di testo e vengono restituiti un massimo di 200 risultati.
• Per usare il reranker in una query, vedere Usare il reranker in una query.

endpoint standard di Python SDK

Per informazioni dettagliate, vedere le informazioni di riferimento Python SDK.

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index using full-text search (Beta)
results4 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="FULL_TEXT"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.9] * 1024,
    columns=["id", "text"],
    num_results=2
    )

endpoint ottimizzato per l'archiviazione di Python SDK

Per informazioni dettagliate, vedere le informazioni di riferimento Python SDK.

L'interfaccia filtro esistente è stata ripensata per gli indici di ricerca vettoriali ottimizzati per l'archiviazione per adottare una stringa di filtro più simile a SQL anziché il dizionario di filtri usato negli endpoint di ricerca vettoriale standard.

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

# similarity search with query vector
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
)

# similarity search with query vector and filter string
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    # this is a single filter string similar to SQL WHERE clause syntax
    filters="language = 'en' AND country = 'us'",
    num_results=2
)

REST API

Consultare la documentazione di riferimento dell'API REST: POST /api/2.0/vector-search/indexes/{index_name}/query.

Per le applicazioni di produzione, Databricks consiglia di usare principali di servizio anziché token di accesso personali. Oltre a migliorare la sicurezza e la gestione degli accessi, l'uso dei principali di servizio può migliorare le prestazioni fino a 100 msec per query.

Nell'esempio di codice seguente viene illustrato come eseguire una query su un indice usando un principale del servizio.

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint, then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

# Generate OAuth token
export TOKEN=$(curl -X POST  --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

Nell'esempio di codice seguente viene illustrato come eseguire query su un indice usando un token di accesso personale ( PAT).

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Query vector search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query vector search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

SQL

Per usare la funzione di intelligenza artificiale , vedere la funzione vector_search.

Impaginazione

Quando una query richiede più di 1.000 risultati, i risultati vengono restituiti automaticamente in pagine fino a 1.000. Il numero massimo di risultati che una singola query può restituire in tutte le pagine è 10.000. Gli endpoint standard e ottimizzati per l'archiviazione supportano la paginazione.

La paginazione funziona con tutti i tipi di query.

PYTHON SDK

L'SDK Python gestisce la paginazione in modo trasparente. Quando si imposta num_results su un valore maggiore di 1.000, l'SDK recupera automaticamente tutte le pagine e restituisce il set di risultati completo. Non è necessario alcun codice aggiuntivo.

# The SDK automatically paginates and returns all 5000 results
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=5000
)

REST API

Quando si usa direttamente l'API REST, è necessario gestire manualmente la paginazione. Se sono disponibili più risultati, la risposta include un next_page_token campo. Per recuperare la pagina successiva dei risultati, passare questo token all'endpoint "query-next-page".

Vedere la documentazione di riferimento dell'API REST: POST /api/2.0/vector-search/indexes/{index_name}/query-next-page.

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Initial query - if num_results exceeds 1000, the response includes next_page_token
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query \
  --data '{"num_results": 5000, "query_text": "...", "columns": ["id", "text"]}'

# Use next_page_token from the response to get the next page
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query-next-page \
  --data '{"page_token": "<next_page_token from previous response>"}'

Continua a chiamare l'endpoint query-next-page con il next_page_token di ogni risposta fino a quando il token è vuoto o assente, il che indica che tutti i risultati sono stati restituiti.

Usare filtri per le query

Una query può definire filtri in base a qualsiasi colonna della tabella Delta. similarity_search restituisce solo le righe che corrispondono ai filtri specificati.

Nella tabella seguente sono elencati i filtri supportati.

Note sull'utilizzo di LIKE

LIKE esempi per gli endpoint standard

{"column LIKE": "apple"}: corrisponde alle stringhe "apple" e "mela pera", ma non corrisponde a "ananas". Si noti che non corrisponde a "ananas" anche se contiene una sottostringa "apple" – cerca una corrispondenza esatta su token separati da spazi vuoti come in "mela pera".

{"column NOT LIKE": "apple"} fa l'opposto. Corrisponde a "ananas" e "pera", ma non corrisponde a "mela" o "pera mela".

LIKE esempi per gli endpoint ottimizzati per l'archiviazione

Esempi di codice

endpoint standard di Python SDK

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]},
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"},
    num_results=2
    )

endpoint ottimizzato per l'archiviazione di Python SDK

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title IN ("Ares", "Athena")',
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title = "Ares" OR id = "Athena"',
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title != "Hercules"',
    num_results=2
    )

REST API

Vedere POST /api/2.0/vector-search/indexes/{index_name}/query.

Usare il reranker in una query

Le prestazioni dell'agente dipendono dal recupero delle informazioni più rilevanti per una query. Reranking è una tecnica che migliora la qualità del recupero valutando i documenti recuperati per identificare quelli che sono semanticamente più rilevanti. Databricks ha sviluppato un sistema di IA composto basato sulla ricerca per identificare questi documenti. È anche possibile specificare colonne contenenti metadati che si desidera utilizzare per il reranker per un contesto aggiuntivo durante la valutazione della pertinenza di ogni documento.

La *reranking* comporta un piccolo ritardo di latenza, ma può migliorare significativamente la qualità del recupero delle informazioni e le prestazioni dell'agente. Databricks consiglia di provare a eseguire il reranking per qualsiasi caso d'uso dell'agente RAG.

Gli esempi in questa sezione illustrano come usare il reranker di ricerca vettoriale. Quando si usa il reranker, si impostano le colonne da restituire (columns) e le colonne di metadati da usare separatamente per il reranking (columns_to_rerank). num_results è il numero finale di risultati da restituire. Ciò non influisce sul numero di risultati utilizzati per la reranking.

Il messaggio di debug della query include informazioni sulla durata della fase di riordino. Per esempio:

'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}

Se la chiamata di reranker ha esito negativo, tali informazioni vengono incluse nel messaggio di debug:

'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}

PYTHON SDK

# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()

from databricks.vector_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create a Vector Search index",
    columns = ["id", "text", "parent_doc_summary", "date"],
    num_results = 10,
    query_type = "hybrid",
    reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
    )

REST API

Per assicurarsi di ottenere informazioni sulla latenza, impostare debug_level su almeno 1.

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 10, "query_text": "How to create a Vector Search index", "columns": ["id", "text", "parent_doc_summary", "date"], "reranker": {"model": "databricks_reranker",
             "parameters": {
               "columns_to_rerank":
                 ["text", "parent_doc_summary"]
              }
             },
"debug_level": 1}'

Ricerche di punti

Per eseguire una ricerca di punti, usare un filtro per qualsiasi colonna chiave primaria.

Algoritmi di recupero

In questa sezione vengono descritti i diversi algoritmi di recupero o tipi di query e quando è possibile utilizzarli. Usare il query_type parametro per specificare l'algoritmo di recupero da usare. Per confrontare automaticamente le prestazioni di algoritmi diversi per l'indice, vedere Valutare la qualità del recupero della ricerca vettoriale.

ANN (ricerca vettoriale)

La ricerca ANN converte una query in un incorporamento vettoriale e trova i documenti i cui incorporamenti sono più simili. Questo è efficace per comprendere il significato. Ad esempio, una query come "come riparare un tubo rotto" corrisponde ai documenti relativi all'idraulica anche se non contengono queste parole esatte.

• Quando ann funziona bene: le query sono concettuali, conversazionali o usano vocabolario diverso rispetto ai documenti.
• Quando l'ANN potrebbe avere prestazioni scarse: le query si basano su parole chiave esatte, sostantivi appropriati o terminologia specifica del dominio che gli incorporamenti potrebbero non acquisire esattamente.

Full-text (ricerca di parole chiave)

La ricerca full-text trova i documenti contenenti i termini di ricerca. La ricerca full-text ha una precisione elevata. Quando gli utenti cercano nomi, codici o termini tecnici specifici, la corrispondenza delle parole chiave trova riscontri esatti che la ricerca vettoriale potrebbe perdere.

• Quando il full-text funziona correttamente: le query contengono identificatori specifici, nomi di prodotto, codici di errore o terminologia specifica del dominio.
• Quando il testo full-text potrebbe non performare al meglio: le query vengono espresse in modo diverso dai documenti o usano sinonimi e parafrasi.

Ricerca ibrida

La ricerca ibrida esegue in parallelo sia le ricerche con reti neurali artificiali (ANN) sia quelle full-text, poi unisce i risultati utilizzando la Fusione dei Ranghi Reciproci (RRF). Questo combina la comprensione semantica della ricerca vettoriale con la precisione della corrispondenza delle parole chiave.

• Quando la ricerca ibrida offre prestazioni elevate: il carico di lavoro delle query è una combinazione di query concettuali e con un numero elevato di parole chiave. La soluzione ibrida è la strategia più affidabile per utilizzo generico.

Reranker

Il reranker è un secondo passaggio facoltativo sovrapposto a qualsiasi strategia. Dopo il recupero iniziale, un modello di codificatore incrociato rivaluta ogni risultato nel contesto della query, generando un ordinamento di pertinenza più accurato.

Il reranker migliora in genere la qualità di circa 10%, ma aggiunge latenza. È adatto per le applicazioni in cui la qualità è più importante, ad esempio chatbot RAG, ma potenzialmente meno adatta per applicazioni di ricerca ad alta velocità effettiva e a bassa latenza.