由 Vertex AI Gemini 2.5 Pro 模型提供支持的非结构化数据的数据分析扫描 (UnstructuredDataProfileSpec) 会分析现有的 BigQuery 对象表,将 Cloud Storage 中的原始非结构化文件(例如 PDF)转换为可查询的结构化资产。此独立工作流专为已拥有 BigQuery 对象表的用户设计,支持通过自定义提示指导提取。如果您从 Cloud Storage 中的原始文件开始,并希望使用自动化发现工作流,请参阅使用发现扫描来处理非结构化数据。
本文档介绍了如何设置必要的权限、准备对象表、使用 REST API 为非结构化数据创建数据分析扫描、查看生成的数据洞见、整理图谱配置文件,以及将数据提取到 BigQuery 中。
准备工作
在为非结构化数据创建数据剖析扫描之前,请确保您拥有所需的权限并已启用相应的 API。
启用 API
在项目中启用以下 API:
dataplex.googleapis.combigquery.googleapis.comaiplatform.googleapis.com(Vertex AI)
启用 API 所需的角色
如需启用 API,您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin),该角色包含 serviceusage.services.enable 权限。了解如何授予角色。
所需的角色和权限
非结构化数据语义推理是一项高级数据分析扫描功能,适用于 BigQuery 对象表。如需配置和运行非结构化数据分析,您必须满足访问对象表的基本权限,并授予其他角色,以便在多个服务代理之间进行语义推理。
基准对象表角色
如需访问和查询 BigQuery 对象表,请确保您和 Knowledge Catalog 使用的服务账号在项目上具有以下基本 Identity and Access Management (IAM) 角色:
- BigQuery Data Viewer (
roles/bigquery.dataViewer) - BigQuery Connection User (
roles/bigquery.connectionUser)
如需查看对象表的前提条件的完整列表,请参阅创建对象表。
用于语义推理的其他角色
除了基准表访问权限之外,还要确保您和服务账号拥有以下额外的 IAM 角色。
其他身份和角色的摘要
| 身份类型 | 典型的主账号格式 | 所需 IAM 角色 | 核心用途 |
|---|---|---|---|
| 最终用户 | 您的 Google Cloud 用户账号 |
|
您可以使用这些额外的角色来配置扫描、查看 AI 生成的结果、整理图谱分析文件,以及触发最终的数据提取。 |
| Dataplex Universal Catalog 发现代理 | service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com |
|
此 Google 代管式服务代理使用这些额外的角色来调用 Vertex AI,以生成推断的架构和元数据。 |
| BigQuery 连接服务账号 | 与您的连接相关联的唯一身份(例如 bqcx-<var>PROJECT_NUMBER</var>-<var>ID</var>@gcp-sa-bigquery-condel.iam.gserviceaccount.com) |
|
它将 BigQuery 连接到外部存储空间,使 BigQuery 能够读取原始文件、创建对象表并运行 AI 推理,而不会泄露您的个人用户凭据。 |
| 流水线执行服务账号(可选) | 用户代管式服务账号 |
|
如果您选择使用自动化流水线提取数据,此身份将运行后台作业,以将 AI 生成的实体具体化到 BigQuery 表中。 |
| 默认的 Dataform 服务账号(可选) | service-<var>PROJECT_NUMBER</var>@gcp-sa-dataform.iam.gserviceaccount.com |
|
使用流水线提取方法时,Dataform 需要获得模拟流水线执行服务账号的权限才能编排工作流。 |
最终用户角色和权限
<如需确保您的用户账号具有创建扫描、查看数据洞见、整理图谱配置文件和提取数据所需的权限,请让您的管理员为您的用户账号授予项目的以下 IAM 角色:
-
创建扫描并查看数据洞见:
- Dataplex DataScan Editor (
roles/dataplex.dataScanEditor) - Dataplex Catalog Editor (
roles/dataplex.catalogEditor)
- Dataplex DataScan Editor (
-
使用 SQL 或流水线提取数据:
- BigQuery Data Editor (
roles/bigquery.dataEditor) - BigQuery Job User (
roles/bigquery.jobUser)
- BigQuery Data Editor (
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色可提供创建扫描、查看数据分析、整理图谱个人资料和提取数据所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需创建扫描、查看分析洞见、整理图谱配置文件和提取数据,需要具备以下权限:
-
DataScans:
-
dataplex.datascans.create -
dataplex.datascans.get -
dataplex.datascans.getData -
dataplex.datascans.list -
dataplex.datascans.update
-
-
数据提取:
-
bigquery.tables.create -
bigquery.tables.update -
bigquery.tables.getData -
bigquery.jobs.create
-
您的管理员也可以使用自定义角色或其他预定义角色为用户账号授予这些权限。
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 角色:
- 全部:
- Vertex AI 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 User (
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含使用 Vertex AI 运行扫描和执行语义推理所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需使用 Vertex AI 运行扫描和执行语义推理,需要具备以下权限:
- 全部:
-
aiplatform.endpoints.predict -
bigquery.datasets.create -
bigquery.datasets.get -
bigquery.tables.get -
bigquery.tables.getData -
storage.buckets.get -
storage.objects.get -
storage.objects.list
-
您的管理员也可以使用自定义角色或其他预定义角色为 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) - Vertex AI User (
roles/aiplatform.user) 对项目具有
- 针对包含非结构化数据的存储桶的 Storage Object Viewer (
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含读取对象表和运行推理所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
您需要具备以下权限才能读取对象表和运行推理:
- 全部:
- 针对包含非结构化数据的存储桶的
storage.buckets.get - 针对包含非结构化数据的存储桶的
storage.objects.get - 针对项目的
aiplatform.endpoints.predict权限
- 针对包含非结构化数据的存储桶的
您的管理员也可以使用自定义角色或其他预定义角色为 BigQuery 连接服务账号(从连接详情的连接信息部分检索 ID)授予这些权限。
流水线执行服务账号角色和权限(可选)
如果您选择使用自动化流水线提取推断出的数据,则必须创建或提供专用服务账号来运行该流水线。此执行服务账号充当在 BigQuery 中验证身份并运行后台数据提取和分析任务的身份。此外,您还必须向默认 Dataform 服务账号授予模拟此执行服务账号的权限。
为确保流水线执行服务账号具有使用流水线提取推理出的实体和关系所需的权限,请让您的管理员为项目中的流水线执行服务账号授予以下 IAM 角色:
- 全部:
- BigQuery Data Editor (
roles/bigquery.dataEditor) - BigQuery Job User (
roles/bigquery.jobUser) - BigQuery User (
roles/bigquery.user) - Vertex AI User (
roles/aiplatform.user)
- BigQuery Data Editor (
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含使用流水线提取推理出的实体和关系所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
您需要具备以下权限才能使用流水线提取推理出的实体和关系:
- 全部:
-
bigquery.tables.create -
bigquery.tables.update -
bigquery.tables.get -
bigquery.tables.getData -
bigquery.jobs.create -
aiplatform.endpoints.predict
-
您的管理员也可以使用自定义角色或其他预定义角色为流水线执行服务账号授予这些权限。
为确保默认 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)
如需详细了解如何授予角色,请参阅管理对项目、文件夹和组织的访问权限。
这些预定义角色包含模拟流水线执行服务账号所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
如需模拟流水线执行服务账号,您需要具有以下权限:
-
全部:
iam.serviceAccounts.getAccessToken
您的管理员也可以使用自定义角色或其他预定义角色为默认 Dataform 服务账号 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com) 授予这些权限。
准备对象表
非结构化数据的数据分析扫描直接在现有的 BigQuery 对象表上运行。在创建扫描作业之前,请确保您的非结构化数据(例如 PDF)存储在 Cloud Storage 存储桶中,并且您已使用 Cloud 资源连接在该存储桶上创建了相应的 BigQuery 对象表。
确保您和 Knowledge Catalog 服务账号对对象表所用的连接拥有 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 "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN:run"
替换以下内容:
PROJECT_ID:您的 Google Cloud项目的 ID。LOCATION:数据分析扫描所在的 Google Cloud 区域。DATASCAN:数据分析扫描的名称。
探索数据分析扫描结果
数据分析扫描完成后,Knowledge Catalog 会生成一个图谱配置文件,其中包含实体和关系的相关推断架构。您可以使用 Google Cloud 控制台或 REST API 探索这些结果。
控制台
如果您已启用将图谱配置文件发布到目录 (graphProfilePublishingEnabled: true),则可以在 Knowledge Catalog 中查看对象表及其推理出的语义图谱:
在 Google Cloud 控制台中,前往 Knowledge Catalog 搜索页面。
粘贴并搜索您在扫描中配置了 ID 的对象表。
在搜索结果中,点击相应表格以打开其条目页面。
在详细信息标签页的方面下,验证是否存在图谱配置文件方面 (
dataplex-types.global.graph-profile)。此方面包含实体和关系的推断架构。点击数据分析标签页。在数据分析标签页上,您可以查看以下信息:
语义提取。系统会显示一个横幅,指示已检测到可提取的实体和关系。该横幅包含一个提取按钮,用于使用 SQL 或流水线部署来实现数据。
说明。AI 生成的人类可读摘要用于说明非结构化数据的内容。它描述了发现的主要节点(实体),以及它们如何通过边(关系)相互关联。
流水线。与此资源关联的之前部署的数据提取流水线的列表。您可以查看显示名称、区域、创建时间和创建流水线的用户。
推理出的实体和关系。直观的互动式图表会显示非结构化数据的发现语义结构。该图表包含表示不同实体的节点(例如
Recipe和Ingredient)以及表示实体之间连接的边(例如HasAllergenStatus)。您可以使用图例来过滤和探索特定节点和边。实体。发现的主要实体的详细列表。您可以展开每个实体,查看其 AI 生成的说明和推理出的架构,其中包括字段名称、数据类型和字段说明。
关系:实体之间发现的连接的详细列表。您可以展开每种关系,查看其说明以及定义实体之间如何相互映射的架构。
REST
如需使用 REST API 直接从扫描作业执行中检索图谱分析结果,请使用 dataScans.jobs.get 方法和 view=full:
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN/jobs/JOB_ID?view=full"
替换以下内容:
PROJECT_ID:您的 Google Cloud项目的 ID。LOCATION:数据分析扫描所在的 Google Cloud 区域。DATASCAN:数据分析扫描的名称。JOB_ID:数据分析扫描作业执行的唯一 ID。
以下示例展示了 seller-contracts-scan 作业的响应,包括 unstructuredDataProfileResult 和 graphProfile:
{
"name": "projects/example-retail-project/locations/us-central1/dataScans/seller-contracts-scan/jobs/123e4567-e89b-12d3-a456-426614174000",
"uid": "123e4567-e89b-12d3-a456-426614174000",
"startTime": "2026-06-08T19:12:03.102Z",
"endTime": "2026-06-08T19:15:28.415Z",
"state": "SUCCEEDED",
"type": "DATA_SCAN_TYPE_UNSTRUCTURED_DATA_PROFILE",
"unstructuredDataProfileSpec": {
"customizedPrompt": "Focus extraction on seller agreement terms, identifying seller business entities, commission rates, payment terms, and termination clauses in the PDFs.",
"graphProfilePublishingEnabled": true
},
"unstructuredDataProfileResult": {
"description": "The unstructured data contains seller agreement PDFs. The primary entities discovered are Seller Entity, Commission Rate, Payment Terms, and Termination Clause, mapped to each other through business agreement relationships.",
"graphProfile": {
"nodeTypes": [
{
"name": "Seller Entity",
"description": "Discovered business entity representing the seller.",
"fields": [
{
"name": "seller_name",
"dataType": "STRING",
"description": "The legal name of the seller.",
"mode": "NULLABLE"
},
{
"name": "address",
"dataType": "STRING",
"description": "The physical or mailing address of the seller.",
"mode": "NULLABLE"
}
]
},
{
"name": "Commission Rate",
"description": "Discovered agreed commission rate terms.",
"fields": [
{
"name": "rate_percentage",
"dataType": "NUMBER",
"description": "The agreed commission percentage.",
"mode": "NULLABLE"
}
]
},
{
"name": "Payment Terms",
"description": "Discovered payment schedule and terms.",
"fields": [
{
"name": "billing_cycle",
"dataType": "STRING",
"description": "The agreed billing frequency or payment schedule.",
"mode": "NULLABLE"
}
]
}
],
"edgeTypes": [
{
"name": "AgreedCommission",
"description": "Defines the commission rate agreed by the seller entity.",
"sourceNodeType": "Seller Entity",
"targetNodeType": "Commission Rate"
},
{
"name": "HasPaymentTerms",
"description": "Defines the payment terms applicable to the seller entity.",
"sourceNodeType": "Seller Entity",
"targetNodeType": "Payment Terms"
}
]
}
}
}
更新了推断性数据分析
推理出的数据洞见会存储在 Knowledge Catalog Catalog 中,作为附加到对象表的方面。您可以使用 REST API 手动更新这些数据洞见。
REST
如需使用 REST API 更新推断出的数据洞见,请按以下步骤操作:
创建一个名为
payload.json的文件,并添加要更新的方面的 JSON 内容。例如:{ "aspects": { "dataplex-types.global.graph-profile": { "data": { "nodeTypes": [], "edgeTypes": [] } } } }在终端中运行以下命令:
curl -X PATCH \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d @payload.json \ "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID?updateMask=aspects"替换以下内容:
PROJECT_ID:您的项目 ID,例如example-projectLOCATION:条目的位置,例如us-central1ENTRY_GROUP_ID:条目组的 ID,例如example-entry-group(对于 BigQuery 对象表,请使用@bigquery)ENTRY_ID:条目的 ID,例如example-entry(从 Google Cloud 控制台中的条目详情页面的概览标签页中检索)
如需了解详情并查看其他语言的代码示例,请参阅更新条目的方面。
将数据提取到 BigQuery
您可以使用 SQL 或自动化流水线,将推理出的实体和关系具体化为 BigQuery 中的结构化表或视图。
在 Google Cloud 控制台中,前往 Knowledge Catalog 搜索页面。
搜索扫描生成的对象表。
在搜索结果中,点击相应表格以打开其条目页面。
点击数据分析标签页。
在数据分析标签页上,点击提取。
根据您的分析需求和非结构化数据的规模,选择以下方法之一:
通过 SQL 提取:如果需要快速进行临时分析、处理中小型数据集,或者希望使用 BigQuery 远程模型实现零基础架构方法,请选择此选项。
如需使用 SQL 提取数据,请按以下步骤操作:
- 选择 Extract by SQL。
- 在使用 SQL 提取窗格中,选择目标数据集。该数据集必须与源数据集位于同一位置。
- 点击提取。
- 在 BigQuery 编辑器中,系统会打开一个预填充的查询,其中使用了
ML.PROCESS_DOCUMENT函数。运行该查询以创建标准表和视图。
如需详细了解如何使用 SQL 提取文档分析数据,请参阅使用
ML.PROCESS_DOCUMENT函数处理文档。按流水线提取:如果需要大规模数据处理,或者需要强大的重试逻辑、错误处理和自动化编排来处理大量文档,请选择此选项。
如需使用流水线提取数据,请按以下步骤操作:
- 选择通过流水线提取。
- 在使用流水线提取窗格中,输入流水线的显示名称。
- 选择区域。
- 选择目标数据集。该数据集必须与源数据集位于同一位置。
- 点击提取。这会创建一个 BigQuery 流水线,用于使用 Dataform 编排数据具体化。
- 运行流水线中的所有任务,以生成结构化节点和边视图。
如需详细了解如何运行数据工作流,请参阅 Dataform 简介。
将语义数据洞见提取并具体化到 BigQuery 中后,您可以执行以下任务:
查询结构化数据。针对新创建的表运行标准 SQL 查询,以分析提取的实体和关系。
与现有数据联接。将从非结构化文件中提取的定性数据洞见与现有的结构化 BigQuery 数据集(例如,将解析后的账单数据与会计表格联接)相结合。
探索数据洞见。使用 BigQuery Studio 中的数据分析洞见功能,为新的结构化资产自动生成自然语言问题和 SQL 查询。
使用 Gemini 进行分析。在 BigQuery 中使用 Gemini 执行对话式分析、总结趋势,或根据提取的数据在数据洞察中创建信息中心。
后续步骤
- 了解如何针对非结构化数据使用发现扫描。
- 详细了解如何发现数据。
- 请参阅数据分析简介。