基于 LlamaIndex 和 FastAPI 构建的企业级 RAG（检索增强生成）知识库后端系统。 支持完全私有化部署，具备多租户权限隔离、LDAP 统一认证、文档溯源高亮及会话持久化等企业级特性。 本项目是本人业余时间的开发成果，仅供学习交流使用，严禁商业用途（个人和企业可以免费使用）。
前端项目地址：Enterprise RAG Knowledge Base (Frontend)
💡 说明：本文档包含架构图和数据流图，推荐在 GitHub/GitLab 网页端查看，或在本地安装 Mermaid 预览插件。
-
🔐 企业级安全架构
- RBAC 权限控制：基于角色的权限管理（管理员/普通成员）。
- 多租户隔离：通过
workspace_id实现部门级数据物理/逻辑隔离。 - 双模认证：支持本地账号与 LDAP/AD 域账号 混合登录，自动同步组织架构。
-
🧠 全能型 RAG 引擎
- Ollama 驱动：LLM (
qwen2.5) 和 Embedding (bge-m3) 均由 Ollama 服务统一管理，降低后端资源占用。 - 精准重排序：内置本地 BGE-Reranker 模型（打包于镜像中），大幅提升检索准确率。
- 智能切片：集成 PyMuPDF，支持 PDF/Word/Excel 等多格式文档的高精度解析与切分。
- Ollama 驱动：LLM (
-
💬 深度交互体验
- 会话持久化：完整保存历史对话记录，支持断点续聊。
- 引用溯源：返回精准的文档切片位置，支持前端 PDF 原文高亮定位。
- 流式响应：全异步
StreamingResponse，提供丝滑的打字机体验。
-
🐳 一键部署
- 开箱即用：后端镜像内置 Reranker 模型，无需额外下载。
- 容器编排：提供完整的
docker-compose.yml，一键拉起全套服务。
这是一个专为数据安全敏感型企业打造的 RAG（检索增强生成）知识库系统。 本项目旨在解决企业内部知识管理的痛点，提供从底层模型到上层 UI 的全链路私有化解决方案，确保数据不出域，断网环境亦可全功能运行。
- 无需联网：系统内置所有依赖包与 AI 模型（Embedding/Rerank），支持在物理隔离的内网环境一键 Docker 部署。
- 数据安全：所有数据（向量、文档、对话日志）均存储在本地 PostgreSQL，无第三方 API 调用风险。
- 部门级隔离：实现了基于
Workspace的多租户逻辑。研发部的文档，财务部不可见，从底层向量检索阶段即进行物理/逻辑隔离。 - 无缝认证：支持 Local + LDAP/AD 双模认证。企业域账号直接登录，自动同步组织架构，管理员可进行细粒度的人员与部门管理。
我们不盲目追求大参数，而是追求效果与资源的最佳平衡：
- LLM (Ollama)：选用
Qwen2.5系列。在中文理解、指令遵循上表现优异，且通过 Ollama 部署可大幅降低显存门槛。 - Embedding (Ollama/BGE-M3)：选用
BAAI/bge-m3。- 选择理由：支持 8192 超长上下文（优于 BERT 的 512），完美适配长文档切片；具备 SOTA 级别的多语言与中文检索能力。
- Rerank (Local Python)：内置
BAAI/bge-reranker-base。- 选择理由：这是 RAG 精度的关键。在向量粗排后进行精排，能有效解决“搜到了但相关性不高”的问题，显著减少大模型幻觉。
- 精准溯源高亮：不同于普通的“显示引用文件”，本系统实现了PDF/TXT 原文级高亮定位。点击引用，弹窗自动滚动并高亮具体的段落，所见即所得。
- 上下文记忆：基于数据库持久化的会话管理，刷新不丢失。支持多轮对话，模型能理解“它”、“上面提到的”等指代词。
- 全格式支持：集成了 PyMuPDF 等解析器，支持 PDF、Word、Excel、Markdown 等多种格式的深度解析与智能切片。
- 提供可视化的管理仪表盘，管理员可实时监控知识库文档总量、问答活跃度趋势、文件类型分布及系统健康状态。
系统采用 计算分离 架构：Ollama 负责繁重的生成与向量化计算，Python 后端负责业务逻辑与轻量级重排序。
graph TD
%% ==== Client Layer ====
Client["前端（Vue3 / Web）"] -->|"REST API + Bearer Token"| Gateway["Nginx / FastAPI Router"]
%% ==== Backend Core ====
subgraph Backend_Service["后端服务（Python）"]
Gateway --> Auth["认证模块（OAuth2 / LDAP）"]
Gateway --> Manager["业务逻辑层"]
%% ==== RAG Engine ====
subgraph RAG_Engine["RAG 引擎（LlamaIndex）"]
Manager --> Ingestion["文档解析与切片（PyMuPDF）"]
Manager --> Retrieval["混合检索器（向量 + 关键词）"]
Manager --> ChatEngine["对话引擎（Context Mode）"]
Retrieval --> Reranker["本地重排序模型（BGE-Reranker）"]
Ingestion --> EmbedModel["向量化模型（BGE-M3 Small）"]
end
end
%% ==== Data Layer ====
subgraph Data_Storage["数据存储"]
PG["PostgreSQL（pgvector）"]
FileSys["文件存储（files）"]
end
%% ==== External / Local Services ====
subgraph External_Services["外部 / 本地服务"]
Ollama["Ollama - Qwen2.5 模型服务"]
LDAP["企业 LDAP / AD Server"]
end
%% ==== Cross-layer Connections ====
Auth <--> LDAP
Auth <--> PG
Retrieval <--> PG
Manager --> FileSys
ChatEngine <--> Ollama
描述了用户与系统及其外部实体的核心数据交互流程。
graph LR
%% ==== Actors ====
User["普通用户"]
Admin["管理员"]
%% ==== System Core ====
System["企业知识库后端系统"]
%% ==== External Systems ====
DB["PostgreSQL 数据库"]
LLM["Ollama 模型服务"]
LDAP["LDAP 认证源"]
%% ==== User Interactions ====
User -->|"1. 提问 / 查询"| System
User -->|"2. 上传文档"| System
Admin -->|"3. 用户 / 部门管理"| System
%% ==== System Dependencies ====
System -->|"4. 账号验证"| LDAP
System -->|"5. 存取向量 / 元数据 / 历史记录"| DB
System -->|"6. 生成回答（Context）"| LLM
%% ==== Output ====
System -->|"7. 返回答案 + 引用来源"| User
- Runtime: Python 3.10+
- Web Framework: FastAPI
- RAG Framework: LlamaIndex (v0.10+)
- Database: PostgreSQL 16 (with
pgvectorextension) - AI Engine:
- Ollama: 运行
qwen2.5:3b(Chat) 和bge-m3(Embedding) - Local Python: 运行
BAAI/bge-reranker-base(Rerank)
- Ollama: 运行
- Deployment: Docker & Docker Compose
- 宿主机安装 Docker & Docker Compose。
- 宿主机安装 Ollama 并拉取模型：
ollama pull qwen2.5:3b ollama pull bge-m3 ollama run qwen2.5:3b
- 拉取前后端代码并且放在同一个文件夹下面
enterprise_kb/ # 假设总目录是enterprise_kb
├── llamaindex_rag # 后端
├── llamaindex_rag_front # 前端
为了实现 Rerank 功能的离线运行，请下载 BAAI/bge-reranker-base 模型文件放入 models/bge-reranker-base/ 目录。该目录会被打包进 Docker 镜像。
具体方法参考后端models目录下的readme.txt文件
按 docker-compose.yml 上的说明修改文件
在后端项目根目录llamaindex_rag下执行：
docker-compose up -d --build首次启动时，系统会自动执行以下初始化操作：
- 数据库：自动创建表结构（包含向量表）。
- 组织架构：创建默认公共部门 (
global)。 - 管理员：创建默认超级管理员账号。
- 账号:
admin@internal.com - 密码:
admin123(请登录后立即修改)
- 账号:
核心配置位于 docker-compose.yml 或 .env 文件：
| 变量名 | 说明 | 默认值 |
|---|---|---|
DB_HOST |
数据库地址 | localhost:5432 |
OLLAMA_BASE_URL |
Ollama 服务地址 | http://localhost:11434 |
LDAP_SERVER |
LDAP 服务器地址 | ldap://localhost:389 |
EMBED_MODEL_NAME |
嵌入模型名称 | bge-m3 |
EMBEDDING_DIM |
向量维度 | 1024 (对应 BGE-M3) |
在 docker-compose.yml 中：
environment:
- DB_HOST=db
- OLLAMA_BASE_URL=http://host.docker.internal:11434 # 指向宿主机 Ollama
- EMBED_MODEL_NAME=bge-m3 # 指定 Ollama 中的模型名
- EMBEDDING_DIM=1024 # BGE-M3 的维度llamaindex_rag/
├── main.py # 程序入口，负责 App 组装
├── rag_engine.py # LlamaIndex 核心配置 (单例模式)
├── dependencies.py # FastAPI 依赖注入 (DB, Auth)
├── database.py # 数据库连接池
├── models.py # SQLAlchemy 数据模型
├── routers/ # 业务路由模块
│ ├── auth.py # 登录认证
│ ├── chat.py # 问答与会话管理
│ ├── documents.py # 文档上传、解析与切片
│ ├── files.py # 文件预览流 (支持断点续传)
│ ├── admin.py # 部门人员管理
│ └── dashboard.py # 统计报表数据
├── test/ # 测试脚本目录
│ └── init_ldap_data.py # 测试用 LDAP 初始化脚本
├── files/ # 持久化文件存储目录
├── init_sql/ # PG数据库初始化目录
│ └── init.sql # PG数据库初始化脚本
├── models/ # 本地 Reranker 模型 (构建时打入镜像)
├── .env # 环境变量配置文件
├── requirements.txt # Python 依赖列表
├── docker-compose.yml # 容器编排配置文件（LDAP是测试用的可以删除）
└── Dockerfile # 容器构建描述文件
如果需要在本地环境开发：
- 准备环境:
conda create -n rag_backend python=3.10 conda activate rag_backend pip install -r requirements.txt
- 数据库准备:
安装 PostgreSQL(16) 并创建数据库，确保
pgvector扩展已启用。 执行初始化脚本：psql -h localhost -U your_user -d your_db -f init_sql/init.sql
- 启动 LDAP 服务（可选，如果公司环境有可以用公司环境的ldap服务）:
如果需要测试 LDAP 功能，可以使用 Docker 启动一个测试用的 LDAP 服务器：
并使用
docker run -d -p 389:389 --name test-ldap osixia/openldap:1.5.0
test/init_ldap_data.py脚本初始化测试数据。 - 修改环境变量:
按照上述数据库和ldap环境修改
.env文件 - 准备模型:
请确保
models/bge-reranker-base目录下有模型文件。 - 启动ollama:
宿主机安装 Ollama 并拉取模型：
ollama pull qwen2.5:3b ollama pull bge-m3 ollama run qwen2.5:3b
- 启动服务:
访问 Swagger 文档：
python main.py
http://localhost:8000/docs
现在的 RAG 能跑通，但面对复杂问题可能还不够精准。
-
混合检索 (Hybrid Search)：
- 痛点：纯向量检索对于“精确匹配”（如搜索合同号
HT-2023-001或专有名词）效果很差。 - 方案：引入 BM25 关键词检索。LlamaIndex 支持 PGVector 的混合检索模式。
- 实现：同时进行
Vector Search+Keyword Search，然后用Reciprocal Rank Fusion (RRF)算法合并结果，最后再 ReRank。
- 痛点：纯向量检索对于“精确匹配”（如搜索合同号
-
元数据增强 (Metadata Extraction)：
- 方案：在上传文档时，让 LLM 自动提取摘要、关键词、年份等元数据存入数据库。
- 效果：用户可以问“2023年的财务报表”，系统能通过 Metadata Filter 精准过滤年份，而不是靠语义去猜。
-
复杂文档解析 (LlamaParse / OCR)：
- 痛点：现在的方案对于扫描件 PDF 还是无能为力。
- 方案：引入 OCR 引擎（如 PaddleOCR）或接入云端解析服务（如果允许的话），处理表格和扫描件。
-
前端高亮增强 (Highlight)：
- 痛点：高亮位置不对，特别是对于非txt文档。
- 方案：增强前端高亮定位文本算法，结合第1条改进。
让系统“活”起来，不仅能查，还能进化。
-
后台日志与监控：
- 集成 LangFuse 或 Arize Phoenix（LlamaIndex 原生支持）。
- 效果：可以看到每一个 Request 的完整链路：检索了哪些块？相似度多少？LLM 输入了什么？输出了什么？耗时多少？
- 这是排查“为什么 AI 胡说八道”的终极工具。
-
知识库“重索引”功能：
- 痛点：如果哪天想换更强的 Embedding 模型（比如 BGE-M4），现在的数据库就废了。
- 方案：在后台增加一个“重建索引”按钮。后台任务自动读取
uploads/目录下的源文件，重新切片、重新 Embedding 入库。
本项目采用 AGPL-3.0 许可证，这意味着：
- 您可以自由地使用、修改和分发本项目，但必须遵守 AGPL-3.0 协议要求
- 闭源商用需要购买商业授权
- 项目的重要贡献者可免费获得商业授权
强烈建议优先考虑AGPL-3.0合规方案。如有商业授权疑问，请邮件联系作者