ai_search Fonction

S’applique à : Databricks SQL Databricks Runtime

La ai_search() fonction récupère des informations d’une ou plusieurs sources de connaissances. Les sources de connaissances peuvent inclure des index de recherche IA ou des tables synchronisées Lakebase avec Lakebase Search activée.

Étant donné une requête en langage naturel et des sources de connaissances configurées pour l’appel, la fonction génère des requêtes de recherche optimisées, récupère et déduplique les résultats entre les sources, les reclasse selon leur pertinence et renvoie les documents les plus pertinents. Par défaut, il synthétise également une réponse ancrée en langage naturel sur les documents récupérés.

À utiliser ai_search pour enrichir des données opérationnelles avec un contexte pertinent à grande échelle, construire des pipelines de génération augmentée par récupération batch (RAG), ou exposer la récupération comme outil à un système d’IA composé — le tout à partir d’un seul appel de fonction SQL.

Sécurité des données

Vos données de document sont traitées dans le périmètre de sécurité Databricks. Databricks ne stocke pas les paramètres qui sont passés dans les appels de fonctions IA, mais conserve les détails de la gestion des métadonnées, comme la version d’exécution de Databricks utilisée.

Exigences

• Databricks Runtime 18.2 ou version ultérieure.
• Une ou plusieurs sources de connaissances à rechercher : index de recherche IA, ou tables synchronisées Lakebase avec Lakebase Search activé.
• Pour utiliser une table synchronisée Lakebase, préparez-la d’abord pour la recherche. Voir configuration de Lakebase.
• Si vous utilisez le calcul serverless, la version de l’environnement serverless doit être réglée à 3 ou plus, car cela permet des fonctionnalités comme VARIANT.
• La ai_search fonction est disponible via les notebooks Databricks, l’éditeur SQL, les flux de travail Databricks, les jobs ou les pipelines déclaratifs Spark sur Lakeflow.

Syntax

ai_search(query, knowledge_sources [, instructions] [, options])

Arguments

• query : Une expression STRING ou VARIANT. La requête de recherche en langage naturel. VARIANT l’entrée, telle que la sortie d’une autre fonction IA, est sérialisée en interne sur une chaîne JSON.
• knowledge_sources: A VARIANT ou STRING une expression contenant un tableau JSON de configurations de sources de connaissances à rechercher. Voir Configuration de la source de connaissances. Vous pouvez spécifier jusqu’à 10 sources de connaissances.
• instructions: Une expression optionnelle STRING pouvant compter jusqu’à 4 000 caractères. Des instructions en langage naturel qui guident la génération de requêtes, la génération de filtres de métadonnées et le reclassement. Par exemple : 'Prefer official documentation over internal articles when both cover the same topic.'
• options: facultatif MAP<STRING, STRING>. Clés prises en charge :
  • 'version': La version fonctionnelle à utiliser.
  • 'generate_answer': 'true' (par défaut) ou 'false'. Lorsque 'true', la fonction synthétise une réponse en langage naturel fondé à partir des documents récupérés et la renvoie sur le answer champ. Réglez sur 'false' le retour des documents uniquement.
  • 'generate_citations': 'true' ou 'false' (par défaut). Lorsque 'true', la fonction renvoie des citations qui montrent quels chunks récupérés le modèle a utilisé pour soutenir sa réponse générée. Cette option doit 'generate_answer' être 'true'.

Configuration de la source de connaissances

L’argument knowledge_sources est un tableau JSON. Chaque élément est une {type, config} enveloppe. Le type champ identifie comment ai_search il se connecte à la source et est distinct du nom de la ressource destinée au client. Réglez type sur vector_search pour un index AI Search, ou lakebase_search pour une table synchronisée Lakebase avec Lakebase Search activé. Le config champ contient la configuration spécifique à la source.

Un seul appel peut se combiner vector_search et lakebase_search sourcer, jusqu’à la limite de 10 sources.

Configuration de l’index de recherche IA

Pour un index IA Search avec type défini à vector_search, config accepte les clés suivantes :

L’exemple suivant configure un index de recherche IA comme source de connaissances :

[
  {
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }
]

Pour construire un index IA Search à partir de documents bruts, utilisez ai_parse_document et ai_prep_search créez des chunks prêts à la recherche dans une table Delta. Ensuite , créez un index de recherche IA à partir de cette table. Une fois l’index en ligne, utilisez son nom à trois niveaux comme index_name.

Configuration de la base du lac

Avant de pouvoir utiliser une table synchronisée Lakebase comme source de connaissances, préparez-la pour la recherche :

1. Activez Lakebase Search et installez les extensions. Suivez Lakebase Search pour activer Lakebase Search dans les paramètres de votre projet, puis connectez-vous à la base de données Postgres du projet et installez l’extension lakebase_vector en exécutant CREATE EXTENSION IF NOT EXISTS lakebase_vector CASCADE;. Il fournit la recherche vectorielle approximative du plus proche voisin qui ai_search utilise. Activer la recherche Lakebase nécessite un accès bêta et est irréversible.
2. Synchronisez votre table Unity Catalog dans le projet. Utilisez une table synchronisée, mappez la colonne d’inclusion à une vector(n) colonne, puis construisez un lakebase_ann index dessus. La dimension n doit correspondre à la sortie de votre modèle d’embedding.
3. Générez les embeddings hors ligne avec un point de terminaison de service de modèle. Remplissez la colonne d’embedding avec un modèle d’embedding — par exemple, en interrogeant un modèle d’embedding avec ai_query — puis passez ce même point de terminaison que embedding_model (voir ci-dessous). ai_search Intègre chaque requête au moment de la recherche, de sorte que la requête et les inclusions de documents stockés partagent un espace vectoriel.

