Aller au contenu principal
Dernière mise à jour le

Créer des Endpoint et des index de recherche IA

Les index de recherche IA fournissent une recherche de similarité en temps réel sur une table Delta, et les Endpoint de recherche IA servent ces index pour les requêtes. Cet article décrit comment créer les deux. Pour une introduction à la recherche IA, consultez Databricks AI Search.

Vous pouvez créer et gérer des composants AI Search, tels qu'un endpoint AI Search et des index AI Search, à l'aide de l'interface utilisateur, du SDK Python ou de l'API REST.

Pour des exemples de notebooks illustrant comment créer et interroger des Endpoint de recherche IA, voir exemples de notebooks 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.

Exigences​

La permission de créer et de gérer les endpoints de Recherche IA est configurée à l'aide de listes de contrôle d'accès. Consultez les ACL des Endpoint de Recherche IA.

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.

Créer un endpoint de recherche IA​

Vous pouvez créer un endpoint AI Search à l'aide de l'interface utilisateur Databricks, du SDK Python ou de l'API.

Créer un endpoint de recherche IA à l'aide de l'interface utilisateur​

Suivez ces étapes pour créer un Endpoint de recherche IA à l'aide de l'interface utilisateur.

  1. Dans la barre latérale gauche, cliquez sur Compute .

  2. Cliquez sur l'onglet Recherche IA et cliquez sur Créer un Endpoint .

    Créer un compute de Recherche IA.

  3. Le formulaire Créer un Endpoint s'ouvre. Saisissez un nom pour ce Endpoint.

    Boîte de dialogue : Créer un endpoint de recherche IA.

  4. Dans le champ Type , sélectionnez Standard ou Stockage optimisé . Voir les options d'Endpoint.

  5. (Facultatif) Sous Paramètres avancés , sélectionnez une politique d'utilisation. Consultez les politiques d'utilisation d'AI Search.

  6. Cliquez sur Confirmer .

Créer un Endpoint de recherche IA à l’aide du Python SDK​

L'exemple suivant utilise la fonction SDK create_endpoint() pour créer un endpoint de recherche IA.

Python
# The following line automatically generates a PAT Token for authentication
client = AISearchClient()

# The following line uses the service principal token for authentication
# client = AISearchClient(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD" # or "STORAGE_OPTIMIZED"
)

Créez un endpoint de recherche IA à l'aide de l'API REST​

Consultez la documentation de référence de l’API REST : POST /api/2.0/vector-search/endpoints.

Créer un Endpoint de recherche vectorielle à l'aide de Bundles d'automatisation déclarative​

Vous pouvez définir un endpoint de recherche vectorielle comme une ressource dans les Declarative Automation Bundles pour le gérer en tant que code, aux côtés de vos jobs, pipelines et autres assets du workspace. Pour un aperçu des bundles, consultez Que sont les Declarative Automation Bundles ?.

remarque

La définition d’endpoints de recherche vectorielle dans un bundle n’est prise en charge qu’avec le moteur de déploiement direct et nécessite la version 1.1.0 de Databricks CLI ou version ultérieure.

L'exemple suivant définit un Endpoint de recherche vectorielle standard :

YAML
resources:
  vector_search_endpoints:
    my_vector_search_endpoint:
      name: my_vector_search_endpoint
      endpoint_type: STANDARD

Pour la liste complète des champs pris en charge, y compris endpoint_type, budget_policy_id, min_qps, et permissions, consultez endpoint de recherche vectorielle.

Créer un endpoint avec un QPS cible pour les charges de travail à haut throughput​

Pour les charges de travail à throughput élevé, vous pouvez créer un endpoint avec un QPS cible. Cette fonctionnalité est disponible uniquement pour les endpoints standard.

Pour définir un QPS cible, utilisez le parameter target_qps. Consultez Monter en charge le throughput de l'Endpoint avec un QPS élevé.

important

La définition de target_qps provisionne une capacité supplémentaire, ce qui augmente le coût de l'Endpoint. Vous êtes facturé pour cette capacité supplémentaire, indépendamment du trafic réel de query. La mise à l'échelle du throughput est un effort optimal et n'est pas garantie.

