Partager via

Interroger un index de recherche vectorielle

Cet article explique comment interroger un index de recherche vectorielle, notamment comment utiliser des filtres et reclasser.

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 du Kit de développement logiciel (SDK) Python.

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 Kit de développement logiciel (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 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.

Point de terminaison standard du Kit de développement logiciel (SDK) Python

Pour plus d’informations, consultez la référence du Kit de développement logiciel (SDK) 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
    )

Point de terminaison optimisé pour le stockage du Kit de développement logiciel (SDK) Python

Pour plus d’informations, consultez la référence du Kit de développement logiciel (SDK) Python.

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.

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.

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. Consultez les exemples de code ci-dessous.
Stockage optimisé : voir l’opérateur like.		 Standard : {"column LIKE": "hello"}
Optimisé pour le stockage : "column LIKE 'hello'"
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')"

Consultez les exemples de code suivants :

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 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 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.

LIKE

LIKE Exemples

{"column LIKE": "apple"}: correspond aux chaînes de caractères « pomme » et « pomme poire », mais ne correspond pas à « ananas » ou « poire ». 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 ».

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 de reclasser pour n’importe quel cas d’usage de l’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.

Kit de développement logiciel (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.

  • Last updated on