Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 Antigravity CLI 测试数据上下文

AI 智能体可以推理，但它们对您的特定公司一无所知。假设您向智能体提问：“我们第一季度的收入是多少？”如果没有指导，智能体可能会从数据库中数十个名为“收入”的表中进行选择，这些表涵盖了从官方报告到杂乱的测试数据。如果智能体选择的表名称最相似，则可能会根据未经证实的来源返回令人信服的错误答案。

元数据扩充是解决此上下文问题的关键。在本教程中，您将设置切面，这些切面提供此上下文，并使用 Antigravity CLI 测试数据上下文，验证智能体是否可以准确地根据可信的认证数据来回答问题。

目标

部署一个真实的、多层级的数据湖以进行测试。
在 Knowledge Catalog 中设计和注册自定义元数据模板 (切面类型)，以区分官方数据产品与原始沙盒表。
使用 Antigravity CLI (agy) 验证数据治理规则。

准备工作

在开始之前，请确保完成以下操作：

为此教程选择一个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

克隆 Google Cloud DevRel Demos 代码库。

从 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 数据集和表。

将设置脚本设为可执行，然后运行它。这会创建三个 BigQuery 数据集（finance_mart、marketing_prod、analyst_sandbox），并使用示例数据填充其表：

chmod +x ./setup_bq_tables.sh
./setup_bq_tables.sh

您现在拥有一个完全填充但不受治理的数据湖。对于 AI 智能体，每个表看起来都完全相同。

创建数据治理模板（切面类型）

现在，您需要定义数据治理规则。如需在 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。这可确保元数据保持结构化和机器可读。

注册切面类型

运行以下 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）。

使用 CLI 应用切面

在运行脚本之前，请查看要附加到表的数据。运行以下命令，查看内部财务数据的元数据：
```
cat aspect_payloads/fin_internal.yaml
```
YAML 文件定义了表的业务上下文：
```
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 控制台中打开 Knowledge Catalog 页面。您可以使用顶部的搜索栏来查找它。
搜索 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 插件并配置智能体技能。

安装服务插件

在 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

验证安装

在 Antigravity CLI 提示符中，确认插件处于活动状态。输入 /mcp 以列出已配置的工具和插件：

/mcp

输出应显示 knowledge-catalog 列为活动插件及其可用工具：

MCP Servers ... >  ✓ knowledge-catalog  Tools: search_entries, lookup_context, lookup_entry

试试看

现在，您可以查看数据上下文的实际应用了。将这些提示逐个粘贴到 Antigravity CLI 会话中。

场景 1：查找“Gold”标准数据

查看 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

总结

您已构建坚实的数据基础，使用元数据应用严格的上下文，并验证了所有内容都在本地使用 Antigravity CLI 正常运行。

后续步骤

尝试其他 Knowledge Catalog 应用场景。

使用 Antigravity CLI 测试数据上下文 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

目标

准备工作

准备环境

构建示例数据湖

创建数据治理模板（切面类型）

检查切面架构

注册切面类型

应用数据治理

生成数据治理载荷

使用 CLI 应用切面

验证元数据

使用 Antigravity CLI 测试数据上下文

安装服务插件

检查智能体技能

启动 Antigravity CLI 并测试场景

验证安装

试试看

场景 1：查找“Gold”标准数据

场景 2：公开披露

场景 3：实时运营需求

场景 4：沙盒探索

清理

总结

后续步骤

使用 Antigravity CLI 测试数据上下文