Interroger un index de recherche vectorielle

Cette page explique comment interroger un index de recherche vectorielle, y compris la pagination, les filtres et la reclassement.

Pour obtenir des exemples de carnets illustrant comment créer et interroger des points de terminaison et des index de recherche vectorielle, consultez les exemples de carnets de recherche vectorielle. Pour obtenir des informations de référence, consultez la référence Python SDK.

Installation

Pour utiliser le Kit de développement logiciel (SDK) de recherche vectorielle, vous devez l’installer dans votre notebook. Utilisez le code suivant pour installer le package :

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

Utilisez ensuite la commande suivante pour importer VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Pour plus d’informations sur l’authentification, consultez Protection et authentification des données.

Comment interroger un index de recherche vectorielle

Vous ne pouvez interroger l’index de recherche vectorielle qu’à l’aide du SDK Python, de l’API REST ou de la fonction SQL vector_search() AI.

Note

Si l’utilisateur interroge l’index n’est pas le propriétaire de l’index de recherche vectorielle, l’utilisateur doit disposer des privilèges UC suivants :

USE CATALOG sur le catalogue qui contient l’index de recherche vectorielle.
USE SCHEMA sur le schéma qui contient l’index de recherche vectorielle.
SELECT sur l’index de recherche vectorielle.

Le type de requête par défaut est ann (voisin le plus proche approximatif). Pour plus d’informations sur les différents algorithmes de récupération, consultez Algorithmes de récupération.

Pour effectuer une recherche hybride par mot-clé et par similarité, définissez le paramètre query_type sur hybrid. Avec la recherche hybride, toutes les colonnes de métadonnées de texte sont incluses et un maximum de 200 résultats sont retournés.
Pour utiliser le reranker dans une requête, consultez Utiliser le reranker dans une requête.

Important

La recherche en texte intégral est disponible en tant que fonctionnalité bêta. Pour effectuer une recherche en texte intégral, définissez le paramètre query_type sur FULL_TEXT. Avec la recherche en texte intégral, vous pouvez récupérer jusqu’à 200 résultats en fonction de la correspondance de mots clés sans utiliser d’incorporations vectorielles. Les requêtes en texte intégral sont prises en charge sur les points de terminaison standard et optimisés pour le stockage. Sur les points de terminaison optimisés pour le stockage, vous pouvez également créer un index de recherche en texte intégral dédié sans incorporation. Consultez Créer un index de recherche en texte intégral (bêta).

point de terminaison standard du KIT de développement logiciel (SDK) Python

Pour plus d’informations, consultez la référence 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
    )

Point de terminaison optimisé pour le stockage du SDK Python

Pour plus d’informations, consultez la référence Python SDK.

L’interface de filtre existante a été recréée pour les index de recherche vectorielle optimisés pour le stockage afin d’adopter une chaîne de filtre de type SQL au lieu du dictionnaire de filtres utilisé dans les points de terminaison de recherche vectorielles 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

Consultez la documentation de référence de l’API REST : POST /api/2.0/vector-search/indexes/{index_name}/query.

Pour les applications de production, Databricks recommande d’utiliser des principaux de service plutôt que des jetons d’accès personnels. En plus d’améliorer la sécurité et la gestion des accès, l’utilisation de principaux de service peut améliorer les performances d’un maximum de 100 msec par requête.

L’exemple de code suivant montre comment interroger un index à l’aide d’un principal de service.

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

