在 Cloud Run 上使用 Gemini CLI 通过 AlloyDB 的 MCP Toolbox 加快数据驱动型开发速度

1. 概览

还记得我们如何利用 AlloyDB 构建动态混合零售体验，将多面过滤与向量搜索相结合吗？该应用有力地展示了现代零售需求，但要实现这一目标并对其进行迭代，需要付出大量的开发工作。对于全栈开发者而言，在代码编辑器和数据库工具之间不断切换往往会成为瓶颈，从而拖慢创新和了解数据的关键流程。

解决方案

这正是加速应用开发的强大之处，也是我非常高兴能分享 MCP（现代云平台）工具箱的原因。该工具箱可通过直观的 Gemini CLI 访问，已成为我工具箱中不可或缺的一部分。想象一下，您可以在集成开发环境 (IDE) 中直接与 AlloyDB 实例无缝互动、编写查询和了解数据集。这不仅仅是为了方便，而是从根本上减少开发生命周期中的摩擦，让您能够专注于构建创新功能，而不是与外部工具作斗争。

在我们的零售电子商务应用中，我们需要高效查询商品数据、处理复杂的过滤条件并充分利用向量搜索的细微差别，因此快速迭代数据库交互的能力至关重要。由 Gemini CLI 提供支持的 MCP Toolbox 不仅简化了这一流程，还加快了流程，改变了我们探索、测试和优化应用所依赖的数据库逻辑的方式。接下来，我们深入了解一下这种颠覆性的组合如何让全栈开发变得更快、更智能、更轻松。

学习和构建内容

一个 Retail Search 应用，利用 IDE 中的 MCP Toolbox，由 Gemini CLI 提供支持。我们将涉及以下内容：

1. 如何将 MCP Toolbox 直接集成到 IDE 中，以实现无缝的 AlloyDB 互动。
2. 使用 Gemini CLI 针对零售数据编写和执行 SQL 查询的实用示例。
3. 利用 Gemini CLI 与我们的零售电子商务数据集互动，编写通常需要单独工具才能完成的查询，并立即查看结果。
4. 探索通过熟悉的 IDE 内命令行界面来探测和了解数据的新方法，包括检查表结构和执行快速数据健全性检查。
5. 这种加速的数据库工作流如何直接有助于缩短全栈开发周期，从而实现快速原型设计和迭代。

Techstack

我们正在使用：

• AlloyDB for database
• MCP Toolbox，用于从应用中抽象出数据库的高级生成式 AI 功能
• Cloud Run，用于无服务器部署。
• Gemini CLI 来理解和分析数据集，并构建零售电子商务应用的数据库部分。

要求

• 一个浏览器，例如 Chrome 或 Firefox
• 启用了结算功能的 Google Cloud 项目。

2. 准备工作

创建项目

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

对于 Google Cloud 赠金：如果您想获得 Google Cloud 赠金来帮助您开始使用，请点击此链接 兑换赠金。您可以按照 此处的说明兑换。

3. 您将使用 Cloud Shell，它是在 Google Cloud 中运行的命令行环境。点击 Google Cloud 控制台顶部的“激活 Cloud Shell”。

4. 连接到 Cloud Shell 后，您可以使用以下命令检查自己是否已通过身份验证，以及项目是否已设置为您的项目 ID：

gcloud auth list

5. 在 Cloud Shell 中运行以下命令，以确认 gcloud 命令了解您的项目。

gcloud config list project

6. 如果项目未设置，请使用以下命令进行设置：

gcloud config set project <YOUR_PROJECT_ID>

7. 启用必需的 API：点击链接并启用 API。

或者，您也可以使用 gcloud 命令来完成此操作。如需了解 gcloud 命令和用法，请参阅文档。

3. 数据库设置

在本实验中，我们将使用 AlloyDB 作为电子商务数据的数据库。它使用集群来保存所有资源，例如数据库和日志。每个集群都有一个主实例，可提供对数据的访问点。表将包含实际数据。

我们来创建 AlloyDB 集群、实例和表，以便加载电子商务数据集。

创建集群和实例

1. 在 Cloud 控制台中浏览 AlloyDB 页面。在 Cloud 控制台中查找大多数页面的简单方法是使用控制台的搜索栏进行搜索。
2. 在该页面中选择创建集群：

