使用非结构化数据的数据剖析

由 Vertex AI Gemini 2.5 Pro 模型提供支持的非结构化数据 (UnstructuredDataProfileSpec) 的数据分析扫描功能可分析现有的 BigQuery 对象表，将 Cloud Storage 中的原始非结构化文件（例如 PDF）转换为可查询的结构化资产。此独立工作流专为已拥有 BigQuery 对象表的用户设计，支持通过自定义提示指导提取。如果您要从 Cloud Storage 中的原始文件入手，并希望使用自动化发现工作流，请参阅使用发现扫描来发现非结构化数据。

本文档介绍了如何设置必要的权限、准备对象表、使用 REST API 为非结构化数据创建数据分析扫描、查看生成的数据洞见、整理图谱配置文件，以及将数据提取到 BigQuery 中。

准备工作

在为非结构化数据创建数据剖析扫描之前，请确保您拥有所需的权限并已启用相应的 API。

启用 API

在项目中启用以下 API：

• dataplex.googleapis.com
• bigquery.googleapis.com
• aiplatform.googleapis.com (Vertex AI)

启用 API

所需的角色和权限

非结构化数据语义推理是一项高级数据分析扫描功能，适用于 BigQuery 对象表。如需配置和运行非结构化数据分析，您必须满足访问对象表的基本权限，并向多个服务代理授予额外的角色以进行语义推理。

基准对象表角色

如需访问和查询 BigQuery 对象表，请确保您和知识目录使用的服务账号在项目上具有以下基本 Identity and Access Management (IAM) 角色：

• BigQuery Data Viewer (roles/bigquery.dataViewer)
• BigQuery Connection User (roles/bigquery.connectionUser)

如需查看对象表的前提条件的完整列表，请参阅创建对象表。

用于语义推理的其他角色

除了基准表访问权限之外，还要确保您和服务账号拥有以下额外的 IAM 角色。

最终用户角色和权限

如需确保您的用户账号具有创建扫描、查看数据洞见、整理图谱配置文件和提取数据所需的权限，请让您的管理员为您的用户账号授予项目的以下 IAM 角色：

• 创建扫描并查看数据洞见：
  • Dataplex DataScan Editor (roles/dataplex.dataScanEditor)
  • Dataplex Catalog Editor (roles/dataplex.catalogEditor)
• 使用 SQL 或流水线提取数据：
  • BigQuery Data Editor (roles/bigquery.dataEditor)
  • BigQuery Job User (roles/bigquery.jobUser)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色可提供创建扫描、查看数据分析、整理图谱个人资料和提取数据所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您的管理员也可以使用自定义角色或其他预定义角色为用户账号授予这些权限。

Dataplex 发现服务代理角色和权限

Dataplex 发现服务代理是一种服务代理，需要访问权限才能使用 Vertex AI 运行扫描和执行语义推理。

如需确保 Dataplex 发现服务代理（通常为 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）拥有使用 Vertex AI 运行扫描和执行语义推理所需的权限，请让您的管理员为项目中的 Dataplex 发现服务代理（通常为 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）授予以下 IAM 角色：

• 全部：
  • Agent Platform User (roles/aiplatform.user)
  • Dataplex Discovery Service Agent (roles/dataplex.discoveryServiceAgent)
  • BigQuery Job User (roles/bigquery.jobUser)
  • BigQuery Data Viewer (roles/bigquery.dataViewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含使用 Vertex AI 运行扫描和执行语义推理所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您的管理员也可以使用自定义角色或其他预定义角色为 Dataplex 发现服务代理（通常为 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com）授予这些权限。

BigQuery 连接服务账号角色和权限

通过 BigQuery Cloud 资源连接，Knowledge Catalog 可以访问存储在 Cloud Storage 中的非结构化数据。创建连接时，BigQuery 会自动代表您创建一个专用服务账号。此服务账号充当用于连接到外部数据源的身份。

默认情况下，此服务账号不具备任何权限。您必须明确向此服务账号授予包含数据的 Cloud Storage 存储分区的所需 IAM 角色。您可以使用现有的 BigQuery 连接，也可以在与源 Cloud Storage 存储桶相同的位置创建新的连接。如需详细了解如何共享连接，请参阅与用户共享连接。

如需确保 BigQuery 连接服务账号（从连接详情的连接信息部分检索 ID）拥有读取对象表和运行推理所需的权限，请让您的管理员为 BigQuery 连接服务账号（从连接详情的连接信息部分检索 ID）授予以下 IAM 角色：

• 全部：
  • 针对包含非结构化数据的存储桶的 Storage Object Viewer (roles/storage.objectViewer)
  • 项目的 Agent Platform User (roles/aiplatform.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含读取对象表和运行推理所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您的管理员也可以使用自定义角色或其他预定义角色为 BigQuery 连接服务账号（从连接详情的连接信息部分检索 ID）授予这些权限。

流水线执行服务账号角色和权限（可选）

如果您选择使用自动化流水线提取推断出的数据，则必须创建或提供专用服务账号来运行该流水线。此执行服务账号充当在 BigQuery 中验证身份并运行后台数据提取和分析任务的身份。此外，您还必须向默认 Dataform 服务账号授予模拟此执行服务账号的权限。

为确保流水线执行服务账号具有使用流水线提取推理出的实体和关系所需的权限，请让您的管理员为项目中的流水线执行服务账号授予以下 IAM 角色：

• 全部：
  • BigQuery Data Editor (roles/bigquery.dataEditor)
  • BigQuery Job User (roles/bigquery.jobUser)
  • BigQuery User (roles/bigquery.user)
  • Agent Platform User (roles/aiplatform.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含使用流水线提取推理出的实体和关系所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您的管理员也可以使用自定义角色或其他预定义角色为流水线执行服务账号授予这些权限。

为确保默认 Dataform 服务账号 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) 具有模拟流水线执行服务账号的必要权限，请让您的管理员为流水线执行服务账号上的默认 Dataform 服务账号 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) 授予以下 IAM 角色：

• 所有用户： Service Account Token Creator (roles/iam.serviceAccountTokenCreator)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

这些预定义角色包含模拟流水线执行服务账号所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您的管理员也可以使用自定义角色或其他预定义角色为默认 Dataform 服务账号 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) 授予这些权限。

