自 2026 年 4 月 10 日起，Dataplex Universal Catalog 更名为 Knowledge Catalog。API、客户端库、CLI 和 IAM 名称保持不变。如需了解详情，请参阅 Google Cloud Knowledge Catalog 简介。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

配置丰富化任务的前提条件

如需在 Knowledge Studio 中运行丰富任务，您可以配置客户管理的账号、第三方身份验证提供方、Cloud Storage 存储桶和 Cloud Logging 视图。设置这些前提条件组件后，扩充智能体便可安全地访问目标数据源、注入非结构化知识信号，并从历史智能体互动中学习。

下表介绍了前提条件配置以及您需要配置这些配置的时间：

配置功能	何时配置
Google Cloud API	必需。您必须启用底层 Google Cloud API 才能运行丰富工作流。如需了解详情，请参阅本文档中的准备工作部分。
客户代管式服务	必需。您可以使用专用服务账号来限制对目标数据集和上下文集的读写权限。如需了解详情，请参阅本文档的配置客户代管式服务账号部分。
用户 Identity and Access Management (IAM) 角色	必需。您需要向工作流管理员和审核者授予生成和审批元数据的权限。如需了解详情，请参阅本文档的向用户授予所需的 IAM 角色部分。
第三方身份验证提供方	可选。您正在连接到第三方知识来源（例如 Microsoft SharePoint、Atlassian Confluence 或 GitHub）。如需了解详情，请参阅本文档的配置第三方身份验证提供方部分。
Cloud Storage 存储桶	可选。您正在提取非结构化业务上下文（例如 PDF、Markdown 和 CSV）以及评估数据集。如需了解详情，请参阅本文档的准备 Cloud Storage 存储桶部分。
评估数据集	可选。您希望提供种子查询和基准数据集，以主动跟踪智能体的准确率。如需了解详情，请参阅本文档的设置评估数据集的格式部分。
用于自主学习的智能体跟踪记录	可选。您希望让扩充智能体自动分析 Gemini Enterprise 应用或 BigQuery Agent Analytics 表中的下游智能体互动。如需了解详情，请参阅本文档的配置智能体跟踪记录以进行自学部分。
数据分析和数据洞见	推荐。您希望通过针对常用表生成统计分析和基准 AI 数据洞见，来提高丰富质量。如需了解详情，请参阅本文档中的启用数据分析和数据洞见部分。

准备工作

登录您的 Google Cloud 账号。如果您是 Google Cloud新手，请创建一个账号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

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.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Dataplex, Data Lineage, BigQuery, Cloud Storage, and IAM Credentials APIs, if any are not already enabled.

Roles required to enable APIs

Enable the APIs

必需的 API 详情

如需配置和运行丰富化任务，启用的 API 会执行以下功能：

API 名称	服务标识符	在丰富化工作流中的用途
Dataplex API	`dataplex.googleapis.com`	主要控制平面 API。管理 `EnrichmentTask`、`EnrichmentRun`、上下文集、更改请求和 EnrichmentChatService。
BigQuery API	`bigquery.googleapis.com`	扫描表架构、提取 SQL 执行历史记录以及查询 BigQuery Agent Analytics 跟踪表时需要此权限。
Cloud Storage API	`storage.googleapis.com`	对于提取评估集和管理评估数据集样本，必须提供此信息。
IAM 服务账号凭据 API	`iamcredentials.googleapis.com`	在执行任务期间，需要安全地对执行代理进行身份验证并授予短期有效凭据 (SLC)。

配置客户代管式服务账号

丰富化任务使用客户代管式服务账号来运行操作。使用专用服务账号，您可以限制对目标数据集和上下文集的读写权限。

创建服务账号。

如需创建服务账号，您必须拥有项目的 Owner (roles/owner)、Editor (roles/editor) 或 Service Account Admin (roles/iam.serviceAccountAdmin) 角色。

