本頁面由 Cloud Translation API 翻譯而成。

在 AlloyDB 上為生成式 AI 和代理應用程式安裝及設定 Toolbox

1. 總覽

資料庫專用的生成式 AI 工具箱是 Google 推出的開放原始碼伺服器，可讓您更輕鬆地建構生成式 AI 工具，與資料庫互動。它可處理連線資源池、驗證等複雜作業，讓您更輕鬆、快速且安全地開發工具。這項服務可協助您建構生成式 AI 工具，讓服務專員存取資料庫中的資料。工具箱提供以下功能：

簡化開發作業：透過不到 10 行程式碼，將工具整合至代理程式，在多個代理程式或架構之間重複使用工具，並更輕鬆地部署新版本的工具。

提升效能：採用連線集區、驗證等最佳做法。

強化安全性：整合式驗證機制，可更安全地存取資料。

端對端監控：內建 OpenTelemetry 支援功能的即用指標和追蹤記錄。

Toolbox 位於應用程式調度架構和資料庫之間，提供用於修改、發布或叫用工具的控制平面。這項服務可為您提供集中式位置，用於儲存及更新工具，讓您在不同服務項目和應用程式之間共用工具，並且無須重新部署應用程式即可更新這些工具。

建構項目

在本實驗室中，您將建構應用程式，使用工具執行簡單的資料庫 (AlloyDB) 查詢，可從代理程式或生成式 AI 應用程式叫用。您需要

安裝 Toolbox
在 Toolbox 伺服器上設定工具 (用於在 AlloyDB 中執行工作)
在 Cloud Run 上部署 Toolbox
使用已部署的 Cloud Run 端點測試工具
建構 Cloud Run 函式以叫用工具箱

需求條件

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：

您也可以使用單一指令執行下列操作，但如果您是試用版帳戶使用者，可能會在嘗試大量啟用這些功能時遇到配額問題。因此，指令會以每行一項的方式輸入。

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 Console 中找到大部分的頁面，請使用控制台的搜尋列進行搜尋。

在該頁面中選取「建立叢集」：

您會看到類似下方的畫面。使用下列值建立叢集和執行個體 (如果您要從存放區複製應用程式程式碼，請務必確認這些值相符)：

叢集 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 指令，並視需要使用「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 欄位。其他欄位會在稍後的實驗室中填入。

複製該處的程式碼行/插入陳述式，然後將這些行貼到空白編輯器分頁中，並選取「RUN」。

如要查看資料表內容，請展開「Explorer」專區，直到看到名為 apparels 的資料表。選取三橫線 (⋮) 圖示，即可查看查詢表格的選項。系統會在新編輯器分頁中開啟 SELECT 陳述式。

授予權限

執行下列陳述式，將 embedding 函式的執行權限授予使用者 postgres：

GRANT EXECUTE ON FUNCTION embedding TO postgres;

將 Vertex AI 使用者角色授予 AlloyDB 服務帳戶

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

讓我們進一步瞭解這個查詢：

在這個查詢中，

使用者的搜尋文字為：「I want a white plush teddy bear toy with a floral pattern.」
我們會使用模型 text-embedding-005，將其轉換為 embedding() 方法中的嵌入資料。在上一節中，我們將嵌入函式套用至資料表中的所有項目，因此這個步驟應該會讓您感到熟悉。
「<=>」代表使用 COSINE SIMILARITY 距離方法。如要查看所有可用的相似度評估指標，請參閱 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 貼到「Networks」(網路) 文字方塊的「Authorized external networks」(授權外部網路) 中。

完成後，按一下「更新執行個體」。

這項作業需要幾分鐘才能完成。

8. Toolbox 安裝方式

您可以建立專案資料夾來儲存工具詳細資料。在本例中，我們要處理玩具店資料，因此請建立名為「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"

現在，如果您在雲端以網路預覽模式開啟伺服器，應該會看到 Toolbox 伺服器已啟動並執行名為 get-toy-price. 的新工具。

9. Toolbox 的 Cloud Run 部署作業

讓我們將其部署至 Cloud Run，以便實際使用這項工具。

依序按照這個頁面中的操作說明進行，直到「部署至 Cloud Run」部分的第 3 點出現 gcloud run deploy toolbox 指令為止。您需要第一個選項，而非第二個選項，因為後者是用於使用 VPC 網路方法時。
成功部署後，您會收到 Toolbox 伺服器的 Cloud Run 部署端點。使用 CURL 指令進行測試。

您已準備就緒，可以在代理應用程式中使用新部署的工具！

10. 將應用程式連結至 Toolbox

在本節中，我們將建構一個小型應用程式，用於測試您的工具，以便與應用程式互動並擷取回應。

前往 Google Colab 並開啟新的筆記本。
在筆記本中執行下列指令

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)

結果應如下所示：

這是在使用工具包的 Python 應用程式中明確叫用的工具 toolbox-langchain.

如果您想使用這項工具，並將其繫結至 LangGraph 整合應用程式中的代理程式，可以輕鬆透過 langgraph 工具包完成。
請參考程式碼片段。

11. 將其帶入雲端！

我們將這個 Python 程式碼片段納入 Cloud Run 函式，讓它成為無伺服器服務！

從程式碼 repo 資料夾複製原始碼，將其上傳至 Cloud Functions。
前往 Cloud Run Functions 主控台，然後按一下「CREATE FUNCTION」(建立函式)。
請讓示範應用程式保持未驗證狀態，並在下一頁中選取 Python 3.11 執行階段。
從步驟 1 中分享的來源存放區複製 main.py 和 requirements.txt 檔案，然後貼到各個檔案中。
部署函式後，您就會取得 REST 端點，可在玩具店網路應用程式中存取價格預測工具。
端點應如下所示：

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

您可以前往「測試」分頁，並輸入以下要求輸入內容，直接在 Cloud Functions 控制台中測試：

{

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

}

按一下「測試函式」或在 Cloud Shell 終端機中執行 (視您選擇的選項而定)。結果會顯示在右側的「輸出」標題下方：

12. 恭喜

恭喜！您已成功建立可跨資料庫、平台和生成式 AI 調度架構互動的強大模組化工具，以利建立代理應用程式。