Utför en sökning i ett vektorsökningsindex

På den här sidan beskrivs hur du frågar efter ett vektorsökindex, inklusive sidnumrering, filter och omrankning.

Exempelnotebooks som visar hur du skapar och söker efter slutpunkter och index för vektorsökning finns i Exempelnotebooks för vektorsökning. Referensinformation finns i Python SDK-referens.

Installation

Om du vill använda SDK för vektorsökning måste du installera det i din notebook. Använd följande kod för att installera paketet:

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

Använd sedan följande kommando för att importera VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Information om autentisering finns i Dataskydd och autentisering.

Utföra frågor på ett vektorsökningsindex

Du kan bara köra frågor mot vektorsökningsindexet med hjälp av funktionen Python SDK, REST API eller SQL vector_search() AI.

Standardfrågetypen är ann (ungefärlig närmaste granne). Mer information om de olika hämtningsalgoritmerna finns i Hämtningsalgoritmer.

• Om du vill utföra en hybridsökning med nyckelordslikhet anger du parametern query_type till hybrid. Med hybridsökning inkluderas alla textmetadatakolumner och högst 200 resultat returneras.
• Information om hur du använder reranker i en fråga finns i Använda reranker i en fråga.

Python standardslutpunkt för SDK

Mer information finns i Python SDK-referens.

# 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
    )

Python SDK-lagringsoptimerad slutpunkt

Mer information finns i Python SDK-referens.

Det befintliga filtergränssnittet har utformats på nytt för lagringsoptimerade vektorsökningsindex för att införa en mer SQL-liknande filtersträng i stället för filterordlistan som används i standardvektorsökningsslutpunkter.

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

Se referensdokumentation för REST API: POST /api/2.0/vector-search/indexes/{index_name}/query.

För produktionsprogram rekommenderar Databricks att du använder tjänstens huvudnamn i stället för personliga åtkomsttoken. Förutom förbättrad säkerhets- och åtkomsthantering kan användning av tjänstens huvudnamn förbättra prestanda med upp till 100 msec per fråga.

Följande kodexempel illustrerar hur du gör förfrågningar mot ett index med hjälp av en tjänstprincip.

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

I följande kodexempel visas hur du kör frågor mot ett index med hjälp av en personlig åtkomsttoken (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

Information om hur du använder den här AI-funktionen finns i vector_search funktion.

Paginering

När en fråga begär mer än 1 000 resultat returneras resultatet automatiskt på sidor på upp till 1 000. Det maximala antalet resultat som en enskild fråga kan returnera på alla sidor är 10 000. Både standard- och lagringsoptimerade slutpunkter stöder sidnumrering.

Sidnumrering fungerar med alla frågetyper.

Python SDK

Python SDK hanterar paginering på ett osynligt sätt. När du anger num_results ett värde som är större än 1 000 hämtar SDK automatiskt alla sidor och returnerar den fullständiga resultatuppsättningen. Ingen ytterligare kod krävs.

# 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

När du använder REST-API:et direkt måste du hantera sidnumrering manuellt. Om fler resultat är tillgängliga innehåller svaret ett next_page_token fält. Om du vill hämta nästa sida med resultat, skickar du denna token till slutpunkten för nästa sida av frågan.

Se över REST API-referensdokumentationen: 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>"}'

Fortsätt att anropa slutpunkten för frågan nästa sida med next_page_token från varje svar tills token är tom eller frånvarande, vilket indikerar att alla resultat har returnerats.

Använda filter på frågor

En fråga kan definiera filter baserat på valfri kolumn i Delta-tabellen. similarity_search returnerar endast rader som matchar de angivna filtren.

I följande tabell visas de filter som stöds.

Anteckningar om användning av LIKE

LIKE exempel för standardslutpunkter

{"column LIKE": "apple"}: matchar strängarna "apple" och "apple pear" men matchar inte "ananas". Observera att den inte matchar "ananas" även om den innehåller ett substring "äpple" – det letar efter en exakt matchning över blankstegsavgränsade token som i "äppelpäron".

{"column NOT LIKE": "apple"} gör motsatsen. Den matchar "ananas" och "päron" men matchar inte "äpple" eller "äppelpäron".

LIKE exempel för lagringsoptimerade slutpunkter

Kodexempel

Python standardslutpunkt för 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
    )

