キー・バリュー・ペア抽出のためのカスタム・スキーマの作成

開始前に

文書を見直し、スキーマで定義するフィールド名と説明の指針となる以下の情報を決定する：

• 文書から抽出したいデータの種類
• 抽出したいデータの正確なラベル
• 左上のヘッダーや右のカラムなど、ページ上の各項目の位置

例えば、 カリフォルニア州個人自動車保険申請書類の以下の情報に注目してください：

• エージェンシー名、申請者の住所、キャリア名、契約番号など、抽出したいデータ。
• AGENCY」、「APPLICANT'S NAME AND MAILING ADDRESS」、「POLICY #」などの正確なフィールドラベル。 文書に表示されているラベルをそのまま引用することで、基礎モデルが正しい値に結びつくようになる。

手順

1. スキーマの一番上にあるメタデータで、 document_description フィールドにドキュメントの説明を記述します。 document_description フィールドは、キーと値のペア抽出に使用される基礎モデルの分類器プロンプトに含まれます。

{
   "document_type": "Auto_Insurance_Application",
   "document_description": "California Personal Auto Application form used to open or update an auto policy.",
   "additional_prompt_instructions": "Return phone numbers exactly as they appear in the document.",
}

1. スキーマに含めるフィールドを決定する。 各フィールドについて、以下の3つの要素を定義する：

   • フィールド名 ：フィールドの一意のキー名を選択します。
   • 値の例 ：日付値や整数値など、モデルが期待される型を推測するのに役立つサンプル値を指定します。 例を提供することで、モデルのパフォーマンスが向上する。
   • 説明そのフィールドが何を表しているかを簡単に説明する。 説明文は、抽出プロセス中に何を探すべきかをモデルが理解するのを助けるために、基礎モデルに渡される。
     重要： フィールドの説明は、モデルの検証を助け、ドキュメント内の正しい情報に焦点を当てるためのコンテキストを提供します。 記述は正確で一義的でなければならない。

   例えば、 California Personal Auto Insurance Application 文書から代理店名を抽出するフィールドを定義します。

   "agency_name": {
     "default": "",
     "example": "Spring Insurance",
     "description": "Name of the insurance agency shown in the Agency section (upper‑left of the page)."
   }
   

2. available_options パラメータを使用して、スキーマに追加の属性値を指定します。 文書に明示的に記載されていないが、文脈や視覚的要素から推測できるフィールドにパラメータを使用する。 例えば、請求書では、文書のさまざまな部分で通貨価値がドル記号で表示されることがあるが、米ドルが請求書の通貨であることは明示的に記載されないことがある。 このような場合、モデルが返すことができる有効な通貨値のクローズドリストを提供し、モデルのレスポンスにおける幻覚を減らすことができます。

   "currency": {
     "default": "",
     "example": "USD",
     "available_options": ["USD", "EUR", "CNY", "JPY", "GBP", "AUD", "CAD", "CHF", "HKD", "SGD", "INR", "KRW", "MXN", "BRL", "ZAR", "SEK", "NOK", "DKK", "NZD", "TRY", "AED", "THB", "PLN", "IDR", "MYR", "PHP", "RUB", "CZK", "ILS"],
     "description": "The currency used in the invoice."
   }
   

3. オプション ：テキスト抽出リクエストでスキーマを使用する前に、JSONスキーマをローカルで検証し、スキーマが整形式であり、期待される構造と一致していることを確認します。 次のようなツールを使うことができる：

   • jsonlint.com フォーマットをチェックする
   • スキーマをロードして検査するための Python スクリプト
   • IDE組み込みのJSONリンター

カスタムスキーマとAPIリクエストの例

次のコマンドは、すべての必要なメタデータを先頭に含み、それに続いて、付随する定義を持つ一連のフィールドを含む完全なカスタムスキーマを使用して、テキストを抽出するリクエストを送信します。 各フィールドには、デフォルト値（空）、例、および抽出プロセス中にモデルをガイドするための説明が含まれています。

