本地深度研究员

本地深度研究员是一个完全本地化的网络研究助手，它可以使用由 Ollama 或 LMStudio 托管的任何大语言模型。只需提供一个主题，它就会生成网络搜索查询、收集搜索结果、总结这些结果，并基于总结反思以发现知识空白，进而生成新的搜索查询来填补这些空白，如此循环往复，直至达到用户设定的次数。最后，它会向用户提供一份包含所有引用来源的 Markdown 格式总结。

简短总结视频：

🔥 更新

• 2025年8月6日：新增对工具调用和 gpt-oss 的支持。

⚠️ 警告（2025年8月6日）：gpt-oss 模型在 Ollama 中不支持 JSON 模式。请在配置中选择 use_tool_calling 来使用工具调用功能，而非 JSON 模式。

📺 视频教程

想亲眼见证它的运行，还是自己动手搭建？请查看以下实用视频教程：

• 使用 R1 的本地深度研究员概览 - 加载并测试 DeepSeek R1 蒸馏模型。
• 从零开始构建本地深度研究员 - 介绍其构建过程。

🚀 快速入门

克隆仓库：

git clone https://github.com/langchain-ai/local-deep-researcher.git
cd local-deep-researcher

然后编辑 .env 文件，根据您的需求自定义环境变量。这些环境变量控制模型选择、搜索工具及其他配置设置。运行应用程序时，这些值将通过 python-dotenv 自动加载（因为 langgraph.json 指向“env”文件）。

cp .env.example .env

使用 Ollama 选择本地模型

1. 在 这里 下载适用于 Mac 的 Ollama 应用程序。

2. 从 Ollama 拉取本地大语言模型。例如 deepseek-r1:8b：

ollama pull deepseek-r1:8b

3. 您还可以选择性地更新 .env 文件，添加以下 Ollama 配置设置。

• 如果设置了这些值，它们将优先于 configuration.py 中 Configuration 类的默认值。

LLM_PROVIDER=ollama
OLLAMA_BASE_URL="http://localhost:11434" # Ollama 服务端点，默认为 `http://localhost:11434`
LOCAL_LLM=model # 要使用的模型，默认为 `llama3.2`，若未设置则使用此默认值

使用 LMStudio 选择本地模型

1. 从 这里 下载并安装 LMStudio。

2. 在 LMStudio 中：

   • 下载并加载您偏好的模型（如 qwen_qwq-32b）
   • 切换到“本地服务器”选项卡
   • 启动兼容 OpenAI API 的服务器
   • 记下服务器 URL（默认：http://localhost:1234/v1）

3. 您还可以选择性地更新 .env 文件，添加以下 LMStudio 配置设置。

• 如果设置了这些值，它们将优先于 configuration.py 中 Configuration 类的默认值。

LLM_PROVIDER=lmstudio
LOCAL_LLM=qwen_qwq-32b  # 使用与 LMStudio 中显示的模型名称完全一致的名称
LMSTUDIO_BASE_URL=http://localhost:1234/v1

选择搜索工具

默认情况下，它会使用无需 API 密钥的 DuckDuckGo 进行网络搜索。但您也可以通过在环境文件中添加 API 密钥来使用 SearXNG、Tavily 或 Perplexity。您可以选择性地更新 .env 文件，添加以下搜索工具配置及 API 密钥。如果设置了这些值，它们将优先于 configuration.py 中 Configuration 类的默认值。

SEARCH_API=xxx # 要使用的搜索 API，例如 `duckduckgo`（默认）
TAVILY_API_KEY=xxx # 要使用的 Tavily API 密钥
PERPLEXITY_API_KEY=xxx # 要使用的 Perplexity API 密钥
MAX_WEB_RESEARCH_LOOPS=xxx # 最大研究循环次数，默认为 `3`
FETCH_FULL_PAGE=xxx # 是否获取完整页面内容（仅限 DuckDuckGo），默认为 `false`

使用 LangGraph Studio 运行

Mac

1. （推荐）创建虚拟环境：

python -m venv .venv
source .venv/bin/activate

2. 启动 LangGraph 服务器：

# 安装 uv 包管理器
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.11 langgraph dev

Windows

1. （推荐）创建虚拟环境：

