GSP925

概览

Document AI API 是一种文档理解解决方案，可以提取文档、电子邮件等非结构化数据，从而让用户更容易理解、分析和使用这些数据。

在本实验中，您将通过 Python 来调用 Document AI API，以便创建包括通用表单处理器和 Document OCR 处理器在内的各种处理器，然后使用 Python 对该 API 进行同步和异步调用。本实验为您创建了一个 Vertex AI Workbench 实例。您将通过此实例和 JupyterLab 笔记本，用 Document AI Python 客户端模块执行操作。

目标

在本实验中，您将学习如何完成以下操作：

• 启用 Document AI API 并创建处理器。
• 在 Vertex AI Workbench 实例中安装 Python 客户端库。
• 使用 Python 解析所扫描的表单中的数据，以进行同步 API 调用。
• 使用 Python 解析所扫描的表单中的数据，以进行异步 API 调用。

设置和要求

点击“开始实验”按钮前的注意事项

请阅读以下说明。实验是计时的，并且您无法暂停实验。计时器在您点击开始实验后即开始计时，显示 Google Cloud 资源可供您使用多长时间。

此实操实验可让您在真实的云环境中开展实验活动，免受模拟或演示环境的局限。为此，我们会向您提供新的临时凭据，您可以在该实验的规定时间内通过此凭据登录和访问 Google Cloud。

为完成此实验，您需要：

• 能够使用标准的互联网浏览器（建议使用 Chrome 浏览器）。

注意：请使用无痕模式（推荐）或无痕浏览器窗口运行此实验。这可以避免您的个人账号与学生账号之间发生冲突，这种冲突可能导致您的个人账号产生额外费用。

• 完成实验的时间 - 请注意，实验开始后无法暂停。

注意：请仅使用学生账号完成本实验。如果您使用其他 Google Cloud 账号，则可能会向该账号收取费用。

激活 Cloud Shell

Cloud Shell 是一种装有开发者工具的虚拟机。它提供了一个永久性的 5GB 主目录，并且在 Google Cloud 上运行。Cloud Shell 提供可用于访问您的 Google Cloud 资源的命令行工具。

1. 点击 Google Cloud 控制台顶部的激活 Cloud Shell 。

2. 在弹出的窗口中执行以下操作：

   • 继续完成 Cloud Shell 信息窗口中的设置。
   • 授权 Cloud Shell 使用您的凭据进行 Google Cloud API 调用。

如果您连接成功，即表示您已通过身份验证，且项目 ID 会被设为您的 Project_ID 。输出内容中有一行说明了此会话的 Project_ID：

Your Cloud Platform project in this session is set to {{{project_0.project_id | "PROJECT_ID"}}}

gcloud 是 Google Cloud 的命令行工具。它已预先安装在 Cloud Shell 上，且支持 Tab 自动补全功能。

3. （可选）您可以通过此命令列出活跃账号名称：

gcloud auth list

4. 点击授权。

输出：

ACTIVE: * ACCOUNT: {{{user_0.username | "ACCOUNT"}}} To set the active account, run: $ gcloud config set account `ACCOUNT`

5. （可选）您可以通过此命令列出项目 ID：

gcloud config list project

输出：

[core] project = {{{project_0.project_id | "PROJECT_ID"}}} 注意：如需查看在 Google Cloud 中使用 gcloud 的完整文档，请参阅 gcloud CLI 概览指南。

任务 1. 创建并测试通用表单处理器

在此任务中您将启用 Document AI API，并创建和测试通用表单处理器。通用表单处理器可处理各种类型的文档并提取文档中所有可识别的文本内容。除了打印的文本，它还可以处理手写的和沿任意方向排列的文本，并支持多种语言，理解表单数据元素之间的关联，因此可以帮助您从包含文本标签的表单字段中提取键值对。

启用 Cloud Document AI API

您必须先启用 Cloud Document AI API，然后才能开始使用 Document AI。

1. 在 Cloud 控制台的导航菜单 () 中，点击 API 和 服务 > 库。

2. 搜索 Cloud Document AI API，然后点击启用按钮，以便在 Google Cloud 项目中使用该 API。

如果 Cloud Document AI API 已启用，将会出现管理按钮，您可以继续进行实验。

检查 Cloud Document AI API 是否已启用。

