learningcircuit--local-deep-research/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Local Deep Research

由 AI 驱动的深度智能体（agentic）研究助手

使用多种 LLM 与搜索引擎进行深度智能体研究，并提供规范引用

🧪 首个在单张 RTX 3090（Qwen3.6-27B）上完全本地运行、在本地硬件上报出约 95% SimpleQA（n=500）与 77% xbench-DeepSearch（n=100）的开源项目。 参见 r/LocalLLaMA 公告 与 基准数据集.

▶️ 观看 The Art Of The Terminal 评测

🚀 什么是 Local Deep Research？

由你掌控的 AI 研究助手。本地运行以保护隐私，可使用任意 LLM，并构建你自己的可搜索知识库。数据归你所有，工作原理完全透明。

⚡ 快速开始

选项 1：Docker Run（Linux）

# Step 1: Pull and run Ollama
docker run -d -p 11434:11434 --name ollama ollama/ollama
docker exec ollama ollama pull gpt-oss:20b

# Step 2: Pull and run SearXNG for optimal search results
docker run -d -p 8080:8080 --name searxng searxng/searxng

# Step 3: Pull and run Local Deep Research
docker run -d --network host \
  --name local-deep-research \
  --volume "deep-research:/data" \
  -e LDR_DATA_DIR=/data \
  localdeepresearch/local-deep-research

Mac / Windows / WSL2 用户： --network host 仅在原生 Linux 上可用。在 Docker Desktop 上，它会静默失败，无法发布 5000 端口，并且会使 localhost 指向 LDR 容器自身（因而无法访问 Ollama/SearXNG）。请使用下方的 选项 2，或参阅 Windows/WSL2 常见问题 获取可用的 docker run 方案。

选项 2：Docker Compose

仅 CPU（全平台）：

curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && docker compose up -d

使用 NVIDIA GPU（Linux）：

curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml && \
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.gpu.override.yml && \
docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d

约 30 秒后打开 http://localhost:5000。GPU 配置、环境变量等详见 Docker Compose 指南。

选项 3：pip install

pip install local-deep-research
python -m local_deep_research.web.app   # starts the web UI on http://localhost:5000

你还需要运行 Ollama（或任何兼容 OpenAI 的 LLM 端点）和 SearXNG — 完整步骤见 pip 安装指南。 支持 Windows、macOS 和 Linux。SQLCipher 加密通过预编译 wheel 提供 — 无需编译。 Windows 上导出 PDF 需要 Pango（配置指南). 若遇到加密相关问题，可将 export LDR_BOOTSTRAP_ALLOW_UNENCRYPTED=true 设为使用标准 SQLite。

详细安装指南： Docker · Docker Compose · pip · Unraid · 完整安装参考

较旧的 CPU（x86-64）？ LDR 需要支持 AVX 的 CPU — Intel Sandy Bridge / AMD Bulldozer（2011）或更新型号。部分科学 Python 依赖（pandas、scikit-learn）提供的 wheel 在较旧 CPU 上会因 Illegal instruction 而崩溃。ARM64（aarch64）完全支持。每个发行版都会针对这一下限进行冒烟测试，包括仅 AVX、无 AVX2 的 CPU（#4480).

🏗️ 工作原理

研究

你提出一个复杂问题。Local Deep Research（LDR）会：

• 自动替你完成研究
• 在网页、学术论文与你自己的文档中搜索
• 将所有内容综合成附带规范引用的报告

选择适合的研究策略：快速 pipeline 模式用于快速查证事实，完全智能体（agentic）深度研究则适用于复杂分析与学术工作。

LangGraph Agent Strategy — 一种自主智能体研究模式，由 LLM 决定搜索什么、使用哪些专用引擎（arXiv、PubMed、Semantic Scholar 等），以及何时进行综合归纳。它会根据检索结果自适应切换搜索引擎，并比基于 pipeline 的策略收集显著更多的来源 — 上文约 95% SimpleQA 成绩即由此策略达成。在 Settings 中选择 langgraph-agent。

