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

1. 概览

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

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

提升性能：采用连接池、身份验证等最佳实践。

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

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

Toolbox 位于应用的编排框架和数据库之间，提供了一个控制平面，用于修改、分发或调用工具。它为您提供了一个集中存储和更新工具的位置，从而简化了工具的管理，让您可以在智能体和应用之间共享工具，并在无需重新部署应用的情况下更新这些工具。

构建内容

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

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

要求

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

2. 准备工作

创建项目

在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 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：

您还可以使用单个命令运行以下命令，但如果您是试用账号用户，则可能会遇到批量启用这些 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. 为上下文创建嵌入

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

例如，海边位置可能称为“on the water”“beachfront”“walk from your room to the ocean”“sur la mer”“на берегу океана”等。这些术语看起来各不相同，但它们的语义含义（或在机器学习术语中，它们的嵌入）应该非常接近。

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

注意：如果您使用的是旧版 Google Cloud 项目，可能需要继续使用旧版 text-embedding 模型，例如 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. 为 Toolbox 交互准备 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

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

# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/mcp-toolbox-for-databases/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 服务器：

./toolbox --tools_file "tools.yaml"

现在，如果您在云端以 Web 预览模式打开服务器，您应该能够看到 Toolbox 服务器已启动并运行，其中包含名为 get-toy-price. 的新工具。

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

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

按照此页面中的说明逐个操作，直到您看到 gcloud run deploy toolbox 命令，该命令位于“部署到 Cloud Run”部分下的第 3 点。您需要第一个选项，而不是第二个选项，第二个选项适用于使用 VPC 网络方法的情况。
成功部署后，您将收到 Toolbox 服务器的 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)

您应该会看到如下结果：

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

如果您想使用此工具并将其绑定到 LangGraph 集成应用中的智能体，可以使用 langgraph 工具包轻松完成此操作。
请参阅此操作的代码段。

11. 将其部署到 Cloud！

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

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

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

您可以直接在 Cloud Functions 控制台上对其进行测试，方法是导航到“测试”标签页，然后输入以下内容作为请求输入：

{

           "search": "White plush toy"

}

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

12. 恭喜

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

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