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

Ajoutez des index de recherche IA en tant que ressources Databricks Apps pour activer la recherche sémantique et la récupération basée sur la similarité dans vos applications. Les index de recherche IA stockent et interrogent des incorporations de vecteurs haute dimension, alimentant les cas d’usage 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 anciennement connu sous le nom de Recherche vectorielle Databricks.

Exigences relatives aux privilèges

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

Pour que cet octroi automatique réussisse, l’un des éléments suivants doit être vrai pour chaque privilège :

  • Pour USE CATALOG: tous les utilisateurs de compte ont le USE CATALOG privilège sur le catalogue ou vous disposez du MANAGE privilège sur le catalogue.
  • Pour USE SCHEMA: tous les utilisateurs de compte ont le USE SCHEMA privilège sur le schéma ou vous disposez du MANAGE privilège sur le schéma.
  • Pour SELECT: tous les utilisateurs de compte ont le SELECT privilège sur l’index ou vous disposez du MANAGE privilège sur l’index.

Si l’index utilise un modèle d’incorporation managé par Databricks sur un point de terminaison à débit provisionné ou de mise à disposition personnalisé ajoutez également ce point de terminaison comme ressource d’application avec l’autorisation Peut interroger, ainsi que tout point de terminaison distinct d’incorporation des requêtes (model_endpoint_name_for_query). get_index() lit ces points de terminaison et échoue sans les droits d’accès nécessaires. Les points de terminaison des API Foundation Model facturés au jeton, tels que databricks-gte-large-en, ne nécessitent pas de ressource d’application, sauf si votre compte restreint l’accès aux modèles de fondation à l’aide des autorisations Unity Catalog, auquel cas le principal de service doit disposer du privilège EXECUTE sur le modèle. Voir Configurer un principal de service.

Pour plus d’informations sur l’interrogation d’index de recherche IA avec ces autorisations, consultez Comment interroger un index de recherche IA.

Consultez les informations de référence sur les privilèges du catalogue Unity.

Ajouter une ressource d’index de recherche IA

Avant d’ajouter un index AI Search en tant que ressource, passez en revue les prérequis de la ressource d’application.

  1. Dans la section Ressources de l’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 vectoriel.
  2. Choisissez un index de recherche IA dans les index disponibles dans votre espace de travail. L’index doit déjà exister dans le catalogue Unity.
  3. Sélectionnez le niveau d’autorisation de votre application :
    • Peut sélectionner : Octroie à l’application l’autorisation d’interroger l’index de recherche IA pour rechercher des recherches de similarité. Correspond au SELECT privilège.
  4. (Facultatif) Spécifiez une clé de ressource personnalisée, c’est-à-dire la façon dont vous référencez l’index dans la configuration de votre application. La clé par défaut est vector-search-index.

Note

Les index de recherche IA sont des tables catalogue Unity avec 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 AI Search, Azure Databricks expose le nom complet de trois niveaux par le biais de variables d’environnement que vous pouvez référencer à l’aide du valueFrom champ.

Exemple de configuration :

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 databricks-ai-search SDK Python et les identifiants du principal de service de l'application. Lorsque l’espace de travail satisfait aux exigences relatives à l’URL de l’index, le SDK envoie les requêtes à cette URL, qui peut exploiter la capacité supplémentaire d’un point de terminaison doté d’un objectif de requêtes par seconde (QPS). Les requêtes envoyées avec WorkspaceClient().vector_search_indexes.query_index utilisent l’URL de requête workspace, qui est limitée à quelques dizaines de QPS. Les requêtes envoyées avec le jeton de l’utilisateur issu de l’autorisation utilisateur utilisent également l’URL de requête de l’espace de travail, donc envoyez le trafic de recherche via le principal de service de l’application.

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

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 débit plus élevé, définissez un QPS cible sur un endpoint standard. La capacité supplémentaire s’applique uniquement après que le point de terminaison scaling_info.state est SCALING_CHANGE_APPLIED. Atteindre cet état peut prendre des minutes à des heures, donc attendez avant de faire le test de chargement. Pour suivre le changement et son temps d’achèvement estimé, voir Suivre la progression de la mise à l’échelle.

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

Supprimer une ressource d’index de recherche IA

Lorsque vous supprimez une ressource d’index de recherche IA d’une application, le principal de service de l’application perd l’accès à l’index. L’index lui-même reste inchangé et continue d’être disponible pour d’autres utilisateurs et applications disposant d’autorisations appropriées.

Meilleures pratiques

Tenez compte des éléments suivants lorsque vous travaillez avec les ressources d’indexation de Recherche IA :

  • Vérifiez que le principal de service de l’application a accès aux sources de données sous-jacentes si l’index fait référence à d’autres tables.
  • Surveillez les performances des requêtes et ajustez la configuration d’index ou incorporez des modèles si les temps de réponse se dégradent.
  • Envisagez les planifications d’actualisation d’index pour que les incorporations restent synchronisées avec les données sources.
  • Utilisez les métriques de similarité appropriées (cosinus, euclide, produit par points) en fonction de votre modèle d’incorporation.
  • Un point de terminaison peut être en ligne avant que ses index ne soient prêts à être interrogés. Pour vérifier un index sans bloquer, lire ready et detailed_state dans le champ status que index.describe() renvoie. Pour attendre un index, appelez index.wait_until_ready(), qui sonde toutes les 30 secondes et génère une erreur si l’index est hors ligne ou si le délai d’attente s’écoule.