创建通用表单处理器

使用 Document AI 表单解析器创建 Document AI 处理器。

1. 在控制台的导航菜单 () 中，点击 Document AI > 概览。

2. 点击浏览处理器，然后点击创建处理器并选择表单解析器 - 这是一种通用处理器。

3. 将处理器的名称指定为 form-parser，并从地区列表中选择 US（美国）。

4. 点击创建，创建通用的 form-parser 处理器。

此操作将创建该处理器并返回处理器详情页面。页面中将显示处理器 ID、状态和预测端点。

5. 请记下处理器 ID，因为在后续任务中，您需要使用该处理器 ID 来替换 JupyterLab 笔记本中相应的变量值。

任务 2. 配置 Vertex AI Workbench 实例以执行 Document AI API 调用

实验开始时为您创建了 Vertex AI Workbench 实例，JupyterLab 需要利用此实例来运行。接下来，您需要将此实例连接到 JupyterLab，然后为剩余实验任务配置环境。

1. 在 Google Cloud 控制台的导航菜单 () 中依次点击 Vertex AI > Workbench。

2. 找到 实例，然后点击打开 JupyterLab 按钮。

Workbench 实例的 JupyterLab 界面会在新浏览器标签页中打开。

注意：如果您在 JupyterLab 中没有看到笔记本，请按照以下额外步骤重置实例：

1. 关闭 JupyterLab 的浏览器标签页，然后返回 Workbench 首页。

2. 选中实例名称旁边的复选框，然后点击重置。

3. 打开 JupyterLab 按钮重新启用后，请等待一分钟，然后点击打开 JupyterLab。

3. 点击终端，打开 Vertex AI Workbench 实例中的终端 shell。

4. 在终端 shell 中输入以下命令，将实验文件导入 Vertex AI Workbench 实例：

gsutil cp {{{project_0.startup_script.notebook_files_path|notebook_files_path}}} .

5. 在终端 shell 中输入以下命令，安装 Document AI 所需的 Python 客户端库和其他必需库：

python -m pip install --upgrade google-cloud-core google-cloud-documentai google-cloud-storage prettytable

您会看到输出消息，指示库已成功安装。

注意：发生与权限有关的错误时，请重新运行上述命令，确保成功安装库。相关权限可能需要几分钟才能生效。

6. 在终端 shell 中输入以下命令，导入示例健康登记表：

gsutil cp {{{project_0.startup_script.health_intake_form_path|form_path}}} form.pdf

7. 在笔记本界面中打开 JupyterLab 笔记本（名为 ）。

8. 在选择内核对话框中，从可用内核列表中选择 Python 3。

检查 Vertex AI 实例是否已经准备好进行 Document AI API 同步调用。

任务 3. 请求同步处理文档

同步调用 Document AI API 来处理文档。一次性处理大量文档时，您还可以使用后续任务中将会用到的异步 API 调用。

查看同步调用 Document AI API 的 Python 代码

请花点时间查看 笔记本中的 Python 代码。

第一个代码块会导入必需库并初始化某些变量。

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage from prettytable import PrettyTable project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' file_path = 'form.pdf'

设置处理器 ID 代码单元用于设置处理器 ID。开始使用笔记本处理文档前，您必须手动设置处理器 ID。

processor_id = 'PROCESSOR_ID' # 待处理：替换为有效的处理器 ID

在这一步，您需要提供在任务 1 中创建的处理器的 Document AI 处理器 ID。

提示：如果您之前没有保存此 ID，可以在“Cloud 控制台”标签页中打开导航菜单 ()，点击 Document AI > 我的处理器，然后点击您的处理器名称，打开详情页面。您可以在该页面上复制处理器 ID。

文档处理函数代码单元定义了用于进行 Document AI 处理器同步调用的 process_document 函数。此函数会创建 Document AI API 客户端对象。

该 API 调用所需的处理器名称使用 project_id、locations 和 processor_id 参数来创建，而示例 PDF 文档则以 mime_type 结构进行读取和存储。

此函数会创建一个包含文档处理器全称的请求对象，并以该对象为参数来同步调用 Document AI API 客户端。如果请求成功，返回的文档对象将包含一些属性，这些属性则包含在表单中检测到的实体。

