在 AlloyDB 上为生成式 AI 和代理应用安装并设置数据库专用 MCP 工具箱

1. 概览

MCP Toolbox for Databases 是 Google 提供的一款开源服务器，可让您更轻松地构建用于与数据库交互的生成式 AI 工具。它通过处理连接池、身份验证等复杂问题，让您能够更轻松、更快速、更安全地开发工具。它可帮助您构建生成式 AI 工具，让智能体能够访问数据库中的数据。工具箱提供：

简化开发：只需不到 10 行代码即可将工具集成到代理中，在多个代理或框架之间重复使用工具，并更轻松地部署新版本的工具。

更出色的性能：连接池、身份验证等最佳实践。

增强的安全性：集成式身份验证，可更安全地访问您的数据。

端到端可观测性：开箱即用的指标和跟踪功能，内置对 OpenTelemetry 的支持。

该工具箱位于应用的编排框架和数据库之间，提供用于修改、分发或调用工具的控制平面。它提供了一个集中存储和更新工具的位置，让您可以轻松管理工具，还可以在代理和应用之间共享工具，并更新这些工具，而无需重新部署应用。

构建内容

在本实验中，您将构建一个应用，该应用使用工具执行简单的数据库 (AlloyDB) 查询，并且可以从智能体或生成式 AI 应用中调用该查询。为此，您需要

安装 MCP Toolbox for Databases
在工具箱服务器上设置工具（旨在在 AlloyDB 中执行任务）
在 Cloud Run 上部署 MCP Toolbox for Databases
使用已部署的 Cloud Run 端点测试该工具
构建 Cloud Run 函数以调用该工具箱

要求

一个浏览器，例如 Chrome 或 Firefox
启用了结算功能的 Google Cloud 项目（请参阅下一部分中的步骤）。

2. 准备工作

创建项目

在 Google Cloud Console 的项目选择器页面上，选择或创建一个 Google Cloud 项目。
确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。
您将使用 Cloud Shell，它是在 Google Cloud 中运行的命令行环境。点击 Google Cloud 控制台顶部的“激活 Cloud Shell”。

“激活 Cloud Shell”按钮图片

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

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

在 Cloud Shell 终端中逐一运行以下命令，以启用所需的 API：

您还可以使用单个命令运行以下操作，但如果您是试用账号用户，尝试批量启用这些服务时可能会遇到配额问题。因此，每个命令都单独显示在一行中。

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

另一种方法是使用 gcloud 命令，通过控制台搜索每种产品或使用此链接。

如果遗漏了任何 API，您始终可以在实施过程中启用它。

如需了解 gcloud 命令和用法，请参阅文档。

3. 数据库设置

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

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

创建集群和实例

在 Cloud 控制台中浏览 AlloyDB 页面。

在 Cloud 控制台中查找大多数页面的简单方法是使用控制台的搜索栏进行搜索。

在该页面中选择“创建集群”：

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

集群 ID：“vector-cluster”
密码：“alloydb”
与 PostgreSQL 15 兼容
地区：“us-central1”
联网：“default”

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

请务必将实例 ID 更改为“

vector-instance"

。

请注意，创建集群大约需要 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;

创建表

使用以下 DDL 语句创建表：

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

成功执行上述命令后，您应该能够在数据库中查看该表。

注入数据

在此实验中，我们在此 SQL 文件中提供了大约 72 条记录的测试数据。它包含 id, name, description, quantity, price, image_url 字段。其他字段将在稍后的实验中填写。

从该处复制相应行/插入语句，然后将这些行粘贴到空白编辑器标签页中，并选择“运行”。

如需查看表内容，请展开“探索器”部分，直到看到名为“apparels”的表。选择三竖点图标 (⋮)，即可看到用于查询表格的选项。系统会在新的编辑器标签页中打开 SELECT 语句。

授予权限

运行以下语句，向用户 postgres 授予对 embedding 函数的执行权限：

GRANT EXECUTE ON FUNCTION embedding TO postgres;

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

前往 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"

5. 为上下文创建嵌入

计算机处理数字比处理文本容易得多。嵌入系统会将文本转换为一系列浮点数（称为向量嵌入），这些浮点数应能表示文本，无论文本的措辞如何、使用何种语言等。

例如，海滨位置可能会被称为“水上”“海滨”“从房间步行到海边”“sur la mer”“на берегу океана”等。这些术语看起来各不相同，但它们的语义或机器学习术语中的嵌入应该非常接近。

现在，数据和上下文已准备就绪，我们将运行 SQL，以将商品描述的嵌入内容添加到字段 embedding 中的表中。您可以使用多种嵌入模型。我们使用的是 Vertex AI 中的 text-embedding-005。请务必在整个项目中使用相同的嵌入模型！

注意：如果您使用的是旧版 Google Cloud 项目，可能需要继续使用旧版文本嵌入模型，例如 textembedding-gecko。

返回 AlloyDB Studio 标签页，然后输入以下 DML：

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

再次查看 toys 表，查看一些嵌入内容。请务必重新运行 SELECT 语句，以查看更改。

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

此方法应返回玩具说明的嵌入向量（看起来像一个浮点数数组），如下所示：

注意：在免费层级下新建的 Google Cloud 项目在每秒允许的嵌入请求数方面可能会遇到配额问题。我们建议您使用 ID 的过滤查询，然后在生成嵌入内容时，有选择地选择 1-5 条记录，依此类推。

6. 执行向量搜索

现在，表、数据和嵌入都已准备就绪，接下来我们来针对用户搜索文本执行实时向量搜索。

假设用户提出以下问题：

“I want a white plush teddy bear toy with a floral pattern。”

您可以运行以下查询来查找匹配项：

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

