借助 Knowledge Catalog（以前称为 Dataplex Universal Catalog）中的元数据丰富功能，您可以提供结构化数据上下文，以便 AI 智能体能够基于可信、经过认证的来源提供回答。在本教程中，您将向示例 BigQuery 表附加自定义切面，并使用 Antigravity CLI 测试 AI 智能体如何应用治理规则。
目标
- 在 BigQuery 中部署一个真实的多层数据湖，以供测试。
- 在 Knowledge Catalog 中设计和注册自定义元数据模板（切面类型），以区分官方数据产品和原始沙盒表。
- 使用 Antigravity CLI (
agy) 验证数据治理规则和 AI 智能体接地。
准备工作
在开始之前，请务必执行以下操作：
- 请为本教程选择一个 Google Cloud 项目。
- 确认您的项目已启用结算功能。
如需完成本教程，您还应基本了解 BigQuery 和 Knowledge Catalog。
准备环境
本教程使用 Google Cloud Shell，它是在云端运行的命令行环境。Antigravity CLI (agy) 已预安装在 Google Cloud Shell 中。
在 Google Cloud 控制台中，点击右上角工具栏中的激活 Cloud Shell。预配并连接到环境需要一些时间。
在 Cloud Shell 中，设置
PROJECT_ID和REGION变量，以便后续所有命令都以您的特定 Google Cloud 项目为目标。export PROJECT_ID=$(gcloud config get-value project) gcloud config set project $PROJECT_ID export REGION="us-central1"启用必要的 Google Cloud 服务。
gcloud services enable \ artifactregistry.googleapis.com \ bigquery.googleapis.com \ dataplex.googleapis.com \ aiplatform.googleapis.com \ run.googleapis.com \ cloudbuild.googleapis.com \ iam.googleapis.com-
从 GitHub 下载基础架构代码和脚本。使用稀疏结账功能，仅拉取本教程所需的特定文件夹。
# Perform a shallow clone to get only the latest repository structure without the full history git clone --depth 1 --filter=blob:none --sparse https://github.com/GoogleCloudPlatform/devrel-demos.git cd devrel-demos # Specify and download only the folder you need for this tutorial git sparse-checkout set data-analytics/governance-context cd data-analytics/governance-context
在 BigQuery 中部署示例数据湖
现实世界中的数据环境很少是干净的。AI 智能体可以进行推理，但它们一开始对贵公司的具体情况一无所知。想象一下，您向智能体询问：“我们第一季度的收入是多少？”如果没有指导，代理可能会从数据库中名为“revenue”的数十个表中进行选择，这些表涵盖了从官方报告到原始测试数据的各种内容。如果智能体选择了名称听起来最接近的表，则可能会根据未经核实的来源返回看似正确但实际错误的回答。
为了模拟这种情况，您需要混合使用“官方”数据集市和不受信任的“沙盒”表。您可以使用设置脚本来部署 BigQuery 数据集和表。
将设置脚本设为可执行，然后运行它。此操作会创建三个 BigQuery 数据集（finance_mart、marketing_prod、analyst_sandbox），并使用示例数据填充其表：
chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh
现在，您拥有了一个数据已完全填充但未治理的数据湖。对 AI 智能体来说，每个表看起来都完全一样。
在 Knowledge Catalog 中定义自定义切面类型
现在，您需要定义数据治理规则。如需在 Knowledge Catalog 中执行此操作，您需要创建一个切面类型，这是一种可重复使用的强类型元数据模板。
在本部分中，您将使用 gcloud CLI 注册此模板，以便查看其定义。
检查切面模板架构
输出 aspect_template.json 的内容以查看架构定义：
cat aspect_template.json
它会显示以下 JSON 结构：
{
"name": "OfficialDataProductSpec",
"type": "record",
"recordFields": [
{
"name": "product_tier",
"type": "enum",
"enumValues": [
{ "name": "GOLD_CRITICAL", "index": 1 },
{ "name": "SILVER_STANDARD", "index": 2 },
{ "name": "BRONZE_ADHOC", "index": 3 }
],
...
},
{
"name": "is_certified",
"type": "bool",
"...": "..."
}
]
}
请注意，此架构如何强制执行严格的数据类型，例如针对关键性层级（GOLD_CRITICAL、SILVER_STANDARD、BRONZE_ADHOC）使用 enum，针对 is_certified 使用 bool。这可确保元数据保持结构化和机器可读。
在 Knowledge Catalog 中注册切面类型
运行以下 gcloud 命令，在 Knowledge Catalog 注册表中注册此模板：
gcloud dataplex aspect-types create official-data-product-spec \
--location="${REGION}" \
--project="${PROJECT_ID}" \
--description="Defines the comprehensive profile of a data product for data governance agents." \
--display-name="Official Data Product Spec" \
--metadata-template-file-name="aspect_template.json"
将治理切面附加到数据湖表
这是关键的工程步骤。目前，表 finance_mart.fin_monthly_closing_internal 和 analyst_sandbox.tmp_data_dump_v2_final_real 在 AI 智能体看来完全相同。它们只是具有列的对象。
为了区分它们，您需要应用切面，为这些表附加经过认证的元数据标签，以便加以区分。在实际企业环境中，您会使用 CI/CD 流水线自动执行此操作。在本教程中，您将使用脚本模拟该自动化过程。
生成切面元数据载荷
Knowledge Catalog 切面键必须具有全局唯一性（以您的项目 ID 为前缀）。./generate_payloads.sh 脚本会动态生成 YAML 元数据文件：
chmod +x ./generate_payloads.sh
./generate_payloads.sh
此操作会创建一个 aspect_payloads/ 目录，其中包含 4 个 YAML 文件，分别定义了不同的数据治理场景（fin_internal.yaml、fin_public.yaml、mkt_realtime.yaml、sandbox.yaml）。
将切面附加到 BigQuery 表
在运行脚本之前，请先查看要附加到表中的数据。运行以下命令，查看内部财务数据的元数据：
cat aspect_payloads/fin_internal.yamlYAML 文件定义了表的业务上下文：
your-project-id.us-central1.official-data-product-spec: data: product_tier: GOLD_CRITICAL data_domain: FINANCE usage_scope: INTERNAL_ONLY update_frequency: DAILY_BATCH is_certified: true请注意，此提示如何明确定义业务情境，例如设置
is_certified: true并分配GOLD_CRITICAL层级。这为 AI 智能体提供了清晰、结构化的规则来进行评估，而不是根据表名称进行猜测。运行应用脚本。此脚本会遍历您的 BigQuery 表，并使用
gcloud dataplex entries update命令将元数据载荷附加到每个表：chmod +x ./apply_governance.sh ./apply_governance.sh
在 Google Cloud 控制台中验证应用的切面
在继续操作之前，请在 Google Cloud 控制台中检查脚本是否正确应用了切面：
- 在 Google Cloud 控制台中打开知识目录页面。您可以使用顶部的搜索栏找到该扩展程序。
- 搜索
fin_monthly_closing_internal。 在结果中选择 BigQuery 表名称，打开其详情页面。 - 在底部的可选标记和切面部分中，找到
official-data-product-spec切面。确认这些值与您应用的“Gold Internal”场景相符。
现在，您已确认技术上相同的 BigQuery 表（fin_monthly_closing_internal 和 tmp_data_dump_v2_final_real）在逻辑上通过机器可读的元数据进行区分。
使用 Antigravity CLI 测试数据上下文
在构建应用之前，您可以使用 Antigravity CLI 在本地验证数据治理逻辑。为此，您需要安装 Knowledge Catalog 插件并配置代理技能。
安装 Knowledge Catalog 插件
在 Cloud Shell 中，安装服务插件：
export DATAPLEX_PROJECT="${PROJECT_ID}"
agy plugin install https://github.com/gemini-cli-extensions/dataplex
检查智能体技能定义
智能体技能是一个静态、可重复使用的定义文件，位于 .agents/skills/knowledge-catalog-governance/SKILL.md 中。它包含将抽象的人类规则（例如“我需要安全的数据”）转换为结构化技术查询的逻辑。
如需检查技能设置并了解数据上下文的工作原理，请检查 SKILL.md 文件：
cat .agents/skills/knowledge-catalog-governance/SKILL.md
请注意，它会指示模型遵循严格的第 1 阶段（元数据验证）和第 2 阶段（查询执行）循环。模型必须先发现并验证元数据，然后才能构建任何 SQL 语句。这种“搜索优先”逻辑可防止代理猜测表名称或根据未经证实的信息源给出虚假回答。
启动 Antigravity CLI 会话
启动 Antigravity CLI 会话。由于您位于项目文件夹中，CLI 会自动发现并从 .agents/skills 目录加载技能：
agy
在 CLI 中验证插件安装
在 Antigravity CLI 提示中，确认插件处于活跃状态。输入 /mcp 以列出已配置的工具和插件：
/mcp
输出内容应显示 knowledge-catalog 已列为有效插件，并显示其可用工具：
MCP Servers ... > ✓ knowledge-catalog Tools: search_entries, lookup_context, lookup_entry
运行数据上下文验证场景
现在，您可以查看数据上下文的实际应用了。将这些提示逐一粘贴到 Antigravity CLI 会话中。
场景 1：检索经过认证的黄金级数据
看看 Antigravity CLI 能否为一场重要的董事会会议找到最可靠的数据：
We are preparing the deck for an internal Board of Directors meeting next week. I need the numbers to be absolutely finalized, trustworthy, and kept strictly confidential. Which table is safe to use?
CLI 应跳过原始数据并找到 fin_monthly_closing_internal。为此，它会将您对“最终确定”和“机密”数据的请求与您之前应用的 GOLD_CRITICAL 和 INTERNAL_ONLY 标记进行匹配。
场景 2：仅检索外部批准的数据
假设您想在外部共享数据。您希望确保 CLI 不会泄露任何内部机密：
I need to share our quarterly financial summary with an external consulting firm. It is critical that we do not leak any raw or internal metrics. Which dataset is officially scrubbed and explicitly approved for external sharing?
即使内部表包含最详细的信息，CLI 也必须绕过它。它应该会指向 fin_quarterly_public_report，因为它是唯一一个标记为 EXTERNAL_READY 的表。
场景 3：检索实时流式数据
数据科学家通常需要绝对最新的信息。看看 Antigravity CLI 是否能区分每日批处理和直播：
My dashboard needs to show what's happening right now with our ad spend. I can't wait for the overnight load. What do you recommend?
CLI 应找到 mkt_realtime_campaign_performance。它用于标识元数据中的 REALTIME_STREAMING 更新频率。
场景 4：探索未经认证的沙盒数据
有时，“足够好”比“完美”更好。查看 Antigravity CLI 能否找到一些实验性机器学习工作的原始沙盒数据：
I'm just playing around with some new ML models and need a lot of raw data. It doesn't need to be perfect, just a sandbox environment.
CLI 应找到 tmp_data_dump_v2_final_real。它知道这是正确的选择，因为它与 BRONZE_ADHOC 层级匹配，并且明确标记有 is_certified: false。
完成测试后，您可以退出 CLI 会话：
/quit
清理
请按照以下步骤操作，以免产生周期性费用：
如果您处于 Antigravity CLI 会话中，请按
Ctrl+C两次或输入/quit退出会话。执行清理脚本，销毁本教程中创建的 BigQuery 表、数据集和 Knowledge Catalog 方面类型：
chmod +x ./cleanup_data_lake.sh ./cleanup_data_lake.sh卸载服务插件并移除本地演示文件：
agy plugin uninstall dataplex cd ~ rm -rf ~/devrel-demos
后续步骤
- 尝试其他 Knowledge Catalog 应用场景。