Python
client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD",
    target_qps=500,  # target QPS for high-throughput workloads
)

Pour modifier le QPS cible sur un Endpoint existant, utilisez update_endpoint().

Python
from databricks.ai_search.client import AISearchClient

client = AISearchClient()

# Set or update target QPS
response = client.update_endpoint(name="vector_search_endpoint_name", target_qps=500)

# Check scaling status
scaling_info = response.get("endpoint", {}).get("scaling_info", {})
print(f"State: {scaling_info.get('state')}")  # SCALING_CHANGE_IN_PROGRESS or SCALING_CHANGE_APPLIED

Après avoir mis à jour le QPS cible, synchronisez vos index pour appliquer la nouvelle configuration.

(Facultatif) Créer et configurer un endpoint pour le déploiement du modèle d'intégration​

Si vous choisissez que Databricks compute les intégrations, vous pouvez utiliser un Endpoint des APIs de modèles de fondation préconfiguré ou créer un Endpoint de diffusion de modèle pour diffuser le modèle d'intégration de votre choix. Consultez les API de modèles de fondation basées sur le paiement par jeton ou Créez des endpoints de diffusion de modèles de fondation pour obtenir des instructions. Pour des exemples de notebooks, consultez les exemples de notebooks de recherche IA.

Lorsque vous configurez un endpoint d'embedding, Databricks vous recommande de supprimer la sélection par default de Dimensionner à zéro . Les Endpoints de service peuvent prendre quelques minutes pour démarrer, et la query initiale sur un index avec un Endpoint sous-dimensionné pourrait expirer.

remarque

L’initialisation de l’index AI Search peut expirer si l’endpoint d’intégration n’est pas configuré de manière appropriée pour le dataset. Vous ne devez utiliser les Endpoint CPU que pour les petits dataset et les tests. Pour les datasets plus volumineux, utilisez un endpoint GPU pour des performances optimales.

Créer un index de recherche IA​

Vous pouvez créer un index de recherche IA à l'aide de l'interface utilisateur, du SDK Python ou de l'API REST. L'interface utilisateur est l'approche la plus simple.

Il existe deux types d'index :

  • Index de synchronisation Delta se synchronise automatiquement avec une table Delta source, en mettant à jour l'index de manière automatique et incrémentielle à mesure que les données sous-jacentes de la table Delta changent.
  • Direct Vector Access Index prend en charge la lecture et l'écriture directes de vecteurs et de métadonnées. L’utilisateur est responsable de la mise à jour de cette table à l’aide de l’API REST ou du SDK Python. Ce type d'index ne peut pas être créé à l'aide de l'interface utilisateur. Vous devez utiliser l'API REST ou le SDK.

Les index Delta Sync prennent en charge les modes de recherche suivants :

  • Recherche vectorielle (ANN ou hybride) : nécessite des colonnes d'intégration. Prend en charge les Endpoint standard et optimisés pour le stockage. Vous pouvez également utiliser query_type="FULL_TEXT" pour la recherche par mots-clés sur ces index.
  • **Index de recherche en texte intégral dédié** (bêta) : Un index de synchronisation Delta créé sans aucune colonne d'intégration, pour une recherche par mots-clés uniquement. Disponible uniquement sur les Endpoints optimisés pour le stockage utilisant le mode de synchronisation Trigger. Consultez Créer un index de recherche en texte intégral.
remarque

Le nom de colonne _id est réservé. Si votre table source a une colonne nommée _id, renommez-la avant de créer un index de recherche IA.