专用服务账号可隔离您的丰富化操作，让您能够仅授予这些任务所需的特定读写权限，而不会影响其他工作负载。

如需创建服务账号，请按照以下步骤操作：
Google Cloud CLI

如需创建服务账号，请使用 gcloud iam service-accounts create 命令：

在使用下面的命令数据之前，请先进行以下替换：
- SERVICE_ACCOUNT_NAME：您的服务账号的名称
执行以下命令：
Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \ --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" \ --display-name="Knowledge Catalog enrichment agent SA"
Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ` --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ` --display-name="Knowledge Catalog enrichment agent SA"
Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud iam service-accounts create SERVICE_ACCOUNT_NAME ^ --description="Service Account for Dataplex Knowledge Catalog enrichment agent execution" ^ --display-name="Knowledge Catalog enrichment agent SA"
REST

在使用任何请求数据之前，请先进行以下替换：
- SERVICE_ACCOUNT_NAME：您的服务账号的名称
- TARGET_PROJECT_ID：您的 Google Cloud 项目 ID
HTTP 方法和网址：
POST https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts
请求 JSON 正文：
{ "accountId": "SERVICE_ACCOUNT_NAME", "serviceAccount": { "displayName": "Knowledge Catalog enrichment agent SA", "description": "Service Account for Dataplex Knowledge Catalog enrichment agent execution" } }
如需发送您的请求，请展开以下选项之一：
curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts"
PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://iam.googleapis.com/v1/projects/TARGET_PROJECT_ID/serviceAccounts" | Select-Object -Expand Content
您应该会收到一个成功的状态代码 (2xx) 和一个空响应。
向目标范围内的执行服务账号授予必要的资源级 IAM 角色：
- 针对项目的 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)：服务账号需要此角色才能使用配额和调用 Knowledge Catalog（原 Dataplex Universal Catalog）API。
- 目标上下文集（或项目）的 Dataplex Content Editor (roles/dataplex.contentEditor) 角色：允许代理读取上下文集条目，创建、更新和删除上下文条目和 reference 条目链接，以及提交更改请求。此角色包括 dataplex.entryGroups.getContextSet、dataplex.entryGroups.requestContextChanges、dataplex.entries.getContext、dataplex.entries.createContext、dataplex.entries.updateContext、dataplex.entries.deleteContext、dataplex.entryLinks.create、dataplex.entries.link 和 dataplex.entryGroups.useReferenceEntryLink。
- 针对项目（或目标目录资源）的 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 和 Dataplex Catalog Viewer (roles/dataplex.catalogViewer)：允许代理检查目录元数据并读取关联的业务术语库和语义资产。虽然 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 包含所有 Dataplex Catalog Viewer (roles/dataplex.catalogViewer) 权限，但如果未指定目标上下文集且 Policy Troubleshooter 不可用， Google Cloud 控制台回退检查也会验证 Dataplex Catalog Viewer (roles/dataplex.catalogViewer)。
- 针对目标数据集和表（以及任何 BigQuery Agent Analytics 跟踪表或其数据集）的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色：让智能体能够列出表、读取表架构和智能体分析跟踪表、对表数据进行抽样，以及运行验证检查。
- 项目的 BigQuery Job User (roles/bigquery.jobUser)（以及包含代理分析跟踪记录表的项目，如果不同）(bigquery.jobs.create)：允许客户代管式服务账号运行 BigQuery 查询作业，以进行数据抽样、查询历史记录分析和验证检查。
- （推荐）目标项目（bigquery.jobs.listAll，必须在项目级层授予，而不是在单个数据集上授予）的 BigQuery Resource Viewer (roles/bigquery.resourceViewer)：让客户代管式服务账号分析历史 SQL 查询，以发现常见的联接和过滤条件。如果未授予此角色，代理会跳过查询历史记录分析，而不会导致运行失败。
- 目标 Lakehouse 目录、命名空间或表上的 BigLake Viewer (roles/biglake.viewer)：丰富 Lakehouse 资产时需要。
- （可选）针对项目的 Dataplex Workflow Approver (roles/dataplex.workflowApprover)：仅当您在任务中启用自动发布时才需要。允许代理自动批准和发布自己的元数据更改请求。
注意：为便于设置，以下代码示例在项目级层授予这些角色。对于生产系统，请在项目级层保留项目级角色（例如 Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)、BigQuery Job User (roles/bigquery.jobUser) 和 BigQuery Resource Viewer (roles/bigquery.resourceViewer)）。针对目标上下文集、数据集和 Lakehouse 资源授予资源级角色（例如 Dataplex 内容编辑者 (roles/dataplex.contentEditor)、BigQuery 数据视图者 (roles/bigquery.dataViewer) 和 BigLake 查看者 (roles/biglake.viewer)）。