3. 您会看到如下所示的界面。使用以下值创建 集群和实例（如果您要从代码库克隆应用代码，请确保这些值匹配）：

• 集群 ID：“vector-cluster”
• 密码：“alloydb”
• PostgreSQL 15 / 最新推荐版本
• 地区：“us-central1”
• 网络：“default”

4. 选择默认网络后，您会看到如下所示的界面。

选择设置连接。

5. 然后，选择使用自动分配的 IP 范围，然后点击“继续”。查看信息后，选择“创建连接”。
6. 设置好网络后，您可以继续创建集群。点击创建集群以完成集群设置，如下所示：

重要提示：

1. 请务必将实例 ID（可在配置集群 / 实例时找到）更改为**vector-instance**。如果您无法更改，请务必在所有后续引用中 **使用您的实例 ID**。
2. 请注意，创建集群大约需要 10 分钟。成功后，您应该会看到一个屏幕，其中显示了您刚刚创建的集群的概览。

4. 数据注入

现在，我们来添加一个包含商店相关数据的表格。前往 AlloyDB，选择主集群，然后选择 AlloyDB Studio：

您可能需要等待实例完成创建。完成后，使用您在创建集群时创建的凭据登录 AlloyDB。使用以下数据向 PostgreSQL 进行身份验证：

• 用户名：“postgres”
• 数据库：“postgres”
• 密码：“alloydb”

成功通过 AlloyDB Studio 的身份验证后，您可以在编辑器中输入 SQL 命令。您可以使用最后一个窗口右侧的加号添加多个编辑器窗口。

您将在编辑器窗口中输入 AlloyDB 命令，并根据需要使用“运行”“格式化”和“清除”选项。

启用扩展程序

为了构建此应用，我们将使用扩展程序 pgvector 和 google_ml_integration。借助 pgvector 扩展程序，您可以存储和搜索向量嵌入。google_ml_integration 扩展程序提供用于访问 Vertex AI 预测端点以在 SQL 中获取预测结果的函数。通过运行以下 DDL 启用这些扩展程序：

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

如果您想查看数据库中已启用的扩展程序，请运行以下 SQL 命令：

select extname, extversion from pg_extension;

创建表

您可以在 AlloyDB Studio 中使用以下 DDL 语句创建表：

CREATE TABLE apparels ( 
  id BIGINT, 
  category VARCHAR(100), 
  sub_category VARCHAR(50), 
  uri VARCHAR(200), 
  gsutil_uri VARCHAR(200),
  image VARCHAR(100), 
  content VARCHAR(2000), 
  pdt_desc VARCHAR(5000), 
  color VARCHAR(2000),
  gender VARCHAR(200),
  embedding vector(768),
  img_embeddings vector(1408),
  additional_specification VARCHAR(100000));

嵌入列将允许存储文本的向量值。

授予权限

运行以下语句，以授予对“embedding”函数的执行权限：

GRANT EXECUTE ON FUNCTION embedding TO postgres;

为 AlloyDB 服务账号授予 Vertex AI User 角色

在 Google Cloud IAM 控制台中，向 AlloyDB 服务账号（格式如下：service-<<PROJECT_NUMBER>>@gcp-sa-alloydb.iam.gserviceaccount.com）授予“Vertex AI 用户”角色访问权限。PROJECT_NUMBER 将包含您的项目编号。

或者，您也可以从 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"

将数据加载到数据库中

1. 将工作表中 insert scripts sql 中的 insert 查询语句复制到上述编辑器中。您可以复制 10-50 条 insert 语句，以便快速演示此使用情形。在此 “所选插页式广告 25-30 行”标签页中，有一个所选插页式广告的列表。
2. 点击运行。查询结果会显示在结果表中。

重要提示：

请务必仅复制 25-50 条记录以进行插入，并确保这些记录来自一系列类别、子类别、颜色和性别类型。

5. 为数据创建嵌入

现代搜索的真正创新在于理解含义，而不仅仅是关键字。这时，嵌入和向量搜索就派上用场了。

