Aller au contenu principal

Ajouter une ressource d'index de recherche IA à une application Databricks

Ajoutez les index de recherche IA comme Ressources Databricks Apps pour activer la recherche sémantique et la récupération basée sur la similarité dans vos applications. Les index d'AI Search stockent et interrogent les embeddings vectoriels de haute dimension, alimentant des cas d'utilisation tels que la génération augmentée par récupération (RAG), la recherche sémantique et les systèmes de recommandation.

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

Exigences en matière de privilèges​

Pour accéder à un index de recherche AI, le Service Principal de l'application doit avoir le privilège USE CATALOG sur le catalogue parent, le privilège USE SCHEMA sur le schéma parent et le privilège SELECT sur l'index. Lorsque vous ajoutez la ressource d'index, Databricks accorde automatiquement ces privilèges au Service Principal de l'application.

Pour que cet octroi automatique réussisse, l'une des conditions suivantes doit être vraie pour chaque privilège :

  • Pour USE CATALOG: Soit tous les utilisateurs du compte disposent du privilège USE CATALOG sur le catalogue, soit vous disposez du privilège MANAGE sur le catalogue.
  • Pour USE SCHEMA: Soit tous les utilisateurs du compte disposent du privilège USE SCHEMA sur le schéma, soit vous disposez du privilège MANAGE sur le schéma.
  • **Pour SELECT:** Soit tous les utilisateurs SELECT du compte ont le privilège sur l'index, soit vous avez le MANAGE privilège sur l'index.

Si l’index utilise un modèle d’embedding géré par Databricks sur un throughput de provisionnement ou un Endpoint de serving personnalisé, ajoutez également cet Endpoint en tant que Ressource d’application avec l’autorisation Can query , ainsi que tout Endpoint d’embedding de query distinct (model_endpoint_name_for_query). get_index() lit ces Endpoint et échoue sans accès. Les Endpoint des APIs Foundation Model avec paiement par jeton, comme databricks-gte-large-en, ne nécessitent pas de Ressources d’application sauf si votre compte restreint les modèles de fondation avec des autorisations Unity Catalog, auquel cas le Service Principal a besoin de EXECUTE sur le modèle. Voir Configurer un service principal.

Pour plus d'information sur la query des index de recherche IA avec ces permissions, voir Comment interroger un index de recherche IA.

Consultez la référence des privilèges Unity Catalog.

Ajouter une ressource d'index de recherche IA​

Avant d'ajouter un index de recherche AI en tant que ressource, examinez les conditions préalables aux ressources de l'application.

  1. Dans la section Ressources d’application lorsque vous créez une application, ou dans Paramètres > Ressources lorsque vous modifiez une application, cliquez sur + Ajouter une ressource > Index de recherche vectorielle .

  2. Choisissez un index de recherche IA parmi les index disponibles dans votre Workspace. L'index doit déjà exister dans Unity Catalog.

  3. Sélectionnez le niveau d'autorisation de votre application :

    • Peut sélectionner : Accorde à l’application la permission de query l’index de recherche IA pour des recherches de similarité. Correspond au privilège SELECT.
  4. (Facultatif) Spécifiez une clé de ressource personnalisée, qui est la façon dont vous référencez l'index dans la configuration de votre application. La clé default est vector-search-index.

remarque

Les index de recherche IA sont des tables Unity Catalog de type TABLE_ONLINE_VECTOR_INDEX_REPLICA ou TABLE_ONLINE_VECTOR_INDEX_DIRECT. Lorsque vous sélectionnez un index de recherche IA, vous sélectionnez une table spécialement configurée qui prend en charge les opérations de recherche sémantique.

Variables d'environnement​

Lorsque vous déployez une application avec une ressource d'index de recherche IA, Databricks expose le nom complet à trois niveaux via des variables d'environnement que vous pouvez référencer en utilisant le champ valueFrom.

Exemple de configuration :

