使用 Gemini Data Analytics 的 AlloyDB QueryData

1. 简介

此 Codelab 提供了有关如何开始使用 QueryData for AlloyDB 的指南，并介绍了如何在智能体应用中使用它通过自然语言输入生成准确且可预测的 SQL 语句

前提条件

对 Google Cloud 控制台有基本的了解
具备命令行界面和 Cloud Shell 方面的基本技能

学习内容

如何创建 AlloyDB 集群并导入示例数据
如何启用 AlloyDB Data Access API
如何为 AlloyDB 启用 QueryData
如何生成模板
如何使用分面搜索
如何将 QueryData 与 AI 智能体搭配使用

所需条件

Google Cloud 账号和 Google Cloud 项目
支持 Google Cloud 控制台和 Cloud Shell 的网络浏览器，例如 Chrome

2. 设置和要求

项目设置

创建 Google Cloud 项目

在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

启动 Cloud Shell

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

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

激活 Cloud Shell

或者，您也可以先按 G，再按 S。如果您位于 Google Cloud 控制台中，或者使用此链接，此序列将激活 Cloud Shell。

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

Google Cloud Shell 终端的屏幕截图，显示环境已连接

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

3. 准备工作

启用 API

如需使用 AlloyDB、Compute Engine、网络服务和 Vertex AI，您需要在 Google Cloud 云项目中启用它们各自的 API。

在 Cloud Shell 终端中，确保项目 ID 已设置：

gcloud config get-value project

您应该会在输出中看到项目 tID：

student@cloudshell:~ (test-project-001-402417)$ gcloud config get-value project
Your active configuration is: [cloudshell-23188]
test-project-001-402417
student@cloudshell:~ (test-project-001-402417)$

设置环境变量 PROJECT_ID：

PROJECT_ID=$(gcloud config get-value project)

启用所有必要的服务：

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.googleapis.com

预期输出

student@cloudshell:~ (test-project-001-402417)$ gcloud config set project test-project-001-402417
Updated property [core/project].
student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-14650]
student@cloudshell:~ (test-project-001-402417)$ 
student@cloudshell:~ (test-project-001-402417)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       geminidataanalytics.googleapis.com \
                       cloudaicompanion.googleapis.com \
                       aiplatform.googleapis.com
Operation "operations/acat.p2-4470404856-1f44ebd8-894e-4356-bea7-b84165a57442" finished successfully.

4. 部署 AlloyDB

创建 AlloyDB 集群和主实例。您可以使用准备好的脚本部署该应用，该脚本会部署所有必需的资源；也可以按照文档中的说明自行逐步完成部署。

使用自动化脚本部署 AlloyDB

此方法使用自动化脚本来部署 AlloyDB 集群，并提供必要的信息以开始使用已部署的资源。

在 Cloud Shell 终端中，执行命令以从代码库克隆部署脚本。

REPO_NAME="codelabs"
REPO_URL="https://github.com/GoogleCloudPlatform/$REPO_NAME"
SOURCE_DIR="alloydb-querydata"

git clone --no-checkout --filter=blob:none --depth=1 $REPO_URL

cd $REPO_NAME
git sparse-checkout set $SOURCE_DIR
git checkout
cd $SOURCE_DIR

运行部署脚本。

./deploy_alloydb.sh --public-ip

脚本需要一些时间才能运行完毕，通常大约需要 5-7 分钟，并部署 AlloyDB 集群和具有公共 IP 和专用 IP 的主实例。公共 IP 仅适用于授权网络或通过使用 AlloyDB Auth 代理来访问。如需详细了解公共 IP 地址，请参阅文档。脚本应输出有关已部署的 AlloyDB 集群的信息。请注意，您的密码会有所不同 - 请将密码记录在某处以供日后使用。

...
<redacted>
...
Creating primary instance: alloydb-aip-01-pr (8 vCPUs for TRIAL cluster)
Operation ID: operation-1765988049916-646282264938a-bddce198-9f248715
Creating instance...done.                                                                                                                                                                                                             
----------------------------------------
Deployment Process Completed
Cluster:  alloydb-aip-01 (TRIAL)
Instance: alloydb-aip-01-pr
Region:   us-central1
Initial Password: JBBoDTgixzYwYpkF (if new cluster)
----------------------------------------

您还可以在 Web 控制台中看到新集群和主实例

5. 准备数据库

您需要启用 Vertex AI 集成才能使用 AI 函数和运算符，启用数据访问权限 API 并为示例数据集创建数据库。

