创建数据丰富化任务

预览

此功能受服务专用条款的“通用服务条款”部分中的“非正式版产品条款”的约束。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

借助 Knowledge Studio 丰富化任务，您可以自动从架构、标准操作程序 (SOP)、代码库和查询日志中提取业务上下文。创建扩充任务时，您需要配置目标资源、知识信号、评估基准和时间表，以生成为 AI 应用提供依据的元数据建议。

准备工作

在创建丰富化任务之前，请先满足以下前提条件。

了解相关概念

在运行丰富任务之前，我们建议您先熟悉丰富架构的核心组件：

• 如需简要了解 Knowledge Studio 智能体如何自动生成元数据，请参阅关于丰富任务。

• 如需简要了解元数据上下文如何为 AI 智能体提供依据并简化数据探索，请参阅数据上下文简介。

• 如需简要了解 Knowledge Catalog 层次结构（包括条目组、条目、切面和条目链接），请参阅 Knowledge Catalog 中的元数据简介。

准备所需组件

在创建丰富化任务之前，请确保您的环境已针对 AI 丰富化进行了正确配置。如需查看设置说明，请参阅配置丰富任务的前提条件。

准备好以下组件：

• 服务账号：具有所需角色的专用用户服务账号。在本文档中，术语“执行服务账号”是指此客户代管式服务账号，以区别于 Google 管理的 Knowledge Catalog 服务代理。扩充任务会以此服务账号的身份运行，并使用该账号读取来源和向上下文集写入数据。

• 上下文集：用于保存丰富元数据的目标上下文集。上下文集可以是区域级、多区域级或全球级，每个上下文集在每个区域只能关联一个丰富化任务。上下文集还可用作要丰富化的资产的默认来源；除非您在设置期间过滤默认资源，否则上下文集中的所有内容都会默认进行丰富化。如果不存在上下文集，您还可以在任务设置期间创建一个空上下文集。如需了解详情，请参阅管理上下文集中的“创建上下文集”部分。

• 要丰富的数据资源（可选）：您要丰富但尚未包含在目标上下文集中的其他数据资产。在任务创建期间添加这些额外资源可以丰富任务内容，并在运行的提案获得批准后自动将这些资源添加到目标上下文集。目标资源可以包括 BigQuery 数据集和表，或者 Lakehouse 目录、命名空间和表（默认资源和添加的资源总数最多为 500 个）。如需了解资源名称语法，请参阅完整资源名称。

• 知识信号（可选）：如果您打算为 AI 智能体提供文档、术语表或 SQL 脚本以供学习，请确保准备好 Cloud Storage 存储桶、文件夹或文件，设置 .jsonl 评估数据集的文件格式，或为第三方来源网址配置第三方身份验证提供方。如需了解第三方连接器设置说明，请参阅为扩充任务配置外部连接器。

• 轨迹日志（可选）：如果您打算启用智能体自学习功能，请配置一个 Gemini Enterprise 应用（在 Cloud Logging 中开启轨迹插桩和提示与回答日志记录功能）或一个 BigQuery Agent Analytics 表，以便扩充智能体从中学习历史互动。如需了解详情，请参阅管理可观测性设置和配置丰富任务的前提条件中的“为自学配置智能体跟踪记录”部分。

• 数据分析和数据洞见（推荐）：为了提高生成的元数据建议的质量，请在运行任务之前，对常用目标表启用数据分析和 AI 数据洞见。

所需的角色

设置和运行丰富化任务涉及三个身份，每个身份都需要特定的 IAM 角色：

• 最终用户（您的用户账号）：在 Knowledge Studio 中创建、配置和触发丰富化任务。
• 执行服务账号（客户管理）：运行丰富任务，读取来源资产和可选交互轨迹，并向上下文集提出元数据更新建议。
• Knowledge Catalog Service Agent（由 Google 管理）：在运行期间模拟您的执行服务账号，并执行后端 BigQuery 采样、查询历史记录分析和验证查询作业。

最终用户

如需获得创建、修改和运行丰富化任务所需的权限，请让管理员向您授予以下 IAM 角色：

• 创建、修改和运行丰富化任务：针对项目的 Dataplex DataScan Editor (roles/dataplex.dataScanEditor) 或 Dataplex Editor (roles/dataplex.editor)
• 将执行服务账号附加到丰富任务：执行服务账号的 Service Account User (roles/iam.serviceAccountUser)

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

