利用 Knowledge Catalog 元数据奠定数据基础

1. 简介

生成式 AI 模型是强大的推理器，但缺乏机构背景。如果高管问 AI 智能体“我们的第一季度收入是多少？”，智能体可能会在您的数据湖中找到数十个名为“收入”的表。有些是严谨的财务报告，有些是实时营销估算，还有许多可能是已废弃的沙盒。

如果没有明确的依据，AI 智能体将根据简单的名称相似性选择表，从而导致根据未经验证的数据得出“令人信服的错误”答案。

此 Codelab 是一个由两部分组成的系列教程的第一部分，将探讨如何构建治理感知型 AI 智能体。

在第一部分中，您将构建数据基础。您将在 BigQuery 中设置一个真实的“杂乱”数据湖，应用严格的元数据标记（Knowledge Catalog 切面）来区分有效数据和噪声，并使用 Antigravity (AGY) CLI 在本地测试智能体是否严格遵循您的数据治理规则。

您可以阅读本系列的第二部分，其中介绍了如何使用 Model Context Protocol (MCP) 和 Cloud Run 将本地智能体原型部署到安全的企业级 Web 应用中。👉 阅读第 2 部分

学习内容

• 使用设置脚本部署真实的多层数据湖。
• 在 Knowledge Catalog 中设计和注册自定义元数据模板（切面类型），以区分官方数据产品和原始沙盒表。
• 在编写任何应用代码之前，使用 AGY CLI 在本地验证数据治理规则。

所需条件

• 启用了结算功能的 Google Cloud 项目。
• 对 Google Cloud Shell 的访问权限（AGY CLI 预安装在 Cloud Shell 中）。
• 对 BigQuery 和 Knowledge Catalog 的基本了解和熟悉程度。

主要概念

• Knowledge Catalog ：统一的元数据管理服务。我们使用它通过业务背景（治理）来丰富技术元数据（架构）。
• 切面类型: 结构化元数据模板。与自由文本标记不同，切面会强制执行强类型（枚举、布尔值），使其能够可靠地供机器评估。

2. 设置和要求

启动 Cloud Shell

虽然可以通过笔记本电脑对 Google Cloud 进行远程操作，但在此 Codelab 中，您将使用 Google Cloud Shell，这是一个在云端运行的命令行环境。

在 Google Cloud 控制台 中，点击右上角工具栏中的 Cloud Shell 图标：

预配和连接到环境应该只需要片刻时间。完成后，您应该会看到如下内容：

这个虚拟机已加载了您需要的所有开发工具。它提供了一个持久的 5 GB 主目录，并且在 Google Cloud 中运行，大大增强了网络性能和身份验证功能。您在此 Codelab 中的所有工作都可以在浏览器中完成。您无需安装任何程序。

初始化环境

打开 Cloud Shell 并设置项目变量，以确保所有命令都以正确的基础架构为目标。

export PROJECT_ID=$(gcloud config get-value project)
gcloud config set project $PROJECT_ID
export REGION="us-central1"

启用 API

启用必要的 Google Cloud 服务以执行以下说明。

gcloud services enable \
  bigquery.googleapis.com \
  dataplex.googleapis.com

克隆存储库

从 GitHub 存储库获取基础架构代码和自动化脚本。为了节省 Cloud Shell 中的磁盘空间，我们只会下载本实验所需的特定文件夹。

# 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 we need for this lab
git sparse-checkout set data-analytics/governance-context
cd data-analytics/governance-context

构建“杂乱”数据湖

现实世界的数据环境很少是干净的。为了模拟现实，我们需要混合使用“官方”数据集市和不受信任的“沙盒”表。

我们将使用设置脚本来部署 BigQuery 数据集和表。

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

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

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

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

现在，我们将定义一些数据治理规则。在 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 governance agents." \
    --display-name="Official Data Product Spec" \
    --metadata-template-file-name="aspect_template.json"

4. 应用治理

这是关键的工程步骤。目前，表 finance_mart.fin_monthly_closing_internal 和 analyst_sandbox.tmp_data_dump_v2_final_real 对于 LLM 来说看起来完全相同。它们只是包含列的对象。

作为治理工程师，您必须将 切面（经过认证的元数据标签）附加到这些表，以区分它们。在实际企业中，您可以通过 CI/CD 流水线自动执行此操作。我们将使用脚本模拟该自动化。

生成治理载荷

Knowledge Catalog 切面键必须具有全局唯一性（以您的项目 ID 为前缀）。./generate_payloads.sh 脚本将动态生成 YAML 元数据文件。

chmod +x ./generate_payloads.sh
./generate_payloads.sh

输出：

这将创建一个文件夹“./aspect_payloads”，其中包含 4 个 YAML 文件，用于定义治理场景（Gold/Internal、Gold/Public、Silver/Realtime、Bronze/Sandbox）。

使用 CLI 应用切面

在运行脚本之前，我们先来看看实际应用的内容，以揭开该过程的神秘面纱。运行以下命令以查看内部财务载荷的结构：

cat aspect_payloads/fin_internal.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

请注意此 YAML 如何明确定义业务背景，例如设置 is_certified: true 标志和分配 GOLD_CRITICAL 层级。为 LLM 提供清晰的结构化规则以进行评估，而不是仅仅根据表名称进行猜测。

现在，运行应用脚本。这将遍历 BigQuery 表并执行 gcloud dataplex entries update 命令以附加此严格的元数据。

