🔍OpenDeepSearch：通过开源推理模型和推理代理 democratize 搜索 🚀

• 描述 📝
• 目录 📑
• 特性 ✨
• 安装 📚
• 设置
• 使用 ️
  • 独立使用 OpenDeepSearch 🔍
  • 运行 Gradio 演示 🖥️
  • 与 SmolAgents 和 LiteLLM 集成 🤖⚙️
  • 带有数学和搜索工具的 ReAct 代理 🤖⚙️
• 搜索模式 🔄
  • 默认模式 ⚡
  • 专业模式 🔍
• 致谢 💡
• 引用
• 联系方式 📩

特性 ✨

• 语义搜索 🧠：利用 Crawl4AI 和语义搜索重排序器（如 Qwen2-7B-instruct 和 Jina AI），提供深入的结果
• 两种运行模式 ⚡：
  • 默认模式：快速高效的搜索，延迟极低。
  • 专业模式（深度搜索）：以额外的处理时间为代价，获得更深入、更准确的结果。
• 专为 AI 代理优化 🤖：可与 CodeAgent 等 SmolAgents 无缝协作。
• 快速轻量 ⚡：设计注重速度与效率，设置简单。
• 可扩展 🔌：易于配置，可与不同模型和 API 配合使用。

安装 📚

要安装 OpenDeepSearch，请运行：

pip install -e . #你也可以使用：uv pip install -e .
pip install -r requirements.txt #你也可以使用：uv pip install -r requirements.txt

注意：必须安装 torch。 注意：使用 uv 而不是普通的 pip 会让操作更加轻松！

使用 PDM（替代包管理器）📦

你也可以使用 PDM 作为 OpenDeepSearch 的替代包管理器。PDM 是一个现代化的 Python 包和依赖项管理器，支持最新的 PEP 标准。

# 如果尚未安装 PDM，请先安装
curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 -

# 初始化一个新的 PDM 项目
pdm init

# 安装 OpenDeepSearch 及其依赖项
pdm install

# 激活虚拟环境
eval "$(pdm venv activate)"

PDM 具有以下优势：

• 锁文件支持，实现可重复的安装
• 支持 PEP 582（无需虚拟环境）
• 快速的依赖解析
• 内置虚拟环境管理

设置

1. 选择搜索提供商：

   • 选项 1：Serper.dev：获取 免费 2500 积分，并添加你的 API 密钥。

     • 访问 serper.dev 创建账户。
     • 获取你的 API 密钥，并将其存储为环境变量：

     export SERPER_API_KEY='your-api-key-here'
     

   • 选项 2：SearXNG：使用自托管或公共 SearXNG 实例。

     • 在初始化 OpenDeepSearch 时指定 SearXNG 实例的 URL。
     • 如果你的实例需要认证，可选择提供 API 密钥：

     export SEARXNG_INSTANCE_URL='https://your-searxng-instance.com'
     export SEARXNG_API_KEY='your-api-key-here'  # 可选
     

2. 选择重排序解决方案：

   • 快速开始使用 Jina：在 Jina AI 注册以获取立即可用的 API 密钥
   • 自托管选项：在本地设置 Infinity Embeddings 服务器，使用开源模型，例如 Qwen2-7B-instruct
   • 更多关于重排序选项的详细信息，请参阅我们的 重排序指南

3. 设置 LiteLLM 提供商：

   • 从 支持列表 中选择一个提供商，包括：
     • OpenAI
     • Anthropic
     • Google (Gemini)
     • OpenRouter
     • HuggingFace
     • Fireworks
     • 以及更多！
   • 将你选择的提供商的 API 密钥设置为环境变量：

   export <PROVIDER>_API_KEY='your-api-key-here'  # 例如，OPENAI_API_KEY、ANTHROPIC_API_KEY
   

   • 对于 OpenAI，你还可以设置自定义的基础 URL（适用于自托管端点或代理）：

   export OPENAI_BASE_URL='https://your-custom-openai-endpoint.com'
   

   • 你可以为不同任务设置默认的 LiteLLM 模型 ID：

   # 通用默认模型（所有任务的回退）
   export LITELLM_MODEL_ID='openrouter/google/gemini-2.0-flash-001'
   
   # 任务特定模型
   export LITELLM_SEARCH_MODEL_ID='openrouter/google/gemini-2.0-flash-001'  # 用于搜索任务
   export LITELLM_ORCHESTRATOR_MODEL_ID='openrouter/google/gemini-2.0-flash-001'  # 用于代理编排
   export LITELLM_EVAL_MODEL_ID='gpt-4o-mini'  # 用于评估任务
   

   • 在初始化 OpenDeepSearch 时，你可以使用提供商的格式指定你选择的模型（这将覆盖环境变量）：

   search_agent = OpenDeepSearchTool(model_name="provider/model-name")  # 例如，“anthropic/claude-3-opus-20240229”、“huggingface/microsoft/codebert-base”、“openrouter/google/gemini-2.0-flash-001”
   