这些预定义角色包含创建、修改和运行丰富化任务所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

如需创建、修改和运行丰富化任务，您需要具备以下权限：

• 创建、查看、列出、更新、删除和运行丰富化任务：
  • dataplex.agentTasks.create
  • dataplex.agentTasks.get
  • dataplex.agentTasks.getData
  • dataplex.agentTasks.list
  • dataplex.agentTasks.update
  • dataplex.agentTasks.delete
  • dataplex.agentTasks.run
• 关联执行服务账号： iam.serviceAccounts.actAs

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

执行服务账号

执行服务账号是客户管理的身份，富化任务在此身份下运行并执行所有操作。

如需确保执行服务账号拥有运行丰富任务、读取目标数据和提议元数据更新所需的权限，请让您的管理员为执行服务账号授予以下 IAM 角色：

重要提示：您必须向执行服务账号（而不是向您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。

• 在任务执行期间使用 API：针对包含丰富任务的项目的 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)
• 查看目标 BigQuery 数据集和表：针对目标 BigQuery 数据集和表的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色
• 查看目标 Lakehouse 资产（丰富 Lakehouse 资产时）：针对目标 Lakehouse 目录、命名空间和表的 BigLake Viewer (roles/biglake.viewer) 角色
• 向上下文集提议和写入元数据：
  • 针对目标上下文集的 Dataplex Content Editor (roles/dataplex.contentEditor)
  • 针对项目的 Dataplex Catalog Editor (roles/dataplex.catalogEditor)
  • 针对项目的 Dataplex Catalog Viewer (roles/dataplex.catalogViewer)
• （可选）在任务项目上运行 BigQuery 作业（仅当作业创建操作移至 VPC Service Controls 边界内时才需要）：任务项目上的 BigQuery Job User (roles/bigquery.jobUser)
• （可选）自动批准并发布建议的更改（如果您启用了自动发布）：针对项目的 Dataplex Workflow Approver (roles/dataplex.workflowApprover)
• （可选）从现有 Logging 轨迹日志中学习（自学）：拥有 Gemini Enterprise 应用的项目的 Private Logs Viewer (roles/logging.privateLogViewer)
• （可选）从 BigQuery Agent Analytics 表学习（自学）：
  • 针对代理分析表（或其数据集）的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色
  • 针对包含智能体分析表的项目的 BigQuery Job User (roles/bigquery.jobUser)

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

这些预定义角色包含运行丰富任务、读取目标数据和提议元数据更新所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

您需要拥有以下权限才能运行丰富化任务、读取目标数据和提出元数据更新建议：

• 使用配额和服务： serviceusage.services.use
• 查看 BigQuery 数据集和表元数据以及读取表数据：
  • bigquery.datasets.get
  • bigquery.tables.get
  • bigquery.tables.getData
• 查看 Lakehouse 目录、命名空间和表：
  • biglake.catalogs.get
  • biglake.namespaces.get
  • biglake.tables.get
  • biglake.tables.list
• 查看和提议更改上下文集和条目：
  • dataplex.entryGroups.getContextSet
  • dataplex.entryGroups.requestContextChanges
  • dataplex.entries.createContext
  • dataplex.entries.updateContext
  • dataplex.entries.getContext
  • dataplex.entries.listContext
  • dataplex.entryLinks.create
• 创建、更新、查看和列出目录条目和条目组：
  • dataplex.entries.create
  • dataplex.entries.update
  • dataplex.entries.get
  • dataplex.entries.list
  • dataplex.entryGroups.create
  • dataplex.entryGroups.update
  • dataplex.entryGroups.requestChanges
• （可选）运行 BigQuery 作业（适用于 VPC Service Controls 边界或 BigQuery Agent Analytics 表）： bigquery.jobs.create
• （可选）自动批准更改请求：dataplex.changeRequests.use
• （可选）读取 Logging 视图和日志条目：
  • logging.views.access
  • logging.logEntries.list

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

Dataplex Service Agent

Knowledge Catalog 服务代理是 Google 代管式服务账号，Knowledge Catalog 使用该账号代表您执行后端操作，例如在扩充运行期间模拟您的执行服务账号，以及运行 BigQuery 抽样、查询历史记录分析和验证查询作业。