构建你的知识库

flowchart LR
    R[Research] --> D[Download Sources]
    D --> L[(Library)]
    L --> I[Index & Embed]
    I --> S[Search Your Docs]
    S -.-> R

每次研究会话都会发现宝贵来源。可直接下载到加密资料库 — ArXiv 学术论文、PubMed 文章、网页等。LDR 提取文本、建立索引并使一切可搜索。下次研究时，可同时对自己的文档与实时网页提问。你的知识会随时间不断累积。

🛡️ 安全

flowchart LR
    U1[User A] --> D1[(Encrypted DB)]
    U2[User B] --> D2[(Encrypted DB)]

你的数据始终属于你。每位用户都拥有独立的 SQLCipher 数据库，采用 AES-256 加密，密钥由你的密码派生。你的密码绝不会被存储——登录通过尝试解密你的数据库来完成，因此数据库文件本身对任何获取到它们的人都无法使用。每位用户的 LLM API 密钥加密存储在同一个人数据库中，而非共享的服务器级存储。

Docker 部署 附带 cap_drop: ALL、no-new-privileges 以及非 root 运行时，捆绑的 Ollama 和 SearXNG 镜像均通过 digest 固定版本。或者完全在本地运行 Ollama + SearXNG，数据永不离开你的机器。

内存中的凭据：与任何在运行时使用密钥的应用一样，凭据在活跃会话期间保存在进程内存中——通过会话范围的凭据生命周期和核心转储排除（core dump exclusion）加以缓解。完整威胁模型请参阅安全策略。

供应链安全：Docker 镜像使用 Cosign 通过 GitHub 的无密钥 OIDC 流程进行签名，包含 SLSA 来源证明（provenance attestations），并附带经认证的 SPDX SBOM。分步验证命令请参阅验证镜像与 SBOM。

安全透明度：扫描器抑制项及其理由记录在 Security Alerts Assessment、Scorecard Compliance、Container CVE Suppressions 和 SAST Rule Rationale 中。部分告警（Dependabot、代码扫描）只能在 GitHub Security tab, 中关闭，或在其之外极难抑制，因此上述文件并未涵盖每一条已关闭的发现。

详细架构 → | 安全策略 → | 安全审查流程 →

🔒 隐私与数据

Local Deep Research 不包含遥测、分析或跟踪。我们不会收集、传输或存储任何关于你或你使用情况的数据。没有分析 SDK、没有回传（phone-home）调用、没有崩溃报告、没有外部脚本。使用指标保留在你本地的加密数据库中。

LDR 发出的唯一网络请求均由你发起：搜索查询（发往你配置的搜索引擎）、LLM API 调用（发往你选择的提供商），以及通知（仅在你配置了 Apprise 时）。

由于我们不收集任何使用数据，我们依赖你告诉我们哪些好用、哪些有问题、以及你希望接下来看到什么——错误报告, 功能建议，甚至你喜爱或从不使用的功能，都有助于我们改进 LDR。

📊 基准测试

来自社区基准测试 的 headline 结果，采用 langgraph-agent 策略配合 Serper 搜索，通过 Ollama 完全在本地运行：

Model	SimpleQA	xbench-DeepSearch
Qwen3.6-27B	95.7% (287/300)	77.0% (77/100)
Qwen3.5-9B	91.2% (182/200)	59.0% (59/100)
gpt-oss-20B	85.4% (295/346)	–

注意事项：样本量较小、LLM 评分器噪声，以及较新基础模型在 SimpleQA 上的污染风险。

正在挑选本地模型？同一社区维护的数据集会跟踪各模型、搜索引擎和研究策略的准确率——这是你在下载数 GB 权重之前，快速了解哪些 Ollama / LM Studio / llama.cpp 模型真正适合深度研究的最快方式。在 Hugging Face 上浏览完整排行榜 →

提交你自己的结果 →（贡献者列于 CONTRIBUTORS.md), 或在本地运行基准测试 →。

