Aller au contenu principal
Dernière mise à jour le

Interroger un index de recherche IA

Vous pouvez query un index AI Search avec le SDK Python, l'API REST ou la fonction SQL vector_search(). AI Search prend en charge les types de query ANN, hybrides et en texte intégral, ainsi que la pagination, les filtres et le reranking pour affiner la qualité de la récupération.

Pour des Notebooks d'exemple illustrant comment créer et query des endpoints et des index de recherche IA, consultez les Notebooks d'exemple de recherche IA. Pour des informations de référence, consultez la référence du SDK Python.

Databricks AI Search était auparavant connu sous le nom de Databricks Vector Search.

Installation​

Pour utiliser le SDK AI Search, vous devez l'installer dans votre notebook. Utilisez le code suivant pour installer le package :

%pip install databricks-ai-search
dbutils.library.restartPython()

Utilisez ensuite la commande suivante pour importer AISearchClient:

from databricks.ai_search.client import AISearchClient

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

Comment interroger un index de recherche IA​

Vous ne pouvez interroger l'index de recherche IA qu'en utilisant le SDK Python, l'API REST ou la fonction IA SQL vector_search().

remarque

Si l'utilisateur query l'index n'est pas le propriétaire de l'index AI Search, il doit disposer des privilèges UC suivants :

  • USE CATALOG sur le catalogue qui contient l'index de recherche IA.
  • USE SCHEMA sur le schéma qui contient l’index de recherche AI.
  • SÉLECTIONNER sur l’index AI Search.

Le type de query par default est ann (voisin le plus proche approximatif). Pour plus de détails sur les différents algorithmes de récupération, consultez Algorithmes de récupération.

  • Pour effectuer une recherche hybride par mots-clés et similarité, définissez le parameter query_type sur hybrid. Par default, la recherche hybride inclut toutes les colonnes de métadonnées textuelles et renvoie un maximum de 200 résultats.
  • « Pour utiliser le réorganisateur dans une query, consultez Utiliser le réorganisateur dans une query. »
info

Bêta

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 parameter query_type sur FULL_TEXT. Grâce à la recherche en texte intégral, vous pouvez récupérer jusqu'à 200 résultats basés sur la correspondance par mots-clés sans utiliser d'intégrations vectorielles. Les query en texte intégral sont prises en charge sur les Endpoint standard et optimisés pour le stockage. Sur les endpoints optimisés pour le stockage, vous pouvez également créer un index de recherche en texte intégral dédié sans intégrations. Consultez Créer un index de recherche en texte intégral (Bêta). Pour rechercher des colonnes de texte sélectionnées, trier les résultats ou renvoyer des totaux agrégés pour les query en texte intégral et hybrides, voir Rechercher des colonnes de texte sélectionnées, trier les résultats et renvoyer des agrégations (Bêta).

Pour plus de détails, consultez la référence du SDK Python.

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
    )

Pagination​

Lorsqu'une query demande plus de 1 000 résultats, ceux-ci sont automatiquement renvoyés par pages de 1 000 au maximum. Le nombre maximal de résultats qu'une seule query peut renvoyer sur toutes les pages est de 10 000. Les Endpoint standard et optimisés pour le stockage prennent en charge la pagination.

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

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 SDK récupère automatiquement toutes les pages et renvoie le jeu de résultats complet. Aucun code supplémentaire n'est requis.

Python
# The SDK automatically paginates and returns all 5000 results
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=5000
)

Utiliser des filtres sur les query​

Une query peut définir des filtres basés sur n'importe quelle colonne de la table Delta. similarity_search renvoie uniquement les lignes qui correspondent aux filtres spécifiés.

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

remarque

Pour les Endpoint optimisés pour le stockage, les résultats sont sur-récupérés. Si vous définissez num_results à k, plus de k résultats sont récupérés, et le filtre est appliqué aux résultats récupérés. Il est possible qu'aucun résultat ne soit renvoyé même s'il existe des résultats dans le dataset qui correspondent à la condition de filtre, si le score de ces documents ne fait pas partie des meilleurs.

Opérateur de filtre

Comportement

Exemples

NOT

Standard : annule le filtre. La clé doit se terminer par « NOT ». Par exemple, « color NOT » avec la valeur « red » correspond aux documents dont la couleur n'est pas rouge.

Optimisé pour le stockage : consultez != (signe bangeq) opérateur.

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.