我们使用预训练的语言模型将商品说明和用户查询转换为称为“嵌入”的高维数值表示形式。这些嵌入可捕获语义含义，让我们能够找到“含义相似”的商品，而不仅仅是包含匹配字词的商品。最初，我们尝试直接对这些嵌入进行向量相似度搜索，以建立基准，这表明即使在进行性能优化之前，语义理解功能也十分强大。

嵌入列将允许存储商品说明文本的向量值。img_embeddings 列将用于存储图片嵌入（多模态）。这样，您还可以使用基于文本与图片距离的搜索。不过，在本实验中，我们将仅使用文本嵌入。

SELECT embedding('text-embedding-005', 'AlloyDB is a managed, cloud-hosted SQL database service.');

这应该会返回查询中示例文本的嵌入向量，该向量看起来像一个浮点数数组。如下所示：

更新 abstract_embeddings 向量字段

运行以下 DML，以使用相应的嵌入更新表中的内容说明：

UPDATE apparels SET embedding = embedding('text-embedding-005',pdt_desc)::vector 
WHERE pdt_desc IS NOT NULL;

如果您使用的是 Google Cloud 的试用信用额度结算账号，则可能难以生成超过少量（例如最多 20-25 个）的嵌入内容。因此，请限制插入脚本中的行数。

如果您想生成图片嵌入（用于执行多模态情境搜索），请同时运行以下更新：

update apparels set img_embeddings = ai.image_embedding(
  model_id => 'multimodalembedding@001',
  image => gsutil_uri,
  mimetype => 'image/jpg')       
where gsutil_uri is not null

6. MCP Toolbox for Databases (AlloyDB)

在幕后，强大的工具和结构合理的应用可确保顺畅运行。

借助 MCP（模型上下文协议）工具箱，您可以更轻松地将生成式 AI 和 Agentic 工具与 AlloyDB 集成。它充当一个开源服务器，可简化连接池、身份验证以及数据库功能向 AI 代理或其他应用的安全公开。

在我们的应用中，我们使用 MCP Toolbox for Databases 作为所有智能混合搜索查询的抽象层。

按照以下步骤设置并部署适用于我们使用情形的 Toolbox：

您可以看到，MCP Toolbox for Databases 支持的数据库之一是 AlloyDB，并且我们在上一部分中已预配该数据库，因此接下来我们来设置 Toolbox。

1. 前往 Cloud Shell 终端，确保您的项目已选中并显示在终端的提示中。在 Cloud Shell 终端中运行以下命令，以进入项目目录：

mkdir gemini-cli-project

cd gemini-cli-project

2. 运行以下命令，在新文件夹中下载并安装工具箱：

# see releases page for other versions
export VERSION=0.7.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

这应该会在您的当前目录中创建工具箱。将路径复制到工具箱。

3. 前往 Cloud Shell 编辑器（用于代码编辑模式），然后在项目根文件夹“gemini-cli-project”中添加一个名为“tools.yaml”的文件。

sources:
    alloydb:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"


tools:
   get-apparels:
    kind: postgres-sql
    source: alloydb
    description: Get all apparel data.
    statement: |
      select id, content, uri, category, sub_category,color,gender from apparels;

我们来了解一下 tools.yaml：

来源表示工具可以与之互动的不同数据源。来源表示工具可以与之互动的数据源。您可以在 tools.yaml 文件的 sources 部分中将来源定义为映射。通常，来源配置将包含连接数据库并与之互动所需的任何信息。

工具定义了智能体可以执行的操作，例如读取和写入来源。工具表示代理可以执行的操作，例如运行 SQL 语句。您可以在 tools.yaml 文件的 tools 部分中将工具定义为映射。通常，工具需要一个来源才能发挥作用。

如需详细了解如何配置 tools.yaml，请参阅此文档。

如上文的 Tools.yaml 文件所示，工具“get-apparels”会列出数据库中所有服装的详细信息。

7. 设置 Gemini CLI

在 Cloud Shell 编辑器中，在 gemini-cli-project 文件夹中创建一个名为 .gemini 的新文件夹，并在其中创建一个名为 settings.json 的新文件。

{
  "mcpServers": {
"AlloyDBServer": {
  "command": "/home/user/gemini-cli-project/toolbox",
  "args": ["--tools-file", "tools.yaml", "--stdio"]
}
  }
}