✨ 核心功能

🔍 研究模式

• Quick Summary - 30 秒至 3 分钟内获得带引用的答案
• Detailed Research - 结构化发现的全面分析
• Report Generation - 带章节与目录的专业报告
• Document Analysis - 用 AI 搜索你的私有文档

🛠️ 高级能力

• LangChain Integration - 将任意向量存储用作搜索引擎
• REST API - 经身份验证的 HTTP 访问，每位用户独立数据库
• Benchmarking - 测试并优化你的配置
• Analytics Dashboard - 跟踪成本、性能与使用指标
• Journal Quality System - 自动期刊声誉评分，索引 212K+ 来源，含掠夺性期刊检测与质量仪表板。由 OpenAlex（CC0）、DOAJ（CC0）和 Stop Predatory Journals（MIT）提供支持。参见 v1.6.0 公告.
• Real-time Updates - WebSocket 支持，实时展示研究进度
• Chat Mode - 多轮研究对话，支持流式进度与跨轮次累积上下文
• Export Options - 将结果下载为 PDF 或 Markdown
• Research History - 保存、搜索并回顾过往研究
• Adaptive Rate Limiting - 智能重试系统，学习最优等待时间
• Keyboard Shortcuts - 高效导航（ESC、Ctrl+Shift+1-4）

📰 新闻与研究订阅

• 自动化研究摘要 - 订阅主题或特定查询；AI 筛选并仅汇总最相关的发展动态
• 可定制投递 - 每日、每周或自定义计划，以 Markdown 报告或结构化摘要形式交付

🌐 搜索源

免费搜索引擎

• 学术：arXiv、PubMed、Semantic Scholar
• 通用：Wikipedia、SearXNG
• 技术：GitHub、Elasticsearch
• 历史：Wayback Machine
• 新闻：The Guardian、Wikinews

付费搜索引擎

• Tavily - AI 驱动的搜索
• Google - 通过 SerpAPI 或 Programmable Search Engine
• Brave Search - 注重隐私的网页搜索

自定义源

• 本地文档 - 用 AI 搜索你的文件
• LangChain Retrievers - 任意向量存储或数据库
• 元搜索（Meta Search） - 智能组合多个搜索引擎

LDR 遵守 robots.txt，在抓取网页时会如实表明自身身份——不使用隐身或反检测技术。在少数情况下，这意味着会无法抓取阻止自动化访问的页面，我们认为这是正确的权衡。

完整搜索引擎指南 →

💻 使用示例

Python API

from local_deep_research.api import LDRClient, quick_query

# Option 1: Simplest - one line research
summary = quick_query("username", "password", "What is quantum computing?")
print(summary)

# Option 2: Client for multiple operations
client = LDRClient()
client.login("username", "password")
result = client.quick_research("What are the latest advances in quantum computing?")
print(result["summary"])

HTTP API

下方代码示例展示基本 API 结构——完整可运行示例请见下方链接

import requests
from bs4 import BeautifulSoup

# Create session and authenticate
session = requests.Session()
login_page = session.get("http://localhost:5000/auth/login")
soup = BeautifulSoup(login_page.text, "html.parser")
login_csrf = soup.find("input", {"name": "csrf_token"}).get("value")

# Login and get API CSRF token
session.post("http://localhost:5000/auth/login",
            data={"username": "user", "password": "pass", "csrf_token": login_csrf})
csrf = session.get("http://localhost:5000/auth/csrf-token").json()["csrf_token"]

# Make API request
response = session.post("http://localhost:5000/api/start_research",
                       json={"query": "Your research question"},
                       headers={"X-CSRF-Token": csrf})

🚀 开箱即用的 HTTP API 示例 → examples/api_usage/http/

• ✅ 自动创建用户 - 开箱即用
• ✅ 完整身份验证，含 CSRF 处理
• ✅ 结果重试逻辑 - 等待研究完成
• ✅ 进度监控与错误处理

命令行工具

# Run benchmarks from CLI
python -m local_deep_research.benchmarks.cli.benchmark_commands simpleqa --examples 50