Optimisé pour le stockage : 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 du filtre. La clé doit se terminer par <=. Par exemple, price <= avec la valeur 200 correspond aux documents dont le prix est inférieur ou égal à 200.

Stockage optimisé : consultez l'<= (opérateur 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, price \> avec la valeur 200 correspond aux documents où le prix est supérieur à 200.

**Stockage optimisé** : Voir > opérateur >.

Standard : {"id >": 200}

Optimisé pour le stockage : "id > 200"

>=

Standard : Vérifie si la valeur du champ est supérieure ou égale à la valeur du 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 >= (signe supérieur ou égal) opérateur.

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 où color1 est red ou color2 est blue.

Optimisé pour le stockage : Consultez l'or opérateur.

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 dans une chaîne.

Optimisé pour le stockage : Consultez l'like opérateur.

Consultez les Notes sur l'utilisation de LIKE.

Aucun opérateur de filtre spécifié

Standard : Le filtre vérifie la correspondance exacte. Si plusieurs valeurs sont spécifiées, elle correspond à l'une des valeurs.

Stockage optimisé : voir = (signe égal) opérateur et in prédicat.

Standard : {"id": 200} {"id": [200, 300]}

Optimisé pour le stockage : "id = 200" "id IN (200, 300)"

to_timestamp (Endpoint optimisés pour le stockage uniquement)

Optimisé pour le stockage : Filtrez sur un timestamp. Consulter la fonctionto_timestamp

Optimisé pour le stockage : "date > TO_TIMESTAMP('1995-01-01')"

Opérateur de filtre

Comportement

Exemples

NOT

Standard : annule le filtre. La clé doit se terminer par « NOT ». Par exemple, « color NOT » avec la valeur « red » correspond aux documents dont la couleur n'est pas rouge.

Optimisé pour le stockage : consultez != (signe bangeq) opérateur.

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.

Optimisé pour le stockage : 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 du filtre. La clé doit se terminer par <=. Par exemple, price <= avec la valeur 200 correspond aux documents dont le prix est inférieur ou égal à 200.

Stockage optimisé : consultez l'<= (opérateur 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, price \> avec la valeur 200 correspond aux documents où le prix est supérieur à 200.

**Stockage optimisé** : Voir > opérateur >.

Standard : {"id >": 200}

Optimisé pour le stockage : "id > 200"

>=

Standard : Vérifie si la valeur du champ est supérieure ou égale à la valeur du 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 >= (signe supérieur ou égal) opérateur.

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 où color1 est red ou color2 est blue.

Optimisé pour le stockage : Consultez l'or opérateur.

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 dans une chaîne.

Optimisé pour le stockage : Consultez l'like opérateur.

Consultez les Notes sur l'utilisation de LIKE.

Aucun opérateur de filtre spécifié

Standard : Le filtre vérifie la correspondance exacte. Si plusieurs valeurs sont spécifiées, elle correspond à l'une des valeurs.

Stockage optimisé : voir = (signe égal) opérateur et in prédicat.

Standard : {"id": 200} {"id": [200, 300]}

Optimisé pour le stockage : "id = 200" "id IN (200, 300)"

to_timestamp (Endpoint optimisés pour le stockage uniquement)

Optimisé pour le stockage : Filtrez sur un timestamp. Consulter la fonctionto_timestamp

Optimisé pour le stockage : "date > TO_TIMESTAMP('1995-01-01')"

Notes sur l'utilisation de LIKE​

LIKE exemples pour les Endpoint standard

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

{"column NOT LIKE": "apple"} fait le contraire. Il correspond à « pineapple » et « pear », mais ne correspond pas à « apple » ou « apple pear ».

LIKE exemples d'Endpoint optimisés pour le stockage

Format

Correspondances

"column LIKE 'apple'"

Équivalent à l'opérateur =. Renvoie uniquement les correspondances exactes.

"column LIKE 'apple%'"

Renvoie les lignes où un préfixe correspond à apple, tel que applepie.

"column LIKE '%apple'"

Renvoie les lignes dont le suffixe correspond à apple, comme pineapple.

"column LIKE '%apple%'"

Renvoie les lignes qui contiennent une sous-chaîne qui correspond à apple, telle que pineapplecake.

Format

Correspondances

"column LIKE 'apple'"

Équivalent à l'opérateur =. Renvoie uniquement les correspondances exactes.

"column LIKE 'apple%'"

Renvoie les lignes où un préfixe correspond à apple, tel que applepie.

"column LIKE '%apple'"

Renvoie les lignes dont le suffixe correspond à apple, comme pineapple.

