文書中のテキストを分類する

入力ファイルを、特定の一般的な文書タイプ用のスキーマ定義、またはカスタム文書用のスキーマ定義に分類します。文書を前処理することで、分類された文書内のテキストをより効率的に抽出することができる。

ドキュメントでスキーマベースのキーと値のペア抽出を使用する前に、テキスト分類 REST API リクエスト本文で複数のスキーマを定義することで、ドキュメントを分類することができます。あらかじめ定義された文書タイプやカスタム文書に対応するスキーマを組み合わせて提供することができます。文書をあらかじめ分類しておくことで、抽出処理を提供されたスキーマで定義されたフィールドに限定することができる。ドキュメント内のキーと値のペアのデータがスキーマにマッチしない場合、テキスト分類APIはドキュメントが分類されていないことを示します。

テキスト分類 REST API を使用すると、プロジェクトに保存されている入力ファイルを資産分類できます。

必要な権限: ドキュメントを分類するには、プロジェクト内で管理者または編集者の役割を持っている必要があります。
必要な認証情報: watsonx.ai API で認証するには、認証情報を生成する必要があります。詳細は「ベアラートークンの生成」を参照してください。

始める前に

管理者は、文書を処理する一連の機械学習モデルをインストールする必要があります。必要なモデルの集合のIDは. です wdu。
プロジェクトにドキュメントを追加する前に、以下のようにドキュメントを準備してください：
- 文書からパスワード保護を解除します。
- PDF文書がデジタル認証されている場合は、文書をDOCや DOCX などの別のファイル形式に変換してください。
特定のユースケースに合わせて、テキスト分類リクエストに含めるパラメータを決定します。詳細はテキスト分類パラメータを参照。

重要:

プロジェクト wdu_project_models_dnd を変更したり削除したりしないでください。このプロジェクトはインストール中に自動的に作成され、 watsonx.ai のLLMサービスにアクセスするために必要です。プロジェクトを削除すると、テキストのKVP抽出、スキーマ生成、テキスト分類など、LLMに基づく機能が動作しなくなります。よくある間違いには、「Invalid project GUID encountered in request path」「Failed to load model 'semantickvp'」「Cannot set Project or Space」などがあります。

手順

REST API を使用してビジネス・ドキュメントを分類するには、以下のハイレベルな手順に従います：

分類対象のファイルをストレージ資産に追加してください。また、テキスト抽出処理の結果を保存するストレージ資産指定することもできます。

以下のストレージタイプを使用できます：
接続されたストレージ資産

ドキュメントをプロジェクト内の資産として保存し、API内で接続IDによってファイルを参照してください。クレデンシャルに アクセス・キーと秘密鍵 ペアを使用する接続資産サポートされています。詳細は、「 APIから参照するファイルを追加する」を参照のこと。

プロジェクトまたはデプロイメント・スペース内のコンテナ
入力文書をデプロイメント・スペーススペースまたはプロジェクト内のコンテナに保存するには、資産ファイルAPIを使用して入力ファイルを直接アップロードしてください。詳細は、 Data & AI Common Core Software API ドキュメントを参照してください。

入力ファイルは、APIにおいて以下のファイルパスで参照されます：
```
"document_reference": {
  "type": "container",
  "location": {
    "path": "dummy_path/ibm-annual-report-2024-pt1_1-20-1.pdf"
  }
},
"results_reference": {
  "type": "container",
  "location": {
    "path": "dummy_path/results/"
  }
}
```
分類プロセスを開始するには、 Start a text classification request API メソッドを使用します。 APIリクエストの詳細については、 REST APIリクエスト例を参照してください。

metadata.id フィールドに返されるIDに注意。このIDは、後でリクエストのステータスを確認するために使用します。
リクエストのステータスを確認するには、 Get the results of the request APIメソッドを使用します。

ステータスをチェックすることは、プロセスが何らかの理由で失敗したかどうかを知る唯一の方法である。

ステータスが completed の場合、 results フィールドには文書分類処理結果の詳細が表示されます。

REST APIリクエスト例

以下のコマンドは、プロジェクト内の Cloud Object Storage バケツに格納されている retail_guidebook.pdf ファイルからテキストを抽出するリクエストを送信し、抽出された結果を results_data フォルダに保存します。

curl -X POST \
  'https://cpd-<namespace-name>.apps.<OCP-domain>/ml/v1/text/classifications?version=2025-10-08' \
  --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": "retail_guidebook.pdf"
      }
    },
    "parameters": {
      "languages": [
        "en"
      ],
      "ocr_mode": "enabled",
      "classification_mode": "exact",
      "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": "john.smith@gmail.com",
                "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."
              }
           }
        } ]
      }
    }
  }

レスポンスから、 results 属性から、分類結果を見つけることができます：

"results": {
  "completed_at": "2025-10-08T09:05:42.880Z",
  "running_at": "2025-10-08T09:05:27.345Z",
  "status": "completed",
  "document_classified": "True",
  "document_type": "Auto_Insurance_Application"
}

次の作業

テキスト分類要求の結果を使用して、ドキュメントからテキストをより効率的に抽出するためにキーと値のペアのスキーマ定義をどのように使用するかを決定することができます。詳細はテキスト抽出を参照してください。