ai_enrich Fonction

S’applique à : Databricks SQL Databricks Runtime

La ai_enrich() fonction génère de nouvelles colonnes pour une ligne à partir d’un schéma que vous définissez. À partir du contenu d’entrée et d’un schéma cible, la fonction appelle un modèle d’IA pour remplir chaque champ. Il peut optionnellement ancrer les valeurs générées dans une ou plusieurs sources de connaissances comme un index de recherche IA ou une recherche web en direct, afin que les valeurs reflètent vos propres données ou informations de up-to-date plutôt que les seules données d’entraînement du modèle.

À utiliser ai_enrich pour ajouter des attributs dérivés à une table à grande échelle. Vous pouvez taguer et catégoriser les enregistrements, combler les métadonnées manquantes, ou attacher le contexte recherché à chaque ligne à partir d’un seul appel de fonction SQL. Par défaut, chaque champ généré est renvoyé avec une courte justification expliquant comment la valeur a été déduite.

Spécifications

• Databricks Runtime 18.2 ou version ultérieure.
• 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.
• Pour ancrer l’enrichissement dans un index IA Search, il vous faut un ou plusieurs index AI Search à utiliser comme sources de connaissances.
• La ai_enrich 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.

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.

Syntax

ai_enrich(content, schema [, knowledge_sources] [, options])

Arguments

• content : Une expression STRING ou VARIANT. La dispute pour enrichir. VARIANT l’entrée, comme la sortie d’une autre fonction IA comme ai_parse_document, est sérialisée en une chaîne JSON en interne.

• schema: Un STRING littéral qui définit les colonnes à générer. Il utilise la même grammaire que ai_extract. Le schéma peut être :

  • Schéma simple : un tableau JSON de noms de champs, qui sont générés sous forme de chaînes.

    ["industry", "headquarters_country", "year_founded"]
    

  • Schéma avancé : un objet JSON avec informations de type, descriptions et structures imbriquées.

    • Prend en charge string, , integernumber, booleanet enum les types. Effectue la validation de type. Maximum de 500 valeurs d’énumération.
    • Prend en charge les objets imbriqués en utilisant "type": "object" avec "properties".
    • Prend en compte des tableaux de primitives ou d’objets utilisant "type": "array" avec "items".
    • Champ optionnel "description" pour chaque propriété afin de guider la valeur générée.

    {
      "hq_address": {
        "type": "object",
        "description": "Registered headquarters address",
        "properties": {
          "city": { "type": "string" },
          "country": { "type": "string" }
        }
      },
      "founding_team": { "type": "array", "description": "Full names of the founders", "items": { "type": "string" } },
      "founding_year": { "type": "integer", "description": "Year the company was founded" }
    }
    

• knowledge_sources: Une option VARIANT ou STRING une expression contenant un tableau JSON de configurations de sources de connaissances utilisées pour mettre à la terre les valeurs générées. Voir Configuration de la source de connaissances.

• options: facultatif MAP<STRING, STRING>. Touches prises en charge :

  • 'version': La version fonctionnelle à utiliser.
  • 'instructions': A STRING de jusqu’à 20 000 caractères. Conseils en langage naturel qui décrivent la tâche d’enrichissement. Optionnel ; les noms des champs de schéma seuls peuvent piloter l’enrichissement. Par exemple : 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (par défaut) ou 'false'. Lorsque 'true', chaque champ généré est retourné comme un {rationale, value} objet, où rationale explique comment la valeur a été dérivée. Réglez sur 'false' retour {value} uniquement.

Configuration de la source de connaissances

L’argument knowledge_sources est un tableau JSON. Chaque élément est une {type, description, config} enveloppe. Le type champ identifie comment ai_enrich il récupère le contexte de mise à la terre, et le config champ contient la configuration spécifique à la source.

Configuration de l’index de recherche IA

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

Vous pouvez configurer plus d’une vector_search source en un seul appel.

Configuration de la recherche web

Pour une recherche web avec type défini à web_search, config accepte les clés optionnelles suivantes. La recherche web s’effectue via la recherche web sur Azure Databricks ; voir Limitations pour la disponibilité.

Vous pouvez configurer au maximum une web_search source par appel.

L’exemple suivant configure un index de recherche IA et une recherche web comme sources de connaissances :

[
  {
    "type": "vector_search",
    "description": "Internal product catalog",
    "config": {
      "index_name": "prod_catalog.docs.product_catalog",
      "text_col": "description",
      "doc_uri_col": "product_url"
    }
  },
  {
    "type": "web_search",
    "config": {
      "allowed_domains": ["wikipedia.org"]
    }
  }
]