• 安装 Python 3.11（并在安装过程中将其添加到 PATH）。
• 重启终端以确保 Python 可用，然后创建并激活虚拟环境：

python -m venv .venv
.venv\Scripts\Activate.ps1

2. 启动 LangGraph 服务器：

# 安装依赖
pip install -e .
pip install -U "langgraph-cli[inmem]"            

# 启动 LangGraph 服务器
langgraph dev

使用 LangGraph Studio 界面

当您启动 LangGraph 服务器时，应该会看到以下输出，并且 Studio 将在您的浏览器中打开：

准备就绪！

API：http://127.0.0.1:2024

文档：http://127.0.0.1:2024/docs

LangGraph Studio Web UI：https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

通过上述 URL 打开 LangGraph Studio Web UI。在“配置”选项卡中，您可以直接设置各种助手配置。请注意，配置值的优先级顺序如下：

1. 环境变量（最高优先级）
2. LangGraph UI 配置
3. Configuration 类中的默认值（最低优先级）

为助手提供一个研究主题，您就可以直观地看到它的整个流程！

关于模型兼容性的说明

在选择本地大语言模型时，请确保其能够生成结构化的 JSON 输出。然而，某些模型可能难以满足这一要求，此时助手会启用后备机制来处理这种情况。例如，DeepSeek R1 (7B) 和 DeepSeek R1 (1.5B) 模型就难以生成所需的 JSON 输出，助手会自动切换到后备模式进行处理。

浏览器兼容性说明

访问 LangGraph Studio UI 时：

• 建议使用 Firefox 以获得最佳体验
• Safari 用户可能会因混合内容（HTTPS/HTTP）而遇到安全警告
• 如果遇到问题，请尝试：
  1. 使用 Firefox 或其他浏览器
  2. 禁用广告拦截扩展程序
  3. 检查浏览器控制台以获取具体的错误信息

工作原理

Local Deep Researcher 的灵感来源于 IterDRAG。该方法会将一个问题分解为多个子问题，分别为每个子问题检索文档、回答子问题，然后基于回答结果再检索第二个子问题的相关文档。我们的实现与此类似：

• 给定用户提供的主题，使用本地 LLM（通过 Ollama 或 LMStudio）生成网络搜索查询
• 利用搜索引擎或工具查找相关资料
• 使用 LLM 对与用户研究主题相关的网络搜索结果进行总结
• 随后，LLM 会对总结内容进行反思，识别知识空白
• 生成新的搜索查询以填补这些知识空白
• 重复上述过程，每次都会用网络搜索的新信息更新总结内容
• 整个流程可配置迭代次数（请参阅“configuration”选项卡）

输出

图的输出是一个包含研究摘要的 Markdown 文件，并附有引用来源的标注。在研究过程中收集的所有资料都会保存到图的状态中。您可以在 LangGraph Studio 中查看这些资料：

最终的摘要也会保存到图的状态中：

部署选项

部署此图的方式有多种 途径。有关使用 LangGraph 部署的详细步骤，请参阅 LangChain Academy 的 第 6 模块。

TypeScript 实现

该项目的 TypeScript 版本（不含 Perplexity 搜索）可在以下地址找到： https://github.com/PacoVK/ollama-deep-researcher-ts

作为 Docker 容器运行

随附的 Dockerfile 只会运行带有 local-deep-researcher 服务的 LangChain Studio，但并未将 Ollama 作为依赖服务包含在内。您需要单独运行 Ollama，并配置 OLLAMA_BASE_URL 环境变量。此外，您还可以通过设置 LOCAL_LLM 环境变量来指定要使用的 Ollama 模型。

克隆仓库并构建镜像：

$ docker build -t local-deep-researcher .

运行容器：

$ docker run --rm -it -p 2024:2024 \
  -e SEARCH_API="tavily" \ 
  -e TAVILY_API_KEY="tvly-***YOUR_KEY_HERE***" \
  -e LLM_PROVIDER=ollama \
  -e OLLAMA_BASE_URL="http://host.docker.internal:11434/" \
  -e LOCAL_LLM="llama3.2" \  
  local-deep-researcher

注意：您会看到如下日志信息：

