`ai_extract` 関数

適用対象: 「はい」のチェックマーク Databricks SQL Databricks Runtime

重要

プレビュー期間中:

基になる言語モデルでは複数の言語を処理できますが、この AI 関数は英語用にチューニングされています。
AI Functionsの地域可用性については、地域限定の機能を参照してください。

ai_extract()関数は、指定したスキーマに従ってテキストとドキュメントから構造化データを抽出します。基本的な抽出に単純なフィールド名を使用したり、入れ子になったオブジェクト、配列、型の検証、請求書、コントラクト、財務申告などのビジネスドキュメントのフィールドの説明を含む複雑なスキーマを定義したりできます。

この関数は、VARIANTなどの他の AI 関数からのテキストまたはai_parse_document出力を受け取り、エンドツーエンドのドキュメント処理のための構成可能なワークフローを可能にします。

ai_extractの結果を検証して反復処理するビジュアル UI については、「情報の抽出」を参照してください。

要件

Apache 2.0 ライセンス

Databricks では、該当する使用条件に準拠するために、これらのライセンスを確認することをお勧めしています。 Databricks の内部ベンチマークに従ってパフォーマンスが向上するモデルが将来出現した場合、Databricks によってモデルが変更される可能性があります (および、このページで提供されている該当するライセンスの一覧)。

この関数を利用するモデルは、Model Serving Foundation Model API を使用して使用できるようになります。 Databricks で使用できるモデルと、それらのモデルの使用を管理するライセンスとポリシーについては、該当するモデルの用語を参照してください。

Databricks の内部ベンチマークに従ってパフォーマンスが向上するモデルが将来出現した場合、Databricks によってモデルが変更され、ドキュメントが更新される可能性があります。

この関数は、一部のリージョンでのみ使用できます。 AI 関数の可用性に関するページを参照してください。
この関数は、Azure Databricks SQL クラシックでは使用できません。
Databricks SQL の価格ページを確認してください。
Databricks Runtime 15.1 以上では、この関数は Databricks ノートブック内でサポートされ、これには Databricks ワークフロー内でタスクとして実行されるノートブックも含まれます。
バッチ推論ワークロードでは、パフォーマンスを向上させるために Databricks Runtime 15.4 ML LTS が必要です。

構文

Databricks では、入れ子になったフィールドの抽出と説明がサポートされているため、この関数のバージョン 2 を使用することをお勧めします。

バージョン 2.1 (推奨)

ai_extract(
    content VARIANT | STRING,
    schema STRING,
    [options MAP<STRING, STRING>]
) RETURNS VARIANT

バージョン 2

ai_extract(
    content VARIANT | STRING,
    schema STRING,
    [options MAP<STRING, STRING>]
) RETURNS VARIANT

バージョン 1

ai_extract(
    content STRING,
    labels ARRAY<STRING>,
    [options MAP<STRING, STRING>]
) RETURNS STRUCT

引数

バージョン 2.1 (推奨)

content: VARIANT または STRING 式。以下のいずれかを受け入れます:
- 生テキスト STRING
- 別の AI 関数 (VARIANT など) によって生成されるai_parse_document
schema: 抽出用の JSON スキーマを定義する STRING リテラル。スキーマは次のようになります。
- 単純なスキーマ: フィールド名の JSON 配列 (文字列と見なされます)
```
"[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
```
- 高度なスキーマ: 型情報、説明、入れ子構造を持つ JSON オブジェクト
  - string、integer、number、boolean、およびenum型をサポートします。型の検証を実行します。無効な値を指定すると、エラーが発生します。最大 500 個の列挙値。
  - "type": "object"を使用して入れ子になったオブジェクトをサポートします"properties"
  - で "type": "array" を使用するプリミティブまたはオブジェクトの配列をサポートします "items"
  - 抽出品質をガイドする各プロパティの省略可能な "description" フィールド
options: 構成オプションを含む省略可能な MAP<STRING, STRING> :
- version: 移行 ("2.1"、 "2.0"、 "1.0") をサポートするためのバージョン切り替え。既定値は入力の種類に基づいています。
- instructions:抽出品質を向上させるためのタスクとドメインのグローバルな説明。 20,000 文字未満にする必要があります。
- enableCitations: trueすると、抽出スキーマ内の各フィールドの出力に、0 個以上の引用文献の一覧が含まれます。これは、抽出された出力をドキュメントに示します。
- enableConfidenceScores: trueすると、抽出スキーマ内の各フィールドの出力には、その値に関するモデルの確実性を示す 0 ~ 1 の信頼度スコアが含まれます。適切な信頼度のしきい値は、特定のユースケースによって異なります。リスクとエラーに対する許容範囲に合わせてカットオフを選択する必要があります。

