Blog E

[Workshop][Gemini CLI] Build with AI 2026 實戰筆記：用 Gemini CLI + 官方 MCP，從零到上線一隻 Google Drive LINE Bot

Thu, 14 May 2026 00:00:00 +0000

(活動：Build with AI 2026 @ Google Taipei 101 / 簡報：SpeakerDeck / 教材：kkdai/BwAI-2026 / 範例：kkdai/bwai2026-sample)

前情提要：當 CLI 變成「會思考的同事」

2026 年 Google I/O 之後，Gemini CLI 已經不只是另一個包了 LLM 的 terminal 玩具，而是一個可以掛 MCP、會自己 plan、會自己跑 gcloud、會在不懂的時候停下來問你的開發工具。

這次在 Build with AI 2026 的工作坊裡，我把這套工具流壓縮成兩個 hands-on session：

Workshop 1：環境準備 + 兩個必裝的官方 MCP —— 讓 Gemini CLI 接上 Google 的官方知識與 Maps Platform。
Workshop 2：對 Gemini CLI 講一句話，把 LINE Bot 部署上 Cloud Run —— 不再手敲那串又長又痛苦的 gcloud run deploy ...。

整份教材已開源在 kkdai/BwAI-2026，範例專案在 kkdai/bwai2026-sample，活動投影片放在 SpeakerDeck。這篇是現場 walkthrough 的完整文字版，含我們當天在台上撞到的三個雷。

為什麼是 Gemini CLI + MCP？先看時間軸

過去一年 Gemini API 與其生態的更新節奏非常密：

時間	新東西	對工作流的影響
2025/08	Gemini YouTube Video Understanding	直接 URL 餵影片給模型
2025/11	Gemini File Search	Managed RAG，不用自己接 vector DB
2025/12	Google Search Grounding (Vertex)	模型答案能 grounded 到 search 結果
2025/12	Maps Grounding & Maps Platform Assist MCP	地圖場景原生上身
2026/02	Google Developer Knowledge API + MCP Server	官方文件變成可被 LLM 查詢的工具
2026/03	Gemini 3 Flash + Tool Combo	單次 call 串多個 grounding tool

核心觀察：Google 把每個新能力都做成 MCP Server，意思是 Gemini CLI 只要 mcp add 一行，就能把 IDE 從「會寫 code 的 LLM」升級成「會用 Google 官方資源寫 code 的 LLM」。

這次 workshop 我選了兩個對 LINE Bot 開發者最有感的 MCP 來示範。

Workshop 1：環境準備與官方 MCP 安裝

為什麼建議用 Cloud Shell 開場

現場工作坊最怕的就是 「老師我這邊 gcloud 跳 Python 3.11 找不到」 這種環境議題。我把整套示範直接放在 Google Cloud Shell：

gcloud 預裝好。
gemini CLI 預裝好（最新版 Cloud Shell image 已內建）。
gcloud auth 跟 Cloud Shell 帳號自動連動，省掉 OAuth dance。

進 https://console.cloud.google.com/，先確認專案是你新建的（不要不小心開到公司正式環境），然後右上角點開 Cloud Shell：

# 驗證兩個工具都在
gcloud --version
gemini --version

[!TIP] 如果你想在本機跑也可以，依照 Gemini CLI 官方安裝指南就行，但 workshop 現場我們統一用 Cloud Shell 來避免「每個人環境一個樣」的悲劇。

MCP 是什麼？三句話講完

MCP (Model Context Protocol) 是 Anthropic 提的開放協定，讓 LLM client 跟 外部能力提供者 用統一格式對話。
Gemini CLI 是 MCP client，你可以 gemini mcp add ... 掛任何符合 MCP 規格的 server。
Google 自家現在已經把好幾個 API 包成官方 MCP server，掛上去等於給你的 AI 助手裝上「Google 內部知識庫」。

MCP #1：Google Developer Knowledge

這個 MCP 把 Google 全家桶的官方文件（Cloud / Android / Web / Firebase / Workspace…）變成 Gemini 可呼叫的工具。比 web search 強的地方在於：它返回的是經過官方索引的 chunk，附正確 source URL，不會被陳年 blog 帶偏。

設定步驟

到 Google Cloud Console 啟用 Developer Knowledge API。
到「憑證」建立一支 API Key，並把它限制為只能呼叫 Developer Knowledge API（最小權限原則）。
在 Cloud Shell 跑：

gemini mcp add -t http \
  -H "X-Goog-Api-Key: YOUR_API_KEY" \
  google-developer-knowledge \
  https://developerknowledge.googleapis.com/mcp \
  --scope user

--scope user 表示這個 MCP 對你所有 project 都有效，下次換 repo 不用再裝一次。

驗證

進入 gemini 互動模式，先打：

/mcp list

應該看到 google-developer-knowledge 狀態為 Connected。然後丟一個典型問題：

請幫我查詢 Google Cloud Run 的最新部署限制（Deployment Limits），並列出前三項。

正確行為：

Gemini 會 call 出 google-developer-knowledge tool。
回答內容引用自 cloud.google.com/run/quotas 等官方頁面。
最後附 reference URL。

MCP #2：Google Maps Platform Code Assist

這支 MCP 專門幫你寫 Google Maps 整合用的 code —— 包含 Maps JavaScript API、Places API、Routes API 的最新呼叫姿勢。對「想做地圖功能但又懶得翻三份 doc」的開發者極友善。

gemini mcp add -s user -t http \
  maps-code-assist-mcp \
  https://mapscodeassist.googleapis.com/mcp

驗證

我想在網頁中嵌入一個 Google 地圖，請幫我寫出一段基本的 JavaScript code，
中心點設在台北 101。

期待的行為：

Gemini call maps-code-assist-mcp。
產出的 code 不會用到已被 deprecated 的 new google.maps.Map() 同步 loader，而是會用現在官方推薦的 importLibrary async pattern。
會主動提醒你要去拿 Maps JavaScript API Key 並做 referer 限制。

如果你看到它還在生 2020 年的舊寫法，那就是 MCP 沒掛好 —— 重新 /mcp list 看狀態。

Workshop 2：把 LINE Bot 部署到 Cloud Run

這部分用範例專案 kkdai/bwai2026-sample。它是一隻 LINE Bot 檔案備份小幫手：

使用者把圖片 / 影片 / 音訊 / PDF 丟進 LINE 對話框。
Bot 自動把檔案存到 使用者自己 的 Google Drive，依 YYYY-MM 分資料夾。
支援 /recent_files、/search_files <keyword>、/disconnect_drive 等指令。

技術棧：Go + LINE Messaging API SDK + Google Drive API + Firestore（存 OAuth token）+ Cloud Run。

git clone https://github.com/kkdai/bwai2026-sample
cd bwai2026-sample

部署流程總覽

[階段一] 拿 LINE 金鑰（Channel Secret + Access Token）
      ↓
[階段二] GCP 專案設定（啟用 Run / Build / Firestore / Artifact / Drive API）
      ↓
[階段三] 設定 OAuth Consent Screen + Gemini CLI 登入
      ↓
[階段四] 對 Gemini CLI 講一句中文，部署到 Cloud Run
      ↓
[階段五] 回 LINE Developers Console 填 Webhook URL

階段一：LINE 金鑰

到 LINE Official Account Manager 建立官方帳號。
到後台「設定 → Messaging API」啟用 Messaging API，建立 Provider。
回 LINE Developers Console 對應的 Channel：
- Basic settings → 拿 Channel Secret。
- Messaging API → 點 Issue 拿 Channel Access Token (long-lived)。
超重要：回 OA Manager 把「自動回應訊息」停用，否則你的 code 永遠搶不到要回的訊息。

階段二：GCP 專案開通

# 切到 workshop 用的乾淨專案
gcloud config set project your-cool-project-id

# 一口氣啟用整套服務
gcloud services enable \
  run.googleapis.com \
  cloudbuild.googleapis.com \
  firestore.googleapis.com \
  artifactregistry.googleapis.com \
  drive.googleapis.com

# 建 Firestore（拿來存 per-user OAuth token + state 防偽造）
gcloud firestore databases create \
  --location=asia-east1 \
  --type=firestore-native

[!NOTE] --type=firestore-native 這個值在第三個踩坑會講為什麼很容易寫錯。

因為 Bot 要代表「使用者本人」上傳檔案到他的 Google Drive，這條路一定要走 OAuth。

進 OAuth 同意畫面：
- User Type：External。
- 應用程式名稱：My LINE Bot（或你想叫的名字）。
- 支援電子郵件 / 開發者聯絡信箱：填你自己的 Gmail。
填完後 務必點「發布應用程式」 —— 不發布的話只有在 Test Users 名單裡的帳號能用。
建立 OAuth 客戶端 ID：
- 類型選 網頁應用程式 (Web Application)。
- 已授權的重新導向 URI：暫時填 https://placeholder/oauth/callback，等階段四拿到 Cloud Run URL 再回來改。
- 存下 Client ID 與 Client Secret。
本機跑：
```
gcloud auth application-default login
```
這會把 ADC（Application Default Credentials）寫到本機，Gemini CLI 跑 gcloud 時就會用這份憑證，不會半路彈出瀏覽器要你 re-auth。

階段四：用 Gemini CLI 部署到 Cloud Run（重頭戲）

工作坊現場最讓參與者「哇」一聲的就是這段。

進入專案目錄後，啟動 Gemini CLI 互動模式：

gemini

然後就講一句話：

幫我使用 gcloud 部署到 Cloud Run，如果需要任何資料請停下來問我。
參考 repo https://github.com/kkdai/bwai2026-sample，
region 用 asia-east1，環境變數會用到
ChannelSecret、ChannelAccessToken、GOOGLE_CLIENT_ID、
GOOGLE_CLIENT_SECRET、GOOGLE_REDIRECT_URL。

Gemini CLI 接下來會：

自己 ls 跟 cat Dockerfile 確認專案結構。
生出 plan：先用 PENDING 佔位部署 → 拿到 URL → 補 OAuth redirect → 更新 env vars。
執行前停下來問你確認（這是 CLI 的 confirm 模式，預設打開，不會自己 yolo）。
跑出大概長這樣的指令：

gcloud run deploy linebot-backup-service \
  --source . \
  --region asia-east1 \
  --set-env-vars "GOOGLE_CLOUD_PROJECT=your-cool-project-id,\
ChannelSecret=YOUR_LINE_SECRET_XXXX,\
ChannelAccessToken=YOUR_LINE_TOKEN_XXXX,\
GOOGLE_CLIENT_ID=PENDING,\
GOOGLE_CLIENT_SECRET=PENDING,\
GOOGLE_REDIRECT_URL=PENDING" \
  --allow-unauthenticated \
  --quiet

3 ～ 5 分鐘後拿到 Service URL，例如 https://linebot-backup-service-xxxxx.a.run.app。

補上真實的 OAuth 設定

回 Console 把剛才填的 https://placeholder/oauth/callback 改成 https://linebot-backup-service-xxxxx.a.run.app/oauth/callback。
把真實 Client ID / Secret 貼給 Gemini CLI，請它幫你 update：

gcloud run services update linebot-backup-service \
  --region asia-east1 \
  --update-env-vars \
"GOOGLE_REDIRECT_URL=https://linebot-backup-service-xxxxx.a.run.app/oauth/callback,\
GOOGLE_CLIENT_ID=real-client-id.apps.googleusercontent.com,\
GOOGLE_CLIENT_SECRET=real-secret-xxxx"

階段五：把 LINE Webhook 對到 Cloud Run

回 LINE Developers Console → Messaging API tab。
Webhook URL：填 https://linebot-backup-service-xxxxx.a.run.app/callback。
按 Verify，期待看到 Success。
Use webhook 切到開啟。
最後回 OA Manager 再確認「自動回應訊息」是關的、「Webhook」是開的。

打開 LINE 把 Bot 加好友，丟一張圖、跑一次 OAuth、看 Drive 裡多了一個 LINE Bot Uploads/2026-05/... 的資料夾 —— 整套流程就跑通了。

常用維運指令

功能	指令
重新部署	`gcloud run deploy linebot-backup-service --source . --region asia-east1`
改環境變數	`gcloud run services update linebot-backup-service --update-env-vars "KEY=VALUE"`
即時 log	`gcloud beta run services logs tail linebot-backup-service`
查服務狀態	`gcloud run services describe linebot-backup-service --region asia-east1`

整個維運其實也可以丟給 Gemini CLI：「幫我看一下 linebot-backup-service 最近 5 分鐘的 log，找出 5xx」就行。

工作坊現場踩坑紀錄

踩坑一：Billing 沒開，第一次 deploy 就紅字

第一次 gcloud run deploy 直接噴：

FAILED_PRECONDITION: Billing account for project [your-cool-project-id] is not found.
Please ensure that you have linked an active billing account.

原因：工作坊參與者多半開新專案來做，新專案預設沒有綁定 Billing。Cloud Run、Cloud Build、Artifact Registry 都需要計費才能跑 —— 即使是免費額度內，也要有「綁過卡的 billing account」掛在 project 上。

解法：

# 看 project 現在的 billing 狀態
gcloud beta billing projects describe your-cool-project-id

# 列出有哪些可用的 billing account
gcloud beta billing accounts list

# 綁定
gcloud beta billing projects link your-cool-project-id \
  --billing-account=0X0X0X-0X0X0X-0X0X0X

不能或不想綁卡的話，現場我們改用「已有 billing 的 sandbox project」當示範。

踩坑二：Firestore type 參數名稱

