在 AlloyDB 上为生成式 AI 和代理应用安装和设置 Toolbox

1. 概览

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

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

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

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

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

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

构建内容

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

1. 安装 Toolbox
2. 在 Toolbox 服务器上设置工具（用于在 AlloyDB 中执行任务）
3. 在 Cloud Run 上部署 Toolbox
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”。

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

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

7. 在 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 集群、实例和表，以便加载电子商务数据集。

创建集群和实例

1. 在 Cloud 控制台中，前往 AlloyDB 页面。

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

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

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

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

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

请务必将实例 ID 更改为“

vector-instance"

。

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

4. 数据提取

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

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

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

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

您可以在编辑器窗口中输入 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 字段。我们将在稍后的实验中填写其他字段。

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

如需查看表内容，请展开“Explorer”部分，直到看到名为 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 项目，则可能需要继续使用较低版本的文本嵌入模型，例如 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;

我们来详细看看这个查询：

在此查询中，

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

结果如下所示：

如您在结果中所见，匹配项与搜索文本非常接近。尝试更改文字，看看结果如何变化。

7. 为 Toolbox 互动准备 AlloyDB

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

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

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

此过程需要几分钟才能完成。

8. 工具箱安装

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

mkdir toystore

cd toystore

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

# 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

3. 切换到 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 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，请参阅此文档。

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

./toolbox --tools_file "tools.yaml"

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

9. Toolbox 的 Cloud Run 部署

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

1. 依次按照此页面中的说明操作，直到找到“部署到 Cloud Run”部分下第 3 点中的 gcloud run deploy toolbox 命令。您需要使用第一个选项，而不是第二个选项（适用于使用 VPC 网络方法的情况）。
2. 成功部署后，您将收到 Toolbox 服务器的 Cloud Run 部署端点。使用 C网址 命令进行测试。

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

10. 将您的应用与 Toolbox 相关联

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

1. 前往 Google Colab，然后打开一个新笔记本。
2. 在笔记本中运行以下代码

pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

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

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

# Print result
print(result)

3. 您应该会看到如下结果：

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

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

11. 将其上传到云端！

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

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

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

2. 您可以直接在 Cloud Functions 控制台中对其进行测试，只需前往“测试”标签页，然后输入以下请求输入即可：

{

               "`search`"`:` "`White plush toy`"

}

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

12. 恭喜

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