DeepSearcher 是一个开源深度研究工具，它结合了先进的LLM和向量数据库，能够基于私有数据进行搜索、评估和推理，并生成全面的研究报告。

以下是一份详细的部署和使用教程。

📋 部署前准备

  1. 核心依赖:
    • Python: 版本 3.10 或更高。
    • API密钥: 你需要至少一个LLM提供商的API密钥（如OpenAI、DeepSeek等），并将其设置为环境变量。
  2. 推荐工具:
    • uv: 一个更快的Python包管理器，官方推荐用于开发模式安装。

🚀 第一步：安装

DeepSearcher 提供两种安装方式：通过 pip 直接安装，或从源码进行开发模式安装。

方式一：使用 pip 安装 (推荐)

这是最快捷的方式，适合绝大多数用户。

  1. 创建并激活虚拟环境:

    1
    2
    3
    python -m venv .venv
    source .venv/bin/activate  # Linux/macOS
    # .\.venv\Scripts\activate  # Windows

  2. 安装 DeepSearcher:

    1
    pip install deepsearcher
    • 如果需要特定功能（如Ollama支持），可以安装可选依赖：
    1
    pip install "deepsearcher[ollama]"

方式二：开发模式安装 (用于二次开发)

如果你想获取最新代码或进行开发，可以使用此方式。

  1. 克隆仓库:

    1
    2
    git clone https://github.com/zilliztech/deep-searcher.git
    cd deep-searcher

  2. 使用 uv 同步依赖:

    1
    2
    3
    uv sync
    source .venv/bin/activate  # Linux/macOS
    # .\.venv\Scripts\activate  # Windows

⚙️ 第二步：基本配置

DeepSearcher 通过Python代码或 config.yaml 文件进行配置。你需要设置LLM、嵌入模型和向量数据库。

配置LLM

以下是一些常见LLM提供商的配置示例。确保已设置对应的环境变量（如 OPENAI_API_KEY）。

  • OpenAI:

    1
    config.set_provider_config("llm", "OpenAI", {"model": "o1-mini"})

  • DeepSeek (官方):

    1
    config.set_provider_config("llm", "DeepSeek", {"model": "deepseek-reasoner"})

  • Ollama (本地):

    1
    config.set_provider_config("llm", "Ollama", {"model": "qwen3"})

配置嵌入模型 (Embedding)

  • OpenAI Embedding:

    1
    config.set_provider_config("embedding", "OpenAIEmbedding", {"model": "text-embedding-3-small"})

  • Milvus 内置 Embedding:

    1
    config.set_provider_config("embedding", "MilvusEmbedding", {"model": "BAAI/bge-base-en-v1.5"})

配置向量数据库

目前主要支持 Milvus。

  • Milvus Lite (本地文件):

    1
    config.set_provider_config("vector_db", "Milvus", {"uri": "./milvus.db", "token": ""})

  • Milvus 服务器:

    1
    config.set_provider_config("vector_db", "Milvus", {"uri": "http://localhost:19530", "token": ""})

💻 第三步：运行方式

DeepSearcher 提供了 Python 库、命令行界面 (CLI) 和 Web 服务三种使用方式。

方式一：Python 脚本

创建一个 Python 文件，编写如下代码进行数据加载和查询：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
from deepsearcher.configuration import Configuration, init_config
from deepsearcher.online_query import query
from deepsearcher.offline_loading import load_from_local_files

config = Configuration()
# ... 在此处配置你的 LLM、Embedding 和 Vector DB ...
init_config(config=config)

# 1. 加载本地数据
load_from_local_files(paths_or_directory="/path/to/your/local/files")

# 2. 执行查询
result = query("请写一份关于XXX的报告。")
print(result)

方式二：命令行界面 (CLI)

DeepSearcher 也提供了便捷的 CLI 命令。

  • 加载数据:

    1
    2
    3
    4
    5
    # 从本地文件加载
    deepsearcher load "/path/to/your/local/file.pdf"

    # 从网址加载 (需设置 FIRECRAWL_API_KEY)
    deepsearcher load "https://example.com"

  • 查询:

    1
    deepsearcher query "请写一份关于XXX的报告。"

方式三：部署 Web 服务 (FastAPI)

DeepSearcher 可以作为一个 Web 服务运行。

  1. 启动服务:

    1
    python main.py

    服务默认运行在 http://localhost:8000。

  2. 访问 API 文档:
    打开浏览器访问 http://localhost:8000/docs，你可以通过 Swagger UI 直接查看和测试所有 API 接口。

🐳 第四步：使用 Docker 部署 (可选)

项目提供了 Dockerfile 和 docker-compose 支持，方便容器化部署。具体步骤请参阅项目中的 Dockerfile 和相关文档。

📚 数据加载配置

你可以配置不同的文档加载器和网络爬虫来处理数据。

  • 本地文件加载器: 支持 PDFLoader, TextLoader, UnstructuredLoader 等。
  • 网络爬虫: 支持 FireCrawlCrawler（需API Key）、Crawl4AICrawler（本地）、JinaCrawler（需API Key）等。

示例：使用 FireCrawl 加载网页

1
2
config.set_provider_config("web_crawler", "FireCrawlCrawler", {})
# ... 然后调用 load_from_website

❓ 常见问题 (Q&A)

  • LLM输出格式解析失败怎么办？
    小型LLM可能难以遵循指令生成期望格式。建议使用更强大的推理模型，如 deepseek-r1 (671B)、OpenAI o-series 或 Claude 4 Sonnet。

  • 连接 Hugging Face 失败？
    可能是网络问题。可以尝试设置镜像源或配置代理：

    1
    export HF_ENDPOINT=https://hf-mirror.com

  • 在 Jupyter Notebook 中无法运行？
    需要安装 nest_asyncio 并应用补丁：

    1
    pip install nest_asyncio
    1
    2
    import nest_asyncio
    nest_asyncio.apply()

📊 总结

DeepSearcher 提供了一个强大的框架，用于在私有数据上进行深度研究和检索增强生成。建议从 pip 安装和 Python 脚本方式开始，熟悉基本工作流后，再探索 CLI 命令 和 Web 服务部署。对于生产环境，考虑使用 Docker 或配置更健壮的 Milvus 服务器。