教材初版（連 AI 第一次猜的也是）寫 --type=native 或 --type=native-mode：

ERROR: argument --type: Invalid choice: 'native-mode'.
  Valid choices: ['firestore-native', 'datastore-mode']

原因：gcloud firestore databases create 在 2024 年某次更新後，把 type 參數值改成更明確的 firestore-native / datastore-mode。舊文件、舊回答（包括 LLM 訓練語料）會給你舊值。

解法：

gcloud firestore databases create \
  --location=asia-east1 \
  --type=firestore-native

這個雷剛好示範了為什麼要裝 Google Developer Knowledge MCP —— 掛上它之後 Gemini 會去查官方最新文件，不會丟給你過時的 type 值。

踩坑三：忘記啟用 Drive API，OAuth 過了卻寫不進去

部署完、Webhook 對好、走完 OAuth 同意畫面拿到 token，結果第一張圖上傳就 500。看 log：

googleapi: Error 403: Google Drive API has not been used in project
your-cool-project-id before or it is disabled.

原因：階段二的 gcloud services enable ... 那串裡如果漏掉 drive.googleapis.com，OAuth 是可以過的（因為 Consent Screen 跟 Drive API 是兩件事），但你的 server 拿著 access token 去打 drive.googleapis.com 時會被擋。

解法（最快）：

gcloud services enable drive.googleapis.com

解法（根本）：把所有要用到的 API 一次都 enable，列在教材的 checklist 裡，現場跟著跑就不會漏。階段二那串指令我特別把 drive.googleapis.com 寫進去，就是為了堵這個雷。

[!TIP] 一個 debug 的好習慣：只要 server 拿著正確 token 卻被 403，先去 API Library 確認對應 API 是 enabled，再去看 OAuth scope，最後才是看 IAM。順序錯會浪費很多時間。

為什麼這套組合值得學？

工作坊跑完，我問現場參與者最有感的是哪個 moment，得到的回答幾乎一致：「對著 Gemini CLI 講中文就把服務部署上去」那一刻。

那為什麼會有感？拆開來看：

以前 DevOps 卡的是 記得哪個指令，現在卡的是 表達清楚你想做什麼。後者門檻低很多，新人三天上手 vs. 三個月才敢碰 gcloud。
MCP 把官方知識前置注入 Gemini。你不再需要先自己 RTFM、再翻譯成 prompt 給 LLM；MCP 等於讓 LLM 自己有 RTFM 的能力。
錯誤訊息回到工具自己面前。以前報錯要 Google + StackOverflow，現在直接貼回 CLI，它讀完錯誤再決定下一步 —— 形成完整的 plan-act-observe 迴圈。
整套工作流 reproducible。教材、範例、prompt 都在 GitHub repo 裡，任何人 clone 下來照著做，結果應該一致。

想再深入？建議的進階閱讀

官方教材：kkdai/BwAI-2026
範例專案：kkdai/bwai2026-sample
投影片：SpeakerDeck
Gemini CLI：github.com/google/gemini-cli
MCP 規格：modelcontextprotocol.io
延伸：用 Gemini CLI + Developer Knowledge MCP、Map MCP Grounding

後記：來 LINE 一起做東西吧

這次工作坊也是我們 LINE Taiwan DevRel 招募的場合之一。如果你看完這篇覺得：

想長期玩 LINE Messaging API + Google Cloud + Gemini 的整合。
喜歡邊寫 production code 邊把流程做成可被別人複製的教材。
每週能投入三天以上，且有意願在實習結束後轉正。

歡迎私訊我或寄信來聊聊，我們有一週三天的彈性實習方案，做得好就有轉正成為長期夥伴的機會。

最後感謝所有來現場一起 hands-on 的開發者 —— 願意把週末花在「用新工具打通整條 pipeline」的人，永遠是社群最值得敬佩的那一群。下一場見！

[Gemini實戰][RAG] Gemini API File Search 多模態大升級全解析：Embedding 2、Metadata 過濾、頁級引用，附 LINE Bot 開源實作

Sun, 10 May 2026 00:00:00 +0000

(圖片來源: Google Blog - Gemini API File Search is now multimodal: build efficient, verifiable RAG)

前情提要：RAG 終於不用自己拼樂高了

過去這幾年只要做 RAG（Retrieval-Augmented Generation），開發者腦袋裡浮現的元件清單大概都長這樣：

一個 chunker（langchain？自己寫？）
一個 embedding model（OpenAI text-embedding-3？Cohere？BGE？）
一個向量資料庫（ChromaDB、FAISS、pgvector、Pinecone…挑哪個都要打架）
一個檢索 + rerank 的流程
然後才是 LLM

更別說多模態 RAG 還要再多一層：圖片怎麼 embed？要不要先 OCR？要不要切兩個 store 文字一個圖片一個？文圖混搜怎麼算分？光是這幾題就能耗掉一個 sprint。

這幾天 Google 在開發者部落格丟出 Expanded Gemini API File Search for multimodal RAG，把上面這條冗長的 pipeline 變成「呼叫一個 managed API」的事，而且圖片是原生支援的。

本文會做兩件事：

把新功能拆開講清楚，包含背後的 Gemini Embedding 2 在做什麼。
用一隻已開源的 LINE Bot（kkdai/linebot-multimodal-rag）當作活生生的示範，看新功能怎麼在實際 production code 裡組合起來 — 順便把我除錯時撞到的兩個典型坑分享給大家避雷。

新功能三大重點

依照官方部落格，這次升級的核心就三件事：

1. 真．多模態檔案搜尋（Native Multimodal File Search）

過去的 File Search 是純文字檢索，圖片只能靠 OCR 變成文字才能進 store。

“File Search now processes images and text together. Powered by the Gemini Embedding 2 model, the tool understands native image data.”

現在你可以直接把圖片丟進 File Search Store，跟文字一起被索引。背後的引擎是 Gemini Embedding 2 —— 文字、圖片、影片、音訊、文件共用同一個向量空間，所以你可以「拿圖找文字」、「拿文字找圖」、或者「拿圖找圖」，不用自己對齊空間。

對我們做產品的人來說，這代表：

文圖混搜不再是研究題目，是一個 API call。
不用維護兩個 store（一個給文字 chunks、一個給 CLIP-style image embeddings）。
科學圖表、UI screenshot、報表、相簿…這些以前 OCR 之後損失大半語意的東西，現在能保留原始視覺資訊去檢索。

2. Custom Metadata 與 Server-side 過濾

每一份你丟進 store 的檔案，現在都可以掛上 key-value 標籤：

{"key": "user_id", "string_value": "U1234abcd..."}
{"key": "department", "string_value": "Legal"}
{"key": "status", "string_value": "Final"}

查詢時用 google.aip.dev/160 filter 語法（跟 GCP 大部分 list API 一樣的格式）：

metadata_filter='department="Legal" AND status="Final"'

過濾是在 Google 那邊先做 的，不是先撈一堆再丟掉。少了 noise 之後，速度跟精準度都會上升，這對 multi-tenant SaaS 來說根本是救命符 —— 一個 store 配 metadata filter 就能切租戶，不用為了隔離開 N 個 store。

我的 LINE Bot 就直接靠這個做 per-user 資料隔離：每筆檔案上傳時掛上 LINE 的 user_id，查詢時 filter 一帶，使用者 A 永遠不可能在問答中看到使用者 B 的資料。

3. 頁級引用（Page-level Citations）

回應裡的每個被引用片段，現在會帶頁碼。

“captures the page number for every piece of indexed information.”

對企業客戶來說這超關鍵。”AI 跟我說合約第 X 頁有提到 Y” vs. “AI 跟我說合約有提到 Y” —— 前者可以直接被法務 / 稽核接受，後者還要花人力翻書驗證。頁碼解開了「LLM 答案無法溯源」的最後一哩。

多模態的引擎：Gemini Embedding 2

新功能的核心是這顆 Gemini Embedding 2 模型。把它的規格 quote 出來方便你做選型決策：

項目	規格
支援輸入	文字、圖片、影片、音訊、文件（同一個 embedding space）
Input token 上限	8,192 tokens
Output 維度	128 ～ 3,072（用 Matryoshka Representation Learning，小維度也能保有相近精度）
多語支援	100+ 語言

幾個關鍵 benchmark（recall@1）：

Text-to-Image Search：TextCaps 89.6 / Docci 93.4
Image-to-Text Search：TextCaps 97.4
Multilingual (MTEB)：mean 69.9
Video-Text Matching：Vatex ndcg@10 68.8
Speech-Text Retrieval：MSEB mrr@10 73.9

幾個重點觀察：

Matryoshka 不是 buzzword：你可以先用 3072 維存進去，跑檢索時切到 768 維跑得快還能維持品質。儲存 / 算分成本可以分階段優化。
跨模態分數高得很真實：97.4% recall@1（image→text）代表如果你有一張圖、要找對應的描述文字，幾乎一次就找對。這對「拿手機拍個產品標籤，找對應使用手冊頁面」這類使用情境直接就能落地。
100+ 語言：對台灣 / 日韓 / 東南亞市場是很現實的差異點。

開發者真正會在意的事：價格與接入成本

從 Multimodal RAG with the Gemini API File Search tool: a developer guide 這篇官方教學文裡，有兩段是真的對成本敏感的開發者該畫起來：

“Fully managed, with no vector database overhead.”

“Storage and query-time embeddings are free. You only pay for indexing and tokens.”

翻成白話：

不用付向量資料庫的錢，也不用付運維它的人月。
儲存免費、查詢時的 embedding 計算也免費。
你只有兩筆要付：初次 indexing 時的 embedding 費用、以及生成回答時消耗的 LLM tokens。

對個人 side project 跟早期 startup 都是友善的成本曲線 —— 你不需要在第一天就決定「我能不能負擔向量 DB 的 baseline」。

標準工作流程：4 個 SDK call 接完一條 RAG

整理 dev.to guide 後的最小可行流程：

from google import genai
from google.genai import types

client = genai.Client()

# 1. 建立 store（指定多模態 embedding model）
store = client.file_search_stores.create(config={
    "display_name": "my-multimodal-rag",
    "embedding_model": "models/gemini-embedding-2",
})

# 2. 上傳檔案 + 自訂 metadata
operation = client.file_search_stores.upload_to_file_search_store(
    file_search_store_name=store.name,
    file="report-q1.pdf",
    config={
        "display_name": "Q1 Report",
        "custom_metadata": [
            {"key": "department", "string_value": "Finance"},
            {"key": "year", "string_value": "2026"},
        ],
    },
)
# 上傳是 long-running operation，要 poll：
# operation = client.operations.get(operation)

# 3. 把 file_search 當 tool 餵給 generate_content
response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="去年第一季的營收成長率是多少？",
    config=types.GenerateContentConfig(
        tools=[types.Tool(file_search=types.FileSearch(
            file_search_store_names=[store.name],
            metadata_filter='department="Finance" AND year="2026"',
        ))],
    ),
)

# 4. 取引用（含頁碼）
for citation in response.candidates[0].grounding_metadata.grounding_chunks:
    print(citation.web.uri, citation.web.title)  # 或對應的 file/page 欄位

要附上引用圖片給使用者，還有 client.file_search_stores.download_media() 可以呼叫。

不誇張，整套多模態 RAG 不到 30 行 code。

演示案例：把這些新功能塞進一隻 LINE Bot

光看 SDK 範例很抽象，所以我把它做成一隻可以上工的 LINE Bot，開源在 kkdai/linebot-multimodal-rag：

使用者在 LINE 對話框丟 PDF / 圖片 / 文字檔 → Bot 進 File Search Store 索引。
使用者打字問 → Gemini 從這位使用者自己上傳的資料裡找答案。
使用者丟一張圖問 → 一樣可以做圖找文字的檢索。
部署目標：GCP Cloud Run + Cloud Build 自動部署。

架構非常直觀（重點欄位）：

元件	角色
LINE Webhook	FastAPI 接收訊息事件
GCS	持久化原檔（`uploads/{user_id}/{message_id}.{ext}`）
Gemini File Search Store	唯一的索引層（managed）
Custom metadata `user_id`	多租戶隔離
FastAPI BackgroundTasks	避開 LINE reply token 30 秒上限

對照前面講的三大新功能：

多模態：使用者丟圖、丟 PDF，都進同一個 store，搜尋時都吃同一條 pipeline。
Custom metadata：每個 LINE user 的檔案都掛 user_id 標籤，查詢時 filter，做到 server-side 強制隔離。
Page-level citations：未來要在 LINE 訊息裡顯示「答案出自 XX.pdf 第 5 頁」，直接消費 grounding_metadata。

整個 repo 大概不到 600 行 Python，就把一個「自己的私人多模態知識庫聊天 Bot」做完了。

部署實戰：commit → 自動上線

開源範例光跑得起來不夠，要在工作坊現場示範就得是「改 code 推 GitHub 就自動部署」的水準。這次我請 Claude Code 當副駕駛幫我把 CI/CD 接起來。

我只丟了一句：

「幫我建立 Cloud Build 連接 GitHub，commit 到 main 後就 trigger build 部署到 Cloud Run。」

Claude Code 自己先掃 cloudbuild.yaml、現有 Cloud Run 設定、Secret Manager、Artifact Registry，列了一份「目前的問題」，然後停下來問我關鍵決策：要保留現有 service 名稱還是改 yaml？GitHub 要不要授權？等我回答完，它一口氣把缺的資源建起來：