Knowledge Catalog 服务代理使用以下电子邮件格式：

service-PROJECT_NUMBER@gcp-sa-dataplex.

将 PROJECT_NUMBER 替换为您的 Google Cloud项目编号。

授予查询历史记录访问权限（推荐）后，丰富代理可以分析历史 SQL 查询 (INFORMATION_SCHEMA.JOBS_BY_PROJECT)，以识别常见的联接键和过滤条件。如果未授予 BigQuery Resource Viewer (roles/bigquery.resourceViewer) 角色，代理会跳过查询历史记录分析，而不会导致运行失败。

如需确保 Knowledge Catalog Service Agent 拥有模拟执行服务账号和执行后端 BigQuery 分析所需的权限，请让您的管理员为 Knowledge Catalog Service Agent 授予以下 IAM 角色：

重要提示：您必须向 Knowledge Catalog Service Agent（而非您的用户账号）授予这些角色。如果未能向正确的主账号授予这些角色，可能会导致权限错误。

• 模拟执行服务账号以运行任务：执行服务账号的 Service Account Token Creator (roles/iam.serviceAccountTokenCreator)
• 执行后端 BigQuery 分析和验证查询：针对包含目标表的项目或数据集的 BigQuery 数据视图 (roles/bigquery.dataViewer)
• （推荐）在项目级层读取 BigQuery 查询历史记录：针对运行查询的项目，拥有 BigQuery Resource Viewer (roles/bigquery.resourceViewer) 角色

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

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

所需权限

您需要具备以下权限才能冒充执行服务账号并执行后端 BigQuery 分析：

• 为服务账号模拟生成令牌并对载荷进行签名：
  • iam.serviceAccounts.getAccessToken
  • iam.serviceAccounts.getOpenIdToken
  • iam.serviceAccounts.signJwt
  • iam.serviceAccounts.signBlob
• 查看 BigQuery 数据集和表元数据以及读取表数据：
  • bigquery.datasets.get
  • bigquery.tables.get
  • bigquery.tables.getData
• （推荐）列出 BigQuery 作业并查看项目元数据：
  • bigquery.jobs.listAll
  • resourcemanager.projects.get

您的管理员也可以使用自定义角色或其他预定义角色为 Knowledge Catalog Service Agent 授予这些权限。

打开 Knowledge Studio 工作区

如需打开任务创建向导，请执行以下步骤：

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

   前往 Knowledge Studio

2. 在导航窗格中，选择丰富。

3. 点击 + 创建丰富化任务。

为数据丰富化任务命名

在定义窗格中，执行以下步骤：

1. 在显示名称字段中，为任务提供一个描述性名称（例如 Finance Dataset enrichment）。
2. 在任务 ID 字段中，提供唯一 ID 或使用自动生成的 ID。

3. 在目标字段中，描述丰富任务的目标，以指导提取过程。提供自然语言指南，详细说明此上下文集的业务使命和 AI 功能目标。

   例如：

   Curate and maintain the authoritative context set for the
   `subscription_revenue` domain. Focus on resolving metric discrepancies
   between `gross_sales`, `net_billed_revenue`, and `discount_applied`.
   Ensure all customer join keys (e.g. `customer_id`, `subscription_fk`)
   have explicit column documentation, and establish parameterized query
   templates for Monthly Recurring Revenue (MRR) and Churn Rate calculations.
   

4. 点击继续。

配置丰富化任务参数

范围指定了要扩充的内容以及代理读取的内容。

在范围窗格中，执行以下步骤：

1. 在项目字段中，选择包含上下文集的项目。

2. 在上下文集字段中，选择任务将进行丰富化处理并将结果保存至其中的上下文集。如果您没有上下文集，请点击创建新的上下文集。

   上下文集可以是区域级、多区域级或全球级，每个上下文集在每个区域只能关联一个丰富化任务。如果您选择的上下文集已附加到该区域中的现有丰富化任务，向导会显示一条出错提示，其中包含指向现有任务的链接，并要求您选择其他上下文集。创建丰富化任务后，您便无法更改其上下文集。

3. 如果您选择的上下文集位于多区域（例如 us 或 eu）或 global 中，请在丰富任务区域字段中选择运行丰富任务的单个区域（例如 us-central1）。如果上下文集位于单个区域中，则任务会自动使用上下文集的区域。

