此页面由 Cloud Translation API 翻译。

创建数据集

必须使用加标签的文档数据集才能训练、追加训练或评估处理器版本。

本页介绍了如何创建数据集、导入文档以及定义架构。如需为导入的文档添加标签，请参阅为文档添加标签。

本页面假定您已创建支持训练、追加训练或评估的处理器。如果您的处理器受支持，您会在 Google Cloud 控制台中看到模块序列标签页。

数据集存储选项

您可以从以下两种方式中选择一种来保存数据集：

由 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 文件夹。

如果您的 Cloud Storage 位于其他 Google Cloud 项目中，请务必授予访问权限，以便 Document AI 能够从该位置读取文件。具体而言，您必须向 Document AI 的核心服务代理 service-{project-id}@gcp-sa-prod-dai-core.iam.gserviceaccount.com 授予 Storage Object Viewer 角色。如需了解详情，请参阅服务代理。

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% 应由 2020 年的 W2 文档组成。这样的测试集组成可确保在评估处理器性能时，为每种文档子类型分配适当的重要性。此外，如果您要从国际表单中提取人名，请确保您的测试集包含来自所有目标国家/地区的表单。

训练集的最佳实践

任何已包含在测试集中的文档都不应包含在训练集中。

与测试集不同，最终训练集在文档多样性或频率方面不必严格代表客户使用情况。有些标签比其他标签更难训练。因此，您可以通过将训练集偏向这些标签来获得更好的效果。

一开始，我们还没有找到很好的方法来确定哪些标签比较难。您应先使用与测试集中所述相同的方法，从一组小型随机抽样的初始训练集开始。此初始训练集应包含您计划注释的文件总数的大约 10%。然后，您可以迭代评估处理器质量（查找特定错误模式）并添加更多训练数据。

定义处理器架构

创建数据集后，您可以在导入文档之前或之后定义处理器架构。

处理器的 schema 定义了要从文档中提取的标签（例如姓名和地址）。

选择修改架构，然后根据需要创建、修改、启用和停用标签。

完成后，请务必选择保存。

create-dataset-10

关于架构标签管理的注意事项：

架构标签一经创建，便无法修改其名称。
只有在没有训练好的处理器版本时，才能修改或删除架构标签。您只能修改数据类型和出现类型。
停用标签也不会影响预测。当您发送处理请求时，处理器版本会提取训练时有效的所有标签。

获取数据架构

此示例展示了如何使用 dataset.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 更新当前架构。此示例展示了用于将数据集架构更新为包含一个标签的命令。如果您想添加新标签，而不是删除或更新现有标签，则可以先调用 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。

如果实体应具有一个值（即使同一文档中出现相同的值多次），请选择 ONCE。如果实体预计有多个值，请选择 MULTIPLE。

父级标签和子标签

父子标签（也称为表格实体）用于为表格中的数据添加标签。下表包含 3 行 4 列。

create-dataset-11

您可以使用父子标签定义此类表。在此示例中，父标签 line-item 定义了表格中的一行。

创建父级标签

在修改架构页面上，选择创建标签。
选中这是父级标签复选框，然后输入其他信息。父标签必须包含 optional_multiple 或 require_multiple，以便重复使用以捕获表格中的所有行。
选择保存。

create-dataset-12

父级标签会显示在修改架构页面上，旁边会显示添加子标签选项。

创建子标签

在修改架构页面上，选择父标签旁边的添加子标签。
输入子标签的信息。
选择保存。

对您要添加的每个子标签重复此操作。

子标签会在修改架构页面上的父标签下方显示缩进。

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/

标签流程