L’exemple de code suivant montre comment interroger un index à l’aide d’un jeton d’accès personnel (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

Important

La fonction d’IA vector_search() est en Préversion publique.

Pour utiliser cette fonction IA, consultez vector_search la fonction.

Numérotation des pages

Lorsqu’une requête demande plus de 1 000 résultats, les résultats sont automatiquement retournés dans les pages allant jusqu’à 1 000. Le nombre maximal de résultats qu’une requête unique peut retourner sur toutes les pages est de 10 000. Les points d'accès standard et optimisés pour le stockage prennent en charge la pagination.

La pagination fonctionne avec tous les types de requêtes.

SDK Python

Le sdk Python gère la pagination de manière transparente. Lorsque vous définissez num_results sur une valeur supérieure à 1 000, le Kit de développement logiciel (SDK) récupère automatiquement toutes les pages et retourne le jeu de résultats complet. Aucun code supplémentaire n’est requis.

# 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

Lorsque vous utilisez directement l’API REST, vous devez gérer la pagination manuellement. Si d’autres résultats sont disponibles, la réponse inclut un next_page_token champ. Pour récupérer la page suivante des résultats, transmettez ce jeton au point de terminaison de la requête de la page suivante.

Consultez la documentation de référence de l’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>"}'

Continuez d'appeler le point de terminaison de la requête de la page suivante avec le next_page_token de chaque réponse jusqu’à ce que le jeton soit vide ou absent, ce qui indique que tous les résultats ont été retournés.

Utiliser des filtres sur des requêtes

Une requête peut définir des filtres en fonction de n’importe quelle colonne de la table Delta. similarity_search retourne uniquement les lignes qui correspondent aux filtres spécifiés.

Le tableau suivant répertorie les filtres pris en charge.

Note

Pour les points de terminaison optimisés pour le stockage, les résultats sont récupérés en excès. Si vous définissez num_results sur k, plus de k résultats sont récupérés, et le filtre est appliqué aux résultats extraits. Il est possible qu’aucun résultat ne soit retourné même s’il existe des résultats dans le jeu de données qui correspondent à la condition de filtre, si le score de ces documents ne figure pas parmi les premiers.

Opérateur de filtre	Comportement	Examples
`NOT`	Standard : annule le filtre. La clé doit se terminer par « NOT ». Par exemple, « color NOT » avec la valeur « rouge » correspond aux documents où la couleur n’est pas rouge. Stockage optimisé : voir l’opérateur `!=` (signe point d’exclamation égal)	Standard : `{"id NOT": 2}{“color NOT”: “red”}` Optimisé pour le stockage : `"id != 2" "color != 'red'"`
`<`	Standard : vérifie si la valeur du champ est inférieure à la valeur du filtre. La clé doit se terminer par « <». Par exemple, « price <» avec la valeur 200 correspond aux documents où le prix est inférieur à 200. Stockage optimisé : voir l’opérateur `<` (signe inférieur).	Standard : `{"id <": 200}` Optimisé pour le stockage : `"id < 200"`
`<=`	Standard : vérifie si la valeur du champ est inférieure ou égale à la valeur de filtre. La clé doit se terminer par « <= ». Par exemple, « price <= » avec la valeur 200 correspond aux documents où le prix est inférieur ou égal à 200. Stockage optimisé : voir l’opérateur `<=` (signe inférieur ou égal).	Standard : `{"id <=": 200}` Optimisé pour le stockage : `"id <= 200"`
`>`	Standard : vérifie si la valeur du champ est supérieure à la valeur du filtre. La clé doit se terminer par « >». Par exemple, « prix >» avec la valeur 200 correspond aux documents où le prix est supérieur à 200. Stockage optimisé : voir l’opérateur `>` (signe supérieur).	Standard : `{"id >": 200}` Optimisé pour le stockage : `"id > 200"`
`>=`	Standard : vérifie si la valeur du champ est supérieure ou égale à la valeur de filtre. La clé doit se terminer par « >= ». Par exemple, « price >= » avec la valeur 200 correspond aux documents où le prix est supérieur ou égal à 200. Stockage optimisé : voir l’opérateur `>=` (signe supérieur ou égal).	Standard : `{"id >=": 200}` Optimisé pour le stockage : `"id >= 200"`
`OR`	Standard : vérifie si la valeur du champ correspond à l’une des valeurs de filtre. La clé doit contenir `OR` pour séparer plusieurs sous-clés. Par exemple, `color1 OR color2` avec la valeur `["red", "blue"]` correspond aux documents dans lesquels soit `color1` est `red`, soit `color2` est `blue`. Stockage optimisé : voir l’opérateur `or`.	Standard : `{"color1 OR color2": ["red", "blue"]}` Optimisé pour le stockage : `"color1 = 'red' OR color2 = 'blue'"`
`LIKE`	Standard : correspond aux jetons séparés par des espaces blancs dans une chaîne. Stockage optimisé : voir l’opérateur `like`.	Consultez les notes sur l’utilisation de `LIKE`.
Aucun opérateur de filtre spécifié	Standard : Filtre vérifie une correspondance exacte. Si plusieurs valeurs sont spécifiées, elle correspond à l’une des valeurs. Stockage optimisé : voir l’opérateur `=` (signe égal) et predicate `in`.	Standard : `{"id": 200}{"id": [200, 300]}` Optimisé pour le stockage : `"id = 200""id IN (200, 300)"`
`to_timestamp` (points de terminaison optimisés pour le stockage uniquement)	Optimisé pour le stockage : filtration par horodatage. Voir Fonction `to_timestamp`	Optimisé pour le stockage : `"date > TO_TIMESTAMP('1995-01-01')"`

Remarques sur l’utilisation de `LIKE`

LIKE exemples pour les points de terminaison standard

{"column LIKE": "apple"}: correspond aux chaînes « pomme » et « poire de pomme » mais ne correspond pas à « ananas ». Notez qu’il ne correspond pas à « ananas », même s’il contient une sous-chaîne « pomme », il recherche une correspondance exacte sur des jetons séparés par des espaces blancs comme dans « poire de pomme ».

{"column NOT LIKE": "apple"} fait l’inverse. Il correspond à « ananas » et « poire », mais ne correspond pas à « pomme » ou « poire de pomme ».

LIKE exemples de points de terminaison optimisés pour le stockage

Format	Correspondances
`"column LIKE 'apple'"`	Équivalent à l’opérateur `=` . Retourne uniquement les correspondances exactes.
`"column LIKE 'apple%'"`	Retourne des lignes où un préfixe correspond à `apple`, par exemple `applepie`.
`"column LIKE '%apple'"`	Retourne des lignes où un suffixe correspond à `apple`, par exemple `pineapple`.
`"column LIKE '%apple%'"`	Retourne des lignes qui comportent une sous-chaîne correspondant à `apple`, comme `pineapplecake`.

Exemples de code

point de terminaison standard du KIT de développement logiciel (SDK) Python

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

Point de terminaison optimisé pour le stockage du SDK Python

# 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

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

Utiliser le reranker lors de l’exécution d’une requête

Les performances de l’agent dépendent de la récupération des informations les plus pertinentes pour une requête. La reclassement est une technique qui améliore la qualité de récupération en évaluant les documents récupérés pour identifier ceux qui sont sémantiquement les plus pertinents. Databricks a développé un système d’IA composé basé sur la recherche pour identifier ces documents. Vous pouvez également spécifier des colonnes contenant des métadonnées que vous souhaitez utiliser pour un contexte supplémentaire, car elle évalue la pertinence de chaque document.

Le reclassement entraîne un petit retard de latence, mais peut améliorer considérablement la qualité de la récupération et les performances de l’agent. Databricks recommande d’essayer la réévaluation du classement pour tout cas d'utilisation d'un agent RAG.

Les exemples de cette section montrent comment utiliser le reranker de recherche vectorielle. Lorsque vous utilisez le reranker, vous définissez les colonnes à renvoyer (columns) et les colonnes de métadonnées à utiliser pour la reclassement (columns_to_rerank) séparément. num_results est le nombre final de résultats à retourner. Cela n’affecte pas le nombre de résultats utilisés pour la reclassement.

Le message de débogage de la requête inclut des informations sur la durée de l’étape de réorganisation. Par exemple:

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

Si l’appel au reclassificateur échoue, cette information est incluse dans le message de débogage :

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

Note

L’ordre dans lequel les colonnes sont répertoriées columns_to_rerank est important. Le calcul de reclassement prend les colonnes dans l’ordre dans lequel elles sont répertoriées et considère uniquement les 2 000 premiers caractères qu’il trouve.

SDK Python

# 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

Pour vous assurer que vous obtenez des informations de latence, définissez debug_level sur au moins 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}'

