使用 Gemini CLI 代理测试数据上下文

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

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

目标

  • 创建用于测试的真实数据湖。
  • 使用 Knowledge Catalog 方面标记“黄金”数据，以便将其与测试数据区分开。
  • 使用 Gemini CLI 在本地测试数据上下文。

准备工作

在开始之前，请务必执行以下操作：

如需完成本教程，您还应基本了解 BigQuery、Knowledge Catalog 和 Terraform。

准备环境

本教程使用 Google Cloud Shell，它是在云端运行的命令行环境。

  1. 在 Google Cloud 控制台中，点击右上角工具栏中的激活 Cloud Shell。预配并连接到环境需要一些时间。

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

  3. 启用必要的 Google Cloud 服务。

    gcloud services enable \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.googleapis.com

  4. 克隆 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

构建数据湖

为了使情况更贴近现实，您需要混合使用官方数据和不可信的杂乱数据。使用 Terraform 和教程代码库中预配置的 Terraform 配置文件可快速完成此设置。

Terraform 配置可处理两项任务：

  • 设置 Knowledge Catalog 切面类型（元数据模板）、BigQuery 数据集和表，包括 finance_mart.fin_monthly_closing_internal 和 analyst_sandbox.tmp_data_dump_v2_final_real。
  • 将示例数据加载到表中。

  1. 打开 terraform 目录并对其进行初始化。

    cd terraform
terraform init

  2. 应用配置。 此过程最多可能需要 1 分钟。

    terraform apply -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

现在，您就拥有了一个不受管控的数据湖！对于 AI 智能体，数据湖中的表看起来完全相同，因为它们只是具有列的对象。如需修正此问题，您需要在下一步中应用治理。

应用治理

这是设置过程中最重要的部分。目前，对于 AI 智能体，这两个表格看起来完全相同。为了区分它们，您需要应用切面，这些切面类似于经过认证的元数据标签，可为代理提供所需的上下文。在本部分中，您将使用两个脚本：一个用于生成元数据，另一个用于将元数据应用于表。

生成治理载荷

Terraform 已设置切面类型，现在您需要生成数据来填充这些切面类型。

运行 ./generate_payloads.sh 脚本以创建 aspect_payloads/ 目录。该目录包含四个 YAML 文件，用于定义不同的治理方案，您将在下一步中应用这些文件。

返回到教程目录的根目录，然后运行 ./generate_payloads.sh 脚本：

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

应用切面

  1. 在运行 apply_governance.sh 脚本之前，请先查看将附加到表中的数据。运行以下命令，查看为内部财务数据定义的元数据：

    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 智能体提供了清晰的结构化规则，以便其遵循。

  2. 运行 apply_governance.sh 脚本： 此脚本会遍历您的 BigQuery 表，并使用 gcloud CLI 将 YAML 载荷中的元数据“标记”到每个表中。

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

验证元数据

在继续操作之前，请检查脚本是否正确应用了方面。

  1. 在 Google Cloud 控制台中打开知识目录页面。您可以使用顶部的搜索栏找到该扩展程序。
  2. 搜索 fin_monthly_closing_internal。 在结果中选择表名称，以打开其详情页面。
  3. 在可选的标记和切面部分中，找到 official-data-product-spec 切面。确认这些值与您应用的“Gold Internal”方案一致。

现在，您已成功使用元数据来区分这些表，并为 AI 智能体提供了相应的方法。

使用 Gemini CLI 测试数据上下文

在构建完整的 Web 应用之前，您可以使用 Model Context Protocol (MCP) 环境在本地测试治理逻辑。在此设置中，Gemini CLI 充当客户端（您与之对话的界面），而 Knowledge Catalog 扩展程序充当本地服务器。

安装 Knowledge Catalog 扩展程序

在 Cloud Shell 中，安装 Knowledge Catalog 扩展程序。

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

定义规则

GEMINI.md 配置文件包含将“我需要安全数据”等声明性规则转换为精确搜索的逻辑，这些搜索只会返回具有正确治理标签的表。

目前，配置文件只是一个模板。您需要将特定的 Google Cloud 项目 ID 添加到规则中，以便在运行 CLI 时，它能正确定位受治理的数据。

  1. 将 PROJECT_ID 添加到配置文件中。

    envsubst < GEMINI.md > GEMINI.md.tmp && mv GEMINI.md.tmp GEMINI.md

  2. 如需检查您的更改并了解数据上下文的工作方式，请快速查看 GEMINI.md 文件：

    cat GEMINI.md

    请注意，该文件将规则拆分为第 1 阶段和第 2 阶段。这会强制执行严格的操作顺序。代理必须先查找正确的数据治理标签（第 1 阶段），然后才能访问数据本身（第 2 阶段）。这种“先搜索”的逻辑可防止代理猜测表名称或根据未经证实的来源生成虚假回答。

    确保第 2 阶段包含您的实际 Google Cloud 项目 ID。如果此设置不正确，代理将不知道在哪里查找您的数据。

启动 Gemini CLI 并测试场景

开始新的 Gemini 会话。由于您位于项目文件夹中，因此 CLI 会自动检测并加载本地 GEMINI.md 作为系统上下文。

gemini

验证安装

确认 Knowledge Catalog 扩展程序处于有效状态。dataplex 应显示在已配置的 MCP 服务器工具列表中。

/mcp desc

试试看

现在，我们来看看数据上下文的实际应用。将这些提示逐个粘贴到 CLI 中。

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

看看 Gemini 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：实时运营需求

数据科学家通常需要最新的信息。看看 Gemini 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：沙盒探索

有时，“足够好”比“完美”更好。查看 Gemini 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

清理

为避免产生周期性扣款，请按照以下步骤操作：

  1. 销毁 Terraform 资源。

    cd ~/devrel-demos/data-analytics/governance-context/terraform
terraform destroy -var="project_id=${PROJECT_ID}" -var="region=${REGION}" -auto-approve

  2. 卸载 Knowledge Catalog 扩展程序并移除本地演示文件。

    gemini extensions uninstall dataplex
cd ~
rm -rf ~/devrel-demos

总结

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