Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
Op deze pagina wordt beschreven hoe u een query uitvoert op een vectorzoekindex, waaronder paginering, filters en opnieuw rangtekening.
Zie bijvoorbeeld notebooks die illustreren hoe u eindpunten en indexen voor vectorzoekopdrachten kunt maken en opvragen, Vector search voorbeeldnotebooks. Zie de Python SDK-verwijzing voor naslaginformatie.
Installatie
Als u de Vector Search SDK wilt gebruiken, moet u deze installeren in uw notebook. Gebruik de volgende code om het pakket te installeren:
%pip install databricks-vectorsearch
dbutils.library.restartPython()
Gebruik vervolgens de volgende opdracht om VectorSearchClientte importeren:
from databricks.vector_search.client import VectorSearchClient
Zie Gegevensbescherming en -verificatie voor meer informatie over verificatie.
Een query uitvoeren op een vectorzoekindex
U kunt alleen een query uitvoeren op de vectorzoekindex met behulp van de Python SDK, de REST API of de SQL vector_search() AI-functie.
Opmerking
Als de gebruiker die de index opvraagt niet de eigenaar is van de vectorzoekindex, moet de gebruiker de volgende UC-bevoegdheden hebben:
- USE CATALOG in de catalogus die de vectorzoekindex bevat.
- USE SCHEMA in het schema dat de vectorzoekindex bevat.
- SELECT op de vectorzoekindex.
Het standaardquerytype is ann (bij benadering dichtstbijzijnde buur). Voor details over de verschillende ophaalalgoritmen, zie Ophaalalgoritmen.
- Als u een zoekopdracht voor hybride trefwoorden wilt uitvoeren, stelt u de parameter
query_typein ophybrid. Bij hybride zoekopdrachten worden alle kolommen met tekstmetagegevens opgenomen en worden maximaal 200 resultaten geretourneerd. - Zie De reranker gebruiken in een query voor het gebruik ervan.
Belangrijk
Zoeken in volledige tekst is beschikbaar als bètafunctie. Als u een zoekopdracht in volledige tekst wilt uitvoeren, stelt u de parameter in query_type op FULL_TEXT. Met zoeken in volledige tekst kunt u maximaal 200 resultaten ophalen op basis van trefwoordkoppeling zonder vectorinsluitingen te gebruiken. Query's met volledige tekst worden ondersteund op zowel standaard- als op opslag geoptimaliseerde eindpunten. Op eindpunten die zijn geoptimaliseerd voor opslag, kunt u ook een speciale zoekindex voor volledige tekst maken zonder insluitingen. Zie Een zoekindex voor volledige tekst maken (bèta).
Python SDK-standaardeindpunt
Zie de Python SDK-verwijzing voor meer informatie.
# 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 eindpunt geoptimaliseerd voor opslag
Zie de Python SDK-verwijzing voor meer informatie.
De bestaande filterinterface is opnieuw ontworpen voor door opslag geoptimaliseerde vectorzoekindexen om een meer SQL-achtige filtertekenreeks te gebruiken in plaats van de filterwoordenlijst die wordt gebruikt in standaard vectorzoekeindpunten.
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
Zie de REST API-referentiedocumentatie: POST /api/2.0/vector-search/indexes/{index_name}/query.
Voor productietoepassingen raadt Databricks aan om service-principals te gebruiken in plaats van persoonlijke toegangstokens. Naast verbeterd beveiligings- en toegangsbeheer, kan het gebruik van service-principals de prestaties verbeteren met maximaal 100 msec per query.
In het volgende codevoorbeeld ziet u hoe u een query uitvoert op een index met behulp van een service-principal.
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}'
In het volgende codevoorbeeld ziet u hoe u een query kunt uitvoeren op een index met behulp van een persoonlijk toegangstoken (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
Belangrijk
De vector_search() AI-functie bevindt zich in openbare voorvertoning.
Pagina-indeling
Wanneer een query meer dan 1000 resultaten aanvraagt, worden de resultaten automatisch geretourneerd op pagina's van maximaal 1000. Het maximum aantal resultaten dat één query op alle pagina's kan retourneren, is 10.000. Zowel standaard- als voor opslag geoptimaliseerde eindpunten bieden ondersteuning voor paginering.
Paginering werkt met alle querytypen.
Python SDK
De Python SDK verwerkt paginering transparant. Wanneer u instelt num_results op een waarde die groter is dan 1000, haalt de SDK automatisch alle pagina's op en wordt de volledige resultatenset geretourneerd. Er is geen extra code vereist.
# 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
Wanneer u de REST API rechtstreeks gebruikt, moet u paginering handmatig afhandelen. Als er meer resultaten beschikbaar zijn, bevat het antwoord een next_page_token veld. Als u de volgende pagina met resultaten wilt ophalen, geeft u dit token door aan het eindpunt van de query volgende pagina.
Zie de REST API-referentiedocumentatie: 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>"}'
Ga door met het aanroepen van het eindpunt van de query volgende pagina met het next_page_token antwoord totdat het token leeg of afwezig is, wat aangeeft dat alle resultaten zijn geretourneerd.
Filters gebruiken voor query's
Een query kan filters definiëren op basis van elke kolom in de Delta-tabel.
similarity_search retourneert alleen rijen die overeenkomen met de opgegeven filters.
De volgende tabel bevat de ondersteunde filters.
Opmerking
Voor opslag-geoptimaliseerde eindpunten worden de resultaten overgehaald. Als u deze optie instelt num_resultsk, worden er meer dan k resultaten opgehaald en wordt het filter toegepast op de opgehaalde resultaten. Het is mogelijk dat er geen resultaten worden geretourneerd, zelfs als er resultaten zijn in de gegevensset die overeenkomt met de filtervoorwaarde, als de score van deze documenten niet tot de top behoort.
| Filteroperator | Gedrag | Voorbeelden |
|---|---|---|
NOT |
Standaard: het filter wordt ontkend. De sleutel moet eindigen op 'NIET'. 'color NOT' met de waarde 'rood' komt bijvoorbeeld overeen met documenten waarbij de kleur niet rood is. Geoptimaliseerd voor opslag: zie != de operator (bangeq-teken). |
Standaard: {"id NOT": 2}{“color NOT”: “red”}Geoptimaliseerd voor opslag: "id != 2" "color != 'red'" |
< |
Standaard: controleert of de veldwaarde kleiner is dan de filterwaarde. De sleutel moet eindigen op ' <'. Bijvoorbeeld 'price <' met waarde 200 komt overeen met documenten waarbij de prijs kleiner is dan 200. Geoptimaliseerd voor opslag: zie < de operator (lt sign). |
Standaard: {"id <": 200}Geoptimaliseerd voor opslag: "id < 200" |
<= |
Standaard: controleert of de veldwaarde kleiner is dan of gelijk is aan de filterwaarde. De sleutel moet eindigen op "<=". Bijvoorbeeld : "price <=" met waarde 200 komt overeen met documenten waarbij de prijs kleiner is dan of gelijk is aan 200. Geoptimaliseerd voor opslag: zie <= de operator (lt eq sign). |
Standaard: {"id <=": 200}Geoptimaliseerd voor opslag: "id <= 200" |
> |
Standaard: controleert of de veldwaarde groter is dan de filterwaarde. De sleutel moet eindigen op ' >'. Bijvoorbeeld 'price >' met waarde 200 komt overeen met documenten waarbij de prijs groter is dan 200. Geoptimaliseerd voor opslag: zie > de operator (gt-teken). |
Standaard: {"id >": 200}Geoptimaliseerd voor opslag: "id > 200" |
>= |
Standaard: controleert of de veldwaarde groter is dan of gelijk is aan de filterwaarde. De sleutel moet eindigen op ">=". Bijvoorbeeld: 'price >=' met waarde 200 komt overeen met documenten waarbij de prijs groter is dan of gelijk is aan 200. Geoptimaliseerd voor opslag: zie >= operator (gt eq-teken). |
Standaard: {"id >=": 200}Geoptimaliseerd voor opslag: "id >= 200" |
OR |
Standaard: controleert of de veldwaarde overeenkomt met een van de filterwaarden. De sleutel moet OR bevatten om meerdere subsleutels te scheiden.
color1 OR color2 met waarde ["red", "blue"] bijvoorbeeld overeenkomt met documenten waarbij color1red is of color2blueis.Geoptimaliseerd voor opslag: zie or operator. |
Standaard: {"color1 OR color2": ["red", "blue"]}Geoptimaliseerd voor opslag: "color1 = 'red' OR color2 = 'blue'" |
LIKE |
Standaard: komt overeen met door witruimten gescheiden tokens in een tekenreeks. Geoptimaliseerd voor opslag: zie like operator. |
Zie Opmerkingen over het gebruik van LIKE. |
| Er is geen filteroperator opgegeven |
Standaard: Filter controleert op een exacte overeenkomst. Als er meerdere waarden zijn opgegeven, komt deze overeen met een van de waarden. Geoptimaliseerd voor opslag: zie = de operator (eq sign) en in het predicaat. |
Standaard: {"id": 200}{"id": [200, 300]}Geoptimaliseerd voor opslag: "id = 200""id IN (200, 300)" |
to_timestamp (alleen voor opslag geoptimaliseerde eindpunten) |
Geoptimaliseerd voor opslag: filteren op een tijdstempel. Zie to_timestamp functie |
Geoptimaliseerd voor opslag: "date > TO_TIMESTAMP('1995-01-01')" |
Opmerkingen over het gebruik van LIKE
LIKE voorbeelden voor standaardeindpunten
{"column LIKE": "apple"}: komt overeen met de tekenreeksen "appel" en "appelpeen", maar komt niet overeen met "ananas". Houd er rekening mee dat het niet overeenkomt met 'ananas', ook al bevat het een subtekenreeks 'appel'. Het zoekt naar een exacte overeenkomst over door witruimte gescheiden tokens, zoals in 'appelpeen'.
{"column NOT LIKE": "apple"} doet het tegenovergestelde. Het komt overeen met "ananas" en "peer", maar komt niet overeen met "appel" of "appelpeer".
LIKE voorbeelden voor opslag-geoptimaliseerde eindpunten
| Formaat | Overeenkomsten |
|---|---|
"column LIKE 'apple'" |
Gelijk aan = operator. Retourneert alleen exacte overeenkomsten. |
"column LIKE 'apple%'" |
Retourneert rijen waarbij een voorvoegsel overeenkomt apple, zoals applepie. |
"column LIKE '%apple'" |
Retourneert rijen waarbij een achtervoegsel overeenkomt apple, zoals pineapple. |
"column LIKE '%apple%'" |
Retourneert rijen met een subtekenreeks die overeenkomt apple, zoals pineapplecake. |
Codevoorbeelden
Python SDK-standaardeindpunt
# 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 opslag-geoptimaliseerd eindpunt
# 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
Zie POST /api/2.0/vector-search/indexes/{index_name}/query.
De rerankeerfunctie gebruiken in een query
De prestaties van de agent zijn afhankelijk van het ophalen van de meest relevante informatie voor een query. Rerankeren is een techniek die de kwaliteit van het ophalen verbetert door de opgehaalde documenten te evalueren om de documenten te identificeren die semantisch het meest relevant zijn. Databricks heeft een samengesteld AI-systeem op basis van onderzoek ontwikkeld om deze documenten te identificeren. U kunt ook kolommen opgeven die metagegevens bevatten die u wilt gebruiken voor extra context, terwijl de relevantie van elk document wordt beoordeeld.
Het opnieuw rangstellen zorgt voor een kleine vertraging in de latentie, maar kan de kwaliteit van het ophalen en de prestaties van de agent aanzienlijk verbeteren. Databricks raadt aan om de rerankering uit te proberen voor een rag-agent-use-case.
In de voorbeelden in deze sectie wordt getoond hoe u de vectorzoekreranker kunt gebruiken. Wanneer u de herrankering gebruikt, stelt u de kolommen in op het retourneren (columns) en de metagegevenskolommen die u afzonderlijk wilt gebruiken voor het opnieuw rangzetten (columns_to_rerank).
num_results is het definitieve aantal resultaten dat moet worden geretourneerd. Dit heeft geen invloed op het aantal resultaten dat wordt gebruikt voor herrankering.
Het bericht over foutopsporing van query's bevat informatie over hoe lang de herrankeringsstap duurde. Voorbeeld:
'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}
Als de aanroep van de reranker mislukt, wordt deze informatie opgenomen in het foutopsporingsbericht:
'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.'}]}
Opmerking
De volgorde waarin kolommen worden vermeld columns_to_rerank , is belangrijk. De herrankeringsberekening neemt de kolommen in de volgorde waarin ze worden weergegeven en houdt alleen rekening met de eerste 2000 tekens die worden gevonden.
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
Om ervoor te zorgen dat u latentiegegevens krijgt, stelt u in debug_level op ten minste 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}'
Puntzoekacties
Als u een puntzoekactie wilt uitvoeren, gebruikt u een filter op een primaire-sleutelkolom.
Ophaalalgoritmen
In deze sectie worden de verschillende algoritmen of querytypen voor het ophalen beschreven en wanneer deze kunnen worden gebruikt. Gebruik de query_type parameter om het ophaalalgoritme op te geven dat moet worden gebruikt. Als u automatisch de prestaties van verschillende algoritmen voor uw index wilt vergelijken, ziet u Evalueren van de kwaliteit van vectorzoekopdrachten.
| Strategie | Hoe werkt het? | Ideaal voor |
|---|---|---|
| ANN (dichtstbijzijnde buur) | Zoekopdrachten met behulp van vector insluitingen om semantisch vergelijkbare documenten te vinden. | Conceptuele en semantische query's waarbij betekenis belangrijker is dan exacte formulering. |
| Volledige tekst | Trefwoordzoekopdrachten die overeenkomen met exacte termen. | Query's met specifieke termen, juiste zelfstandige naamwoorden, product-id's of technische jargon. |
| Hybride | Combineert ANN- en volledige tekstresultaten met behulp van Reciprocal Rank Fusion (RRF). | Ophalen voor algemeen gebruik. Het aanbevolen uitgangspunt voor de meeste gebruiksvoorbeelden. |
| Hybride + reranker | Voert een hybride zoekopdracht uit en scoort vervolgens de resultaten opnieuw met een cross-encoder herordeneringsmodel. | Hogere precisie wanneer latentie toestaat (~1,5s extra per query). |
ANN (vectorzoekopdracht)
ANN-zoekopdracht converteert een query naar een vector insluiten en zoekt documenten waarvan de insluitingen het meest vergelijkbaar zijn. Dit is effectief om betekenis te begrijpen. Een query zoals 'Een gebroken pijp herstellen' komt bijvoorbeeld overeen met documenten over loodgieters, zelfs als ze niet die exacte woorden bevatten.
- Wanneer ANN goed presteert: query's zijn conceptueel, gespreksmatig of gebruiken andere woordenlijst dan de documenten.
- Wanneer ANN mogelijk minder goed presteert: query's zijn afhankelijk van exacte trefwoorden, de juiste zelfstandige naamwoorden of domeinspecifieke terminologie die insluitingen mogelijk niet nauwkeurig vastleggen.
Volledige tekst (trefwoorden zoeken)
Zoeken in volledige tekst komt overeen met documenten met de querytermen. Zoeken in volledige tekst heeft hoge precisie. Wanneer gebruikers zoeken naar specifieke namen, codes of technische termen, vindt trefwoordmatching exacte treffers die vectorgebaseerd zoeken kan missen.
- Wanneer volledige tekst goed presteert: query's bevatten specifieke id's, productnamen, foutcodes of domeinspecifieke terminologie.
- Wanneer volledige tekst minder goed presteert: query's worden anders geformuleerd dan de documenten of gebruiken synoniemen en parafrasies.
Hybride zoekopdracht
Met hybride zoekopdrachten worden zowel ANN- als volle-tekst zoekopdrachten parallel uitgevoerd en worden de resultaten samengevoegd met behulp van Reciprocal Rank Fusion (RRF). Dit combineert het semantische begrip van vectorzoekopdrachten met de precisie van trefwoordkoppeling.
- Wanneer hybride zoekopdrachten goed presteren: de queryworkload is een combinatie van conceptuele en trefwoord-intensieve query's. Hybride is de meest robuuste strategie voor algemeen gebruik.
Herrankeerder
De reranker is een optionele tweede pass die wordt toegepast bovenop een willekeurige strategie. Na het initiële ophalen evalueert een model voor meerdere coderingsprogramma's elk resultaat opnieuw in de context van de query, wat nauwkeurigere relevantievolgorde produceert.
De reranker verbetert doorgaans de kwaliteit met ongeveer 10%, maar voegt latentie toe. Het is geschikt voor toepassingen waarbij kwaliteit het belangrijkst is, zoals RAG-chatbots, maar mogelijk minder geschikt voor zoektoepassingen met een hoge doorvoer, lage latentie.