Rechercher des points

Pour effectuer une recherche de point, utilisez un filtre sur n’importe quelle colonne de clé primaire.

Algorithmes de récupération

Cette section décrit les différents algorithmes de récupération ou types de requêtes et quand chacun d’eux peut être utilisé. Utilisez le query_type paramètre pour spécifier l’algorithme de récupération à utiliser. Pour comparer automatiquement les performances de différents algorithmes pour votre index, consultez Évaluer la qualité de récupération de recherche vectorielle.

Stratégie	Fonctionnement	Idéal pour
ANN (voisin le plus proche approximatif)	Effectue des recherches à l’aide d’incorporations vectorielles pour rechercher des documents sémantiquement similaires.	Requêtes conceptuelles et sémantiques où la signification importe plus que la formulation exacte.
Full-text	Recherche de mots clés qui correspond à des termes exacts.	Requêtes avec des termes spécifiques, des noms appropriés, des ID de produit ou un jargon technique.
Hybride	Combine les résultats de l’ANN et du texte intégral en utilisant la fusion de rangs réciproques (RRF).	Récupération d’informations à usage général. Point de départ recommandé pour la plupart des cas d’usage.
Hybride + reranker	Exécute la recherche hybride, puis réévalue les résultats avec un modèle de reclassement d'encodeur croisé.	Précision plus élevée lorsque la latence autorise (~1,5s supplémentaire par requête).