YAML
env:
- name: VECTOR_SEARCH_INDEX
valueFrom: vector-search-index # Use your custom resource key if different

Utilisation de l'index dans votre application :

Interrogez l'index avec le SDK Python databricks-ai-search et les identifiants de Service Principal de l'application. Lorsque le workspace respecte les conditions requises pour l'URL d'index, le SDK envoie des requêtes à l'URL d'index, qui peut utiliser la capacité supplémentaire d'un endpoint avec un QPS (requêtes par seconde) cible. Les requêtes envoyées avec WorkspaceClient().vector_search_indexes.query_index utilisent l'URL de query du Workspace, qui est limitée à quelques dizaines de QPS. Les requêtes envoyées avec le jeton de l'utilisateur à partir de l'autorisation utilisateur utilisent également l'URL de query du Workspace, envoyez donc le trafic de recherche avec le Service Principal de l'application.

Ajoutez databricks-ai-search version 0.83 ou supérieure aux dépendances de votre application. Consultez Gérer les dépendances pour une application Databricks.

Python
import os
from databricks.ai_search.client import AISearchClient

# DATABRICKS_HOST can be set without a scheme, and the SDK requires one.
host = os.environ["DATABRICKS_HOST"]
if not host.startswith(("https://", "http://")):
host = f"https://{host}"

# Pass the app's service principal credentials so queries use the index URL.
client = AISearchClient(
workspace_url=host,
service_principal_client_id=os.environ["DATABRICKS_CLIENT_ID"],
service_principal_client_secret=os.environ["DATABRICKS_CLIENT_SECRET"],
)

# Create the index object when the app starts and reuse it for every query.
index = client.get_index(index_name=os.environ["VECTOR_SEARCH_INDEX"])

results = index.similarity_search(
query_text="What is machine learning?", # Or pass query_vector for self-managed embeddings.
columns=["id", "text"],
num_results=10,
)

# Each row lists values in the same order as the manifest columns.
column_names = [column["name"] for column in results["manifest"]["columns"]]
for row in results["result"]["data_array"]:
print(dict(zip(column_names, row)))

Remplacez columns par les colonnes de votre index. Pour atteindre un throughput plus élevé, définissez une cible QPS sur un endpoint standard. La capacité supplémentaire ne s'applique qu'une fois que le scaling_info.state de l'endpoint est SCALING_CHANGE_APPLIED. Atteindre cet état peut prendre de quelques minutes à quelques heures, veuillez donc patienter avant d'effectuer un test de charge. Pour suivre la modification et son heure d'achèvement estimée, consultez Suivre la progression de la mise à l'échelle.

Pour plus d'informations, consultez Utiliser les variables d'environnement pour accéder aux ressources.

Lorsque vous supprimez une ressource d'index AI Search d'une application, le service principal de l'application perd l'accès à l'index. L'index lui-même reste inchangé et reste disponible pour les autres utilisateurs et applications qui disposent des autorisations appropriées.

Bonnes pratiques​

Veuillez tenir compte des points suivants lorsque vous travaillez avec les ressources d'index AI Search :

  • Assurez-vous que le Service Principal de l'application a accès aux sources de données sous-jacentes si l'index référence d'autres tables.
  • Surveillez les performances des query et ajustez la configuration de l'index ou les modèles d'intégration si les temps de réponse se dégradent.
  • Envisagez les planifications de refresh d'index pour maintenir les intégrations synchronisées avec les données source.
  • Utilisez des métriques de similarité appropriées (cosinus, euclidienne, produit scalaire) basées sur votre modèle d'intégration.
  • Un Endpoint peut être en ligne avant que ses index soient prêts à être query. Pour vérifier un index sans bloquer, lisez ready et detailed_state dans le champ status que index.describe() retourne. Pour attendre un index, appelez index.wait_until_ready(), qui interroge toutes les 30 secondes et génère une erreur si l’index passe hors ligne ou si le délai d’attente est dépassé.