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

為 AlloyDB 的生成式 AI 和代理程式應用程式安裝並設定資料庫專用的 MCP Toolbox

程式碼研究室簡介

subject上次更新時間：4月 28, 2025
account_circle作者：Author: Abirami Sukumaran Anubhav Dhawan

1. 總覽

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

簡化開發流程：只需不到 10 行的程式碼，就能將工具整合至您的代理程式、在多個代理程式或架構之間重複使用工具，以及輕鬆部署新版工具。

效能更佳：最佳做法，例如連線集區、驗證等。

強化安全性：整合驗證機制，讓他人以更安全的方式存取資料。

端對端觀測能力：內建 OpenTelemetry 支援，可立即使用的指標和追蹤記錄。

Toolbox 位於應用程式調度架構和資料庫之間，提供用於修改、發布或叫用工具的控制平面。這項服務可提供集中式位置來儲存及更新工具，簡化工具管理作業，讓您在代理程式和應用程式之間共用工具，並更新這些工具，而無須重新部署應用程式。

建構項目

在本研究室中，您將建構應用程式，使用工具執行可從代理程式或生成式 AI 應用程式叫用的簡易資料庫 (AlloyDB) 查詢。為此，您

  1. 安裝資料庫適用的 MCP 工具箱
  2. 在 Toolbox 伺服器上設定工具 (設計在 AlloyDB 中執行工作)
  3. 在 Cloud Run 中部署資料庫適用的 MCP 工具箱
  4. 使用已部署的 Cloud Run 端點測試工具
  5. 建構 Cloud Run 函式以叫用 Toolbox

需求條件

  • 瀏覽器，例如 Chrome 或 Firefox
  • 已啟用計費功能的 Google Cloud 專案 (請參閱下一節的步驟)。

2. 事前準備

建立專案

  1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 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

您也可以透過控制台搜尋各項產品或使用這個連結，藉此改用 gcloud 指令。

如果遺漏任何 API，您隨時可以在導入過程中啟用。

如要瞭解 gcloud 指令和用法，請參閱說明文件。

3. 資料庫設定

在這個研究室中，我們會使用 AlloyDB 做為資料庫保存零售資料。它會使用叢集來保存所有資源，例如資料庫和記錄檔。每個叢集都有一個「主要執行個體」，用來提供資料的存取點。資料表會保留實際資料。

讓我們建立要載入電子商務資料集的 AlloyDB 叢集、執行個體和資料表。

建立叢集和執行個體

  1. 前往 Cloud 控制台的 AlloyDB 頁面。

如要在 Cloud 控制台中找到大多數頁面，只要使用控制台的搜尋列搜尋頁面，即可輕鬆找到所需頁面。

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

f76ff480c8c889aa.png

  1. 您會看到類似下方的畫面。建立含有下列值的叢集和執行個體 (請確保這兩個值相符，以便從存放區複製應用程式程式碼)：
  • 叢集 ID：「vector-cluster」
  • 密碼：「alloydb」
  • 與 PostgreSQL 15 相容
  • 區域：「us-central1」
  • 網路：「default」

538dba58908162fb.png

  1. 選取預設網路後，系統會顯示以下畫面，選取「設定連線」。
    7939bbb6802a91bf.png
  2. 請在這裡選取「使用系統自動分配的 IP 範圍」，然後點選「繼續」。詳閱資訊後，請選取「建立連線」。768ff5210e79676f.png
  3. 網路設定完成後，即可繼續建立叢集。按一下「建立叢集」，完成叢集的設定程序，如下所示：

e06623e55195e16e.png

請務必將執行個體 ID 變更為 "

vector-instance"

。

請注意，叢集建立作業大約需要 10 分鐘。成功後，您應會看到剛剛建立的叢集總覽畫面。

4. 資料擷取

接著新增內含該商店資料的資料表。前往 AlloyDB，然後依序選取主要叢集和 AlloyDB Studio：

847e35f1bf8a8bd8.png

您可能需要等待執行個體建立完畢。完成後，請使用您在叢集建立期間建立的憑證登入 AlloyDB。使用下列資料向 PostgreSQL 進行驗證：

  • 使用者名稱：「postgres」
  • 資料庫：「postgres」
  • 密碼：「alloydb」

成功在 AlloyDB Studio 中通過驗證後，您就能在編輯器中輸入 SQL 指令。如要新增多個編輯器視窗，請使用最後一個視窗右側的加號。

91a86d9469d499c4.png

如有需要，您可以在編輯器視窗中輸入「執行」、「格式」和「清除」選項，為 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 欄位。本研究室的後續部分會填妥其他欄位。

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

如要查看表格內容，請展開「多層檢視」部分，直到看見「服飾」表格為止。選取三號 (⋮) 即可查看查詢資料表的選項。SELECT 陳述式會在新的「編輯器」分頁中開啟。

cfaa52b717f9aaed.png

授予權限