ANN (recherche vectorielle)

La recherche ANN convertit une requête en un vecteur incorporé et recherche des documents dont les incorporations sont les plus similaires. Cela est efficace pour comprendre la signification. Par exemple, une requête telle que « comment corriger un canal cassé » correspond aux documents sur la plomberie même s’ils ne contiennent pas ces mots exacts.

Lorsque ANN fonctionne correctement : les requêtes sont conceptuelles, conversationnelles ou utilisent un vocabulaire différent des documents.
Quand ANN peut sous-performer : les requêtes s'appuient sur des mots-clés précis, des noms propres ou une terminologie spécifique au domaine que les embeddings peuvent ne pas capturer précisément.

Texte intégral (recherche de mots clés)

La recherche en texte intégral correspond aux documents contenant les termes de la requête. La recherche en texte intégral a une haute précision. Lorsque les utilisateurs recherchent des noms, des codes ou des termes techniques spécifiques, la correspondance de mots clés trouve des correspondances exactes que la recherche vectorielle peut manquer.

Lorsque le texte intégral fonctionne correctement : les requêtes contiennent des identificateurs spécifiques, des noms de produits, des codes d’erreur ou une terminologie spécifique au domaine.
Lorsque le texte intégral pourrait être moins performant : les requêtes sont formulées différemment des documents ou utilisent des synonymes et des paraphrases.

Recherche hybride

La recherche hybride exécute les recherches ANN et plein texte en parallèle, puis fusionne les résultats à l’aide du Reciprocal Rank Fusion (RRF). Cela combine la compréhension sémantique de la recherche vectorielle avec la précision de la correspondance de mots clés.

Lorsque la recherche hybride s’effectue correctement : la charge de travail de requête est un mélange de requêtes conceptuelles et lourdes de mots clés. Hybride est la stratégie à usage général la plus robuste.

Reranker

Le reranker est une deuxième passe facultative appliquée par-dessus n’importe quelle stratégie. Après la récupération initiale, un modèle d’encodeur croisé réévalue chaque résultat dans le contexte de la requête, produisant un ordre de pertinence plus précis.

Le reclassement améliore généralement la qualité d’environ 10%, mais ajoute une latence. Il convient aux applications où la qualité importe le plus, comme les chatbots RAG, mais potentiellement moins adaptées aux applications de recherche à débit élevé et à faible latence.

Commentaires

Cette page a-t-elle été utile ?

Last updated on 2026-04-19

Interroger un index de recherche vectorielle

Installation

Comment interroger un index de recherche vectorielle

point de terminaison standard du KIT de développement logiciel (SDK) Python

Point de terminaison optimisé pour le stockage du SDK Python

REST API

SQL

Numérotation des pages

SDK Python

REST API

Utiliser des filtres sur des requêtes

Remarques sur l’utilisation de LIKE

Exemples de code

point de terminaison standard du KIT de développement logiciel (SDK) Python

Point de terminaison optimisé pour le stockage du SDK Python

REST API

Utiliser le reranker lors de l’exécution d’une requête

SDK Python

REST API

Rechercher des points

Algorithmes de récupération

ANN (recherche vectorielle)

Texte intégral (recherche de mots clés)

Recherche hybride

Reranker

Commentaires

Ressources supplémentaires

Remarques sur l’utilisation de `LIKE`