在上述代码段的命令部分中，将“/home/user/gemini-cli-project/toolbox”替换为您的工具箱路径。

安装 Gemini CLI

最后，在 Cloud Shell 终端中，通过执行以下命令，在同一目录 gemini-cli-project 中安装 Gemini CLI：

sudo npm install -g @google/gemini-cli

设置项目 ID

确保您已在环境中设置有效项目 ID：

export GOOGLE_CLOUD_PROJECT=<<YOUR_PROJECT_ID>>

开始使用 Gemini CLI

在命令行中，输入以下命令：

gemini

您应该会看到如下所示的响应：

进行身份验证，然后继续执行下一步。

8. 开始与 Gemini CLI 互动

使用命令 /mcp 列出已配置的 MCP 服务器。

您应该能够看到我们配置的 2 个 MCP 服务器：GitHub 和 MCP Toolbox for Databases，以及它们列出的工具。

就我而言，我拥有更多工具。因此，请暂时忽略此错误。您应该会在 AlloyDB MCP 服务器中看到 get-apparels 工具。

通过 MCP Toolbox 开始查询数据库

现在，尝试提出自然语言问题，以获取我们正在处理的数据集的回答和查询：

> How many types of genders the apparel dataset has?

> Give me the SQL that I can use to find the number of apparels that are footwear 

> What are the unique sub categories that are there?
that I can use to find the number of apparels that are footwear 

现在，假设我根据数据分析和许多此类查询提出了一个详细的查询，并想对其进行测试。或者，假设数据库工程师已为您构建了 Tools.yaml，如下所示：

sources:
    alloydb:
        kind: "alloydb-postgres"
        project: "<<YOUR_PROJECT_ID>>"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
   get-apparels:
    kind: postgres-sql
    source: alloydb
    description: Get all apparel data.
    statement: |
      select id, content, uri, category, sub_category,color,gender from apparels;

   filtered-vector-search:
    kind: postgres-sql
    source: alloydb
    description: Get the list of facet filter values from the retail dataset.
    parameters:
      - name: categories
        type: array
        description: List of categories preferred by the user.
        items:
          name: category 
          type: string
          description: Category value. 
      - name: subCategories
        type: array
        description: List of sub-categories preferred by the user.
        items:
          name: subCategory 
          type: string
          description: Sub-Category value.
      - name: colors
        type: array
        description: List of colors preferred by the user.
        items:
          name: color 
          type: string
          description: Color value.
      - name: genders
        type: array
        description: List of genders preferred by the user for apparel fitting.
        items:
          name: gender 
          type: string
          description: Gender name.
      - name: searchtext
        type: string
        description: Description of the product that the user wants to find database matches for.    
    statement: |
      SELECT id, content, uri, category, sub_category,color,gender FROM apparels 
      where category = ANY($1) and sub_Category = ANY($2) and color = ANY($3) and gender = ANY($4)
      order by embedding <=> embedding('text-embedding-005',$5)::vector limit 10

现在，我们来尝试一下自然语言搜索：

> How many yellow shirts are there for boys?

是不是很酷？现在，我可以修复 YAML 文件，以便在查询方面取得更多进展，同时以更快的速度在我的应用中交付新功能。

9. 加快应用开发速度

通过 Gemini CLI 和 MCP Toolbox 将数据库功能直接引入 IDE 的好处不仅仅是理论上的。这可转化为切实可行的提速工作流程，尤其对于像我们的混合零售体验这样的复杂应用而言。我们来看几个场景：

1. 快速迭代商品过滤逻辑

假设我们刚刚推出了“夏季运动服装”的新促销活动。我们想测试多面过滤条件（例如按品牌、尺寸、颜色、价格范围过滤）如何与此新类别互动。

不集成 IDE：

我可能会切换到单独的 SQL 客户端，编写查询，执行查询，分析结果，然后返回到 IDE 调整应用代码，再切换回客户端，然后重复上述步骤。这种上下文切换非常耗时。

使用 Gemini CLI 和 MCP：

我可以在 IDE 中完成更多操作：

