為 Gen AI 安裝及設定 MCP 工具箱；AlloyDB 上的代理程式應用程式

1. 總覽

MCP Toolbox for Databases 是 Google 的開放原始碼伺服器，可簡化建構生成式 AI 工具的程序，方便您與資料庫互動。這項服務可處理連線集區和驗證等複雜作業，讓您更輕鬆、快速且安全地開發工具。這項工具可協助您建構生成式 AI 工具，讓 AI 代理能存取資料庫中的資料。工具箱提供：

簡化開發作業：在不到 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：

您也可以執行單一指令來執行下列操作，但如果您是試用帳戶使用者，嘗試大量啟用這些功能時可能會遇到配額問題。因此，每個指令都會單獨列於一行。

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 欄位。其他欄位會在實驗室的後續部分填寫。

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

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

授予權限

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

GRANT EXECUTE ON FUNCTION embedding TO postgres;

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

前往 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.」
我們要在 embedding() 方法中使用模型 text-embedding-005，將其轉換為嵌入。上一個步驟中，我們已將嵌入函式套用至表格中的所有項目，因此這個步驟應該很熟悉。
「<=>」代表使用「餘弦相似度」距離方法。如要查看所有可用的相似度測量方式，請參閱 pgvector 說明文件。
我們會將嵌入方法的結果轉換為向量型別，使其與資料庫中儲存的向量相容。
LIMIT 5 代表我們要為搜尋文字擷取 5 個最鄰近的項目。

結果如下所示：

如搜尋結果所示，相符項目與搜尋文字相當接近。請嘗試變更文字，看看結果會如何變化。

7. 準備 AlloyDB 以進行 Toolbox 互動

準備設定 Toolbox 時，請在 AlloyDB 執行個體中啟用公開 IP 連線，讓新工具可以存取資料庫。

前往 AlloyDB 執行個體，按一下「EDIT」，然後前往「Edit primary instance」頁面。
前往「Public IP connectivity」專區，勾選「Enable public 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/mcp-toolbox-for-databases/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

切換至 Cloud Shell 編輯器。展開新建立的「toystore」資料夾，然後建立名為 tools.yaml 的新檔案。複製下列內容。將 YOUR_PROJECT_ID 替換為您的專案 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. 將 MCP Toolbox for Databases 部署至 Cloud Run

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

請按照這個頁面的說明操作，直到看到「Deploy to Cloud Run」(部署至 Cloud Run) 專區的第 3 點出現 gcloud run deploy toolbox 指令為止。您需要第一個選項，而不是第二個選項 (適用於使用虛擬私有雲網路方法時)。
部署成功後，您會收到 Toolbox 伺服器的 Cloud Run 部署端點。使用 CURL 指令進行測試。

提示：

請仔細按照頁面上的指示操作，不要遺漏任何步驟。

您已設定妥當，現在可以在代理程式應用程式中使用新部署的工具了！

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 控制台，然後按一下「CREATE FUNCTION」。
請為示範應用程式保留未經驗證的狀態，並在下一頁選取 Python 3.11 執行階段。
從步驟 1 中共用的來源存放區複製 main.py 和 requirements.txt 檔案，然後貼到對應的檔案中。
將 main.py 中的伺服器網址替換為您的伺服器網址。
部署函式後，您就會取得 REST 端點，供玩具店網頁應用程式存取價格預測工具。
端點應如下所示：

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

您可以直接在 Cloud Functions 控制台測試，方法是前往「測試」分頁，然後輸入下列內容做為要求輸入：

{

           "search": "White plush toy"

}

點選「TEST THE FUNCTION」或在 Cloud Shell 終端機中執行您選擇使用的任何項目。您應該會在右側的「輸出」標題下方看到結果：

12. 恭喜

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

為 Gen AI 安裝及設定 MCP 工具箱；AlloyDB 上的代理程式應用程式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。