Pour une source de connaissances Lakebase avec type un ensemble à lakebase_search, config accepte les clés suivantes :

L’exemple suivant configure une table Lakebase comme source de connaissances. Remplacez-le embedding_model par le point de terminaison utilisé pour intégrer la table hors ligne :

[
  {
    "type": "lakebase_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles_synced",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "embedding_column": "article_embedding",
      "embedding_model": "databricks-gte-large-en",
      "lakebase_project_id": "my-lakebase-project"
    }
  }
]

Returns

A VARIANT avec le schéma suivant :

{
  "document": [
    {
      "page_content": STRING,  // Text content of the retrieved chunk
      "doc_uri": STRING,       // URI of the source document
      "metadata": MAP          // Additional metadata from the index
    }
  ],
  "answer": STRING,            // Grounded answer synthesized from the retrieved
                               // documents, or null
  "citations": [               // Present only when generate_citations is true
    {
      "document_index": INT    // Position in the document array above, starting at 0
    }
  ]
}

Quand generate_citations est true, lisez les answer champs et citations ensemble. Chaque combinaison de valeurs signifie quelque chose de différent :

• Un non-nul answer avec un tableau vide citations signifie qu’une réponse a été générée, mais qu’aucun chunk retourné n’a été sélectionné.
• Un null answer avec un tableau vide citations signifie que la génération de citations s’est exécutée mais n’a produit aucune citation car aucune réponse à la base n’a été générée.
• Une valeur nulle citations signifie que la génération de citations n’était pas disponible ou n’a pas été invoquée, y compris quand query est SQL NULL.

Examples

Recherche de base

L’exemple suivant recherche un index IA Search et retourne des documents classés ainsi qu’une réponse fondée :

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "filter_columns": "product,language"
    }
  }]')
) AS result;

Retourner les chunks de support pour la réponse générée

L’exemple suivant retourne le sous-ensemble des chunks récupérés que le modèle sélectionné pour soutenir la réponse :

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "vector_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles",
      "text_col": "article_body",
      "doc_uri_col": "article_url"
    }
  }]'),
  options => map('generate_citations', 'true')
) AS result;

Le document tableau contient toujours l’ensemble complet des chunks retournés. Utilisez les document_index éléments de chaque citation pour choisir les supports dans ce tableau. Ces indices ne sont valides que dans une seule réponse. Ils peuvent changer entre les appels, lors de changements de reclassement, ou lors de la mise à jour de l’index.

Recherche multi-sources avec instructions

L’exemple suivant recherche deux index de recherche IA et l’utilise instructions pour orienter la génération et le reclassement des requêtes :

SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.internal_kb", "text_col": "body", "doc_uri_col": "source_uri"}
    }
  ]'),
  'Focus on firewall rules and VPC/VNet configuration. Prefer official documentation over internal articles when both cover the same topic.'
) AS result;

Recherchez dans un tableau Lakebase

L’exemple suivant recherche dans une table synchronisée Lakebase et retourne des documents classés ainsi qu’une réponse ancrée :

SELECT ai_search(
  'How do I configure auto-scaling for my SQL warehouse?',
  PARSE_JSON('[{
    "type": "lakebase_search",
    "config": {
      "index_name": "prod_catalog.docs.support_articles_synced",
      "text_col": "article_body",
      "doc_uri_col": "article_url",
      "embedding_column": "article_embedding",
      "embedding_model": "databricks-gte-large-en",
      "lakebase_project_id": "my-lakebase-project"
    }
  }]')
) AS result;

Combinez un index de recherche IA et une table Lakebase

L’exemple suivant recherche dans un index de recherche IA et dans une table Lakebase dans le même appel. Les résultats des deux sources sont dédupliqués, reclassés ensemble, puis retournés en une seule liste classée :

SELECT ai_search(
  'What are the networking requirements for serverless SQL warehouses?',
  PARSE_JSON('[
    {
      "type": "vector_search",
      "config": {"index_name": "prod_catalog.docs.public_docs", "text_col": "content", "doc_uri_col": "doc_url"}
    },
    {
      "type": "lakebase_search",
      "config": {
        "index_name": "prod_catalog.docs.internal_kb_synced",
        "text_col": "body",
        "doc_uri_col": "source_uri",
        "embedding_column": "body_embedding",
        "embedding_model": "databricks-gte-large-en",
        "lakebase_project_id": "my-lakebase-project"
      }
    }
  ]')
) AS result;

Enrichir une table avec une récupération et une réponse générée

L’exemple suivant enrichit chaque ticket de support avec des documents pertinents et une solution suggérée. Comme la génération de réponses est activée par défaut, la résolution suggérée est disponible directement sur le answer terrain — aucune étape de génération distincte n’est requise.

SELECT
  ticket_id,
  customer_description,
  ai_search(
    customer_description,
    PARSE_JSON('[{
      "type": "vector_search",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]'),
    'Find product documentation, known issues, and troubleshooting guides relevant to this support ticket.'
  ):answer::STRING AS suggested_resolution
FROM support.tickets.open_tickets;

Pour contrôler le format de sortie ou utiliser un modèle spécifique, il faut définir 'generate_answer' et 'false' enchaîner les documents récupérés à ai_query la place.

Limitations

• ai_search prend en charge les index AI Search ("type": "vector_search") et les tables synchronisées Lakebase ("type": "lakebase_search") comme sources de connaissances.
• Vous pouvez spécifier jusqu’à 10 sources de connaissances par appel, dans n’importe quelle combinaison des types pris en charge.
• L’argument instructions est limité à 4 000 caractères.

Fonctions associées

• Fonction ai_parse_document
• Fonction ai_prep_search
• Fonction ai_query
• Fonction ai_extract
• Fonction ai_enrich