DeepSearcher pip 安装指南：从环境准备到首次查询的完整实操

• 人工智能
• 大模型
• RAG
• AI Agent
• 深度研究
• 知识库

DeepSearcher 是一个开源的深度研究（Deep Research）工具，用于在私有数据上执行检索、评估与推理，其核心流程基于 LLM 与向量数据库（如 Milvus）的协同工作。本文以官方 pip 安装方式为主线，覆盖虚拟环境准备、包安装、可选依赖、安装验证与安装后的首次查询配置，并结合仓库源码（pyproject.toml、deepsearcher/cli.py等）说明底层实现，帮助你在不改动源码的前提下，快速搭建一套可用的 DeepSearcher 环境。

适用场景与前置条件

pip 安装方式（pip install deepsearcher）适合大多数希望直接使用 DeepSearcher、无需修改源码的用户。官方文档给出的前置条件如下：

• Python 3.10 或更高版本：这也是项目在 pyproject.toml 中声明的requires-python = ">=3.10"下限；
• pip 包管理器：随 Python 一同安装；
• 虚拟环境工具（推荐使用）：用于隔离项目依赖，避免污染系统 Python 环境。

此外，根据 安装总览 中的系统要求，运行 DeepSearcher 还需要：

• 4GB RAM 以上（推荐 8GB+）；
• 可用的互联网连接：用于下载模型与依赖包（首次安装依赖、拉取 embedding 模型或调用云端 LLM API 时都需要联网）。

说明：本仓库当前pyproject.toml中deepsearcher的版本为0.0.2，本文所有命令与配置均以仓库实际内容为准。

分步安装：创建虚拟环境并安装 DeepSearcher

官方推荐的三步安装流程如下：

第一步：创建虚拟环境

在项目工作目录下执行：

python -m venv .venv

venv是 Python 标准库自带的虚拟环境工具，无需额外安装。创建的.venv目录将包含独立的 Python 解释器与包目录，后续安装的依赖全部落在该目录内。

第二步：激活虚拟环境

不同操作系统的激活命令不同：

=== "Linux/macOS"bash source .venv/bin/activate

=== "Windows"bash .venv\Scripts\activate

激活成功后，终端提示符前会出现(.venv)前缀，表明当前 shell 正在使用虚拟环境中的 Python 与 pip。

第三步：安装 DeepSearcher

pip install deepsearcher

该命令会从 PyPI 拉取deepsearcher包及其核心依赖。根据 pyproject.toml 的dependencies声明，核心依赖至少包括：

• fastapi/uvicorn：提供 HTTP 服务能力；
• openai：OpenAI 兼容接口的 LLM 调用基础；
• pymilvus：Milvus 向量数据库客户端（默认向量库）；
• pdfplumber、langchain-text-splitters、numpy、requests、termcolor、tqdm、argparse、firecrawl-py、ibm-watsonx-ai等。

安装完成后，deepsearcher命令即被注册到虚拟环境的bin/Scripts目录下——这是由 pyproject.toml 中的入口点声明deepsearcher = "deepsearcher.cli:main"决定的，意味着你可以直接使用deepsearcherCLI 工具。

可选依赖：按集成场景按需安装

DeepSearcher 通过可选的extras支持多种第三方集成。官方文档给出的两种安装方式为：

实际上，仓库在 pyproject.toml 中声明了远不止这两个 extras。除ollama（依赖ollama>=0.4.8）外，还包括：

• voyageai：VoyageAI 向量模型（VoyageEmbedding）；
• anthropic：Claude 系列 LLM；
• google：Gemini LLM 与GeminiEmbedding（google-genai）；
• unstructured：非结构化文档加载（unstructured-ingest、unstructured[all-docs]）；
• zhipuai：智谱 GLM LLM 与 Embedding；
• oracledb：Oracle 向量数据库（对应deepsearcher/vector_db/oracle.py）；
• azure-search：Azure AI Search 向量库（对应deepsearcher/vector_db/azure_search.py）；
• boto3：Amazon Bedrock LLM 与 Embedding；
• together：Together AI LLM；
• qdrant：Qdrant 向量库 + FastEmbed（qdrant-client、fastembed）；
• docling：Docling 文档解析（Loader 与 Crawler）；
• crawl4ai：Crawl4AI 网页爬虫；
• sentence-transformers：本地 Sentence-Transformer Embedding；
• ibm-watsonx：IBM watsonx.ai LLM 与 Embedding。

安装建议：如果你是首次体验，可先安装核心包并准备一个 OpenAI 兼容的 API Key；当需要使用某个具体集成时，再按需安装对应的 extras，例如pip install "deepsearcher[qdrant]"或pip install "deepsearcher[docling]"，避免一次性引入过多重型依赖。

验证安装：三种检查方式

方式一：Python 版本号检查（官方示例）

官方文档提供了最直接的验证方式：

# Simple verification from deepsearcher import __version__ print(f"DeepSearcher version: {__version__}")

该脚本会打印当前安装的 DeepSearcher 版本号（本仓库对应0.0.2），打印成功即说明包已正确导入。

方式二：CLI 入口验证

由于 pip 安装后注册了deepsearcher命令行入口，可以直接运行：

deepsearcher --help

