这是一个面向学习展示的 RAG Agent 开源项目RAG_4study_project，核心是做工业级可用、过程可观测的检索增强生成，方便开发迭代和效果展示，以下是重新整理后的项目说明： 一、本地部署步骤
- 环境准备
需要提前装好：Python 3.12 及以上版本；包管理推荐用uv，也可以用原生 pip；需要 Docker 和 Docker Compose 来启动依赖的 Milvus 向量库。 2. 安装依赖
两种安装方式二选一：
推荐 uv 方式：在项目根目录执行uv sync完成依赖安装，之后可以用uv run python backend/app.py或者uv run uvicorn backend.app:app --host 0.0.0.0 --port 8000 --reload启动服务。 pip 方式：先创建虚拟环境python -m venv .venv，激活后升级 pip，执行pip install -e .安装依赖，之后用相同命令启动服务即可。 3. 配置环境变量
在项目根目录新建.env文件，按照模板填入配置：大模型的 API 密钥、模型名称、接口地址、嵌入模型名称；重排序模型配置（可选，不配置会自动降级）；Milvus 的地址和端口；可选的高德天气 API 密钥（用来做自定义工具演示）。 4. 启动 Milvus 向量库
项目自带的docker-compose.yml已经配置好了 Milvus 以及依赖的 etcd、minio、管理面板 Attu，执行docker compose up -d就能后台启动，Milvus 默认端口 19530，Attu 管理面板默认端口 8000。 5. 访问应用
Milvus 启动完成后，启动后端应用，就可以浏览器访问了：前端主页地址是http://127.0.0.1:8000/，接口文档地址是http://127.0.0.1:8000/docs。 二、项目整体介绍 核心能力
基于 LangChain Agent 做定制化，支持自定义工具；用户上传文档后会做三级滑动窗口分块，仅最小的叶子分块转向量存入 Milvus，父级分块存在本地文档库；自带会话记忆和自动摘要，支持长对话上下文保留。 整体运行架构：FastAPI 后端 + 纯 Vue3 CDN 单页前端 + Milvus 向量库。 核心特色 / 创新点
这个项目实现了很多工业级 RAG 的实用特性：
混合检索：同时做语义稠密向量 + BM25 关键词稀疏向量检索，用 Milvus 混合搜索 + RRF 排序融合结果，兼顾语义理解和关键词匹配 精排可可视化：召回后接入 Jina 重排序做精排，重排序分数可以直接在前端展示 稳定性降级：混合检索或者稀疏检索出问题时，会自动降级为纯稠密向量检索，不会整体报错 原生流式输出：后端逐 token 推送结果，前端用 SSE 实现打字机效果 RAG 过程实时可视化：模型生成回答前，检索的每一步都会提前展示给用户，不会出现长时间静默等待 回答随时终止：支持用户随时中断正在生成的回答，后端会立刻停止推理，真正节省 token 和资源 会话压缩管理：旧对话会自动做摘要，既保留长上下文，又控制 token 数量不超标 全链路文档处理：从上传、切分、生成向量到入库自动化完成，重复上传会自动清理旧数据 三级分块 + 自动合并：把文档分成大、中、小三层，检索先召回小块，满足条件后自动合并回父块，既保证检索精度又保留完整上下文 轻量化存储：仅叶子小块存向量，父块存在本地，减少向量冗余，还保留上下文聚合能力 工具易扩展：已经做好天气查询示例，新增第三方 API、企业数据源非常方便 全链路可观测：检索、评分、重写、来源所有信息都记录，前端可以展开查看每一步细节 智能查询重写：支持 Step-Back、HyDE 两种重写策略，会自动根据情况选择，需要时才重写查询二次检索 相关性门控：会先判断召回文档的相关性，不够用才触发重写，避免无效计算 实时思考展示：通过异步技术穿透，Agent 做检索、评分、重写每一步都实时推前端，解决了传统 RAG 的 "静默思考" 问题 三、目录与核心流程 目录结构
backend/后端：各个文件职责清晰，从入口、接口、Agent、工具、文档处理、向量存储到 Milvus 交互都做了分层 frontend/前端：三个文件实现整个交互界面，纯静态无需额外构建 data/：存落地的会话历史、父块数据、上传的原文档 向量库：Milvus，支持 docker 启动或者自建服务接入 核心流程
用户问答全链路：用户前端提问→调用流式接口→后端返回 SSE 流→Agent 判断问题类型调用对应工具→知识库检索会实时推送每一步→Agent 流式生成回答推前端→前端打字机展示→对话落盘存历史 RAG 检索流程：初次召回叶子块→重排序→自动合并父块→相关性打分（合格直接生成，不合格触发重写）→选择重写策略→重写后二次召回→去重后给 Agent 生成回答→全链路信息留存可观测 文档入库流程：前端上传 PDF/Word→三级分块打标签→父块存本地→叶子块生成两种向量→仅叶子块写入 Milvus→完成入库可被检索 会话记忆流程：按用户、会话存对话→太长自动摘要压缩→前端支持增删查历史会话 四、关键技术实现细节
跨线程实时推送解决阻塞问题：FastAPI 的异步事件循环在主线程，同步 RAG 工具放线程池避免阻塞主线程，项目通过 "主线程提前捕获事件循环 + 线程安全回调" 的方案，实现子线程的 RAG 步骤能实时推给主线程，不会丢消息也不阻塞。 自研混合检索双塔：不是简单调用 Milvus 接口，自己实现了 BM25 稀疏向量生成，搭配稠密向量，Milvus 同时检索后用 RRF 无参数融合结果，不用人工调权重，效果稳定。 前端无缝状态切换：前端做了微型状态机，同一个气泡从 "思考→展示检索步骤→输出回答" 无缝切换，不会出现两个气泡跳转的突兀体验。 确定性终止能力：前端用 AbortController 取消请求，后端显式捕获断开信号，主动取消 Agent 后台任务，立刻停止大模型推理，真正做到节省资源，避免无效计算。