パフォーマンスを評価する

Document AI が生成する適合率や再現率などの評価指標を使用して、プロセッサの予測パフォーマンスを判断します。

これらの評価指標は、プロセッサから返されたエンティティ(予測)とテスト ドキュメントのアノテーションを比較して生成されます。プロセッサにテストセットがない場合は、まずデータセットを作成し、テスト ドキュメントにラベルを付ける必要があります。

評価を実行する

プロセッサ バージョンをトレーニングまたはアップトレーニングするたびに、評価が自動的に実行されます。

評価を手動で実行することもできます。これは、テストセットを変更した後に更新された指標を生成する場合や、事前トレーニング済みのプロセッサ バージョンを評価する場合に必要です。

ウェブ UI

  1. Google Cloud コンソールで、[プロセッサ] ページに移動して、プロセッサを選択します。

    [プロセッサ] ページに移動

  2. [評価とテスト] タブで、評価するプロセッサの [バージョン] を選択し、[新しい評価を実行] をクリックします。

完了すると、ページにはすべてのラベルと個々のラベルの評価指標が表示されます。

Python

詳細については、Document AI Python API のリファレンス ドキュメントをご覧ください。

Document AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID'
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'
# gcs_input_uri = # Format: gs://bucket/directory/


def evaluate_processor_version_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version_id: str,
    gcs_input_uri: str,
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    name = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    evaluation_documents = documentai.BatchDocumentsInputConfig(
        gcs_prefix=documentai.GcsPrefix(gcs_uri_prefix=gcs_input_uri)
    )

    # NOTE: Alternatively, specify a list of GCS Documents
    #
    # gcs_input_uri = "gs://bucket/directory/file.pdf"
    # input_mime_type = "application/pdf"
    #
    # gcs_document = documentai.GcsDocument(
    #     gcs_uri=gcs_input_uri, mime_type=input_mime_type
    # )
    # gcs_documents = [gcs_document]
    # evaluation_documents = documentai.BatchDocumentsInputConfig(
    #     gcs_documents=documentai.GcsDocuments(documents=gcs_documents)
    # )
    #

    request = documentai.EvaluateProcessorVersionRequest(
        processor_version=name,
        evaluation_documents=evaluation_documents,
    )

    # Make EvaluateProcessorVersion request
    # Continually polls the operation until it is complete.
    # This could take some time for larger files
    operation = client.evaluate_processor_version(request=request)
    # Print operation details
    # Format: projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID
    print(f"Waiting for operation {operation.operation.name} to complete...")
    # Wait for operation to complete
    response = documentai.EvaluateProcessorVersionResponse(operation.result())

    # After the operation is complete,
    # Print evaluation ID from operation response
    print(f"Evaluation Complete: {response.evaluation}")

評価の結果を取得する

ウェブ UI

  1. Google Cloud コンソールで、[プロセッサ] ページに移動して、プロセッサを選択します。

    [プロセッサ] ページに移動

  2. [評価とテスト] タブで、評価を表示するプロセッサのバージョンを選択します。

完了すると、ページにはすべてのラベルと個々のラベルの評価指標が表示されます。

Python

詳細については、Document AI Python API のリファレンス ドキュメントをご覧ください。

Document AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'
# evaluation_id = 'YOUR_EVALUATION_ID'