Créer un index à l'aide de l'interface utilisateur​

  1. Dans la barre latérale gauche, cliquez sur Catalogue pour ouvrir l'interface utilisateur de l'Explorateur de catalogues.

  2. Accédez à la table Delta que vous souhaitez utiliser.

  3. Cliquez sur le bouton Créer en haut à droite et sélectionnez Index de recherche vectorielle dans le menu déroulant.

    bouton de création d&#39;index

  4. Utilisez les sélecteurs dans la boîte de dialogue pour configurer l'index.

    Boîte de dialogue de création d&#39;index

    Structure de l'index​

    Nom : nom à utiliser pour la table en ligne dans Unity Catalog. Le nom nécessite un espace de noms à trois niveaux, <catalog>.<schema>.<name>. Les noms ne peuvent contenir ni espaces, ni points, ni barres obliques, ni caractères de contrôle.

    Type d'index : Sélectionnez Hybride pour prendre en charge la recherche sémantique (vectorielle) et par mots-clés sur le même index. Sélectionnez Plein texte pour une recherche par mots-clés uniquement sans embeddings. Consultez Créer un index de recherche en texte intégral (Bêta) pour connaître les exigences de l'index en texte intégral.

    Clé primaire : colonne à utiliser comme clé primaire.

    Intégrations​

    Source d'intégrations : indiquez si vous souhaitez que Databricks calcule les intégrations pour une colonne de texte dans la table Delta ( Calculer les intégrations ), ou si votre table Delta contient des intégrations précalculées ( Utiliser les intégrations existantes ).

    • Si vous avez sélectionné **Compute embeddings**, sélectionnez la colonne pour laquelle vous souhaitez que les intégrations soient calculées. Un modèle d'intégration géré par Databricks est sélectionné par default. Pour utiliser un modèle différent, développez Paramètres avancés et choisissez dans la liste déroulante Modèle d'intégration . Seules les colonnes de texte sont prises en charge.

      • Pour les applications de production utilisant des Endpoint standard, Databricks recommande d’utiliser le modèle de fondation databricks-qwen3-embedding-0-6b avec un Endpoint de service à throughput provisionné.

      • Pour les applications de production utilisant des endpoints optimisés pour le stockage avec des modèles hébergés par Databricks, utilisez directement le nom du modèle (par exemple, databricks-qwen3-embedding-0-6b) comme endpoint de modèle d'intégration. Les endpoints optimisés pour le stockage utilisent ai_query avec l'inférence par batch au moment de l'ingestion, offrant un throughput élevé pour le job d'embedding. Si vous préférez utiliser un endpoint de throughput provisionné pour les requêtes, spécifiez-le dans le champ model_endpoint_name_for_query lors de la création de l'index.

    • Si vous avez sélectionné Utiliser les intégrations existantes , sélectionnez la colonne qui contient les intégrations précalculées et la dimension d'intégration. Le format de la colonne d’intégration précalculée doit être array[float]. Pour les Endpoint optimisés pour le stockage, la dimension d’intégration doit être uniformément divisible par 16.

    Sauvegarder les embeddings calculés : activez ce paramètre pour enregistrer les embeddings générés dans une table Unity Catalog. Pour plus d'informations, consultez Enregistrer la table d'embeddings générés.

    Ressources de compute​

    Endpoint de recherche vectorielle : sélectionnez l'endpoint de recherche vectorielle pour stocker l'index.

    Mode de synchronisation : le mode continu maintient l'index synchronisé avec quelques secondes de latence. Cependant, cela entraîne un coût plus élevé, car un cluster de compute est provisionné pour exécuter le pipeline de streaming de synchronisation continue.

    • Pour les Endpoint standard, les modes Continuous et Triggered effectuent des mises à jour incrémentielles, de sorte que seules les données qui ont changé depuis la dernière synchronisation sont traitées.
    • Pour les Endpoint optimisés pour le stockage, chaque synchronisation reconstruit partiellement l'index. Pour les index gérés lors des synchronisations ultérieures, toutes les intégrations générées dont la ligne source n’a pas changé sont réutilisées et n’ont pas besoin d’être recalculées. Voir Limitations des Endpoint optimisés pour le stockage.

    En mode de synchronisation **Triggered**, vous utilisez le SDK Python ou l’API REST pour start la synchronisation. Consultez Mettre à jour un index de synchronisation Delta.

    Pour les endpoints optimisés pour le stockage, seul le mode de synchronisation Triggered est pris en charge.

    Paramètres avancés​

    Paramètres avancés

    La section **Paramètres avancés** est réduite par default. La plupart des utilisateurs peuvent accepter les default. Développez-le pour affiner l'un des éléments suivants :

    Modèle d’intégration : remplacer le modèle d’intégration default. Le modèle default hébergé par Databricks fonctionne pour la plupart des Workspaces. Modifiez-le ici si vous en avez besoin d'un autre ou si vous n'avez pas accès à celui par default.

    Colonnes à indexer : sélectionnez les colonnes à inclure dans l’index. Si vous laissez ce champ vide, toutes les colonnes de la table source sont indexées. La clé primaire et les colonnes d'intégration sont toujours incluses. Seules les colonnes indexées peuvent être renvoyées dans les résultats de la recherche ou utilisées comme filtres.

    Politique d'utilisation : appliquez une politique d'utilisation pour étiqueter les coûts de l'index pour le suivi par équipe ou par projet. Consultez les politiques d'utilisation d'AI Search.

    Utiliser un modèle d'intégration distinct pour les requêtes : si vous avez sélectionné Calculer les intégrations , sélectionnez cette option pour spécifier un endpoint de déploiement de modèle d'intégration distinct pour l'interrogation de l'index. Ceci peut être utile si vous avez besoin d'un endpoint de throughput élevé pour l'ingestion, mais d'un endpoint à faible latence pour les requêtes. Le modèle spécifié dans le champ Modèle d'intégration est toujours utilisé pour l'ingestion et est également utilisé pour les requêtes, sauf si vous spécifiez un modèle différent ici.

  5. Lorsque vous avez terminé la configuration de l'index, cliquez sur Créer .

