用途
gemini-google-search-tool 是一个 Python CLI 工具与库,将 Gemini AI 模型通过 Google Search grounding 连接到实时网络内容。它适用于需要超出模型训练截止时间的实时网络信息、需要可验证来源与引用的 AI 回答、希望借助 Google Search grounding 减少幻觉,以及构建需要最新信息的 AI 工作流的场景。
不适用于:不需要实时数据的静态知识查询、不需要来源归属的任务,以及仅离线环境(该工具需要互联网和 API key)。
主要能力
- 自动搜索决策:Gemini 判断搜索是否能改善回答。
- 查询生成:自动生成合适的搜索查询。
- 结果处理:处理搜索结果并综合信息。
- 引用生成:返回带可验证来源的 grounded 回答。
- 支持多查询搜索以获得更全面的覆盖。
- 提供内联引用链接(--add-citations)。
- 支持 JSON(默认)与 Markdown(--text)输出。
- 支持从 stdin 读取提示词。
- 提供 bash、zsh、fish 的 shell 补全脚本。
- 提供多级详细度日志(-v/-vv/-vvv)。
安装与前置条件
从源码安装:
git clone https://github.com/dnvriend/gemini-google-search-tool.git
cd gemini-google-search-tool
uv tool install .
验证安装:
gemini-google-search-tool --version
前置条件:Python 3.14 或更高版本、uv 包管理器、Google Gemini API key(可免费获取)、GEMINI_API_KEY 环境变量。
使用方式
设置 API key:
export GEMINI_API_KEY='your-api-key-here'
基本查询:
gemini-google-search-tool query "Who won euro 2024?"
带内联引用:
gemini-google-search-tool query "Latest AI news" --add-citations
使用 pro 模型:
gemini-google-search-tool query "Complex analysis" --pro
query 命令参数:PROMPT(位置参数,除非使用 --stdin 否则必填)、--stdin/-s(从 stdin 读取提示词,覆盖 PROMPT)、--add-citations(在回答文本中添加内联引用链接)、--pro(使用 gemini-2.5-pro 模型,默认 gemini-2.5-flash)、--text/-t(输出 markdown 格式而非 JSON)、-v/-vv/-vvv(详细度级别 INFO/DEBUG/TRACE)。
从 stdin 读取:
echo "Climate change updates" | gemini-google-search-tool query --stdin
Markdown 输出:
gemini-google-search-tool query "Quantum computing news" --text
Pro 模型加详细输出:
gemini-google-search-tool query "Complex analysis" --pro -vv
Trace 模式(显示 HTTP 请求):
gemini-google-search-tool query "Test" -vvv
JSON 输出结构包含 response_text、citations(含 index、uri、title)以及 grounding_metadata(含 web_search_queries、grounding_chunks、grounding_supports)。Markdown 输出为回答文本后跟 Citations 列表。
completion 命令用于生成 shell 补全脚本:
gemini-google-search-tool completion {bash|zsh|fish}
示例:
eval "$(gemini-google-search-tool completion bash)"
eval "$(gemini-google-search-tool completion zsh)"
mkdir -p ~/.config/fish/completions
gemini-google-search-tool completion fish > ~/.config/fish/completions/gemini-google-search-tool.fish
持久化安装可加入 ~/.bashrc 或 ~/.zshrc。
作为库使用
from gemini_google_search_tool import (
GeminiClient,
query_with_grounding,
add_inline_citations,
)
client = GeminiClient() # Reads GEMINI_API_KEY from environment
response = query_with_grounding(
client=client,
prompt="Who won euro 2024?",
model="gemini-2.5-flash",
)
print(response.response_text)
print(f"Citations: {len(response.citations)}")
if response.grounding_segments:
text_with_citations = add_inline_citations(
response.response_text,
response.grounding_segments,
response.citations,
)
print(text_with_citations)
模型选择
gemini-2.5-flash(默认):响应快、适合高并发查询、成本效益高、适合直接问题,推荐用于大多数场景。
gemini-2.5-pro(--pro):推理能力更强、更适合复杂分析、回答质量更高、每次查询成本更高。
详细度级别
无标志(WARNING):仅错误和警告,输出干净的 JSON/文本。
-v(INFO):显示查询命令启动、客户端初始化、模型与 grounding 查询、查询完成等信息。
-vv(DEBUG):显示提示词校验、客户端初始化、API 调用、提取的引用数量、网络搜索查询等。
-vvv(TRACE):显示 TCP 连接、TLS 启动、请求头发送等 HTTP 级细节。
流水线集成
JSON 输出到 stdout,日志到 stderr:
gemini-google-search-tool query "test" | jq '.response_text'
gemini-google-search-tool query "test" | jq '.citations[]'
gemini-google-search-tool query "test" && echo "Success"
stdin 支持:
cat question.txt | gemini-google-search-tool query --stdin
echo "Who won euro 2024?" | gemini-google-search-tool query --stdin
输出格式与退出码
JSON(默认):结构化输出,含 response_text 与 citations,便于机器解析;始终包含 citations 数组;使用 -vv 或 -vvv 时可包含 grounding_metadata。
Markdown(--text):人类可读,回答文本后跟引用部分。
详细度日志输出到 stderr,保持 stdout 干净以便 JSON 解析。
退出码:0 表示成功;1 表示错误(客户端错误、无效参数或查询失败)。
常见问题
缺少 API key:错误提示 GEMINI_API_KEY environment variable is required。解决:从 Google AI Studio 获取 API key,设置环境变量或加入 shell 配置文件。
空或无效响应:错误提示 Query failed: Invalid response format。解决:检查 API key 是否有效、验证网络连接、使用 -vv 查看详细错误、检查 Gemini API 状态页。
速率限制:错误提示 Query failed: Rate limit exceeded。解决:等待重试、检查 Google AI Studio 中的 API 配额、考虑升级 API 层级。
模块导入错误(库使用):ImportError: No module named 'gemini_google_search_tool'。解决:安装包 uv tool install .,或在开发中使用 uv sync 后 uv run python script.py,并验证安装。
获取帮助与调试
gemini-google-search-tool --help
gemini-google-search-tool query --help
gemini-google-search-tool completion --help
gemini-google-search-tool --version
调试:使用 -vv 查看 API 调用与响应处理,使用 -vvv 追踪 HTTP 请求。
最佳实践
默认使用 Flash 模型;需要验证时使用 --add-citations;通过 jq 处理 JSON 输出;排障用 -vv,HTTP 级细节用 -vvv;API key 安全存放在 shell 配置文件而非脚本中;脚本或自动化中始终检查退出码;复杂分析使用 --pro。
资源
GitHub 仓库:https://github.com/dnvriend/gemini-google-search-tool
Google Search Grounding 文档:https://ai.google.dev/gemini-api/docs/grounding
Gemini API 文档:https://ai.google.dev/gemini-api/docs
获取 API Key:https://aistudio.google.com/app/apikey
Python 包:可通过 uv tool install 安装。
开发者指南:见仓库中的 CLAUDE.md。