# Manage rate limiting
python -m local_deep_research.web_search_engines.rate_limiting status
python -m local_deep_research.web_search_engines.rate_limiting reset --engine SearXNGSearchEngine

完整参考请见命令行工具指南。

🔗 接入自有知识库

将 LDR 连接到你现有的知识库。与上文 HTTP 客户端不同，quick_summary() 在进程内运行 LDR——无需服务器——因此你可以传入实时 Python 对象，例如 LangChain retriever：

from local_deep_research.api import quick_summary

# Use your existing LangChain retriever
result = quick_summary(
    query="What are our deployment procedures?",
    retrievers={"company_kb": your_retriever},
    search_tool="company_kb"
)

支持：FAISS、Chroma、Pinecone、Weaviate、Elasticsearch，以及任意兼容 LangChain 的 retriever。

集成指南 →

🔌 MCP 服务器（Claude 集成）

LDR 提供 MCP（Model Context Protocol）服务器，使 Claude Desktop、Claude Code 等 AI 助手能够执行深度研究。完整配置说明见 MCP 服务器指南。

⚠️ 安全提示：此 MCP 服务器仅面向本地使用，通过 STDIO 传输（例如 Claude Desktop）。它没有内置身份验证或速率限制。若要在网络上暴露，必须先实施适当的安全控制。网络部署要求见 MCP 安全最佳实践。

安装

# Install with MCP extras
pip install "local-deep-research[mcp]"

Claude Desktop 配置

添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "openai",
        "LDR_LLM_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Code 配置

添加到你的 .mcp.json（项目级）或 ~/.claude/mcp.json（全局）：

{
  "mcpServers": {
    "local-deep-research": {
      "command": "ldr-mcp",
      "env": {
        "LDR_LLM_PROVIDER": "ollama",
        "LDR_LLM_OLLAMA_URL": "http://localhost:11434"
      }
    }
  }
}

任意 LDR 设置均可通过 env 以 LDR_* 变量传入——完整列表见自动生成的完整配置参考。

可用工具

Tool	Description	Duration	LLM Cost
search	来自特定引擎（arxiv、pubmed、wikipedia 等）的原始结果	5-30s	None
quick_research	快速研究摘要	1-5 min	Yes
detailed_research	全面分析	5-15 min	Yes
generate_report	完整 Markdown 报告	10-30 min	Yes
analyze_documents	搜索本地集合	30s-2 min	Yes
list_search_engines	列出可用搜索引擎	instant	None
list_strategies	列出研究策略	instant	None
get_configuration	获取当前配置	instant	None

单独搜索引擎

search 工具可让你直接查询特定搜索引擎并获取原始结果（标题、链接、摘要）——无 LLM 处理、无费用、速度快。这对需要监控与订阅、希望定期检查新内容而又不消耗 LLM token 的场景尤其有用。

# Search arXiv for recent papers
search(query="transformer architecture improvements", engine="arxiv")

# Search PubMed for medical literature
search(query="CRISPR clinical trials 2024", engine="pubmed")

# Search Wikipedia for quick facts
search(query="quantum error correction", engine="wikipedia")

# Search GitHub for code and repositories
search(query="agentic research frameworks", engine="github")

# Use list_search_engines() to see all available engines

使用示例

"Use quick_research to find information about quantum computing applications"
"Search arxiv for recent papers on diffusion models"
"Generate a detailed research report on renewable energy trends"

🤖 支持的 LLM

本地模型

• Ollama — 连接其原生 API（默认 http://localhost:11434）
• LM Studio — 连接其 OpenAI 兼容服务器（默认 http://localhost:1234/v1）
• llama.cpp — 连接 llama-server 的 OpenAI 兼容端点（默认 http://localhost:8080/v1）；使用 llama-server -m <model.gguf> 启动
• 常见模型：Llama、Mistral、Gemma、DeepSeek、Qwen
• LLM 处理保留在本地（搜索查询仍会访问网络）。无 API 费用。