curl -X POST \
  'https://{region}.ml.cloud.ibm.com/ml/v1/text/extractions?version=2024-10-18' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJraWQiOi...'

リクエスト・ボディは以下の通りである：

{
    "project_id": "e40e5895-ce4d-42a3-b699-8ac764b89a09",
    "document_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "5c0cefce-da57-408b-b47d-58f7785de3ee"
      },
      "location": {
        "bucket":"my-cloud-object-storage-bucket",
        "file_name": "ca_auto_insurance_app.pdf"
      }
    },
    "results_reference": {
      "type": "connection_asset",
      "connection": {
        "id": "5c0cefce-da57-408b-b47d-58f7785de3ee"
      },
      "location": {
        "bucket":"my-cloud-object-storage-bucket",
        "file_name": "results_data"
      }
    },
    "parameters": {
      "requested_outputs": [
        "assembly",
        "md",
        "html",
        "plain_text",
        "page_images",
      ],
      "languages": [
        "en"
      ],
      "mode": "standard",
      "ocr_mode": "enabled",
      "create_embedded_images": "disabled",
      "semantic_config": {
        "schemas": [ {
           "document_type": "Auto_Insurance_Application",
           "document_description": "A California Personal Auto Application form used to collect information necessary for initiating or updating an auto insurance policy. It includes agency, applicant, carrier, and policy details such as contact information, address, policy number, and effective/expiration dates.",
           "additional_prompt_instructions": "Return phone numbers and policy numbers exactly as they appear in the document.",
           "fields": {
              "agency_name": {
                "default": "",
                "example": "Spring Insurance",
                "description": "Name of the insurance agency handling the auto application."
              },
              "applicant_name": {
                "default": "",
                "example": "John Smith",
                "description": "Full name of the person applying for auto insurance."
              },
              "applicant_address": {
                "default": "",
                "example": "245 W 52nd St, Apt 8B, New York, NY 10019",
                "description": "Mailing address of the applicant including street, apartment, city, state, and ZIP code."
              },
              "applicant_phone": {
                "default": "",
                "example": "(917) 555-2843",
                "description": "Phone number for contacting the applicant."
              },
              "applicant_email": {
                "default": "",
                "example": "[email protected]",
                "description": "Email address of the applicant."
              },
              "carrier_name": {
                "default": "",
                "example": "Tower Insurance Company",
                "description": "Name of the insurance carrier providing the policy."
              },
              "policy_number": {
                "default": "",
                "example": "10",
                "description": "Unique identifier for the insurance policy."
              },
              "effective_date": {
                "default": "",
                "example": "2023-01-01",
                "description": "Date when the insurance policy becomes effective."
              },
              "expiration_date": {
                "default": "",
                "example": "2024-01-01",
                "description": "Date when the insurance policy expires."
              }
           }
        } ]
      }
    }
  }

ベスト・プラクティス

効果的なスキーマを書くために、以下のベストプラクティスを使用する：

フィールドの命名規則

アンダースコアで単語を区切る。 例えば、 applicantName の代わりに applicant_name を使う。 名前は短く、しかし説明的にする。 セクションのフィールドには、 [section_name]_[field_name] の書式を使用します。 テーブルのフィールドには、 の書式を使用します。 [table_name]_row_[row_number]_[column_name]

効果的な説明を書く

その情報が文書のどこにあるのかを具体的に示すこと。 日付や数字など、値の形式を変更する指示は含めないこと。 その分野を特定するラベルや見出しがあれば記載する。 特殊なケースやバリエーションに注意すること。

追加のプロンプト指示ファンデーションモデルのプロンプト指示を使用して、「画像に表示されている番号の書式を保持する」など、特定のドキュメントタイプに対する抽出精度を向上させます。

トラブルシューティング

以下の表は、カスタム・スキーマを使用する際によくある問題とその解決方法について説明したものです：

詳細情報

• watsonx.ai APIリファレンス・ドキュメント

親トピック テキスト抽出パラメータ