バージョン 2

content: VARIANT または STRING 式。以下のいずれかを受け入れます:
- 生テキスト STRING
- 別の AI 関数 (VARIANT など) によって生成されるai_parse_document
schema: 抽出用の JSON スキーマを定義する STRING リテラル。スキーマは次のようになります。
- 単純なスキーマ: フィールド名の JSON 配列 (文字列と見なされます)
```
"[\"vendor_name\", \"invoice_id\", \"total_amount\"]"
```
- 高度なスキーマ: 型情報、説明、入れ子構造を持つ JSON オブジェクト
  - string、integer、number、boolean、およびenum型をサポートします。型の検証を実行します。無効な値を指定すると、エラーが発生します。最大 500 個の列挙値。
  - "type": "object"を使用して入れ子になったオブジェクトをサポートします"properties"
  - で "type": "array" を使用するプリミティブまたはオブジェクトの配列をサポートします "items"
  - 抽出品質をガイドする各プロパティの省略可能な "description" フィールド
options: 構成オプションを含む省略可能な MAP<STRING, STRING> :
- version: 移行をサポートするバージョンスイッチ (v1 動作の場合は"1.0" 、v2 動作の場合は "2.0" )。既定値は入力の種類に基づいていますが、 "1.0"にフォールバックします。
- instructions:抽出品質を向上させるためのタスクとドメインのグローバルな説明。 20,000 文字未満にする必要があります。

バージョン 1

content: 生のテキストを含む STRING 式。
labels: ARRAY<STRING> リテラル。各要素は、抽出するエンティティの種類です。
options: 構成オプションを含む省略可能な MAP<STRING, STRING> :
- version: 移行をサポートするバージョンスイッチ (v1 動作の場合は"1.0" 、v2 動作の場合は "2.0" )。既定値は入力の種類に基づいていますが、 "1.0"にフォールバックします。

戻り値

バージョン 2.1 (推奨)

次を含む VARIANT を返します。

{
  "response": {...},       // Extracted data matching the provided schema. Each leaf is returned as a Field object (see below).
  "error_message": null,   // null on success, or error message on failure
  "metadata": { ... }      // Metadata about the response, including unfurled citation ids.
}

response フィールドには、スキーマに従って抽出された構造化データが含まれます。

フィールド名と型がスキーマ定義と一致する
スキーマの構造は応答で保持されます。入れ子になったオブジェクトと配列は元の形状を維持します。抽出スキーマの各 "スカラー" フィールドには、次のフィールドを含む出力オブジェクトがあります。
- value:抽出された値。スキーマに従って型指定されます。 Null フィールドを抽出できない場合は。
- citation_ids: enableCitations が trueされている場合にのみ存在します。 metadata.citationsにインデックスが作成された ID の配列。
- confidence_score: enableConfidenceScores が trueされている場合にのみ存在します。 0 から 1 の範囲の浮動小数点数。
整数型、数値型、ブール型、列挙型に対して型の検証が適用される
content が NULL の場合、結果は NULL です。

metadata フィールドには、応答に関するメタデータが含まれています。 enableCitationsがtrueされると、metadata フィールドには、抽出された値を入力の場所までトレースするresponse フィールドの各引用 ID に関する詳細が含まれます。

入力の種類に応じて、引用文献には次の 2 種類のいずれかを指定できます。

生テキスト (STRING) 入力の場合、引用は元の入力のテキストのスパンです。 metadata.citations 内の各オブジェクトには次のものが含まれます。
- id: フィールドのcitation_idsエントリに一致する整数。
- start: 入力文字列への 0 から始まる文字オフセットを含みます。
- stop: 入力文字列への排他的な 0 から始まる文字オフセット。
PDF ドキュメントと画像の場合 (ai_parse_documentの下流ai_extract使用する場合)、引用は元の入力の境界ボックスです。 metadata.citations内の各オブジェクトには次のものが含まれます。
- id: フィールドの citation_ids エントリに一致する整数。
- bbox: {coord, page_id} オブジェクトの配列。出力の element.bbox と同じ形状 ai_parse_document 。 coord はページイメージ上のピクセル座標です。 [x0, y0, x1, y1]; page_id は 0 から始まるページインデックスです。