Créer un index à l'aide du SDK Python​

L'exemple suivant crée un index Delta Sync avec des embeddings calculés par Databricks. Pour plus de détails, consultez la référence du SDK Python.

Cet exemple montre également le parameter facultatif model_endpoint_name_for_query, qui spécifie un Endpoint de déploiement de modèle d'intégration distinct à utiliser pour l'interrogation de l'index.

Python
client = AISearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2", # This model is used for ingestion, and is also used for querying unless model_endpoint_name_for_query is specified.
  model_endpoint_name_for_query="e5-mini-v2"   # Optional. If specified, used only for querying the index.
)

L'exemple suivant crée un index Delta Sync avec des intégrations autogérées.

Python
client = AISearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

By default, toutes les colonnes de la table source sont synchronisées avec l'index. Pour sélectionner un sous-ensemble de colonnes à synchroniser, utilisez columns_to_sync. La clé primaire et les colonnes d'intégration sont toujours incluses dans l'index.

Pour synchroniser *uniquement* la clé primaire et la colonne d'intégration, vous devez les spécifier dans columns_to_sync comme indiqué :

Python
index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

Pour synchroniser des colonnes supplémentaires, spécifiez-les comme indiqué. Vous n'avez pas besoin d'inclure la clé primaire et la colonne d'intégration, car elles sont toujours synchronisées.

Python
index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

Créer un index de recherche en texte intégral (Beta)​

info

Bêta

La création d'index de recherche plein texte est disponible dans le cadre de la version bêta de Recherche vectorielle : Recherche plein texte , uniquement sur les Endpoint optimisés pour le stockage. Pour l'utiliser, activez l'aperçu public de la fonction Recherche vectorielle : recherche en texte intégral . Contactez votre équipe de compte ou consultez Gérer les aperçus Databricks pour activer les aperçus.

Un index de recherche en texte intégral permet une recherche par mots-clés sur les colonnes textuelles sans nécessiter de plongements vectoriels. C'est utile lorsque vous souhaitez rechercher des termes exacts, des identifiants ou des mots-clés plutôt que la similarité sémantique.

Pendant la synchronisation, Databricks détecte la langue dominante pour chaque colonne de texte et utilise un analyseur spécifique à la langue. Les langues prises en charge sont l'anglais, le chinois, le japonais, le coréen, l'allemand, le français, l'espagnol, l'italien, le portugais et le russe.

