diff --git a/README_ZH.md b/README_ZH.md new file mode 100644 index 0000000..3afa993 --- /dev/null +++ b/README_ZH.md @@ -0,0 +1,335 @@ +# 🔍 OpenDeepSearch: 通过开源推理模型与代理实现搜索民主化 🚀 + +
+ Sentient Logo +
+ +
+
+ + Homepage + + + GitHub + + + Hugging Face + +
+ +
+ + Discord + + + Twitter Follow + +
+ +

+ 📄 阅读论文 +

+ +## 项目简介 📝 + +OpenDeepSearch (ODS) 是一个**轻量级但功能强大的“AI 研究助理”**，专为解决 AI Agent 的联网能力而设计。它不仅是简单的关键词匹配，更是一个能像人类研究员一样**深读网页、筛选信息、生成报告**的智能搜索层。 + +**为什么你需要它？** +现在的 AI 往往面临“知识幻觉”和“数据滞后”的问题。传统的联网插件只能抓取网页的标题和摘要，经常遗漏关键信息。ODS 的出现，就是为了提供一个**开源、免费、可本地化**的 Deep Research 替代方案，赋予 Agent **“全页阅读”** 和 **“深度推理”** 的能力。 + +
+ Evaluation Results +
+ +- **高性能**: 在单跳（Single-hop）查询（如 [SimpleQA](https://openai.com/index/introducing-simpleqa/)）任务上，性能媲美闭源商业搜索方案 🔍。 +- **高级推理**: 在多跳（Multi-hop）复杂查询（如 [FRAMES bench](https://huggingface.co/datasets/google/frames-benchmark)）任务上，性能显著优于传统搜索替代方案 🚀。 + +## 目录 📑 + +- [项目简介 📝](#项目简介-) +- [核心亮点 ✨](#核心亮点-) +- [痛点与解决方案 🎯](#痛点与解决方案-) +- [运作机制 ⚙️](#运作机制-️) +- [安装指南 📚](#安装指南-) +- [环境配置 ⚙️](#环境配置-️) +- [使用指南 🛠️](#使用指南-️) + - [作为独立模块使用 🔍](#作为独立模块使用-) + - [运行 Gradio 演示界面 🖥️](#运行-gradio-演示界面-️) + - [与 SmolAgents 集成 🤖](#与-smolagents-集成-) + - [构建 ReAct Agent 🧠](#构建-react-agent-) +- [搜索模式详解 🔄](#搜索模式详解-) +- [致谢 💡](#致谢-) + +## 核心亮点 ✨ + +- **🧠 像人类一样思考**: 利用 **[Crawl4AI](https://github.com/unclecode/crawl4ai)** 进行全页爬取，而非仅看摘要。 +- **⚡ 双模式运行**: + - **默认模式 (Default)**: 快速、高效，适合简单事实查询。 + - **专业模式 (Pro Mode)**: 深度研究，包含全自动的爬取、切分、重排序流程，适合复杂行业调研。 +- **🤖 Agent 优先**: 专为 AI Agent 设计，与 **SmolAgents** 无缝配合，是构建自主智能体的最佳搭档。 +- **🔌 自由扩展**: 支持通过 n8n、Dify 等平台封装为 API 服务，轻松集成到现有的工作流中。 + +## 痛点与解决方案 🎯 + +| 传统搜索集成痛点 ❌ | OpenDeepSearch 解决方案 ✅ | +|-------------------|--------------------------| +| **浅层信息**: 仅读取标题和摘要，经常错过正文细节。 | **全页理解**: 实际访问并爬取网页正文，不错过任何细节。 | +| **噪音干扰**: 广告、侧边栏严重干扰 AI 判断。 | **智能清洗**: 自动去除杂质，提取纯净的正文内容。 | +| **缺乏语义**: 无法处理“多跳推理”问题（需结合多处信息）。 | **智能重排序**: 使用 Embedding 模型筛选“黄金片段”，构建高质量上下文。 | +| **闭源昂贵**: 依赖付费 API，数据不可控。 | **完全开源**: 支持本地部署，数据隐私可控，成本极低。 | + +## 运作机制 ⚙️ + +把 ODS 想象成一个流水线工厂： + +1. **接收任务**: 用户提出复杂问题（如“分析 Rust 与 Python 的最新性能对比”）。 +2. **广度搜索 (Eyes)**: 调用 Serper/SearXNG 获取初始链接。 +3. **深度爬取 (Hands)**: 像浏览器一样打开每个链接，抓取全文。 +4. **智能筛选 (Brain)**: 将长文切块，使用 Jina/Infinity 等模型进行重排序，筛选出最相关的段落。 +5. **生成答案 (Mouth)**: 将筛选后的精华内容喂给 LLM，生成最终报告。 + +## 安装指南 📚 + +OpenDeepSearch 支持多种安装方式。 + +### 使用 PIP 安装 + +```bash +pip install -e . +# 或者安装依赖 +pip install -r requirements.txt +``` + +*注意：你需要预先安装 `torch`。推荐使用 `uv` 来加速安装：`uv pip install -e .`* + +### 使用 PDM 安装 (推荐) 📦 + +PDM 是一个现代化的 Python 包管理器，支持 lockfile 和 PEP 582。 + +```bash +# 1. 安装 PDM +curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 - + +# 2. 初始化项目 +pdm init + +# 3. 安装依赖 +pdm install + +# 4. 激活虚拟环境 +eval "$(pdm venv activate)" +``` + +## 环境配置 ⚙️ + +在使用前，你需要配置必要的 API Key。为了简化配置，本项目支持读取根目录下的 `.env` 文件。 + +### 1. 快速配置 (推荐组合) + +对于初次使用者，我们推荐以下**高性价比且易于获取**的服务组合： + +1. **搜索**: [Serper.dev](https://serper.dev) (提供免费额度，Google 搜索结果) +2. **重排序**: [Jina AI](https://jina.ai/) (专为搜索优化，提供免费额度) +3. **大模型**: [OpenRouter](https://openrouter.ai) (一站式聚合 OpenAI, Anthropic, Gemini 等模型) + +**配置步骤**： + +在项目根目录下创建一个名为 `.env` 的文件，并填入以下内容： + +```bash +# 1. 搜索服务配置 (Serper) +SERPER_API_KEY="在这里填入你的_Serper_Key" + +# 2. 重排序服务配置 (Jina AI) +JINA_API_KEY="在这里填入你的_Jina_Key" + +# 3. LLM 服务配置 (推荐使用 OpenRouter 聚合服务) +OPENROUTER_API_KEY="在这里填入你的_OpenRouter_Key" + +# 4. 指定默认使用的模型 ID (格式: 供应商/模型名) +# 推荐使用 Gemini 2.0 Flash (速度快、窗口大、成本低) +LITELLM_MODEL_ID="openrouter/google/gemini-2.0-flash-001" +``` + +--- + +### 2. 详细配置选项 + +如果你有特定的需求或自托管服务，可以参考以下详细说明。 + +#### A. 搜索提供商 (Search Provider) + +* **Serper.dev (云端)** + * 注册：[serper.dev](https://serper.dev) + * 配置：`SERPER_API_KEY` +* **SearXNG (开源/自托管)** + * 适用于隐私敏感或拥有自建基础设施的用户。 + * 配置： + ```bash + SEARXNG_INSTANCE_URL='https://your-searxng-instance.com' + # 如果你的实例有鉴权机制 + # SEARXNG_API_KEY='your-api-key' + ``` + +#### B. 重排序方案 (Reranking) + +* **Jina AI (云端)** + * 注册：[jina.ai](https://jina.ai/) + * 配置：`JINA_API_KEY` +* **Infinity (本地/自托管)** + * 部署：[Infinity Embeddings](https://github.com/michaelfeil/infinity) + * 特点：支持本地运行 Qwen2-7B 等高性能开源模型，数据不出域。 + +#### C. LLM 提供商 (LiteLLM) + +ODS 使用 [LiteLLM](https://docs.litellm.ai/docs/providers) 统一调用接口，支持几乎所有主流模型。 + +* **OpenAI / Azure** + ```bash + OPENAI_API_KEY='sk-...' + # 可选：自定义 Base URL (用于代理或兼容接口) + # OPENAI_BASE_URL='https://api.openai.com/v1' + ``` +* **Anthropic (Claude)** + ```bash + ANTHROPIC_API_KEY='sk-ant-...' + ``` +* **Gemini (Google)** + ```bash + GEMINI_API_KEY='AIza...' + ``` + +## 使用指南 🛠️ + +### 作为独立模块使用 🔍 + +你可以在 Python 脚本中直接调用 ODS 进行搜索。 + +```python +from opendeepsearch import OpenDeepSearchTool +import os + +# 确保环境变量已设置，或在代码中设置 +os.environ["SERPER_API_KEY"] = "your-key" +os.environ["JINA_API_KEY"] = "your-key" + +# 初始化工具 +search_agent = OpenDeepSearchTool( + model_name="openrouter/google/gemini-2.0-flash-001", + reranker="jina" +) + +# 确保代理已初始化 +if not search_agent.is_initialized: + search_agent.setup() + +# 执行查询 +query = "猎豹全速跑完亚历山大三世桥需要多长时间？" +result = search_agent.forward(query) +print(result) +``` + +### 运行 Gradio 演示界面 🖥️ + +想要可视化的体验？启动本地 Web 界面： + +```bash +# 基本启动 +python gradio_demo.py + +# 自定义参数启动 +python gradio_demo.py \ + --model-name "openrouter/google/gemini-2.0-flash-001" \ + --reranker "jina" \ + --search-provider "searxng" \ + --searxng-instance "https://your-searxng-instance.com" +``` + +### 与 SmolAgents 集成 🤖 + +这是 ODS 最强大的用法——作为工具赋予 Agent 联网能力。 + +```python +from opendeepsearch import OpenDeepSearchTool +from smolagents import CodeAgent, LiteLLMModel + +# 初始化 ODS 工具 +search_tool = OpenDeepSearchTool( + model_name="openrouter/google/gemini-2.0-flash-001", + reranker="jina" +) + +# 定义模型 +model = LiteLLMModel( + "openrouter/google/gemini-2.0-flash-001", + temperature=0.2 +) + +# 创建 CodeAgent 并注入工具 +code_agent = CodeAgent(tools=[search_tool], model=model) + +# 运行复杂查询 +result = code_agent.run("比较 Python 和 Rust 在 WebAssembly 编译方面的最新进展") +print(result) +``` + +### 构建 ReAct Agent 🧠 + +结合其他工具（如 Wolfram Alpha）构建更强大的推理 Agent。 + +```python +from opendeepsearch import OpenDeepSearchTool +from opendeepsearch.wolfram_tool import WolframAlphaTool +from opendeepsearch.prompts import REACT_PROMPT +from smolagents import ToolCallingAgent, LiteLLMModel + +# 初始化工具 +search_agent = OpenDeepSearchTool(...) +wolfram_tool = WolframAlphaTool(app_id="your-app-id") + +# 创建 ReAct Agent +react_agent = ToolCallingAgent( + tools=[search_agent, wolfram_tool], + model=model, + prompt_templates=REACT_PROMPT +) + +react_agent.run("罗马斗兽场到威尼斯里亚托桥的直线距离是多少米？") +``` + +## 搜索模式详解 🔄 + +| 模式 | 特点 | 适用场景 | 原理 | +|------|------|----------|------| +| **Default Mode (默认)** | ⚡ 极速 | 简单事实查询、快速验证 | 仅使用搜索引擎返回的 Snippets (摘要) 进行回答，无深度爬取。 | +| **Pro Mode (专业)** | 🔍 深度 | 复杂研究、多跳推理、需要精确细节 | 1. 搜索获取链接
2. **Crawl4AI** 爬取完整网页
3. 切分文本并使用 Embedding 进行语义重排序
4. 构建长上下文供 LLM 推理。 | + +## 致谢 💡 + +本项目站在巨人的肩膀上： + +- **[SmolAgents](https://huggingface.co/docs/smolagents/index)** 🤗 – 提供强大的 Agent 框架。 +- **[Crawl4AI](https://github.com/unclecode/crawl4ai)** 🕷️ – 提供高效的异步爬虫支持。 +- **[Infinity Embedding API](https://github.com/michaelfeil/infinity)** 🌍 – 提供高性能的向量嵌入服务。 +- **[LiteLLM](https://www.litellm.ai/)** 🔥 – 统一 LLM 接口调用。 + +## 引用 + +如果您在研究中使用了 OpenDeepSearch，请引用： + +```bibtex +@misc{alzubi2025opendeepsearchdemocratizing, + title={Open Deep Search: Democratizing Search with Open-source Reasoning Agents}, + author={Salaheddin Alzubi and Creston Brooks and Purva Chiniya and Edoardo Contente and Chiara von Gerlach and Lucas Irwin and Yihan Jiang and Arda Kaz and Windsor Nguyen and Sewoong Oh and Himanshu Tyagi and Pramod Viswanath}, + year={2025}, + eprint={2503.20201}, + archivePrefix={arXiv}, + primaryClass={cs.LG}, + url={https://arxiv.org/abs/2503.20201}, +} +``` + +## 联系方式 📩 + +如有问题或合作意向，请提交 Issue 或直接联系维护者。 +