# EcoEquipRAG **Repository Path**: elfbobo_admin_admin/eco-equip-rag ## Basic Information - **Project Name**: EcoEquipRAG - **Description**: 环保设备运维 RAG 项目 - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-12-02 - **Last Updated**: 2025-12-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 环保设备运维RAG系统 后端精简架构设计（突出AI+RAG核心） ## 一、核心设计理念调整 langchain 架构，登录要求用明文密码（仅用于开发环境），用户权限基于角色（管理员/普通用户/访客）。session 管理基于 JWT，包含用户信息、权限校验、过期时间等。 用户权限，逻辑判断，根据用户角色，判断是否有对应权限，通过MySQL查询用户角色，判断是否有对应权限。 - 管理员：系统配置、用户管理、模型微调、日志监控等。 - 普通用户：设备检索、故障问答、运维建议等。 - 访客：仅能查看设备信息、故障码说明等。 session 管理，逻辑判断，通过MySQL查询session，根据JWT token，判断是否过期，过期则重新登录，未过期则继续处理。 - 登录：用户输入用户名密码，后端校验后返回 JWT token。 - 会话保持：后续请求在 header 中携带 token，后端校验权限后继续处理。 - 过期处理：token 过期后，前端自动触发重新登录流程。 密码存储，明文存储（仅用于开发环境），生产环境下，密码存储采用哈希算法（如bcrypt）存储。 模块化开发，清晰模块边界，核心组件为RAG系统的检索、融合、生成、会话增强模块，将非核心模块轻量化整合，不要出现冗余模块 fastApi 框架，实现RESTful API接口，提供用户登录、设备检索、故障问答、模型微调等功能。 企业级日志全链路追踪，支持RAG流程追踪、LLM调用日志、错误详情记录，通过日志分析，定位问题所在，快速修复。 数据库相关的配置，eco_equip_rag/config/config.ini已提供 本项目重难点，是大模型的集成与优化，如何将大模型的能力融入到RAG系统中，实现高效的运维问答，以及大模型的数据预处理、训练 微调与改写、部署等等 详细讲解大模型的数据集，包括数据采集、预处理、标注、存储等方面，以及数据在采集、预处理、标注、存储、模型训练、微调、改写、部署等环节的具体实现， 以及流转过程，包含数据从采集到模型训练再到部署的整个流程，详细讲解每个环节的具体实现，以及数据在每个环节的流转过程，数据数量、数据形状等。 聚焦**RAG核心链路**与**AI大模型能力**，砍掉冗余分层，将非核心模块轻量化整合。以“检索→融合→生成→会话增强”为核心骨架，业务适配（环保设备运维）嵌入核心流程，工程化能力作为支撑层简化实现，让架构直接体现AI项目特点。 ## 二、精简后后端目录结构（突出RAG+LLM） ``` eco-equip-rag/ ├── backend/ │ ├── eco_equip_rag/ # 核心代码（聚焦RAG+LLM） │ │ ├── api/ # 接口层（仅保留核心交互入口） │ │ │ ├── v1/ │ │ │ │ ├── rag.py # RAG核心接口（检索+问答） │ │ │ │ ├── llm.py # LLM相关接口（微调/改写） │ │ │ │ └── system.py # 轻量系统接口（配置/权限） │ │ │ └── deps.py # 接口依赖（权限/请求校验） │ │ ├── core/ # RAG+LLM核心层（架构核心） │ │ │ ├── retrieval/ # 检索管线（RAG核心） │ │ │ │ ├── retriever.py # 多路召回入口（稠密+稀疏+规则） │ │ │ │ ├── strategies.py # 融合策略（加权/RRF/学习融合） │ │ │ │ ├── reranker.py # 重排序（BGE Reranker） │ │ │ │ ├── filters.py # 业务过滤（设备/故障码等） │ │ │ │ └── rules.py # 规则路由（环保运维业务适配） │ │ │ ├── llm/ # AI大模型能力（核心模块） │ │ │ │ ├── qwen.py # Qwen模型封装（生成/改写） │ │ │ │ ├── prompt.py # Prompt工程（业务模板） │ │ │ │ └── finetune.py # LoRA微调入口（突出AI能力） │ │ │ ├── session/ # 会话增强（RAG上下文能力） │ │ │ │ ├── manager.py # 会话缓存+持久化 │ │ │ │ └── summary.py # 历史摘要+向量检索 │ │ │ └── rag_pipeline.py # RAG总流水线（检索→LLM→生成） │ │ ├── db/ # 存储层（轻量化整合） │ │ │ ├── models/ # SQLAlchemy模型（用户/会话） │ │ │ ├── vector/ # 向量库适配（Milvus/FAISS/PgVector） │ │ │ ├── search/ # 稀疏检索适配（ES/BM25） │ │ │ └── migrations/ # 数据库迁移（替代alembic独立目录） │ │ ├── config/ # 配置中心（轻量化） │ │ │ └── settings.py # 统一配置（RAG参数/LLM配置/数据库） │ │ ├── utils/ # 工具层（整合工程化能力） │ │ │ ├── logger.py # 日志（AI流程追踪） │ │ │ ├── exceptions.py # 异常处理（RAG/LLM专属异常） │ │ │ └── tools.py # 通用工具（文本处理/格式转换） │ │ ├── cli/ # 命令行工具（AI相关操作） │ │ │ ├── ingest.py # 数据摄入（构建索引） │ │ │ ├── index.py # 索引管理（向量+稀疏） │ │ │ └── finetune.py # 微调命令（LLM模型训练） │ │ └── main.py # 后端入口（FastAPI启动） │ ├── tests/ # 测试用例（聚焦RAG/LLM核心流程） │ ├── .env # 环境变量 │ ├── pyproject.toml # 依赖配置（已有） │ └── Dockerfile # 构建文件 └── ...（前端+部署文件同之前） ``` ## 三、核心模块精简设计（突出RAG+AI大模型） ### 3.1 核心层（core/）：RAG+LLM双核心驱动 #### 3.1.1 retrieval/：RAG检索核心（保留全部核心能力，精简目录） - 整合原“过滤DSL”“规则路由”到当前目录，避免跨模块跳转 - 核心逻辑聚焦“环保运维业务适配”：故障码、设备型号、工艺环节等过滤条件直接嵌入检索流程 - 关键优化：检索器初始化时直接加载业务规则，无需额外依赖注入，突出RAG“业务+检索”融合特点 #### 3.1.2 llm/：AI大模型能力（独立为核心模块，强化AI属性） - 聚合**查询改写**（多查询生成）、**回答生成**、**LoRA微调**三大核心AI能力 - Prompt工程针对性适配环保运维场景：预设“故障排查”“工单生成”“报警分析”专属模板 - 支持模型动态切换（DashScope/本地Transformers），通过配置文件一键切换，体现AI项目灵活性 #### 3.1.3 session/：RAG会话增强（突出上下文理解能力） - 整合“历史摘要”与“历史向量检索”，避免长对话遗忘，强化RAG优于传统检索的核心优势 - 轻量化实现：会话持久化直接调用db层，无需额外服务封装，聚焦“上下文增强AI生成效果” #### 3.1.4 rag_pipeline.py：总流水线（串联核心流程，体现RAG本质） - 唯一入口：`run(query, session_id, filters)` → 会话增强→多查询改写→多路检索→融合重排→LLM生成→返回结果 - 流程可视化：日志打印每一步耗时（检索耗时/LLM生成耗时），便于AI流程优化 - 业务嵌入：过滤条件（设备型号/故障码等）贯穿全流程，确保RAG结果贴合环保运维场景 ### 3.2 存储层（db/）：轻量化支撑，适配RAG核心需求 - 向量库/稀疏检索适配：抽象统一接口，支持热切换，但不做过度分层，直接提供`VectorStore`/`SparseSearch`类供检索核心调用 - 关系型数据库：仅保留“用户/会话/权限”核心表，支撑RAG系统落地，不扩展多余业务表 - 核心目标：为RAG+LLM提供高效存储支撑，不喧宾夺主 ### 3.3 接口层（api/）：极简入口，聚焦AI交互 - 仅保留3类核心接口，避免接口冗余： 1. RAG核心接口：`/api/v1/rag/query`（接收查询+过滤条件，返回AI回答+引用） 2. LLM能力接口：`/api/v1/llm/rewrite`（查询改写）、`/api/v1/llm/finetune`（微调触发） 3. 系统接口：`/api/v1/system/config`（RAG/LLM参数配置） - 接口设计突出AI特点：支持流式响应（LLM生成实时返回）、置信度返回、引用溯源 ### 3.4 工程化支撑（config/utils/）：轻量化，不抢核心风头 - 配置中心：统一管理RAG参数（融合权重/Top-K）、LLM参数（温度/最大tokens）、存储配置，支持动态调整 - 工具层：聚焦RAG+LLM专属工具（文本切片、向量归一化、Prompt格式化、日志追踪），砍掉通用冗余工具 - 异常处理：新增RAG专属异常（检索失败、模型调用失败）、LLM专属异常（微调失败、改写超时），精准定位AI流程问题 ## 四、核心流程精简（突出RAG+AI大模型联动） ```mermaid graph TD A[用户查询+业务过滤条件] --> B[会话增强（历史摘要+向量检索）] B --> C[LLM多查询改写（Qwen生成N个检索子查询）] C --> D[多路检索（稠密向量+稀疏检索+业务规则）] D --> E[融合策略（加权/RRF/学习融合）] E --> F[BGE重排序（提升相关性）] F --> G[LLM回答生成（基于检索结果+上下文）] G --> H[返回AI回答+引用溯源+置信度] ``` ## 五、精简架构核心优势（突出AI+RAG特点） 1. 核心聚焦：目录结构直接体现“RAG检索”“AI大模型”两大核心，无冗余分层 2. 流程连贯：RAG流水线贯穿始终，AI大模型（查询改写/回答生成/微调）深度嵌入核心流程 3. 业务贴合：环保运维业务规则（故障码/设备型号）直接融入检索核心，不单独拆分 4. 工程化高效：轻量化支撑模块，减少开发维护成本，聚焦AI能力落地 5. 可扩展性：保留核心组件抽象（向量库/LLM模型），支持AI技术栈升级（如替换为GPT-4o/新向量库） ## 六、结尾交付物提议 要不要我帮你生成**RAG核心流水线（rag_pipeline.py）的完整代码实现**，以及**LLM查询改写+回答生成的Prompt模板（适配环保设备运维场景）**，直接落地核心AI+RAG能力？ \n+## 七、启动与开发（Windows） ### 后端启动（Poetry） ```powershell # 安装依赖 poetry install # 启动 FastAPI 后端（默认 8000 端口） poetry run uvicorn eco_equip_rag.main:app --reload --host 0.0.0.0 --port 8000 ``` ### 前端启动 ```powershell cd eco_equip_rag_web npm install # 开发模式启动 npm run dev # 如需对接真实后端（关闭 mock）：在当前终端临时设置环境变量（PowerShell） $env:VITE_USE_MOCK='false' $env:VITE_API_BASE='http://localhost:8000/' npm run dev # 生产构建与本地预览 npm run build npm run preview ``` ### 调试模式（后端+前端） ```powershell # 后端启动（FastAPI） poetry run uvicorn eco_equip_rag.main:app --reload --host 127.0.0.1 --port 8000 # 初始化ES样本数据（可扩容） Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/v1/rag/seed/es?n=50 | ConvertTo-Json -Compress # 检索调试（确认“值机”可命中） Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8000/v1/rag/debug/es -Body (@{ query = '值机'; topK = 5 } | ConvertTo-Json) -ContentType 'application/json' | ConvertTo-Json -Compress # SSE流式调试（浏览器直接访问） # http://127.0.0.1:8000/v1/rag/debug/sse # 前端流式调试日志开关 cd eco_equip_rag_web $env:VITE_DEBUG_STREAM='true' npm run dev ```