4. 在要丰富化的资源部分中，查看默认资源，并视需要添加更多 BigQuery 或 Lakehouse 资源：

   • 默认资源：默认情况下，所选上下文集中的所有内容都会得到丰富化处理。展开默认资源，以查看或过滤上下文集中的预填充表。
   • 添加更多 BigQuery 或 Lakehouse 资源：除了上下文集之外，添加您要丰富化的 BigQuery 数据集或表，或者 Lakehouse 目录、命名空间或表。添加这些资源后，当运行的建议获得批准时，这些资源也会添加到上下文集中。一个丰富任务最多支持 500 个总资源，包括默认资源和添加的资源。

   您添加的所有资源都必须与上下文集的位置一致。多区域上下文集（例如 us）与该位置内的单区域（例如 us-central1）匹配，而 global 上下文集接受来自任何区域的资源。区域不匹配会导致任务创建失败。

   如果您选择空上下文集，并且未在此部分中添加任何其他资源，Knowledge Studio 会显示警告。如果您使用此配置运行任务，它会根据您的指令生成语义知识库，但不会对任何表条目进行丰富化处理。

   如需按完整资源名称添加资源，请在文本字段中输入资源名称（使用英文逗号分隔多个资源名称）：

   • BigQuery 表: //bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID

   • Lakehouse 资产：//dataplex.googleapis.com/projects/PROJECT_ID/locations/LOCATION/lakes/LAKE_ID/zones/ZONE_ID/assets/ASSET_ID

   或者，如需直观地选择资源，请执行以下步骤：

   1. 点击浏览，打开选择来源对话框。
   2. 如需从最近使用的资源中进行选择，请点击最近标签页，然后选择要添加的资源。
   3. 如需浏览或搜索所有资源，请点击全部标签页，然后执行以下操作：
      1. 在搜索字段中，输入 BigQuery 或 Lakehouse 资源的搜索字词。
      2. 在资源树中，展开项目和数据集层次结构以找到您的资源。
      3. 选中一个或多个资源旁边的复选框。您可以在“详细信息”窗格中预览所选资源的架构和详细信息。
      4. 点击确认。

5. 可选：在知识信号部分，将 AI 智能体连接到其他来源，以便读取上下文。这些资源是只读的，不会被丰富。

   • Cloud Storage 存储桶、文件夹或文件：输入存储桶名称、以斜杠结尾的文件夹路径（例如 bucket-name/folder/）或单个路径，或者点击浏览以选择存储桶、文件夹或文件（最多 1,000 个 Cloud Storage 来源）。每输入一个条目后，请按 Enter 键、英文逗号或空格键。

   • 术语表：输入术语表名称，或点击浏览搜索术语表。每输入一个术语表名称后，请按 Enter 键、英文逗号或空格键。

     确保所有关联的术语表都位于兼容的区域或 global 范围内。

   • 外部来源：如需连接 Google Workspace、Microsoft SharePoint、GitHub 或 Atlassian（Confluence 空间和 Jira 项目）等第三方平台，您可以单独配置这些平台，也可以提供 YAML 配置文件。

     如需使用 YAML 文件配置来源，请执行以下操作：

     1. 在来源配置文件（可选）字段中，点击浏览，然后选择您的 YAML 文件。

     如需手动配置来源，请执行以下操作：

     1. 在已连接的来源下，点击要配置的平台旁边的设置。
     2. 在来源网址字段中，输入文档、代码库、空间或 Jira 项目的网址，然后在每个网址后按 Enter 键或英文逗号。

     3. 如果平台需要身份验证（例如 GitHub、Atlassian 或 Microsoft），请执行以下操作来附加凭据：

        1. 点击 + 添加连接。
        2. 在新建连接窗格中，在身份验证提供方字段中输入身份验证提供方的完整资源名称。请使用以下格式：
           projects/PROJECT_ID/locations/LOCATION/authProviders/PROVIDER_NAME
        3. 在 URI 格式下，点击 + 添加 URI 格式，以指定此凭证有权访问哪些网址。您可以将星号 (*) 用作通配符（例如 https://github.com/test-org/*）。
        4. 点击完成。

        Google Workspace 资源可直接使用任务的执行服务账号 IAM 权限进行连接，因此不需要身份验证提供方连接。