使用 ️

你可以独立使用 OpenDeepSearch，也可以将其与 SmolAgents 集成，以增强推理和代码生成能力。

独立使用 OpenDeepSearch 🔍

from opendeepsearch import OpenDeepSearchTool
import os

# 设置 API 密钥的环境变量
os.environ["SERPER_API_KEY"] = "your-serper-api-key-here"  # 如果使用 Serper
# 或者对于 SearXNG
# os.environ["SEARXNG_INSTANCE_URL"] = "https://your-searxng-instance.com"
# os.environ["SEARXNG_API_KEY"] = "your-api-key-here"  # 可选

os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key-here"
os.environ["JINA_API_KEY"] = "your-jina-api-key-here"

# 使用 Serper（默认）
search_agent = OpenDeepSearchTool(
    model_name="openrouter/google/gemini-2.0-flash-001",
    reranker="jina"
)

# 或者使用 SearXNG
# search_agent = OpenDeepSearchTool(
#     model_name="openrouter/google/gemini-2.0-flash-001",
#     reranker="jina",
#     search_provider="searxng",
#     searxng_instance_url="https://your-searxng-instance.com",
#     searxng_api_key="your-api-key-here"  # 可选
# )

if not search_agent.is_initialized:
    search_agent.setup()
    
query = "最快的陆地动物是什么？"
result = search_agent.forward(query)
print(result)

运行 Gradio 演示 🖥️

要通过友好的用户界面体验 OpenDeepSearch，只需运行以下命令：

python gradio_demo.py

这将启动一个本地 Web 界面，您可以在其中交互式地测试不同的搜索查询和模式。

您可以通过命令行参数自定义演示：

# 使用 Serper（默认）
python gradio_demo.py --model-name "openrouter/google/gemini-2.0-flash-001" --reranker "jina"

# 使用 SearXNG
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" \
  --searxng-api-key "your-api-key-here"  # 可选

可用选项：

• --model-name: 用于搜索的 LLM 模型
• --orchestrator-model: 用于代理编排器的 LLM 模型
• --reranker: 要使用的重排序器（jina 或 infinity）
• --search-provider: 要使用的搜索引擎（serper 或 searxng）
• --searxng-instance: SearXNG 实例 URL（使用 searxng 时必填）
• --searxng-api-key: SearXNG API 密钥（可选）
• --serper-api-key: Serper API 密钥（可选，未提供时将使用环境变量）
• --openai-base-url: OpenAI API 基础 URL（可选，未提供时将使用 OPENAI_BASE_URL 环境变量）

与 SmolAgents 和 LiteLLM 集成 🤖⚙️

from opendeepsearch import OpenDeepSearchTool
from smolagents import CodeAgent, LiteLLMModel
import os

# 设置 API 密钥环境变量
os.environ["SERPER_API_KEY"] = "your-serper-api-key-here"  # 如果使用 Serper
# 或对于 SearXNG
# os.environ["SEARXNG_INSTANCE_URL"] = "https://your-searxng-instance.com"
# os.environ["SEARXNG_API_KEY"] = "your-api-key-here"  # 可选

os.environ["OPENROUTER_API_KEY"] = "your-openrouter-api-key-here"
os.environ["JINA_API_KEY"] = "your-jina-api-key-here"

# 使用 Serper（默认）
search_agent = OpenDeepSearchTool(
    model_name="openrouter/google/gemini-2.0-flash-001",
    reranker="jina"
)

# 或者使用 SearXNG
# search_agent = OpenDeepSearchTool(
#     model_name="openrouter/google/gemini-2.0-flash-001",
#     reranker="jina",
#     search_provider="searxng",
#     searxng_instance_url="https://your-searxng-instance.com",
#     searxng_api_key="your-api-key-here"  # 可选
# )

model = LiteLLMModel(
    "openrouter/google/gemini-2.0-flash-001",
    temperature=0.2
)

code_agent = CodeAgent(tools=[search_agent], model=model)
query = "猎豹以全速奔跑，需要多长时间才能跑完亚历山大三世桥的长度？"
result = code_agent.run(query)

print(result)

带有数学和搜索工具的 ReAct 代理 🤖⚙️

from opendeepsearch import OpenDeepSearchTool
from opendeepsearch.wolfram_tool import WolframAlphaTool
from opendeepsearch.prompts import REACT_PROMPT
from smolagents import LiteLLMModel, ToolCallingAgent, Tool
import os