Les index de recherche en texte intégral présentent les exigences suivantes :

  • Vous devez utiliser un endpoint **optimisé pour le stockage**. Les endpoints standards ne sont pas pris en charge.
  • Vous devez utiliser le mode de synchronisation Triggered . La synchronisation continue n'est pas prise en charge.
  • Les paramètres embedding_source_column, embedding_vector_column, et embedding_dimension ne sont pas pris en charge.

L'exemple suivant crée un index de recherche en texte intégral à l'aide du SDK Python.

Python
client = AISearchClient()

index = client.create_delta_sync_index(
  endpoint_name="storage_optimized_endpoint",
  source_table_name="catalog.schema.source_table",
  index_name="catalog.schema.full_text_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  columns_to_sync=["id", "text", "metadata_column"],
  index_subtype="FULL_TEXT"
)

Après avoir créé l'index, Trigger une synchronisation pour le peupler :

Python
index.sync()

Pour interroger l'index de texte intégral, utilisez query_type="FULL_TEXT". Consultez Query an AI Search index pour plus de détails.

Python
results = index.similarity_search(
  query_text="search terms",
  columns=["id", "text"],
  num_results=10,
  query_type="FULL_TEXT"
)

L'exemple suivant crée un index d'accès direct au vecteur.

Python

client = AISearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name=f"{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    &quot;id&quot;: &quot;int&quot;,
    &quot;field2&quot;: &quot;string&quot;,
    &quot;field3&quot;: &quot;float&quot;,
    &quot;text_vector&quot;: &quot;array&lt;float&gt;&quot;}
)

Créer un index à l'aide de l'API REST​

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

Enregistrer la table d'intégrations générée​

Si Databricks génère les intégrations, vous pouvez enregistrer les intégrations générées dans une table Unity Catalog. Cette table est créée dans le même schéma que l'index vectoriel et est liée à partir de la page de l'index vectoriel.

Le nom de la table est le nom de l’index de recherche IA, suivi de _writeback_table. Le nom n’est pas modifiable.

Vous pouvez accéder à la table et la query comme n’importe quelle autre table dans Unity Catalog. Vous ne devriez toutefois pas supprimer ou modifier la table, car elle n'est pas destinée à être mise à jour manuellement. La table est supprimée automatiquement si l'index est supprimé.

Mettre à jour un index de recherche IA​

Mettre à jour un index Delta Sync​

Les index créés avec le mode de synchronisation Continu se mettent à jour automatiquement lorsque la table Delta source change. Si vous utilisez le mode de synchronisation **Triggered**, vous pouvez start la synchronisation à l'aide de l'UI, du SDK Python ou de l'API REST.

  1. Dans Catalog Explorer, accédez à l'index de recherche IA.

  2. Dans la tab Présentation , dans la section Ingestion des données , cliquez sur Synchroniser maintenant.

    Bouton Synchroniser maintenant pour synchroniser un index AI Search depuis Catalog Explorer..

Mettre à jour un index vectoriel d'accès direct​

Vous pouvez utiliser le SDK Python ou l'API REST pour insérer, mettre à jour ou supprimer des données d'un index vectoriel d'accès direct.

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

Python
index.upsert([
    {
        "id": 1,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.0] * 1024
    },
    {
        "id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1] * 1024
    }
])

Comment effectuer des modifications de schéma sans temps d'arrêt​

Les modifications de schéma de la table source ne sont pas prises en charge, à moins que vous ne reconstruisiez l'index. Cela inclut la modification des colonnes existantes et l'ajout de nouvelles colonnes. Le schéma d'index est fixe au moment de la création, de sorte que toute modification du schéma nécessite la création d'un nouvel index pour prendre effet.

Suivez ces étapes pour reconstruire et déployer l'index sans interruption :

  1. Effectuez le changement de schéma sur votre table source.
  2. Créez un nouvel index en utilisant le schéma mis à jour.
  3. Une fois le nouvel index prêt, redirigez le trafic vers le nouvel index.
  4. Supprimer l'index d'origine.
Sur cette page