ai_extract 関数

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

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

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

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

要件

Apache 2.0 ライセンス

現時点で使用できる基になるモデルは、 Apache 2.0 ライセンスの Copyright © The Apache Software Foundation に基づくライセンスが付与されています。 お客様は、該当するモデル ライセンスへのコンプライアンスを遵守する責任を負います。

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

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

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

Tip

Databricks では、を使用することをお勧めします。 バージョン 1.0 は、これらの機能をサポートしていないレガシ インターフェイスであり、新規または運用環境のワークロードには推奨されません。

バージョン 2.0 以降では、

  • 入れ子になったオブジェクト、配列、型の検証、フィールドの説明を含むリッチ JSON スキーマ
  • アップストリーム AI 関数からの STRING と VARIANT の両方の入力を受け入れます。 ai_parse_document

バージョン 2.1 では、引用文献と信頼度スコアも追加されます。

バージョンを明示的にピン留めするには、 options => map('version', '2.1')渡します。

構文

ai_extract(content, schema [, options])

バージョン 2

ai_extract(content, schema [, options])

バージョン 1 (レガシ)

ai_extract(content, labels [, options])

引数

  • 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"にフォールバックします。

戻り値

次を含む 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 version and citation details.
}

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

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

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

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

  • 生テキスト (STRING) 入力の場合、引用は元の入力のテキストのスパンです。 metadata.citations 内の各オブジェクトには次のものが含まれます。
    • id: フィールドのcitation_idsエントリに一致する整数。
    • start: 入力文字列への 0 から始まる文字オフセットを含みます。
    • stop: 入力文字列への排他的な 0 から始まる文字オフセット。
  • PDF ドキュメントと画像の場合 (ai_extractの下流ai_parse_document使用する場合)、引用は元の入力の境界ボックスです。 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
  "metadata": {
    "version": "2.0"     // Function version used
  },
  "error_message": null  // null on success, or error message on failure
}

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

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

metadata フィールドには、応答に関するメタデータが含まれています。

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

バージョン 1 (レガシ)

各フィールドがSTRUCTで指定されたエンティティ型に対応するlabelsを返します。 各フィールドには、抽出されたエンティティを表す文字列が含まれます。 任意のエンティティ型に対して複数の候補が見つかると、関数は 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": {
     "version": "2.1",
     "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": {
    "version": "2.1",
    "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"
   },
   "metadata": {
     "version": "2.0"
   },
   "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"
   },
   "metadata": {
     "version": "2.0"
   },
   "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
     }
   },
   "metadata": {
     "version": "2.0"
   },
   "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
   },
   "metadata": {
     "version": "2.0"
   },
   "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"}

制限事項

  • この関数は、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