def process_document( project_id=project_id, location=location, processor_id=processor_id, file_path=file_path ): # 实例化客户端 client = documentai.DocumentProcessorServiceClient() # 处理器的完整资源名称，例如： # projects/project-id/locations/location/processor/processor-id # 您必须先在 Cloud 控制台上创建新处理器 name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" with open(file_path, "rb") as image: image_content = image.read() # 将文件读入内存 document = {"content": image_content, "mime_type": "application/pdf"} # 配置处理请求 request = {"name": name, "document": document} # 使用 Document AI 客户端处理示例表单 result = client.process_document(request=request) return result.document

文档处理代码单元会调用 process_document 函数，并将响应结果保存在 document 变量中，然后输出检测到的原始文本。所有处理器都会报告 document.text 属性的某些数据。

document=process_document() # 输出所有检测到的文本。 # 所有文档处理器都会显示文本内容 print("Document processing complete.") print("Text: {}".format(document.text))

获取文本函数代码单元用于定义 get_text() 函数，此函数使用指定元素的 text_segments 中的 text_anchor、start_index 和 end_index 属性来检索该元素的文本。若处理器返回表单数据，可使用此函数来检索表单名称和表单值。

def get_text(doc_element: dict, document: dict): """ Document AI 通过文档中文本的偏移值来 识别表单字段。此函数将偏移值转换为 文本片段。 """ response = "" # 如果一个文本段有几行，则会将其 # 存储为不同的文本段。 for segment in doc_element.text_anchor.text_segments: start_index = ( int(segment.start_index) if segment in doc_element.text_anchor.text_segments else 0 ) end_index = int(segment.end_index) response += document.text[start_index:end_index] return response

显示表单数据单元用于迭代所有检测到的页面，并使用 get_text() 函数检索每个检测到的 form_field 的字段名称和字段值。然后输出这些值及其相应的置信度分数。使用通用表单解析器或专业解析器的处理器可返回表单数据，而使用 Document OCR 解析器创建的处理器不会返回表单数据。

document_pages = document.pages print("Form data detected:\n") # 针对各页面提取每个表单字段并显示字段名称、值和置信度分数 for page in document_pages: print("Page Number:{}".format(page.page_number)) for form_field in page.form_fields: fieldName=get_text(form_field.field_name,document) nameConfidence = round(form_field.field_name.confidence,4) fieldValue = get_text(form_field.field_value,document) valueConfidence = round(form_field.field_value.confidence,4) print(fieldName+fieldValue +" (Confidence Scores: (Name) "+str(nameConfidence)+", (Value) "+str(valueConfidence)+")\n")

显示实体数据单元用于从文档对象中提取实体数据，并显示每个检测到的实体的类型、值和置信度属性。只有使用“采购费用”解析器等专业 Document AI 解析器的处理器可返回实体数据。通用表单解析器和 Document OCR 解析器不会返回实体数据。

if 'entities' in dir(document): entities = document.entities # 获取各键值对及其置信度分数。 table = PrettyTable(['Type', 'Value', 'Confidence']) for entity in entities: entity_type = entity.type_ value = entity.mention_text confience = round(entity.confidence,4) table.add_row([entity_type, value, confience]) print(table) else: print("Document does not contain entity data.")

任务 4. 运行同步调用 Document AI API 的 Python 代码

在 JupyterLab 笔记本中执行代码，同步调用 Document AI API。

1. 在第二个设置处理器 ID 代码单元中，请使用您在此前步骤中创建的 form-parser 处理器的 ID 来替换 PROCESSOR_ID 占位符文本。

2. 选择第一个单元，点击运行菜单，然后点击运行所选单元及其下方全部单元，以便运行笔记本中的所有代码。

如果使用了示例健康登记表单，您将在表单数据的输出单元中看到类似如下的数据：

Form data detected: Page Number:1 Phone #: (906) 917-3486 (Confidence Scores: (Name) 1.0, (Value) 1.0) ... Date: 9/14/19 (Confidence Scores: (Name) 0.9999, (Value) 0.9999) ... Name: Sally Walker (Confidence Scores: (Name) 0.9973, (Value) 0.9973) ...

如果您能创建专业处理器，最后一个单元就会显示实体数据，否则会显示一个空表。

3. 在 JupyterLab 菜单中点击文件，然后点击保存笔记本来保存进度。

