このページは Cloud Translation API によって翻訳されました。

データセットを作成

プロセッサバージョンのトレーニング、アップトレーニング、評価を行うには、ドキュメントのラベル付きデータセットが必要です。

このページでは、データセットの作成方法、ドキュメントのインポート方法、スキーマの定義方法について説明します。インポートしたドキュメントにラベルを付けるには、ドキュメントにラベルを付けるをご覧ください。

このページでは、トレーニング、アップトレーニング、評価をサポートするプロセッサを作成済みであることを前提としています。プロセッサがサポートされている場合、Google Cloud コンソールに [トレイン] タブが表示されます。

データセットのストレージオプション

データセットを保存するには、次の 2 つのオプションから選択できます。

Google が管理
カスタムロケーションの Cloud Storage

特別な要件がない限り（ドキュメントを CMEK 対応のフォルダのセットに保存するなど）、よりシンプルな Google 管理ストレージオプションをおすすめします。作成したデータセットのストレージオプションは、プロセッサに対して変更できません。

カスタム Cloud Storage ロケーションのフォルダまたはサブフォルダは、最初は空で、厳密に読み取り専用として扱われる必要があります。内容を手動で変更すると、データセットが使用できなくなり、データが失われる可能性があります。Google 管理のストレージオプションには、このリスクはありません。

ストレージロケーションをプロビジョニングする手順は次のとおりです。

Google が管理するストレージ（推奨）

新しいプロセッサを作成するときに詳細オプションを表示します。
デフォルトのラジオグループオプションは [Google 管理] ストレージのままにします。
[作成] を選択します。
データセットが正常に作成され、データセットのロケーションが Google 管理のロケーションであることを確認します。

カスタムストレージオプション

詳細オプションをオンまたはオフにします。
[独自のストレージロケーションを指定] を選択します。
入力コンポーネントから Cloud Storage フォルダを選択します。
[作成] を選択します。

Dataset API オペレーション

このサンプルでは、processors.updateDataset メソッドを使用してデータセットを作成する方法を示します。データセットリソースはプロセッサ内のシングルトンリソースです。つまり、リソース作成 RPC はありません。代わりに、updateDataset RPC を使用して設定できます。Document AI には、指定した Cloud Storage バケットにデータセットドキュメントを保存するか、Google によって自動的に管理されるようにするオプションがあります。

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID The ID of your custom processor
GCS_URI: Your Cloud Storage URI where dataset documents are stored

指定されたバケット

次の手順に沿って、指定した Cloud Storage バケットを使用してデータセットリクエストを作成します。

HTTP メソッド

PATCH https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset

リクエスト JSON:

  {
      "name":"projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset"
      "gcs_managed_config" {
          "gcs_prefix" {
              "gcs_uri_prefix": "GCS_URI"
          }
      }
      "spanner_indexing_config" {}
  }

Google が管理

Google が管理するデータセットを作成する場合は、次の情報を更新します。

HTTP メソッド

PATCH https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset

リクエスト JSON:

  {
      "name":"projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset"
      "unmanaged_dataset_config": {}
      "spanner_indexing_config": {}
  }

リクエストを送信するには、Curl を使用します。

リクエスト本文を request.json という名前のファイルに保存します。次のコマンドを実行します。

CURL

  curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset"

次のような JSON レスポンスが返されます。

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
  }

ドキュメントのインポート

新しく作成したデータセットは空です。ドキュメントを追加するには、[ドキュメントをインポート] を選択し、データセットに追加するドキュメントを含む Cloud Storage フォルダを 1 つ以上選択します。

Cloud Storage が別のプロジェクトにある場合は、Document AI がそのロケーションからファイルを読み取れるようにアクセス権を付与してください。 Google Cloud 具体的には、Document AI のコアサービスエージェント service-{project-id}@gcp-sa-prod-dai-core.iam.gserviceaccount.com に ストレージオブジェクト閲覧者ロールを付与する必要があります。詳細については、サービスエージェントをご覧ください。

create-dataset-8

次に、次のいずれかの割り当てオプションを選択します。

トレーニング: トレーニングセットに割り当てます。
テスト: テストセットに割り当てます。
自動分割: トレーニングセットとテストセット内のドキュメントをランダムにシャッフルします。
未割り当て: トレーニングや評価では使用されません。後で手動で割り当てることができます。

課題は後でいつでも変更できます。

[インポート] を選択すると、Document AI は、サポートされているファイル形式と JSON Document ファイルをすべてデータセットにインポートします。JSON Document ファイルの場合、Document AI はドキュメントをインポートし、その entities をラベルインスタンスに変換します。

