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] 等）