使用 ML.PROCESS_DOCUMENT 函数处理文档

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

支持的位置

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

所需的角色

如需创建远程模型并处理文档，您需要在项目级拥有以下 Identity and Access Management (IAM) 角色：

创建文档处理器：Document AI Editor (roles/documentai.editor)
创建和使用 BigQuery 数据集、表和模型：BigQuery Data Editor (roles/bigquery.dataEditor)
创建、委托和使用 BigQuery 连接：BigQuery Connections Admin (roles/bigquery.connectionsAdmin)

如果您尚未配置默认连接，则可以在运行 CREATE MODEL 语句时创建并设置一个连接。为此，您必须拥有项目的 BigQuery Admin (roles/bigquery.admin) 角色。如需了解详情，请参阅配置默认连接。
向连接的服务账号授予权限：Project IAM Admin (roles/resourcemanager.projectIamAdmin)
创建 BigQuery 作业：BigQuery Job User (roles/bigquery.jobUser)

这些预定义角色包含执行本文档中的任务所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

创建数据集：bigquery.datasets.create
创建、委托和使用连接：bigquery.connections.*
设置服务账号权限：resourcemanager.projects.getIamPolicy 和 resourcemanager.projects.setIamPolicy
创建模型并运行推断：
- bigquery.jobs.create
- bigquery.models.create
- bigquery.models.getData
- bigquery.models.updateData
- bigquery.models.updateMetadata
创建对象表：bigquery.tables.create 和 bigquery.tables.update
创建文档处理器：
- documentai.processors.create
- documentai.processors.update
- documentai.processors.delete

您也可以使用自定义角色或其他预定义角色来获取这些权限。

准备工作

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.
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
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection API, and Document AI APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.
Enable the APIs

创建处理器

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

创建数据集

您必须在同一区域中创建数据集、连接和文档处理器。

创建 BigQuery 数据集以包含您的资源：

控制台

在 Google Cloud 控制台中，前往 BigQuery 页面。

转到 BigQuery
在左侧窗格中，点击 探索器：

如果您没有看到左侧窗格，请点击 展开左侧窗格以打开该窗格。
在探索器窗格中，点击您的项目名称。
点击 查看操作 > 创建数据集。
在 创建数据集 页面上，执行以下操作：
1. 在数据集 ID 中，输入数据集的名称。
2. 在位置类型部分，选择区域或多区域。
  - 如果您选择了区域，请从区域列表中选择一个位置。
  - 如果您选择了多区域，请从多区域列表中选择美国或欧洲。
3. 点击创建数据集。

bq

如需创建新数据集，请使用带有 --location 标志的 bq mk 命令：
```
bq --location=LOCATION mk -d DATASET_ID
```
替换以下内容：
- LOCATION：数据集的位置。
- DATASET_ID 是您要创建的数据集的 ID。
确认已创建数据集：
```
bq ls
```

创建连接

创建 Cloud 资源连接并获取连接的服务账号。在与上一步中创建的数据集相同的位置创建连接。

如果您已配置默认连接，或者您具有 BigQuery Admin 角色，则可以跳过此步骤。

控制台

前往 BigQuery 页面。

转到 BigQuery
在左侧窗格中，点击 探索器：

如果您没有看到左侧窗格，请点击 展开左侧窗格以打开该窗格。
在探索器窗格中，展开您的项目名称，然后点击连接。
在连接页面上，点击创建连接。
对于连接类型，请选择 Vertex AI 远程模型、远程函数、BigLake 和 Spanner（Cloud 资源）。
在连接 ID 字段中，输入连接的名称。
对于位置类型，为连接选择一个位置。连接应与数据集等其他资源位于同一位置。
点击创建连接。
点击转到连接。
在连接信息窗格中，复制服务账号 ID 以在后续步骤中使用。

bq

在命令行环境中，创建连接：
```
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...
```

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

bq show --connection PROJECT_ID.REGION.CONNECTION_ID

输出类似于以下内容：