バージョン 2

次を含む VARIANT を返します。

{
  "response": { ... },   // Extracted data matching the provided schema
  "error_message": null          // null on success, or error message on failure
}

response フィールドには、スキーマに従って抽出された構造化データが含まれます。

フィールド名と型がスキーマ定義と一致する
入れ子になったオブジェクトと配列は構造体に保持されます
フィールドが見つからない場合は null される可能性があります
型の検証は、 integer、 number、 boolean、および enum 型に適用されます

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

バージョン 1

各フィールドがSTRUCTで指定されたエンティティ型に対応するlabelsを返します。各フィールドには、抽出されたエンティティを表す文字列が含まれます。任意のエンティティ型に対して複数の候補が見つかると、関数は 1 つだけを返します。

例

バージョン 2.1 (推奨)

単純なスキーマ - フィールド名のみ

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '["invoice_id", "vendor_name", "total_amount", "invoice_date"]',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":   {"value": "12345"},
     "vendor_name":  {"value": "Acme Corp"},
     "total_amount": {"value": "1250.00"},
     "invoice_date": {"value": "2024-01-15"}
   },
   "error_message": null
 }

高度なスキーマ - 型と説明

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":   {"value": "12345"},
     "vendor_name":  {"value": "Acme Corp"},
     "total_amount": {"value": 1250.00},
     "invoice_date": {"value": "2024-01-15"}
   },
   "error_message": null
 }

入れ子になったオブジェクトと配列

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp
     Line 1: Widget A, qty 10, $50.00 each
     Line 2: Widget B, qty 5, $100.00 each
     Subtotal: $1,000.00, Tax: $80.00, Total: $1,080.00',
    '{
      "invoice_header": {
        "type": "object",
        "properties": {
          "invoice_id": {"type": "string"},
          "vendor_name": {"type": "string"}
        }
      },
      "line_items": {
        "type": "array",
        "description": "List of invoiced products",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "quantity": {"type": "integer"},
            "unit_price": {"type": "number"}
          }
        }
      },
      "totals": {
        "type": "object",
        "properties": {
          "subtotal": {"type": "number"},
          "tax_amount": {"type": "number"},
          "total_amount": {"type": "number"}
        }
      }
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_header": {
       "invoice_id":  {"value": "12345"},
       "vendor_name": {"value": "Acme Corp"}
     },
     "line_items": [
       {"description": {"value": "Widget A"}, "quantity": {"value": 10}, "unit_price": {"value": 50.00}},
       {"description": {"value": "Widget B"}, "quantity": {"value": 5},  "unit_price": {"value": 100.00}}
     ],
     "totals": {
       "subtotal":     {"value": 1000.00},
       "tax_amount":   {"value": 80.00},
       "total_amount": {"value": 1080.00}
     }
   },
   "error_message": null
 }

を使用したコンポーザビリティ `ai_parse_document`

> WITH parsed_docs AS (
    SELECT
      path,
      ai_parse_document(
        content,
        MAP('version', '2.0')
      ) AS parsed_content
    FROM READ_FILES('/Volumes/finance/invoices/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_extract(
      parsed_content,
      '["invoice_id", "vendor_name", "total_amount"]',
      MAP('version', '2.1', 'instructions', 'These are vendor invoices.')
    ) AS invoice_data
  FROM parsed_docs;

列挙型の使用

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp, amount: $1,250.00 USD',
    '{
      "invoice_id": {"type": "string"},
      "vendor_name": {"type": "string"},
      "total_amount": {"type": "number"},
      "currency": {
        "type": "enum",
        "labels": ["USD", "EUR", "GBP", "CAD", "AUD"],
        "description": "Currency code"
      },
      "payment_terms": {"type": "string"}
    }',
    options => map('version', '2.1')
  );
 {
   "response": {
     "invoice_id":     {"value": "12345"},
     "vendor_name":    {"value": "Acme Corp"},
     "total_amount":   {"value": 1250.00},
     "currency":       {"value": "USD"},
     "payment_terms":  {"value": null}
   },
   "error_message": null
 }

引用文献 (STRING 入力、SPAN 引用)

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
   options => map(
     'version', '2.1',
     'enableCitations', 'true'
   )
  );
 {
   "response": {
     "invoice_id": {"citation_ids": [0], "value": "12345"},
     "vendor_name": {"citation_ids": [0], "value": "Acme Corp"},
     "total_amount": {"citation_ids": [1], "value": 1250.00},
     "invoice_date": {"citation_ids": [1], "value": "2024-01-15"}
   },
   "metadata": {
     "chunk_type": "span",
     "citations": [
       {"id": 0, "start": 0, "stop": 29},
       {"id": 1, "start": 29, "stop": 60}
     ]
   },
   "error_message": null
 }