6. 点击继续。

配置评估和自学习

改进窗格中的设置为可选设置。如需了解如何设置评估和精选数据集的格式，请参阅为丰富任务配置前提条件。如需了解如何在 Gemini Enterprise 中选择模型，请参阅在 Agent Studio 中设计代理中的“使用流程构建器创建代理”部分。

在改进窗格中，执行以下步骤：

1. 可选：在评估部分中，配置以下字段：

   • 评估集：如需衡量建议的上下文更改的影响，请输入 Cloud Storage URI 或点击浏览以选择 .jsonl 文件。

   • 精选集：如需提供一组种子问题以进行迭代优化，请输入 Cloud Storage URI 或点击浏览以选择 .jsonl 文件。

2. 可选：在发布部分中，指定发布节奏：

   启用自动发布功能后，智能体会将提案暂存为变更请求，并在运行符合所有发布条件时自动批准运行，同时留下审核记录。删除提案始终会保留以供人工审核。停用自动发布功能后，人工审核者必须先批准更改请求，然后才能将其发布到上下文集。

   • 如需在将元数据合并到生产上下文集之前要求人工审核，请清除启用自动发布复选框。

   • 如需自动发布符合质量条件的运行，请选中启用自动发布复选框。使用自动发布阈值滑块设置运行自动发布所需的最低总体置信度分数（默认值为 85%）。每个提案还必须通过有效性检查（例如有效的 SQL 语法）。如果配置了评估数据集，您还可以使用质量下降上限滑块，在评估准确率下降幅度超过指定阈值（默认值为 5%）时限制发布。如果运行不满足所有这些条件，则所有提案都会保持暂存状态，作为更改请求进行人工审核。

3. 可选：如需在真实代理对话中查找差距并使上下文保持最新，请在自学部分中选择启用自学切换开关。

4. 可选：如果您启用了自学功能，请在学习来源部分下添加以下任一来源：

   • Gemini Enterprise 应用：在项目 ID 列表中，选择相应项目。在 Gemini Enterprise 应用列表中，选择生成对话跟踪记录的应用，然后点击完成。您可以添加多个 Gemini Enterprise 应用。为了优化丰富和自学习功能，我们建议您在 Gemini Enterprise 应用中指定 Gemini 3.8 Flash 或更高版本的模型。

   • BigQuery Agent Analytics：在表字段中，输入包含智能体对话事件的表的名称，或点击浏览以直观地选择该表，然后点击完成。您可以添加多个表格。

5. 点击继续。

配置运行设置

在运行窗格中，执行以下步骤：

1. 在运行身份部分中，点击服务账号列表，然后选择任务用于读取来源和写入上下文集中的执行服务账号。

   选择服务账号后，Knowledge Studio 会自动运行政策问题排查工具，以检查执行服务账号、Knowledge Catalog 服务代理和目标资源：

   • 如果缺少任何必需的角色，并且您有权修改这些资源上的 IAM 政策，请点击全部授予以自动授予缺少的角色。
   • （推荐）选择授予对 BigQuery 查询历史记录的访问权限，以授予 BigQuery Resource Viewer (roles/bigquery.resourceViewer) 角色 (bigquery.jobs.listAll)，并可选择在查询历史记录项目 ID 字段中指定运行 BigQuery 查询的其他项目 ID。

2. 在触发器下，选择触发条件：

   • 按需：仅在您点击运行时运行。
   • 预定：根据周期性时间表（例如每天、每周或每月）自动运行。所有预定运行时间均使用世界协调时间 (UTC)。

3. 可选：在通知下，点击 + 添加收件人，指定最多五个电子邮件地址，以便在每次运行后接收报告。

4. 在摘要窗格中验证参数，然后点击创建。

您的新丰富化任务已保存。根据您的触发器设置，任务要么等待其首次预定执行，要么准备立即运行。扩充运行通常需要 20 到 60 分钟才能完成，对于启用了精选和评估集的大型数据集，则可能需要长达数小时。在代理初始化和提取信号期间，执行日志可能需要 20 到 30 分钟才会开始显示。当任务完成执行运行后，代理会将生成的 AI 元数据提案排入一个或多个更改请求批次中，供您审核。

后续步骤

• 管理丰富化任务
• 评估和批准丰富化提案