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

使用 Antigravity CLI 测试数据上下文

AI 智能体可以推理，但一开始对贵公司的具体情况一无所知。假设您向智能体询问“我们第一季度的收入是多少？”如果没有指导，代理可能会从数据库中数十个名为“收入”的表格中进行选择，这些表格的数据范围从正式报告到杂乱的测试数据不等。如果代理选择名称最接近的表，则可能会根据未经验证的来源返回令人信服的错误答案。

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

目标

在 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

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

将设置脚本设为可执行，然后运行该脚本。这会创建三个 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 命令，在知识目录注册表中注册此模板：

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.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 控制台中正确应用方面：

在 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 应用场景。

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

目标

准备工作

准备环境

在 BigQuery 中部署示例数据湖

在 Knowledge Catalog 中定义自定义切面类型

检查方面模板架构

在 Knowledge Catalog 中注册切面类型

将治理方面附加到数据湖表

生成方面元数据载荷

将方面附加到 BigQuery 表

在 Google Cloud 控制台中验证应用方面

使用 Antigravity CLI 测试数据上下文

安装 Knowledge Catalog 插件

检查代理技能定义

启动 Antigravity CLI 会话

在 CLI 中验证插件安装

运行数据上下文验证方案

场景 1：检索已获认证的黄金级数据

场景 2：将检索范围限制为外部批准的数据

场景 3：检索实时流式数据

场景 4：探索未认证的沙盒数据

清理

后续步骤

使用 Antigravity CLI 测试数据上下文