Google Search Grounding：讓 Gemini 搜尋網路資訊

學完你能做什麼

• 為 Gemini 模型啟用 Google Search，讓 AI 能夠搜尋即時網路資訊
• 調節搜尋閾值，控制模型搜尋的頻率
• 理解 Google Search Grounding 的工作原理和適用場景
• 根據任務需求選擇合適的配置

你現在的困境

什麼是 Google Search Grounding？

Google Search Grounding 是 Gemini 的一個功能，它允許模型在需要時自動搜尋 Google，取得即時資訊（如新聞、統計數據、產品價格等），而不是完全依賴訓練資料。

你用 Gemini 問「今天天氣如何」或「最新版 VS Code 版本號」，模型可能回答不出來，因為它的訓練資料已經過時了。啟用 Google Search Grounding 後，模型可以自己上網查答案，就像你用瀏覽器一樣。

什麼時候用這一招

場景	是否需要啟用	原因
程式碼生成、程式設計問題	❌ 不需要	程式設計知識相對穩定，訓練資料足夠
取得最新資訊（新聞、價格、版本）	✅ 強烈推薦	需要即時資料
事實查核（具體日期、統計）	✅ 推薦	避免模型編造資訊
創意寫作、腦力激盪	❌ 不需要	不需要事實準確性
技術文件查詢	✅ 推薦	查找最新 API 文件

核心思路

Google Search Grounding 的核心是讓模型在需要時自動搜尋，而不是每次都搜尋。外掛程式通過注入 googleSearchRetrieval 工具，讓 Gemini 能夠呼叫 Google 搜尋 API。

關鍵概念

• Auto 模式：模型自己決定是否搜尋（根據閾值）
• 閾值（grounding_threshold）：控制模型搜尋的「門檻」。值越小，搜尋越頻繁

🎒 開始前的準備

前置檢查

在開始前，請確認：

• [ ] 已完成 快速安裝
• [ ] 已新增至少一個 Google 帳戶
• [ ] 已成功發起首次請求（參考 首次請求）

跟我做

第 1 步：檢查設定檔位置

外掛程式的設定檔位於：

• macOS/Linux: ~/.config/opencode/antigravity.json
• Windows: %APPDATA%\opencode\antigravity.json

如果檔案不存在，先建立它：

# macOS/Linux
cat > ~/.config/opencode/antigravity.json << 'EOF'
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json"
}
EOF

# Windows
@"
{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json"
}
"@ | Out-File -FilePath "$env:APPDATA\opencode\antigravity.json" -Encoding utf8

你應該看到：設定檔已建立，包含 $schema 欄位

第 2 步：啟用 Google Search

在設定檔中新增 web_search 設定：

{
  "$schema": "https://raw.githubusercontent.com/NoeFabris/opencode-antigravity-auth/main/assets/antigravity.schema.json",
  "web_search": {
    "default_mode": "auto",
    "grounding_threshold": 0.3
  }
}

設定說明：

欄位	值	說明
web_search.default_mode	"auto" 或 "off"	啟用或停用 Google Search，預設 "off"
web_search.grounding_threshold	0.0 - 1.0	搜尋閾值，預設 0.3，僅在 auto 模式生效

你應該看到：設定檔已更新，包含 web_search 設定

第 3 步：調整搜尋閾值（可選）

grounding_threshold 控制模型搜尋的頻率：

閾值	行為	適用場景
0.0 - 0.2	頻繁搜尋，幾乎每次不確定都搜	需要高度準確的即時資料
0.3（預設）	適中，模型需要較確信才會搜	日常使用，平衡準確性和速度
0.7 - 1.0	很少搜尋，只在高置信度時搜	減少搜尋次數，提升速度

經驗之談

從預設值 0.3 開始，如果發現：

• 模型沒搜尋 → 降低閾值（如 0.2）
• 搜尋太頻繁，回應慢 → 提高閾值（如 0.5）

你應該看到：閾值已調整，可根據實際使用體驗優化

第 4 步：驗證設定

重新啟動 OpenCode，或重新載入設定（如果支援），然後發起一個需要即時資訊的請求：

使用者輸入：
VS Code 最新版本是多少？

系統回覆（啟用 Google Search）：
VS Code 的最新穩定版本是 1.96.4（截至 2026 年 1 月）...

[citation:1] ← 引用來源標記

你應該看到：

• 模型回答包含引用來源（[citation:1] 等）
• 回答內容是最新的，不是訓練資料中的舊版本