引用文献 (ai_parse_documentからの VARIANT、BBOX 引用)

> WITH parsed AS (
    SELECT ai_parse_document(
             content,
             map('imageOutputPath', '/Volumes/main/default/parsed_images/')  // necessary for rendering bboxes
           ) AS doc
    FROM READ_FILES('/Volumes/main/default/invoices/invoice.pdf', format => 'binaryFile')
  )
  SELECT ai_extract(
    doc,
    '{"invoice_id":{"type":"string"}, "total_amount":{"type":"number"}}',
    options => map('version','2.1','enableCitations','true')
  ) AS extracted
  FROM parsed;
{
  "response": {
    "invoice_id":   {"citation_ids": [0], "value": "12345"},
    "total_amount": {"citation_ids": [1], "value": 1250.00}
  },
  "metadata": {
    "chunk_type": "bbox",
    "citations": [
      {"id": 0, "bbox": [{"coord": [120, 80,  240, 110], "page_id": 0}]},
      {"id": 1, "bbox": [{"coord": [400, 500, 560, 530], "page_id": 0}]}
    ],
    "pages": [{"id": 0, "image_uri": "/Volumes/main/default/parsed_images/6077ca79...f8efdb2ed05.jpg"}]
  },
  "error_message": null
}

信頼度スコア


> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }',
   options => map(
    'version', '2.1',
    'enableConfidenceScores', 'true'
   )
  );
{
  "response": {
    "invoice_id": {"confidence_score": 0.95, "value": "12345"},
    "vendor_name": {"confidence_score": 0.62, "value": "Acme Corp"},
    "total_amount": {"confidence_score": 1.0, "value": 1250.00},
    "invoice_date": {"confidence_score": 0.99, "value": "2024-01-15"}
  },
  "error_message": null
}

ノートブックの例

次のノートブックは、 ai_extract 関数の引用文献の出力を分析するためのビジュアルデバッグインターフェイスを提供します。ここでは、引用メタデータを部分文字列スニペット (STRING 入力) または境界ボックスオーバーレイ (VARIANT 入力) としてレンダリングし、 ai_extract 引用文献を SQL の ai_parse_document 要素に結合して、手動レビューのために信頼性の低い抽出にフラグを設定する方法を示します。

引用文献レンダリングノートブック

ノートブックを入手

バージョン 2

単純なスキーマ - フィールド名のみ

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '["invoice_id", "vendor_name", "total_amount", "invoice_date"]'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": "1250.00",
     "invoice_date": "2024-01-15"
   },
   "error_message": null
 }

高度なスキーマ - 型と説明

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp for $1,250.00 dated 2024-01-15',
    '{
      "invoice_id": {"type": "string", "description": "Unique invoice identifier"},
      "vendor_name": {"type": "string", "description": "Legal business name"},
      "total_amount": {"type": "number", "description": "Total invoice amount"},
      "invoice_date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
    }'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": 1250.00,
     "invoice_date": "2024-01-15"
   },
   "error_message": null
 }

入れ子になったオブジェクトと配列

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp
     Line 1: Widget A, qty 10, $50.00 each
     Line 2: Widget B, qty 5, $100.00 each
     Subtotal: $1,000.00, Tax: $80.00, Total: $1,080.00',
    '{
      "invoice_header": {
        "type": "object",
        "properties": {
          "invoice_id": {"type": "string"},
          "vendor_name": {"type": "string"}
        }
      },
      "line_items": {
        "type": "array",
        "description": "List of invoiced products",
        "items": {
          "type": "object",
          "properties": {
            "description": {"type": "string"},
            "quantity": {"type": "integer"},
            "unit_price": {"type": "number"}
          }
        }
      },
      "totals": {
        "type": "object",
        "properties": {
          "subtotal": {"type": "number"},
          "tax_amount": {"type": "number"},
          "total_amount": {"type": "number"}
        }
      }
    }'
  );
 {
   "response": {
     "invoice_header": {
       "invoice_id": "12345",
       "vendor_name": "Acme Corp"
     },
     "line_items": [
       {"description": "Widget A", "quantity": 10, "unit_price": 50.00},
       {"description": "Widget B", "quantity": 5, "unit_price": 100.00}
     ],
     "totals": {
       "subtotal": 1000.00,
       "tax_amount": 80.00,
       "total_amount": 1080.00
     }
   },
   "error": null
 }