如需授予这些标准角色，请按照以下步骤操作：

如需向项目添加 IAM 政策绑定，请使用 gcloud projects add-iam-policy-binding 命令：

在使用下面的命令数据之前，请先进行以下替换：
- SERVICE_ACCOUNT_NAME：您的服务账号的名称
- TARGET_PROJECT_ID：您的 Google Cloud 项目 ID
执行以下命令：
Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.contentEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/dataplex.catalogViewer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/bigquery.jobUser"
```
Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.contentEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/dataplex.catalogViewer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/bigquery.jobUser"
```
Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.contentEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogEditor"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/dataplex.catalogViewer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.dataViewer"

gcloud projects add-iam-policy-binding TARGET_PROJECT_ID ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/bigquery.jobUser"
```
向用户授予 Service Account User (roles/iam.serviceAccountUser) 角色，以授予他们模拟服务账号的权限：

在控制台中创建丰富化任务的用户必须拥有此权限，以便他们可以指定此服务账号并将其附加到任务。

如需向用户授予 Service Account User (roles/iam.serviceAccountUser) 角色，请按以下步骤操作：

如需向服务账号添加 IAM 政策绑定，请使用 gcloud iam service-accounts add-iam-policy-binding 命令：

在使用下面的命令数据之前，请先进行以下替换：
- SERVICE_ACCOUNT_NAME：您的服务账号的名称
- TARGET_PROJECT_ID：您的 Google Cloud 项目 ID
- USER_EMAIL：用户的邮箱
执行以下命令：
Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="user:USER_EMAIL@domain.com" \
    --role="roles/iam.serviceAccountUser"
```
Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="user:USER_EMAIL@domain.com" `
    --role="roles/iam.serviceAccountUser"
```
Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="user:USER_EMAIL@domain.com" ^
    --role="roles/iam.serviceAccountUser"
```
通过向内部 Knowledge Catalog 服务代理授予 Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 角色，允许其模拟此服务账号：

此角色可让底层 Knowledge Catalog 服务在代表您运行后台丰富化操作时，假定此专用服务账号的身份及其受限权限。

如需授权代理承担服务账号身份，请按照以下步骤操作：

如需向服务账号添加 IAM 政策绑定，请使用 gcloud iam service-accounts add-iam-policy-binding 命令：

在使用下面的命令数据之前，请先进行以下替换：
- SERVICE_ACCOUNT_NAME：您的服务账号的名称
- TARGET_PROJECT_ID：您的 Google Cloud 项目 ID
- TARGET_PROJECT_NUMBER：您的 Google Cloud 项目编号
执行以下命令：
Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com \
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" \
    --role="roles/iam.serviceAccountTokenCreator"
```
Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com `
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" `
    --role="roles/iam.serviceAccountTokenCreator"
```
Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com ^
    --member="serviceAccount:service-TARGET_PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com" ^
    --role="roles/iam.serviceAccountTokenCreator"
```

向用户授予所需的 IAM 角色

为确保您的团队能够管理丰富工作流并审核 AI 生成的提案，请向您的用户授予适当的 IAM 角色。如需了解如何授予这些角色，请参阅管理对项目、文件夹和组织的访问权限。