Document AI は、インポートフォルダを変更したり、インポート完了後にフォルダから読み取ったりしません。

ページ上部の [アクティビティ] を選択して [アクティビティ] パネルを開きます。正常にインポートされたファイルとインポートに失敗したファイルが一覧表示されます。

既存のプロセッサバージョンがある場合は、[ドキュメントをインポート] ダイアログで [自動ラベル付けを使用したインポート] チェックボックスをオンにします。ドキュメントは、インポート時に以前のプロセッサを使用して自動ラベル付けされます。ラベル付きとマークしないと、自動ラベル付けされたドキュメントをトレーニングまたはアップトレーニングしたり、テストセットで使用したりすることはできません。自動ラベル付けされたドキュメントをインポートしたら、自動ラベル付けされたドキュメントを手動で確認して修正します。次に、[保存] を選択して修正を保存し、ドキュメントにラベルが付いていることを示します。必要に応じてドキュメントを割り当てることができます。自動ラベル付けをご覧ください。

ドキュメントのインポート RPC

このサンプルでは、dataset.importDocuments メソッドを使用してドキュメントをデータセットにインポートする方法を示します。

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor
GCS_URI: Your Cloud Storage URI where dataset documents are stored
DATASET_TYPE: The dataset type to which you want to add documents. The value should be either `DATASET_SPLIT_TRAIN` or `DATASET_SPLIT_TEST`.
TRAINING_SPLIT_RATIO: The ratio of documents which you want to autoassign to the training set.

トレーニングデータセットまたはテストデータセット

トレーニングデータセットまたはテストデータセットにドキュメントを追加する場合:

HTTP メソッド

POST https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/importDocuments

リクエスト JSON:

  {
      "batch_documents_import_configs": {
          "dataset_split": DATASET_TYPE
          "batch_input_config": {
          "gcs_prefix": {
              "gcs_uri_prefix": GCS_URI
          }
          }
      }
  }

トレーニングデータセットとテストデータセット

ドキュメントをトレーニングデータセットとテストデータセットに自動的に分割する場合:

HTTP メソッド

POST https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/importDocuments

リクエスト JSON:

  {
      "batch_documents_import_configs": {
          "auto_split_config": {
          "training_split_ratio": TRAINING_SPLIT_RATIO
          },
          "batch_input_config": {
          "gcs_prefix": {
              "gcs_uri_prefix": "gs://test_sbindal/pdfs-1-page/"
          }
          }
      }
  }

リクエスト本文を request.json という名前のファイルに保存し、次のコマンドを実行します。

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/importDocuments"

次のような JSON レスポンスが返されます。

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
  }

ドキュメントの削除 RPC

このサンプルでは、dataset.batchDeleteDocuments メソッドを使用してデータセットからドキュメントを削除する方法を示します。

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor
DOCUMENT_ID: The document ID blob returned by <code>ImportDocuments</code> request

ドキュメントを削除する

HTTP メソッド

  POST https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/batchDeleteDocuments

リクエスト JSON:

  {
  "dataset_documents": {
      "individual_document_ids": {
      "document_ids": DOCUMENT_ID
      }
      }
  }

リクエスト本文を request.json という名前のファイルに保存し、次のコマンドを実行します。

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/batchDeleteDocuments"

次のような JSON レスポンスが返されます。

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"
  }

ドキュメントをトレーニングセットまたはテストセットに割り当てる

[データ分割] でドキュメントを選択し、トレーニングセット、テストセット、未割り当てのいずれかに割り当てます。

create-dataset-9

テストセットのベストプラクティス

テストセットの品質によって、評価の品質が決まります。

テストセットはプロセッサ開発サイクルの開始時に作成し、ロックインして、プロセッサの品質の経時的な変化を追跡できるようにする必要があります。

テストセットには、ドキュメントタイプごとに少なくとも 100 個のドキュメントを含めることをおすすめします。開発中のモデルにお客様が使用しているドキュメントの種類をテストセットが代表していることを確認することが重要です。

テストセットは、頻度に関して本番環境トラフィックを代表するものである必要があります。たとえば、W2 フォームを処理していて、70% が 2020 年、30% が 2019 年のものであると予想される場合、テストセットの約 70% は W2 2020 ドキュメントで構成する必要があります。このようなテストセットの構成により、プロセッサのパフォーマンスを評価する際に、各ドキュメントのサブタイプに適切な重要度が付与されます。また、国際フォームから個人名を抽出する場合は、テストセットにターゲットとするすべての国のフォームが含まれていることを確認してください。

トレーニングセットのベストプラクティス