准备对象表

非结构化数据的数据分析扫描直接在现有的 BigQuery 对象表上运行。在创建扫描作业之前，请确保您的非结构化数据（例如 PDF）存储在 Cloud Storage 存储桶中，并且您已使用 Cloud 资源连接在该存储桶上创建了相应的 BigQuery 对象表。

确保您和知识目录服务账号对对象表所用的连接拥有 BigQuery Connection User (roles/bigquery.connectionUser) 角色。

如需详细了解如何创建对象表和设置所需的连接，请参阅创建对象表。

为非结构化数据创建数据分析扫描

如需从对象表中提取语义数据洞见，您必须为非结构化数据 (UnstructuredDataProfileSpec) 创建数据分析扫描作业。此扫描作业会使用 Vertex AI Gemini 2.5 Pro 模型来分析对象表引用的非结构化文件，并生成推断的元数据、架构和关系。

在此初始版本中，仅支持使用 REST API 创建扫描。

如需使用 REST API 为非结构化数据创建数据分析扫描，请使用 dataScans.create 方法并提供 unstructuredDataProfileSpec。

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?dataScanId=DATASCAN
{
  "description": "Data profile scan for unstructured data",
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": {
      "onDemand": {}
    }
  },
  "unstructuredDataProfileSpec": {
    "customizedPrompt": "",
    "graphProfilePublishingEnabled": false
  }
}

替换以下内容：

• PROJECT_ID：您的 Google Cloud项目的 ID。
• LOCATION： Google Cloud 地区（必须支持 Gemini 2.5 Pro）。
• DATASCAN：数据分析扫描的名称。
• DATASET_ID 和 TABLE_ID：BigQuery 数据集和对象表名称。

数据分析扫描规范参数

• customizedPrompt：可选。自然语言提示，用于指示 Gemini 要提取的特定实体或网域上下文（例如 Focus extraction on M&A contract terms, identifying purchasing entities, target companies, and agreed escrow amounts.）。默认情况下，此属性为空字符串 ("")。自定义提示的字符长度上限有限制。

• graphProfilePublishingEnabled：可选。是否在扫描完成后自动将推断出的图谱配置文件发布到目录。默认情况下，此值为 false。

Knowledge Catalog 会运行数据分析扫描，并使用 AI 生成的元数据丰富目录条目。对于标准数据集，此过程通常需要几分钟的时间。

示例：从卖家 PDF 文件中提取合同条款

以下示例展示了某零售公司创建数据分析扫描 (seller-contracts-scan) 以分析存储在对象表 (seller_agreements_obj_table) 中的卖家协议 PDF 的 REST API 请求。该请求使用自定义提示来指示 Gemini 提取特定的业务术语，例如佣金率和付款条件：

POST https://dataplex.googleapis.com/v1/projects/example-retail-project/locations/us-central1/dataScans?dataScanId=seller-contracts-scan
{
  "description": "Data profile scan for seller PDF agreements",
  "data": {
    "resource": "//bigquery.googleapis.com/projects/example-retail-project/datasets/marketplace_operations/tables/seller_agreements_obj_table"
  },
  "executionSpec": {
    "trigger": {
      "onDemand": {}
    }
  },
  "unstructuredDataProfileSpec": {
    "customizedPrompt": "Focus extraction on seller agreement terms, identifying seller business entities, commission rates, payment terms, and termination clauses in the PDFs.",
    "graphProfilePublishingEnabled": true
  }
}

运行数据分析扫描

如果您将数据分析扫描配置为按需运行，则必须手动触发扫描才能分析非结构化数据。

如需使用 REST API 运行按需数据分析扫描，请使用 dataScans.run 方法：

curl -X POST \
-H