# 建 Artifact Registry repo
gcloud artifacts repositories create linebot \
  --repository-format=docker --location=asia-east1

# 機密搬家：從現役 service 抽到 Secret Manager（透過 stdin，不留 shell history）
gcloud run services describe linebot-gemini-file-search --region=asia-east1 \
  --format='value(...)' \
  | gcloud secrets create LINE_CHANNEL_SECRET --data-file=-

# 給 Cloud Build / Compute SA 部署需要的角色
for role in run.admin iam.serviceAccountUser artifactregistry.writer \
            secretmanager.secretAccessor storage.objectAdmin logging.logWriter; do
  gcloud projects add-iam-policy-binding your-cool-project-id \
    --member="serviceAccount:660825558664-compute@developer.gserviceaccount.com" \
    --role="roles/$role" --condition=None
done

# 建 trigger
gcloud builds triggers create github \
  --name=linebot-multimodal-rag-main \
  --repo-owner=kkdai --repo-name=linebot-multimodal-rag \
  --branch-pattern="^main$" --build-config=cloudbuild.yaml

唯一不能自動化的是 GitHub OAuth 授權 —— Claude Code 直接坦白告訴我「這步只能去 Console 點」，附上 URL 跟逐步指引。一分鐘點完回來，trigger 就跑通了。

踩坑紀錄：兩個跟新功能直接相關的雷

踩坑一：寫死的 Model ID 過時

cloudbuild.yaml 跟 code 預設值都寫了 gemini-3.1-flash，但翻了一下 Gemini API 目前的 model id 清單：根本沒這個 model。Gemini 3 Flash 正確的 ID 是 gemini-3-flash-preview。

為什麼會發生：multimodal RAG 是一個非常新的功能，相關文件、教學、範例都還在大量誕生中，命名也微調過。Repo 初版很容易寫到一個「看起來像但其實不存在」的 id。

解法：全 repo 改成 gemini-3-flash-preview，順便確認 embedding model 是 models/gemini-embedding-2（對的，沒踩到雷）。Push 之後 Cloud Build 自動 trigger、三分鐘新 revision 上線。

踩坑二：神祕的「Upload has already been terminated」

這個雷直接踩在 File Search Store 新支援的「圖片上傳」這條 path 上 —— 也是最值得分享的一個，因為它示範了「新 API 的錯誤訊息有時候很委婉」。

我從 LINE 傳了一張 JPG 給 Bot 點「存入資料庫」，結果：

❌ 存入失敗：400 Bad Request. {'message': 'Upload has already been terminated.', 'status': 'Bad Request'}

完全看不出原因。Cloud Logging 也只有同一行錯誤，沒有 stack trace。上 Google AI Developers Forum 翻一輪，發現好幾種 file type（.md / .xlsx / 大 CSV）都有人遇過類似回報。

真正的元兇藏在這段看起來無辜的程式碼：

# app/gemini_service.py（修改前）
suffix = mimetypes.guess_extension(mime_type) or ".bin"
with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
    tmp.write(file_bytes)
    tmp_path = tmp.name

在 Python 3.13 之前，mimetypes.guess_extension("image/jpeg") 回傳的是 .jpe，不是 .jpg。原因是標準函式庫的 MIME 表裡 .jpe 字典序排在 .jpg 前面，這個怪癖存在了將近二十年。

Gemini File Search Store 看到副檔名 .jpe 不認得，但 API 回的訊息又用「Upload has already been terminated」這種非常容易誤導人的講法 —— 一開始我還以為是上傳大小超過、或被併發掐住、或是 SDK 內部有 race。

修法：副檔名直接從 display_name 取（handlers 已經正確設成 image_<id>.jpg），備援用一張顯式 MIME 對照表：

# app/gemini_service.py（修改後）
_MIME_TO_EXT = {
    "image/jpeg": ".jpg",
    "image/png": ".png",
    "image/webp": ".webp",
    "application/pdf": ".pdf",
    # ...
}

if "." in display_name:
    suffix = "." + display_name.rsplit(".", 1)[-1].lower()
else:
    suffix = _MIME_TO_EXT.get(mime_type) or mimetypes.guess_extension(mime_type) or ".bin"

print(f"[BG Store] uploading display_name={display_name!r} mime={mime_type} "
      f"size={len(file_bytes)} tmp_suffix={suffix}")

順手把 except 那邊也補上 traceback.format_exc()，這樣下次出事 Cloud Logging 就會有完整堆疊。

這個故事的 takeaway：當你在用「新 GA 沒多久的 API」上跑新 modality 時，請務必：

在客戶端先確認你產生的檔名 / 副檔名是 API 預期的格式，不要相信 mimetypes 標準庫幫你猜的。
把 stack trace 寫進 log，不然 forum 上那種「換一個檔案就好了」的玄學討論你救不了自己。
從 Gemini File Search 官方支援格式清單對照你產生的副檔名一致。

總結：multimodal RAG 的入場費，史上最低

這次的 Gemini API File Search 升級，把一條過去要做 3 個月才能上線的功能線壓縮成「幾十行 code + 一個 managed API」就能跑：

多模態天生支援：文字、圖片、影片、音訊、文件共享同一個 embedding 空間，再見 OCR 過渡層。
Custom metadata + server-side filter：multi-tenant SaaS 不用糾結 store 切多少個了。
Page-level citations：企業合規場景終於有原生 grounding。
管錢友善：storage / query embedding 都不用錢，只付 indexing + LLM tokens。
Embedding 2 的跨模態分數：97.4% recall@1 不是 demo 數字，是直接能撐住產品的等級。

如果你想直接看一個 production-shaped 的端到端範例：kkdai/linebot-multimodal-rag 整個 repo PR welcome，也歡迎拿去改成你自己領域的 RAG 應用 —— Notion 知識庫、員工手冊問答機、相簿管家、研究論文索引…大概只有想像力會限制你。

想開始的話，建議的閱讀順序：

Google 官方部落格：Expanded Gemini API File Search for multimodal RAG
Gemini Embedding 2 規格頁：deepmind.google/models/gemini/embedding
開發者實作指南：Multimodal RAG with the Gemini API File Search tool: a developer guide
我的開源範例：github.com/kkdai/linebot-multimodal-rag

歡迎大家一起來試試看這個很強大的 Multimodal RAG 的支援吧！

[GCP 實戰][BwAI] AI 賦能開發：使用 Gemini CLI 快速部署 LINE Bot 雲端備份神器

Sat, 02 May 2026 00:00:00 +0000

前情提要

在即將到來的 Build With AI 2026 的工作坊中，我們帶來了一個非常實用的專案：LINE Bot 檔案備份機器人。它可以讓你把 LINE 聊天室裡的圖片、檔案直接丟上 Google Drive，還會按月份自動幫你建資料夾整理得服服貼貼。

傳統上，要把這樣一個包含 OAuth 授權、Firestore 資料庫、Cloud Run 容器部署的專案放上雲端，新手往往會對著落落長的 gcloud 指令發愁。

但這次不一樣，我們有秘密武器：Gemini CLI。

這篇文章將紀錄我們如何把 AI 當作 DevOps 工程師，透過「講話」的方式完成整個複雜的部署流程，當然，也包含了過程中踩到的各種真實坑洞。

準備工作：召喚 AI 助手

在開始之前，除了基本的 gcloud 安裝與登入，你只需要安裝 Gemini CLI。

準備好以下「機密參數」（本文皆已 Mock 處理）：

PROJECT_ID: your-cool-project-id
LINE Channel Secret: YOUR_LINE_SECRET_XXXX
LINE Access Token: YOUR_LINE_TOKEN_XXXX

進入專案資料夾後，我只對 Gemini CLI 說了一句話：

「幫我使用 gcloud 部署到 Cloud Run，如果需要任何資料，請停下來問我。參考 repo…」

接下來，就是見證奇蹟（與修 bug）的時刻。

實戰部署流程：AI 帶路

Gemini CLI 非常聰明地分析了 Dockerfile 與 main.go，馬上列出了一套作戰計畫。

第一步：環境檢測與 API 啟用

AI 首先幫我確認了 gcloud 當前的專案設定，並一鼓作氣啟用了必要的服務：

gcloud services enable firestore.googleapis.com \
  cloudbuild.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com

第二步：建立 Firestore 資料庫 (遇到第一個坑)

我們的 Bot 需要記錄 OAuth 的 State 防偽造標記，所以需要 Firestore。 AI 嘗試執行了指令，但我們馬上遇到錯誤。(詳見後文踩坑紀錄)

修正後，正確的指令是：

gcloud firestore databases create --location=asia-east1 --type=firestore-native

第三步：先上車後補票的 Cloud Run 部署

這是一個經典的「雞生蛋、蛋生雞」問題：Google OAuth 需要知道你的 Cloud Run 網址 (Redirect URI)，但你的 Cloud Run 部署又需要填寫 OAuth 的 Client ID 和 Secret。

Gemini CLI 的策略很棒：先用佔位符部署！

gcloud run deploy linebot-backup-service \
  --source . \
  --region asia-east1 \
  --set-env-vars "GOOGLE_CLOUD_PROJECT=your-cool-project-id,ChannelSecret=YOUR_LINE_SECRET_XXXX,ChannelAccessToken=YOUR_LINE_TOKEN_XXXX,GOOGLE_CLIENT_ID=PENDING,GOOGLE_CLIENT_SECRET=PENDING,GOOGLE_REDIRECT_URL=PENDING" \
  --allow-unauthenticated \
  --quiet

部署成功後，我們拿到了一串香噴噴的網址：https://linebot-backup-service-xxxxx.a.run.app。

第四步：完成 Google OAuth 設定與環境變數更新

有了網址，我就可以去 Google Cloud Console 的「API 與服務」完成設定：

建立 OAuth 同意畫面。
建立 網頁應用程式 的憑證。
把剛剛的網址加上 /oauth/callback 填入「已授權的重新導向 URI」。

拿到真實的 ID 與 Secret 後，我直接把資訊貼給 Gemini CLI，它便自動幫我更新了服務：

gcloud run services update linebot-backup-service \
  --region asia-east1 \
  --update-env-vars "GOOGLE_REDIRECT_URL=https://[YOUR_URL]/oauth/callback,GOOGLE_CLIENT_ID=real-client-id.apps.googleusercontent.com,GOOGLE_CLIENT_SECRET=real-secret-xxxx"

大功告成！最後只要去 LINE Developers Console 把 Webhook 填上就好。

部署過程中的血淚踩坑紀錄

看起來行雲流水，但其實中間 AI 和我一起撞了幾個牆。這也是使用 CLI 工具最真實的體驗。

踩坑一：忘記綁定信用卡的 390001 錯誤

在執行第一次 gcloud run deploy 時，終端機直接噴了滿臉紅字：

FAILED_PRECONDITION: Billing account for project is not found...

原因：Cloud Run 和 Cloud Build 需要專案啟用計費功能（Billing Enabled）。這是一個全新的測試專案，我忘記綁定帳單了。解法：AI 立刻幫我檢查了專案狀態 (gcloud beta billing projects describe)，並詢問我是要切換到有計費的專案，還是去修復它。我乖乖去 Console 綁定信用卡後，部署才得以繼續。

踩坑二：指令參數的語法演進

在建立 Firestore 時，AI 一開始給的指令是 --type=native-mode 或 --type=native，結果 gcloud 不領情：

ERROR: argument --type: Invalid choice: 'native-mode'

原因：gcloud 的 CLI 參數會隨著版本更迭。解法：仔細看 gcloud 的錯誤提示，現在正確的參數值是 firestore-native 或 datastore-mode。修改為 --type=firestore-native 後順利通關。

踩坑三：那個隱形的「Drive API」

當一切部署完畢，我們在測試「上傳到 Google Drive」時，卻發生了權限錯誤。原因：這是一個幫你把檔案傳到 Drive 的 Bot，但我們在第一步啟用 API 時，竟然忘記啟用主角：Google Drive API！沒有它，就算 OAuth 授權成功，程式一樣會被擋在門外。解法：我只對終端機輸入了神祕的 "3." (暗示第三個檢查點)，AI 立刻心領神會，補上了這關鍵的一擊：

gcloud services enable drive.googleapis.com

總結

透過 Gemini CLI，原本枯燥且容易出錯的基礎設施建置工作，變成了一場「雙人結隊程式設計」。

AI 可以幫你記住冗長的 gcloud 參數、幫你梳理部署邏輯（先用 PENDING 部署再更新），甚至在你遇到報錯時，能根據錯誤訊息快速調整策略。

這就是 Build With AI 2026 想傳達的核心精神：讓 AI 處理繁瑣的 DevOps 雜活，開發者就能把更多精力放在核心業務邏輯的創新上。

如果你還在手敲又長又臭的 gcloud 指令，強烈建議你把 Gemini CLI 裝起來試試看！

[GCP 實戰] 打造持久化 AI 助手：在 GCE 部署 Hermes Agent 並接軌 Telegram

Fri, 01 May 2026 00:00:00 +0000

前情提要

在解決了 LINE Bot 的 Vertex AI 遷移後，我開始思考：能不能有一個「更具主動性」且「擁有長期記憶」的 AI 助手？這時候我盯上了 NousResearch 開源的 Hermes Agent 。

不同於一般的 Chatbot，Hermes 被設計成一個「會呼吸的操作系統」，它能自己執行 Shell 指令、寫 Python 腳本、管理長期記憶，甚至能透過不同的 Gateway (Telegram, Discord) 隨時與你保持聯繫。