第 5 步：測試不同閾值

嘗試調整 grounding_threshold，觀察模型行為變化：

// 低閾值（頻繁搜尋）
"grounding_threshold": 0.1

// 高閾值（很少搜尋）
"grounding_threshold": 0.7

每次調整後，用相同問題測試，觀察：

• 是否搜尋（查看回應是否有引用）
• 搜尋次數（多個 citation）
• 回應速度

你應該看到：

• 低閾值：搜尋更頻繁，但回應稍慢
• 高閾值：搜尋更少，但可能回答不準確

檢查點 ✅

點擊展開驗證清單

完成以下檢查，確認設定正確：

• [ ] 設定檔包含 web_search 設定
• [ ] default_mode 設定為 "auto"
• [ ] grounding_threshold 在 0.0 到 1.0 之間
• [ ] 發起需要即時資訊的請求，模型返回包含引用
• [ ] 調整閾值後，模型搜尋行為有變化

如果全部通過，說明 Google Search Grounding 已正確啟用！

踩坑提醒

問題 1：模型沒有搜尋

症狀：啟用 auto 模式後，模型仍然沒有搜尋，也沒有引用來源。

原因：

• 閾值太高（如 0.9），模型需要極高確信度才搜尋
• 問題本身不需要搜尋（如程式設計問題）

解決方法：

• 降低 grounding_threshold 到 0.2 或更低
• 用明確需要即時資訊的問題測試（如「今天天氣如何」、「最新新聞」）

問題 2：搜尋太頻繁，回應慢

症狀：每個問題都搜尋，回應時間明顯增加。

原因：

• 閾值太低（如 0.1），模型過於頻繁觸發搜尋
• 問題類型本身需要即時資訊（如股票價格、新聞）

解決方法：

• 提高 grounding_threshold 到 0.5 或更高
• 如果任務不需要即時資訊，將 default_mode 改為 "off"

問題 3：設定檔格式錯誤

症狀：外掛程式報錯，無法載入設定。

原因：JSON 格式錯誤（如多餘的逗號、引號不匹配）。

解決方法：使用 JSON 驗證工具檢查設定檔，確保格式正確。

# 驗證 JSON 格式
cat ~/.config/opencode/antigravity.json | python3 -m json.tool

本課小結

• Google Search Grounding 讓 Gemini 模型能夠搜尋即時網路資訊
• 通過 web_search.default_mode: "auto" 啟用，"off" 停用
• grounding_threshold 控制搜尋頻率：值越小，搜尋越頻繁
• 預設閾值 0.3 適合大多數場景，可根據實際體驗調整
• 模型會在回答中引用來源，標記為 [citation:1] 等

下一課預告

下一課我們學習 雙配額系統。

你會學到：

• Antigravity 和 Gemini CLI 兩個獨立配額池如何工作
• 如何在配額池之間切換，最大化利用率
• 配額池化的最佳實踐

---

附錄：原始碼參考

點擊展開查看原始碼位置

更新時間：2026-01-23

功能	檔案路徑	行號
Google Search 設定 Schema	src/plugin/config/schema.ts	303-319
Google Search 型別定義	src/plugin/transform/types.ts	85-88
Google Search 注入邏輯	src/plugin/transform/gemini.ts	402-419
Google Search 設定載入	src/plugin/config/loader.ts	173-184
Google Search 設定應用	src/plugin.ts	1194-1196

關鍵設定項：

• web_search.default_mode: "auto" 或 "off"，預設 "off"
• web_search.grounding_threshold: 0.0 - 1.0，預設 0.3

關鍵函式：

• applyGeminiTransforms()：應用所有 Gemini 轉換，包括 Google Search 注入
• normalizeGeminiTools()：規範化工具格式，保留 googleSearchRetrieval 工具
• wrapToolsAsFunctionDeclarations()：將工具包裝為 functionDeclarations 格式

工作原理：

1. 外掛程式從設定檔讀取 web_search.default_mode 和 web_search.grounding_threshold
2. 當 mode === "auto" 時，在請求的 tools 陣列中注入 googleSearchRetrieval 工具：

   {
     "googleSearchRetrieval": {
       "dynamicRetrievalConfig": {
         "mode": "MODE_DYNAMIC",
         "dynamicThreshold": 0.3  // grounding_threshold
       }
     }
   }

3. Gemini 模型根據閾值決定是否呼叫搜尋工具
4. 搜尋結果會包含在回應中，並標記引用來源（[citation:1] 等）