執行下列陳述式，將 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. 建立結構定義的嵌入

電腦處理數字比處理文字要簡單許多。嵌入系統會將文字轉換為一系列稱為「向量嵌入」的浮點數。無論文字的寫法、使用的語言等，都能代表文字。

舉例來說，海濱地點可稱為「在水上」、「海濱」、「從你的房間走到大海」、「畢爾拉默」、「三貴賓」、「三出價」和「三者行政區」。這些詞看起來不一，但兩者的語意含意不盡相同，但在機器學習術語中應該彼此相近。

現在資料和結構定義已準備就緒，我們將執行 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.png

注意：如果在免費方案中新建 Google Cloud 專案，嵌入模型每秒允許的嵌入要求數量可能會有配額問題。建議您對 ID 使用篩選查詢，然後選擇性地選擇 1 到 5 筆記錄，然後產生嵌入項目。

6. 執行 Vector Search

現在資料表、資料和嵌入項目都已準備就緒，接下來讓我們開始針對使用者搜尋文字執行即時向量搜尋。

假設使用者提問：

「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. 準備 AlloyDB 以便使用 Toolbox 互動功能

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

  1. 前往 AlloyDB 執行個體，按一下「編輯」，然後開啟「編輯主要執行個體」頁面。
  2. 前往「公開 IP 連線」專區，勾選「啟用公開 IP」核取方塊，然後輸入 Cloud Shell 機器的 IP 位址。
  3. 如要取得 Cloud Shell 機器的 IP，請前往 Cloud Shell 終端機並輸入 ifconfig。從結果中找出 eth0 內地址，然後將最後 2 位數替換成 0.0 的遮罩大小：「/16」。例如「XX.XX.0.0/16」，其中 XX 是數字。
  4. 將這個 IP 貼到編輯執行個體頁面的「網路」文字方塊內。

5f6e60e8dec2cea1.png

  1. 完成後，點選「更新執行個體」。

這項作業會在幾分鐘內完成。

8. 安裝資料庫的 MCP 工具箱

  1. 您可以建立專案資料夾來儲存工具詳細資料。在本例中，由於我們處理的是玩具儲存資料，我們可以建立名為「toystore」的資料夾，並瀏覽到這個資料夾。前往「Cloud Shell Terminal」，確認已選取專案，並在終端機提示中顯示該專案。透過 Cloud Shell 終端機執行下列指令：
mkdir toystore

cd toystore
  1. 執行下列指令，在新資料夾中下載並安裝 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
  1. 切換至 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 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. 按照這個頁面中的操作說明逐一進行，直到找到位於「部署至 Cloud Run」一節下方 3 點的 gcloud run deploy toolbox 指令為止。使用虛擬私有雲網路方法時，您需要使用第一個選項，而非第二個選項。
  2. 部署成功後，您會收到 Toolbox 伺服器的已部署 Cloud Run 端點。使用 CURL 指令進行測試。

提示：

請詳閱頁面中的操作說明，並確實遵守。

現在可以在代理程式應用程式中使用新部署的工具了！

10. 將應用程式與資料庫適用的 MCP Toolbox 連結

在這一部分中，我們會建構一個小型應用程式來測試工具，以便與應用程式的需求互動並擷取回應。

  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.png

如果使用 toolbox-langchain. 工具包的 Python 應用程式，系統會明確叫用這項工具

  1. 如要使用這項工具，並繫結至 LangGraph 整合應用程式中的代理程式，您可以使用 langgraph 工具包輕鬆達成此目的。
  2. 相關詳情請參閱程式碼片段。

11. 使用雲端！

讓我們把這個 Python 程式碼片段納入 Cloud Run 函式中，使其成為無伺服器架構！

  1. 從程式碼存放區資料夾複製原始碼，以便將內容傳送到 Cloud Functions。
  2. 前往「Cloud Run Functions」控制台，然後按一下「建立 FUNCTION」。
  3. 請讓示範應用程式不要進行驗證，然後在下一頁選取 Python 3.11 執行階段。
  4. 從步驟 1 提供的來源存放區複製 main.py 和 requirements.txt 檔案，然後貼上各個檔案。
  5. 使用您的伺服器網址取代 main.py 中的伺服器網址。
  6. 部署函式之後，您就已取得 REST 端點，可以在玩具店網路應用程式中使用價格預測工具。
  7. 端點應如下所示：

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

  1. 只要前往「測試」分頁並輸入下列內容做為要求輸入，即可直接在 Cloud Functions 控制台中進行測試：

{

           "search": "White plush toy"

}

  1. 按一下 [測試函式] 或在 Cloud Shell 終端機中，視需要執行。結果會顯示在右側的「Output」(輸出) 標題下方：

d7ba57cf5e5ca553.png

12. 恭喜

恭喜！您已成功建立穩固的模組化工具，可在各資料庫、平台和生成式 AI 自動化調度管理架構中互動，建立您的虛擬應用程式。

bug_report 回報錯誤