運用 Gemini 3 Flash 和 AlloyDB AI 建構自主供應鏈

1. 總覽

「會讀書的聊天機器人」時代即將結束。我們即將進入「智慧代理視覺」時代。

在本程式碼研究室中，我們將實作「確定性 AI 工程」，也就是建構不會猜測的 AI 系統。如果要求標準 AI 模型計算複雜圖片中的項目，模型通常會「產生幻覺」(猜測)。在供應鏈中，猜測很危險。如果 AI 猜測你有 12 個項目，但實際上你有 15 個，就會引發代價高昂的錯誤。

我們將運用 Gemini 3 Flash 中的全新「思考、行動、觀察」迴圈，建構自主供應鏈代理。不只是查看，而是調查。

確定性架構

我們會先從「盲目」和「失憶」系統開始。您將逐一「喚醒」其感官：

1. 眼睛 (Vision Agent)：我們啟用 Gemini 3 Flash 的程式碼執行功能，模型不會預測權杖來猜測數字，而是編寫 Python 程式碼 (OpenCV) 來確定像素數量。
2. 記憶體 (供應商代理程式)：我們啟用 AlloyDB AI 和 ScaNN (可擴充的最近鄰)。這樣一來，代理程式就能在數毫秒內，從數百萬個選項中找出零件的確切供應商。
3. 握手 (A2A 通訊協定)：我們使用標準化的 agent_card.json 啟用代理間通訊，讓 Vision Agent 自行向 Supplier Agent 下單。

建構項目

• 影像代理程式，可對攝影機畫面執行「視覺數學」運算。
• 供應商代理程式：由 AlloyDB ScaNN 提供支援，可進行高速向量搜尋。
• Control Tower 前端，提供即時 WebSocket 更新，可將自主迴圈視覺化。

課程內容

• 如何使用 Gemini API，透過 gemini-3-flash-preview 啟用 Agentic Vision。
• 瞭解如何在 AlloyDB 中使用 <=> (餘弦距離) 運算子實作向量搜尋。
• 如何使用 Auth Proxy 將 Cloud Shell 連接至 AlloyDB。

需求條件

• Chrome 或 Firefox 瀏覽器
• 已啟用計費功能的 Google Cloud 專案。
• Vision Agent 適用的 Gemini API 金鑰 (Google AI Studio 提供免費方案)。

2. 事前準備

建立專案

1. 在 Google Cloud 控制台的專案選取器頁面中，選取或建立 Google Cloud 專案。
2. 確認 Cloud 專案已啟用計費功能。瞭解如何檢查專案是否已啟用計費功能。

如要試用本程式碼研究室，請使用 GCP 試用帳單抵免額連結：https://bit.ly/cvs14-ghj

如何透過這個連結兌換抵免額？參閱。

3. 您將使用 Cloud Shell，這是 Google Cloud 中執行的指令列環境。點選 Google Cloud 控制台頂端的「啟用 Cloud Shell」。

4. 連至 Cloud Shell 後，請使用下列指令確認您已通過驗證，專案也已設為您的專案 ID：

gcloud auth list

就是這麼簡單！

現在可以一鍵設定了。下一個章節將：

• 自動開啟 Cloud Shell
• 複製存放區
• 透過互動式教學課程引導你完成整個設定程序

3. 在 Cloud Shell 中一鍵設定

我們已將設定程序簡化為導覽式 Cloud Shell 教學課程。所有作業都會自動完成，包括基礎架構佈建、AlloyDB 設定、Auth Proxy 設定和資料庫播種。

啟動 Cloud Shell 教學課程

⚠️ 重要事項 - 點選前請注意：點選下方按鈕後，系統會顯示安全對話方塊，詢問是否要「在 Cloud Shell 中開啟」。這項資訊會顯示在存放區複製作業「之前」。

須遵循的規定如下：

1. ✅ 勾選「信任存放區」方塊
2. ✅ 按一下「確認」

否則存放區不會複製。

準備好了嗎？按一下即可開啟專案，並查看逐步教學課程：

一鍵執行

後續步驟：