创建、配置和监控任务的工作流管理员（例如数据监管员）需要以下角色：

Dataplex DataScan Editor (roles/dataplex.dataScanEditor) 或 Dataplex Editor (roles/dataplex.editor)：允许用户创建、修改和触发丰富化任务。
客户代管式服务账号的 Service Account User (roles/iam.serviceAccountUser) 角色：需要将服务账号关联为任务的执行身份。如需了解设置详情，请参阅本文档的配置客户代管式服务账号部分。

变更审核者（例如域名所有者或主题专家）负责检查、批准 AI 生成的元数据提案并将其发布到目录，他们需要以下角色：

针对上下文集的 Dataplex Content Editor (roles/dataplex.contentEditor) 角色，以及针对项目的 Dataplex Catalog Viewer (roles/dataplex.catalogViewer) 角色：需要（与 Dataplex Workflow Approver (roles/dataplex.workflowApprover) 角色一起）批准和发布上下文集提案。如果审核者还批准上下文集之外的直接目录建议，请在项目上授予 Dataplex Catalog Editor (roles/dataplex.catalogEditor) 角色，而不是 Dataplex Catalog Viewer (roles/dataplex.catalogViewer) 角色。如需在批准建议之前以内嵌方式修改说明，审核者还需要 dataplex.changeRequests.update 权限（例如，通过 Dataplex Administrator (roles/dataplex.admin) 或自定义角色）。
针对上下文集的 Dataplex Content User (roles/dataplex.contentUser) 以及针对项目的 Dataplex Catalog Viewer (roles/dataplex.catalogViewer)：对上下文集条目和更改请求提案进行只读检查时需要。
针对项目的 Dataplex Workflow Approver (roles/dataplex.workflowApprover) 角色：需要此角色才能批准变更请求并将其发布到实时上下文集。
针对项目的 Dataplex DataScan Data Viewer (roles/dataplex.dataScanDataViewer)、Dataplex DataScan Viewer (roles/dataplex.dataScanViewer) 或 Dataplex Viewer (roles/dataplex.viewer) 角色：需要此角色才能查看每个提案的置信度分数、测试失败诊断和下游评估记分卡。

配置第三方身份验证提供方

将扩充智能体连接到第三方知识源（例如 Microsoft SharePoint、Atlassian Confluence 和 Jira 或 GitHub）时，您必须使用 Google Cloud的智能体身份服务配置身份验证提供方。

Agent Identity 充当安全凭证管理器，在项目中加密第三方令牌，确保人工操作员在执行任务期间无需处理原始客户端密钥。

如需了解如何为特定外部平台生成所需令牌和配置身份验证提供方的分步说明，请参阅为丰富任务配置外部连接器。

为身份验证提供方设置 IAM 权限

如需允许丰富代理在活跃运行期间安全地动态检索您的身份验证提供方凭据，您必须向代管式 Knowledge Catalog Service Agent (service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com) 授予 Agent Identity Admin (roles/agentidentity.admin) 角色。您可以在身份验证提供方资源级层或项目级层授予此角色。

此外，在Google Cloud 控制台中将身份验证提供方附加到任务的人类用户必须对身份验证提供方拥有 agentidentity.authProviders.get 和 agentidentity.authProviders.setIamPolicy 权限（包含在 Agent Identity Admin (roles/agentidentity.admin) 中）。

准备 Cloud Storage 存储桶

Cloud Storage 是知识丰富化工作流的主要基于文件的暂存、上下文提取和制品导出层。

您可以配置代理，使其从一个或多个输入存储桶、文件夹路径或单个文件中注入文件，以便根据您的企业领域知识进行推理。支持的上下文类型包括：