向 AlloyDB 授予必要权限

向 AlloyDB 服务代理添加 Vertex AI 权限。

使用顶部的“+”号打开另一个 Cloud Shell 标签页。

在新的 Cloud Shell 标签页中，执行以下命令：

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

预期的控制台输出：

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:service-4470404856@gcp-sa-alloydb.iam.gserviceaccount.com
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1

启用 Data Access API

您必须在 AlloyDB 集群上启用 Data Access API，才能使用 execute_sql 等 MCP 工具。

在同一终端标签页中执行。

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
curl -X PATCH \
 -H "Authorization: Bearer $(gcloud auth print-access-token)" \
 -H "Content-Type: application/json" \
 https://alloydb.googleapis.com/v1alpha/projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER/instances/$ADBCLUSTER-pr?updateMask=dataApiAccess \
 -d '{
   "dataApiAccess": "ENABLED",
 }'

启用 IAM 身份验证

我们将为代理工具使用 IAM 身份验证，这需要在实例上启用 IAM 身份验证，并将您自己添加为数据库用户。在实例级启用 IAM 身份验证之前，请等待上一步启用数据访问权限 API 完成。实例状态应为绿色。

我们先从在实例级层启用 IAM 开始。在同一终端标签页中执行。

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud beta alloydb instances update $ADBCLUSTER-pr \
   --database-flags password.enforce_complexity=on,alloydb.iam_authentication=on \
   --region=$REGION \
   --cluster=$ADBCLUSTER \
   --project=$PROJECT_ID \
   --update-mode=FORCE_APPLY

将自己添加为 AlloyDB 用户：

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
gcloud alloydb users create $(gcloud config get-value account) \
--cluster=$ADBCLUSTER \
--superuser=true \
--region=$REGION \
--type=IAM_BASED

在标签页中执行命令“exit”，关闭该标签页：

exit

连接到 AlloyDB Studio

在以下章节中，所有需要连接到数据库的 SQL 命令都可以在 AlloyDB Studio 中执行。T

前往 AlloyDB for Postgres 中的“集群”页面。

点击主实例，打开 AlloyDB 集群的 Web 控制台界面。

然后点击左侧的 AlloyDB Studio：

选择 postgres 数据库和 IAM 身份验证。然后点击“验证”按钮。

系统会打开 AlloyDB Studio 界面。如需在数据库中运行命令，请点击右侧的“无标题查询”标签页。

系统会打开一个界面，您可以在其中运行 SQL 命令

创建数据库

创建数据库快速入门。

在 AlloyDB Studio 编辑器中，执行以下命令。

创建数据库：

CREATE DATABASE quickstart_db

预期输出：

Statement executed successfully

连接到 quickstart_db

通过连接到数据库来检查数据库是否已创建。使用切换用户/数据库的按钮重新连接到 Studio。

从下拉列表中选择新的 quickstart_db 数据库，并使用相同的 IAM 身份验证。

系统会打开一个新连接，您可以在其中处理 quickstart_db 数据库中的对象。您可以在那里检查导入的架构和数据，并处理 QueryData 上下文集。

6. 示例数据

现在，您需要在数据库中创建对象并加载数据。您将使用虚构的 Cymbal Shipping 公司数据集。它包含有关货物、卡车、请求和卡车行程的虚构数据，以及虚构的司机。

创建存储分区

您将使用 Google SDK (gcloud) 将数据从克隆的代码库导入到 AlloyDB 数据库。您需要为此创建一个 Cloud Storage 存储分区，并向 AlloyDB 服务账号授予访问权限。或者，您也可以始终尝试使用 Web 控制台来完成此操作，如文档中所述。

在 Google Cloud Shell 终端中，执行以下命令：

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
gcloud storage buckets create gs://$PROJECT_ID-import --project=$PROJECT_ID --location=$REGION
gcloud storage buckets add-iam-policy-binding gs://$PROJECT_ID-import --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" --role=roles/storage.objectViewer

加载数据

下一步是加载数据。压缩后的 SQL 转储位于克隆的代码库文件夹中。以下命令假定您在创建 AlloyDB 集群时，使用主目录作为上一步中克隆代码库的起点。

将压缩的 SQL 转储复制到新存储分区：

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
gcloud storage cp ~/$REPO_NAME/$SOURCE_DIR/postgres_dump.sql.gz  gs://$PROJECT_ID-import

然后将数据加载到 quickstart_db 数据库：

