什么是gemini-smart-search
Gemini Smart Search 是一个基于本地脚本的智能搜索工具，专为需要以 Gemini 模型作为后端搜索引擎而设计的轻量级解决方案。它通过在本地运行 Python 脚本的方式，将用户查询路由至 Gemini 的多个模型变体（如 Flash-Lite 和 Flash 系列），并根据配额、可用性和性能动态选择最优模型。该工具不依赖网关配置变更，避免了频繁重启系统或修改全局设置的问题，特别适合在开发、测试或隔离不同 API 配额池时使用。其核心优势在于支持结构化 JSON 输出，便于下游系统自动化处理结果，同时具备完善的错误回退机制，可在遇到配额超限或模型不可用等临时问题时自动切换候选模型。 该工具采用双层模型路由架构：外层为面向用户的显示链（display chain），提供直观的性能层级标签（如 cheap、balanced、deep），内层为实际探测的 API 模型 ID 列表，确保即使在预览版模型命名复杂的情况下也能正确调用。例如，在处理 Gemini 3.x 系列时，不会简单使用 UI 标签，而是主动探测带 preview 后缀的真实 API 端点。此外，工具优先使用环境变量 `SMART_SEARCH_GEMINI_API_KEY`，若无则回退至标准 `GEMINI_API_KEY`，并支持从项目根目录下的 `.env.local` 文件加载密钥，避免敏感信息进入版本控制。这种设计既保证了安全性，又提升了配置的灵活性。 尽管当前版本功能较为基础，未引入缓存、高级调优参数或引用链接规范化等复杂特性，但其最小可行实现已覆盖关键生产需求：直接调用 Gemini API、启用 Google 搜索 grounding、按模式路由模型、支持 JSON 格式返回以及跨模型失败时的自动回退。所有成功与失败的响应均遵循统一的数据契约，包含查询内容、所用模型、引用来源、错误类型及是否需人工升级等信息，极大增强了可观测性与集成能力。
核心功能特点
- 支持动态路由至多个 Gemini 模型变体（如 Flash-Lite 和 Flash），根据配额和可用性智能选择最优模型
- 提供三种预设模式（cheap/balanced/deep）对应不同的性能与成本权衡策略
- 采用双层模型映射机制：人类可读的显示链 + 实际探测的 API 模型 ID，兼容预览版模型命名规则
- 结构化 JSON 输出，包含查询、模型使用详情、引用链接、错误状态及升级路径等完整字段
- 内置配额与临时故障感知的回退机制，仅在特定上游错误时切换模型，避免静默失败
- 支持专用 API 密钥路径（`SMART_SEARCH_GEMINI_API_KEY`），优先于通用密钥，且可从 `.env.local` 安全加载
适用场景
Gemini Smart Search 最适用于那些希望完全基于 Gemini 模型进行网络搜索但又不愿频繁改动网关配置的场景。例如，在 AI 代理系统中，当默认的 `web_search` 功能过于静态或每次更换模型都需要重启服务时，此技能可作为灵活的后端替代方案。开发者可以在不中断其他模块的前提下，通过命令行参数快速切换模型偏好，测试不同模型对同一查询的响应质量，或在特定任务中优化延迟与成本的平衡。 另一个典型应用场景是隔离和管理多个 Gemini API 配额池。企业或团队可能拥有多个 API 密钥，用于区分生产环境与沙箱环境，或者为不同优先级的应用分配独立配额。此时，使用 Gemini Smart Search 可以为每个应用指定专属密钥路径，避免资源争抢，并实现细粒度的用量监控与告警。结合其 JSON 输出能力，这些结果还可被集成到日志分析平台或自动化运维流程中，进一步提升可管理性。 此外，该工具特别适合需要稳定接口对接的下游系统。由于所有响应均为标准化 JSON 格式，无论成功与否，接收方都能一致地解析数据，无需额外适配逻辑。这对于构建可扩展的 AI 工作流至关重要——无论是用于知识检索、事实核查还是实时问答系统，都能确保输入输出的一致性和可靠性。虽然目前不支持高级功能如缓存或多轮对话上下文，但对于追求简洁、可控且易于调试的搜索接口而言，它已经提供了足够强大的基础能力。