[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82273":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":12,"openIssues":13,"contributorsCount":13,"subscribersCount":13,"size":13,"stars1d":13,"stars7d":14,"stars30d":15,"stars90d":13,"forks30d":13,"starsTrendScore":13,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":13,"starSnapshotCount":13,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},82273,"deep-research-agent","956501819\u002Fdeep-research-agent","956501819","Agentic RAG 驱动的深度研究 Agent — Agent 自主拆解问题、选择检索策略、评估质量、自我纠正，最终生成带引用溯源的结构化研究报告。",null,"Python",101,8,0,23,69,58.26,false,"main",true,[],"2026-06-12 04:01:37","\u003Cdiv align=\"center\">\n\n# Deep Research Agent\n\n**一个面向复杂问题的 Agentic RAG 深度研究系统**\n\n让 Agent 自主完成问题拆解、检索策略选择、混合召回、Rerank 精排、质量评估、查询改写与带引用报告生成。\n\n\u003Cp>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.12+-3776AB?style=flat-square&logo=python&logoColor=white\" alt=\"Python\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FFastAPI-Backend-009688?style=flat-square&logo=fastapi&logoColor=white\" alt=\"FastAPI\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FVue_3-Frontend-42b883?style=flat-square&logo=vuedotjs&logoColor=white\" alt=\"Vue\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLangGraph-Agent-1f6feb?style=flat-square\" alt=\"LangGraph\" \u002F>\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FRAG-Hybrid%20%2B%20Rerank-7c3aed?style=flat-square\" alt=\"RAG\" \u002F>\n\u003C\u002Fp>\n\n\u003Cp>\n  \u003Ca href=\"#核心能力\">核心能力\u003C\u002Fa> ·\n  \u003Ca href=\"#系统架构\">系统架构\u003C\u002Fa> ·\n  \u003Ca href=\"#快速开始\">快速开始\u003C\u002Fa> ·\n  \u003Ca href=\"#配置说明\">配置说明\u003C\u002Fa> ·\n  \u003Ca href=\"#api-概览\">API 概览\u003C\u002Fa> ·\n  \u003Ca href=\"#测试与验证\">测试与验证\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003C\u002Fdiv>\n\n---\n\n## 项目简介\n\n传统 RAG 往往是一次性链路：用户提问 → 检索 → 回答。它不会主动判断检索结果是否足够好，也不会在信息不足时自动调整搜索方向。\n\n`Deep Research Agent` 将 RAG 升级为一个可观测、可重试、可扩展的研究型 Agent：\n\n```text\n用户问题\n  -> Query Decomposition：拆解为 2-5 个子问题\n  -> Strategy Routing：为每个子问题选择 semantic \u002F keyword \u002F hybrid\n  -> Hybrid Retrieval：向量检索 + BM25 + RRF 粗排\n  -> Optional Rerank：SiliconFlow Qwen Reranker 二阶段精排\n  -> Quality Critique：相关性 + 完整性双维度评估\n  -> Self Correction：失败时查询改写与策略升级重试\n  -> Synthesis：聚合多源信息并生成带引用的研究报告\n```\n\n---\n\n## 核心能力\n\n| 能力 | 说明 |\n|---|---|\n| 自主问题拆解 | 使用 LLM 将复杂问题拆成多个可独立检索的子问题 |\n| 自适应检索策略 | 根据问题类型选择 `semantic`、`keyword` 或 `hybrid` |\n| 中文关键词检索 | `BM25 + jieba` 中文词级分词，提升中文精确匹配效果 |\n| 混合检索 | 向量召回 + BM25 召回 + RRF 融合排序 |\n| 二阶段精排 | 可选接入 SiliconFlow `Qwen\u002FQwen3-Reranker-8B` |\n| 质量 Critique | 对检索结果进行相关性与完整性评分 |\n| 自我纠错 | 低质量结果会触发查询改写和策略升级，最多重试 3 次 |\n| 流式可视化 | FastAPI SSE 实时推送 Agent 执行过程到 Vue 前端 |\n| 文档管理 | 支持 PDF、DOCX、Markdown、TXT 上传、切块、嵌入和索引 |\n| 上传安全 | 单文件默认最大 `20 MB`，上传文件名会做安全清理 |\n\n---\n\n## 系统架构\n\n```mermaid\nflowchart TD\n    A[用户问题] --> B[Decomposition Node\u003Cbr\u002F>问题拆解与研究计划]\n    B --> C[Retrieval Node\u003Cbr\u002F>策略选择与多路召回]\n    C --> D[Hybrid Retrieval\u003Cbr\u002F>Vector + BM25 + RRF]\n    D --> E{Rerank enabled?}\n    E -- yes --> F[SiliconFlow Rerank\u003Cbr\u002F>Qwen\u002FQwen3-Reranker-8B]\n    E -- no --> G[Top-K Results]\n    F --> G\n    G --> H[Critique Node\u003Cbr\u002F>相关性\u002F完整性评分]\n    H --> I{质量通过?}\n    I -- 否，仍可重试 --> C\n    I -- 是或重试耗尽 --> J[Synthesis Node\u003Cbr\u002F>报告生成与引用标注]\n    J --> K[Vue 前端\u003Cbr\u002F>SSE 实时展示]\n```\n\n### Agent 状态流转\n\n```text\nDecomposition -> Retrieval -> Critique -> should_retry?\n                                         | \n                                         |-- retry -> Retrieval\n                                         |-- done  -> Synthesis -> END\n```\n\n---\n\n## 技术栈\n\n| 层级 | 技术 | 说明 |\n|---|---|---|\n| Agent 编排 | `LangGraph` | 显式状态流转与条件路由 |\n| 后端服务 | `FastAPI` + `SSE` | 异步 API 与流式进度推送 |\n| 前端界面 | `Vue 3` + `Vite` + `Naive UI` | 多页面交互式前端 |\n| LLM | SiliconFlow \u002F Qwen \u002F OpenAI-compatible | 多 Provider 统一封装 |\n| Embedding | `BAAI\u002Fbge-large-zh-v1.5` | 1024 维，支持本地\u002FAPI 双模式 |\n| 向量库 | Chroma \u002F Milvus \u002F Zilliz Cloud | 本地持久化或远程向量库 |\n| 关键词检索 | `rank-bm25` + `jieba` | 中文词级分词 + BM25 |\n| 混合排序 | RRF | 融合向量检索与 BM25 排名 |\n| Rerank | SiliconFlow Rerank | 可选 `Qwen\u002FQwen3-Reranker-8B` 二阶段精排 |\n| 配置管理 | `pydantic-settings` + `.env` | 类型安全环境变量配置 |\n\n---\n\n## 功能模块\n\n| 页面 | 路径 | 功能 |\n|---|---|---|\n| 深度研究 | `\u002F` | 提交复杂问题，查看 Agent 拆解、检索、评估、合成全过程 |\n| 快速检索 | `\u002Fquick-search` | 快速 RAG 问答，返回摘要和引用来源 |\n| 资料管理 | `\u002Fdocuments` | 上传、查看、删除知识库文档 |\n| 系统设置 | `\u002Fsettings` | 配置 LLM、Embedding、向量库、Rerank、Web Search |\n\n---\n\n## 快速开始\n\n### 1. 环境要求\n\n- Python `3.12+`\n- Node.js `18+` 推荐\n- SiliconFlow API Key，或其他 OpenAI-compatible API Key\n\n### 2. 安装依赖\n\n```bash\npip install -e \".[dev]\"\n```\n\n前端依赖会在 `.\u002Fstart.sh` 首次启动时自动安装，也可以手动安装：\n\n```bash\ncd frontend-vue\nnpm install\n```\n\n### 3. 配置环境变量\n\n```bash\ncp config\u002F.env.example config\u002F.env\nvim config\u002F.env\n```\n\n最小配置示例：\n\n```env\nLLM_PROVIDER=siliconflow\nLLM_MODEL=Qwen\u002FQwen3-8B\nLLM_API_KEY=sk-your-siliconflow-api-key-here\nLLM_BASE_URL=https:\u002F\u002Fapi.siliconflow.cn\u002Fv1\n\nEMBEDDING_MODE=api\nEMBEDDING_MODEL=BAAI\u002Fbge-large-zh-v1.5\nEMBEDDING_API_BASE_URL=https:\u002F\u002Fapi.siliconflow.cn\u002Fv1\nEMBEDDING_API_KEY=sk-your-siliconflow-api-key-here\n```\n\n### 4. 启动项目\n\n一键启动：\n\n```bash\n.\u002Fstart.sh\n```\n\n手动启动：\n\n```bash\n# 终端 1：后端\nuvicorn backend.main:app --reload --port 8000\n\n# 终端 2：前端\ncd frontend-vue && npm run dev\n```\n\n访问地址：\n\n| 服务 | 地址 |\n|---|---|\n| 前端 | `http:\u002F\u002Flocalhost:5173` |\n| 后端健康检查 | `http:\u002F\u002Flocalhost:8000\u002Fhealth` |\n| Swagger API 文档 | `http:\u002F\u002Flocalhost:8000\u002Fdocs` |\n\n---\n\n## 配置说明\n\n### LangSmith，可选\n\n开启后可在 LangSmith 查看 LangGraph 节点、LLM、Embedding、Rerank 和 Web Search trace。\n\n```env\nLANGSMITH_TRACING=true\nLANGSMITH_TRACING_V2=true\nLANGSMITH_API_KEY=lsv2-your-langsmith-api-key\nLANGSMITH_PROJECT=deep-research-agent\nLANGSMITH_ENDPOINT=https:\u002F\u002Fapi.smith.langchain.com\n# 兼容旧版 LangChain\u002FLangSmith tracing 开关\nLANGCHAIN_TRACING_V2=true\nLANGCHAIN_ENDPOINT=https:\u002F\u002Fapi.smith.langchain.com\n```\n\n### LLM\n\n```env\nLLM_PROVIDER=siliconflow\nLLM_MODEL=Qwen\u002FQwen3-8B\nLLM_API_KEY=sk-your-siliconflow-api-key-here\nLLM_BASE_URL=https:\u002F\u002Fapi.siliconflow.cn\u002Fv1\nLLM_TEMPERATURE=0.3\nLLM_MAX_TOKENS=4096\n```\n\n### Embedding\n\n```env\nEMBEDDING_MODE=api\nEMBEDDING_MODEL=BAAI\u002Fbge-large-zh-v1.5\nEMBEDDING_API_BASE_URL=https:\u002F\u002Fapi.siliconflow.cn\u002Fv1\nEMBEDDING_API_KEY=sk-your-siliconflow-api-key-here\n```\n\n### Rerank，可选\n\n默认关闭，避免额外 API 费用。开启后会先召回候选结果，再调用 SiliconFlow Rerank 精排。\n\n```env\nRERANK_ENABLED=false\nRERANK_PROVIDER=siliconflow\nRERANK_MODEL=Qwen\u002FQwen3-Reranker-8B\nRERANK_API_KEY=\nRERANK_BASE_URL=https:\u002F\u002Fapi.siliconflow.cn\u002Fv1\nRERANK_TOP_N=5\nRERANK_CANDIDATE_MULTIPLIER=4\nRERANK_TIMEOUT=30\n```\n\n说明：`RERANK_API_KEY` 留空时，会优先复用 `LLM_API_KEY`，其次复用 `EMBEDDING_API_KEY`。\n\n### 向量库\n\n默认使用本地 Chroma：\n\n```env\nRETRIEVAL_VECTOR_BACKEND=chroma\nCHROMA_PERSIST_DIR=.\u002Fdata\u002Fchroma_db\n```\n\n使用 Milvus \u002F Zilliz Cloud：\n\n```env\nRETRIEVAL_VECTOR_BACKEND=milvus\nMILVUS_URI=https:\u002F\u002Fyour-zilliz-endpoint\nMILVUS_TOKEN=your-zilliz-token\nMILVUS_COLLECTION_NAME=research_docs\n```\n\n### Web Search，可选\n\n```env\nMCP_WEB_SEARCH_ENABLED=false\nMCP_TAVILY_API_KEY=\nMCP_TAVILY_MAX_RESULTS=5\nMCP_WEB_SEARCH_TIMEOUT=30\n```\n\n---\n\n## 文档管理与上传安全\n\n支持上传：\n\n- `.pdf`\n- `.docx`\n- `.md`\n- `.txt`\n\n上传后会自动完成：\n\n```text\n保存文件 -> 文本解析 -> 分块 -> Embedding -> 写入向量库 -> 更新 BM25 索引\n```\n\n安全策略：\n\n| 项目 | 说明 |\n|---|---|\n| 大小限制 | 单文件默认最大 `20 MB` |\n| 安全文件名 | 清理路径分隔符、控制字符和异常符号 |\n| 格式限制 | 仅允许 PDF、DOCX、Markdown、TXT |\n| 失败清理 | 上传或索引失败时清理临时文件目录 |\n\n---\n\n## API 概览\n\n### Research API\n\n| 方法 | 路径 | 说明 |\n|---|---|---|\n| `POST` | `\u002Fapi\u002Fv1\u002Fresearch` | 提交深度研究任务 |\n| `GET` | `\u002Fapi\u002Fv1\u002Fresearch\u002F{task_id}\u002Fstream` | SSE 订阅研究过程 |\n| `GET` | `\u002Fapi\u002Fv1\u002Fresearch\u002F{task_id}` | 查询任务状态与结果 |\n| `POST` | `\u002Fapi\u002Fv1\u002Fresearch\u002F{task_id}\u002Fcancel` | 取消运行中的任务 |\n\n提交任务示例：\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:8000\u002Fapi\u002Fv1\u002Fresearch \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\":\"RAG 技术的演进阶段有哪些？\",\"enable_web_search\":false}'\n```\n\n### Quick Search API\n\n| 方法 | 路径 | 说明 |\n|---|---|---|\n| `POST` | `\u002Fapi\u002Fv1\u002Fquick-search` | 快速检索 + LLM 摘要 |\n\n```bash\ncurl -X POST http:\u002F\u002Flocalhost:8000\u002Fapi\u002Fv1\u002Fquick-search \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"query\":\"Transformer 的核心机制是什么？\",\"top_k\":5}'\n```\n\n### Documents API\n\n| 方法 | 路径 | 说明 |\n|---|---|---|\n| `GET` | `\u002Fapi\u002Fv1\u002Fdocuments` | 文件列表，包含已索引文档 |\n| `POST` | `\u002Fapi\u002Fv1\u002Fdocuments\u002Fupload` | 上传文档，默认最大 20MB |\n| `DELETE` | `\u002Fapi\u002Fv1\u002Fdocuments\u002F{file_id}` | 删除文档及关联 chunks |\n\n### Settings API\n\n| 方法 | 路径 | 说明 |\n|---|---|---|\n| `GET` | `\u002Fapi\u002Fv1\u002Fsettings` | 读取当前配置，API Key 掩码返回 |\n| `PATCH` | `\u002Fapi\u002Fv1\u002Fsettings` | 更新 LLM、Embedding、Retrieval、Rerank、MCP 等配置 |\n| `POST` | `\u002Fapi\u002Fv1\u002Fsettings\u002Ftest-connection` | 测试 LLM、Embedding、Milvus 连接 |\n| `GET` | `\u002Fapi\u002Fv1\u002Fsettings\u002Fsystem-info` | 查看向量库统计与版本信息 |\n\n---\n\n## 项目结构\n\n```text\ndeep-research-agent\u002F\n├── backend\u002F                         # FastAPI 后端\n│   ├── main.py                      # 应用入口、CORS、生命周期\n│   ├── routers\u002F                     # API 路由\n│   └── services\u002F                    # 任务管理服务\n├── config\u002F                          # pydantic-settings 配置\n│   ├── settings.py\n│   └── .env.example\n├── data\u002F                            # 示例文档、ChromaDB、上传文件\n├── frontend-vue\u002F                    # Vue 3 前端\n│   └── src\u002F\n│       ├── api\u002F                     # 后端 API 调用层\n│       ├── components\u002F              # UI 组件\n│       ├── composables\u002F             # SSE 等组合逻辑\n│       ├── pages\u002F                   # 页面\n│       └── stores\u002F                  # Pinia 状态\n├── mcp_servers\u002F                     # MCP Server 实现\n├── research_agent\u002F                  # 核心 Agent 逻辑\n│   ├── critique\u002F                    # 质量评估与重试控制\n│   ├── llm\u002F                         # 多 Provider LLM 客户端\n│   ├── planner\u002F                     # 查询拆解与研究计划\n│   ├── retrieval\u002F                   # 检索、BM25、Rerank、向量库\n│   │   ├── bm25.py                  # BM25 + jieba 中文分词\n│   │   ├── hybrid.py                # Vector + BM25 + RRF + Rerank\n│   │   ├── reranker.py              # SiliconFlow Rerank 客户端\n│   │   └── vector_store.py          # Chroma \u002F Milvus 向量库\n│   ├── synthesis\u002F                   # 报告生成与引用\n│   ├── graph.py                     # LangGraph 编排\n│   └── streaming.py                 # SSE 事件总线\n├── scripts\u002F                         # 索引和辅助脚本\n├── tests\u002F                           # 29 个测试用例\n├── pyproject.toml\n└── README.md\n```\n\n---\n\n## 测试与验证\n\nPython 测试：\n\n```bash\nPYTHONDONTWRITEBYTECODE=1 python3 -m pytest tests -q\n# 29 passed\n```\n\n前端构建：\n\n```bash\ncd frontend-vue\nnpm run build\n```\n\n真实接口连通性已验证：\n\n| 接口 | 结果 |\n|---|---|\n| LLM | 可正常回复 |\n| Embedding API | `api` 模式，返回 `1024` 维向量 |\n| SiliconFlow Rerank | `Qwen\u002FQwen3-Reranker-8B` 可正常排序 |\n\n---\n\n## 路线图\n\n| 阶段 | 方向 |\n|---|---|\n| V2 | Knowledge Graph 构建 + 多跳推理，NetworkX -> Neo4j |\n| V3 | 更多 MCP 数据源接入，例如 Notion、GitHub、数据库 |\n| V4 | Agent 记忆系统，多轮对话与用户画像 |\n| V5 | RAGAS 评估看板 + LangFuse 全链路追踪 |\n\n---\n\n## License\n\nMIT © 2025 Liu Yue\n\n---\n\n\u003Cdiv align=\"center\">\n\n**Built with LangGraph, FastAPI, Vue 3 and Agentic RAG**\n\n\u003C\u002Fdiv>\n","Deep Research Agent 是一个基于Agentic RAG的深度研究系统，能够自主拆解问题、选择检索策略、评估质量、自我纠正，并生成带引用溯源的结构化研究报告。该项目采用Python开发，利用FastAPI构建后端服务，Vue 3作为前端界面，结合LangGraph进行Agent编排，支持多种LLM模型如Qwen和OpenAI兼容模型，以及BAAI的bge-large-zh-v1.5嵌入模型。其核心功能包括自适应检索策略、混合检索机制（向量召回+BM25+RRF）、二阶段精排、质量Critique与自我纠错等，适用于需要对复杂问题进行深入分析并产出高质量报告的研究场景。",2,"2026-06-11 04:08:14","CREATED_QUERY"]