1. Cloud Shell 會開啟，並預先複製存放區
2. 右側會顯示教學面板，提供逐步操作說明
3. 系統會引導你完成下列步驟：

• 取得 Gemini API 金鑰 (提供免費方案)
• 在終端機中設定 GCP 專案
• 執行設定 (檢查 API、視需要啟用，並佈建 AlloyDB：約 15 分鐘)
• 進行 2 項重要程式碼變更 (啟用視覺和記憶體)
• 建立代理資訊卡 (A2A 通訊協定)
• 啟動所有服務

本教學課程為互動式，每個步驟都有編號，方便您追蹤進度。

📌 自動：設定指令碼會檢查驗證、API 和專案設定。如有需要注意的事項，系統會提示你。

💡 重新啟動安全無虞：如果設定卡住或失敗，您可以安全地重新執行 sh setup.sh。指令碼會偵測現有的 AlloyDB 執行個體，並略過佈建作業，從您上次中斷的地方繼續執行。

替代方法：手動設定

如要手動控制：

1. 開啟 Cloud Shell 並確認已設定專案

gcloud config get-value project

2. 視需要設定專案

gcloud config set project YOUR_PROJECT_ID

3. 複製存放區

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git
cd visual-commerce-gemini-3-alloydb

4. 執行設定

sh setup.sh

按照設定指令碼的畫面指示操作。

後續步驟：本教學課程會引導您完成剩餘步驟。完成後，請繼續前往第 4 節，瞭解幕後發生的情況

4. 幕後花絮：Auth Proxy 和資料庫播種

注意：如果您已完成完整的 Cloud Shell 教學課程，這些步驟都會自動完成。本節說明幕後發生的情況。

問題：AlloyDB 位於私有虛擬私有雲中。Cloud Shell 不屬於這個專案。無法直接連線。

修正方式：AlloyDB Auth Proxy 會在 Cloud Shell 上的 127.0.0.1:5432 與 AlloyDB 執行個體之間，建立經過 IAM 驗證的安全通道。如果執行個體已啟用公開 IP，Proxy 會使用該 IP；否則會透過 VPC 的私人 IP 連線。

setup.sh 執行的動作

1. 自動偵測到 AlloyDB 執行個體 (叢集、區域、專案)
2. 建立 .env，其中包含所有憑證 (GEMINI_API_KEY、DB_PASS、AlloyDB 詳細資料)
3. 已下載並啟動 Auth Proxy (如適用，請使用 –public-ip)
4. 資料庫已填入 8 個範例庫存零件 + ScaNN 索引

您的 .env 檔案已準備就緒。日後所有執行作業都會自動載入憑證。

確認是否成功

確認您仍在存放區根目錄中

pwd  # Should end with: visual-commerce-gemini-3-alloydb

檢查 Auth Proxy 是否正在執行

ps aux | grep alloydb-auth-proxy

建立的內容

• 庫存資料表，包含 8 個部分和 768 維度的嵌入內容
• ScaNN 索引 (idx_inventory_scann)，用於快速向量搜尋

常見錯誤：

• 「DB_PASS not set」：重新執行 sh setup.sh，重新建立 .env。
• 「Connection refused」：Auth Proxy 可能需要更多時間。等待 30 秒後再重試。
• 「No instance found」：驗證部署作業：gcloud alloydb instances list
• 「Bus error」(Auth Proxy 終止)：二進位檔損毀。修正：rm alloydb-auth-proxy && sh setup.sh

5. 步驟 1：記憶體 (供應商代理程式)

注意：如果您已完成 Cloud Shell 教學課程，就已進行這項程式碼變更。本節將說明這項功能的重要性及運作方式。

供應商代理程式會使用 AlloyDB ScaNN 記憶數百萬個零件。我們將其啟動為 A2A 伺服器，然後修正向量查詢。

The Audit：The Amnesiac

如果您現在查詢供應商代理程式 (使用預留位置 SQL)，系統會傳回找到的第一列，而非最接近的相符項目。沒有相似度概念。他患有失憶症。

啟動供應商代理程式

A2A 伺服器 (main.py) 會委派給 agent_executor.py，後者會將通訊協定橋接至 inventory.py 中的業務邏輯。

