针对非结构化数据使用发现扫描

非结构化数据的数据分析扫描在 Cloud Storage 发现扫描期间使用 Vertex AI Gemini 2.5 Pro 模型，将 Cloud Storage 中的原始非结构化文件（例如 PDF）转换为 BigQuery 中可查询的结构化资产。此自动化工作流专为从 Cloud Storage 中的原始文件开始的用户而设计。如果您已有现成的 BigQuery 对象表，或者想使用自定义提示来引导提取，请参阅使用非结构化数据的数据分析。

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

准备工作

在创建发现扫描之前，请确保您拥有所需的权限并已启用相关 API。

启用 API

在项目中启用以下 API：

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

启用 API

所需的角色和权限

如需为非结构化数据配置和运行数据分析扫描，您必须满足发现扫描的基本权限，然后授予其他角色，以便在多个服务代理之间进行语义推理。

基准发现扫描角色

确保您和 Knowledge Catalog 使用的服务账号拥有标准发现扫描所需的基准权限。如需查看完整列表，请参阅发现和编目 Cloud Storage 数据。

用于语义推理的其他角色

除了基准发现角色之外，还要确保您和服务账号具有以下额外的 Identity and Access Management (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 角色：

• 全部：
  • 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 运行扫描和执行语义推理所需的权限。如需查看所需的确切权限，请展开所需权限部分：

您的管理员也可以使用自定义角色或其他预定义角色为 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） 对项目具有

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

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

您的管理员也可以使用自定义角色或其他预定义角色为 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)

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

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

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

为确保默认 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) 授予这些权限。

准备非结构化数据

在运行发现扫描之前，您必须将非结构化数据上传到 Cloud Storage 存储桶。非结构化数据的数据分析扫描经过优化，可用于分析 PDF 文档。

如需详细了解如何在 Cloud Storage 中存储和管理文件，请参阅上传对象。

创建 Cloud 资源连接

如需将发现扫描结果发布为 BigQuery 对象表，您必须创建 Cloud 资源连接，并向其服务账号授予对 Cloud Storage 中非结构化数据的访问权限。

1. 创建 Cloud 资源连接。
2. 向与连接关联的服务账号授予包含非结构化数据的 Cloud Storage 存储桶的 Storage Object Viewer (roles/storage.objectViewer) 角色。如需了解详情，请参阅授予服务账号访问权限。

为非结构化数据创建发现扫描

如需从非结构化数据中提取语义分析洞见，您必须先创建 Cloud Storage 发现扫描作业。此扫描作业会自动在 Cloud Storage 中查找非结构化文件，并将其编入对象表中。通过在此过程中启用语义推理，Knowledge Catalog 会使用 Vertex AI Gemini 2.5 Pro 模型来分析文件并生成推理出的元数据、架构和关系。

您可以使用 Google Cloud 控制台或 REST API 创建启用语义推理的 Cloud Storage 发现扫描。

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?dataScanId=DATASCAN
{
"description": "Cloud Storage discovery scan with semantic inference",
"data": {
"resource": "//storage.googleapis.com/BUCKET_NAME"
},
"executionSpec": {
"trigger": {
  "onDemand": {}
}
},
"dataDiscoverySpec": {
"bigqueryPublishingConfig": {
  "tableType": "OBJECT_TABLE",
  "connection": "projects/PROJECT_ID/locations/LOCATION/connections/CONNECTION_ID"
},
"unstructuredDataEventsConfig": {
  "enabled": true
}
}
}

运行发现扫描

如果您将发现扫描配置为按需运行，则必须手动触发扫描，以查找非结构化数据并生成数据洞见。

您可以使用 Google Cloud 控制台或 REST API 触发发现扫描。

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"

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

找到对象表

发现扫描完成后，Knowledge Catalog 会创建一个或多个对象表，并使用 AI 生成的元数据填充 Knowledge Catalog 中的相应条目。如果因发现扫描而创建了多个条目，则每个条目都有自己的“数据洞见”标签页。您可以查看自动生成的表格说明、推断出的架构和关系图。

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

   转到 BigQuery

2. 在导航菜单中，依次点击治理 > 元数据整理。

3. 在 Cloud Storage 发现窗格中，点击您针对非结构化数据运行的发现扫描。

   • 扫描详情部分显示有关发现扫描的详细信息。
   • 扫描状态部分显示最新扫描作业的发现结果。

4. 点击已发布的数据集的链接。

5. 在 BigQuery 数据集显示的表列表中，选择为发现数据扫描生成的对象表。

6. 复制表格 ID。您将在下一部分用到它。

探索发现扫描结果