def get_evaluation_sample(
    project_id: str,
    location: str,
    processor_id: str,
    processor_version_id: str,
    evaluation_id: str,
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the evaluation
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    evaluation_name = client.evaluation_path(
        project_id, location, processor_id, processor_version_id, evaluation_id
    )
    # Make GetEvaluation request
    evaluation = client.get_evaluation(name=evaluation_name)

    create_time = evaluation.create_time
    document_counters = evaluation.document_counters

    # Print the Evaluation Information
    # Refer to https://cloud.google.com/document-ai/docs/reference/rest/v1beta3/projects.locations.processors.processorVersions.evaluations
    # for more information on the available evaluation data
    print(f"Create Time: {create_time}")
    print(f"Input Documents: {document_counters.input_documents_count}")
    print(f"\tInvalid Documents: {document_counters.invalid_documents_count}")
    print(f"\tFailed Documents: {document_counters.failed_documents_count}")
    print(f"\tEvaluated Documents: {document_counters.evaluated_documents_count}")

プロセッサ バージョンのすべての評価を一覧表示する

Python

詳細については、Document AI Python API のリファレンス ドキュメントをご覧ください。

Document AI に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


from google.api_core.client_options import ClientOptions
from google.cloud import documentai  # type: ignore

# TODO(developer): Uncomment these variables before running the sample.
# project_id = 'YOUR_PROJECT_ID'
# location = 'YOUR_PROCESSOR_LOCATION' # Format is 'us' or 'eu'
# processor_id = 'YOUR_PROCESSOR_ID' # Create processor before running sample
# processor_version_id = 'YOUR_PROCESSOR_VERSION_ID'


def list_evaluations_sample(
    project_id: str, location: str, processor_id: str, processor_version_id: str
) -> None:
    # You must set the api_endpoint if you use a location other than 'us', e.g.:
    opts = ClientOptions(api_endpoint=f"{location}-documentai.googleapis.com")

    client = documentai.DocumentProcessorServiceClient(client_options=opts)

    # The full resource name of the processor version
    # e.g. `projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}`
    parent = client.processor_version_path(
        project_id, location, processor_id, processor_version_id
    )

    evaluations = client.list_evaluations(parent=parent)

    # Print the Evaluation Information
    # Refer to https://cloud.google.com/document-ai/docs/reference/rest/v1beta3/projects.locations.processors.processorVersions.evaluations
    # for more information on the available evaluation data
    print(f"Evaluations for Processor Version {parent}")

    for evaluation in evaluations:
        print(f"Name: {evaluation.name}")
        print(f"\tCreate Time: {evaluation.create_time}\n")

すべてのラベルの評価指標

evaluate-the-performance-of-processors-1

[All labels] の指標は、データセット内のすべてのラベルの真陽性、偽陽性、偽陰性の数に基づいて計算されるため、各ラベルがデータセットに表示される回数で重み付けされます。これらの用語の定義については、個々のラベルの評価指標をご覧ください。

  • 適合率: テストセットのアノテーションと一致する予測の割合。True Positives / (True Positives + False Positives) として定義

  • 再現率: テストセット内のアノテーションのうち、正しく予測されたものの割合。True Positives / (True Positives + False Negatives) として定義

  • F1 スコア: 適合率と再現率の調和平均。適合率と再現率を 1 つの指標にまとめ、両方に同じ重みを付けます。2 * (Precision * Recall) / (Precision + Recall) として定義

個々のラベルの評価指標

evaluate-the-performance-of-processors-2

  • 真陽性: テスト ドキュメントのアノテーションと一致する予測エンティティ。詳細については、一致の動作をご覧ください。

  • 偽陽性: テスト ドキュメント内のアノテーションと一致しない予測エンティティ。

  • 偽陰性(False Negatives): 予測されたエンティティのいずれとも一致しないテスト ドキュメント内のアノテーション。

    • 偽陰性(しきい値を下回る): 予測エンティティと一致するはずだったテスト ドキュメント内のアノテーション。ただし、予測エンティティの信頼値が指定された信頼しきい値を下回っています。

信頼度のしきい値

評価ロジックでは、予測が正しくても、指定された信頼度のしきい値を下回る信頼度の予測は無視されます。Document AI は、信頼度のしきい値を低く設定した場合に一致するアノテーションである偽陰性(しきい値以下)のリストを提供します。

Document AI は、F1 スコアを最大化する最適なしきい値を自動的に計算し、デフォルトで信頼度のしきい値をこの最適値に設定します。

スライダー バーを動かして、信頼度のしきい値を自由に選択できます。一般に、信頼度のしきい値が高いほど、次のようになります。

  • 予測が正しくなる可能性が高いため、適合率が高くなります。
  • 予測数が少ないため、再現率が低くなります。

表形式のエンティティ

親ラベルの指標は、子指標を直接平均して計算されるのではなく、親の信頼度しきい値をすべての子ラベルに適用し、結果を集計して計算されます。

親の最適なしきい値は、すべての子に適用したときに親の F1 スコアが最大になる信頼度のしきい値です。

一致の動作

予測されたエンティティは、次の条件を満たす場合にアノテーションと一致します。

照合に使用されるのは、型とテキスト値のみです。テキスト アンカーやバウンディング ボックスなどの他の情報(後述の表形式のエンティティを除く)は使用されません。

単一発生ラベルと複数発生ラベル

単一出現ラベルには、同じドキュメント内でその値が複数回アノテーションされている場合でも(たとえば、同じドキュメントのすべてのページに請求書 ID が表示されている場合)、ドキュメントごとに 1 つの値(請求書 ID など)があります。複数のアノテーションのテキストが異なっていても、それらは同じとみなされます。つまり、予測されたエンティティがアノテーションのいずれかに一致する場合、一致と見なされます。追加のアノテーションは重複する言及と見なされ、真陽性、偽陽性、偽陰性のいずれのカウントにも寄与しません。

複数回出現するラベルには、複数の異なる値を指定できます。したがって、予測された各エンティティとアノテーションは個別に考慮され、照合されます。ドキュメントに複数回出現するラベルのアノテーションが N 個含まれている場合、予測されたエンティティと N 個の一致が存在する可能性があります。予測された各エンティティとアノテーションは、真陽性、偽陽性、偽陰性として個別にカウントされます。

ファジー一致

[ファジー マッチング] 切り替えを使用すると、一部のマッチング ルールを厳しくしたり緩くしたりして、一致する数を減らしたり増やしたりできます。

たとえば、ファジー マッチングを使用しない場合、大文字と小文字が異なるため、文字列 ABCabc と一致しません。ファジー一致を使用すると、一致します。

ファジー一致が有効になっている場合、ルールは次のように変更されます。

  • 空白の正規化: 先頭と末尾の空白を削除し、連続する中間空白(改行を含む)を単一のスペースに圧縮します。

  • 先頭と末尾の句読点の削除: 先頭と末尾の句読点文字 !,.:;-"?| を削除します。

  • 大文字と小文字を区別しない照合: すべての文字を小文字に変換します。

  • 金額の正規化: データ型が money のラベルの場合、先頭と末尾の通貨記号を削除します。

表形式のエンティティ

親エンティティとアノテーションにはテキスト値がなく、子エンティティの結合されたバウンディング ボックスに基づいて照合されます。予測された親が 1 つで、アノテーション付きの親が 1 つしかない場合、バウンディング ボックスに関係なく、それらは自動的に照合されます。

保護者が一致すると、お子様は表形式以外のエンティティとして一致します。親が一致しない場合、Document AI は子を照合しようとしません。つまり、親エンティティが一致しない場合、テキスト コンテンツが同じでも、子エンティティは正しくないと見なされます。

親エンティティと子エンティティはプレビュー機能であり、1 つのネストレイヤを持つテーブルでのみサポートされています。

評価指標をエクスポートする

  1. Google Cloud コンソールで、[プロセッサ] ページに移動して、プロセッサを選択します。

    [プロセッサ] ページに移動

  2. [評価とテスト] タブで、[指標をダウンロード] をクリックして、評価指標を JSON ファイルとしてダウンロードします。