使用 Dataplex 元数据构建数据基础

1. 简介

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

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

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

在第一部分中，您将构建数据基础。您将在 BigQuery 中设置一个真实的“杂乱”数据湖，应用严格的元数据标记 (Dataplex Aspect) 以区分有效数据和噪声，并使用 Gemini CLI 在本地测试 LLM 是否严格遵循您的治理规则。

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

前提条件

启用了结算功能的 Google Cloud 项目。
对 BigQuery、 Dataplex Universal Catalog 和 Terraform 有基本的了解和熟悉。
能够访问 Google Cloud Shell。

学习内容

使用 Terraform 部署真实的多层数据湖。
在 Dataplex 中设计严格的元数据模板（Aspect 类型），以区分官方数据产品和原始沙盒表。
在编写任何应用代码之前，使用 Gemini CLI 在本地验证治理规则。

所需条件

能够访问 Google Cloud Shell
Terraform（预安装在 Cloud Shell 中）。
Gemini CLI（预安装在 Cloud Shell 中）。

重要概念

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

2. 设置和要求

启动 Cloud Shell

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

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

激活 Cloud Shell

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

Google 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 \
  artifactregistry.googleapis.com \
  bigqueryunified.googleapis.com \
  cloudaicompanion.googleapis.com \
  cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com \
  datacatalog.googleapis.com \
  run.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

构建“杂乱”数据湖

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

我们将使用 Terraform 部署此环境。该配置处理两项任务：

基础架构 ：创建 Dataplex Aspect 类型和 BigQuery 数据集/表。
数据加载 ：运行 BigQuery INSERT 作业，以便在创建后立即使用示例数据填充表。

导航到 terraform 目录并对其进行初始化。

cd terraform
terraform init

应用配置。这最多可能需要 1 分钟的时间。

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

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

3. 应用治理

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

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

生成治理负载

Dataplex Aspect 键必须是全局唯一的（以您的项目 ID 为前缀）。./generate_payloads.sh 脚本将动态生成 YAML 元数据文件。

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

输出：

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

通过 CLI 应用 Aspect

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

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 层。为 AI 提供清晰的结构化规则以进行评估，而不是仅仅根据表名称进行猜测。

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

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

验证（可选）

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

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

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

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

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

在构建 Web 应用（我们将在第 2 部分中完成此操作）之前，我们将在本地验证治理逻辑。我们需要安装 Dataplex 扩展程序并配置系统提示。

安装扩展程序

在 Cloud Shell 中，安装 Dataplex 扩展程序。系统会要求您确认并提供设置详细信息。

export DATAPLEX_PROJECT="${PROJECT_ID}"

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

（输入 Y 以接受安装，并在系统提示时输入您的项目 ID）。

定义政策文件

GEMINI.md 文件包含将抽象的人为规则（例如“我需要安全数据”）转换为严格的技术查找的逻辑。

此文件目前是通用的。智能体需要确切知道要搜索哪个 Google Cloud 项目，以防止其从公共互联网或其他背景中幻觉表。

将 PROJECT_ID 注入到政策文件中。

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

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

cat GEMINI.md

请注意此文件中的两点：

项目范围 ：检查第 2 阶段。确保 projectid:${PROJECT_ID} 已替换为您的实际项目 ID (e.g., projectid:my-lab-project)。如果未替换此变量，智能体将在您有权访问的每个项目中进行搜索，从而导致答案不正确。
算法：请注意第 1 阶段 / 第 2 阶段逻辑。我们明确指示模型不要猜测 SQL。它必须先搜索正确的标记定义（第 1 阶段），然后才能搜索数据（第 2 阶段）。

启动智能体并测试场景

启动 Gemini CLI 会话，这次将治理政策作为系统背景加载。

gemini

注意：您可能会看到加载了多个上下文文件（例如 GEMINI.md 和其他文件）。这种情况很正常。CLI 会加载此项目的特定规则的本地 GEMINI.md，以及 Dataplex 扩展程序本身的默认说明。

验证安装

输入 /mcp desc 以确认 Dataplex 扩展程序处于活动状态。您应该会看到 dataplex 列为已配置的 MCP 服务器，并提供可用工具。

测试场景（原型设计）

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

场景 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，因为其 Aspect 在语义上与 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，因为其 Aspect 在语义上与 BRONZE_ADHOC（原始数据）和 is_certified: false（沙盒环境）匹配。

（如需退出 Gemini 会话，请输入 /quit）

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

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

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

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

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

👉 链接到第 2 部分 Codelab

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

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

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

👉 前往“清理”部分。

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

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

销毁数据湖 (Terraform)

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

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

卸载 Gemini CLI 扩展程序并移除本地文件

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