您可以在 Knowledge Catalog 中查看对象表及其推理出的语义图。

1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 搜索页面。

   转到搜索

2. 粘贴并搜索您在上一部分中选择的 ID 所对应的对象表。

3. 在搜索结果中，点击相应表格以打开其条目页面。

4. 在详细信息标签页的方面下，验证是否存在图谱配置文件方面 (dataplex-types.global.graph-profile)。此方面包含实体和关系的推断架构。

5. 点击数据分析标签页。在数据分析标签页上，您可以查看以下信息：

   • 语义提取。系统会显示一个横幅，指示检测到可提取的实体和关系。该横幅包含一个提取按钮，用于使用 SQL 或流水线部署来实现数据具体化。

   • 说明。AI 生成的直观易懂的摘要可说明非结构化数据的内容。它描述了发现的主要节点（实体），以及它们如何通过边（关系）相互关联。

   • 流水线。与此资源关联的之前部署的数据提取流水线的列表。您可以查看显示名称、区域、创建时间和创建流水线的用户。

   • 推断出的实体和关系。直观的交互式图表会显示非结构化数据的发现语义结构。 该图包含表示不同实体的节点（例如 Recipe 和 Ingredient）以及表示实体之间连接的边（例如 HasAllergenStatus）。您可以使用图例过滤和探索特定节点和边。

   • 实体。发现的主要实体的详细列表。您可以展开每个实体，查看其 AI 生成的说明和推断的架构，其中包括字段名称、数据类型和字段说明。

   • 关系。实体之间发现的连接的详细列表。您可以展开每种关系，查看其说明以及定义实体之间如何相互映射的架构。

更新了推断性数据分析

推理出的数据洞见会存储在 Knowledge Catalog Catalog 中，作为附加到对象表的方面。您可以使用 REST API 手动更新这些数据洞见。

将数据提取到 BigQuery

您可以使用 SQL 或自动化流水线，将推理出的实体和关系具体化为 BigQuery 中的结构化表或视图。

1. 在 Google Cloud 控制台中，前往 Knowledge Catalog 搜索页面。

   转到搜索

2. 搜索扫描生成的对象表。

3. 在搜索结果中，点击相应表格以打开其条目页面。

4. 点击数据分析标签页。

5. 在数据分析标签页上，点击提取。

6. 根据您的分析需求和非结构化数据的规模，选择以下方法之一：

   • 通过 SQL 提取：如果需要快速进行临时分析、处理中小型数据集，或者希望使用 BigQuery 远程模型实现零基础架构方法，请选择此选项。

     如需使用 SQL 提取数据，请按以下步骤操作：

     1. 选择 Extract by SQL。
     2. 在使用 SQL 提取窗格中，选择目标数据集。该数据集必须与源数据集位于同一位置。
     3. 点击提取。
     4. 在 BigQuery 编辑器中，系统会打开一个预填充的查询，其中使用了 ML.PROCESS_DOCUMENT 函数。运行该查询以创建标准表和视图。

     如需详细了解如何使用 SQL 提取文档分析数据，请参阅使用 ML.PROCESS_DOCUMENT 函数处理文档。

   • 按流水线提取：如果需要大规模数据处理，或者需要强大的重试逻辑、错误处理和自动化编排来处理大量文档，请选择此选项。

     如需使用流水线提取数据，请按以下步骤操作：

     1. 选择通过流水线提取。
     2. 在使用流水线提取窗格中，输入流水线的显示名称。
     3. 选择区域。
     4. 选择目标数据集。该数据集必须与源数据集位于同一位置。
     5. 点击提取。这会创建一个 BigQuery 流水线，用于使用 Dataform 编排数据具体化。
     6. 运行流水线中的所有任务，以生成结构化节点和边视图。

     如需详细了解如何运行数据工作流，请参阅 Dataform 简介。

将语义数据洞见提取并具体化到 BigQuery 中后，您可以执行以下任务：

• 查询结构化数据。针对新创建的表运行标准 SQL 查询，以分析提取的实体和关系。

• 与现有数据联接。将从非结构化文件中提取的定性数据洞见与现有的结构化 BigQuery 数据集（例如，将解析后的账单数据与会计表格联接）相结合。

• 探索数据洞见。使用 BigQuery Studio 中的数据分析洞见功能，为新的结构化资产自动生成自然语言问题和 SQL 查询。

• 使用 Gemini 进行分析。在 BigQuery 中使用 Gemini 执行对话式分析、总结趋势，或根据提取的数据在数据洞察中创建信息中心。

后续步骤

• 了解如何使用非结构化数据的数据分析文件。
• 详细了解如何发现数据。
• 请参阅数据分析简介。