"column LIKE '%apple%'"

Renvoie les lignes qui contiennent une sous-chaîne qui correspond à apple, telle que pineapplecake.

Exemples de code​

Python
# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={&quot;title&quot;: [&quot;Ares&quot;, &quot;Athena&quot;]},
    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={&quot;title OR id&quot;: [&quot;Ares&quot;, &quot;Athena&quot;]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={&quot;title NOT&quot;: &quot;Hercules&quot;},
    num_results=2
    )

Rechercher les colonnes de texte sélectionnées, trier les résultats et renvoyer les agrégations (Bêta)​

info

Bêta

Les options de recherche de colonnes de texte sélectionnées, de tri et de retour d'agrégations font partie de la version bêta **Vector Search : Recherche plein texte**. Pour utiliser,,query_columns sort_columns facetsou, activez l'aperçu public **Vector Search : Recherche plein texte**. Contactez votre équipe de compte ou consultez Gérer les aperçus Databricks pour activer les aperçus.

Utilisez ces options pour rechercher des champs de texte sélectionnés, appliquer un ordre de résultats explicite ou renvoyer des agrégations pour les résultats correspondants.

Ces options sont prises en charge pour les requêtes en texte intégral et hybrides. Elles ne sont pas prises en charge pour les requêtes ANN.

Rechercher les colonnes de texte sélectionnées

Utilisez query_columns pour rechercher uniquement les colonnes de texte spécifiées. Si vous l'omettez, la requête recherche toutes les colonnes de texte.

Python
query_columns=["title", "text"]

Trier les résultats

Utilisez sort_columns pour classer les résultats par valeurs de colonne au lieu de l'ordre de pertinence par default. Les entrées utilisent le format "<column> ASC" ou "<column> DESC".

Python
sort_columns=["rating DESC", "publication_year DESC"]

Retournez les agrégations

Utilisez facets pour renvoyer les comptes agrégés pour les résultats correspondants.

Les facettes de valeur comptent les résultats correspondants par valeurs distinctes dans une colonne, telle que la langue ou la catégorie. TOP limite le nombre de valeurs renvoyées et est défini par default sur 10 s'il est omis.

Python
facets=["language TOP 5"]

Exemple de réponse :

JSON
{
  "facet_result": {
    "facet_array": [
      ["language", "en", 28],
      ["language", "el", 14]
    ]
  }
}

Les buckets numériques comptent les résultats correspondants qui se situent dans des plages numériques spécifiées, telles que les années de publication ou les prix. Les limites du bucket sont inclusives.

Python
facets=["publication_year BUCKETS [[1900,1949],[1950,1999],[2000,2025]]"]

Exemple de réponse :

JSON
{
  "facet_result": {
    "facet_array": [
      ["publication_year", "[1900,1949]", 8],
      ["publication_year", "[1950,1999]", 14],
      ["publication_year", "[2000,2025]", 20]
    ]
  }
}

Pour les requêtes en texte intégral, la Recherche IA calcule des agrégations sur tous les résultats qui correspondent à la requête et aux filtres, et pas seulement les lignes renvoyées dans la réponse. Pour les requêtes hybrides, AI Search applique le tri et les agrégations à l'ensemble de candidats borné que la recherche hybride produit, et non à chaque ligne de l'index.

Pour les champs de requête et le schéma de réponse de l'API REST, consultez POST /api/2.0/vector-search/indexes/{index_name}/query.

Utilisez le réorganisateur dans une query​

Les performances de l'agent dépendent de la récupération des informations les plus pertinentes pour une query. Le réordonnancement est une technique qui améliore la qualité de la 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 les colonnes contenant des métadonnées que vous souhaitez que le réordonnanceur utilise pour un contexte supplémentaire lorsqu'il évalue la pertinence de chaque document.

Le reranking entraîne un léger délai de latence, mais peut améliorer considérablement la qualité de récupération et les performances de l'agent. Databricks recommande d'essayer le reclassement pour tout cas d'utilisation d'agent RAG.

Le réordonnanceur de recherche IA est un service désigné Databricks qui utilise Databricks Geos pour gérer la résidence des données. Les clients en dehors des États-Unis et de l'UE pourraient avoir besoin d' activer le traitement inter-géographique pour utiliser le réordonnanceur.

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

Le message de débogage de la query comprend des informations sur le temps qu'a pris l'étape de reclassement. Par exemple :