💡 疑難排解提示：如果收到「地址已在使用中」錯誤訊息，請終止現有程序，然後再試一次：

pkill -f uvicorn #Kill all uvicorn processes

步驟 1：前往代理程式目錄

cd agents/supplier-agent

步驟 2：安裝依附元件

pip install -r requirements.txt

步驟 3：啟動代理程式伺服器

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & 會在背景執行伺服器並抑制輸出內容，以免中斷終端機。

步驟 4：確認代理程式正在執行 (啟動後等待 2 到 3 秒)

curl http://localhost:8082/.well-known/agent-card.json

預期輸出內容：含有代理程式設定的 JSON (應會傳回，且沒有錯誤)

真實語意嵌入

設定期間，資料庫會以透過 Google Gen AI SDK 的 text-embedding-005 模型生成的實際語意嵌入做為種子。確保系統比對的是相似度，而非隨機向量。使用平行嵌入項目生成功能，為 13 個樣本項目建立有意義的 768 維度向量，擷取每個部分的語意含義，種子程序約需 10 秒。

AlloyDB 繞道：為何選擇 ScaNN？

注意：標準向量搜尋 (HNSW) 會耗用大量記憶體。當目錄成長到 1 億個零件時，索引會變得太大，無法存放在 RAM 中。ScaNN (可擴充的近似最鄰近) 使用向量量化。這項功能會壓縮向量，讓索引符合 CPU 的 L2 快取。因此速度最多比標準 HNSW 快 10 倍。

修正方式：實作 <=> 運算子

代理程式會隨附預留位置查詢。我們需要啟用 ScaNN 向量搜尋。

步驟 1：開啟商品目錄檔案

cd agents/supplier-agent

步驟 2：在 inventory.py 中找出 TODO

在第 47 到 60 行附近找出 find_supplier() 函式。您會看到：

# ============================================================
# CODELAB STEP 1: Implement ScaNN Vector Search
# ============================================================
# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

步驟 3：將預留位置 SQL 替換為 ScaNN 向量搜尋

刪除這兩行：

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

並替換為：