检查是否已通过同步调用 Cloud Document AI API 来处理文档。

任务 5. 创建 Document AI Document OCR 处理器

在此任务中，您将使用通用 Document OCR 解析器来创建 Document AI 处理器。

1. 在导航菜单中，依次点击 Document AI > 概览。

2. 点击浏览处理器，然后点击创建处理器并选择 Document OCR。这是一种通用处理器。

3. 将处理器的名称指定为 ocr-processor 并从地区列表中选择 US（美国）。

4. 点击创建以创建处理器。

5. 记下处理器 ID。您在后续任务中将需要指定此 ID。

任务 6. 为异步调用 Document AI API 准备环境

在此任务中，您将上传示例 JupyterLab 笔记本，以便测试 Document AI API 异步调用，您还会将部分实验示例表单复制到 Cloud Storage 来进行异步处理。

1. 点击终端标签页，重新打开 Vertex AI Workbench 实例中的终端 shell。

2. 创建输入文档的 Cloud Storage 存储桶，并将示例 W2 表单复制到存储桶：

export PROJECT_ID="$(gcloud config get-value core/project)" export BUCKET="${PROJECT_ID}"_doc_ai_async gsutil mb gs://${BUCKET} gsutil -m cp {{{project_0.startup_script.async_files_path|async_files_path}}} gs://${BUCKET}/input

3. 在笔记本界面中打开 JupyterLab 笔记本（名为 ）。

4. 在选择内核对话框中，从可用内核列表中选择 Python 3。

检查 Vertex AI 实例是否已准备好进行 Document AI API 异步调用。

任务 7. 请求异步处理文档

查看用于异步调用 Document AI API 的 Python 代码

请花点时间查看 笔记本中的 Python 代码。

第一个代码单元会导入必需库。

from google.cloud import documentai_v1beta3 as documentai from google.cloud import storage import re import os import pandas as pd import simplejson as json

设置处理器 ID 代码单元用于设置处理器 ID。开始使用笔记本处理文档前，您必须手动设置处理器 ID。

processor_id = "PROCESSOR_ID" # 待处理：替换为有效的处理器 ID

设置变量代码单元用于定义进行异步调用的参数，包括用于存储源数据的 Cloud Storage 输入存储桶和用于存储输出文件的 Cloud Storage 输出存储桶的位置。在本实验的下一个部分，您需要在运行代码前替换掉此单元中的占位值 PROJECT_ID 和 PROCESSOR_ID。处理器位置、Cloud Storage 输入存储桶和输出存储桶等其他变量包含默认值，无需更改。

project_id = %system gcloud config get-value core/project project_id = project_id[0] location = 'us' # 如果处理器使用的位置不是 'us'，就替换为 'eu' gcs_input_bucket = project_id+"_doc_ai_async" # 只需提供存储桶名称，无需 gs:// 前缀 gcs_input_prefix = "input/" # 输入存储桶文件夹，例如 input/ gcs_output_bucket = project_id+"_doc_ai_async" # 只需提供存储桶名称，无需 gs:// 前缀 gcs_output_prefix = "output/" # 输出存储桶文件夹，例如 output/ timeout = 300

定义 Google Cloud 客户端对象代码单元会初始化 Document AI 和 Cloud Storage 客户端。

client_options = {"api_endpoint": "{}-documentai.googleapis.com".format(location)} client = documentai.DocumentProcessorServiceClient(client_options=client_options) storage_client = storage.Client()

创建输入配置代码单元将为源数据创建输入配置数组参数，这些参数将作为输入配置传递到异步 Document AI 请求。此数组会存储 Cloud Storage 输入位置上每个文件的 Cloud Storage 来源位置和 MIME 类型。

blobs = storage_client.list_blobs(gcs_input_bucket, prefix=gcs_input_prefix) input_configs = [] print("Input Files:") for blob in blobs: if ".pdf" in blob.name: source = "gs://{bucket}/{name}".format(bucket = gcs_input_bucket, name = blob.name) print(source) input_config = documentai.types.document_processor_service.BatchProcessRequest.BatchInputConfig( gcs_source=source, mime_type="application/pdf" ) input_configs.append(input_config)

创建输出配置代码单元用于为异步调用请求创建包含 Cloud Storage 输出存储桶位置的输出参数，并将其存储为 Document AI 批量输出配置。