网域文档和数据字典：Markdown、纯文本、PDF、HTML 或 CSV 文件，其中包含表定义、业务术语库、标准操作程序 (SOP)、数据流水线架构或列命名准则。知识信号配置支持整个存储桶、文件夹路径（例如 bucket-name/folder/）或单个文件路径。我们建议您将这些文档整理到一个专用的 Cloud Storage 存储桶或文件夹中，与评估数据集和不相关的文件分开。
评估数据集：存储种子查询和留出验证查询集的 JSONL 文件。如需了解详情，请参阅本文档的设置评估数据集的格式部分。
参考 SQL 和转换脚本：保存的 SQL 脚本、dbt 模型定义或 ETL 转换逻辑，可提供有关表联接模式和业务计算的情境信号。

配置输出存储桶后，富化代理还可以将结构化 bundle 和运行工件导出到该存储桶。支持的输出工件包括：

详细的评估报告：全面的记分卡，显示每个查询的准确率变化、测试失败诊断和置信度分布指标。

为确保富化代理可以从存储桶中运行，请确保您的执行服务账号具有必要的权限：

向输入存储桶授予 Storage Object Viewer (roles/storage.objectViewer) 角色，以便代理可以读取暂存的文档和配置文件。
（可选）如果您希望代理保存执行工件和验证日志，请在输出存储桶上授予 Storage Object Creator (roles/storage.objectCreator) 角色。

如需向服务账号授予对 Cloud Storage 存储桶的访问权限，请按照以下步骤操作：

如需向存储桶添加 IAM 政策绑定，请使用 gcloud storage buckets add-iam-policy-binding 命令：

在使用下面的命令数据之前，请先进行以下替换：

CUSTOMER_BUCKET：Cloud Storage 存储桶的名称
SERVICE_ACCOUNT_NAME：您的服务账号的名称
TARGET_PROJECT_ID：您的 Google Cloud 项目 ID

执行以下命令：

Linux、macOS 或 Cloud Shell

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Windows (PowerShell)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/storage.objectViewer"

Windows (cmd.exe)

gcloud storage buckets add-iam-policy-binding gs://CUSTOMER_BUCKET ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/storage.objectViewer"

设置评估数据集的格式

扩充工作流可以自动提取信息，而无需示例。不过，提供评估数据集可让智能体自行测试并提高准确率。

您可以提供两种类型的数据集：

精选集：用户问题示例和预期 SQL 查询的列表。智能体会使用此列表进行练习，并撰写更出色的表格摘要。
评估集：用于对代理的表现进行评分的单独问题列表。如果代理表现不佳，此评估集可防止将不佳的更新发布到您的目录。

或者，您也可以提供一个整合的数据集。扩充服务会自动将数据划分为精选集和评估集。

数据集架构要求

评估数据集必须采用 JSONL 文件格式，并存储在 Cloud Storage 中。文件中的每一行都必须包含一个自然语言问题，并配对预期的标准答案 SQL 查询。下表显示了可接受的格式字段：

字段名称	类型	说明
`display_name`	`STRING`	可选。评估请求的标识符或名称。
`evaluation_request.prompt.text`	`STRING`	自然语言问题或用户提示。
`evaluation_request.golden_response.candidate`	`STRING`	标识黄金回答。设置为 `golden`。
`evaluation_request.golden_response.text`	`STRING`	经过验证、可回答问题的标准答案 SQL 查询。自动评分器会将智能体的 SQL 与此查询进行比较。

评估结果的评分方式：基于 Gemini 的自动评分器会检查智能体的最终 SQL 是否与标准答案 SQL 在语义上等效，即是否返回相同的答案。格式和别名差异不会受到处罚。每个问题都会通过或未通过，质量得分即为通过率。标准答案必须是 SQL 查询。不支持自定义指标。

以下代码段展示了一个有效的 .jsonl 评估文件：

{"display_name": "revenue-2026", "evaluation_request": {"prompt": {"text": "What is total revenue for customer C100 in 2026?"}, "golden_response": {"candidate": "golden", "text": "SELECT SUM(amount) FROM `project.dataset.orders` WHERE customer_id = 'C100' AND EXTRACT(YEAR FROM order_date) = 2026;"}}}
{"display_name": "monthly-subscribers", "evaluation_request": {"prompt": {"text": "List active subscribers on monthly billing"}, "golden_response": {"candidate": "golden", "text": "SELECT user_id, email FROM `project.dataset.subscriptions` WHERE status = 'ACTIVE' AND plan_type = 'MONTHLY';"}}}