PROJECT_ID=$(gcloud config get-value project)
CLUSTER_NAME=alloydb-aip-01
REGION=us-central1
gcloud alloydb clusters import $CLUSTER_NAME  --region=us-central1 --database=quickstart_db --gcs-uri=gs://$PROJECT_ID-import/postgres_dump.sql.gz --project=$PROJECT_ID --sql

该命令会将示例数据集加载到 quickstart_db 数据库中。您可以使用 AlloyDB Studio 验证表和记录。

7. 使用数据代理

我们先从一个使用 Google ADK for Python 创建并使用 MCP Toolbox for Databases 连接到 AlloyDB 实例的 AI 智能体示例开始。

安装 MCP Toolbox for Databases

MCP Toolbox for Databases 是一项开源项目，可为多种数据库引擎（包括 AlloyDB for PostgreSQL）提供 MCP 支持。您可以在该文档中了解 MCP Toolbox。

您需要下载适用于您平台的最新版软件。如需了解最新版本，请查看“版本”页面。以下示例展示了如何将 MCP Toolbox 的版本 31 下载到 Cloud Shell。

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
export VERSION=0.31.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

您需要为 Toolbox 准备一个配置文件。我们在当前目录下有一个示例 tools.yaml.example 文件，接下来将通过将两个占位符替换为项目 ID 和区域来准备 tools.yaml 文件。

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    tools.yaml.example > tools.yaml

启动 MCP Toolbox for Databases

现在，您可以使用准备好的配置文件启动 MCP 工具箱。

按 Google Cloud Shell 界面顶部的“+”按钮，在 Google Cloud Shell 中打开一个新标签页。

在新标签页中，切换到包含工具箱二进制文件和配置文件 tools.yaml 的目录，然后启动 MCP 服务器。

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config tools.yaml

您应该会在输出中看到“Server ready to serve!”，如下所示。

2026-03-30T10:28:03.614374-04:00 INFO "Initialized 1 sources: cymbal-logistics-sql-source"
2026-03-30T10:28:03.614517-04:00 INFO "Initialized 0 authServices: "
2026-03-30T10:28:03.614531-04:00 INFO "Initialized 0 embeddingModels: "
2026-03-30T10:28:03.614657-04:00 INFO "Initialized 2 tools: execute_sql_tool, list_cymbal_logistics_schemas_tool"
2026-03-30T10:28:03.614711-04:00 INFO "Initialized 1 toolsets: default"
2026-03-30T10:28:03.614723-04:00 INFO "Initialized 0 prompts: "
2026-03-30T10:28:03.614779-04:00 INFO "Initialized 1 promptsets: default"
2026-03-30T10:28:03.616214-04:00 INFO "Server ready to serve!"

检查代理源代码

在克隆的代码库文件夹中的第一个标签页中，使用 Google Cloud Shell 编辑器查看代理代码。

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/agent.py

您可以在代理中看到 AlloyDB 的 Google Cloud MCP 服务器部分。我们提供一个端点作为 MCP_SERVER_网址、身份验证、项目 ID，并将其添加到 MCP 工具集。

MCP_SERVER_URL = "http://127.0.0.1:5000"
creds, project_id = default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
if not creds.valid:
    creds.refresh(GoogleAuthRequest())

print(f"Authenticated as project: {project_id}")

mcp_toolset = ToolboxToolset(
    server_url=MCP_SERVER_URL,
)

在代理代码中，MCP 工具集作为代理的 tools 参数包含在内。此外，还有集群名称、实例名称、区域和数据库作为代理提示的变量。

MODEL_ID = "gemini-3-flash-preview"
cluster_name="alloydb-aip-01"
instance_name="alloydb-aip-01-pr"
location="us-central1"
database_name="quickstart_db"

# Agent configuration

root_agent = Agent(
    model=MODEL_ID,
    name='root_agent',
    description='A helpful assistant for analyst requests.',
    instruction=f"""
    Answer user questions to the best of your knowledge using provided tools.
    Do not try to generate non-existent data but use the grounded data from the database.
    When you answer questions about Cymbal Logistic activity
    use the toolset to run query in the AlloyDB cluster {cluster_name} instance {instance_name} in the location {location}
    in the project {project_id} in the database {database_name}
    """,
    tools=[mcp_toolset],
)

检查代码后，按编辑器窗口右上角的“打开终端”按钮，切换回终端。

启动代理

现在，您可以使用 Google ADK 网页界面以交互模式启动智能体。ADK 网页界面提供了一种便捷的方式来测试和排查智能体工作流的问题。