• 查询：我可以快速更新 yaml 中的查询（假设的数据集），例如“SELECT DISTINCT brand FROM products WHERE category = ‘activewear' AND season = ‘summer'”，然后在终端中尝试运行该查询。
• 数据探索：立即查看返回的品牌。如果我需要查看特定品牌和尺码的商品是否有货，可以使用另一个快速查询：“SELECT COUNT(*) FROM products WHERE brand = ‘SummitGear' AND size = ‘M' AND category = ‘activewear' AND season = ‘summer'”
• 代码集成：然后，我可以根据这些快速的 IDE 内数据洞见立即调整前端过滤逻辑或后端 API 调用，从而大幅缩短反馈环。

2. 针对商品推荐对 Vector Search 进行微调

我们的混合搜索功能依赖于向量嵌入来提供相关的商品推荐。假设我们发现“男士跑鞋”推荐的点击率有所下降。

不集成 IDE：

我会运行数据库工具中的自定义脚本或查询，分析推荐鞋款的相似度得分，将其与用户互动数据进行比较，并尝试关联任何模式。

使用 Gemini CLI 和 MCP：

• 分析嵌入内容：我可以直接查询商品嵌入内容及其关联的元数据：“SELECT product_id, name, vector_embedding FROM products WHERE category = ‘running shoes' AND gender = ‘male' LIMIT 10”
• 交叉参考：我还可以直接在界面中快速检查所选商品与其推荐商品之间的实际向量相似度。例如，如果向浏览过商品 B 的用户推荐了商品 A，我可以运行查询来检索并比较它们的向量嵌入。
• 调试：这有助于更快地进行调试和假设检验。嵌入模型的行为是否符合预期？数据中是否存在影响推荐质量的异常情况？我无需离开编码环境即可获得初步解答。

3. 了解新功能的架构和数据分布

假设我们计划添加“客户评价”功能。在编写后端 API 之前，我们需要了解现有的客户数据以及评价的结构。

不集成 IDE：

我需要连接到数据库客户端，对客户和订单等表运行 DESCRIBE 命令，然后查询示例数据以了解关系和数据类型。

使用 Gemini CLI 和 MCP：

• 架构探索：我可以简单地查询 YAML 文件中的表格，并直接在终端中执行查询。
• 数据抽样：然后，我可以提取样本数据，了解客户的人口统计特征和购买记录：“SELECT customer_id, name, signup_date, total_orders FROM customers ORDER BY signup_date DESC LIMIT 5”
• 规划：通过快速访问架构和数据分布，我们可以做出明智的决策，例如如何设计新的评价表、建立哪些外键，以及如何高效地将评价与客户和产品相关联，所有这些都可以在为新功能编写任何应用代码之前完成。

以上仅列举了几个示例，但它们突显了核心优势：减少摩擦并提高开发者速度。通过将 AlloyDB 交互直接引入 IDE，Gemini CLI 和 MCP Toolbox 使我们能够更快地构建更好、响应更迅速的应用。

10. 清理

为避免系统因本博文中使用的资源向您的 Google Cloud 账号收取费用，请按照以下步骤操作：

1. 在 Google Cloud 控制台中，前往资源管理器页面。
2. 在项目列表中，选择要删除的项目，然后点击删除。
3. 在对话框中输入项目 ID，然后点击关停以删除项目。
4. 或者，您也可以点击“DELETE CLUSTER”按钮，删除我们刚刚为该项目创建的 AlloyDB 集群（如果您在配置时未选择 us-central1 作为集群的位置，请更改此超链接中的位置）。

11. 恭喜

恭喜！您已成功将 MCP Toolbox 直接集成到 IDE 中，以便无缝地与 AlloyDB 交互，并利用 Gemini CLI 与我们的零售电子商务数据集交互，从而编写通常需要单独工具才能完成的查询。您已学习了探测和了解数据的新方法，包括检查表结构、执行快速数据健全性检查等，所有这些操作都可以在 IDE 中通过熟悉的命令行界面完成。

请继续克隆 repo，进行分析，并告诉我您是否使用 Gemini CLI 和 MCP Toolbox for Databases 增强了应用。

如需了解更多使用 Gemini CLI、MCP 构建并部署在无服务器运行时上的此类数据驱动型应用，请报名参加我们即将推出的 Code Vipassana 季，您将获得讲师指导的实践课程和更多此类 Codelab！