為了讓它能 24/7 待命，我選擇將它部署在 Google Compute Engine (GCE) 上。這篇文章將紀錄從零開始的部署過程，以及我在配置最新的 Gemini 2.5 Flash 模型時踩過的那些坑。

環境參數預備

在開始之前，請確保你手手上這這些必要的參數：

PROJECT_ID: YOUR_PROJECT_ID
LOCATION: global
GOOGLE_API_KEY: YOUR_GOOGLE_API_KEY (Google AI Studio 取得)

第一步：建立 GCE 實例

Hermes Agent 需要一點運算能力來處理工具調用（Tool Use），建議使用 e2-medium 規格。

gcloud compute instances create hermes-agent-vm \
    --project=YOUR_PROJECT_ID \
    --zone=us-central1-a \
    --machine-type=e2-medium \
    --image-family=ubuntu-2204-lts \
    --image-project=ubuntu-os-cloud \
    --boot-disk-size=30GB \
    --metadata=startup-script='#!/bin/bash
        apt-get update
        apt-get install -y git curl python3-pip python3-venv nodejs npm
    '

第二步：安裝 Hermes Agent

SSH 進入 VM 後，直接使用官方提供的一鍵安裝腳本。

進入 VM：

gcloud compute ssh hermes-agent-vm --zone=us-central1-a

執行安裝：

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc

第三步：配置 Gemini 2.5 Flash (SOP 實戰)

這是整場演習最容易踩坑的地方。Hermes 預設可能會指向不存在或過期的模型標識符。

建立配置文件：在 ~/.hermes/config.yaml 中，我們必須精確指定 Gemini 2.5 Flash，且 不可帶 google/ 前綴。

model:
  provider: gemini
  default: "gemini-2.5-flash"
terminal:
  backend: local
gateway:
  provider: telegram
auxiliary:
  # ⚠️ 非常重要：Hermes 內部會硬編碼輔助模型，必須手動覆寫
  title_generation: { provider: gemini, model: "gemini-2.5-flash" }
  summarization: { provider: gemini, model: "gemini-2.5-flash" }

設定 API Key：在 ~/.hermes/.env 中寫入密鑰與權限設定：

echo "GOOGLE_API_KEY=你的_API_KEY" >> ~/.hermes/.env
echo "GATEWAY_ALLOW_ALL_USERS=true" >> ~/.hermes/.env

第四步：接軌 Telegram 與背景持久化

為了不讓 SSH 斷線後 Agent 就消失，我們使用 Systemd 來管理。

建立 Systemd 服務 (/etc/systemd/system/hermes.service)：

[Unit]
Description=Hermes Agent Gateway
After=network.target
    
[Service]
Type=simple
User=root
Environment=HOME=/root
Environment=PYTHONUNBUFFERED=1
ExecStart=/usr/local/lib/hermes-agent/venv/bin/hermes gateway run
Restart=always
RestartSec=10
    
[Install]
WantedBy=multi-user.target

啟動服務：

sudo systemctl daemon-reload
sudo systemctl enable hermes
sudo systemctl restart hermes

遷移過程中的血淚踩坑：為什麼我的 Agent 沒反應？

即使配置正確，我還是遇到了「Agent 讀取訊息但死不回覆」的窘境。查了日誌 (journalctl -u hermes) 才發現幾個深坑：

踩坑一：Gemini 3.0 的 404 幽靈

我在配置時試圖追求最新，用了 gemini-3-flash-preview。結果日誌噴出一堆 404 Model Not Found。原因：Hermes 內部的 auxiliary_client.py 硬編碼了許多 gemini-3-flash-preview 作為預設值。當這些輔助功能（如生成標題）報錯時，會連帶影響整個 Gateway 的回覆邏輯。解法：手動在 config.yaml 中顯式定義所有 auxiliary 模型為 gemini-2.5-flash，或者直接用 sed 去補丁源代碼。

踩坑二：模型標識符的前綴混淆

在不同的 SDK 中，有人用 google/gemini-2.5-flash，有人用 gemini-2.5-flash。經驗：在 Hermes 的 Gemini Provider 中，直接使用短名稱 gemini-2.5-flash 是最保險的。加了 google/ 反而會讓 API 路由出錯。

踩坑三：Systemd 與「已經運行的進程」衝突

當你手動跑過 hermes gateway 後再啟動服務，系統會報 Gateway already running (PID xxxx)。解法：在 Systemd 的 ExecStart 之前，可以加一條 ExecStartPre=/usr/bin/pkill -9 -f hermes || true，確保每次啟動都是乾淨的環境。

總結

現在，我的專屬 Hermes Agent 已經穩定的跑在 GCE 上，並且透過 Telegram 隨時待命。它不僅能幫我查資料，還能直接在雲端 VM 上幫我跑一些簡單的運算腳本。

這次部署讓我學到：面對更新極快的模型，官方文檔（或 MCP 工具查詢）才是唯一的真理。不要盲目追求最新版本號，確保標識符與當前 API 環境匹配才是穩定運行的關鍵。

如果你也想要一個 24 小時不睡覺的 AI 數位替身，趕快照著這份 SOP 弄一台吧！

[GCP 實戰] OpenAB 部署筆記：在 GCE 上打造支援 Telegram 的 Gemini ACP 橋接器

Thu, 30 Apr 2026 00:00:00 +0000

前情提要

最近為了讓 AI 編碼助理（如 Claude Code 或 Gemini CLI）能直接在聊天平台上使用，我開始研究 OpenAB **。這是一個強大的橋接器，能將 Slack、Discord 或 Telegram 對接到符合 **ACP (Agent Client Protocol) 標準的 CLI 工具。

這篇文章紀錄了我將 OpenAB 部署在 Google Cloud 上的完整實戰過程，特別是如何繞過認證限制、處理 Telegram 的 HTTPS 需求，以及解決容器化部署中的路徑與權限問題。

OpenAB 參考文件： https://openabdev.github.io/openab/
OpenAB Repo: https://github.com/openabdev/openab

部署決策：為什麼選 GCE 而不是 Cloud Run？

雖然 Cloud Run 是我的首選，但在處理 OpenAB 時，Google Compute Engine (GCE) 才是最佳解決方案。原因有二：

Stateful Session (狀態化對話)：OpenAB 會為每個對話 thread 啟動一個子進程（如 Gemini CLI）。這些進程必須長期駐留以維持對話上下文。Cloud Run 的自動縮減機制會殺死這些進程，導致對話中斷。
認證持久化：AI CLI 的 Token 需要儲存在本地磁碟。GCE 配合 Persistent Disk 能保證重啟後登入狀態不消失。

實戰步驟：Step-by-Step 部署過程

第一步：撰寫自動化啟動腳本 (Startup Script)

為了讓部署標準化，我們撰寫了一個 setup-openab.sh。其核心任務是安裝 Docker、建立持久化目錄，並動態生成 config.toml。

最關鍵的部分是 自定義 Docker Image。由於 OpenAB 官方鏡像不一定包含所有 AI 工具，我們透過 Dockerfile 現場安裝 Node.js 與 @google/gemini-cli：

FROM ghcr.io/openabdev/openab:latest
USER root
RUN apt-get update && apt-get install -y curl && \
    curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
    apt-get install -y nodejs && \
    npm install -g @google/gemini-cli
USER 1000

第二步：使用 gcloud 建立 GCE 實例

我們選擇 e2-medium 規格，並透過 Metadata 傳遞敏感資訊（如 Bot Token），避免寫死在腳本中。

gcloud compute instances create openab-server \
    --project=your-project-id \
    --zone=asia-east1-b \
    --machine-type=e2-medium \
    --image-family=debian-11 \
    --image-project=debian-cloud \
    --metadata-from-file startup-script=setup-openab.sh \
    --metadata=tg_bot_token=YOUR_BOT_TOKEN

第三步：配置 Gemini API Key

不同於 Kiro 需要互動式登入，gemini-cli 可以直接讀取環境變數。我們將 API Key 注入到 OpenAB 的 config.toml 中，讓它在背景自動運作：

[agent]
command = "gemini"
args = ["--acp"]
env = { GEMINI_API_KEY = "AIzaSy..." }

第四步：使用 Cloudflare Tunnel 解決 HTTPS 需求

Telegram Webhook 強制要求 HTTPS。與其設定複雜的 Nginx + SSL，我選擇使用 Cloudflare Quick Tunnel：

在 VM 執行：cloudflared tunnel --url http://localhost:8080。
取得隨機生成的 HTTPS 網址。
註冊 Webhook：curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=<CF_URL>/webhook/telegram&secret_token=<SECRET>"。

遷移過程中的血淚踩坑：技術總結

在部署過程中，我們來回除錯了幾次，以下是總結出的三大「坑」：

踩坑一：鏡像來源的混淆

一開始我嘗試從 Docker Hub Pull openabdev/openab 但一直失敗。最後才發現該專案目前的穩定鏡像是放在 GitHub Container Registry (GHCR)。

解法：必須使用 ghcr.io/openabdev/openab:latest。

踩坑二：硬編碼的配置路徑

OpenAB 的 Dockerfile 內部預期設定檔路徑在 /etc/openab/config.toml。我最初掛載到 /app/config.toml 導致容器啟動後立即閃退報錯。

解法：修正 Docker Volume 掛載路徑為 /etc/openab/config.toml。

踩坑三：Security Secret Token 驗證失敗

即便 URL 正確，Telegram 訊息仍被 Gateway 拒絕。日誌顯示 invalid or missing secret_token。

原因：openab-gateway 為了防止非法請求，會生成一個內部校驗碼。
解法：必須從 Gateway 容器中提取該 Token，並在 setWebhook 時作為 secret_token 參數傳遞。

總結：完美的 AI 橋接方案

透過這套架構，我成功在 GCP 上建立了一個完全自託管、安全且高效率的 AI 助理。它不依賴昂貴的訂閱，而是直接利用 Gemini 的 API 能力，並透過 Telegram 作為互動介面。

如果你也想在雲端架設一個專屬的 ACP 橋接器，這套 GCE + Docker + Cloudflare Tunnel 的組合方案將是最平衡穩定選擇。

[GCP 實戰] LINE Bot 遷移大作戰：從 AI Studio 轉向 Vertex AI 解決 429 額度危機

Mon, 20 Apr 2026 00:00:00 +0000

前情提要

最近我們部署在 Google Cloud Run 上的 LINE 名片助理機器人 (linebot-namecard-python) 突然罷工了。透過 gcloud logging read 查了一下日誌，迎面而來的是這個無情的錯誤：

google.api_core.exceptions.ResourceExhausted: 429 Your billing account has exceeded its monthly spending cap.

這是一個慘痛的教訓：我們當初為了快速開發，直接使用了 Google AI Studio 提供的 API Key（走 google.generativeai 套件）。隨著流量增加，我們很快就撞上了 Google AI Studio Tier 1 的 429 限制（Rate Limit / Quota 爆炸），結果默默把每月的免費額度給打爆了。

為了徹底解決這個問題，我們決定將所有依賴 AI Studio Gemini API Key 的應用程式，全面轉換成 Google Cloud Vertex AI，直接走 GCP 的企業級架構與計費系統。

這篇文章就來分享這次遷移的完整過程，以及途中發現「Vertex AI 的資訊實在太少，導致模型設定常常踩坑」的各種血淚經驗。

身份驗證升級：推薦使用 Workload Identity

在遷移的過程中，最重要的一環就是身分驗證。過去我們習慣在環境變數塞一個 GEMINI_API_KEY，簡單粗暴但充滿資安隱患。

來到 GCP 的世界，很多人第一直覺是去開一個 Service Account（服務帳戶），然後把 JSON 金鑰載下來放進程式裡。但強烈建議不要走 Service Account 金鑰這條路！

搭配 gcloud cli，其實可以很快速地為 Cloud Run 設定 Workload Identity。程式碼中不需要任何金鑰，只要在執行環境中賦予該 Identity 對應的 Vertex AI User 權限，Google Cloud SDK 就會自動取得憑證。這樣不僅大幅降低金鑰外洩的風險，管理起來也更輕鬆。

程式碼升級：從 AI Studio 轉向 Vertex AI

要將專案從 Google AI Studio SDK 遷移到 Vertex AI，主要有三個步驟：

替換依賴套件：在 requirements.txt 中，移除舊的 google.generativeai，換成 google-cloud-aiplatform。
更新環境變數設定：在 config.py 中，我們不再需要 API Key，而是改用 GCP 的 PROJECT_ID 和 LOCATION：
```
PROJECT_ID = os.getenv("PROJECT_ID", None)
LOCATION = os.getenv("LOCATION", "global") # 預設使用 global
```

核心程式碼改寫 (gemini_utils.py)： Vertex AI 的 SDK 介面雖然類似，但對於多模態（如圖片）的處理稍微嚴格一點。我們需要將 PIL.Image 轉換成 vertexai.generative_models.Part 格式：

import vertexai
from vertexai.generative_models import GenerativeModel, Part
from io import BytesIO
import PIL.Image
   
# 初始化 Vertex AI
vertexai.init(project=PROJECT_ID, location=LOCATION)
   
def pil_to_bytes(img: PIL.Image.Image) -> bytes:
    img_byte_arr = BytesIO()
    img.save(img_byte_arr, format='JPEG')
    return img_byte_arr.getvalue()
   
