Abfragen eines Vektorsuchindex

Auf dieser Seite wird beschrieben, wie Sie einen Vektorsuchindex abfragen, einschließlich Paginierung, Filter und Reranking.

Beispielnotizbücher, die veranschaulichen, wie Sie Endpunkte und Indizes für die Vektorsuche erstellen und abfragen, finden Sie unter Notizbücher für die Vektorsuche. Referenzinformationen finden Sie in der Python SDK-Referenz.

Installation

Um das Vektorsuch-SDK zu verwenden, müssen Sie es in Ihrem Notizbuch installieren. Verwenden Sie den folgenden Code, um das Paket zu installieren:

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

Verwenden Sie dann den folgenden Befehl, um VectorSearchClientzu importieren:

from databricks.vector_search.client import VectorSearchClient

Informationen zur Authentifizierung finden Sie unter Datenschutz und Authentifizierung.

Wie man einen Vektorsuchindex abfragt

Sie können den Vektorsuchindex nur mithilfe des Python SDK, der REST-API oder der SQL-vector_search() AI-Funktion abfragen.

Der Standardabfragetyp ist ann (ungefährer Nachbar). Legen Sie den Parameter query_type auf hybridfest, um eine Hybrid-Schlüsselwort-Ähnlichkeitssuche auszuführen. Bei der Hybridsuche werden alle Textmetadatenspalten eingeschlossen, und maximal 200 Ergebnisse werden zurückgegeben.

Informationen zum Verwenden des Rerankers in einer Abfrage finden Sie unter Verwenden des Rerankers in einer Abfrage.

Python SDK-Standardendpunkt

Ausführliche Informationen finden Sie in der SDK-Referenz Python.

# 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-speicheroptimierter Endpunkt

Ausführliche Informationen finden Sie in der SDK-Referenz Python.

Die vorhandene Filterschnittstelle wurde für speicheroptimierte Vektorsuchindizes neu entwickelt, um eine SQL-ähnliche Filterzeichenfolge anstelle des Filterwörterbuchs zu übernehmen, das in Standardvektorsuchendpunkten verwendet wird.

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

Weitere Informationen finden Sie in der REST-API-Referenzdokumentation: POST /api/2.0/vector-search/indexes/{index_name}/query.

Für Produktionsanwendungen empfiehlt Databricks die Verwendung von Dienstprinzipalen anstelle von persönlichen Zugriffstoken. Zusätzlich zur verbesserten Sicherheits- und Zugriffsverwaltung kann die Verwendung von Dienstprinzipalen die Leistung um bis zu 100 msec pro Abfrage verbessern.

Das folgende Codebeispiel veranschaulicht, wie ein Index mithilfe eines Serviceprinzips abgefragt wird.

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

Im folgenden Codebeispiel wird veranschaulicht, wie sie einen Index mithilfe eines persönlichen Zugriffstokens (PERSONAL Access Token, PAT) abfragen.

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

Informationen zur Verwendung dieser KI-Funktionfinden Sie unter vector_search-Funktion.

Paginierung

Wenn eine Abfrage mehr als 1.000 Ergebnisse anfordert, werden die Ergebnisse automatisch auf Seiten von bis zu 1.000 zurückgegeben. Die maximale Anzahl der Ergebnisse, die eine einzelne Abfrage auf allen Seiten zurückgeben kann, beträgt 10.000. Sowohl standard- als auch speicheroptimierte Endpunkte unterstützen die Paginierung.

Die Paginierung funktioniert mit allen Abfragetypen.

Python SDK

Das Python SDK behandelt die Paginierung transparent. Wenn Sie num_results auf einen Wert festlegen, der größer als 1.000 ist, ruft das SDK automatisch alle Seiten ab und gibt das vollständige Result-Set zurück. Es ist kein zusätzlicher Code erforderlich.

# 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