配置智能体跟踪记录以进行自学

如需让丰富代理自动分析下游 Gemini Enterprise 代理互动或 BigQuery 代理分析表，您可以选择向其提供对应用互动轨迹的读取权限。

通过提取这些轨迹，代理可以执行轨迹挖掘。该智能体可以发现下游智能体因缺少上下文而遇到困难的地方，将频繁的用户问题归类为高影响力的查询类别，并自动整理解决这些差距所需的确切表摘要、列语义和业务术语。

根据您的企业架构，选择以下两种设置方法之一：

使用限定了范围的日志视图进行直接日志记录（推荐）：创建一个仅限于应用遥测数据的日志视图，以授予最小权限读取权限。如需查看相关说明，请参阅本文档的使用限定范围的日志视图进行直接日志记录部分。
BigQuery Agent Analytics：如果贵组织以原生方式将互动日志路由到 BigQuery 日志接收器，请授予对导出的 BigQuery 数据集的读取权限。如需查看相关说明，请参阅本文档的 BigQuery Agent Analytics 部分。

使用限定范围的日志视图直接记录日志（推荐）

为应用启用互动日志记录后，执行日志会直接流式传输到 Logging。您可以创建一个专用日志视图，仅限 Gemini Enterprise 应用的使用情况审核日志，并向执行服务账号授予对该视图的访问权限。由于扩充服务会发出项目级日志读取 (projects/<var>TARGET_PROJECT_ID</var>)，因此仅授予视图级权限是不够的，执行服务账号还必须对拥有 Gemini Enterprise 应用的项目拥有 logging.logEntries.list 和 logging.views.access 权限。如需了解如何为 Gemini Enterprise 应用开启跟踪插桩和提示与回答日志记录，请参阅管理可观测性设置。

创建限定了范围的日志视图，以隔离日志。限定范围的日志视图可确保该视图仅公开 Gemini Enterprise 应用的使用情况审核和推理遥测数据（通过对 logName="projects/<var>TARGET_PROJECT_ID</var>/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/<var>TARGET_PROJECT_ID</var>/logs/discoveryengine.googleapis.com%2Fgen_ai.*" 进行过滤）。如需了解详情，请参阅使用 Cloud Logging 访问 Gemini Enterprise 使用情况审核日志。
gcloud CLI

如需创建限定范围的日志视图，请使用 gcloud logging views create 命令：

在使用下面的命令数据之前，请先进行以下替换：
- LOG_VIEW_NAME：日志视图的名称
- TARGET_PROJECT_ID：拥有 Gemini Enterprise 应用的 Google Cloud 云项目的 ID
执行以下命令：
Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud logging views create LOG_VIEW_NAME \ --project=TARGET_PROJECT_ID \ --location=global \ --bucket=_Default \ --log-filter='logName="projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*"'
Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

gcloud logging views create LOG_VIEW_NAME ` --project=TARGET_PROJECT_ID ` --location=global ` --bucket=_Default ` --log-filter='logName="projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*"'
Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

注意：如果此命令使用 ' 引用内容，请用英文双引号替换这些单引号。如果引用嵌套，请使用 \" 对内部引号进行转义。

gcloud logging views create LOG_VIEW_NAME ^ --project=TARGET_PROJECT_ID ^ --location=global ^ --bucket=_Default ^ --log-filter='logName="projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity" OR logName=~"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*"'
REST