首先，我们使用 uv 软件包管理器安装所有必需的 Python 软件包。

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
uv sync

安装完所有软件包后，您需要在代理目录中添加一个 .env 文件，以指示代理使用 Vertex AI 与 AI 模型进行所有通信。

echo "GOOGLE_GENAI_USE_VERTEXAI=true" > data_agent/.env
echo "GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project -q)" >> data_agent/.env
echo "GOOGLE_CLOUD_LOCATION=global" >> data_agent/.env

然后，您可以启动代理

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

您应该会看到类似以下内容的输出，其中包含 http://127.0.0.1:8000 等端点。

您可以点击 Cloud Shell 中的相应网址，系统会在单独的浏览器标签页中打开一个预览窗口，您可以在该窗口中从左侧的下拉列表中选择 data_agent。

在 ADK 网页界面中，您可以在右下角发布问题，并在右侧查看完整的执行流程，包括每个步骤的轨迹。

8. 测试不含 QueryData 的 NL2SQL（适用于 AlloyDB）

借助该智能体，您可以使用自然语言以自由形式提问，智能体将使用 MCP Toolbox for Databases 作为工具来回答问题。问题会发布在右下角，而包含所有工具调用的答案会显示在顶部。

您正在处理一家运输公司的运营数据，其中包含有关运输请求、卡车、司机和司机完成的行程的信息。第一个问题是关于 2026 年 2 月完成的行程数。

在右下角的输入字段中，输入以下内容，然后按 Enter 键。

Hello, can you tell me how many trips we've done in February?

代理将通过执行多次工具调用来使用 list_cymbal_logistics_schemas_tool 和 execute_sql_tool 识别架构中的正确表，并执行多条 SQL 语句来获取正确的数据。

最终，在构建正确的查询并针对数据库执行该查询后，它会生成正确的结果。

我们在 2026 年 2 月完成了 108 次行程。我们的记录显示，2025 年 2 月没有已安排或已完成的行程。

您可以点击工具执行情况，查看每个工具调用的作用。例如，以下是执行的查询，用于获取我们的结果。

尝试使用 ADK Web 界面发出其他简单请求，看看它如何执行不同的查询来获得结果。

在终端中按 ctrl+c 停止代理。您可以关闭包含 ADK 网页界面的浏览器标签页。

您还可以按相同的 ctrl+c 键快捷键停止第二个标签页中的 MCP 工具箱，然后关闭第二个标签页。

在下一步中，我们将构建 QueryData 上下文，以改进 NL2SQL 响应和性能。

9. 构建 QueryData ContextSet

您可以在上一步中看到，AI 模型多次调用数据库的信息架构，以确定应使用哪些表和列来构建 SQL 查询。为了提高性能、准确率并使结果更具可预测性，我们将添加 QueryData 上下文，以定义应执行哪些查询来响应特定请求。

创建有针对性的模板

QueryData ContextSet 是一个 JSON 文件，其中包含查询模板和 Facet，可为 AI 模型提供必要的数据和指令，以便根据查询模式和数据结构使用正确的 SQL 查询或 SQL 查询部分来实现所请求的目标。

您从目标明确的模板开始。使用 Cloud Shell 编辑器创建文件。在 Cloud Shell 终端中执行。

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

然后，插入我们在上一章中使用的自然语言查询的模板 - “我们 2 月份完成了多少次行程？”

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a given month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ]
}

然后，使用下载按钮将模板从 Cloud Shell 下载到您的计算机。

加载 QueryData 上下文集

如需使用 QueryData 上下文集，我们需要将其上传到数据库。

打开 AlloyDB Studio。在左侧面板底部，您会看到 QueryData Context 和三个点。

点击这三个点，然后选择“创建上下文”。系统会打开一个对话框，您可以在其中输入

名称：cymbal_context_set
说明：Cymbal Logistic Query Data
上传上下文的描述文件：点击“Browse”按钮，然后选择包含 QueryData ContextSet 的 JSON 文件

如果您是首次按下保存按钮，系统可能需要一些时间来初始化上下文存储空间。

您应该能够看到下载的上下文，点击右侧的三个竖向按钮即可看到可用的操作。在下一章中，我们将从“测试上下文”操作开始。

10. 测试 QueryData 上下文集

测试模板