Python SDK-lagringsoptimerad slutpunkt

# 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

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

Använda rerankern i en fråga

Agentprestanda beror på hur du hämtar den mest relevanta informationen för en fråga. Reranking är en teknik som förbättrar hämtningskvaliteten genom att utvärdera de hämtade dokumenten för att identifiera de som är semantiskt mest relevanta. Databricks har utvecklat ett forskningsbaserat sammansatt AI-system för att identifiera dessa dokument. Du kan också ange kolumner som innehåller metadata som du vill att rerankern ska använda för ytterligare kontext när den utvärderar varje dokuments relevans.

Att ändra rangordning medför en liten fördröjning, men kan avsevärt förbättra hämtningskvaliteten och agentprestandan. Databricks rekommenderar att du provar att ändra rangordning för alla RAG-agentanvändningsfall.

Exemplen i det här avsnittet visar hur du använder vektorsökningsrerankern. När du använder reranker anger du att kolumnerna ska returnera (columns) och de metadatakolumner som ska användas för att ändra rangordning (columns_to_rerank) separat. num_results är det slutliga antalet resultat som ska returneras. Detta påverkar inte antalet resultat som används för att ändra rangordning.

Frågefelsökningsmeddelandet innehåller information om hur lång tid det tog att ändra rangordning. Till exempel:

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

Om reranker-anropet misslyckas inkluderas den informationen i felsökningsmeddelandet:

'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

För att säkerställa att du får svarstidsinformation anger du debug_level till minst 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}'

Punktsökningar

Om du vill göra en punktsökning använder du ett filter på valfri primärnyckelkolumn.

Hämtningsalgoritmer

I det här avsnittet beskrivs de olika hämtningsalgoritmerna eller frågetyperna och när var och en kan användas. Använd parametern query_type för att ange vilken hämtningsalgoritm som ska användas. Information om hur du automatiskt jämför prestanda för olika algoritmer för ditt index finns i Utvärdera vektorsökningens hämtningskvalitet.

ANN (vektorsökning)

ANN-sökning konverterar en fråga till en vektorinbäddning och hittar dokument vars inbäddningar är som mest lika. Detta är effektivt för att förstå innebörden. Till exempel matchar en fråga som "hur du åtgärdar ett trasigt rör" dokument om VVS även om de inte innehåller de exakta orden.

• När ANN fungerar bra: Frågor är konceptuella, konversationsmässiga eller använder andra ordförråd än dokumenten.
• När ANN kan underprestera: Frågor förlitar sig på exakta nyckelord, lämpliga substantiv eller domänspecifik terminologi som inbäddningar kanske inte samlar in exakt.

Fulltext (nyckelordssökning)

Fulltextsökning matchar dokument som innehåller frågetermerna. Fulltextsökning har hög precision. När användare söker efter specifika namn, koder eller tekniska termer hittar nyckelordsmatchning exakta träffar som vektorsökningen kan missa.

• När fulltext fungerar bra: Frågor innehåller specifika identifierare, produktnamn, felkoder eller domänspecifik terminologi.
• När fulltext kan underprestera: Frågor formuleras på ett annat sätt än dokumenten eller använder synonymer och parafraser.

Hybridsökning

Hybridsökningen kör både ANN- och fulltextsökningar parallellt och sammanfogar sedan resultaten med hjälp av Reciprocal Rank Fusion (RRF). Detta kombinerar den semantiska förståelsen av vektorsökning med precisionen för nyckelordsmatchning.

• När hybridsökningen fungerar bra: Frågearbetsbelastningen är en blandning av konceptuella och nyckelordsintensiva frågor. Hybrid är den mest robusta strategin för generell användning.

Reranker

En reranker är ett valfritt andra pass som tillämpas ovanpå vilken strategi som helst. Efter den inledande hämtningen utvärderar en korskodarmodell varje resultat i frågans kontext, vilket ger en mer exakt relevansordning.

Rerankern förbättrar vanligtvis kvaliteten med cirka 10% men lägger till svarstid. Den är lämplig för program där kvalitet är viktigast, till exempel RAG-chattrobotar, men potentiellt mindre lämplig för sökprogram med högt dataflöde och låg latens.