Wenn Sie die REST-API direkt verwenden, müssen Sie die Paginierung manuell behandeln. Wenn weitere Ergebnisse verfügbar sind, enthält die Antwort ein next_page_token Feld. Um die nächste Seite der Ergebnisse abzurufen, übergeben Sie dieses Token an den Endpunkt der nächsten Seite der Abfrage.

Weitere Informationen finden Sie in der REST-API-Referenzdokumentation: 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>"}'

Rufen Sie den Endpunkt der nächsten Seite der Abfrage mit der next_page_token von jeder Antwort aus, bis das Token leer oder nicht vorhanden ist, was angibt, dass alle Ergebnisse zurückgegeben wurden.

Verwenden von Filtern für Abfragen

Eine Abfrage kann Filter basierend auf einer beliebigen Spalte in der Delta-Tabelle definieren. similarity_search gibt nur Zeilen zurück, die den angegebenen Filtern entsprechen.

In der folgenden Tabelle sind die unterstützten Filter aufgeführt.

Hinweise zur Nutzung von LIKE

LIKE Beispiele für Standardendpunkte

{"column LIKE": "apple"}: entspricht den Zeichenfolgen "Apfel" und "Apfelbirne", stimmt aber nicht mit "Ananas" überein. Beachten Sie, dass sie nicht mit "Ananas" übereinstimmt, obwohl sie eine Teilzeichenfolge "Apfel" enthält – es sucht nach einer genauen Übereinstimmung über Leerzeichen getrennte Token wie in "Apfelbirne".

{"column NOT LIKE": "apple"} tut das Gegenteil. Sie entspricht „pineapple” und „pear”, aber nicht „apple” oder „apple pear”.

LIKE Beispiele für speicheroptimierte Endpunkte

Code-Beispiele

Python SDK-Standardendpunkt

# 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-speicheroptimierter Endpunkt

# 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

Weitere Informationen unter POST /api/2.0/vector-search/indexes/{index_name}/query.

Verwenden Sie den Reranker in einer Abfrage

Die Agentleistung hängt vom Abrufen der relevantesten Informationen für eine Abfrage ab. Das Reranking ist eine Technik, die die Abrufqualität verbessert, indem die abgerufenen Dokumente ausgewertet werden, um diejenigen zu identifizieren, die semantisch relevant sind. Databricks hat ein forschungsbasiertes Verbund-KI-System entwickelt, um diese Dokumente zu identifizieren. Sie können auch Spalten mit Metadaten angeben, die der Reranker für zusätzlichen Kontext verwenden soll, da es die Relevanz jedes Dokuments bewertet.

Das Reranking verursacht eine geringe Latenzverzögerung, kann jedoch die Abrufqualität und die Agentleistung erheblich verbessern. Databricks empfiehlt, die Neusortierung für jeden Anwendungsfall eines RAG-Agents auszuprobieren.

Die Beispiele in diesem Abschnitt zeigen, wie der Vektorsuche-Reranker verwendet wird. Wenn Sie den Reranker verwenden, legen Sie fest, dass die Spalten zurückgegeben werden sollen (columns) und dass die Metadatenspalten separat zur Nutzung für die Neurankung verwendet werden sollen (columns_to_rerank). num_results ist die endgültige Anzahl der zurückzugebenden Ergebnisse. Dies wirkt sich nicht auf die Anzahl der Ergebnisse aus, die für die Reranking verwendet werden.

Die Abfragedebugmeldung enthält Informationen dazu, wie lange der Reranking-Schritt ausgeführt wurde. Beispiel:

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

Wenn der Reranker-Aufruf fehlschlägt, werden diese Informationen in der Debugmeldung enthalten:

'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

Um sicherzustellen, dass Sie Latenzinformationen erhalten, legen Sie diese auf mindestens 1 fest debug_level .

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

Punkt-Nachschlagevorgänge

Verwenden Sie zum Nachschlagen eines Punkts einen Filter für eine beliebige Primärschlüsselspalte.