使用“Test context”操作在 AlloyDB Studio 中测试我们的上下文。点击“测试上下文”后，系统会打开一个新的 AlloyDB Studio 编辑器窗口，其中包含标题“cymbal_context_set”和标题为“Generate SQL using QueryData context: cymbal_context_set”的 Gemini SQL 生成邀请。点击 SQL 生成，然后输入

Hello, can you tell me how many trips we've done in February?

当 SQL 生成后，按“Insert”按钮。

您将看到与我们之前向上下文模板提出的查询完全相同的查询。

-- How many trips we've done in February?
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'

尝试将月份替换为“1 月”，然后检查生成的 SQL 语句。它将使用月份作为参数化 intent 的参数，并自动调整 SQL 语句。

我们尝试了查询模板，当知道我们期望的用户请求类型时，该模板可以正常运行。不过，有时我们希望使用特定顺序或特定子句来重新定义意图，因此仅引导查询的一部分（例如条件或过滤条件）会很有帮助。

例如，如果我们要求返回“上个月”的数据，则希望获得上一个日历月的报告（从该月的第 1 天到最后一天），而不是过去 30 天的报告。

我们可以将此类方面作为 SQL 代码段添加到 ContextSet 配置中，并添加之前添加的模板。打开 querydata_cymbal_contextset.json。

edit ~/$REPO_NAME/$SOURCE_DIR/data_agent/querydata_cymbal_contextset.json

并在现有模板之后添加这些方面。文件中的最终内容应如下所示

{
  "templates": [
    {
      "nl_query": "How many trips we've done in February?",
      "sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE('February 2026', 'Month YYYY') AND departure_time < TO_DATE('February 2026', 'Month YYYY') + INTERVAL '1 month'",
      "intent": "Count trips done in a certain month like February 2026",
      "manifest": "How many trips we've done in a given month",
      "parameterized": {
        "parameterized_intent": "How many trips we've done in $1",
        "parameterized_sql": "SELECT COUNT(*) FROM truck_trips WHERE departure_time >=TO_DATE($1, 'Month YYYY') AND departure_time < TO_DATE($1, 'Month YYYY') + INTERVAL '1 month'"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)",
      "intent": "last month",
      "manifest": "Records for the previous calendar month",
      "parameterized": {
        "parameterized_intent": "previous calendar month",
        "parameterized_sql_snippet": "departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)"
      }
    }
  ]
}

保存该文件，然后将其上传到您的计算机。

然后，使用“查询”上下文操作“修改上下文”，并上传修改后的文件以替换旧的上下文集。

现在，尝试再次使用测试上下文，并使用“上个月”意图生成 SQL 语句。例如，如果您为短语“show trucks trips for the last month"”生成 SQL，系统将使用我们在 cymbal_context.json 文件中提供的条件作为分面。

您应该会看到类似以下所示的内容：

-- show trucks trips for the last month
SELECT COUNT(*) FROM truck_trips WHERE departure_time >=date_trunc('month', current_date - interval '1 month') AND departure_time < date_trunc('month', current_date)

现在，如何将它与 AI 智能体搭配使用？在下一章中，我们将使“查询数据”上下文可供 AI 代理使用。

11. 使用 AI 智能体进行 QueryData

您将使用相同的数据代理，但现在 MCP 工具箱将配置为使用 QueryData ContextSet。

准备并启动 MCP Toolbox for Databases

我们需要为 MCP Toolbox 提供一个新的配置文件，该文件将使用 Gemini Data Analytics API 和 AlloyDB 作为数据库来源。

在终端中运行：

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
sed -e "s/##PROJECT_ID##/$PROJECT_ID/g" \
    -e "s/##REGION##/$REGION/g" \
    querydata.yaml.example > querydata.yaml

切换到编辑器，然后找到文件 querydata.yaml。配置文件 querydata.yaml 将如下所示，但项目 ID 和区域将反映您的环境。不过，您仍需更新 contextSetId 值，并将 "<add-context-set-id>" 占位符替换为控制台中的值。

kind: sources
name: gda-api-source
type: cloud-gemini-data-analytics
projectId: test-project-001-402417
---
kind: tools
name: cloud_gda_query_tool
type: cloud-gemini-data-analytics-query
source: gda-api-source
location: "us-central1"
description: Use this tool to send natural language queries to the Gemini Data Analytics API and receive SQL, natural language answers, and explanations.
context:
  datasourceReferences:
    alloydb:
      databaseReference:
        projectId: "test-project-001-402417"
        region: "us-central1"
        clusterId: "alloydb-aip-01"
        instanceId: "alloydb-aip-01-pr"
        databaseId: "quickstart_db"
      agentContextReference:
        contextSetId: "<add-context-set-id>"