# 设置 API 密钥环境变量
os.environ["SERPER_API_KEY"] = "your-serper-api-key-here"
os.environ["JINA_API_KEY"] = "your-jina-api-key-here"
os.environ["WOLFRAM_ALPHA_APP_ID"] = "your-wolfram-alpha-app-id-here"
os.environ["FIREWORKS_API_KEY"] = "your-fireworks-api-key-here"

model = LiteLLMModel(
    "fireworks_ai/llama-v3p1-70b-instruct",  # 您的 Fireworks Deepseek 模型
    temperature=0.7
)
search_agent = OpenDeepSearchTool(model_name="fireworks_ai/llama-v3p1-70b-instruct", reranker="jina") # 将重排序器设置为“jina”或“infinity”

# 初始化 Wolfram Alpha 工具
wolfram_tool = WolframAlphaTool(app_id=os.environ["WOLFRAM_ALPHA_APP_ID"])

# 使用搜索和 Wolfram 工具初始化 React 代理
react_agent = ToolCallingAgent(
    tools=[search_agent, wolfram_tool],
    model=model,
    prompt_templates=REACT_PROMPT # 使用 REACT_PROMPT 作为系统提示
)

# React 代理的示例查询
query = "罗马斗兽场与威尼斯里亚托桥之间的距离是多少米？"
result = react_agent.run(query)

print(result)

搜索模式 🔄

OpenDeepSearch 提供两种不同的搜索模式，以在速度和深度之间取得平衡：

默认模式 ⚡

• 使用基于 SERP 的交互快速获取结果
• 处理开销最小
• 适用于单跳、简单的查询
• 响应时间快
• 非常适合基础信息检索

专业模式 🔍

• 包含全面的网页抓取
• 实现结果的语义重排序
• 包括数据的高级后处理
• 处理时间稍长
• 在以下方面表现出色：
  • 多跳查询
  • 复杂的搜索需求
  • 详细的信息收集
  • 需要交叉验证的问题

致谢 💡

OpenDeepSearch 建立在众多优秀的开源项目之上：

• SmolAgents 🤗 – 提供代理框架和推理能力。
• Crawl4AI 🕷️ – 提供数据爬取支持。
• Infinity Embedding API 🌍 – 提供语义搜索功能。
• LiteLLM 🔥 – 用于高效的 AI 模型集成。
• 各种开源库 📚 – 增强搜索和检索功能。

引用

如果您在工作中使用了 OpenDeepSearch，请使用以下 BibTex 条目进行引用：

@misc{alzubi2025opendeepsearchdemocratizing,
      title={Open Deep Search: 以开源推理代理民主化搜索},
      author={Salaheddin Alzubi 和 Creston Brooks 和 Purva Chiniya 和 Edoardo Contente 和 Chiara von Gerlach 和 Lucas Irwin 和 Yihan Jiang 和 Arda Kaz 和 Windsor Nguyen 和 Sewoong Oh 和 Himanshu Tyagi 和 Pramod Viswanath},
      year={2025},
      eprint={2503.20201},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2503.20201},
}

联系方式 📩

如有任何问题或合作意向，请提交 issue 或直接联系维护人员。

uv pip install -e .
uv pip install -r requirements.txt

pip install -e .
pip install -r requirements.txt

# 安装 PDM
curl -sSL https://raw.githubusercontent.com/pdm-project/pdm/main/install-pdm.py | python3 -

# 初始化项目并安装依赖
pdm init
pdm install

# 激活虚拟环境
eval "$(pdm venv activate)"

export OPENAI_API_KEY='your-api-key-here'
# 或者
export ANTHROPIC_API_KEY='your-api-key-here'

# 通用默认模型
export LITELLM_MODEL_ID='openrouter/google/gemini-2.0-flash-001'

# 针对搜索任务的模型
export LITELLM_SEARCH_MODEL_ID='openrouter/google/gemini-2.0-flash-001'

from opendeepsearch import OpenDeepSearchTool
import os

# 确保环境变量已设置 (如果在终端未设置，也可在此处代码中设置)
# os.environ["SERPER_API_KEY"] = "your-api-key"
# os.environ["OPENAI_API_KEY"] = "your-api-key"

# 初始化工具
# model_name 格式为 "provider/model-name"，例如 "openai/gpt-4o" 或 "anthropic/claude-3-opus-20240229"
search_agent = OpenDeepSearchTool(model_name="openai/gpt-4o-mini")

# 执行搜索查询
query = "2024 年诺贝尔物理学奖得主是谁？"
results = search_agent.run(query)

print(results)

python app.py