ai_enrich 函數

適用於：Databricks SQL Databricks Runtime

這個 ai_enrich() 函式會根據你定義的結構，為一列產生新的欄位。 給定輸入內容與目標結構後，函式會呼叫 AI 模型來填補每個欄位。 它可以選擇性地將產生的值建立在一個或多個 知識來源 中，例如 人工智慧搜尋索引 或即時網路搜尋，讓這些值反映你自己的資料或 up-to日期資訊，而非僅是模型的訓練資料。

用於 ai_enrich 大規模地將衍生屬性加入資料表。 你可以標記並分類紀錄、補足缺少的元資料，或從單一 SQL 函式呼叫中附加研究過的上下文到每一列。 預設情況下，每個產生的欄位都會回傳一個簡短的理由，說明該值是如何推導出來的。

Requirements

• Databricks 執行環境 18.2 或以上。
• 若使用無伺服器運算，無伺服器環境版本必須設定為 3 或以上，這樣才能啟用像 VARIANT。
• 要建立在 AI 搜尋索引的基礎上，你需要一個或多個 AI 搜尋索引 作為知識來源。
• 此功能 ai_enrich 可透過 Databricks 筆記本、SQL 編輯器、Databricks 工作流程、工作或 Lakeflow 上的 Spark 宣告式管線使用。

數據安全性

您的文件數據會在 Databricks 安全性周邊內處理。 Databricks 不儲存傳遞給 AI 函式呼叫的參數，但會保留元資料執行細節，例如 Databricks 執行時版本。

語法

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

Arguments

• content STRING：或VARIANT表達式。 那排要豐富。 VARIANT 輸入，例如另一個 AI 函式 ai_parse_document的輸出，內部會序列化成 JSON 字串。

• schema： 一個 STRING 定義要產生欄位的文字。 它使用與 相同的文法 ai_extract。 該模式可以是：

  • 簡單結構：一個由欄位名稱組成的 JSON 陣列，這些欄位名稱以字串形式產生。

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

  • 進階結構：一個包含型別資訊、描述與巢狀結構的 JSON 物件。

    • 支援、stringinteger、number、booleanenum、及類型。 執行型別驗證。 最多可有 500 個 enum 值。
    • 支援使用 "type": "object" 含 "properties"的巢狀物件。
    • 支援使用 "type": "array" 。"items"
    • 每個屬性的可選 "description" 欄位用來引導產生的數值。

    {
      "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：一個可選 VARIANT 的表達式， STRING 包含用來支撐產生值的知識來源配置的 JSON 陣列。 請參見 知識來源配置。

• options：一個可選 MAP<STRING, STRING>的 。 支援的按鍵：

  • 'version'：使用的功能版本。
  • 'instructions'： A STRING ，最多可達20,000字元。 描述豐富化任務的自然語言指導。 可選;僅模式欄位名稱即可驅動豐富化。 例如， 'Infer attributes for each company from its public profile.'
  • 'enableRationale'： 'true' （預設值）或 'false'。 當 'true'時，每個產生的欄位會以物件形式返回 {rationale, value} ，其中 rationale 解釋了該值如何推導出來。 設定為 'false' 僅返回 {value} 。

知識來源配置

這個 knowledge_sources 參數是一個 JSON 陣列。 每個元素都是一個 {type, description, config} 信封。 欄位 type 識別如何 ai_enrich 擷取接地上下文，欄位 config 則包含特定來源的配置。

AI 搜尋索引配置

對於設定 type 為 vector_search的 config AI 搜尋索引，接受以下鍵數：

你可以在一次通話中設定多個 vector_search 來源。

網頁搜尋設定

對於設定 type 為 web_search的 config 網頁搜尋，接受以下選用鍵。 網頁搜尋可透過 Azure Databricks 的網頁搜尋進行;詳見可用性限制。

你最多只能設定一個 web_search 來源。

以下範例將 AI 搜尋索引與網頁搜尋配置為知識來源：

[
  {
    "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

VARIANT A，其結構如下：

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

該 response 欄位包含產生的欄位：

• 欄位名稱和類型與結構定義相符。 巢狀物件和陣列會保持其原始形狀。
• 預設情況下（enableRationale 為 'true'），每個葉節點是一個 {rationale, value} 物件，其中 rationale 是對該值如何產生的簡短說明， value 是根據結構型別產生的值。 當 enableRationale 時 'false'，每個葉子 都是一個 {value} 物件。
• value場的狀態是null無法產生。

該 metadata 欄位包含關於回應的元資料。 當該列被知識來源接地時， metadata.sources 是一組將該列接地的原始文件識別碼陣列。 接地是針對一列的，因此 sources 適用於整排，而非單一欄位。

如果 content 是 NULL，結果就是 NULL。

Examples

網路搜尋中的基層富集

以下範例透過簡單的陣列結構（每個欄位以字串形式產生）豐富每家公司，並基於開放網路上的即時網路搜尋：

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

限制網路搜尋至特定網域

以下範例與上述相同，但限制搜尋範圍為 allowed_domains，因此只有來自這些領域的結果才會使數值得到基礎：

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;

強制執行帶有指令的型別結構

以下範例使用相同的開放網路搜尋，但採用完整型別結構，新增 instructions 以引導任務，並停用 rationale，使每個欄位回傳一個純值：

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;

填充巢狀結構

以下範例為每家公司填充巢狀結構——結構化地址物件、創辦人名稱陣列、類型化年份及巢狀融資輪——這些結構基於即時網路搜尋，使值反映當前公開資訊，而非僅模型的訓練資料：

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;

AI 搜尋索引中的地質豐富

以下範例以產品文件的 AI 搜尋索引為基礎，豐富每個支援工單，使產生的數值從你自己的內容中提取：

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;

Limitations

• 知識 web_search 來源的接地僅在部分地區和工作空間中可用。 請參閱 Azure Databricks 上的網頁搜尋。
• instructions選項限制為 20,000 字元。

相關功能

• ai_extract函式
• ai_search函式
• ai_parse_document函式
• ai_prep_search函式
• ai_query函式