ai_enrich 関数

適用対象: Databricks SQL Databricks Runtime

ai_enrich()関数は、あなたが定義したスキーマから行の新しい列を生成します。 入力内容とターゲットスキーマが与えられたとき、関数はAIモデルを呼び出して各フィールドを埋めます。 生成された値をAI検索インデックスやライブウェブ検索など、1つ以上の知識ソースに基づけることも可能で、モデルのトレーニングデータだけでなく、自分のデータや up-to日付情報を反映させることができます。

ai_enrichを使って、スケールでテーブルに派生属性を追加できます。 レコードにタグ付けや分類、欠落しているメタデータの補完、または単一のSQL関数呼び出しから各行に調査済みのコンテキストを付けることができます。 デフォルトでは、生成された各フィールドには、値がどのように導出されたかを説明する短い理由が添えられて返されます。

Requirements

• Databricks Runtime 18.2 以降。
• サーバーレスコンピュートを使用している場合、サーバーレス環境のバージョンは3以上に設定されており、これにより VARIANTなどの機能が可能になります。
• AI検索インデックスを基盤にするには、知識源として使うAI 検索インデックス を1つ以上必要です。
• ai_enrich機能はDatabricksノートブック、SQLエディタ、Databricksのワークフロー、ジョブ、またはLakeflow上のSpark Declarative Pipelinesを通じて利用可能です。

データのセキュリティ

ドキュメント データは、Databricks セキュリティ境界内で処理されます。 DatabricksはAI関数呼び出しに渡されるパラメータを保存しませんが、Databricksランタイムバージョンなどのメタデータ実行の詳細は保持します。

構文

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

論争

• content: STRING または VARIANT 式。 豊かさを増やすための列。 VARIANT 入力、例えば ai_parse_documentのような別のAI関数の出力は内部的にJSON文字列にシリアライズされます。

• schema: 生成する列を定義する STRING リタラルです。 ai_extractと同じ文法を使っています。 スキーマは次のようになります。

  • シンプルスキーマ:文字列として生成されるフィールド名のJSON配列です。

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

  • 高度なスキーマ:型情報、記述、ネスト構造を持つJSONオブジェクト。

    • string、integer、number、boolean、およびenum型をサポートします。 型の検証を実行します。 最大 500 個の列挙値。
    • "properties"を使った"type": "object"を使ったネストオブジェクトをサポートします。
    • "items"を使ったプリミティブやオブジェクトの配列を"type": "array"サポートします。
    • 各プロパティごとにオプションの "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: 生成された値を基盤とする知識ソース構成のJSON配列を含むオプションの VARIANT または STRING 式。 「 ナレッジソース構成」を参照してください。

• options: 省略可能な MAP<STRING, STRING>。 サポートキー:

  • 'version': 使う関数バージョン。
  • 'instructions'最大20,000文字の STRING 。 エンリッチメント課題を説明する自然言語のガイダンス。 オプションです;スキーマフィールド名だけでエンリッチメントを駆動できます。 たとえば、'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に設定されたAI検索インデックスの場合、configは以下のキーを受け入れます。

1回の通話で複数の vector_search ソースを設定することができます。

ウェブ検索の設定

typeがweb_searchに設定されたウェブ検索の場合、configは以下のオプションキーを受け入れます。 ウェブ検索はAzure Databricksのウェブ検索を通じて実行されます。可用性については「制限」を参照してください。

1回の通話で最大1つの 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"]
    }
  }
]

返品

以下の 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.
}

responseフィールドには生成された列が含まれます:

• フィールド名やタイプはスキーマの定義に一致しています。 ネストされたオブジェクトや配列は元の形状を保ちます。
• デフォルト(enableRationale は 'true')、各リーフは {rationale, value} オブジェクトであり、 rationale は値の導出方法の簡単な説明、 value はスキーマに従って型付けされた生成値です。 enableRationaleが'false'されると、各葉は{value}オブジェクトとなります。
• フィールドの value は生成できないときには null されます。

metadata フィールドには、応答に関するメタデータが含まれています。 行が知識ソースによってグラウンディングされている場合、 metadata.sources はその行をグラウンディングしたソースドキュメント識別子の配列です。 接地は行単位で行われるため、個々のフィールドではなく列全体に sources 適用されます。

content が NULL の場合、結果は NULL です。

例示

ウェブ検索における地層濃縮

以下の例は、各企業がオープンウェブ上のライブウェブ検索に基づいているシンプルな配列スキーマ(各フィールドが文字列として生成される)を用いて各企業を豊かにしています。

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 関数