ai_enrich-Funktion

Gilt für: Databricks SQL Databricks Runtime

Die ai_enrich() Funktion generiert neue Spalten für eine Zeile aus einem von dir definierten Schema. Gegeben Eingabeinhalt und ein Zielschema, ruft die Funktion ein KI-Modell auf, um jedes Feld auszufüllen. Sie kann die generierten Werte optional in einer oder mehreren Wissensquellen wie einem KI-Suchindex oder einer Live-Websuche verankern, sodass die Werte Ihre eigenen Daten oder up-to-Datumsdaten widerspiegeln und nicht nur die Trainingsdaten des Modells.

Verwenden Sie ai_enrich , um abgeleitete Attribute in einer Tabelle im Maßstab hinzuzufügen. Sie können Datensätze taggen und kategorisieren, fehlende Metadaten ausfüllen oder jeder Zeile aus einem einzigen SQL-Funktionsaufruf erforschten Kontext anhängen. Standardmäßig wird jedes generierte Feld mit einer kurzen Begründung zurückgegeben, die erklärt, wie der Wert abgeleitet wurde.

Requirements

• Databricks Runtime 18.2 oder höher.
• Wenn Sie serverlose Rechenleistungen verwenden, muss die serverlose Umgebungsversion auf 3 oder höher gesetzt werden, da dies Funktionen wie VARIANTmöglich macht.
• Um Bereicherung in einem KI-Suchindex zu verankern, benötigen Sie einen oder mehrere KI-Suchindizes als Wissensquellen.
• Die ai_enrich Funktion ist über Databricks-Notizbücher, einen SQL-Editor, Databricks-Workflows, Jobs oder Spark Declarative Pipelines auf Lakeflow verfügbar.

Datensicherheit

Ihre Dokumentdaten werden innerhalb des Databricks-Sicherheitsperimeters verarbeitet. Databricks speichert die Parameter, die in die KI-Funktionsaufrufe eingegeben werden, nicht, behält aber Metadaten-Laufdetails, wie zum Beispiel die verwendete Databricks-Runtime-Version.

Syntax

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

Argumente

• content: Ein STRING- oder VARIANT-Ausdruck. Der Row, um zu bereichern. VARIANT Eingabe, wie zum Beispiel die Ausgabe einer anderen KI-Funktion wie ai_parse_document, wird intern zu einem JSON-String serialisiert.

• schema: Ein STRING Literal, das die zu generierenden Spalten definiert. Sie verwendet dieselbe Grammatik wie ai_extract. Das Schema kann folgendes sein:

  • Einfaches Schema: Ein JSON-Array von Feldnamen, die als Zeichenketten generiert werden.

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

  • Fortgeschrittenes Schema: Ein JSON-Objekt mit Typinformationen, Beschreibungen und verschachtelten Strukturen.

    • Unterstützt string, integer, number, , booleanund enum Typen. Führt die Typüberprüfung aus. Maximal 500 Enumerationswerte.
    • Unterstützt verschachtelte Objekte mit "type": "object" ."properties"
    • Unterstützt Arrays von Primitiven oder Objekten mit "type": "array" ."items"
    • Optionales Feld "description" für jede Eigenschaft zur Steuerung des generierten Werts.

    {
      "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: Ein optionaler VARIANT oder STRING Ausdruck, der ein JSON-Array von Wissensquellenkonfigurationen enthält, die zur Erdung der generierten Werte verwendet werden. Siehe Konfiguration der Wissensquelle.

• options: Optional MAP<STRING, STRING>. Unterstützte Tasten:

  • 'version': Die Funktionsversion, die verwendet werden sollte.
  • 'instructions': A STRING mit bis zu 20.000 Zeichen. Natürliche Sprachanleitung, die die Anreicherungsaufgabe beschreibt. Optional; allein die Schemafeldnamen können die Anreicherung steuern. Beispiel: 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (Standard) oder 'false'. Wenn 'true', wird jedes erzeugte Feld als Objekt {rationale, value} zurückgegeben, wobei rationale erklärt, wie der Wert abgeleitet wurde. Nur auf Rückgabe {value} eingestellt'false'.

Konfiguration der Wissensquelle

Das Argument knowledge_sources ist ein JSON-Array. Jedes Element ist eine Hüllkurve {type, description, config} . Das Feld type identifiziert, wie ai_enrich er den Erdungskontext abruft, und das Feld config enthält die quellenspezifische Konfiguration.

KI-Suchindexkonfiguration

Für einen KI-Suchindex mit type gesetzt auf vector_searchakzeptiert , config folgende Schlüssel:

Man kann mehr als eine vector_search Quelle in einem einzigen Aufruf konfigurieren.

Websuchkonfiguration

Für eine Websuche mit type gesetzt auf web_searchakzeptiert , config die folgenden optionalen Schlüssel. Die Websuche läuft über die Websuche auf Azure Databricks; siehe Einschränkungen für die Verfügbarkeit.

Du kannst höchstens eine Quelle web_search pro Anruf konfigurieren.

Das folgende Beispiel konfiguriert einen KI-Suchindex und eine Websuche als Wissensquellen:

[
  {
    "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 mit folgendem Schema VARIANT :

{
  "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.
}

Das Feld response enthält die generierten Spalten:

• Feldnamen und -typen stimmen mit der Schema-Definition überein. Verschachtelte Objekte und Arrays behalten ihre ursprüngliche Form.
• Standardmäßig (enableRationale ist 'true'), ist jedes Blatt ein {rationale, value} Objekt, wobei rationale eine kurze Erklärung ist, wie der Wert abgeleitet wurde, und value der erzeugte Wert ist, der gemäß dem Schema getippt wird. Wenn enableRationale , 'false'ist jedes Blatt ein {value} Objekt.
• Ein Feld value ist null , wenn es nicht generiert werden kann.

Das metadata Feld enthält Metadaten zur Antwort. Wenn die Zeile von einer Wissensquelle geerdet ist, ist ein Array der Quelldokument-Identifikatoren, metadata.sources die die Zeile geerdet haben. Die Erdung ist auf Reihenhöhe und sources gilt daher für die ganze Reihe und nicht für einzelne Felder.

Wenn content ist NULL, ist das Ergebnis NULL.

Examples

Bodenanreicherung in der Websuche

Das folgende Beispiel bereichert jedes Unternehmen mit einem einfachen Array-Schema (jedes Feld wird als Zeichenkette generiert), das auf einer Live-Websuche über das offene Web basiert:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {}
  }]')
) AS result
FROM sales.accounts.companies;

