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

1. 概览

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

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

性能更高：连接池、身份验证等最佳做法。

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

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

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

构建内容

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

  1. 安装适用于数据库的 MCP 工具箱
  2. 在 Toolbox 服务器上设置工具（用于在 AlloyDB 中执行任务）
  3. 在 Cloud Run 上部署数据库 MCP 工具箱
  4. 使用已部署的 Cloud Run 端点测试该工具
  5. 构建 Cloud run 函数以调用 Toolbox

要求

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

2. 准备工作

创建项目

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

“激活 Cloud Shell”按钮图片

  1. 连接到 Cloud Shell 后，使用以下命令检查您是否已通过身份验证，以及项目是否设置为正确的项目 ID：
gcloud auth list
  1. 在 Cloud Shell 中运行以下命令，以确认 gcloud 命令了解您的项目。
gcloud config list project
  1. 如果项目未设置，请使用以下命令进行设置：
gcloud config set project <YOUR_PROJECT_ID>
  1. 在 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

另一种方法是使用控制台，方法是搜索每个产品或使用此链接。

如果缺少任何 API，您随时可以在实现过程中启用它。

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

3. 数据库设置

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

我们来创建一个 AlloyDB 集群、实例和表，并在其中加载电子商务数据集。

创建集群和实例

  1. 浏览 Cloud 控制台中的 AlloyDB 页面。

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

  1. 从该页面选择“创建集群”：

f76ff480c8c889aa.png

  1. 您将看到如下所示的屏幕。使用以下值创建集群和实例（如果您要从代码库中克隆应用代码，请确保这些值一致）：
  • 集群 ID：“vector-cluster”
  • 密码：“alloydb”
  • 与 PostgreSQL 15 兼容
  • 区域：“us-central1”
  • 网络：“default”

538dba58908162fb

  1. 选择默认网络后，您会看到如下所示的屏幕。点击“设置连接”。
    7939bbb6802a91bf
  2. 然后，选择“使用自动分配的 IP 范围”，然后点击“继续”。查看相关信息后，选择“创建连接”。768ff5210e79676f
  3. 设置网络后，您可以继续创建集群。点击“创建集群”以完成集群设置，如下所示：

e06623e55195e16e.png

请务必将实例 ID 更改为“

vector-instance"

。

请注意，集群创建过程大约需要 10 分钟。成功运行后，您应该会看到一个屏幕，其中显示您刚创建的集群概览。

4. 数据注入

现在，该添加一个表，其中包含有关存储区的数据。前往 AlloyDB，选择主集群，然后选择 AlloyDB Studio：

847e35f1bf8a8bd8.png

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

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

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

91a86d9469d499c4

您可以在编辑器窗口中输入 AlloyDB 的命令，根据需要使用“Run”、“Format”和“Clear”选项。

启用扩展程序

为了构建此应用，我们将使用 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 字段。在本实验的后面部分，我们将填写其他字段。

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

要查看表格内容，请展开“探索”部分，直到您看到名为“wears”的表格。选择三角形图标 (⋮) 即可查看用于查询表的选项。一个 SELECT 语句将在新的“编辑器”标签页中打开。

cfaa52b717f9aaed.png

授予权限

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

GRANT EXECUTE ON FUNCTION embedding TO postgres;

向 AlloyDB 服务账号授予 Vertex AI User ROLE

转到 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;

这应该会为玩具说明返回嵌入矢量（看起来像一个浮点数数组），如下所示：

7d32f7cd7204e1f3

注意：在每秒允许向嵌入模型发出的嵌入请求数方面，免费层级下新建的 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;

我们来详细看一下此查询：

在此查询中，

  1. 用户的搜索文字为：“I want a white plush teddy bear toy with a floral pattern.”
  2. 我们要使用模型 text-embedding-005 在 embedding() 方法中将其转换为嵌入。在最后一步之后，此步骤应该看起来很熟悉，在此步骤中，我们将嵌入函数应用于表中的所有项。
  3. “<=>”表示使用 COSINE SIMILARITY 距离方法。您可以在 pgvector 文档中找到所有相似度度量。
  4. 我们会将嵌入方法的结果转换为矢量类型，使其与存储在数据库中的矢量兼容。
  5. LIMIT 5 表示我们想要为搜索文本提取 5 个最近邻。

结果如下所示：

fa7f0fc3a4c68804.png

从结果中可以观察到，匹配结果与搜索文本非常接近。请尝试更改文本，看看结果会如何变化。

7. 为 Toolbox 交互准备 AlloyDB

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

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

5f6e60e8dec2cea1

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

这需要几分钟才能完成。

8. 用于数据库安装的 MCP 工具箱

  1. 您可以创建一个项目文件夹，用于存储工具详细信息。在本例中，由于我们要处理的是玩具店数据，因此我们创建一个名为“toystore”的文件夹并进入该文件夹。转到 Cloud Shell 终端，确保您的项目处于选中状态并显示在终端的提示符中。从 Cloud Shell 终端运行以下命令：
mkdir toystore

cd toystore
  1. 运行以下命令，将工具箱下载并安装到新文件夹中：
# 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
  1. 切换到 Cloud Shell Editor。展开新创建的文件夹“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 price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

工具定义已设置完毕！

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

  1. 切换到 Cloud Shell 终端，然后输入以下命令，使用您的工具配置启动工具箱服务器：
./toolbox --tools_file "tools.yaml"
  1. 现在，如果您在云端以网页预览模式打开服务器，应该会看到 Toolbox 服务器启动并运行名为 get-toy-price. 的新工具

9. 适用于数据库的 MCP 工具箱的 Cloud Run 部署

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

  1. 请按照本页面中的说明逐个操作，直至到达“Deploy to Cloud Run”部分第 3 点处的 gcloud run deploy toolbox 命令。使用 VPC 网络方法时，您需要第一个选项，而不是第二个选项。
  2. 部署成功后，您将收到 Toolbox 服务器的 Cloud Run 部署端点。使用 C网址 命令对其进行测试。

提示：

请仔细按照页面中的说明操作，切勿错过。

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

10. 将您的应用与适用于数据库的 MCP 工具箱连接

在本部分中，我们将构建一个小型应用来测试您的工具是否能够与应用的需求交互并检索响应。

  1. 前往 Google Colab 并打开一个新的笔记本。
  2. 在笔记本中运行以下命令
!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)
  1. 结果应如下所示：

5074f209a86c4f15

这是在使用工具包 toolbox-langchain 的 Python 应用中明确调用的工具.

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

11. 将其迁移到云端！！！

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

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

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

  1. 您可以直接在 Cloud Functions 控制台中前往“测试”标签页，然后输入以下内容作为请求输入内容，以对其进行测试：

{

           "search": "White plush toy"

}

  1. 点击“测试函数”或在 Cloud Shell 终端中运行（您选择使用的任何方式）。您应该会在右侧的“Output”（输出）标题下方看到结果：

d7ba57cf5e5ca553.png

12. 恭喜

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