我们来详细了解一下此查询：

在此查询中，

用户的搜索文字为：“I want a white plush teddy bear toy with a floral pattern.”
我们正在使用模型 text-embedding-005 在 embedding() 方法中将其转换为嵌入。在最后一步中，我们已将嵌入函数应用于表中的所有项，因此这一步应该很熟悉。
“<=>”表示使用余弦相似度距离方法。您可以在 pgvector 的文档中找到所有可用的相似度衡量指标。
我们将嵌入方法的结果转换为向量类型，以使其与存储在数据库中的向量兼容。
LIMIT 5 表示我们希望提取搜索文本的 5 个最近邻项。

结果如下所示：

从搜索结果中可以看出，匹配项与搜索文本非常接近。尝试更改文字，看看结果有何变化。

7. 为工具箱互动准备 AlloyDB

在准备设置 Toolbox 时，我们先在 AlloyDB 实例中启用公共 IP 连接，以便新工具可以访问数据库。

前往您的 AlloyDB 实例，点击“修改”，然后进入“修改主实例”页面。
前往“公共 IP 连接”部分，勾选“启用公共 IP”复选框，然后输入 Cloud Shell 机器的 IP 地址。
如需获取 Cloud Shell 机器的 IP，请前往 Cloud Shell 终端并输入 ifconfig。从结果中确定 eth0 inet 地址，并将最后 2 位替换为 0.0，掩码大小为“/16”。例如，它看起来会像“XX.XX.0.0/16”，其中 XX 是数字。
将此 IP 粘贴到修改实例页面的“授权的外部网络”的“网络”文本框中。

完成后，点击“更新实例”。

这需要几分钟才能完成。

8. MCP Toolbox for Databases 安装

您可以创建一个项目文件夹来存储工具详细信息。在本例中，由于我们处理的是玩具店数据，因此我们创建一个名为“toystore”的文件夹，然后进入该文件夹。前往 Cloud Shell 终端，确保您的项目已选中并显示在终端的提示中。在 Cloud Shell 终端中运行以下命令：

mkdir toystore

cd toystore

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

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

切换到 Cloud Shell 编辑器。展开新创建的文件夹“toystore”，然后创建一个名为 tools.yaml 的新文件。复制以下内容。替换 YOUR_PROJECT_ID，并检查所有其他连接详细信息是否准确无误。

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

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

在此工具中，我们只是找到与用户搜索文本（自定义玩具说明）最接近的匹配项，并返回其价格。您还可以修改此查询，以查找前 5 个最接近的匹配玩具的平均价格：

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

您已完成工具定义！

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

切换到 Cloud Shell 终端，然后输入以下命令，以使用您的工具配置启动工具箱服务器：

./toolbox --tools_file "tools.yaml"

现在，如果您在云端以网页预览模式打开服务器，应该能够看到工具箱服务器正在运行，其中包含您名为 get-toy-price. 的新工具

9. 将 MCP Toolbox for Databases 部署到 Cloud Run

我们将其部署到 Cloud Run，以便您实际使用此工具。

按照此页面中的说明逐一操作，直到您看到“部署到 Cloud Run”部分中的第 3 点所列的 gcloud run deploy toolbox 命令。您需要的是第一种方法，而不是第二种方法（第二种方法适用于使用 VPC 网络的情况）。
成功部署后，您将收到工具箱服务器的 Cloud Run 部署端点。使用 C网址命令进行测试。

提示：

请仔细按照页面中的说明操作，不要遗漏任何步骤。

您已一切就绪，可以在代理应用中使用新部署的工具了！

10. 使用 MCP Toolbox for Databases 连接应用

在此部分中，我们将构建一个小应用来测试您的工具，以满足应用的需求并检索响应。

前往 Google Colab 并打开一个新笔记本。
在笔记本中运行以下命令

!pip install toolbox-core
from toolbox_core import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")

# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")

# If there are multiple tools 
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")

# Invoke the tool with a search text to pass as the parameter
 result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)

您应该会看到如下结果：

这是在 Python 应用中使用该工具包时显式调用的工具 toolbox-langchain.

如果您想使用此工具并将其绑定到 LangGraph 集成应用中的代理，可以使用 langgraph 工具包轻松实现。
为此，请参阅代码段。

11. 迁移到云端！

让我们将此 Python 代码段封装在 Cloud Run Functions 中，使其成为无服务器代码！

从代码库文件夹复制源代码，以便将其上传到 Cloud Functions。
前往 Cloud Run Functions 控制台，然后点击“创建函数”。
对于演示应用，请保持未经过身份验证的状态，并在下一页中选择 Python 3.11 运行时。
从第 1 步中共享的源代码库复制 main.py 和 requirements.txt 文件，然后粘贴到相应的文件中。
将 main.py 中的服务器网址替换为您的服务器网址。
部署该函数后，您将获得一个 REST 端点，供价格预测工具在玩具店 Web 应用中访问。
您的端点应如下所示：

https://us-central1-*****.cloudfunctions.net/toolbox-toys

您可以在 Cloud Functions 控制台中直接测试该函数，方法是前往“测试”标签页，然后输入以下内容作为请求输入：

{

           "search": "White plush toy"

}

点击“测试函数”或在 Cloud Shell 终端中运行，具体取决于您选择使用哪种方式。您应该会在右侧的“输出”标题下看到相应结果：

12. 恭喜

恭喜！您已成功创建一款强大且真正模块化的工具，该工具可以跨数据库、平台和生成式 AI 编排框架进行交互，帮助您创建智能体应用。

在 AlloyDB 上为生成式 AI 和代理应用安装并设置数据库专用 MCP 工具箱 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。