def generate_json_from_image(img: PIL.Image.Image, prompt: str) -> object:
    model = GenerativeModel(
        "gemini-3-flash-preview",
        generation_config={"response_mime_type": "application/json"},
    )
    # ⚠️ 注意這裡：必須轉換成 Part 物件
    img_part = Part.from_data(data=pil_to_bytes(img), mime_type="image/jpeg")
    response = model.generate_content([prompt, img_part], stream=False)
    return response

遷移過程中的血淚踩坑：模型都很笨？還是 Vertex AI 資訊太少？

在遷移的過程中，有一種強烈的感覺：「模型好像都很笨（我是說在座的所有 models），還是其實是 Vertex AI 官方給的資訊太少了？」

許多在 AI Studio 上理所當然的設定，搬到 Vertex AI 後卻頻頻報錯。以下整理了幾個最容易踩到、讓人來來回回除錯的深坑：

踩坑一：殘留的舊 SDK 導致 Cloud Run 啟動失敗

滿心歡喜地用 gcloud run services update 更新了環境變數，結果 Cloud Run 部署失敗，容器連啟動都啟動不了。

查了日誌才發現：

ModuleNotFoundError: No module named 'google.generativeai'

原因：雖然 gemini_utils.py 已經改寫好了，但主程式 app/main.py 裡面還殘留著 import google.generativeai as genai 以及 genai.configure(...) 的初始化程式碼。既然 requirements.txt 已經移除了這個套件，容器啟動時自然會找不到模組而崩潰。

解法：全面 grep 專案，徹底移除所有舊版 SDK 的引用，然後使用 Cloud Build 重新打包 Docker image 再次推送。

踩坑二：Region 必須選 global 才有最多跟最新模型

程式碼清乾淨、容器也順利啟動了，但當我在 LINE 傳送圖片時，機器人卻拋出了 500 錯誤。日誌顯示：

google.api_core.exceptions.NotFound: 404 Publisher Model ... was not found or your project does not have access to it.

這是我這次遇到最大的坑！很多人（包含我）直覺上會把 Vertex AI 的 Region 設定跟 Project 或 Cloud Run 的 Region 綁在一起（例如設定為 asia-east1 台灣區）。

但在 Vertex AI 的世界裡，Region 很容易跟 Project Region 搞混。如果你想要使用最新、最完整的模型（例如 gemini-3-flash-preview），你必須將 Vertex AI 的 LOCATION 設定為 global。如果硬是設定成 asia-east1 或 us-central1，常常會遇到 404 找不到模型的窘境。

踩坑三：Model 名稱選錯，造成來來回回錯誤

在 Google AI Studio，你可以很隨意地用 gemini-1.5-flash 這個 alias 甚至省略後綴。但在 Vertex AI，模型名稱的規定非常嚴格且混亂。

如果你名稱選錯（例如少加了 -002，或是預覽版名稱拼錯），API 不是直接報錯，就是默默地 Fallback 跑到舊版的 1.5 模型去執行，導致你覺得「這模型怎麼變笨了？」，結果查了半天才發現根本叫錯了模型。

最終解法與建議：

將 config.py 的預設 region 改為 global。
呼叫 vertexai.init(project="line-vertex", location="global")。
確保使用的模型名稱與 GCP 官方文件完全一致，例如直接指定 gemini-3-flash-preview。

總結：Vertex AI 帶來的改變

經過一番折騰，名片機器人終於滿血復活，並且順利升級到最新的 Gemini 3 Flash Preview 模型。從 AI Studio 遷移到 Vertex AI 後，帶來了幾個顯著的好處：

擺脫 Quota 焦慮：徹底解決 AI Studio Tier 1 的 429 爆炸問題，直接透過 GCP 帳單扣款，適合生產環境。
安全性大躍進：捨棄了明文 API Key 與 Service Account 金鑰，擁抱 Workload Identity，架構更安全現代化。
穩定性：享受企業級的 SLA 保障。

雖然一開始覺得 Vertex AI 資訊太少、模型名稱與 Region 設定讓人頭痛，但只要掌握了 global region 以及 Workload Identity 這兩個訣竅，後續的維護其實是非常香的。

完整程式碼已更新至 GitHub，如果你也有專案正準備從 AI Studio 搬家到 Vertex AI，希望這篇踩坑紀錄能幫你少走一點彎路！

[Gemini 3.1] Gemini-3.1-flash TTS 實戰：更簡單、更強大的朗讀摘要功能

Wed, 15 Apr 2026 00:00:00 +0000

前情提要

在上一篇實戰中，我們利用 Gemini 3.1 Flash Live 實現了語音辨識，並透過 Gemini 2.5 Live API 的「側擊」方式勉強達成了朗讀摘要（TTS）功能。

但就在 2026 年 4 月，Google 正式發佈了 Gemini 3.1 Flash TTS。這是一個專門為語音輸出設計的原生模型，不再需要掛載 Live WebSocket，直接透過標準的 generate_content 流程就能輸出高品質音訊。

身為開發者，有更優雅、更原生的方案當然要立刻跟上。這篇文章就來分享如何把 LINE Bot 的朗讀摘要功能升級到 Gemini 3.1 Native TTS，以及過程中踩到的「異步大坑」。

技術升級：從 Live API 轉向 Native TTS

之前的朗讀功能是利用 Gemini 2.5 Live API 模擬出來的，雖然可用，但有幾個缺點：

複雜度高：需要管理 WebSocket 連線生命週期。
模型限制：必須使用特定的 native-audio 模型，且主要支援在 us-central1。
回傳格式固定：採樣率通常固定在 16kHz。

Gemini 3.1 Flash TTS 的出現改變了這一切：

模型名稱：gemini-3.1-flash-tts-preview。
介面一致：使用熟悉的 generate_content_stream。
動態參數：支援從回傳的 MIME type 自動偵測採樣率（通常提升到了 24kHz，音質更好）。

核心程式碼進化（tools/tts_tool.py）

新的實作變得更加簡潔，重點在於 response_modalities=["audio"] 這個設定：

async def text_to_speech(text: str) -> tuple[bytes, int]:
    client = genai.Client(api_key=GOOGLE_AI_API_KEY, http_options={"api_version": "v1beta"})

    contents = [
        types.Content(
            role="user",
            parts=[
                # 加入在地化指令，讓語氣更自然
                types.Part.from_text(text=f"請使用台灣用語的繁體中文，以親切且自然的語氣朗讀以下摘要內容。## Transcript:\n{text}"),
            ],
        ),
    ]

    config = types.GenerateContentConfig(
        response_modalities=["audio"],
        speech_config=types.SpeechConfig(
            voice_config=types.VoiceConfig(
                prebuilt_voice_config=types.PrebuiltVoiceConfig(voice_name="Zephyr")
            )
        ),
    )

    pcm_chunks = []
    sample_rate = 24000 # 預設值

    try:
        # ⚠️ 這裡就是那個差點讓我修到天亮的大坑
        response_stream = await client.aio.models.generate_content_stream(
            model="gemini-3.1-flash-tts-preview",
            contents=contents,
            config=config,
        )
        async for chunk in response_stream:
            if chunk.parts:
                for part in chunk.parts:
                    if part.inline_data:
                        pcm_chunks.append(part.inline_data.data)
                        # 從 MIME type 動態取得採樣率（例如 audio/L16;rate=24000）
                        if part.inline_data.mime_type:
                            sample_rate = parse_rate(part.inline_data.mime_type)
    except Exception as e:
        logger.error(f"TTS Error: {e}")
        raise

    pcm_bytes = b"".join(pcm_chunks)
    duration_ms = int(len(pcm_bytes) / (sample_rate * 2) * 1000)
    
    # 後續同樣透過 ffmpeg 轉成 m4a 傳給 LINE...

踩過的坑：那個消失的 `await`

這次升級遇到一個非常隱晦的 TypeError，在遠端部署後一直噴出：

TypeError: 'async for' requires an object with __aiter__ method, got coroutine

❌ 錯誤寫法

當初照著範例寫，直覺地以為可以直接 async for 一個 method：

# 這是錯的！
async for chunk in client.aio.models.generate_content_stream(...):
    pass

✅ 正確解法

在 Google GenAI Python SDK 的非同步版本中，generate_content_stream 本身是一個 async 函式，它會回傳一個 iterator。所以你必須先 await 拿到那個 iterator，然後再對它進行 async for。

# 正確做法：分兩步
response_stream = await client.aio.models.generate_content_stream(...)
async for chunk in response_stream:
    pass

這個細節在一般的同步程式碼或某些舊版 SDK 中不一定存在，但在處理 3.1 Flash TTS 的非同步串流時，這是能否成功跑起來的關鍵。

在地化調整：讓 Bot 說「台灣話」

雖然摘要本身已經是繁體中文，但 TTS 模型在朗讀時，有時會帶有非本土的腔調或用語。我們透過 Prompt Engineering 解決了這個問題：

「請使用台灣用語的繁體中文，以親切且自然的語氣朗讀…」

加入這行指令後，Gemini 輸出的音訊在語調起伏和斷句上更接近台灣使用者的習慣，大大提升了「朗讀摘要」的親和力。

總結：Native TTS 帶來的改變

從 Live API 遷移到 Native TTS 之後：

連線更穩定：不再需要維持一個長時間的 WebSocket。
音質提升：原生支援 24kHz 採樣率。
維護容易：程式碼量減少了約 30%，邏輯更直接。

這次經驗也提醒了我，即使是看似成熟的 SDK，在處理 async 模式時仍要仔細檢查回傳值類型。

如果你也想讓你的 LINE Bot 開口說話，Gemini 3.1 Flash TTS 絕對是目前的最佳選擇。

完整程式碼已更新至 GitHub，我們下次見！

[Gemini 3.1] Flash Live 語音辨識實戰：讓 LINE Bot 聽懂你說的話

Sat, 28 Mar 2026 00:00:00 +0000

前情提要

Google 在 2026 年 3 月底發佈了 Gemini 3.1 Flash Live，主打「讓音訊 AI 更自然、更可靠」。這個模型專門針對即時雙向語音對話設計，低延遲、可中斷、支援多語言。

剛好手邊有一個 LINE Bot 專案（linebot-helper-python）——它已經能處理文字、圖片、URL、PDF、YouTube，唯獨語音訊息完全不理：

用戶傳送語音訊息
Bot：（沉默）

這次就把語音支援補進去，順便分享幾個踩過的坑。

設計決策：Flash Live 還是標準 Gemini API？

第一個問題：Gemini 3.1 Flash Live 是為即時串流設計的，但 LINE 的語音訊息是預錄好的 m4a 檔案，不是即時音訊流。

用 Flash Live 處理預錄檔案，就像用直播攝影機拍照——技術上可行，但工具選錯了。

決定用標準 Gemini API——直接把音訊 bytes 當 inline data 傳進去，一次呼叫拿到轉錄文字。更簡單、更適合這個場景。

架構設計

整合思路

這個 repo 已經有完整的 Orchestrator 架構，會依照訊息內容自動路由到不同 Agent（Chat、Content、Location、Vision、GitHub）。語音訊息的目標很明確：

把語音轉成文字，然後當成一般文字訊息丟進 Orchestrator——讓現有的所有功能自動支援語音輸入。

使用者說「幫我搜尋附近的加油站」→ 轉錄成文字 → Orchestrator 判斷是地點查詢 → LocationAgent 處理。不需要為語音另外實作邏輯。

完整流程

用戶傳送 AudioMessage（m4a）
    │
    ▼ handle_audio_message()
    │
    ├─ ① LINE SDK 下載音訊 bytes
    │       get_message_content(message_id) → iter_content()
    │
    ├─ ② Gemini 轉錄
    │       tools/audio_tool.py → transcribe_audio()
    │       model: gemini-3.1-flash-lite-preview
    │
    ├─ ③ Reply #1：「你說的是：{transcription}」
    │       reply_message()（消耗 reply token）
    │
    └─ ④ Reply #2：Orchestrator 路由
            handle_text_message_via_orchestrator(push_user_id=user_id)
            ↓
            push_message()（reply token 已用掉，改用 push）

為什麼要兩段回覆？

回覆分成兩則，讓使用者立刻看到轉錄結果，不用等 Orchestrator 處理完才知道 Bot 有沒有聽懂自己說什麼。

核心程式碼詳解

Step 1：音訊轉錄工具（tools/audio_tool.py）

from google import genai
from google.genai import types

TRANSCRIPTION_MODEL = "gemini-3.1-flash-lite-preview"

async def transcribe_audio(audio_bytes: bytes, mime_type: str = "audio/mp4") -> str:
    """
    Transcribe audio bytes to text using Gemini.
    LINE 語音訊息固定是 m4a，MIME type 固定填 audio/mp4。
    """
    client = genai.Client(
        vertexai=True,
        project=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"),
    )

    audio_part = types.Part.from_bytes(data=audio_bytes, mime_type=mime_type)

    response = await client.aio.models.generate_content(
        model=TRANSCRIPTION_MODEL,
        contents=[
            types.Content(
                role="user",
                parts=[
                    audio_part,
                    types.Part(text="請將以上語音內容完整轉錄成文字，保留原語言，不要加任何說明或前綴。"),
                ],
            )
        ],
    )

    return response.text or ""

設計原則：函式本身不 catch exception，讓上層 handler 統一處理錯誤回覆。

Step 2：handler 主流程（main.py）