generationOptions:
  generateQueryResult: true
  generateNaturalLanguageAnswer: true
  generateExplanation: true
  generateDisambiguationQuestion: true

如需查找 ContextSet ID，请点击上下文集的“修改”按钮，如图所示。

您会在右侧的新标签页顶部看到上下文集 ID。

该完整路径应替换 querydata.yaml 文件中的 "<add-context-set-id>" 占位符。

切换回终端。

按 Google Cloud Shell 界面顶部的“+”按钮，在 Google Cloud Shell 中打开一个新标签页。

在新标签页中，切换到包含工具箱二进制文件和配置文件 tools.yaml 的目录，然后启动 MCP 服务器。

REPO_NAME="codelabs"
SOURCE_DIR="alloydb-querydata"
cd ~/$REPO_NAME/$SOURCE_DIR
./toolbox --config querydata.yaml

运行 ADK 智能体

在第一个 Cloud Shell 标签页中，启动代理。

uv run adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

启动后，再次点击 http://127.0.0.1:8000 链接。

您将看到熟悉的 ADK 网页预览版代理界面。发布与上次完全相同的查询。

Hello, can you tell me how many trips we've done in February?

并查看代理工作流。如果一切配置正确，您应该会看到类似以下内容。

之前需要多次交互的请求已转换为对 MCP 工具的一次调用，并使用可预测的 SQL 语句执行。

您可以使用如下请求测试配置的分面

how trucks trips for the last month

在输出中，如果您点击工具操作，可以看到它使用了相同的工具并应用了分面来获取结果。

本实验到此结束。希望您已能够浏览所有示例，并了解如何使用 QueryData for AlloyDB。所提供的技术有助于使代理工作负载和 SQL 生成变得可预测且可靠。

12. 清理环境

为避免产生意外费用，建议您清理临时资源。最可靠的方法是删除您在其中测试工作流程的项目。不过，您也可以选择删除单个资源（例如 AlloyDB）来限制自己。

完成实验后销毁 AlloyDB 实例和集群。

删除 AlloyDB 集群和所有实例

如果您曾使用 AlloyDB 试用版。如果您计划使用试用集群测试其他实验和资源，请勿删除试用集群。您将无法在同一项目中创建其他试用集群。

系统会通过强制选项销毁集群，该选项还会删除属于该集群的所有实例。

如果您已断开连接且之前的所有设置都已丢失，请在 Cloud Shell 中定义项目和环境变量：

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

删除集群：

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

预期的控制台输出：

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.

删除 AlloyDB 备份

删除集群的所有 AlloyDB 备份：

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

预期的控制台输出：

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.

13. 恭喜

恭喜您完成此 Codelab。

所学内容

如何创建 AlloyDB 集群并导入示例数据
如何启用 AlloyDB 数据访问 API
如何为 AlloyDB 启用 QueryData
如何生成模板
如何使用分面搜索
如何将 QueryData 与 AI 智能体搭配使用

14. 调查问卷

输出如下：

您打算如何使用本教程？

仅通读

阅读并完成练习

使用 Gemini Data Analytics 的 AlloyDB QueryData

1. 简介

前提条件

学习内容

所需条件

2. 设置和要求

项目设置

创建 Google Cloud 项目

启动 Cloud Shell

3. 准备工作

启用 API

4. 部署 AlloyDB

使用自动化脚本部署 AlloyDB

5. 准备数据库

向 AlloyDB 授予必要权限

启用 Data Access API

启用 IAM 身份验证

连接到 AlloyDB Studio

创建数据库

连接到 quickstart_db

6. 示例数据

创建存储分区

加载数据

7. 使用数据代理

安装 MCP Toolbox for Databases

启动 MCP Toolbox for Databases

检查代理源代码

启动代理

8. 测试不含 QueryData 的 NL2SQL（适用于 AlloyDB）

9. 构建 QueryData ContextSet

创建有针对性的模板

加载 QueryData 上下文集

10. 测试 QueryData 上下文集

测试模板

构建 QueryData 分面

11. 使用 AI 智能体进行 QueryData

准备并启动 MCP Toolbox for Databases

运行 ADK 智能体

12. 清理环境

删除 AlloyDB 集群和所有实例

删除 AlloyDB 备份

13. 恭喜

所学内容

14. 调查问卷

您打算如何使用本教程？