Local Researcher Skill

---

name: local-researcher

description: 完全本地的深度研究助手 Skill。使用 Ollama 或 LMStudio 本地 LLM 进行迭代式网络研究，生成带引用来源的 Markdown 报告。当用户需要进行隐私优先的研究、本地文档分析或生成结构化研究报告时触发。

version: 1.0.0

---

# Local Researcher Skill

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

前置要求

安装 Ollama（推荐）

# 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](https://lmstudio.ai/)

2. 下载并加载模型（如 qwen_qwq-32b）

3. 进入 "Local Server" 标签页

4. 启动 OpenAI 兼容 API 服务

5. 记下服务地址（默认: http://localhost:1234/v1）

安装本 Skill

# 克隆仓库
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 .

配置

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

cp .env.example .env

编辑 `.env` 文件：

# 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

使用方法

快速开始

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

# 或使用 LangGraph CLI
langgraph dev

程序化使用

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 可视化

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

# 启动开发服务器
langgraph dev

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

完整工作流示例

学术论文预研

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())

市场调研报告

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)

技术趋势追踪

# 使用命令行快速研究
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 部署

# 构建镜像
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 模型特殊配置**：

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

故障排查

Ollama 连接问题

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

# 确保模型已下载
ollama list

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

搜索结果为空

生成质量不佳

隐私与安全

高级用法

自定义研究流程

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()

集成到其他应用

# 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", [])
    }

相关资源