评估效果

Document AI 会生成评估指标（例如精确率和召回率），以帮助您确定处理器的预测性能。

这些评估指标是通过将处理器返回的实体（预测）与测试文档中的注释进行比较生成的。如果您的处理器没有测试集，则必须先创建数据集并为测试文档添加标签。

运行评估

当您训练或增量训练处理器版本时，系统会自动运行评估。

您也可以手动运行评估。在修改测试集后或评估预训练的处理器版本时，必须执行此操作才能生成更新后的指标。

注意 ：如果处理器版本无法提取该标签（例如，该标签在训练时处于停用状态），或者测试集不包含该标签的注释，Document AI 将无法计算该标签的评估指标，也不会计算。此类标签不会纳入汇总指标中。

网页界面

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}")

获取评估结果

网页界面

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")

所有标签的评估指标

所有标签的指标是根据数据集中所有标签的真正例、假正例和假负例数量计算得出的，因此会按每个标签在数据集中出现的次数进行加权。如需了解这些术语的定义，请参阅各个标签的评估指标。

• 精确率：与测试集中的注释匹配的预测所占的比例。定义为 True Positives / (True Positives + False Positives)

• 召回率：测试集中正确预测的注释所占的比例。定义为 True Positives / (True Positives + False Negatives)

• F1 得分：精确率和召回率的调和平均数，可将精确率和召回率合并为单个指标，并为二者提供同等权重。定义为 2 * (Precision * Recall) / (Precision + Recall)

注意 ：Document AI 不提供准确性指标。准确率指标（通常定义为正确预测的实例所占的比例）的意义不大，因为：1) 并非所有标签都会出现在测试集中（例如，可选字段）；2) 单个标签可能有多个值（例如，账单中的订单项）。另一方面，F1 可以被视为与准确率大致相当，但它更适合这些场景。

个别标签的评估指标

• 真正例：与测试文档中的注释匹配的预测实体。如需了解详情，请参阅匹配行为。

• 假正例：与测试文档中的任何注释都不匹配的预测实体。

• 假负例：测试文档中的注释与任何预测实体都不匹配。

  • 漏报（低于阈值）：测试文档中的注释本应与预测实体匹配，但预测实体的置信度值低于指定的置信度阈值。

注意： 假正例和假负例并不互斥。例如，如果某个预测实体在测试集中有对应的注释（尽管不正确），则该预测实体会出现 1 个假正例，而注释会出现 1 个假负例。没有注释的预测实体只是误报。没有关联预测的注释只是假负例。

提示： 如果 checkbox 提取质量不够高，不妨考虑通过表单解析器运行文档。表单解析器会提取可能有助于提高复选框提取质量的信息。具体而言，表单解析器可以自动在复选框周围绘制边界框，而手动绘制的边界框可能不太一致。为此，请使用表单解析器处理文档，然后导入已处理的文档并再次为其添加注释。

置信度阈值

评估逻辑会忽略置信度低于指定置信度阈值的所有预测，即使预测正确也是如此。Document AI 会提供假负例（低于阈值）列表，其中包含如果将置信度阈值设置得更低，则会匹配的注释。

Document AI 会自动计算最佳阈值，以最大限度地提高 F1 得分，并默认将置信度阈值设置为此最佳值。

注意： 如果有多个最佳阈值（具有相同的最大 F1 得分），系统会选择最低的值。

您可以通过移动滑块自由选择自己的置信度阈值。一般来说，置信度阈值越高，会导致以下结果：

• 精确率更高，因为预测结果更有可能正确。
• 召回率较低，因为预测结果较少。

表格实体

父级标签的指标并非通过直接对子级标签的指标求平均值来计算，而是通过将父级标签的置信度阈值应用于其所有子级标签并汇总结果来计算。

父级的最佳阈值是指当应用于所有子级时，可为父级带来最高 F1 得分的置信度阈值值。

匹配行为

预测的实体与注释匹配，如果：

• 预测实体的类型 (entity.type) 与注释的标签名称匹配
• 预测实体的值（entity.mention_text 或 entity.normalized_value.text）与注释的文本值匹配，但须遵循模糊匹配（如果启用）。

请注意，系统仅使用类型和文本值进行匹配。系统不会使用其他信息，例如文本锚点和边界框（下文所述的表格实体除外）。

注意 ：某些身份证件处理器会提取肖像实体，该实体不包含任何文本，只有一个边界框，用于指明身份证件中肖像的位置。由于缺少文本，系统不会评估纵向标签和实体。

单次出现标签与多次出现标签

单次出现的标签在每个文档中只有一个值（例如账单 ID），即使该值在同一文档中被注释多次也是如此（例如，账单 ID 出现在同一文档的每个页面中）。即使多个注释包含不同的文本，也会被视为等同。换句话说，如果预测的实体与任何注释匹配，则计为匹配。额外的注释会被视为重复提及，不会计入真正例、假正例或假负例的计数。

多重出现标签可以有多个不同的值。因此，系统会单独考虑和匹配每个预测实体和注释。如果文档包含多重出现标签的 N 个注释，则可以与预测的实体有 N 个匹配。每个预测实体和注释都会单独计为真正例、假正例或假负例。

模糊匹配

通过模糊匹配切换开关，您可以收紧或放宽某些匹配规则，以减少或增加匹配项的数量。

例如，如果不启用模糊匹配，字符串 ABC 将因大小写而与 abc 不匹配。但使用模糊匹配功能时，它们是匹配的。

启用模糊匹配后，规则会发生以下更改：

• 空格规范化：移除前导和尾随空格，并将连续的中间空格（包括换行符）压缩为单个空格。

• 移除前导/尾随标点符号：移除以下前导/尾随标点符号 !,.:;-"?|。

• 不区分大小写的匹配：将所有字符转换为小写。

• 货币标准化：对于数据类型为 money 的标签，请移除前导和尾随货币符号。

注意： 您无法对数字值使用模糊匹配。例如，1 和 1.00 不匹配，即使启用了模糊匹配也是如此。

表格实体

父实体和注释没有文本值，并且会根据其子项的组合边界框进行匹配。如果只有一个预测的父项和一个注释的父项，则无论边界框如何，它们都会自动匹配。

匹配父级后，系统会像匹配非表格实体一样匹配其子级。如果父级文本不匹配，Document AI 不会尝试匹配其子文本。这意味着，如果子实体的父实体不匹配，即使其文本内容相同，也可能会被视为不正确。

父 / 子实体是一项预览版功能，仅适用于嵌套层级为 1 的表格。

导出评估指标

1. 在 Google Cloud 控制台中，前往处理器页面，然后选择您的处理器。

   前往“处理器”页面

2. 在评估和测试标签页中，点击下载指标，以将评估指标下载为 JSON 文件。

注意 ：导出的指标取决于导出时置信度阈值滑块的值。