Beschränken Sie die Websuche auf bestimmte Domänen

Das folgende Beispiel ist dasselbe wie oben, beschränkt jedoch die Websuche auf spezifische Seiten mit allowed_domains, sodass nur Ergebnisse aus diesen Domänen die Werte erden:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {"allowed_domains": ["wikipedia.org", "sec.gov"]}
  }]')
) AS result
FROM sales.accounts.companies;

Erzwingen Sie ein typisiertes Schema mit Anweisungen

Das folgende Beispiel verwendet dieselbe offene Websuche, jedoch mit einem vollständig typisierten Schema, addiert instructions zur Steuerung der Aufgabe und deaktiviert die Begründung, sodass jedes Feld einen einfachen Wert zurückgibt:

SELECT ai_enrich(
  company_name,
  '{
    "industry": {"type": "string", "description": "Primary industry"},
    "headquarters_country": {"type": "string"},
    "year_founded": {"type": "integer"}
  }',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {}
  }]'),
  options => map(
    'instructions', 'Fill each field from current, authoritative public sources. Use null when a value cannot be verified.',
    'enableRationale', 'false'
  )
) AS result
FROM sales.accounts.companies;

Befülle ein verschachteltes Schema

Das folgende Beispiel füllt für jedes Unternehmen ein verschachteltes Schema aus – ein strukturiertes Adressobjekt, ein Array von Gründernamen, ein getipptes Jahr und eine verschachtelte Finanzierungsrunde – basierend auf einer Live-Websuche, sodass die Werte aktuelle öffentliche Informationen widerspiegeln und nicht nur die Trainingsdaten des Modells:

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"}
      }
    }
  }',
  PARSE_JSON('[{
    "type": "web_search",
    "config": {}
  }]'),
  options => map('instructions', 'Ground each field in current, authoritative public sources. Use null when a value cannot be verified.')
) AS result
FROM sales.accounts.companies;

Bodenanreicherung in einem KI-Suchindex

Das folgende Beispiel bereichert jedes Support-Ticket mit Feldern, die in einem KI-Suchindex der Produktdokumentation basieren, sodass die generierten Werte aus deinen eigenen Inhalten stammen:

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;

Einschränkungen

• Erdung mit einer web_search Wissensquelle ist nur in einigen Regionen und Arbeitsbereichen möglich. Siehe Websuche auf Azure Databricks.
• Die instructions Option ist auf 20.000 Zeichen begrenzt.

Verwandte Funktionen

• ai_extract Funktion
• ai_search Funktion
• ai_parse_document Funktion
• ai_prep_search Funktion
• ai_query Funktion