[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-80931":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":11,"openIssues":13,"contributorsCount":12,"subscribersCount":12,"size":12,"stars1d":12,"stars7d":12,"stars30d":12,"stars90d":12,"forks30d":12,"starsTrendScore":12,"compositeScore":12,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":14,"fork":14,"defaultBranch":15,"hasWiki":16,"hasPages":14,"topics":17,"createdAt":9,"pushedAt":9,"updatedAt":18,"readmeContent":19,"aiSummary":20,"trendingCount":12,"starSnapshotCount":12,"syncStatus":21,"lastSyncTime":22,"discoverSource":23},80931,"NebulaNest_Agent_Console","ichliebewxy\u002FNebulaNest_Agent_Console","ichliebewxy","NebulaNest（星巢智能体控制台）是一个本地运行的 Agent + RAG 工作台。它把文档入库、混合检索、查询改写、工具调用、运行回调和人工审核放在同一个控制台里，适合做企业知识库问答、课程资料检索、客服辅助和可追踪的智能体实验",null,"Python",32,0,1,false,"main",true,[],"2026-06-12 02:04:08","# NebulaNest Agent Console\n\nNebulaNest（星巢智能体控制台）是一个本地运行的 Agent + RAG 工作台。它把文档入库、混合检索、查询改写、工具调用、运行回调和人工审核放在同一个控制台里，适合做企业知识库问答、课程资料检索、客服辅助和可追踪的智能体实验。\n\n![NebulaNest workflow](docs\u002Fassets\u002Fnebulanest-flow.png)\n\n## 项目亮点\n\n- 流式 Agent 对话：`\u002Fchat\u002Fstream` 通过 SSE 返回增量回答、RAG 步骤和最终 trace。\n- 本地知识库：上传 PDF、Word、PPT、Excel、CSV、TXT 后写入 Milvus。\n- 分层 RAG：L3 叶子块进入向量库，L1\u002FL2 父块进入本地 DocStore，检索后支持 auto-merging。\n- 混合检索：Dense embedding + BM25 sparse embedding + Milvus Hybrid Search，并用 RRF 融合。\n- 查询扩展：相关性不足时进入 LangGraph 节点，自动选择 Step-back、HyDE 或复杂组合策略。\n- 可选重排：支持接入 SiliconFlow rerank。\n- 可选 RAGFlow：外部召回结果可与本地 Milvus 结果融合去重。\n- MCP 地图工具：DashScope AMap MCP 使用独立的 `DASHSCOPE_MCP_API_KEY`。\n- 运行回调：MCP、天气、RAGFlow、Milvus 等失败会记录到 `data\u002Ftool_failures.json`，前端可重试或标记解决。\n- 人工审核：可把回答提交到审核队列，支持批准、驳回和修订。\n\n## 技术栈\n\n- 后端：FastAPI、Uvicorn、LangChain、LangGraph、Pydantic。\n- Agent 工具：LangChain tools、langchain-mcp-adapters、DashScope MCP。\n- 向量库：Milvus standalone、MinIO、etcd。\n- 检索：DashScope text embedding、Milvus Hybrid Search、BM25 sparse vector、RRF、可选 rerank。\n- 文档解析：`document_loader.py` 支持 PDF、Office、CSV、TXT 等格式。\n- 前端：Vue 3 CDN、SSE、Marked、Highlight.js、Font Awesome。\n\n## 目录结构\n\n```text\nbackend\u002F\n  app.py                  FastAPI 应用入口\n  api.py                  总路由聚合\n  routes_*.py             聊天、会话、文档、审核、回调路由\n  agent.py                Agent 初始化和同步\u002F流式对话\n  mcp_service.py          DashScope AMap MCP 加载与工具封装\n  settings.py             统一读取环境变量\n  embedding.py            Dense embedding + BM25 sparse embedding\n  milvus_client.py        Milvus 集合、查询、混合检索和自动重连\n  rag_utils.py            本地\u002FRAGFlow 检索编排\n  rag_pipeline.py         LangGraph RAG 主流程\n  rag_expanded.py         扩展查询后的多路召回节点\n  query_expansion.py      Step-back 与 HyDE\n  retrieval_steps.py      Rerank、auto-merging、去重\n  ragflow_client.py       可选 RAGFlow retrieval adapter\nfrontend\u002F\n  index.html              单页控制台\n  script.js               Vue 挂载入口\n  js\u002F*.js                 前端状态、聊天、知识库、审核、格式化逻辑\n  style.css               样式入口\n  css\u002F*.css               拆分后的样式模块\ndocs\u002Fassets\u002F\n  nebulanest-flow.png     README 逻辑总览图\ndata\u002F\n  documents\u002F              上传文件，本地运行数据，默认不提交\n  parent_chunks.json      L1\u002FL2 父块存储，默认不提交\n  tool_failures.json      工具失败与回调记录，默认不提交\ndocker-compose.yml        Milvus 依赖服务\n```\n\n## 运行流程\n\n### 1. 文档入库\n\n用户在前端知识库页上传文件，后端先保存原始文件，再由 `DocumentLoader` 解析文本。解析结果会生成 L1\u002FL2\u002FL3 三层块：父块保存在 `parent_chunks.json`，叶子块生成 dense embedding 和 sparse embedding 后写入 Milvus。这样既能检索到精确片段，也能在回答时上卷到更完整的上下文。\n\n### 2. 对话与检索\n\n前端把问题提交到 `\u002Fchat\u002Fstream`，`agent.py` 调用 LangChain Agent。Agent 根据问题选择本地知识库、天气、AMap MCP 或其他工具。知识库检索会先走 Milvus Hybrid Search，并可融合 RAGFlow 结果；如果相关性评估不足，LangGraph 会触发查询改写，再用 Step-back、HyDE 或复杂查询策略补召回。\n\n### 3. 回答生成\n\n检索结果会经过去重、可选 rerank 和 auto-merging。最终上下文交给模型生成回答，前端通过 SSE 实时显示回答内容、检索步骤、引用片段和 trace 信息。\n\n### 4. 质量闭环\n\n回答可以提交人工审核；工具或外部服务失败会进入运行回调队列。管理员可在前端把失败项标记为重试、已解决或忽略，避免静默失败。\n\n## 环境变量\n\n复制 `.env.example` 为 `.env`，再填入真实 Key。不要把真实 `.env` 提交到仓库。\n\n```env\nCHAT_MODEL=deepseek-v4-flash\nCHAT_API_KEY=...\nCHAT_BASE_URL=https:\u002F\u002Fapi.deepseek.com\nQUERY_EXPANSION_MODEL=deepseek-v4-flash\n\nDASHSCOPE_MCP_API_KEY=...\nAMAP_MCP_ENDPOINT=https:\u002F\u002Fdashscope.aliyuncs.com\u002Fapi\u002Fv1\u002Fmcps\u002Famap-maps\u002Fmcp\n\nDASHSCOPE_EMBEDDING_API_KEY=...\nDASHSCOPE_BASE_URL=https:\u002F\u002Fdashscope.aliyuncs.com\u002Fcompatible-mode\u002Fv1\nDASHSCOPE_EMBEDDING_MODEL=text-embedding-v3\n\nRERANK_MODEL=BAAI\u002Fbge-reranker-v2-m3\nRERANK_BINDING_HOST=https:\u002F\u002Fapi.siliconflow.cn\u002Fv1\u002Frerank\nRERANK_API_KEY=...\n\nAMAP_API_KEY=...\nMILVUS_HOST=127.0.0.1\nMILVUS_PORT=19530\nMILVUS_COLLECTION=embeddings_collection\n```\n\nKey 职责：\n\n- `CHAT_API_KEY`：主对话模型与查询扩展。\n- `DASHSCOPE_MCP_API_KEY`：高德地图 MCP，只用于 `mcp_service.py`。\n- `DASHSCOPE_EMBEDDING_API_KEY`：向量模型，只用于 `embedding.py`。\n- `RERANK_API_KEY`：重排模型，只用于 `retrieval_steps.py`。\n- `AMAP_API_KEY`：高德天气 REST API，不等于 MCP Key。\n\n## 启动\n\n1. 安装依赖：\n\n```powershell\nuv sync\n```\n\n2. 启动 Milvus 依赖：\n\n```powershell\ndocker compose up -d\n```\n\n3. 启动后端和前端静态页：\n\n```powershell\ncd backend\n..\\.venv\\Scripts\\python.exe app.py\n```\n\n4. 打开控制台：\n\n```text\nhttp:\u002F\u002F127.0.0.1:8000\n```\n\nAttu 管理界面默认地址：\n\n```text\nhttp:\u002F\u002F127.0.0.1:8080\n```\n\n后端默认使用 `8000`，避免与 `docker-compose.yml` 中 Attu 的 `8080` 冲突。需要修改时设置 `PORT`。\n\n## 常见问题\n\n### 终端显示 Agent 初始化完成，但前端仍有 `amap_mcp_init`\n\n先看终端是否显示 MCP 工具已加载。如果显示 MCP 未加载到工具，说明 Agent 本体启动成功，但 DashScope MCP 没拿到工具。重点检查：\n\n- `DASHSCOPE_MCP_API_KEY` 是否是开通 MCP 的 Key。\n- `AMAP_MCP_ENDPOINT` 是否正确。\n- 百炼控制台里的 AMap MCP 是否已开通，或是否需要重新开通升级协议。\n\n### Milvus 报 `closed channel`\n\n`milvus_client.py` 已支持 `closed channel` 自动重连并重试一次。若仍失败，检查 Milvus 容器健康状态：\n\n```powershell\ndocker ps\n```\n\n### 上传成功但搜索不到\n\n检查：\n\n- `DASHSCOPE_EMBEDDING_API_KEY` 是否有 embedding 额度。\n- Milvus `19530` 是否可用。\n- 上传文档是否生成 L3 叶子块。\n- `MILVUS_COLLECTION` 是否与当前服务一致。\n\n## 开发约定\n\n- 后端单文件尽量保持在 250 行以内。\n- 前端 JS\u002FCSS 已按功能拆分，`script.js` 和 `style.css` 只保留入口。\n- 不要在业务代码中硬编码真实 Key，只通过 `.env` 读取。\n- 工具失败不要静默丢弃，统一记录到 `tool_failures.json`。\n- `data\u002F`、`volumes\u002F`、`.env`、`.venv\u002F` 默认不提交，避免泄露运行数据和凭据。\n","NebulaNest（星巢智能体控制台）是一个本地运行的Agent + RAG工作台，集成了文档入库、混合检索、查询改写、工具调用、运行回调和人工审核等功能。项目核心功能包括流式Agent对话、本地知识库支持多种文件格式、分层RAG检索、混合检索策略以及可选重排和RAGFlow等。技术上采用FastAPI、LangChain、Milvus等组件构建后端，并使用Vue 3作为前端框架。适用于企业知识库问答、课程资料检索、客服辅助以及可追踪的智能体实验场景。",2,"2026-06-01 03:52:58","CREATED_QUERY"]