Local Researcher Skill#

完全在本地运行的深度研究助手，无需将数据发送到云端 LLM 服务。支持 Ollama 和 LMStudio，迭代式网络研究，输出带引用的专业报告。

前置要求#

安装 Ollama（推荐）#

bash

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# 拉取模型
ollama pull deepseek-r1:8b
ollama pull llama3.2
ollama pull qwen:14b

或使用 LMStudio#

1. 下载 LMStudio
2. 下载并加载模型（如 qwen_qwq-32b）
3. 进入 "Local Server" 标签页
4. 启动 OpenAI 兼容 API 服务
5. 记下服务地址（默认: http://localhost:1234/v1）

安装本 Skill#

bash

# 克隆仓库
git clone https://github.com/langchain-ai/local-deep-researcher.git
cd local-deep-researcher

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

# 安装依赖
pip install -e .

配置#

复制环境变量模板并编辑：

bash

cp .env.example .env

编辑 .env 文件：

bash

# LLM 提供商选择
LLM_PROVIDER=ollama
# LLM_PROVIDER=lmstudio

# Ollama 配置
OLLAMA_BASE_URL=http://localhost:11434
LOCAL_LLM=deepseek-r1:8b

# LMStudio 配置
# LMSTUDIO_BASE_URL=http://localhost:1234/v1
# LOCAL_LLM=qwen_qwq-32b

# 搜索工具配置
SEARCH_API=duckduckgo  # 默认，无需 API key
# SEARCH_API=tavily
# TAVILY_API_KEY=tvly-xxx
# SEARCH_API=perplexity
# PERPLEXITY_API_KEY=pplx-xxx

# 研究循环次数
MAX_WEB_RESEARCH_LOOPS=3

# 是否获取完整页面内容
FETCH_FULL_PAGE=true

使用方法#

快速开始#

bash

# 启动研究（交互模式）
python src/ollama_deep_researcher/main.py

# 或使用 LangGraph CLI
langgraph dev

程序化使用#

python

from langgraph.graph import StateGraph
from ollama_deep_researcher.graph import graph

# 定义研究主题
topic = "量子计算在药物发现中的应用"

# 配置参数
config = {
    "llm_provider": "ollama",
    "local_llm": "deepseek-r1:8b",
    "search_api": "duckduckgo",
    "max_web_research_loops": 3,
    "fetch_full_page": True
}

# 运行研究
result = graph.invoke(
    {"topic": topic},
    config=config
)

# 输出报告
print(result["final_summary"])

核心功能#

1. 迭代式深度研究#

系统自动执行以下循环：

1. 根据主题生成搜索查询
2. 执行网络搜索
3. 总结搜索结果
4. 反思总结，识别知识缺口
5. 生成新查询填补缺口
6. 重复直到达到最大循环次数

2. 多搜索源支持#

搜索源需要 API Key特点DuckDuckGo❌ 不需要默认选项，隐私友好Tavily✅ 需要高质量搜索结果Perplexity✅ 需要AI 增强搜索SearXNG❌ 不需要自托管选项

3. 输出格式#

最终输出为 Markdown 格式报告，包含：

• 执行摘要
• 详细研究发现
• 所有引用的来源链接
• 研究过程元数据

4. LangGraph Studio 可视化#

bash

# 安装 LangGraph CLI
pip install "langgraph-cli[inmem]"

# 启动开发服务器
langgraph dev

打开浏览器访问 Studio UI，可实时观察研究流程：

• 搜索查询生成
• 来源收集
• 总结迭代
• 最终报告生成

完整工作流示例#

学术论文预研#

python

import asyncio
from ollama_deep_researcher.graph import graph

async def research_paper_prep():
    topic = "Transformer 架构在生物信息学中的最新应用"

    config = {
        "llm_provider": "ollama",
        "local_llm": "deepseek-r1:14b",  # 使用更大模型获得更好结果
        "search_api": "duckduckgo",
        "max_web_research_loops": 5,  # 更多轮次深入挖掘
        "fetch_full_page": True
    }

    result = await graph.ainvoke(
        {"topic": topic},
        config=config
    )

    # 保存报告
    with open("literature_review.md", "w") as f:
        f.write(result["final_summary"])

    # 打印引用的来源
    print("参考来源:")
    for source in result.get("sources", []):
        print(f"- {source}")

    return result