2025-02-10T13:45:04.784915Z [info     ] 🎨 Opening Studio in your browser... [browser_opener] api_variant=local_dev message=🎨 Opening Studio in your browser...
URL: https://smith.langchain.com/studio/?baseUrl=http://0.0.0.0:2024

…但浏览器并不会从容器中自动打开。

相反，请使用正确的 baseUrl IP 地址访问以下链接：https://smith.langchain.com/studio/thread?baseUrl=http://127.0.0.1:2024

Local Deep Researcher 快速上手指南

Local Deep Researcher 是一个完全本地化的网络研究助手。它利用本地部署的大语言模型（通过 Ollama 或 LMStudio），自动执行“生成搜索查询 -> 获取结果 -> 总结 -> 反思知识缺口 -> 再次搜索”的循环过程，最终生成带有引用来源的 Markdown 研究报告。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统: macOS, Windows, 或 Linux
• Python: 推荐版本 3.11 (必须添加到系统 PATH)
• 本地大模型服务 (二选一):
  • Ollama: 下载地址 (国内用户若下载缓慢，可尝试社区镜像或手动导入模型文件)
  • LMStudio: 下载地址
• 包管理器:
  • macOS/Linux: curl (用于安装 uv)
  • Windows: pip

安装步骤

1. 克隆项目并配置环境变量

git clone https://github.com/langchain-ai/local-deep-researcher.git
cd local-deep-researcher
cp .env.example .env

编辑 .env 文件，根据您的本地环境调整配置（详见下文模型选择部分）。

2. 准备本地大模型

方案 A：使用 Ollama (推荐)

1. 安装 Ollama 后，在终端拉取一个模型（例如 DeepSeek-R1 或 Llama3.2）：

   ollama pull deepseek-r1:8b
   

2. 在 .env 文件中配置：

   LLM_PROVIDER=ollama
   OLLAMA_BASE_URL="http://localhost:11434"
   LOCAL_LLM=deepseek-r1:8b
   

   注意: 如果使用 gpt-oss 等不支持 JSON 模式的模型，请在配置中启用 use_tool_calling。

方案 B：使用 LMStudio

1. 在 LMStudio 中下载并加载模型。
2. 进入 "Local Server" 标签页，启动服务器 (默认端口 1234)。
3. 在 .env 文件中配置：

   LLM_PROVIDER=lmstudio
   LOCAL_LLM=qwen_qwq-32b
   LMSTUDIO_BASE_URL=http://localhost:1234/v1
   

3. 配置搜索工具

默认使用 DuckDuckGo (无需 API Key)。如需更高精度，可在 .env 中配置 Tavily 或 Perplexity 的 API Key：

SEARCH_API=duckduckgo
# 或者使用付费服务
# SEARCH_API=tavily
# TAVILY_API_KEY=your_key_here
MAX_WEB_RESEARCH_LOOPS=3

4. 启动服务

macOS / Linux 用户

推荐使用 uv 管理环境并启动 LangGraph 开发服务器：

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate

# 安装 uv 并启动服务
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.11 langgraph dev

Windows 用户

# 创建并激活虚拟环境
python -m venv .venv
.venv\Scripts\Activate.ps1

# 安装依赖
pip install -e .
pip install -U "langgraph-cli[inmem]"

# 启动服务
langgraph dev

基本使用

启动成功后，终端将显示类似以下信息：

LangGraph Studio Web UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

1. 打开界面: 点击上述 URL 或在浏览器中访问该地址。
   • 建议: 优先使用 Firefox 浏览器以获得最佳兼容性。Safari 用户可能会遇到混合内容安全警告。
2. 配置参数: 在界面的 configuration 标签页中，您可以直接覆盖 .env 中的设置（优先级：环境变量 > UI 配置 > 代码默认值）。
3. 开始研究:
   • 在输入框中输入您的研究主题（例如："2024 年人工智能在医疗领域的最新进展"）。
   • 点击运行，系统将自动可视化展示思考、搜索、总结和反思的全过程。
4. 获取结果:
   • 研究完成后，您可以在右侧面板查看最终的 Markdown 总结报告。
   • 所有引用的源链接和中间状态均可在 Graph State 中查看。

---

提示：部分小型模型可能在生成结构化 JSON 输出时不稳定，若遇到错误，系统会自动尝试回退机制，或建议更换参数量更大的模型（如 8B 以上）。