async def handle_audio_message(event: MessageEvent):
    """Handle audio (voice) messages — transcribe and route through Orchestrator."""
    user_id = event.source.user_id
    replied = False  # 追蹤 reply token 是否已使用
    try:
        # 下載音訊
        message_content = await line_bot_api.get_message_content(event.message.id)
        audio_bytes = b""
        async for chunk in message_content.iter_content():
            audio_bytes += chunk

        # 轉錄
        transcription = await transcribe_audio(audio_bytes)

        # 空轉錄（無聲或太短）
        if not transcription.strip():
            await line_bot_api.reply_message(
                event.reply_token,
                [TextSendMessage(text="無法辨識語音內容，請重新錄製。")]
            )
            return

        # Reply #1：讓使用者確認轉錄結果（消耗 reply token）
        await line_bot_api.reply_message(
            event.reply_token,
            [TextSendMessage(text=f"你說的是：{transcription.strip()}")]
        )
        replied = True

        # Reply #2：送進 Orchestrator，用 push_message（token 已用掉）
        await handle_text_message_via_orchestrator(
            event, user_id,
            text=transcription.strip(),
            push_user_id=user_id,
        )

    except Exception as e:
        logger.error(f"Error handling audio for {user_id}: {e}", exc_info=True)
        error_text = LineService.format_error_message(e, "處理語音訊息")
        error_msg = TextSendMessage(text=error_text)
        if replied:
            # reply token 已消耗，改用 push
            await line_bot_api.push_message(user_id, [error_msg])
        else:
            await line_bot_api.reply_message(event.reply_token, [error_msg])

Step 3：讓 Orchestrator 支援外部傳入文字

原本的 handle_text_message_via_orchestrator 直接讀 event.message.text，AudioMessage 沒有 .text，所以加兩個 optional 參數：

async def handle_text_message_via_orchestrator(
    event: MessageEvent,
    user_id: str,
    text: str = None,           # ← 外部傳入文字（語音轉錄）
    push_user_id: str = None,   # ← 設定時改用 push_message
):
    msg = text if text is not None else event.message.text.strip()
    try:
        result = await orchestrator.process_text(user_id=user_id, message=msg)
        response_text = format_orchestrator_response(result)
        reply_msg = TextSendMessage(text=response_text)

        if push_user_id:
            await line_bot_api.push_message(push_user_id, [reply_msg])
        else:
            await line_bot_api.reply_message(event.reply_token, [reply_msg])
    except Exception as e:
        error_msg = TextSendMessage(text=LineService.format_error_message(e, "處理您的問題"))
        if push_user_id:
            await line_bot_api.push_message(push_user_id, [error_msg])
        else:
            await line_bot_api.reply_message(event.reply_token, [error_msg])

text is not None（而非 text or ...）是刻意的——萬一語音轉錄出空字串，要讓空字串通過（然後被上層的 if not transcription.strip() 攔掉），不是 fallback 到 event.message.text。

踩過的坑

❌ 坑 1：`Part.from_text()` 不接受 positional argument

最先遇到的 TypeError：

# ❌ 錯誤（TypeError: Part.from_text() takes 1 positional argument but 2 were given）
types.Part.from_text(
    "請將以上語音內容完整轉錄成文字，保留原語言，不要加任何說明或前綴。"
)

# ✅ 正確
types.Part(text="請將以上語音內容完整轉錄成文字，保留原語言，不要加任何說明或前綴。")

在這個版本的 SDK 中，Part.from_text() 的 text 是 keyword argument，或者直接用 Part(text=...) 建構子更保險。

❌ 坑 2：LINE reply token 只能用一次

LINE 的 reply token 是一次性的。一旦呼叫 reply_message()，token 就失效了。

這個專案的語音流程會呼叫兩次：

Reply #1（顯示轉錄文字）→ 消耗 token
Reply #2（Orchestrator 結果）→ token 已失效，會收到 LINE 400 error

解法是讓 Orchestrator handler 支援 push_message 模式（透過 push_user_id 參數），Reply #2 改走 push_message。

錯誤處理也要注意：如果 Reply #1 成功後 Orchestrator 才拋例外，except block 裡也不能再用 reply_message，同樣要改成 push_message。這就是程式碼裡 replied flag 的用途。

❌ 坑 3：Gemini Flash Live 不適合預錄檔案

不是真正的「坑」，但值得說清楚：

Gemini 3.1 Flash Live 是為即時雙向串流設計，有連線建立和串流協定的開銷。LINE 語音訊息是完整的預錄 m4a，一次性處理即可。

直接用 client.aio.models.generate_content() 傳 inline audio bytes，更簡單，延遲也不差。Flash Live 留給真正需要即時對話的場景。

效果展示

場景 1：語音指令查詢

用戶傳送：[語音] 幫我搜尋台北車站附近的咖啡廳

Bot Reply #1：你說的是：幫我搜尋台北車站附近的咖啡廳
Bot Reply #2：[LocationAgent 回覆附近咖啡廳清單]

場景 2：語音問問題

用戶傳送：[語音] Gemini 和 GPT-4 有什麼差別

Bot Reply #1：你說的是：Gemini 和 GPT-4 有什麼差別
Bot Reply #2：[ChatAgent 搭配 Google Search Grounding 回覆比較結果]

場景 3：語音發 URL

用戶傳送：[語音] 幫我摘要這篇文章 https://example.com/article

Bot Reply #1：你說的是：幫我摘要這篇文章 https://example.com/article
Bot Reply #2：[ContentAgent 抓取並摘要文章]

語音轉錄出來的文字直接進 Orchestrator，現有的 URL 偵測、意圖判斷全部照常運作，零額外邏輯。

傳統文字輸入 vs 語音輸入

	文字輸入	語音輸入
輸入格式	TextMessage	AudioMessage（m4a）
前處理	無	Gemini 轉錄
reply token	直接用	Reply #1 消耗，Reply #2 改 push
Orchestrator	直接路由	轉錄文字後路由
支援功能	全部	全部（無需額外設定）
錯誤處理	reply_message	replied flag 判斷 reply/push

分析與展望

這次整合最讓我滿意的是幾乎不用改 Orchestrator 本身。只要在輸入端把語音轉成文字，後面所有的路由邏輯、Agent 呼叫、錯誤處理全都自動繼承。

Gemini 的多模態音訊理解在這個場景裡表現很穩——繁體中文、台語腔調、夾雜英文的句子基本上都能準確轉錄。

未來可以延伸的方向：

多語言自動偵測：轉錄時告訴 Gemini 保留原語言，日文語音→日文轉錄，再由 Orchestrator 決定要不要翻譯
群組語音支援：目前只限 1:1，群組的語音訊息暫時忽略
長錄音摘要：超過一定長度的錄音直接走 ContentAgent 做摘要，而非當指令處理

延伸：🔊 朗讀摘要——讓 Bot 說話

語音辨識讓 Bot「聽懂」使用者說的話。這件事做完之後，自然就有了下一個問題：

Bot 能不能說話回應？

Gemini Live API 有一個 response_modalities: ["AUDIO"] 的設定，可以直接輸出音訊 PCM 串流。我把它接上了另一個場景——朗讀摘要。

功能設計

每次 Bot 摘要完一個 URL、YouTube 或 PDF，訊息底下都會出現「🔊 朗讀」的 QuickReply 按鈕。使用者按下去，Bot 把摘要文字送進 Gemini Live TTS，把 PCM 音訊轉成 m4a，然後用 AudioSendMessage 傳回去。

URL 摘要完成
    │
    ▼ [🔊 朗讀] QuickReply 按鈕
    │
用戶按下按鈕 → PostbackEvent
    │
    ▼ handle_read_aloud_postback()
    │
    ├─ ① 從 summary_store 取出摘要文字（10 分鐘 TTL）
    │
    ├─ ② Gemini Live API → PCM 音訊
    │       model: gemini-live-2.5-flash-native-audio
    │       response_modalities: ["AUDIO"]
    │
    ├─ ③ ffmpeg 轉檔：PCM → m4a
    │       s16le, 16kHz, mono → AAC
    │
    └─ ④ AudioSendMessage 傳給使用者
            original_content_url: /audio/{uuid}
            duration: {ms}

核心程式碼（tools/tts_tool.py）

LIVE_MODEL = "gemini-live-2.5-flash-native-audio"

async def text_to_speech(text: str) -> tuple[bytes, int]:
    client = genai.Client(vertexai=True, project=VERTEX_PROJECT, location="us-central1")
    config = {"response_modalities": ["AUDIO"]}

    async with client.aio.live.connect(model=LIVE_MODEL, config=config) as session:
        await session.send_client_content(
            turns=types.Content(role="user", parts=[types.Part(text=text)]),
            turn_complete=True,
        )
        pcm_chunks = []
        async for message in session.receive():
            if message.server_content and message.server_content.model_turn:
                for part in message.server_content.model_turn.parts:
                    if part.inline_data and part.inline_data.data:
                        pcm_chunks.append(part.inline_data.data)
            if message.server_content and message.server_content.turn_complete:
                break

    pcm_bytes = b"".join(pcm_chunks)
    duration_ms = int(len(pcm_bytes) / 32000 * 1000)  # 16kHz × 16-bit mono

    # PCM → m4a（temp file 模式，避免 moov atom 問題）
    with tempfile.NamedTemporaryFile(suffix=".pcm", delete=False) as f:
        f.write(pcm_bytes)
        pcm_path = f.name
    m4a_path = pcm_path.replace(".pcm", ".m4a")
    subprocess.run(
        ["ffmpeg", "-y", "-f", "s16le", "-ar", "16000", "-ac", "1",
         "-i", pcm_path, "-c:a", "aac", m4a_path],
        check=True, capture_output=True,
    )
    with open(m4a_path, "rb") as f:
        return f.read(), duration_ms

朗讀功能踩的坑

❌ 坑 4：模型名稱完全不同

Gemini Live TTS 的第一個嘗試是：

LIVE_MODEL = "gemini-3.1-flash-live-preview"

照著語音辨識用的 gemini-3.1-flash-lite-preview 推導的，結果直接 1008 policy violation：

Publisher Model `projects/line-vertex/locations/global/publishers/google/
models/gemini-3.1-flash-live-preview` was not found

列出 Vertex AI 可用模型才發現，Live/native audio 的模型命名規則完全不同：

# ✅ 正確
LIVE_MODEL = "gemini-live-2.5-flash-native-audio"

Gemini 3.1 在 Vertex AI 上沒有 Live 版本。Live/native audio 功能目前是 2.5 世代，命名格式是 gemini-live-{version}-{variant}-native-audio，跟一般模型的 gemini-{version}-flash-{variant} 完全是兩套邏輯。

❌ 坑 5：`GOOGLE_CLOUD_LOCATION=global` 讓 Live API 失聯

換了正確的模型名稱之後，錯誤訊息還是一樣：

Publisher Model `projects/line-vertex/locations/global/...` was not found

這次 model 名稱正確了，但 locations/global 很奇怪——我們明明設定了 us-central1。

追查 Google GenAI SDK 的原始碼發現：

# _api_client.py
self.location = location or env_location
if not self.location and not self.api_key:
    self.location = 'global'  # ← 這裡

location or env_location——如果傳進去的 location 是空字串，就會 fallback 到 global。

問題根源是 Cloud Run 的環境變數：

{ "name": "GOOGLE_CLOUD_LOCATION", "value": "global" }

GOOGLE_CLOUD_LOCATION 被設成了 "global" 字串。os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1") 拿到的不是 "us-central1"，而是 "global"——然後 SDK 乖乖連到 global endpoint，但 gemini-live-2.5-flash-native-audio 在 global 沒有 BidiGenerateContent 支援。

Endpoint	標準 API	Live API
`global`	✅ 可用	❌ 模型不在這裡
`us-central1`	✅ 可用	✅ `gemini-live-2.5-flash-native-audio`

解法：Live API 的 location 直接硬寫，不從 env var 讀：

# ❌ 受 GOOGLE_CLOUD_LOCATION=global 影響
VERTEX_LOCATION = os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1")

# ✅ 硬寫，不受 env var 干擾
VERTEX_LOCATION = "us-central1"  # Live API 需要 regional endpoint

語音辨識 vs 朗讀摘要

兩個功能用了完全不同的 Gemini API：

	語音辨識	朗讀摘要
方向	音訊 → 文字	文字 → 音訊
API	標準 `generate_content`	Live API `BidiGenerateContent`
模型	`gemini-3.1-flash-lite-preview`	`gemini-live-2.5-flash-native-audio`
Location	跟著 env var	硬寫 `us-central1`
輸出格式	text	PCM → ffmpeg → m4a
LINE 訊息類型	輸入：`AudioMessage`	輸出：`AudioSendMessage`

總結

Gemini 3.1 Flash Live 的發布讓音訊 AI 更值得認真對待。這次把語音辨識和朗讀摘要都接進了 LINE Bot：

語音辨識：標準 Gemini API，預錄 m4a 一次轉錄，接進現有 Orchestrator
朗讀摘要：Gemini Live TTS，摘要文字轉 PCM，ffmpeg 轉 m4a，AudioSendMessage 傳回

最麻煩的不是功能本身，而是找到正確的模型名稱和定位 SDK 的 location 邏輯——這兩個都沒有在文件顯眼的地方寫清楚，只能靠列出可用模型、讀 SDK 原始碼才找到答案。

完整程式碼在 GitHub，歡迎參考。

我們下次見！

[Gemini] Tool Combo 實戰：在單次 API 呼叫中結合 Maps Grounding 與 Places API 打造 LINE 聚會地點小幫手

Thu, 26 Mar 2026 00:00:00 +0000

參考文章：