テストセットにすでに含まれているドキュメントは、トレーニングセットに含めないでください。

テストセットとは異なり、最終トレーニングセットは、ドキュメントの多様性や頻度に関して、ユーザーの使用状況を厳密に代表している必要はありません。ラベルによっては、トレーニングが難しいものもあります。したがって、これらのラベルにトレーニングセットを偏らせることで、パフォーマンスを向上させることができます。

最初のうちは、どのラベルが難しいかを判断する良い方法はありません。テストセットで説明されているアプローチと同じ方法で、ランダムにサンプリングされた小さな初期トレーニングセットから始めます。この最初のトレーニングセットには、アノテーションを付ける予定のドキュメントの合計数の約 10% を含める必要があります。次に、プロセッサの品質を反復的に評価し（特定のエラーパターンを探す）、トレーニングデータを追加できます。

プロセッサスキーマを定義する

データセットを作成したら、ドキュメントのインポートの前または後にプロセッサスキーマを定義できます。

プロセッサの schema は、ドキュメントから抽出するラベル（名前や住所など）を定義します。

[スキーマを編集] を選択し、必要に応じてラベルを作成、編集、有効化、無効にします。

完了したら、必ず [保存] を選択してください。

create-dataset-10

スキーマラベルの管理に関する注意事項:

スキーマラベルを作成した後、スキーマラベルの名前を編集することはできません。
スキーマラベルを編集または削除できるのは、トレーニング済みのプロセッサバージョンがない場合に限られます。編集できるのはデータ型とオカレンスタイプのみです。
ラベルを無効にしても、予測には影響しません。処理リクエストを送信すると、プロセッサバージョンはトレーニング時にアクティブだったすべてのラベルを抽出します。

データスキーマを取得する

このサンプルでは、データセットを使用する方法を示します。getDatasetSchema を使用して現在のスキーマを取得します。DatasetSchema はシングルトンリソースで、データセットリソースの作成時に自動的に作成されます。

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor

データスキーマを取得する

HTTP メソッド

GET https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema"

次のような JSON レスポンスが返されます。

  {
      "name": "projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema",
      "documentSchema": {
          "entityTypes": [
          {
              "name": $SCHEMA_NAME,
              "baseTypes": [
              "document"
              ],
              "properties": [
              {
                  "name": $LABEL_NAME,
                  "valueType": $VALUE_TYPE,
                  "occurrenceType": $OCCURRENCE_TYPE,
                  "propertyMetadata": {}
              },
              ],
              "entityTypeMetadata": {}
          }
          ]
      }
  }

ドキュメントスキーマを更新する

このサンプルは、dataset.updateDatasetSchema を使用して現在のスキーマを更新する方法を示しています。次の例は、データセットスキーマを更新して 1 つのラベルを追加するコマンドを示しています。既存のラベルを削除または更新するのではなく、新しいラベルを追加する場合は、まず getDatasetSchema を呼び出して、そのレスポンスで適切な変更を加えることができます。

リクエストのデータを使用する前に、次のように置き換えます。

LOCATION: Your processor location
PROJECT_ID: Your Google Cloud project ID
PROCESSOR_ID: The ID of your custom processor
LABEL_NAME: The label name which you want to add
LABEL_DESCRIPTION: Describe what the label represents
DATA_TYPE: The type of the label. You can specify this as string, number, currency, money, datetime, address, boolean.
OCCURRENCE_TYPE: Describes the number of times this label is expected. Pick an enum value.

スキーマの更新

HTTP メソッド

PATCH https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema

リクエスト JSON:

  {
      "document_schema": {
          "entityTypes": [
              {
                  "name": $SCHEMA_NAME,
                  "baseTypes": [
                  "document"
                  ],
                  "properties": [
                  {
                      "name": LABEL_NAME,
                      "description": LABEL_DESCRIPTION,
                      "valueType": DATA_TYPE,
                      "occurrenceType": OCCURRENCE_TYPE,
                      "propertyMetadata": {}
                  },
                  ],
                  "entityTypeMetadata": {}
              }
          ]
      }
  }

リクエスト本文を request.json という名前のファイルに保存し、次のコマンドを実行します。

CURL

  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://LOCATION-documentai.googleapis.com/v1beta3/projects/PROJECT_ID/locations/LOCATION/processors/PROCESSOR_ID/dataset/datasetSchema"

ラベル属性を選択する

データの種類