chmod +x ./apply_governance.sh
./apply_governance.sh

验证（可选）

在继续之前，请验证元数据是否已在控制台中正确应用。

1. 在 Google Cloud 控制台中打开 Knowledge Catalog 页面。如果您在左侧导航菜单中没有看到“Knowledge Catalog”，请使用 Google Cloud 控制台窗口顶部的搜索栏，输入“Knowledge Catalog”，然后选择“热门结果”或“产品和页面”下的结果。
2. 搜索 fin_monthly_closing_internal。您应该会在结果中看到列出的 BigQuery 表。点击表名称以进入其详情页面。

3. 在表的详情页面上，找到底部的“可选标记和切面”部分。
4. 您将找到 official-data-product-spec 切面。确认值与我们应用的“Gold Internal”场景匹配。

您现在已确认，在技术上相同的 BigQuery 表（fin_monthly_closing_internal 和 tmp_data_dump_v2_final_real）在逻辑上通过机器可读的元数据进行区分。

5. 配置智能体并进行原型设计

在构建应用（我们将在第 2 部分中执行此操作）之前，我们将在本地验证数据治理逻辑。我们需要安装 Knowledge Catalog 插件 并配置智能体技能。

安装扩展程序

在 Cloud Shell 中，安装 Knowledge Catalog 插件。系统会要求您确认并提供设置详细信息。

export DATAPLEX_PROJECT="${PROJECT_ID}"

agy plugin install https://github.com/gemini-cli-extensions/dataplex

检查智能体技能

智能体技能是位于 .agents/skills/knowledge_catalog_governance/SKILL.md 中的静态可重复使用定义文件。它包含将抽象的人工规则（例如“我需要安全数据”）转换为严格的技术查找的逻辑。

检查该文件以了解我们教给 AI 的算法：

cat .agents/skills/knowledge_catalog_governance/SKILL.md

请注意，它明确指示模型遵循严格的第 1 阶段（元数据验证）和第 2 阶段（查询执行）循环。模型必须先发现并验证元数据，然后才能构建任何 SQL。

启动智能体并测试场景

启动 AGY CLI 会话。它会自动从 .agents/skills 目录中发现并加载技能。

agy

注意：您可能会看到加载了多个上下文文件。这种情况很正常。CLI 会加载此项目的特定规则的本地技能，以及 Knowledge Catalog 插件本身的默认说明。

验证安装

输入 /mcp 以确认 Knowledge Catalog 插件处于活跃状态。您应该会看到 knowledge-catalog 列为活跃插件及其可用工具。

/mcp

预期输出：

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

测试场景（原型设计）

将以下提示逐个粘贴到正在运行的智能体会话中，以验证其是否遵循您的规则。

💡 提示：如果系统提示，请选择“2. Yes, and always allow ‘knowledge-catalog/search_entries' in this conversation”（是，并在此对话中始终允许“knowledge-catalog/search_entries”），以启用顺畅的测试。

• 场景 A（认证 CFO 的数据）：

"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?"

预期： 智能体从其工具中自动发现您的活跃项目和区域，查询 fin_monthly_closing_internal，因为它在切面中与 GOLD_CRITICAL（准确）和 INTERNAL_ONLY（董事会会议）在语义上匹配，并推荐它。

• 场景 B（公开披露）：

"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?"

预期： 智能体必须绕过每月内部表，并严格选择 fin_quarterly_public_report，因为它是唯一标记为 EXTERNAL_READY 的资产。

• 场景 C（运营需求）：

"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?"

预期： 智能体选择 mkt_realtime_campaign_performance，因为它识别出 REALTIME_STREAMING 更新频率，优先于财务数据的 GOLD_CRITICAL 层级。

• 场景 D（沙盒实验）：

"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."

预期： 智能体选择 tmp_data_dump_v2_final_real，因为它在切面中与 BRONZE_ADHOC（原始数据）和 is_certified: false（沙盒环境）在语义上匹配。

（如需退出 AGY 会话，请输入 /exit 或 /quit）

6. 恭喜！接下来做什么？

您已成功构建受治理的数据基础，并证明 AI 可以使用本地 CLI 原型严格遵循您的元数据规则！

现在，您已到达检查点。请选择下一步：

选项 A：我想立即继续学习第 2 部分！

如果您已准备好使用 Model Context Protocol (MCP) 和 Cloud Run 将此本地原型转换为安全的生产级 Web 应用：

👉 链接到第 2 部分 Codelab

⚠️ 停止： 请勿运行下面的清理步骤。您需要当前数据和 Knowledge Catalog 设置才能完成第 2 部分！

选项 B：我稍后会学习第 2 部分，或者我只想完成第 1 部分。

如果您想今天停止并避免云费用，则应清理资源。

不用担心！在第 2 部分中，我们将提供一个“快速通道脚本”，该脚本将在短短 2 分钟内为您完全重建此第 1 部分环境，以便您从上次中断的地方继续学习。

👉 前往清理部分。

7. 清理（仅适用于选项 B）

如果要就此停止，请销毁资源以避免产生费用。

销毁数据湖

如果您当前处于 AGY CLI 会话中，请按两次 Ctrl+C 或输入 /quit 以退出会话。然后，运行以下命令：

chmod +x ./cleanup_data_lake.sh
./cleanup_data_lake.sh

卸载 AGY CLI 插件并移除本地文件

agy plugin uninstall dataplex
cd ~
rm -rf ~/devrel-demos