💡 该选哪个本地模型？ 参见社区基准测试——社区提交的本地与云端模型准确度数据，便于下载前对比。

云端模型

• OpenAI
• Anthropic Claude
• Google Gemini
• 通过 OpenRouter 支持 100+ 模型

自定义端点

• OpenAI 兼容端点 — 任何支持 OpenAI chat-completions API 的服务（vLLM、llama.cpp、网关等）
• Anthropic 兼容端点 — 自托管、支持 Anthropic Messages API 的服务（/v1/messages）；设置 llm.anthropic_endpoint.url

模型配置 →

🔄 从早期版本升级

• llm.model 不再有默认值。 1.6.3 之前的安装在未配置模型时会自动填充 gemma3:12b（Ollama），这会默默下载一个数 GB 的二进制文件。该字段现在默认为空——请在 Settings → LLM 中选择模型，否则研究任务会明确报错并失败。
• 已移除 auto 和 parallel 元搜索引擎。 默认的 langgraph-agent 策略会按查询动态选择引擎，以此替代它们。已保存的设置会自动迁移（被移除的值将变为 searxng）；请将任何显式使用 search_tool="auto" 的 API 调用或 LDR_SEARCH_TOOL=auto 环境变量覆盖更新为具体引擎，例如 searxng。
• llamacpp 提供方现在使用 HTTP，而非进程内加载。 如果你此前将 llm.llamacpp_model_path 设置为本地 .gguf 文件，该设置不再被读取。请改为运行 llama-server -m <your-model.gguf>（每个现代 llama.cpp 构建都自带），默认的 llm.llamacpp.url（http://localhost:8080/v1）会自动发现它。若你将 llama-server 置于认证代理之后，可通过 llm.llamacpp.api_key 可选地配置 API 密钥支持。

📚 文档

入门

• 安装指南
• 常见问题
• API 快速入门
• 配置指南
• 完整配置参考

核心功能

• 全部功能指南
• 搜索引擎指南
• 分析仪表盘

高级功能

• LangChain 集成
• 基准测试系统
• Elasticsearch 配置
• SearXNG 配置

开发

• Docker Compose 指南
• 开发指南
• CodeQL 指南
• 发布指南
• CI/CD 基础设施 — pre-commit 钩子、工作流、安全扫描
• 工作流状态仪表盘 — 各 GitHub Actions 工作流的实时运行状况
• 测试覆盖率报告 — 发布至 GitHub Pages 的 pytest 覆盖率

示例与教程

• API 示例
• 基准测试示例
• 优化示例

📰 精选报道

"对于那些将隐私放在首位的用户，Local Deep Research 值得特别关注……专为使用可在消费级 GPU 甚至 CPU 上运行的开源 LLM 而调优。记者、研究人员或处理敏感话题的企业可以展开调查，查询永远不会触及外部服务器。"

— Medium：开源深度研究 AI 助手

新闻与文章

• Korben.info - 法国科技博客（"Sherlock Holmes numérique"）
• Roboto.fr - "L'alternative open-source gratuite à Deep Research d'OpenAI"
• KDJingPai AI Tools - AI 效率工具报道
• AI Sharing Circle - AI 资源报道

社区讨论

• r/LocalLLaMA: 95.7% SimpleQA on a single 3090, fully local - Qwen3.6-27B 基准测试公告（161K 次浏览）
• r/WebAfterAI: LDR as the agentic layer on top of Ollama / LM Studio / LocalAI - 技术栈定位说明
• Hacker News - 190+ 点，社区讨论
• LangChain Twitter/X - LangChain 官方推广
• LangChain LinkedIn - 400+ 点赞

国际报道

🇨🇳 中文

• Juejin (掘金) - 开发者社区
• Cnblogs (博客园) - 开发者博客
• GitHubDaily (Twitter/X) - 有影响力的科技账号
• Zhihu (知乎) - 科技社区
• A姐分享 - AI 资源
• CSDN - 安装指南
• NetEase (网易) - 科技新闻门户

