local-researcher

# 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](https://lmstudio.ai/)
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 - 部署教程](https://academy.langchain.com/)
- [LangGraph 文档](https://langchain-ai.github.io/langgraph/)
- [Ollama 模型库](https://ollama.com/library)