使用 ML.PROCESS_DOCUMENT 函数处理文档

预览

本产品或功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 正式发布前产品和功能“按原样”提供，可能仅提供有限支持。 如需了解详情，请参阅发布阶段说明。

注意：如需就此功能提供反馈或请求支持，请发送电子邮件至 [e-mail]。

本文档介绍了如何将 ML.PROCESS_DOCUMENT 函数与远程模型搭配使用，以从对象表中的文档内提取有用的分析洞见。

支持的位置

您必须在 US 或 EU 多区域中创建此过程中使用的远程模型。您必须在远程模型所在的区域中运行 ML.PROCESS_DOCUMENT 函数。

所需权限

• 如需创建 Document AI 处理器，您需要以下角色：

  • roles/documentai.editor

• 如需创建连接，您需要拥有以下角色的成员资格：

  • roles/bigquery.connectionAdmin

• 如需使用 BigQuery ML 创建模型，您需要以下权限：

  • bigquery.jobs.create
  • bigquery.models.create
  • bigquery.models.getData
  • bigquery.models.updateData
  • bigquery.models.updateMetadata

• 如需运行推理，您需要以下权限：

  • 对象表的 bigquery.tables.getData 权限
  • 模型的 bigquery.models.getData 权限
  • bigquery.jobs.create

准备工作

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

   Enable the APIs

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the BigQuery, BigQuery Connection API, and Document AI APIs.

   Enable the APIs

创建处理器

在 Document AI 中创建处理器以处理文档。处理器必须是受支持的类型。

创建连接

创建 Cloud 资源连接并获取连接的服务账号。

从下列选项中选择一项：

控制台

1. 转到 BigQuery 页面。

   转到 BigQuery

2. 如需创建连接，请点击 添加，然后点击与外部数据源的连接。

3. 在连接类型列表中，选择 Vertex AI 远程模型、远程函数和 BigLake（Cloud 资源）。

4. 在连接 ID 字段中，输入连接的名称。

5. 点击创建连接。

6. 点击转到连接。

7. 在连接信息窗格中，复制服务账号 ID 以在后续步骤中使用。

bq

1. 在命令行环境中，创建连接：

   bq mk --connection --location=REGION --project_id=PROJECT_ID \
       --connection_type=CLOUD_RESOURCE CONNECTION_ID
   

   --project_id 参数会替换默认项目。

   替换以下内容：

   • REGION：您的连接区域
   • PROJECT_ID：您的 Google Cloud 项目 ID
   • CONNECTION_ID：您的连接的 ID

   当您创建连接资源时，BigQuery 会创建一个唯一的系统服务账号，并将其与该连接相关联。

   问题排查：如果您收到以下连接错误，请更新 Google Cloud SDK：

   Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
   

2. 检索并复制服务账号 ID 以在后续步骤中使用：

   bq show --connection PROJECT_ID.REGION.CONNECTION_ID
   

   输出类似于以下内容：

   name                          properties
   1234.REGION.CONNECTION_ID     {"serviceAccountId": "[e-mail]"}
   

Terraform

将以下部分附加到 main.tf 文件中。

 ## This creates a cloud resource connection.
 ## Note: The cloud resource nested object has only one output only field - serviceAccountId.
 resource "google_bigquery_connection" "connection" {
    connection_id = "CONNECTION_ID"
    project = "PROJECT_ID"
    location = "REGION"
    cloud_resource {}
}        

替换以下内容：

• CONNECTION_ID：您的连接的 ID
• PROJECT_ID：您的 Google Cloud 项目 ID
• REGION：您的连接区域

向服务账号授予访问权限

从下列选项中选择一项：

控制台

1. 前往 IAM 和管理页面。

   转到“IAM 和管理”

2. 点击 授予访问权限。

   系统随即会打开添加主账号对话框。

3. 在新的主账号字段中，输入您之前复制的服务账号 ID。

4. 在选择角色字段中，选择 Document AI，然后选择 Document AI Viewer。

5. 点击添加其他角色。

6. 在选择角色字段中，选择 Cloud Storage，然后选择 Storage Object Viewer。

7. 点击保存。

gcloud

使用 gcloud projects add-iam-policy-binding 命令：

gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/documentai.viewer' --condition=None
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None

替换以下内容：