sql = """
SELECT part_name, supplier_name
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_vector,))

這項操作的作用：

• <=> 是 PostgreSQL 中的餘弦距離運算子
• ORDER BY part_embedding <=> %s::vector 會找出最接近的相符項目 (距離最短 = 語意最接近)
• %s::vector 會將嵌入陣列轉換為 PostgreSQL 的向量型別
• LIMIT 1 只會傳回最接近的相符項目
• ScaNN 索引會自動加快這項查詢的速度！

步驟 4：儲存檔案 (Ctrl+S 或 Cmd+S)

現在，代理程式會使用語意搜尋，而不是回傳隨機結果！

驗證

測試 A2A 探索和目錄：

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

預期結果：agent-card.json 會傳回代理資訊卡。Python 片段會從植入的資料傳回零件和供應商。

常見錯誤：

• 「找不到你所指定的檔案或目錄」：你不在存放區根目錄中。執行 cd 前往主目錄，然後執行 cd visual-commerce-gemini-3-alloydb，或使用 pwd 找出目前所在位置。
• 通訊埠 8082 正在使用中：終止現有程序：lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError：安裝依附元件：pip install -r requirements.txt
• 資料庫連線失敗：請確認 Auth Proxy 仍在執行中
• 驗證指令碼失敗：請確認種子已在步驟 4 中順利完成

6. 步驟 2：眼睛 (Vision Agent)

注意：如果您已完成 Cloud Shell 教學課程，代表您已啟用程式碼執行功能。本節將說明架構，以及這種做法為何能消除幻覺。

資料庫可供存取，現在就使用 Gemini 3 Flash 喚醒雙眼。Vision Agent 會透過程式碼執行功能執行「視覺數學」。A2A 伺服器 (main.py) 會委派給 agent_executor.py，後者會呼叫 agent.py 進行 Gemini 分析。

稽核：幻覺

如果詢問標準多模態模型「這張雜亂的圖片中有幾個盒子？」，模型會將圖片視為靜態快照並進行猜測。

• 模型會說：「我看到約 12 個盒子。」
• 實際情況：有 15 個盒子。
• 結果：供應鏈故障。

解決方法：喚醒思考、行動、觀察迴圈

我們啟用「程式碼執行」和「思考設定」，讓模型編寫 Python (OpenCV) 程式碼，以確定方式計算。

1. 開啟 agents/vision-agent/agent.py。
2. 找到 GenerateContentConfig 區段。
3. 取消註解 thinking_config=types.ThinkingConfig(...) 區塊和 tools=[types.Tool(code_execution=...)]。
4. 用戶端已設定為使用環境中的 GEMINI_API_KEY。

提示：thinking_level="LOW" 可兼顧速度和準確度。有效值：「MINIMAL」、「LOW」、「MEDIUM」、「HIGH」。需要 google-genai>=1.56.0。

架構注意事項：Vision Agent 使用 Gemini API (API 金鑰)，而 Supplier Agent 則使用 Vertex AI 嵌入 (GCP 憑證)。這種混合式做法可簡化視覺元件，同時維持企業級資料庫功能。

檔案：agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="LOW",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

為什麼 thinking_level="LOW"？

就這項特定工作 (透過執行程式碼計算項目) 而言，「低」可提供充足的推理預算，以：

• 規劃 Python 指令碼結構
• 決定要使用的圖片處理方法
• 確認數量與定界框數量相符

如果使用「高」設定，延遲時間和費用會增加 2 到 3 倍，但確定性工作不會因此提高準確度。如要進行複雜的多步驟推論 (例如「分析這項供應鏈中斷情形，並提出 3 個替代供應商建議，附上理由」。

成本效益最佳化是生產 AI 工程的重要技能：根據工作複雜度調整推理深度。

啟動 Vision Agent

🔄 路徑檢查：如果仍在 agents/supplier-agent/ 中，請先使用 cd ../.. 返回存放區根目錄。

步驟 1：前往 Vision 代理程式目錄

cd agents/vision-agent

步驟 2：安裝依附元件

pip install -r requirements.txt

步驟 3：啟動 Vision 代理程式伺服器

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

> /dev/null 2>&1 & 會在背景執行伺服器並抑制輸出內容，以免中斷終端機。

驗證

測試 A2A 探索功能：

curl http://localhost:8081/.well-known/agent-card.json

預期：含有代理程式名稱和技能的 JSON。您將在步驟 8 中，透過 Control Tower UI 測試實際的影像計數。

常見錯誤：

• 「No such file or directory」：您不在存放區根目錄中。使用 cd ../.. 返回存放區根目錄，或使用 pwd 檢查位置。
• 通訊埠 8081 正在使用中：終止現有程序：lsof -ti:8081 | xargs kill -9
• 未設定 GEMINI_API_KEY：使用 cat .env | grep GEMINI_API_KEY 檢查 .env 檔案是否存在於存放區根目錄中
• API 金鑰無效：確認金鑰正確且未過期
• 找不到 google-genai：安裝依附元件：pip install -r requirements.txt

7. 步驟 3：握手 (A2A 代理商卡片)

注意：如果您已完成 Cloud Shell 教學課程，就已建立這個代理程式資訊卡。本節說明 A2A 通訊協定，以及為何該通訊協定可實現即插即用的代理程式組合。

我們的代理程式會看到問題 (Vision)，並知道供應商 (Memory)。A2A 通訊協定可實現動態探索，前端會讀取每個代理程式的資訊卡，瞭解如何與代理程式通訊。

A2A 與傳統 REST API

方面	傳統 REST	A2A 通訊協定
端點探索	設定中硬式編碼的網址	透過 /.well-known/agent-card.json 動態設定
功能說明	API 文件 (供人閱讀)	技能 (機器可讀)
整合	每項服務的手動代碼	語意比對：「我需要搜尋庫存」→ 發現技能
已新增代理	更新所有用戶端的設定	無須設定，系統會自動探索

實際效益：在傳統微服務中，如果新增第三個「物流代理程式」，您需要使用其網址和 API 合約更新 Control Tower 的程式碼。透過 A2A，控制台會自動探索代理程式，並透過自然語言技能說明瞭解其功能。

因此，A2A 支援即插即用代理程式組合，也就是自主系統的架構模式。

修正方式：建立虛擬服務專員資訊卡

我們需要定義供應商代理可以執行的動作。

1. 將 agents/supplier-agent/agent_card_skeleton.json 複製到 agents/supplier-agent/agent_card.json。
2. 編輯檔案，將預留位置替換成相應的值：

變更前 (架構)：

{
  "name": "___FILL: agent-name ___",
  "description": "___FILL: what-this-agent-does ___"
}

編輯後：

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

3. 重新啟動供應商代理程式，載入新卡片：

步驟 1：停止執行中的代理程式

pkill -f "uvicorn main:app.*8082"

步驟 2：前往代理程式目錄

cd agents/supplier-agent

步驟 3：再次啟動代理程式

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

> /dev/null 2>&1 & 會在背景執行伺服器並抑制輸出內容，以免中斷終端機。

步驟 4：驗證新的代理程式資訊卡 (啟動後等待 2 到 3 秒)

curl http://localhost:8082/.well-known/agent-card.json

預期輸出內容：JSON，其中包含您填入的名稱、說明和技能。

8. 步驟 4：控制中心

注意：如果您已完成 Cloud Shell 教學課程，服務應該已在執行中。跳至下方的「測試系統」一節，存取 Control Tower 並觀看自主工作流程的運作情形。

使用 FastAPI + WebSockets 執行 Control Tower 前端。這項服務會透過 A2A 探索代理程式，並協調整個迴圈，即時更新。

啟動所有服務

啟動所有服務最簡單的方法：

確認您位於存放區根目錄

pwd  # Should end with: visual-commerce-gemini-3-alloydb

接著：

sh run.sh

這個單一指令會啟動：

• AlloyDB Auth Proxy (如果未執行)
• 通訊埠 8081 上的 Vision Agent
• 通訊埠 8082 上的供應商代理程式
• Control Tower (通訊埠 8080)

等待約 10 秒，讓所有服務完成初始化。

💡 疑難排解提示：如果 run.sh 失敗並顯示「address already in use」錯誤：

停止所有服務，然後再試一次

pkill -f uvicorn

sh run.sh

如果服務仍在執行先前的嘗試，就會發生這種情況。

測試系統

存取 Control Tower：

1. 按一下 Cloud Shell 工具列中的「網頁預覽」按鈕 (眼睛圖示 👁️)
2. 選取「透過以下通訊埠預覽：8080」
3. 系統會在新的分頁中開啟 Control Tower 資訊主頁

注意：前端會使用即時 WebSocket，提供線上服務專員的最新資訊。您會看到代理程式卡片在思考、分析及採取行動時更新，不需要重新整理頁面。

執行示範：

1. 右上角：連線狀態 (綠色的「Live」點)、DEMO/AUTO 模式切換開關和音訊控制選項
2. 中心：主要工作流程畫布，可上傳圖片及查看分析結果
3. 側邊面板 (分析期間會顯示)：工作流程時間軸 (左側)、進度追蹤和程式碼檢視器 (右側)

方法 1：快速入門 (建議)

1. 首頁會顯示「快速入門」部分，並提供範例圖片
2. 按一下任一範例圖片，即可自動開始分析
3. 觀看自主工作流程 (約 30 至 45 秒)

選項 2：上傳自己的檔案

1. 拖曳或點選即可瀏覽並上傳倉庫/貨架圖片 (PNG、JPG，大小上限為 10 MB)
2. 按一下「Initiate Autonomous Workflow」(啟動自主工作流程)
3. 觀察 4 階段管道

發生情況：

1. 代理探索：A2A 通訊協定模式會顯示 Vision 代理和供應商代理資訊卡，以及相關技能和端點
2. 影像分析：Gemini 3 Flash 會生成並執行 Python 程式碼 (OpenCV)，計算項目數量。進度列會顯示子步驟。在偵測到的項目上疊加定界框。結果徽章顯示「✓ 程式碼已驗證」或「~ 預估」
3. 供應商比對：AlloyDB ScaNN 向量搜尋動畫。顯示搜尋查詢 (例如：「工業金屬盒」)。結果資訊卡會顯示相符零件、供應商和信心分數
4. 已下單：收據卡片，內含訂單 ID、數量和詳細資料

提示：請開啟「DEMO」模式 (右上角)，以便在簡報期間暫停每個階段。在「AUTO」模式下，工作流程會持續執行。

發生什麼事

Control Tower 使用 A2A 通訊協定，透過 /.well-known/agent-card.json 探索兩個代理程式，協調視覺分析 (Gemini 3 Flash 搭配程式碼執行)，執行向量搜尋 (AlloyDB ScaNN)，並下達自主訂單，所有作業都透過 WebSocket 即時更新。每個代理程式都會透過 A2A 標準公開功能，因此無需自訂 SDK 即可進行隨插即用的組合。瞭解詳情：A2A 通訊協定

疑難排解

路徑相關錯誤：

• 執行指令時顯示「No such file or directory」：您不在存放區根目錄中。

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

服務錯誤：

• 「Address already in use」：先前執行的程序仍處於有效狀態。

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

• 服務未啟動：檢查通訊埠是否遭佔用：

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

• AlloyDB 拒絕連線：確認 Auth Proxy 是否正在執行：

ps aux | grep alloydb-auth-proxy

AlloyDB 連線問題：

如果看到連線至伺服器 (127.0.0.1，通訊埠 5432) 失敗的訊息：

如果看到連線至伺服器 (127.0.0.1，通訊埠 5432) 失敗的訊息：

1. 檢查 Auth Proxy：ps aux | grep alloydb-auth-proxy
2. 確認已啟用公開 IP：gcloud alloydb instances describe INSTANCE_NAME –cluster=CLUSTER_NAME –region=us-central1 –format="value(ipAddress)"
3. 本機開發 (非 Cloud Shell)：
4. 問題：Cloud Shell 會自動運作，但本機需要授權網路
5. 解決方案：重新執行 sh setup.sh，並在系統提示時選擇選項 1 (授權 0.0.0.0/0)
6. 安全性注意事項：即使使用 0.0.0.0/0，連線仍須符合下列條件：
7. 有效的 GCP 憑證 (應用程式預設憑證)
8. 資料庫密碼
9. mTLS 加密 (由驗證 Proxy 處理)

9. 清除

為避免產生費用，請使用自動清除指令碼終止所有資源：

# From repo root
sh cleanup.sh

這項操作會安全移除：

• AlloyDB 叢集 (主要費用驅動因素)
• Cloud Run 服務 (如已部署)
• 相關聯的服務帳戶

指令碼會先要求確認，再刪除任何內容。

10. 參考資料與延伸閱讀資源

本程式碼研究室中的所有技術聲明，都經過 Google Cloud 和 Google AI 官方文件驗證。

官方說明文件

Gemini 3 Flash：

• 程式碼執行 API：https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
• 開發人員指南：https://ai.google.dev/gemini-api/docs/gemini-3
• 模型說明文件：https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
• 模型資訊卡：https://deepmind.google/models/gemini/flash/

AlloyDB AI 和 ScaNN：

• ScaNN 效能基準：https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
• 瞭解 ScaNN 索引：https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
• AlloyDB AI 深入探討：https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
• 最佳調整做法：https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
• AlloyDB 說明文件：https://cloud.google.com/alloydb/docs

價格資訊：

• Gemini API 價格：https://ai.google.dev/gemini-api/docs/pricing
• AlloyDB 定價：https://cloud.google.com/alloydb/pricing
• Vertex AI 定價：https://cloud.google.com/vertex-ai/pricing

已驗證的效能聲明

功能	著作權聲明	資料來源
ScaNN 與 HNSW (已篩選) 的比較	速度快了 10 倍	Google Cloud 網誌 (已驗證)
ScaNN 與 HNSW (標準)	速度快了 4 倍	Google Cloud 網誌 (已驗證)
ScaNN 記憶體用量	縮小 3 到 4 倍	Google Cloud 網誌 (已驗證)
ScaNN 索引建構時間	速度快了 8 倍	Google Cloud 網誌 (已驗證)
程式碼執行逾時	最多 30 秒	Google Cloud 文件 (已驗證)
程式碼執行檔案 I/O	不支援	Google Cloud 文件 (已驗證)
溫度=0 的行為	確定性輸出	經社群驗證

其他資源

服務專員對服務專員 (A2A) 通訊協定：

• A2A 可讓代理程式探索和通訊標準化
• 在 /.well-known/agent-card.json 顯示的服務專員資訊卡
• 自主代理程式協作的新興標準

ScaNN 研究：

• 根據 Google 研究 12 年的成果
• 為 Google 搜尋和 YouTube 提供數十億規模的支援
• 正式發布日期：2024 年 10 月
• 第一個 PostgreSQL 向量索引，適用於數百萬到數十億個向量

11. 挑戰模式：提升代理程式技能

您已建構出可運作的自主供應鏈。準備好進一步提升收益了嗎？這些挑戰會將您學到的模式應用於新問題。

挑戰 1：以圖片為依據的搜尋 (多模態嵌入)

目前流程：Vision Agent 計算項目 → 生成文字查詢 → Supplier Agent 嵌入文字 → 搜尋 AlloyDB

挑戰：完全略過文字，直接將裁剪後的圖片傳送給供應商代理商。

提示：

1. Vision Agent 的程式碼執行作業可以從架子圖片裁剪個別商品
2. Vertex AI 的多模態嵌入@001 模型可直接嵌入圖片
3. 修改 inventory.py，接受圖片位元組而非文字
4. 更新 A2A 技能說明，指出「接受：image/jpeg 或 text」

重要性：對於外觀複雜的零件 (顏色差異、損壞、包裝差異)，圖像搜尋的準確度更高。

挑戰 2：可觀測性 - 公開相關資訊來建立信任

目前狀態：系統運作正常，但您無法查看「幕後」情況

挑戰：檢查 AlloyDB 的查詢記錄，證明向量搜尋正在執行。

步驟：

• AlloyDB 預設會啟用查詢洞察功能。如要驗證，請執行：

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

• 透過使用者介面執行供應商搜尋
• 查看實際執行的 SQL：

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

預期輸出內容：您會看到確切的 ORDER BY part_embedding <=> $1::vector LIMIT 1 查詢，以及執行時間。

重要性：可觀測性有助於建立信任感。當利害關係人詢問「這個代理程式如何做出決策？」時，您可以向他們展示查詢計畫，而不只是輸出內容。

挑戰 3：多代理程式組合

挑戰：新增第三位代理人 (物流代理人)，根據倉庫位置和商品重量計算運費。

架構：

• Vision Agent 輸出內容：項目數量
• 供應商代理程式輸出內容：供應商位置
• 物流代理人 (新功能) 輸入：目的地、重量 → 輸出：運費 + 預計抵達時間

提示：A2A 通訊協定可輕鬆完成這項作業，只要建立含有 calculate_shipping 技能的新代理程式資訊卡即可。Control Tower 會自動探索該帳戶。

您要學習的模式：這是以代理為導向的架構核心，也就是由小型可組合的專家建構複雜系統。

12. 結語

您已成功從生成式 AI 轉移至代理式 AI。

我們建構的內容：

• Vision：我們已將「猜測」取代為程式碼執行 (透過 API 金鑰使用 Gemini 3 Flash)。
• 記憶體：我們以 AlloyDB ScaNN (透過 GCP) 取代「緩慢搜尋」。
• 動作：我們將「API 整合」替換為 A2A 通訊協定。

混合式架構的優點：

本程式碼研究室示範了混合式做法：

• Vision Agent：使用 Gemini API (API 金鑰) - 提供簡單的免費層級，不需支付 Google Cloud 費用
• 供應商服務專員：使用 GCP (Vertex AI + AlloyDB) - 企業級，符合法規要求

這是自主經濟的架構。你可以保留這組代碼。

後續步驟

• 取得 Gemini API 金鑰 (提供免費層級)
• 查看 Gemini API 說明文件
• 查看 AlloyDB AI 說明文件
• 探索 Gemini 程式碼執行功能