内容
# Zoom 搜索
<table>
<tr>
<td align="center" colspan="3">
<h2>更优答案，有限额外成本</h2>
<strong>直接搜索基准线 vs Zoom 搜索工作流程</strong>
</td>
</tr>
<tr>
<td align="center"><h3>有用结果</h3></td>
<td align="center"><h3>答案质量</h3></td>
<td align="center"><h3>额外预算</h3></td>
</tr>
<tr>
<td align="center"><h2>1-5 -> 4-12</h2>更多优质来源</td>
<td align="center"><h2>2.0-7.2 -> 7.8-8.7</h2>更强最终答案</td>
<td align="center"><h2>+5.9s 到 +12.2s</h2>+2.3k 到 +5.1k tokens</td>
</tr>
</table>
<p align="center">
<img src="https://img.shields.io/badge/python-%3E%3D3.10-3776AB" alt="Python >=3.10" />
<img src="https://img.shields.io/badge/license-MIT-0F766E" alt="License: MIT" />
<img src="https://img.shields.io/badge/package-zoom--search-2563EB" alt="Package: zoom-search" />
<img src="https://img.shields.io/badge/tests-pytest-0F172A" alt="Tests: pytest" />
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#代理工具示例">代理工具</a> ·
<a href="./docs/agent-integration.md">代理集成</a> ·
<a href="./docs/benchmarks.md">基准测试</a> ·
<a href="./docs/advanced-configuration.md">高级配置</a>
</p>
Zoom 搜索是一种用于 AI 代理的搜索和证据工具。它帮助代理重写搜索问题，收集更广泛的网络证据，聚焦于高价值源域，并返回带有指标的来源答案。
它适用于需要比单一搜索调用更强的源发现、追溯性和答案基础的代理应用。
## 为什么选择 Zoom 搜索
- **代理搜索工具**：为工具调用代理提供结构化答案、来源、警告和指标。
- **更好的证据收集**：将代理问题重写为更强的搜索变体。
- **源域聚焦**：首先广泛搜索，然后聚焦于高价值域。
- **可追溯的输出**：保留源域、重复来源、警告和运行时指标。
- **MCP/LangGraph 准备**：通过 MCP 或 LangGraph 集成使用 Zoom 搜索。
- **提供商灵活**：使用内置引擎或自定义 OpenAI 兼容和原生 HTTP 提供商。
## 安装
```bash
pip install zoom-search
```
## 快速开始
在没有 API 密钥的情况下运行确定性的本地演示：
```python
import asyncio
from zoom_search import search
async def main() -> None:
response = await search(
question="深圳哪些酒店的房间配备有运动自行车？",
demo_mode=True,
output_mode="answer_with_sources",
seed=7,
)
print(response.answer)
print(response.results)
asyncio.run(main())
```
## 代理工具示例
安装 MCP 额外组件：
```bash
pip install "zoom-search[mcp]"
```
将 Zoom 搜索添加到您的 MCP 客户端：
```json
{
"mcpServers": {
"zoom-search": {
"command": "zoom-search-mcp",
"env": {
"ZOOM_SEARCH_LLM_ENGINE": "gemini",
"ZOOM_SEARCH_LLM_MODEL": "gemini-2.5-flash",
"ZOOM_SEARCH_LLM_API_KEY": "您的 Gemini API 密钥",
"ZOOM_SEARCH_SEARCH_ENGINE": "tavily",
"ZOOM_SEARCH_SEARCH_API_KEY": "您的 Tavily API 密钥"
}
}
}
}
```
您的代理可以调用带有 `question` 参数的 `zoom_search` 工具：
```json
{
"question": "哪些向量数据库支持混合搜索和元数据过滤，用于 Python 应用？",
"output_mode": "answer_with_sources"
}
```
该工具返回来源答案、源域聚焦、警告和运行时指标。
或者，将其包装为 LangGraph/LangChain 工具：
```python
import os
from langchain.tools import tool
from zoom_search import search
@tool
async def zoom_search_evidence(query: str) -> dict:
response = await search(
question=query,
llm_engine=os.environ["ZOOM_SEARCH_LLM_ENGINE"],
llm_model=os.environ["ZOOM_SEARCH_LLM_MODEL"],
llm_api_key=os.environ["ZOOM_SEARCH_LLM_API_KEY"],
search_engine=os.environ["ZOOM_SEARCH_SEARCH_ENGINE"],
search_api_key=os.environ["ZOOM_SEARCH_SEARCH_API_KEY"],
output_mode="answer_with_sources",
)
return response.to_dict()
```
有关 MCP 客户端配置和提供商环境变量的详细信息，请参见 [`docs/agent-integration.md`](./docs/agent-integration.md)。
## 基准测试
历史评估比较直接搜索和 Zoom 搜索代理工作流程，显示出更好的有用结果覆盖率和更强的最终答案，同时具有有限的额外时间和 token 成本。
| 案例 | 好结果 | 答案质量 | 额外时间 | 额外 tokens |
|---|---:|---:|---:|---:|
| Playwright 身份验证重用 | 5 -> 7 | 6.6 -> 8.7 | +5.89s | +2,324 |
| GitHub Actions 机密继承 | 1 -> 4 | 2.0 -> 7.8 | +8.93s | +2,936 |
| 粉蓝花修剪比较 | 4 -> 12 | 7.2 -> 8.4 | +12.17s | +5,073 |
有关完整基准测试说明，请参见 [`docs/benchmarks.md`](./docs/benchmarks.md)。
演示模式、流式传输、对话历史记录和 LangGraph 的可运行示例可在 `examples/` 目录中找到。
## 文档
- 高级配置：https://github.com/goofrey/zoom-search/blob/main/docs/advanced-configuration.md
- 代理集成：https://github.com/goofrey/zoom-search/blob/main/docs/agent-integration.md
- 开发检查：https://github.com/goofrey/zoom-search/blob/main/docs/development.md
- 基准测试：https://github.com/goofrey/zoom-search/blob/main/docs/benchmarks.md
## 许可证
Zoom 搜索在 [MIT 许可证](./LICENSE) 下开源。