name                          properties
1234.REGION.CONNECTION_ID     {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel."}

Python

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Python 设置说明进行操作。如需了解详情，请参阅 BigQuery Python API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

import google.api_core.exceptions
from google.cloud import bigquery_connection_v1

client = bigquery_connection_v1.ConnectionServiceClient()


def create_connection(
    project_id: str,
    location: str,
    connection_id: str,
):
    """Creates a BigQuery connection to a Cloud Resource.

    Cloud Resource connection creates a service account which can then be
    granted access to other Google Cloud resources for federated queries.

    Args:
        project_id: The Google Cloud project ID.
        location: The location of the connection (for example, "us-central1").
        connection_id: The ID of the connection to create.
    """

    parent = client.common_location_path(project_id, location)

    connection = bigquery_connection_v1.Connection(
        friendly_name="Example Connection",
        description="A sample connection for a Cloud Resource.",
        cloud_resource=bigquery_connection_v1.CloudResourceProperties(),
    )

    try:
        created_connection = client.create_connection(
            parent=parent, connection_id=connection_id, connection=connection
        )
        print(f"Successfully created connection: {created_connection.name}")
        print(f"Friendly name: {created_connection.friendly_name}")
        print(
            f"Service Account: {created_connection.cloud_resource.service_account_id}"
        )

    except google.api_core.exceptions.AlreadyExists:
        print(f"Connection with ID '{connection_id}' already exists.")
        print("Please use a different connection ID.")
    except Exception as e:
        print(f"An unexpected error occurred while creating the connection: {e}")

Node.js

试用此示例之前，请按照 BigQuery 快速入门：使用客户端库中的 Node.js 设置说明进行操作。如需了解详情，请参阅 BigQuery Node.js API 参考文档。

如需向 BigQuery 进行身份验证，请设置应用默认凭证。如需了解详情，请参阅为客户端库设置身份验证。

const {ConnectionServiceClient} =
  require('@google-cloud/bigquery-connection').v1;
const {status} = require('@grpc/grpc-js');

const client = new ConnectionServiceClient();

/**
 * Creates a new BigQuery connection to a Cloud Resource.
 *
 * A Cloud Resource connection creates a service account that can be granted access
 * to other Google Cloud resources.
 *
 * @param {string} projectId The Google Cloud project ID. for example, 'example-project-id'
 * @param {string} location The location of the project to create the connection in. for example, 'us-central1'
 * @param {string} connectionId The ID of the connection to create. for example, 'example-connection-id'
 */
async function createConnection(projectId, location, connectionId) {
  const parent = client.locationPath(projectId, location);

  const connection = {
    friendlyName: 'Example Connection',
    description: 'A sample connection for a Cloud Resource',
    // The service account for this cloudResource will be created by the API.
    // Its ID will be available in the response.
    cloudResource: {},
  };

  const request = {
    parent,
    connectionId,
    connection,
  };

  try {
    const [response] = await client.createConnection(request);

    console.log(`Successfully created connection: ${response.name}`);
    console.log(`Friendly name: ${response.friendlyName}`);

    console.log(`Service Account: ${response.cloudResource.serviceAccountId}`);
  } catch (err) {
    if (err.code === status.ALREADY_EXISTS) {
      console.log(`Connection '${connectionId}' already exists.`);
    } else {
      console.error(`Error creating connection: ${err.message}`);
    }
  }
}

Terraform

使用 google_bigquery_connection 资源。

如需向 BigQuery 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为客户端库设置身份验证。

以下示例在 US 区域中创建一个名为 my_cloud_resource_connection 的 Cloud 资源连接：


# This queries the provider for project information.
data "google_project" "default" {}

# This creates a cloud resource connection in the US region named my_cloud_resource_connection.
# Note: The cloud resource nested object has only one output field - serviceAccountId.
resource "google_bigquery_connection" "default" {
  connection_id = "my_cloud_resource_connection"
  project       = data.google_project.default.project_id
  location      = "US"
  cloud_resource {}
}

如需在 Google Cloud 项目中应用 Terraform 配置，请完成以下部分中的步骤。

准备 Cloud Shell

启动 Cloud Shell。
设置要应用 Terraform 配置的默认 Google Cloud 项目。

您只需为每个项目运行一次以下命令，即可在任何目录中运行它。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 配置文件中设置显式值，则环境变量会被替换。

准备目录

每个 Terraform 配置文件都必须有自己的目录（也称为“根模块”）。

在 Cloud Shell 中，创建一个目录，并在该目录中创建一个新文件。文件名必须具有 .tf 扩展名，例如 main.tf。在本教程中，该文件称为 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您按照教程进行操作，可以在每个部分或步骤中复制示例代码。

将示例代码复制到新创建的 main.tf 中。

（可选）从 GitHub 中复制代码。如果端到端解决方案包含 Terraform 代码段，则建议这样做。
查看和修改要应用到您的环境的示例参数。
保存更改。
初始化 Terraform。您只需为每个目录执行一次此操作。
```
terraform init
```
（可选）如需使用最新的 Google 提供程序版本，请添加 -upgrade 选项：
```
terraform init -upgrade
```

应用更改

查看配置并验证 Terraform 将创建或更新的资源是否符合您的预期：
```
terraform plan
```
根据需要更正配置。
通过运行以下命令并在提示符处输入 yes 来应用 Terraform 配置：
```
terraform apply
```
等待 Terraform 显示“应用完成！”消息。
打开您的 Google Cloud 项目以查看结果。在 Google Cloud 控制台的界面中找到资源，以确保 Terraform 已创建或更新它们。

向服务账号授予访问权限

从下列选项中选择一项：

控制台

前往 IAM 和管理页面。

转到“IAM 和管理”
点击 授予访问权限。

系统随即会打开添加主账号对话框。
在新的主账号字段中，输入您之前复制的服务账号 ID。
在选择����段中，选择 Document AI，然后选择 Document AI Viewer。
点击添加其他角色。
在选择角色字段中，选择 Cloud Storage，然后选择 Storage Object Viewer。
点击保存。

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_AI_DOCUMENT_V1 这一 REMOTE_SERVICE_TYPE 创建远程模型：

CREATE OR REPLACE MODEL
`PROJECT_ID.DATASET_ID.MODEL_NAME`
REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`}
OPTIONS (
  REMOTE_SERVICE_TYPE = 'CLOUD_AI_DOCUMENT_V1',
  DOCUMENT_PROCESSOR = 'PROCESSOR_ID'
);

替换以下内容：

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。
PROCESSOR_ID：文档处理器 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`
  [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')]
);

请替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：模型的名称。
OBJECT_TABLE_NAME：包含要处理的文档 URI 的对象表的名称。
PROCESS_OPTIONS：用于指定如何处理文档的 JSON 配置。例如，您可以使用此参数为布局解析器指定文档分块

或者，使用 ML.PROCESS_DOCUMENT 处理部分文档：

SELECT *
FROM ML.PROCESS_DOCUMENT(
  MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`,
  (SELECT *
  FROM `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME`
  WHERE FILTERS
  LIMIT NUM_DOCUMENTS
  )
  [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')]
);

请替换以下内容：

PROJECT_ID：您的项目 ID。
DATASET_ID：包含该模型的数据集的 ID。
MODEL_NAME：模型的名称。
OBJECT_TABLE_NAME：包含要处理的文档 URI 的对象表的名称。
FILTERS：用于过滤掉您要在对象表列中处理的文档的条件。
NUM_DOCUMENTS：您要处理的文档数上限。
PROCESS_OPTIONS：用于定义配置的 JSON 配置，例如布局解析器的分块配置

示例

示例 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`,
    (SELECT * FROM `myproject.mydataset.expense_reports`
    WHERE uri LIKE '%restaurant%'));

后续步骤

如需详细了解 BigQuery ML 中的模型推理，请参阅模型推理概览。
如需详细了解如何使用 Cloud AI API 执行 AI 任务，请参阅 AI 应用概览。
如需详细了解生成式 AI 模型支持的 SQL 语句和函数，请参阅生成式 AI 模型的端到端用户体验历程。