# enterprise-rag **Repository Path**: wenwang2000/enterprise-rag ## Basic Information - **Project Name**: enterprise-rag - **Description**: No description available - **Primary Language**: Python - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-13 - **Last Updated**: 2026-11-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 企业级 RAG 知识管理系统 基于 LlamaIndex 的企业级知识问答与管理系统,支持文档密级管理、RBAC 权限控制、多路检索、链路追踪、Token 统计、效果测评和缓存限流。 ## 功能特性 - **四级文档密级**:公开、内部、机密、绝密 - **三级 RBAC 权限**:普通用户 / 部门管理员 / 超级管理员 - **权限前置过滤**:从入库到检索到生成,全链路权限控制 - **多路检索融合**:Milvus 向量检索 + Elasticsearch 全文检索 + NebulaGraph 知识图谱,RRF 融合排序 - **全链路追踪**:完整记录请求链路、召回文档、Token 消耗、耗时,持久化到 MySQL - **Token 统计**:按用户/模型/时间维度统计调用次数、Token 数和费用 - **Ragas 效果测评**:内置 faithfulness / answer_relevancy / context_precision / context_recall 四维度指标 - **Redis 缓存 + 限流**:问答结果缓存,滑动窗口限流 - **审计日志**:所有关键操作留痕 - **统一审计字段**:所有数据表均含操作人、操作时间、更新人、更新时间,页面可直接查询 - **完整前端管理页面**:问答、文档、Token、链路追踪、测评、用户、审计、系统监控 ## 环境依赖 运行前请确保以下基础环境已启动: | 组件 | 默认端口 | 版本要求 | 备注 | |------|----------|----------|------| | MySQL | 3306 | 8.0+ | 业务数据持久化 | | Redis | 6379 | 6.0+ | 缓存与限流 | | Elasticsearch | 9200 | 7.17.x | 需安装 analysis-ik 中文分词插件 | | Milvus | 19530 | 2.4.x | 向量检索 | | NebulaGraph | 9669 | 3.6+ | 知识图谱 | | Python | - | 3.10+ | 运行环境 | 大模型任选一种:OpenAI GPT 系列、通义千问、本地部署(vLLM/Ollama 等 OpenAI 兼容接口)。 ## 快速启动 ```bash # 1. 配置环境变量 cp .env.example .env # 编辑 .env,修改数据库账号密码、ES/Milvus/Nebula 连接、LLM API Key 等 # 2. 一键启动(自动创建 venv、安装依赖、初始化库表与索引、启动服务) ./start.sh # 3. 访问 # 前端页面:http://localhost:8000/ # API 文档:http://localhost:8000/docs # 健康检查:http://localhost:8000/api/system/health # 4. 默认管理员账号 # 用户名:admin # 密码:admin123 # 首次登录后请修改密码 # 停止服务 ./stop.sh ``` `start.sh` 每次执行会先关闭已在运行的服务进程(依据 `server.pid` 与进程名匹配),再创建/复用项目专属虚拟环境 `.venv`,随后安装依赖、执行 `scripts/init_db.py`(幂等)并启动服务。 ## 数据库配置(密码支持特殊字符) `.env` 中推荐使用分开配置的方式,**密码可以包含 `@ : / # ? % &` 等任意特殊字符**(例如 `Oracle@2020`),程序会在拼接连接串时自动做 URL 编码,无需手动转义: ```ini MYSQL_HOST=127.0.0.1 MYSQL_PORT=3306 MYSQL_USER=rag_user MYSQL_PASSWORD=Oracle@2020 MYSQL_DATABASE=enterprise_rag MYSQL_CHARSET=utf8mb4 ``` 也支持直接给出完整连接串(`DATABASE_URL`),优先级高于上面的分散配置,密码同样支持 `@` `:` 等特殊字符: ```ini DATABASE_URL=mysql+pymysql://root:Oracle@2020@127.0.0.1:3306/enterprise_rag?charset=utf8mb4 ``` > 提示:直接用 `DATABASE_URL` 时,密码中的 `/`、`#`、`?` 按 URL 规范仍是分隔符,建议改用上面的 `MYSQL_PASSWORD` 分散配置以完全避免歧义。 ## 环境检查 启动前可用环境检查脚本验证五个中间件连通性: ```bash source .venv/bin/activate python scripts/check_env.py ``` 输出 `5/5 通过` 即表示所有中间件正常连接。 ## 目录结构 ``` enterprise-rag/ ├── app/ │ ├── auth/ # 认证与用户管理(JWT、RBAC) │ ├── core/ # 配置、LLM 封装、缓存、日志、审计 │ ├── documents/ # 文档管理(上传、版本、解析) │ ├── evaluation/ # Ragas 效果测评 │ ├── models/ # 数据模型(MySQL 表定义) │ ├── rag/ # RAG 核心(入库、检索、问答、重排) │ ├── schemas/ # Pydantic 请求/响应模型 │ ├── system/ # 系统监控与健康检查 │ ├── token_usage/ # Token 统计 │ └── tracing/ # 链路追踪 ├── static/ # 前端页面(单页应用) ├── scripts/ # 运维脚本 │ ├── init_db.py # 数据库/索引/图 schema 初始化(幂等,可重复执行) │ └── check_env.py # 中间件连通性检查 ├── docs/ # 项目文档 │ ├── README.md │ └── 二次开发手册.md ├── db/ # 预留目录(.gitkeep 占位) ├── logs/ # 日志目录(运行时自动生成) ├── uploads/ # 上传文件存储(运行时自动生成) ├── main.py # 应用入口 ├── requirements.txt # Python 依赖(含中文说明) ├── start.sh # 启动脚本 ├── stop.sh # 停止脚本 ├── Dockerfile # Docker 构建 └── .env.example # 环境变量模板 ``` ## 前端功能 | 功能模块 | 说明 | |----------|------| | 智能问答 | 问答对话、参考来源、RAG 统计 | | 文档管理 | 上传(含密级/部门/标签)、下载、详情、删除、版本管理 | | Token 统计 | 7 日趋势图、费用汇总、明细分页 | | 链路追踪 | 召回节点详情、Token 消耗、耗时、缓存命中标记 | | 效果测评 | 测试集管理、发起测评、四维度指标结果 | | 用户管理 | 新建、编辑、删除、角色/密级分配 | | 审计日志 | 全操作留痕(管理员) | | 系统监控 | 五组件健康状态、版本信息、响应耗时 | ## 常见问题 **Q:启动后 RAG 组件初始化延迟怎么办?** A:首次访问问答时会自动重试初始化;请先确认 Milvus 已启动、`MILVUS_HOST/PORT` 配置正确。 **Q:Elasticsearch 写入失败但不影响主流程?** A:日志会打印 warning,此时 ES 全文检索会降级为空,系统仍可正常运行;请检查 ES 端口、认证信息以及 analysis-ik 插件是否安装。 **Q:MySQL 密码含特殊字符连不上?** A:使用 `MYSQL_PASSWORD` 分散配置即可,无需手动转义,程序自动编码。 **Q:测评任务提交后一直是 running?** A:测评在后台线程异步执行,用例较多时请稍候;可查看 `logs/` 与任务状态,ragas 未安装时会自动回退到启发式评分。 **Q:如何切换到通义千问或本地模型?** A:默认已配置为本地 Ollama(`LLM_PROVIDER=local`),LLM 与 Embedding 共用 `http://127.0.0.1:11434/v1`,模型分别为 `qwen3.5:9b` 与 `qwen3-embedding:latest`;如需切换,修改 `.env` 中 `LLM_PROVIDER=openai/qwen/local` 并填写对应 endpoint、model 即可。 **Q:本地 Ollama 模型名怎么确认?** A:执行 `ollama list` 查看本地已拉取模型,确保 `.env` 中 `LOCAL_LLM_MODEL` 与 `LOCAL_EMBEDDING_MODEL` 与列表一致;`python scripts/check_env.py` 会自动探测模型是否存在以及 embedding 维度。