深度研究报告生成工具 Deep Research Agent

Deep Research Agent 是一个基于 LangGraph 和 LangChain 构建的AI智能体自主研究系统，通过研究规划、搜索、综合和报告撰写这四个专业智能体协同工作，能针对任意主题进行全面深入的研究，生成带有可信度评分、质量验证和完整引用的详细报告。Deep Research Agent 能够自主决定搜索策略、动态提取高质量内容，对所有来源进行自动可信度评估以过滤低质量信息。Deep Research Agent 支持导出不同格式的报告（Markdown、HTML、纯文本）、智能研究缓存以减少重复API调用、LLM使用跟踪功能。

多智能体架构

Deep Research Agent采用四大专业自主智能体——ResearchPlanner（研究规划师）、ResearchSearcher（研究搜索师）、ResearchSynthesizer（研究合成师）、ReportWriter（报告撰写师），由LangGraph的StateGraph进行协调调度。每个智能体独立运作，拥有专属工具与决策逻辑，分工明确且高效协同。

自主化研究流程

搜索智能体能够动态判断搜索时机、确定执行的查询内容以及筛选值得深度提取信息的来源，通常会锁定5-8个高质量信息源，确保研究的精准性。

可信度评分机制

通过领域权威性分析对信息源进行自动评估，评分范围为0-100分。评分依据包括可信域名（.edu、.gov）、是否启用HTTPS、是否存在可疑模式以及学术指标等。低可信度（默认阈值40分以下）的信息源会在合成前被自动过滤，保障研究基础的可靠性。

质量验证

采用章节级别的验证机制，确保每个章节内容满足最低长度要求（500字符以上）并符合质量标准。针对操作失败的情况，系统设有带指数退避的重试逻辑，每个操作最多可尝试3次，提升流程稳定性。

导出格式

报告自动生成三种格式供使用：Markdown（原始格式）、HTML（适配网页的样式化格式）、纯文本（去除Markdown标记）。

LLM使用追踪

实时监控API调用情况、输入输出令牌数量以及预估成本，能按智能体进行细分统计，方便识别优化空间，合理控制使用成本。

研究缓存功能

基于文件的智能缓存机制，缓存有效期为7天。通过MD5算法对主题进行哈希处理，确保缓存查询的准确性，减少重复API调用，提升研究效率。

架构设计和工作流程

架构设计

系统通过LangGraph的StateGraph构建四阶段流水线式架构，各阶段依次衔接：

ResearchPlanner → ResearchSearcher → ResearchSynthesizer → ReportWriter

各智能体职责

1、ResearchPlanner：分析研究主题，生成3-5个研究目标；设计3个覆盖不同维度的针对性搜索查询；构建包含最多8个章节的报告大纲；为自主搜索智能体提供策略指导。

2、ResearchSearcher（自主智能体）：基于LangChain的create_agent()构建；动态决策执行哪些查询、何时提取内容；自主使用web_search和extract_webpage_content工具；根据中间研究结果调整研究策略；锁定5-8个高质量信息源并进行深度内容提取；所有信息源均经过可信度评分和过滤。

3、ResearchSynthesizer：结合可信度评估结果分析汇总的搜索结果；优先采用高可信度（评分≥70）信息源的研究发现；通过可信度层级解决信息矛盾；提取关键见解并识别潜在模式；遇到令牌限制错误时，采用渐进式截断方式灵活处理。

4、ReportWriter：以统一的学术语气生成结构化报告章节；支持配置多种引用格式（APA、MLA、芝加哥、IEEE）并添加规范引文；验证章节质量，失败时重新生成；整合最终内容，生成带参考文献章节的Markdown文档。

完整工作流程

1、规划阶段：LLM生成包含研究目标、查询语句和大纲的研究计划。

2、自主搜索：智能体执行搜索操作，从优质信息源中提取内容。

3、可信度评分：对所有信息源进行评分并过滤（默认阈值40分）。

4、合成阶段：结合可信度优先级提取研究发现。

5、报告生成：撰写结构化章节并添加规范引文。

6、导出阶段：将报告以多种格式保存至outputs/目录。

Deep Research Agent安装和配置

安装环境要求

• Python 3.11及以上版本

• pip或uv包管理器

• 本地模型需安装Ollama；云API需准备Google Gemini API密钥（可免费获取）或OpenAI API密钥（可通过官方平台获取）

安装步骤

# 克隆仓库
git clone https://github.com/tarun7r/deep-research-agent.git
cd deep-research-agent

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

# 安装依赖
pip install -r requirements.txt

# 配置方式（三选一）：
# 方式A - Ollama：安装Ollama后，拉取模型（示例：ollama pull qwen2.5:7b）
# 方式B - Gemini：从https://makersuite.google.com/app/apikey获取API密钥
# 方式C - OpenAI：从https://platform.openai.com/api-keys获取API密钥
# 创建.env文件（配置细节见下文）

不同模型提供商配置说明

Ollama（本地模型）

Ollama支持在本地机器运行强大的LLM，无需API费用，也不依赖网络，隐私性强。快速启动：

# macOS/Linux系统安装Ollama
curl -fsSL https://ollama.com/install.sh | sh
# 其他平台可从https://ollama.com下载安装

# 拉取推荐模型
ollama pull qwen2.5:7b

# 验证运行状态
ollama run qwen2.5:7b "Hello, test message"

.env文件配置：

MODEL_PROVIDER=ollama
MODEL_NAME=qwen2.5:7b
SUMMARIZATION_MODEL=qwen2.5:7b

