基于 LangGraph 的多阶段深度研究 Agent
融合实时网络检索、事实级长期记忆、双重 Critic 审查与可追溯引用
项目亮点 · 研究链路 · 系统架构 · 快速开始 · 工程验证 · 项目结构
计划确认 → 深度检索 → 证据反思 → 报告写作 → 审查修订 → 引用校验
可视化展示研究计划、检索过程、Agent 状态与最终报告
| 🧭 计划确认 | 🔎 并行深度检索 |
|---|---|
| 支持用户确认、反馈与重新规划，再进入正式研究。 | 自动拆分问题、去重查询、并行搜索，并由 Research Critic 判断是否补充证据。 |
| 🧠 事实级长期记忆 | ✍️ Writer/Critic 循环 |
| 从 Milvus 召回历史事实，并将新事实写回长期记忆。 | 依次生成大纲、草稿、审查意见和终稿，按反馈迭代修订。 |
| 🛡️ 事实与引用防护 | ♻️ Checkpoint 恢复 |
| 校验章节、专名和 URL，拒绝未知链接与截断终稿。 | 使用稳定 thread_id 恢复任务，避免重复外部搜索。 |
| 📊 可复现评测 | 🖥️ 可视化交互 |
| 提供固定题集、LLM-as-Judge、A/B 与故障注入测试。 | React 前端展示计划、研究过程、状态和最终报告。 |
本项目采用事实级 Memory-Augmented RAG，而不是传统的上传文档问答 RAG。Milvus 保存提取后的事实记录，Redis 分别承担搜索缓存与任务 Checkpoint。
- Milvus：跨任务长期事实记忆与语义召回。
- Redis Search Cache：短期缓存网页搜索结果，减少重复外部调用。
- LangGraph Checkpoint：保存任务图状态，用于失败恢复和任务续跑。
| 依赖 | 失败时行为 |
|---|---|
| Redis Search Cache | 自动降级为进程内缓存；只影响跨进程复用和重启后命中率。 |
| Redis Checkpoint | 默认失败关闭（fail closed），避免把不可恢复的任务误报为可恢复。仅本地开发可显式设置 CHECKPOINT_FALLBACK_TO_MEMORY=1。 |
| Milvus 事实记忆 | 不中断当前研究；暂停长期记忆读写，并按 KB_RECONNECT_INTERVAL_SECONDS 定期重连。 |
Web Search 次数、LLM token、墙钟时间和无进展轮数等单任务预算记录在 LangGraph state 中，因此从 Checkpoint 恢复不会重置预算。
环境变量中的预算值同时是服务端上限：请求可通过 configurable 降低预算，但不能将其提高到服务端上限之上。
| 模块 | 技术 |
|---|---|
| Agent 编排 | LangGraph、LangChain |
| 后端 | Python 3.11+、FastAPI、LangGraph API |
| 模型接入 | OpenAI-compatible API、DashScope Application |
| 长期记忆 | Milvus、PyMilvus、Embedding API |
| 缓存与恢复 | Redis、langgraph-checkpoint-redis |
| 前端 | React 19、TypeScript、Vite、Tailwind CSS |
| 评测 | Pytest、LLM-as-Judge、固定题集 A/B Benchmark |
- Python
3.11+ - Node.js
22 - Docker 与 Docker Compose
- OpenAI-compatible LLM 和 Embedding 服务
- DashScope Application/MCP Web Search 配置
进入项目根目录后执行：
python3.11 -m pip install uv==0.11.1
UV_PROJECT_ENVIRONMENT="$PWD/.venv" \
uv sync --project backend --extra dev --frozen
cd frontend
npm ci
cd ..docker compose -f infrastructure/milvus/docker-compose.yml up -d
docker compose -f infrastructure/redis/docker-compose.yml up -dCheckpoint 使用 Redis Search 索引，因此必须使用 Redis Stack；普通
redis:7-alpine 不支持 FT._LIST，不能用于 CHECKPOINT_BACKEND=redis。
如果本机已有启用 Redis Search 的兼容服务，可跳过第二条命令。
以仓库中的完整模板创建 backend/.env：
cp backend/.env.example backend/.env然后至少替换以下模型、搜索与存储配置：
# 研究模型 / 推理模型
RESEARCH_LLM_MODEL=your-research-model
RESEARCH_LLM_API_KEY=your-api-key
RESEARCH_LLM_BASE_URL=https://your-llm-endpoint/v1
REASONING_LLM_MODEL=your-reasoning-model
REASONING_LLM_API_KEY=your-api-key
REASONING_LLM_BASE_URL=https://your-llm-endpoint/v1
# DashScope 应用与网页搜索
MCP_API_KEY=your-dashscope-api-key
MCP_APP_ID=your-web-search-application-id
# Redis 搜索缓存与任务检查点
REDIS_URL=redis://localhost:6379/0
CHECKPOINT_BACKEND=redis
CHECKPOINT_REDIS_URL=redis://localhost:6379/0
CHECKPOINT_FALLBACK_TO_MEMORY=0
# Milvus 事实记忆
MILVUS_URI=http://localhost:19530
MILVUS_COLLECTION=research_facts
# OpenAI 兼容的向量嵌入服务
EMBEDDING_BASE_URL=https://your-embedding-endpoint/v1
EMBEDDING_API_KEY=your-embedding-api-key
EMBEDDING_MODEL=text-embedding-v3
EMBEDDING_DIM=1024
# 单任务研究预算
NUMBER_OF_INITIAL_QUERIES=2
MAX_RESEARCH_LOOPS=2
MAX_WEB_SEARCH_CALLS=20
MAX_TOTAL_TOKENS=120000
MAX_ELAPSED_SECONDS=900
MAX_NO_PROGRESS_ROUNDS=2
MAX_WRITER_REVISIONS=3
# 事实记忆生命周期与重连
KB_RECONNECT_INTERVAL_SECONDS=30
KB_LIFECYCLE_MODE=freshness
KB_RERANK_ENABLED=1
KB_RERANK_CANDIDATE_MULTIPLIER=3
# 默认不记录请求正文
LOG_REQUEST_BODY=0
EMBEDDING_DIM必须与 Embedding 模型的实际输出维度及 Milvus Collection 维度一致。backend/.env.example是配置项的唯一完整清单，其中还包含可选模型列表、Web Search 限流和生命周期模式说明。
生产部署验收或排查连通性时，可执行 KB 就绪检查：
cd backend
../.venv/bin/python -m agent.kb.preflight
cd ..命令会分别检查 Milvus 与 Embedding，并在任一依赖不可用时返回非零退出码。这是部署就绪探针，不是运行时的强制启动门禁：Milvus 暂时不可用时，Agent 仍可继续研究并在冷却期后重连。Embedding 检查会发送一条固定探针文本，可能产生一次极小的 API 调用费用。
分别在两个终端运行：
# 终端 1：启动 LangGraph 后端
./run_backend.sh# 终端 2：启动 React 前端
./run_frontend.sh默认地址：
- 🌐 Web UI: http://localhost:5173
- 🔗 LangGraph API: http://localhost:2024
- 🧩 LangGraph Studio: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
项目保留固定题集、原始 JSON 结果和评测报告。以下结果只代表对应实验范围，不外推为通用生产指标。
| 验证项 | 结果 | 说明 |
|---|---|---|
| 查询去重 A/B | 状态查询重复率 50% → 0% |
10 个固定主题均成功完成；平均状态查询数 6 → 3 |
| Checkpoint 故障恢复 | Web Search 调用 6 → 3 |
Critique 节点故障后恢复，最终执行查询数保持为 3 |
| Prompt Quality Guards | 幻觉题数 3/5 → 0/5 |
事实约束增强，但固定集均分 4.36 → 4.24，综合质量仍需优化 |
详细报告：
# 默认交付门禁：锁文件、后端测试/lint/typecheck、前端 lint/test/build
make verify
# 单独运行后端单元测试与回归测试
make backend-test
# 固定题集端到端与组件级评测
cd backend
../.venv/bin/python -m eval.run_eval \
--mode all \
--test-set test_set_basic_5.json \
--output eval_runs/local_eval.json
# 查询去重 A/B 基准测试
../.venv/bin/python -m eval.run_benchmark --variant both
# Checkpoint 故障注入基准测试
../.venv/bin/python -m eval.run_resume_benchmark端到端评测会调用真实 LLM、Web Search 和 Milvus。运行前请检查服务连通性、API 配额，并为评测使用独立的 Milvus Collection。
make verify不调用上述付费外部服务；CI 使用backend/uv.lock的 frozen 环境。
DeepResearch/
├── backend/
│ ├── src/agent/
│ │ ├── graph.py # 主图：计划、研究、写作
│ │ ├── budget.py # 单任务搜索/token/时间预算
│ │ ├── checkpoint.py # Redis/Memory Checkpoint
│ │ ├── resume.py # 任务恢复辅助接口
│ │ ├── sub_agents/
│ │ │ ├── research_agent.py # 查询、检索、事实记忆、反思
│ │ │ └── writer_agent.py # 大纲、草稿、审查、终稿
│ │ ├── kb/ # Milvus 事实存储、就绪检查与重连
│ │ ├── search_cache.py # Redis 搜索缓存
│ │ └── llm/llm.py # OpenAI-compatible LLM
│ ├── eval/ # 评测框架与 Benchmark
│ ├── eval_runs/ # 固定集原始结果
│ └── test/ # 单元与回归测试
├── frontend/ # React + Vite Web UI
├── infrastructure/
│ ├── milvus/ # Milvus Docker Compose
│ └── redis/ # Redis Stack Docker Compose
├── docs/
│ ├── assets/ # README 图片与架构图
│ ├── plans/ # 已接受的工程设计与测试缝
│ └── reviews/ # 工程验证报告
├── Makefile # 非付费交付门禁
├── run_backend.sh
└── run_frontend.sh
规范驱动开发（SDD）与 AGENTS.md 的关系是什么？
请结合工程实践、工具链、风险和真实案例生成一份带来源引用的研究报告。
- Web Search 当前依赖 DashScope Application/MCP 配置。
- Milvus 保存提取后的事实记录，不保存原始文档 Chunk。
- Prompt Quality Guards 已增强事实约束，但覆盖度、时效性和来源分级仍需继续优化。
- 生产部署前需要补充鉴权、密钥管理、监控和更严格的安全策略。