Gemini API tooling updates: context circulation, tool combos and Maps grounding for Gemini 3
Google Places API (New) - searchNearby
GitHub: linebot-spot-finder
完整程式碼 GitHub (聚會小幫手 LINE Bot Spot Finder)

前情提要

LINE Bot + Gemini 的組合已經很常見，不管是用 Google Search Grounding 讓模型查即時資訊，還是用 Function Calling 讓模型呼叫自訂邏輯，單獨使用都很成熟。

但如果你想在同一個問題裡同時做到「地圖定位情境」和「查詢真實評分」呢？

以餐廳搜尋來說，傳統做法通常長這樣：

用戶: "幫我找附近評價4星以上的熱炒店"

方案 A（只用 Maps Grounding）：
Gemini 有地圖情境，但評分資訊是 AI 自行描述，不保證準確。

方案 B（只用 Places API）：
可以拿到真實評分，但沒有地圖情境，Gemini 不知道用戶在哪裡。

要兩者兼得，通常需要分兩次 API 呼叫，或是自己手動串接。

AI 能查地圖、也能呼叫外部 API，但要在一次呼叫裡同時做到這兩件事——在 Gemini API 的舊架構下一直是個尷尬的空白。

直到 2026 年 3 月 17 日，Google 發布了 Gemini API Tooling Updates（作者：Mariano Cocirio），這個問題才有了官方解法。

什麼是 Tool Combinations？

Google 在這次更新中宣布了三個核心功能：

1. Tool Combinations（工具組合） 開發者現在可以在單次 Gemini API 呼叫中同時掛上 built-in 工具（如 Google Search、Google Maps）以及自訂 Function Declarations。模型自行決定要呼叫哪個工具、何時呼叫，最後整合結果生成回答。

2. Maps Grounding Gemini 現在可以直接感知地圖資料，不再只是文字描述「位置」，而是真正具備空間情境——知道用戶在哪裡、附近有什麼。

3. Context Circulation 讓多輪工具呼叫之間的情境能自然流通，模型在第二次呼叫時能完整記憶第一次的工具呼叫結果。

這次改動的關鍵在於：

# 舊的做法（兩個工具不能並存）
types.Tool(google_search=types.GoogleSearch())
types.Tool(function_declarations=[MY_FN])

# 新的做法（同一個 Tool 物件，兩者共存）
types.Tool(
    google_maps=types.GoogleMaps(),
    function_declarations=[MY_FN],
)

一行改動，打開了全新的組合方式。

專案目標

這次我用 Tool Combinations 改造了既有的 linebot-spot-finder，讓它從「只能 Maps Grounding 粗略回答」升級到「Google Maps 情境 + Places API 真實資料」：

用戶傳送 GPS 位置後輸入：「請找評價 4 顆星以上、適合多人聚餐的熱炒店，列出名稱、地址和評論摘要。」

Bot（舊版 Maps Grounding）：「附近有幾間熱炒店，評價都不錯。」（AI 自行描述，可能不準）

Bot（新版 Tool Combo）：「老王熱炒｜台北市信義區市民大道100號｜評分 4.6（312則）｜評論：份量大、CP值高，適合聚餐；服務效率高，上菜快。」

差別在於：Gemini 現在同時收到地圖情境（你在哪裡）和 Places API 的真實結構化資料（評分數字、評論文字），回答因此從「模糊描述」變成「有根據的資訊」。

架構設計

整體訊息流程

LINE User 傳送 GPS 位置
    │
    ▼
handle_location()  →  session.metadata 儲存 lat/lng
    │
    └──► 回傳 Quick Reply（餐廳 / 加油站 / 停車場）

LINE User 傳送文字問題（e.g. "找評價4星以上的熱炒店"）
    │
    ▼
handle_text()
    │
    ├── session 有 lat/lng？
    │       是 → tool_combo_search(query, lat, lng)   ← 本文重點
    │       否 → fallback: Gemini Chat + Google Search
    │
    └──► 回傳自然語言答覆

Tool Combo Agentic Loop

tool_combo_search(query, lat, lng)
         │
         ▼
  Step 1: generate_content()
  tools = [google_maps + search_nearby_restaurants]
         │
         ▼
  response.candidates[0].content.parts 裡有 function_call？
       ╱                              ╲
      是                               否
      │                                │
      ▼                                ▼
  _execute_function()           直接回傳 response.text
  → _call_places_api()
    （Places API searchNearby）
    回傳評分、地址、評論
      │
      ▼
  收集成單一 Content(role="user")
  加入 history
      │
      ▼
  Step 3: generate_content(contents=history)
  Gemini 整合地圖情境 + Places 資料
      │
      ▼
  回傳 final.text

為什麼 lat/lng 不放在 Function Declaration 裡？

這是設計上一個重要決策。

如果把 lat/lng 加進 SEARCH_NEARBY_RESTAURANTS_FN 的 parameters，Gemini 會自己填入座標——但它填的是從對話推斷的「大概位置」，不是用戶實際 GPS 座標，誤差可能高達數公里。

正確做法是讓 Python dispatcher 從 session.metadata 取出精確座標，注入進去：

def _execute_function(name: str, args: dict, lat: float, lng: float):
    if name == "search_nearby_restaurants":
        return _call_places_api(
            lat=lat, lng=lng,          # ← 從 session 注入，不讓 Gemini 猜
            keyword=args.get("keyword", ""),
            min_rating=float(args.get("min_rating", 4.0)),
        )

核心程式碼詳解

Step 1：定義 Function Declaration

from google.genai import types

SEARCH_NEARBY_RESTAURANTS_FN = types.FunctionDeclaration(
    name="search_nearby_restaurants",
    description=(
        "用 Google Places API 搜尋附近餐廳，回傳評分、地址與用戶評論。"
        "lat/lng 由系統自動帶入，不需要提供。"
    ),
    parameters=types.Schema(
        type=types.Type.OBJECT,
        properties={
            "keyword": types.Schema(
                type=types.Type.STRING,
                description="餐廳類型或關鍵字，例如：熱炒、火鍋、義式",
            ),
            "min_rating": types.Schema(
                type=types.Type.NUMBER,
                description="最低評分門檻（1–5），預設 4.0",
            ),
            "radius_m": types.Schema(
                type=types.Type.INTEGER,
                description="搜尋半徑（公尺），預設 1000",
            ),
        },
    ),
)

description 裡明確告訴模型「lat/lng 由系統帶入」，避免模型在 args 裡自己填座標。

Step 2：Places API 呼叫

import httpx

PLACES_API_URL = "https://places.googleapis.com/v1/places:searchNearby"
PLACES_FIELD_MASK = (
    "places.displayName,"
    "places.rating,"
    "places.userRatingCount,"
    "places.formattedAddress,"
    "places.reviews"
)

def _call_places_api(lat, lng, keyword="", min_rating=4.0, radius_m=1000):
    body = {
        "includedTypes": ["restaurant"],
        "maxResultCount": 5,
        "locationRestriction": {
            "circle": {
                "center": {"latitude": lat, "longitude": lng},
                "radiusMeters": radius_m,
            }
        },
    }

    response = httpx.post(
        PLACES_API_URL,
        headers={
            "X-Goog-Api-Key": os.getenv("GOOGLE_MAPS_API_KEY"),
            "X-Goog-FieldMask": PLACES_FIELD_MASK,
        },
        json=body,
        timeout=10.0,
    )
    response.raise_for_status()
    data = response.json()

    restaurants = []
    for place in data.get("places", []):
        rating = place.get("rating", 0)
        if rating < min_rating:
            continue
        reviews = [
            r["text"]["text"]
            for r in place.get("reviews", [])[:3]
            if r.get("text", {}).get("text")
        ]
        restaurants.append({
            "name": place["displayName"]["text"],
            "address": place.get("formattedAddress", ""),
            "rating": rating,
            "rating_count": place.get("userRatingCount", 0),
            "reviews": reviews,
        })

    return {"restaurants": restaurants}

Step 3：Tool Combo 主函式（Agentic Loop）

async def tool_combo_search(query: str, lat: float, lng: float) -> str:
    client = genai.Client(
        vertexai=True,
        project=os.getenv("GOOGLE_CLOUD_PROJECT"),
        location=os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"),
        http_options=types.HttpOptions(api_version="v1"),
    )

    enriched_query = (
        f"用戶目前位置：緯度 {lat}，經度 {lng}。\n"
        f"請用台灣用語的繁體中文回答，不要使用 markdown 格式。\n\n"
        f"問題：{query}"
    )

    tool_config = types.GenerateContentConfig(
        tools=[
            types.Tool(
                google_maps=types.GoogleMaps(),                      # ← Maps grounding
                function_declarations=[SEARCH_NEARBY_RESTAURANTS_FN], # ← Places API
            )
        ],
    )

    # ── Step 1 ──────────────────────────────────────────────────────
    response = client.models.generate_content(
        model=TOOL_COMBO_MODEL,
        contents=enriched_query,
        config=tool_config,
    )

    if not response.candidates:
        return response.text or "（無法取得回覆）"

    history = [
        types.Content(role="user", parts=[types.Part(text=enriched_query)]),
        response.candidates[0].content,
    ]

    # ── Step 2：處理 function_call ──────────────────────────────────
    function_response_parts = []
    for part in response.candidates[0].content.parts:
        if part.function_call:
            fn = part.function_call
            result = _execute_function(fn.name, dict(fn.args or {}), lat, lng)
            function_response_parts.append(
                types.Part(
                    function_response=types.FunctionResponse(
                        id=fn.id, name=fn.name, response=result,
                    )
                )
            )

    if function_response_parts:
        history.append(types.Content(role="user", parts=function_response_parts))

        # ── Step 3 ────────────────────────────────────────────────────
        final = client.models.generate_content(
            model=TOOL_COMBO_MODEL,
            contents=history,
            config=tool_config,
        )
        return final.text or "（無法取得回覆）"

    return response.text or "（無法取得回覆）"

踩過的坑

❌ 坑 1：`Part.from_function_response()` 不接受 `id` 參數

這是這次最容易踩的坑，而且錯誤只在真實模型呼叫時才會爆，單元測試幾乎不會發現。

原本參考官方範例這樣寫：

# ❌ 錯誤——TypeError 在 runtime 發生
types.Part.from_function_response(
    id=fn.id,       # ← 這個參數不存在！
    name=fn_name,
    response=result,
)

from_function_response 的實際簽名是：

(*, name: str, response: dict, parts: Optional[list] = None) -> Part

完全沒有 id 參數。每次模型真的觸發 function_call，程式就會在這行噴 TypeError，然後靜默進入 Step 3 的 except，回傳錯誤訊息，Places API 的結果從來沒有真正傳回給 Gemini。

正確寫法是直接建構 types.FunctionResponse：

# ✅ 正確
types.Part(
    function_response=types.FunctionResponse(
        id=fn.id,
        name=fn_name,
        response=result,
    )
)

用 python -c "from google.genai import types; help(types.Part.from_function_response)" 可以立刻確認參數清單。

❌ 坑 2：`include_server_side_tool_invocations=True` 讓 Pydantic 爆炸

看到官方文件範例加了這個參數覺得應該加：

# ❌ 錯誤
types.GenerateContentConfig(
    tools=[...],
    include_server_side_tool_invocations=True,  # ← 安裝的 SDK 版本不支援
)

在 google-genai 1.49.0 這個欄位還不在 GenerateContentConfig 的 model fields 裡，Pydantic 會直接噴 extra_forbidden 驗證錯誤。直接拿掉就好，功能完全正常。

❌ 坑 3：`textQuery` 是 `searchText` 的參數，不是 `searchNearby` 的

想說「有 keyword 就帶進 Places API」，直覺把它加進 request body：

# ❌ 錯誤——對 searchNearby endpoint 是無效欄位
if keyword:
    body["textQuery"] = keyword

searchNearby 只接受 includedTypes、locationRestriction 等欄位；textQuery 是 searchText endpoint 的參數。帶了這個欄位不會報錯（某些版本下），但 keyword 完全不生效。

正確的做法是把 keyword 留在 Function Declaration 的 description 裡給 Gemini 參考，讓模型把意圖轉譯到 enriched_query 上，讓 Maps Grounding 去處理關鍵字語意，Places API 只負責回傳真實評分資料。

❌ 坑 4：`response.candidates[0]` 沒有 guard

模型在遇到安全過濾、RECITATION、或其他非正常終止時，candidates 可能是空 list，這時直接 response.candidates[0] 就是 IndexError。

# ❌ 沒有 guard
history = [
    types.Content(role="user", parts=[types.Part(text=enriched_query)]),
    response.candidates[0].content,   # ← 如果 candidates 是空的就爆
]

# ✅ 加 guard
if not response.candidates:
    return response.text or "（無法取得回覆）"

history = [...]

Demo 展示

場景 1：「找評價 4 顆星以上的聚餐熱炒店」

用戶傳送：GPS 位置（台北市信義區，25.0441, 121.5598）

用戶輸入：「請找評價 4 顆星以上、適合多人聚餐的熱炒店，列出名稱、地址和評論摘要。」

[Step 1: Gemini 收到 query + 地圖情境]
  → 偵測到需要餐廳資料，emit function_call:
    search_nearby_restaurants(keyword="熱炒", min_rating=4.0)

[Step 2: Python 呼叫 Places API]
  → lat=25.0441, lng=121.5598 從 session 注入
  → 回傳 3 間評分 ≥ 4.0 的餐廳，含評論文字