destination_uri = f"gs://{gcs_output_bucket}/{gcs_output_prefix}" output_config = documentai.types.document_processor_service.BatchProcessRequest.BatchOutputConfig( gcs_destination=destination_uri )

创建 Document AI API 请求代码单元使用输入配置和输出配置对象构建 Document AI 异步调用批处理请求对象。

name = f"projects/{project_id}/locations/{location}/processors/{processor_id}" request = documentai.types.document_processor_service.BatchProcessRequest( name=name, input_configs=input_configs, output_config=output_config, )

开始批量（异步）API 调用操作代码单元会将请求对象传递到 batch_process_documents() 方法，以便请求异步处理文档。这是一种异步调用，您需要使用 result() 方法，强制让笔记本等待后台异步作业执行完成。

operation = client.batch_process_documents(request) # 等待操作完成 operation.result(timeout=timeout) print ("Batch process completed.")

提取输出文件列表单元会枚举 destination_uri 变量中定义的输出存储桶位置的对象。

显示异步输出 JSON 文件中检测到的文本单元会加载每个识别为 Document AI 文档对象的 JSON 输出文件，并输出 Document OCR 处理器检测到的文本数据。

显示实体数据单元将显示找到的所有实体数据。但只有使用专业解析器创建的处理器才能获得实体数据。此任务中使用的通用 Document AI OCR 解析器不会显示实体数据。

运行异步调用 Document AI API 的 Python 代码

使用 Jupyterlab 笔记本中为您提供的示例代码，通过 Document AI 批处理请求异步处理文档。

1. 在第二个代码单元中，将 PROCESSOR_ID 占位符文本替换为您在先前步骤中创建的 form-parser 处理器的 ID。

2. 选择第一个单元，点击运行菜单，然后点击运行所选单元及其下方全部单元，以便运行笔记本中的所有代码。

3. 执行代码单元时，您可以逐步浏览笔记本，查看代码及详细介绍如何创建和使用异步请求对象的注释。

笔记本将等待开始批量（异步）API 调用操作代码单元完成异步批处理操作，这个过程需要一两分钟。当批处理 API 调用本身就是异步调用时，笔记本会使用 result 方法，以便强制让笔记本等待异步调用完成，然后再枚举和显示输出数据。

如果异步作业的完成时间超过预期并导致超时，您必须再次运行其余单元，才能显示输出数据。其余单元是指开始批量（异步）API 调用操作单元后面的单元。

输出将包含文本内容，其中会列出在每个文件中检测到的 Document AI 数据。Document OCR 解析器无法检测表单或实体数据，因此不会生成表单或实体数据。如果您能创建专业处理器，就可以查看最后一个单元输出的实体数据。

4. 在 JupyterLab 菜单中点击文件，然后点击保存笔记本来保存进度。

Document processing complete. Text: FakeDoc M.D. HEALTH INTAKE FORM Please fill out the questionnaire carefully. The information you provide will be used to complete your health profile and will be kept confidential. Date: Sally Walker Name: 9/14/19 ... 检查是否已通过异步调用 Cloud Document AI API 来处理文档。

恭喜

您已成功完成 Document AI API 的同步和异步调用。在本实验中，您启用了 Document AI API 并创建了处理器。您在 Vertex AI Workbench 实例中安装了 Python 客户端库，还使用 Python 分别进行了同步 API 调用和异步 API 调用，从而解析了扫描表单中的数据。

后续步骤/了解详情

• 请查阅此指南，详细了解如何使用 Document AI API。

Google Cloud 培训和认证

…可帮助您充分利用 Google Cloud 技术。我们的课程会讲解各项技能与最佳实践，可帮助您迅速上手使用并继续学习更深入的知识。我们提供从基础到高级的全方位培训，并有点播、直播和虚拟三种方式选择，让您可以按照自己的日程安排学习时间。各项认证可以帮助您核实并证明您在 Google Cloud 技术方面的技能与专业知识。

上次更新手册的时间：2025 年 1 月 17 日

上次测试实验的时间：2025 年 1 月 17 日

版权所有 2025 Google LLC 保留所有权利。Google 和 Google 徽标是 Google LLC 的商标。其他所有公司名和产品名可能是其各自相关公司的商标。