Bash
'debug_info': {'response_time': 693.0, 'ann_time': 29.0, 'reranker_time': 619.0}

Si l'appel du reranker échoue, cette information est incluse dans le message de débogage :

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

L'ordre dans lequel les colonnes sont listées dans columns_to_rerank est important. Le calcul de reclassement prend les colonnes dans l'ordre où elles sont listées et ne prend en compte que les 2 000 premiers caractères qu'il trouve.

Python
# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-ai-search --force-reinstall
dbutils.library.restartPython()
Python
from databricks.ai_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create an AI 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"])
    )

Recherches de points​

Pour effectuer une recherche ponctuelle, 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 query et quand chacun peut être utilisé. Utilisez le parameter query_type 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 la récupération de la recherche IA.

Stratégie

Comment ça marche

Idéal pour

ANN (plus proche voisin approximatif)

Recherches utilisant des incorporations vectorielles pour trouver des documents sémantiquement similaires.

Requêtes conceptuelles et sémantiques où le sens est plus important que le libellé exact.

Texte intégral

Recherche par mots-clés qui correspond à des termes exacts.

Requêtes avec des termes spécifiques, des noms propres, des ID de produits ou du jargon technique.

Hybride

Combine les résultats ANN et textuels complets à l'aide de la fusion de rang réciproque (RRF).

Récupération à usage général. Le point de départ recommandé pour la plupart des cas d'usage.

Hybride + réorganisateur

Exécute une recherche hybride, puis reclasse les résultats avec un modèle de reclassement cross-encoder.

Précision supérieure lorsque la latence le permet (généralement moins d'une seconde supplémentaire par query).

Stratégie

Comment ça marche

Idéal pour

ANN (plus proche voisin approximatif)

Recherches utilisant des incorporations vectorielles pour trouver des documents sémantiquement similaires.

Requêtes conceptuelles et sémantiques où le sens est plus important que le libellé exact.

Texte intégral

Recherche par mots-clés qui correspond à des termes exacts.

Requêtes avec des termes spécifiques, des noms propres, des ID de produits ou du jargon technique.

Hybride

Combine les résultats ANN et textuels complets à l'aide de la fusion de rang réciproque (RRF).

Récupération à usage général. Le point de départ recommandé pour la plupart des cas d'usage.

Hybride + réorganisateur

Exécute une recherche hybride, puis reclasse les résultats avec un modèle de reclassement cross-encoder.

Précision supérieure lorsque la latence le permet (généralement moins d'une seconde supplémentaire par query).

La recherche ANN convertit une query en une incorporation vectorielle et trouve les documents dont les incorporations sont les plus similaires. Ceci est efficace pour comprendre le sens . Par exemple, une query telle que « comment réparer un tuyau cassé » correspond à des documents sur la plomberie même s’ils ne contiennent pas ces mots exacts.

  • Quand l'ANN est performant : Les requêtes sont conceptuelles, conversationnelles ou utilisent un vocabulaire différent de celui des documents.
  • Quand l'ANN peut être sous-performante : les query reposent sur des mots-clés exacts, des noms propres ou une terminologie spécifique au domaine que les intégrations peuvent ne pas saisir précisément.

Recherche plein texte (recherche par mot-clé)​

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

Utilisez les options de requête en texte intégral ou hybrides pour rechercher des colonnes de texte sélectionnées, trier les résultats ou renvoyer des totaux agrégés. Voir Rechercher les colonnes de texte sélectionnées, trier les résultats et renvoyer les agrégations (Bêta).

  • Quand la recherche en texte intégral est performante : les queries contiennent des identifiants spécifiques, des noms de produits, des codes d'erreur ou une terminologie spécifique au domaine.
  • Quand la recherche en texte intégral peut être moins performante : les query sont formulées différemment des documents ou utilisent des synonymes et des paraphrases.

Recherche hybride​

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

  • Quand la recherche hybride est performante : La charge de travail des requêtes est un mélange de requêtes conceptuelles et de requêtes à forte densité de mots-clés. L'hybride est la stratégie la plus robuste à usage général.

Réorganisateur​

Le réorganisateur est une deuxième passe facultative appliquée en plus de toute 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 query, ce qui produit un ordre de pertinence plus précis.

Le réorganisateur améliore généralement la qualité d'environ 10 %, mais il ajoute de la latence. Il est adapté aux applications où la qualité est primordiale, telles que les chatbots RAG, mais potentiellement moins adapté aux applications de recherche à throughput élevé et à faible latence.

Sur cette page