[Step 3: Gemini 整合 Maps 情境 + Places 資料]
  → 「老王熱炒｜信義區市民大道100號｜⭐ 4.6（312則）
      評論摘要：份量大、CP值高，朋友聚餐首選；服務快，菜色新鮮。
     ...（共3間）」

場景 2：「有沒有 CP 值高的日式料理？」

用戶輸入：「附近有沒有 CP 值高的日式料理？」

[Step 1: Gemini]
  → function_call: search_nearby_restaurants(keyword="日式料理", min_rating=4.0)

[Step 2: Places API]
  → 回傳 2 間評分符合的日本料理店

[Step 3: Gemini]
  → 「有兩間推薦：
      和食処○○｜...｜⭐ 4.4｜評論：平日午間定食只要280元，新鮮度很高。
      ...」

Demo Script 快速測試

不需要 LINE Bot，直接在本機：

# 只測試 Tool Combo（主功能）
python demo.py combo

# 三個功能全跑
python demo.py all

舊架構 vs 新架構

	舊架構（Maps Grounding only）	新架構（Tool Combo）
工具	`google_maps`（built-in）	`google_maps` + `search_nearby_restaurants`（custom）
評分資料	Gemini 自行描述（可能不準）	Places API 真實數字
評論	AI 生成	真實用戶評論（最多3則）
API 呼叫次數	1次	1次（Step1）+ 1次（Step3）= 2次，但對用戶透明
準確度	中	高
自訂過濾	靠 prompt	`min_rating`、`radius_m` 精確控制

分析與展望

這次實作讓我對 Gemini Tool Combinations 的潛力有了更清楚的認識。

Tool Combinations 真正解決的問題，是讓 Grounding 和 Function Calling 不再是二選一。以前要做「有地圖情境 + 有真實外部資料」，只能自己在應用層手動串兩次 API，或是用 Gemini 的文字生成去「模擬」外部資料（不可靠）。現在模型自己知道何時該用地圖情境、何時該呼叫 Places API，開發者只需要把工具掛上去。

不過這次實作也有幾個值得注意的地方：

lat/lng 注入模式很重要：不能讓模型自己猜座標，一定要從 session 注入，否則定位精度會很差。這個模式也適用於所有「有 session 狀態」的 function calling 場景。
兩次 generate_content 的成本：Tool Combo 的 agentic loop 需要兩次模型呼叫，token 消耗大約是單次的 1.5–2 倍。對低延遲要求高的場景要特別考量。
SDK 版本差異：google-genai 各版本對 GenerateContentConfig 的欄位支援不同，include_server_side_tool_invocations 這類新欄位加版本號確認再用，否則 Pydantic 驗證錯誤很難追。

未來可以延伸的方向：

把 Postback 快速回覆（點「找餐廳」按鈕）也接上 Tool Combo，讓每個入口都能拿到真實評分
加入 searchText endpoint 支援更複雜的關鍵字搜尋（e.g. 米其林推薦）
Tool Combo 搭配其他 built-in 工具（如 google_search）實現更複雜的多工具串接

總結

這次改動的核心概念只有一句話：把 Google Maps grounding 和 Places API function tool 掛在同一個 types.Tool 裡，Gemini 就會在單次對話裡自己協調兩者。

關鍵程式只有這幾行：

# 這就是 Tool Combo 的全部魔法
types.Tool(
    google_maps=types.GoogleMaps(),                       # ← Maps 情境
    function_declarations=[SEARCH_NEARBY_RESTAURANTS_FN], # ← Places API
)

但要讓它真的 work，還需要注意：FunctionResponse 的建構方式、candidates 的 guard、Places API endpoint 的正確欄位、以及 lat/lng 從 session 注入而不是讓模型猜。

完整程式碼在 GitHub，歡迎 clone 來玩。

我們下次見！

AI Agent 的安全性宣告：深入探索 A2AS (Agent-to-Agent Security) 憑證機制

Wed, 25 Mar 2026 00:00:00 +0000

參考連結：

這篇文章記錄了我在維護 linebot-adk (LINE Bot Agent Development Kit) 時，收到的一個有趣 Pull Request：為專案加上 A2AS 安全憑證。這不只是一個 YAML 檔案，更是 2026 年 AI Agent 邁向「工業級安全」的重要里程碑。

前情提要

當我們在開發像 linebot-adk 這樣具備 Tool Use (Function Calling) 能力的 Agent 時，使用者最擔心的問題往往是：「這個 Agent 會不會背著我亂下指令？」或是「它到底能存取哪些資料？」。

傳統上我們只能在 README.md 寫寫說明，但那是給人看的，不是給系統驗證的。這就是為什麼 A2AS (Agent-to-Agent Security) 出現了——它被譽為「AI 界的 HTTPS」。

🛠️ 第一步：理解 A2AS 的 BASIC 模型

A2AS 不只是個名稱，它背後有一套完整的 BASIC 安全模型，旨在解決 AI Agent 之間的信任問題：

(B)ehavior Certificates: 宣告式憑證，明確定義 Agent 的行為邊界。
(A)uthenticated Prompts: 確保提示詞的來源可信且具備追蹤性。
(S)ecurity Boundaries: 利用結構化標籤（如 <a2as:user>）隔離不受信任的輸入。
(I)n-Context Defenses: 在 Prompt 中嵌入防禦邏輯，拒絕惡意注入。
(C)odified Policies: 將業務規則寫成程式碼，在推論時強制執行。

🎨 第二步：解構 a2as.yaml——Agent 的身份證

在 linebot-adk 收到 PR #1 中，最核心的變動就是新增了 a2as.yaml。這個檔案就像是 Agent 的「數位簽名」，將程式碼邏輯顯性化：

manifest:
  subject:
    name: kkdai/linebot-adk
    scope: [main.py, multi_tool_agent/agent.py]
  issued:
    by: A2AS.org
    url: https://a2as.org/certified/agents/kkdai/linebot-adk

agents:
  root_agent:
    type: instance
    models: [gemini-2.5-flash]
    tools: [get_weather, get_current_time]

為什麼這很重要？

這份憑證直接與我們的 main.py 內容掛鉤。當憑證宣告了 tools: [get_weather, get_current_time]，就代表這是一個有限授權的 Agent。如果它試圖執行 delete_database，安全性監控系統就能立刻發現這超出了憑證範圍。

🌐 第三步：結合程式碼邏輯

在 linebot-adk 中，我們使用了 Google 的 ADK (Agent Development Kit) 來建構 Agent。A2AS 憑證能精準地映射我們的程式架構：

1. 工具宣告與實現

在 multi_tool_agent/agent.py 中，我們定義了兩個工具：

def get_weather(city: str) -> dict:
    # 實現獲取天氣的邏輯
    ...

def get_current_time(city: str) -> dict:
    # 實現獲取時間的邏輯
    ...

A2AS 憑證會將這些 function 註冊在 tools 區塊，確保 Agent 的能力邊界是透明且可審計的。

2. Runner 與執行循環

在 main.py 中，我們透過 Runner 來啟動 Agent：

runner = Runner(
    agent=root_agent,
    app_name=APP_NAME,
    session_service=session_service,
)

憑證中的 manifest.subject.scope 標註了 main.py，這意味著整個啟動流程（包含 FastAPI 的 Webhook 處理）都在 A2AS 的合規範圍內。

🚀 第四步：為什麼這是「AI 界的 HTTPS」？

想像一下，如果你要讓一個「旅遊代理 Agent」去跟「飯店預約 Agent」對話。

沒有 A2AS：旅遊 Agent 只能「盲目相信」飯店 Agent。
有了 A2AS：旅遊 Agent 可以先檢查對方的 a2as.yaml 憑證。如果對方宣稱有「修改訂單」的權限但憑證裡沒寫，旅遊 Agent 就可以拒絕交易。

這種 「先驗證，後執行」 的模式，正是 A2AS 想要建立的信任網路。

🛠️ 常見坑洞與故障排除

❓ 憑證過期或 Commit Hash 不符怎麼辦？

原因： A2AS 憑證是綁定特定 Git Commit 的。當你修改了 agent.py 的邏輯但沒更新憑證，驗證就會失效。 修正： 每次修改 Agent 的核心功能（如新增 Tool 或更換 Model）後，都必須重新產出並簽署 a2as.yaml。

❓ 使用 A2AS 會增加延遲嗎？

不會。A2AS 主要是「宣告式」與「結構化」的規範。在推論階段，它是透過結構化標籤（BASIC 模型中的 S）來幫助 LLM 區分指令與資料，反而能減少模型因混淆而產生的幻覺，提升執行效率。

🏁 總結

透過這次 A2AS 憑證的導入，linebot-adk 不再只是一個簡單的 LINE Bot 範例，它成為了一個符合 2026 年安全性標準的透明 Agent。在 AI 代理人逐漸滲透我們生活的時代，「透明」就是最好的防禦。

如果你也在開發 AI Agent，不妨去 A2AS.org 看看，為你的專案加上那枚象徵信任的勳章。Happy Coding! 🦞

Blog E

[Workshop][Gemini CLI] Build with AI 2026 實戰筆記：用 Gemini CLI + 官方 MCP，從零到上線一隻 Google Drive LINE Bot

前情提要：當 CLI 變成「會思考的同事」

為什麼是 Gemini CLI + MCP？先看時間軸

Workshop 1：環境準備與官方 MCP 安裝

為什麼建議用 Cloud Shell 開場

MCP 是什麼？三句話講完

MCP #1：Google Developer Knowledge

設定步驟

驗證

MCP #2：Google Maps Platform Code Assist

驗證

Workshop 2：把 LINE Bot 部署到 Cloud Run

部署流程總覽

階段一：LINE 金鑰

階段二：GCP 專案開通

階段三：OAuth Consent Screen + Gemini CLI 登入

階段四：用 Gemini CLI 部署到 Cloud Run（重頭戲）

補上真實的 OAuth 設定

階段五：把 LINE Webhook 對到 Cloud Run

常用維運指令

工作坊現場踩坑紀錄

踩坑一：Billing 沒開，第一次 deploy 就紅字

踩坑二：Firestore type 參數名稱

踩坑三：忘記啟用 Drive API，OAuth 過了卻寫不進去

為什麼這套組合值得學？

想再深入？建議的進階閱讀

後記：來 LINE 一起做東西吧

[Gemini實戰][RAG] Gemini API File Search 多模態大升級全解析：Embedding 2、Metadata 過濾、頁級引用，附 LINE Bot 開源實作

前情提要：RAG 終於不用自己拼樂高了

新功能三大重點

1. 真．多模態檔案搜尋（Native Multimodal File Search）

2. Custom Metadata 與 Server-side 過濾

3. 頁級引用（Page-level Citations）

多模態的引擎：Gemini Embedding 2

開發者真正會在意的事：價格與接入成本

標準工作流程：4 個 SDK call 接完一條 RAG

演示案例：把這些新功能塞進一隻 LINE Bot

部署實戰：commit → 自動上線

踩坑紀錄：兩個跟新功能直接相關的雷

踩坑一：寫死的 Model ID 過時

踩坑二：神祕的「Upload has already been terminated」

總結：multimodal RAG 的入場費，史上最低

[GCP 實戰][BwAI] AI 賦能開發：使用 Gemini CLI 快速部署 LINE Bot 雲端備份神器

前情提要

準備工作：召喚 AI 助手

實戰部署流程：AI 帶路

第一步：環境檢測與 API 啟用

第二步：建立 Firestore 資料庫 (遇到第一個坑)

第三步：先上車後補票的 Cloud Run 部署

第四步：完成 Google OAuth 設定與環境變數更新

部署過程中的血淚踩坑紀錄

踩坑一：忘記綁定信用卡的 390001 錯誤

踩坑二：指令參數的語法演進

踩坑三：那個隱形的「Drive API」

總結

[GCP 實戰] 打造持久化 AI 助手：在 GCE 部署 Hermes Agent 並接軌 Telegram

前情提要

環境參數預備

第一步：建立 GCE 實例

第二步：安裝 Hermes Agent

第三步：配置 Gemini 2.5 Flash (SOP 實戰)

第四步：接軌 Telegram 與背景持久化

遷移過程中的血淚踩坑：為什麼我的 Agent 沒反應？

踩坑一：Gemini 3.0 的 404 幽靈

踩坑二：模型標識符的前綴混淆

踩坑三：Systemd 與「已經運行的進程」衝突

總結

[GCP 實戰] OpenAB 部署筆記：在 GCE 上打造支援 Telegram 的 Gemini ACP 橋接器

前情提要

部署決策：為什麼選 GCE 而不是 Cloud Run？

實戰步驟：Step-by-Step 部署過程

第一步：撰寫自動化啟動腳本 (Startup Script)

第二步：使用 gcloud 建立 GCE 實例

第三步：配置 Gemini API Key

第四步：使用 Cloudflare Tunnel 解決 HTTPS 需求

遷移過程中的血淚踩坑：技術總結

踩坑一：鏡像來源的混淆

踩坑二：硬編碼的配置路徑

踩坑三：Security Secret Token 驗證失敗

踩過的坑：那個消失的 `await`

❌ 坑 1：`Part.from_text()` 不接受 positional argument

❌ 坑 5：`GOOGLE_CLOUD_LOCATION=global` 讓 Live API 失聯

❌ 坑 1：`Part.from_function_response()` 不接受 `id` 參數

❌ 坑 2：`include_server_side_tool_invocations=True` 讓 Pydantic 爆炸

❌ 坑 3：`textQuery` 是 `searchText` 的參數，不是 `searchNearby` 的

❌ 坑 4：`response.candidates[0]` 沒有 guard