在使用任何请求数据之前，请先进行以下替换：
- LOG_VIEW_NAME：日志视图的名称
- TARGET_PROJECT_ID：拥有 Gemini Enterprise 应用的 Google Cloud 云项目的 ID
HTTP 方法和网址：
POST https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME
请求 JSON 正文：
{ "filter": "logName=\"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgemini_enterprise_user_activity\" OR logName=~\"projects/TARGET_PROJECT_ID/logs/discoveryengine.googleapis.com%2Fgen_ai.*\"" }
如需发送您的请求，请展开以下选项之一：
curl（Linux、macOS 或 Cloud Shell）

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME"
PowerShell (Windows)

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 request.json 的文件中，然后执行以下命令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://logging.googleapis.com/v2/projects/TARGET_PROJECT_ID/locations/global/buckets/_Default/views?viewId=LOG_VIEW_NAME" | Select-Object -Expand Content
您应该会收到一个成功的状态代码 (2xx) 和一个空响应。
创建日志视图后，向执行服务账号授予该视图的 Logs View Accessor (roles/logging.viewAccessor) 角色，并确保该服务账号还对拥有 Gemini Enterprise 应用的项目具有 logging.logEntries.list 权限。

如需向日志视图添加 IAM 政策绑定，请使用 gcloud logging views add-iam-policy-binding 命令：

在使用下面的命令数据之前，请先进行以下替换：
- LOG_VIEW_NAME：日志视图的名称
- SERVICE_ACCOUNT_NAME：您的服务账号的名称
- TARGET_PROJECT_ID：您的 Google Cloud 项目 ID
执行以下命令：
Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud logging views add-iam-policy-binding LOG_VIEW_NAME \
    --location=global \
    --bucket=_Default \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/logging.viewAccessor"
```
Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud logging views add-iam-policy-binding LOG_VIEW_NAME `
    --location=global `
    --bucket=_Default `
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" `
    --role="roles/logging.viewAccessor"
```
Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。
```
gcloud logging views add-iam-policy-binding LOG_VIEW_NAME ^
    --location=global ^
    --bucket=_Default ^
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@TARGET_PROJECT_ID.iam.gserviceaccount.com" ^
    --role="roles/logging.viewAccessor"
```

如需了解详情，请参阅在日志存储桶中配置日志视图。

BigQuery Agent Analytics

如果贵组织使用 Logging 日志接收器将互动日志流式传输到 BigQuery，或直接写入 BigQuery Agent Analytics 表，则您可以改为授予对数据集的访问权限。

确保互动日志已配置为流式传输到指定的 BigQuery 数据集，并验证执行服务账号是否已获得代理分析表（或其数据集）的 BigQuery Data Viewer (roles/bigquery.dataViewer) 角色，以及包含该表的项目的 BigQuery Job User (roles/bigquery.jobUser) 角色。这些角色可让代理运行查询作业，并直接从 BigQuery 读取导出的遥测数据。

如需详细了解如何导出日志，请参阅将日志路由到支持的目标位置。

启用数据分析和数据洞见

在运行丰富化任务之前，我们建议您对常用的目标表启用数据分析和 AI 数据洞见。数据分析可提供统计特征（例如常见值、数据分布和 null 值计数），而数据洞见可生成基准表说明和示例查询。提供这些信号有助于丰富代理生成更准确的元数据建议。

如需详细了解如何配置数据分析扫描，请参阅创建和使用数据分析扫描。
如需详细了解如何生成 AI 数据洞见，请参阅将数据洞见用于结构化数据。

后续步骤

创建丰富化任务

配置丰富化任务的前提条件 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

必需的 API 详情

配置客户代管式服务账号

Google Cloud CLI

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

向用户授予所需的 IAM 角色

配置第三方身份验证提供方

为身份验证提供方设置 IAM 权限

准备 Cloud Storage 存储桶

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

设置评估数据集的格式

数据集架构要求

配置智能体跟踪记录以进行自学

使用限定范围的日志视图直接记录日志（推荐）

gcloud CLI

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

BigQuery Agent Analytics

启用数据分析和数据洞见

后续步骤

配置丰富化任务的前提条件