# 运行
result = asyncio.run(research_paper_prep())

市场调研报告#

python

def market_research(product_category: str):
    """生成市场调研报告"""

    topic = f"{product_category} 市场规模、主要竞争者和发展趋势 2024"

    config = {
        "llm_provider": "ollama",
        "local_llm": "qwen:14b",
        "search_api": "tavily",  # 使用 Tavily 获得更商业化的结果
        "tavily_api_key": "tvly-xxx",
        "max_web_research_loops": 4,
        "fetch_full_page": True
    }

    result = graph.invoke(
        {"topic": topic},
        config=config
    )

    return result["final_summary"]

# 生成报告
report = market_research("新能源汽车")
print(report)

技术趋势追踪#

bash

# 使用命令行快速研究
cd local-deep-researcher
source .venv/bin/activate

# 创建研究脚本
python -c "
from ollama_deep_researcher.graph import graph

result = graph.invoke(
    {'topic': 'Rust 语言在系统编程领域的最新发展'},
    config={
        'llm_provider': 'ollama',
        'local_llm': 'llama3.2',
        'search_api': 'duckduckgo',
        'max_web_research_loops': 3
    }
)

print(result['final_summary'])
"

Docker 部署#

bash

# 构建镜像
docker build -t local-researcher .

# 运行容器
docker run --rm -it -p 2024:2024 \
  -e SEARCH_API=tavily \
  -e TAVILY_API_KEY=tvly-xxx \
  -e LLM_PROVIDER=ollama \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434/ \
  -e LOCAL_LLM=llama3.2 \
  local-researcher

注意：Ollama 需要在宿主机单独运行，容器通过 host.docker.internal 访问。

模型兼容性说明#

模型JSON 模式支持备注llama3.2✅推荐，轻量快速deepseek-r1:8b✅推理能力强qwen:14b✅中文表现好gpt-oss⚠️需要启用 tool calling

gpt-oss 模型特殊配置：

bash

# gpt-oss 不支持 JSON 模式，需要启用 tool calling
USE_TOOL_CALLING=true

故障排查#

Ollama 连接问题#

bash

# 检查 Ollama 服务状态
curl http://localhost:11434/api/tags

# 确保模型已下载
ollama list

# 测试模型
ollama run llama3.2 "Hello"

搜索结果为空#

• 检查网络连接
• 尝试更换搜索 API
• 调整搜索查询语言

生成质量不佳#

• 使用更大的模型（如 14B 参数以上）
• 增加 MAX_WEB_RESEARCH_LOOPS
• 启用 FETCH_FULL_PAGE 获取更完整内容

隐私与安全#

• ✅ 所有数据留在本地
• ✅ 无需联网到 OpenAI/Claude
• ✅ 搜索查询不关联个人身份
• ✅ 适合处理敏感商业/研究数据

高级用法#

自定义研究流程#

python

from langgraph.graph import StateGraph
from ollama_deep_researcher.configuration import Configuration
from ollama_deep_researcher import research_node, reflect_node

# 创建自定义流程
builder = StateGraph(ResearchState)
builder.add_node("research", research_node)
builder.add_node("reflect", reflect_node)
# ... 添加更多节点

# 编译并运行
graph = builder.compile()

集成到其他应用#

python

# FastAPI 示例
from fastapi import FastAPI
from ollama_deep_researcher.graph import graph

app = FastAPI()

@app.post("/research")
async def create_research(topic: str):
    result = await graph.ainvoke(
        {"topic": topic},
        config={"max_web_research_loops": 3}
    )
    return {
        "topic": topic,
        "report": result["final_summary"],
        "sources": result.get("sources", [])
    }

相关资源#

• LangChain Academy - 部署教程
• LangGraph 文档
• Ollama 模型库