从 deepsearcher/cli.py 的源码可以看出，CLI 提供了query与load两个子命令：

• deepsearcher query <your_query> --max_iter 3：对已加载的知识库发起查询，--max_iter控制反思迭代次数，默认 3；
• deepsearcher load <your_local_path_or_url> --collection_name <name> --collection_desc <desc>：从本地文件或网页 URL 加载知识，相关参数还包括--batch_size（默认 256）、--force_new_collection等。

如果你看到[Deprecated]提示，说明使用了旧的--query/--load参数格式，请按提示改用新的子命令格式。

方式三：初始化配置检查

安装总览 还给出了一种结合配置对象的验证方式：

from deepsearcher.configuration import Configuration from deepsearcher.online_query import query # Initialize with default configuration config = Configuration() print("DeepSearcher installed successfully!")

Configuration()会读取包内自带的 deepsearcher/config.yaml 默认配置，其构造函数逻辑位于 deepsearcher/configuration.py（load_config_from_yaml负责解析 YAML，并初始化provide_settings、query_settings、load_settings三组配置）。能顺利构建配置对象，说明依赖与配置文件均就位。

安装之后：快速完成首次查询

1. 准备 API Key 与模型配置

DeepSearcher 默认使用 OpenAI 的 LLM（o1-mini）与 Embedding 模型（text-embedding-ada-002），因此最简单的方式是先在环境变量中设置OPENAI_API_KEY。默认配置见 deepsearcher/config.yaml：

provide_settings: llm: provider: "OpenAI" config: model: "o1-mini" embedding: provider: "OpenAIEmbedding" config: model: "text-embedding-ada-002"

如果你希望使用 DeepSeek、SiliconFlow、Ollama、Gemini 等其它提供商，有两种途径：

• 修改配置文件：编辑deepsearcher/config.yaml，取消对应 provider 的注释；
• 代码中覆盖：调用config.set_provider_config(...)（详见 README 快速开始 与 LLM 配置文档、Embedding 配置文档）。

以代码覆盖为例：

config.set_provider_config("llm", "OpenAI", {"model": "o1-mini"}) config.set_provider_config("embedding", "OpenAIEmbedding", {"model": "text-embedding-ada-002"}) init_config(config=config)

init_config会通过ModuleFactory创建 LLM、Embedding、文件加载器、网页爬虫与向量库实例，并组装RAGRouter（内置DeepSearch与ChainOfRAG两个 agent）以及NaiveRAG，其实现同样位于 deepsearcher/configuration.py。

2. 加载私有数据

加载本地文件：

from deepsearcher.offline_loading import load_from_local_files load_from_local_files(paths_or_directory=your_local_path)

加载网页内容（需要FIRECRAWL_API_KEY环境变量，默认爬虫为FireCrawlCrawler）：

from deepsearcher.offline_loading import load_from_website load_from_website(urls=website_url)

更完整的可运行示例可参考 examples/basic_example.py。

3. 发起查询

result = query("Write a report about xxx.")

query函数定义在 deepsearcher/online_query.py，它会调用default_searcher.query(original_query, max_iter=3)并返回答案、引用列表与消耗的 token 数。如果你只想做检索而不生成答案，也可以使用同文件中的retrieve()、naive_retrieve()、naive_rag_query()等接口。

与开发模式安装的对比与选型

官方提供两种安装路径（见 安装总览）：

详细步骤见 开发模式安装文档。对绝大多数使用场景而言，本文的 pip 方式已经足够；只有当你想为 DeepSearcher 贡献代码或深度定制内部模块时，才建议切换为开发模式。

常见问题与排查思路

• python -m venv .venv失败：确认 Python 版本 ≥ 3.10（python --version），并检查系统是否安装了python3-venv相关组件。
• pip install deepsearcher下载缓慢或超时：可换用国内 PyPI 镜像源，例如pip install deepsearcher -i https://pypi.tuna.tsinghua.edu.cn/simple；同时确保网络可以访问 PyPI。
• deepsearcher命令找不到：多半是虚拟环境未激活，或安装到了其它 Python 环境；重新执行source .venv/bin/activate（Windows 为.venv\Scripts\activate）后再试。
• 首次查询报错 / 无结果：优先检查 LLM 与 Embedding 的 API Key 环境变量是否就位、模型名是否与所选提供商匹配，以及向量库默认配置（deepsearcher/config.yaml 中vector_db默认使用 Milvus，uri: "./milvus.db"，即以本地文件模式运行，无需额外部署 Milvus 服务）。
• 内存不足：官方建议 4GB RAM 起步、8GB+ 更佳；若本地 embedding 模型体积较大，可改用 API 型 embedding（如 OpenAIEmbedding）以降低内存占用。

小结

通过本文，你可以用三条命令（创建虚拟环境 → 激活 →pip install deepsearcher）完成 DeepSearcher 的安装，再结合可选 extras 按需扩展 Ollama、Qdrant、Docling 等集成能力。安装后既可以通过deepsearcher query/deepsearcher load命令行快速体验，也可以基于Configuration+init_config+query的 Python API 编写定制化查询脚本，让 DeepSearcher 在私有数据上真正跑起来。

• 人工智能
• 大模型
• RAG
• AI Agent
• 深度研究
• 知识库