提示：Ollama默认在http://localhost:11434启动本地服务器，智能体将自动连接。

llama.cpp（本地模型）

llama.cpp可直接控制模型执行，在搭载Metal加速的Mac M1/M2/M3设备上性能表现极佳。快速启动：

# 1、下载GGUF格式模型（示例：Qwen2.5:7B q4_k_m量化版本）
cd ../..
mkdir models
# 从Hugging Face下载
huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF qwen2.5-7b-instruct-q4_k_m.gguf --local-dir ./models

# 2、启动支持工具调用的llama.cpp服务器
cd llama.cpp/build/bin
./llama-server -m ~/models/qwen2.5-7b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 35 \
  --ctx-size 4096 \
  --jinja

.env文件配置：

MODEL_PROVIDER=llamacpp
MODEL_NAME=qwen2.5-7b-instruct-q4_k_m  # 模型名称可自定义
SUMMARIZATION_MODEL=qwen2.5-7b-instruct-q4_k_m
LLAMACPP_BASE_URL=http://localhost:8080

重要参数说明： • --jinja：支持工具/函数调用（研究智能体必需） • -ngl 35：将35层模型加载到GPU（Metal加速） • --ctx-size 4096：上下文窗口大小 • --host 0.0.0.0：允许任意IP连接 • --port 8080：服务器端口

性能优化提示：Metal加速可使M1/M2/M3设备速度提升2-3倍；服务器在/v1/chat/completions提供OpenAI兼容API；通过--n-gpu-layers（或-ngl）参数最大化GPU利用率。

Gemini（云API）

无需本地资源，依托谷歌最新前沿模型，跨设备响应速度稳定。需准备API密钥并保持网络连接，提供免费额度，超出后按使用计费。 .env文件配置（示例）：

MODEL_PROVIDER=gemini
GEMINI_API_KEY=你的API密钥
MODEL_NAME=gemini-2.5-flash
SUMMARIZATION_MODEL=gemini-2.5-flash

OpenAI（云API）

无需本地资源，拥有行业领先的模型（GPT-4、GPT-4o），性能稳定可靠。需准备API密钥并保持网络连接，按使用量计费，价格具有竞争力。推荐模型：gpt-4o-mini（性价比高）、gpt-4o（质量最佳）。 .env文件配置（示例）：

MODEL_PROVIDER=openai
OPENAI_API_KEY=你的API密钥
MODEL_NAME=gpt-4o-mini
SUMMARIZATION_MODEL=gpt-4o-mini

可选配置参数

在.env文件中可自定义以下参数：

# 搜索设置
MAX_SEARCH_QUERIES=3
MAX_SEARCH_RESULTS_PER_QUERY=3
MIN_CREDIBILITY_SCORE=40

# 报告设置
MAX_REPORT_SECTIONS=8
CITATION_STYLE=apa  # 可选：apa、mla、chicago、ieee

模型提供商对比

模型提供商	核心特点	适用场景
Ollama（本地）	免费无API费用，离线可用，隐私性强，响应迅速，无速率限制，部署简单，模型管理便捷；需5-8GB内存，首次模型下载约4-5GB	追求便捷性、注重隐私、无网络环境
llama.cpp（本地）	免费无API费用，离线可用，隐私保护极致，Metal加速下本地推理速度最快，无速率限制，模型参数可控性强，量化后内存占用更低；需手动部署和编译，需4-8GB内存（取决于量化程度）	搭载M1/M2/M3芯片的Mac设备，追求极致性能
Gemini（云API）	无需本地资源，模型前沿，跨设备响应稳定；需API密钥和网络，有使用成本（提供免费额度）	无本地硬件资源，追求模型先进性
OpenAI（云API）	无需本地资源，模型性能行业领先，可靠性高；需API密钥和网络，按使用计费	追求报告质量，注重服务稳定性

使用方式

命令行使用

# 交互式模式
python main.py

# 直接指定研究主题
python main.py "量子计算对密码学的影响"

编程式API调用

import asyncio
from src.graph import run_research

async def research():
    state = await run_research("研究主题", verbose=True, use_cache=True)
    
    # 访问报告内容
    print(state["final_report"])
    
    # 访问LLM使用指标
    print(f"LLM调用次数: {state['llm_calls']}")
    print(f"输入令牌数: {state['total_input_tokens']:,}")
    print(f"输出令牌数: {state['total_output_tokens']:,}")
    print(f"总令牌数: {state['total_input_tokens'] + state['total_output_tokens']:,}")
    
    # 访问质量评分
    if state.get("quality_score"):
        print(f"质量评分: {state['quality_score']['total_score']}/100")

asyncio.run(research())

网页界面使用

# 启动网页界面
chainlit run app.py --host 127.0.0.1 --port 8000

网页界面支持： • 交互式对话式研究 • 带阶段标识的实时进度更新 • 质量指标与LLM使用统计展示 • 多格式报告下载（Markdown、HTML、TXT） • 研究历史追踪

输出格式与项目结构

报告输出格式

生成的报告遵循固定结构：

# [研究主题]

**深度研究报告**

## 研究目标
1、[目标1]
2、[目标2]
...

---

## [章节1标题]
[带嵌入式引文[1]、[2]的内容]

## [章节2标题]
[带嵌入式引文[3]、[4]的内容]

---

## 参考文献
1、[按选定格式排版的引文]
2、[按选定格式排版的引文]
...

所有报告自动保存至outputs/目录，文件名包含时间戳，便于区分和查找。