Returns

A VARIANT avec le schéma suivant :

{
  "response": { ... },     // Generated columns matching the provided schema. Each leaf is returned as an object (see below).
  "error_message": null,   // null on success, or an error message on failure
  "metadata": { ... }      // Metadata about the response, including grounding sources.
}

Le response champ contient les colonnes générées :

• Les noms et types de champs correspondent à la définition du schéma. Les objets imbriqués et les réseaux conservent leur forme d’origine.
• Par défaut (enableRationale est 'true'), chaque feuille est un {rationale, value} objet, où rationale est une brève explication de la manière dont la valeur a été dérivée et value est la valeur générée, typée selon le schéma. Lorsque enableRationale est 'false', chaque feuille est un {value} objet.
• Celui d’un value champ est null lorsqu’il ne peut pas être généré.

Le metadata champ contient des métadonnées sur la réponse. Lorsque la ligne est mise à la terre par une source de connaissances, metadata.sources il s’agit d’un tableau des identifiants du document source qui a mis la ligne à la base. La mise à la terre est au niveau des lignes, donc sources s’applique à toute la ligne plutôt qu’aux champs individuels.

Si content est NULL, le résultat est NULL.

Exemples

Enrichissement de base

L’exemple suivant génère deux colonnes pour chaque nom d’entreprise en utilisant les connaissances propres au modèle. Comme la rationalisation est activée par défaut, chaque champ est retourné comme un {rationale, value} objet :

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country"]'
) AS result
FROM sales.accounts.companies;

Schéma structuré avec instructions

L’exemple suivant définit un schéma typé, ajoute instructions pour orienter la tâche, et désactive la justification pour que chaque champ renvoie une valeur claire :

SELECT ai_enrich(
  review_text,
  '{
    "sentiment": {"type": "string", "description": "positive, negative, or neutral"},
    "topics": {"type": "array", "items": {"type": "string"}},
    "requires_follow_up": {"type": "boolean"}
  }',
  options => map(
    'instructions', 'Analyze the customer review and categorize it for the support team.',
    'enableRationale', 'false'
  )
) AS result
FROM support.reviews.customer_reviews;

Générer un schéma imbriqué

L’exemple suivant génère un schéma imbriqué pour chaque entreprise — un objet d’adresse structuré, une série de noms fondateurs, une année tapée et un tour de financement imbriqué :

SELECT ai_enrich(
  company_name,
  '{
    "hq_address": {
      "type": "object",
      "description": "Registered headquarters address",
      "properties": {
        "city": {"type": "string"},
        "country": {"type": "string"}
      }
    },
    "founding_team": {"type": "array", "description": "Full names of the founders", "items": {"type": "string"}},
    "founding_year": {"type": "integer", "description": "Year the company was founded"},
    "latest_funding_round": {
      "type": "object",
      "properties": {
        "stage": {"type": "string", "description": "Funding stage, for example Seed or Series A"},
        "amount_usd": {"type": "number", "description": "Amount raised in USD"}
      }
    }
  }'
) AS result
FROM sales.accounts.companies;

Enrichissement du sol dans un index de recherche IA

L’exemple suivant enrichit chaque ticket de support avec des champs fondés sur un index IA Search de la documentation produit, de sorte que les valeurs générées sont tirées de votre propre contenu :

SELECT
  ticket_id,
  ai_enrich(
    customer_description,
    '{
      "affected_product": {"type": "string"},
      "suggested_resolution": {"type": "string"},
      "documentation_url": {"type": "string"}
    }',
    PARSE_JSON('[{
      "type": "vector_search",
      "description": "Product documentation and troubleshooting guides",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]')
  ) AS result
FROM support.tickets.open_tickets;

Enrichissement du sol avec recherche web

L’exemple suivant enrichit chaque ligne d’entreprise avec des informations up-to-date récupérées sur le web :

SELECT ai_enrich(
  company_name,
  '["recent_funding_round", "latest_headline"]',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {"allowed_domains": ["reuters.com", "bloomberg.com"]}
  }]'),
  options => map('instructions', 'Find the most recent, verifiable information for each company.')
) AS result
FROM sales.accounts.companies;

Limitations

• L’ancrage avec une web_search source de connaissances n’est disponible que dans certaines régions et espaces de travail. Voir la recherche web sur Azure Databricks.
• L’option instructions est limitée à 20 000 personnages.

Fonctions associées

• ai_extract fonction
• ai_search fonction
• ai_parse_document fonction
• ai_prep_search fonction
• ai_query fonction