を使用したコンポーザビリティ ai_parse_document

> WITH parsed_docs AS (
    SELECT
      path,
      ai_parse_document(
        content,
        MAP('version', '2.0')
      ) AS parsed_content
    FROM READ_FILES('/Volumes/finance/invoices/', format => 'binaryFile')
  )
  SELECT
    path,
    ai_extract(
      parsed_content,
      '["invoice_id", "vendor_name", "total_amount"]',
      MAP('instructions', 'These are vendor invoices.')
    ) AS invoice_data
  FROM parsed_docs;

列挙型の使用

> SELECT ai_extract(
    'Invoice #12345 from Acme Corp, amount: $1,250.00 USD',
    '{
      "invoice_id": {"type": "string"},
      "vendor_name": {"type": "string"},
      "total_amount": {"type": "number"},
      "currency": {
        "type": "enum",
        "labels": ["USD", "EUR", "GBP", "CAD", "AUD"],
        "description": "Currency code"
      },
      "payment_terms": {"type": "string"}
    }'
  );
 {
   "response": {
     "invoice_id": "12345",
     "vendor_name": "Acme Corp",
     "total_amount": 1250.00,
     "currency": "USD",
     "payment_terms": null
   },
   "error": null
 }

バージョン 1

> SELECT ai_extract(
    'John Doe lives in New York and works for Acme Corp.',
    array('person', 'location', 'organization')
  );
 {"person": "John Doe", "location": "New York", "organization": "Acme Corp."}

> SELECT ai_extract(
    'Send an email to jane.doe@example.com about the meeting at 10am.',
    array('email', 'time')
  );
 {"email": "jane.doe@example.com", "time": "10am"}

制限事項

バージョン 2.1 (推奨)

この関数は、Azure Databricks SQL クラシックでは使用できません。
この関数はビューでは使用できません。
スキーマでは、最大 128 個のフィールドがサポートされています。
フィールド名には、最大 150 文字を含めることができます。
スキーマでは、入れ子になったフィールドに対して最大 7 レベルの入れ子がサポートされます。
列挙型フィールドでは、最大 500 個の値がサポートされます。
型の検証は、 integer、 number、 boolean、および enum 型に適用されます。値が指定した型と一致しない場合、関数はエラーを返します。
コンテキストの最大合計サイズは 128,000 トークンです。

バージョン 2

この関数は、Azure Databricks SQL クラシックでは使用できません。
この関数はビューでは使用できません。
スキーマでは、最大 128 個のフィールドがサポートされています。
フィールド名には、最大 150 文字を含めることができます。
スキーマでは、入れ子になったフィールドに対して最大 7 レベルの入れ子がサポートされます。
列挙型フィールドでは、最大 500 個の値がサポートされます。
型の検証は、 integer、 number、 boolean、および enum 型に適用されます。値が指定した型と一致しない場合、関数はエラーを返します。
コンテキストの最大合計サイズは 128,000 トークンです。

バージョン 1

この関数は、Azure Databricks SQL クラシックでは使用できません。
この関数は Views では使用できません。
コンテンツにエンティティ型の複数の候補が見つかった場合は、1 つの値のみが返されます。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-03

ai_extract 関数

要件

構文

バージョン 2.1 (推奨)

バージョン 2

バージョン 1

引数

バージョン 2.1 (推奨)

バージョン 2

バージョン 1

戻り値

バージョン 2.1 (推奨)

バージョン 2

バージョン 1

例

バージョン 2.1 (推奨)

単純なスキーマ - フィールド名のみ

高度なスキーマ - 型と説明

入れ子になったオブジェクトと配列

を使用したコンポーザビリティ ai_parse_document

列挙型の使用

引用文献 (STRING 入力、SPAN 引用)

引用文献 (ai_parse_documentからの VARIANT、BBOX 引用)

信頼度スコア

ノートブックの例

引用文献レンダリング ノートブック

バージョン 2

バージョン 1

制限事項

バージョン 2.1 (推奨)

バージョン 2

バージョン 1

関連する関数

フィードバック

その他のリソース

`ai_extract` 関数

を使用したコンポーザビリティ `ai_parse_document`

引用文献レンダリングノートブック