Plain text: 文字列値。
Number: 数値 - 整数または浮動小数点数。
Money: 金額。ラベル付けする際は、通貨記号は含めないでください。
- エンティティが抽出されると、google.type.Money に正規化されます。
Currency: 通貨記号。
Datetime: 日付または時刻の値。
- エンティティが抽出されると、ISO 8601 テキスト形式に正規化されます。
Address - ロケーションの住所。
- エンティティが抽出されると、正規化され、EKG で拡充されます。
Checkbox - true または false のブール値。

オカレンス

エンティティが特定のタイプのドキュメントに常に表示されることが予想される場合は、REQUIRED を選択します。そのような期待がない場合は、OPTIONAL を選択します。

同じ値が同じドキュメントに複数回出現する場合でも、エンティティに 1 つの値が存在することが予想される場合は、ONCE を選択します。エンティティに複数の値が存在することが予想される場合は、MULTIPLE を選択します。

親ラベルと子ラベル

親子ラベル（表形式エンティティ）は、テーブル内のデータにラベルを付けるために使用されます。次の表には 3 行 4 列があります。

create-dataset-11

このようなテーブルは、親子ラベルを使用して定義できます。この例では、親ラベル line-item がテーブルの行を定義します。

親ラベルを作成する

[スキーマを編集] ページで、[ラベルを作成] を選択します。
[This is a parent label] チェックボックスをオンにして、その他の情報を入力します。親ラベルには optional_multiple または require_multiple が含まれている必要があります。これにより、表内のすべての行をキャプチャするために繰り返しることができます。
[保存] を選択します。

create-dataset-12

親ラベルが [スキーマを編集] ページに表示され、その横に [子ラベルを追加] オプションが表示されます。

子ラベルを作成する

[Edit schema] ページで、親ラベルの横にある [Add Child Label] を選択します。
子ラベルの情報を入力します。
[保存] を選択します。

追加する子ラベルごとに手順を繰り返します。

子ラベルは、[スキーマを編集] ページの親ラベルの下にインデントされて表示されます。

create-dataset-13

親子ラベルはプレビュー機能であり、テーブルでのみサポートされています。ネストの深さは 1 に制限されています。つまり、子エンティティに他の子エンティティを含めることはできません。

ラベル付きドキュメントからスキーマラベルを作成する

事前にラベル付けされた Document JSON ファイルをインポートして、スキーマラベルを自動的に作成します。

Document のインポートが進行中の場合、新しく追加されたスキーマラベルがスキーマエディタに追加されます。[スキーマを編集] を選択して、新しいスキーマラベルのデータ型とオカレンスタイプを確認または変更します。確認したら、スキーマラベルを選択し、[有効にする] を選択します。

サンプルデータセット

Document AI Workbench の使用を開始しやすくするために、データセットは公開の Cloud Storage バケットに提供されています。このバケットには、複数のドキュメントタイプのラベル付きとラベルなしのサンプル Document JSON ファイルが含まれています。

ドキュメントの種類に応じて、アップトレーニングまたはカスタムエクストラクタに使用できます。

gs://cloud-samples-data/documentai/Custom/
gs://cloud-samples-data/documentai/Custom/1040/
gs://cloud-samples-data/documentai/Custom/Invoices/
gs://cloud-samples-data/documentai/Custom/Patents/
gs://cloud-samples-data/documentai/Custom/Procurement-Splitter/
gs://cloud-samples-data/documentai/Custom/W2-redacted/
gs://cloud-samples-data/documentai/Custom/W2/
gs://cloud-samples-data/documentai/Custom/W9/

ラベルプロセス

データセットを作成

データセットのストレージ オプション

Google が管理するストレージ（推奨）

カスタム ストレージ オプション

Dataset API オペレーション

指定されたバケット

Google が管理

CURL

ドキュメントのインポート

ドキュメントのインポート RPC

トレーニング データセットまたはテスト データセット

トレーニング データセットとテスト データセット

CURL

ドキュメントの削除 RPC

ドキュメントを削除する

CURL

ドキュメントをトレーニング セットまたはテストセットに割り当てる

テストセットのベスト プラクティス

トレーニング セットのベスト プラクティス

プロセッサ スキーマを定義する

データスキーマを取得する

データスキーマを取得する

CURL

ドキュメント スキーマを更新する

スキーマの更新

CURL

ラベル属性を選択する

ラベル付きドキュメントからスキーマラベルを作成する

サンプル データセット

データセットのストレージオプション

カスタムストレージオプション

トレーニングデータセットまたはテストデータセット

トレーニングデータセットとテストデータセット

ドキュメントをトレーニングセットまたはテストセットに割り当てる

テストセットのベストプラクティス

トレーニングセットのベストプラクティス

プロセッサスキーマを定義する

ドキュメントスキーマを更新する

サンプルデータセット