• PROJECT_NUMBER：您的项目编号。
• MEMBER：您之前复制的服务账号 ID。

未能授予权限会导致 Permission denied 错误。

注意：如果您在与对象表使用的 Cloud Storage 存储桶不同的项目中创建处理器，请向服务账号授予 Identity and Access Management (IAM) 角色，如下所示：

• 在包含处理器的项目中向服务账号授予 Document AI Viewer 角色。
• 在包含 Cloud Storage 存储桶的项目中，向服务账号授予 Storage Object Viewer 角色。

创建数据集

创建数据集以包含模型和对象表。

创建模型

使用 CLOUD_AI_DOCUMENT_V1 这一 REMOTE_SERVICE_TYPE 创建远程模型：

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
OPTIONS (
  REMOTE_SERVICE_TYPE = 'CLOUD_AI_DOCUMENT_V1',
  DOCUMENT_PROCESSOR = 'projects/PROJECT_NUMBER/locations/LOCATION/processors/PROCESSOR_ID/processorVersions/PROCESSOR_VERSION'
);

替换以下内容：

• PROJECT_ID：您的项目 ID。
• DATASET_ID：包含模型的数据集的 ID。
• MODEL_NAME：模型的名称。
• REGION：连接使用的区域。
• CONNECTION_ID：连接 ID，例如 myconnection。

  当您在 Google Cloud 控制台中查看连接详情时，连接 ID 是连接 ID 中显示的完全限定连接 ID 的最后一部分中的值，例如 projects/myproject/locations/connection_location/connections/myconnection。

• PROJECT_NUMBER：包含文档处理器的项目的编号。如需查找此值，请查看处理器详情，查看预测端点，并获取 projects 元素后面的值，例如： https://us-documentai.googleapis.com/v1/projects/project_number/locations/processor_location/processors/processor_id:process。
• LOCATION：文档处理器使用的位置。如需查找此值，请查看处理器详情，查看预测端点，并获取 locations 元素后面的值，例如： https://us-documentai.googleapis.com/v1/projects/project_number/locations/processor_location/processors/processor_id:process。
• PROCESSOR_ID：文档处理器 ID。如需查找此值，请查看处理器详情，查看预测端点，并获取 processors 元素后面的值，例如： https://us-documentai.googleapis.com/v1/projects/project_number/locations/processor_location/processors/processor_id:process。
• PROCESSOR_VERSION：文档处理器版本。如需查找此值，请查看处理器详情，选择管理版本标签页，然后复制要使用的版本的版本 ID 值。

重要提示：即使连接位于默认项目中，您也必须指定连接的项目 ID。

如需查看模型输出列，请在创建模型后点击查询结果中的转到模型。输出列显示在架构标签页的标签部分中。

创建对象表

针对 Cloud Storage 中的一组文档创建对象表。对象表中的文档必须是受支持的类型。

处理文档

使用 ML.PROCESS_DOCUMENT 函数处理文档：

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  TABLE `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
);

替换以下内容：

• PROJECT_ID：您的项目 ID。
• DATASET_ID：包含该模型的数据集的 ID。
• MODEL_NAME：模型的名称。
• OBJECT_TABLE_NAME：包含要处理的文档 URI 的对象表的名称。

示例

示例 1

以下示例使用费用解析器来处理由 documents 表表示的文档：

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `myproject.mydataset.expense_parser`,
  TABLE `myproject.mydataset.documents`
);

此查询返回已解析的费用报告，包括费用报告上的货币、总金额、收据日期和专列项。ml_process_document_result 列包含费用解析器的原始输出，ml_process_document_status 列包含文档处理返回的所有错误。

示例 2

以下示例展示了如何过滤对象表以选择要处理的文档，然后将结果写入表：

CREATE TABLE `myproject.mydataset.expense_details`
AS
SELECT uri, content_type, receipt_date, purchase_time, total_amount, currency
FROM
  ML.PROCESS_DOCUMENT(
    MODEL `myproject.mydataset.expense_parser`, TABLE `myproject.mydataset.expense_reports`)
WHERE uri LIKE '%restaurant%';

后续步骤

• 如需了解 BigQuery ML 中的模型推理，请参阅模型推理概览。
• 如需了解每种模型类型支持的 SQL 语句和函数，请参阅每个模型的端到端用户体验历程。