SuperAPI AI 工具集

skill-gemini-google-search-tool

通用与其它

查看项目

更新于 10-16 06:55

技能介绍

用途

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。