🇯🇵 日文

• note.com: 調査革命：Local Deep Research徹底活用法 - 全面教程
• Qiita: Local Deep Researchを試す - Docker 配置指南
• LangChainJP (Twitter/X) - 日本 LangChain 社区

🇰🇷 韩文

• PyTorch Korea Forum - 韩国机器学习社区
• GeekNews (Hada.io) - 韩国科技新闻

评测与分析

• BSAIL Lab: How useful is Deep Research in Academia? - 贡献者 @djpetti 的学术评测
• The Art Of The Terminal: Use Local LLMs Already! - 本地 AI 工具全面评测，重点介绍 LDR 的研究能力
• Fahd Mirza: Local Deep Research + Ollama — Free AI Research Assistant You Control - 安装演练（349K 订阅者的频道）。视频中展示的 SearXNG 启动问题已在 #3881 中修复——干净的 Docker 安装现已开箱即用。
• BC Adventure Tech: Run ChatGPT Deep Research Locally (Unraid AI Agent Setup) - Unraid 配置与展示

相关项目

• SearXNG LDR-Academic - 面向学术的 SearXNG 分支，内置 12 个研究引擎（arXiv、Google Scholar、PubMed 等），专为 LDR 设计
• DeepWiki Documentation - 第三方文档与指南

注意： 第三方项目与文章由各维护方独立维护。我们提供链接作为有用资源，但无法保证其代码质量或安全性。

🤝 社区与支持

• Discord - 获取帮助并分享研究技巧
• Reddit - 更新与展示
• GitHub Issues - 错误报告

🧑‍💻 贡献

我们欢迎各种规模的贡献——从错字修复到新功能。关键原则：保持 PR 小而原子化（每个 PR 只做一项变更）。对于较大改动，请先开一个 issue 或发起讨论——我们希望保护你的时间，并确保你的努力导向一次成功合并，而非方向不对的 PR。请参阅我们的贡献指南开始参与。

致谢

Local Deep Research 建立在众多开放获取计划、学术数据库和开源项目的基础之上。我们感谢：

学术与研究数据

来源	提供内容	许可证
OpenAlex	约 28 万个来源和约 12 万个机构的学术元数据，含 DOAJ 状态	CC0
DOAJ	开放获取期刊目录——开放获取验证（通过 OpenAlex）	CC0
arXiv	物理学、数学、计算机科学等领域的预印本	多种（见 arXiv 许可证）
PubMed / NCBI	生物医学与生命科学文献	公有领域（美国政府）
Semantic Scholar	跨学科学术搜索与引文数据	Terms
NASA ADS	天体物理学、物理学与天文学论文	Terms
Zenodo	开放研究数据、数据集与软件	因记录而异
PubChem	化学与生物化学数据库	公有领域（美国政府）
Stop Predatory Journals	掠夺性期刊/出版商黑名单	MIT
JabRef	期刊缩写数据库	CC0

知识与内容来源

Wikipedia • OpenLibrary • Project Gutenberg • GitHub • Stack Exchange • The Guardian • Wayback Machine

基础设施与框架

LangChain • Ollama • SearXNG • FAISS

支持开放获取

这些项目依靠捐赠和资助运营，而非付费墙。如果 Local Deep Research 对你有帮助，请考虑回馈使其得以实现的开放获取生态：

• arXiv — 物理、数学、计算机科学等领域的免费预印本
• PubMed / NLM — 开放的生物医学文献
• Wikipedia / Wikimedia — 免费百科全书
• Internet Archive — Wayback Machine 与开放数字图书馆
• DOAJ — 全球开放获取期刊的策展与认证
• OpenAlex — 开放的学术元数据（由 OurResearch) 赞助
• Project Gutenberg — 自 1971 年以来的免费电子书

📄 许可证

MIT License - 详见 LICENSE 文件。

依赖项： 所有第三方软件包均采用宽松许可证（MIT、Apache-2.0、BSD 等）- 详见 allowlist