# RAG知识库

**Repository Path**: lkx2000/rag-knowledge-base

## Basic Information

- **Project Name**: RAG知识库
- **Description**: 企业级RAG系统设计与实现，包含问答系统
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 企业级 RAG 系统

> 基于 LangChain + FastAPI + Milvus + ElasticSearch + Celery 构建的生产级 RAG（Retrieval-Augmented Generation）系统，支持多租户、混合检索、流式对话、异步文档入库与全链路评估。

---

## 一、核心特性

| 维度 | 能力 |
|---|---|
| **多租户** | 租户 / 用户 / 知识库三层隔离，JWT 鉴权 |
| **文档解析** | PDF/Word/PPT/Excel/CSV/图片/Markdown 统一接入，复杂文档走 MinerU，结构化文档走 LangChain Loader |
| **异步入库** | FastAPI 毫秒级返回，Celery 后台异步解析→切分→向量化→入库；失败自动重试 |
| **混合检索** | Milvus 向量检索 + ElasticSearch 关键词检索，70/30 加权融合（也可切回 BM25 内存方案） |
| **结果重排** | CrossEncoder（bge-reranker-v2-m3）二次精排，提升 Top-K 准确率 |
| **对话能力** | 多轮会话、智能历史压缩（语义 + Token 双过滤）、问题改写、流式 SSE 输出、溯源引用 |
| **统一 LLM** | `utils/llm_client.py` 统一管理对话/Embedding 调用，支持 OpenAI 兼容 / 通义原生多厂商一键切换 |
| **可观测** | 检索评估（Recall/Precision/MRR）+ 生成评估（忠实度/相关性/幻觉/完整性）+ 端到端评估 + Markdown 报告 |
| **可部署** | Docker + Docker Compose 一键起 MySQL/Redis/Milvus/ES/FastAPI/Celery |

---

## 二、技术栈

| 类别 | 选型 |
|---|---|
| Web 框架 | FastAPI 0.136 + Uvicorn |
| LLM 框架 | LangChain 1.2 / langchain-classic / langchain-community |
| 向量库 | Milvus 2.4（生产级分布式） |
| 全文检索 | ElasticSearch 8.14（替代内存 BM25） |
| 关系库 | MySQL 8.0 |
| 缓存 / 队列 | Redis 7.2 |
| 异步任务 | Celery 5.6（solo 池，Windows 友好） |
| 鉴权 | JWT（python-jose）+ bcrypt 密码加密 |
| Embedding | 通义 text-embedding-v4（默认，1536 维） |
| LLM | 通义千问（默认，可切换 DeepSeek/OpenAI/Moonshot 等） |
| 重排 | BGE Reranker v2-m3（CrossEncoder，本地部署） |
| 文档解析 | MinerU API + LangChain Loader |
| 前端 | React + Vite（见 [web/README.md](web/README.md)） |
| 部署 | Docker + Docker Compose |

---

## 三、目录结构

```
企业级RAG实现/
├── app/                          # FastAPI 应用包（推荐入口）
│   ├── main.py                   # 应用工厂 create_app()
│   ├── api/v1/                   # 路由按业务域拆分
│   │   ├── auth.py               #   /token       登录
│   │   ├── documents.py          #   /document/*  文档上传/管理
│   │   ├── kb.py                 #   /kb/*        知识库管理
│   │   ├── chat.py               #   /chat/*      RAG 对话（流式）
│   │   ├── sessions.py           #   /session/*   会话/历史
│   │   ├── admin.py              #   /admin/*     管理后台
│   │   └── router.py             #   路由聚合器
│   └── core/                     # 基础设施层
│       ├── config.py             #   全局配置（兼容 utils.config）
│       ├── security.py           #   JWT / 密码
│       ├── logging.py            #   日志初始化
│       ├── exceptions.py         #   统一异常
│       └── constants.py          #   常量
│
├── services/                     # 业务服务层
│   ├── rag_service.py            #   RAG 对话核心（含流式、改写、检索、重排、生成）
│   └── document_service.py       #   文档上传/解析/入库编排
│
├── utils/                        # 工具层
│   ├── config.py                 #   配置加载（环境变量）
│   ├── llm_client.py             #   【统一 LLM 客户端】★ 多厂商/多模型切换
│   ├── db.py                     #   MySQL 连接池
│   ├── redis_utils.py            #   Redis 工具
│   ├── milvus_utils.py           #   Milvus 集合/连接管理
│   ├── es_utils.py               #   ElasticSearch 工具
│   ├── rag_utils.py              #   RAG 核心：切分/检索/重排/会话/日志
│   ├── celery_config.py          #   Celery 配置
│   ├── mineru_utils.py           #   MinerU 文档解析
│   ├── markdown_splitter.py      #   Markdown 结构化切分
│   ├── image_utils.py            #   图片处理
│   ├── oss_utils.py              #   阿里云 OSS
│   ├── prompt_loader.py          #   YAML Prompt 加载
│   └── security.py               #   兼容旧引用
│
├── celery_task.py                # Celery 异步任务定义
├── main.py                       # 旧入口（薄壳，向后兼容）
│
├── prompts/
│   └── rag_prompts.yaml          # Prompt 模板
│
├── evaluation/                   # 评估模块
│   ├── eval_dataset.py           #   数据集加载
│   ├── retrieval_evaluator.py    #   检索评估
│   ├── generation_evaluator.py   #   生成评估
│   ├── end_to_end_evaluator.py   #   端到端评估
│   ├── report_generator.py       #   报告生成
│   ├── run_eval.py               #   统一评估入口
│   └── sample_eval_data.json     #   示例数据
│
├── tests/                        # 测试
│   ├── test_rag.py               #   RAG 主流程
│   ├── test_celery.py            #   Celery 任务
│   ├── test_es.py                #   ES
│   ├── test_mineru.py            #   MinerU
│   ├── test_oss.py               #   OSS
│   ├── test_health_check.py      #   健康检查
│   └── milvus_tester.py          #   Milvus 探针
│
├── web/                          # 前端（React + Vite）
│
├── document_storage/             # 本地上传的文档
├── models/                       # 本地模型（如 reranker）
│
├── init.sql                      # MySQL 表结构
├── init_data.py                  # 初始数据
├── requirements.txt              # Python 依赖
├── Dockerfile                    # 镜像构建
├── docker-compose.yml            # 一键起全栈
├── openai.json                   # OpenAI 兼容端点配置
├── celery_task.py
└── main.py
```

---

## 四、快速开始

### 4.1 环境准备

- **Python 3.11+**
- **Docker 20+ / Docker Compose v2+**（推荐，最省事）
- 或者本地安装：MySQL 8.0、Redis 7.2、Milvus 2.4、ElasticSearch 8.14

### 4.2 克隆 & 安装依赖

```bash
git clone <your-repo>
cd 企业级RAG实现

# 推荐使用 conda
conda create -n rag python=3.11
conda activate rag
pip install -r requirements.txt
```

### 4.3 配置环境变量

复制并编辑 `.env`（参考下方"配置说明"章节）：

```bash
# 必填
DASHSCOPE_API_KEY=sk-xxx           # 通义千问 API Key
SECRET_KEY=your-jwt-secret          # JWT 签名密钥（生产必须改为强随机）

# 数据库
MYSQL_HOST=localhost
MYSQL_USER=root
MYSQL_PASSWORD=xxx
MYSQL_DB=enterprise_rag

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# Milvus
MILVUS_HOST=localhost
MILVUS_PORT=19530

# ElasticSearch
ES_URL=http://localhost:9200

# MinerU（复杂文档解析）
MINERU_API_KEY=your-mineru-key
```

### 4.4 初始化数据库

```bash
mysql -h$MYSQL_HOST -u$MYSQL_USER -p$MYSQL_PASSWORD < init.sql
python init_data.py                  # 插入默认租户/用户/知识库
```

### 4.5 启动服务

**方式 A：本地直接启动**

```bash
# 终端 1：FastAPI
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
# 旧入口也保留：uvicorn main:app

# 终端 2：Celery worker（Windows 务必加 -P solo）
celery -A celery_task worker -l info -P solo
```

**方式 B：Docker Compose 一键起（推荐）**

```bash
docker-compose up -d
# 自动起：MySQL / Redis / Milvus / ES / FastAPI / Celery Worker / Celery Beat
```

### 4.6 访问

| 地址 | 说明 |
|---|---|
| http://localhost:8000/docs | Swagger 接口文档 |
| http://localhost:8000/redoc | ReDoc 接口文档 |
| http://localhost:5173 | 前端（`cd web && npm run dev`） |

---

## 五、核心 API 速览

> 详细参数请访问 `/docs`。所有业务接口需 `Authorization: Bearer <token>` 头。

| 模块 | 方法 | 路径 | 用途 |
|---|---|---|---|
| 认证 | POST | `/token` | 登录获取 JWT |
| 知识库 | GET/POST | `/kb/list` `/kb/create` | 知识库 CRUD |
| 文档 | POST | `/document/upload` | 上传文档（异步入库） |
| 文档 | GET | `/document/list` | 文档列表 |
| 文档 | DELETE | `/document/{id}` | 删除文档（同步清理 Milvus/ES） |
| 会话 | GET/POST | `/session/list` `/session/create` | 会话管理 |
| 对话 | POST | `/chat/stream` | RAG 流式对话（SSE） |
| 评估 | POST | `/admin/eval/run` | 触发评估任务 |

### 调用示例

```bash
# 1. 登录
curl -X POST http://localhost:8000/token \
  -d "username=admin&password=admin123" \
  -H "Content-Type: application/x-www-form-urlencoded"
# → {"access_token": "eyJ...", "token_type": "bearer"}

# 2. 上传文档
curl -X POST "http://localhost:8000/document/upload?kb_id=kb_001" \
  -H "Authorization: Bearer eyJ..." \
  -F "file=@./test.pdf"
# → {"doc_id": "doc_xxx", "status": 0, "message": "已提交，后台处理中"}

# 3. 流式对话
curl -X POST http://localhost:8000/chat/stream \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"query": "介绍下产品", "session_id": "s_001", "kb_id": "kb_001"}'
```

---

## 六、统一 LLM 客户端（`utils/llm_client.py`）

集中管理对话和 Embedding 调用，**切换厂商/模型无需改业务代码**，只改环境变量。

### 公开 API

```python
from utils.llm_client import get_chat_model, get_embedding_model, reload

# 按角色获取对话 LLM
llm_main      = get_chat_model(role="main")       # 主对话（流式、temperature=0.3）
llm_rewrite   = get_chat_model(role="rewrite")    # 问题改写（非流式）
llm_evaluator = get_chat_model(role="evaluator")  # 评估打分（temperature=0.0）

# 获取 Embedding
embedding = get_embedding_model()

# 清空缓存（测试 / 热切换）
reload()
```

### 切换厂商示例

**默认（通义千问 OpenAI 兼容模式）：**
```bash
LLM_PROVIDER=openai_compat
DASHSCOPE_API_KEY=sk-xxx
LLM_MODEL=qwen3.6-plus
```

**切到 DeepSeek：**
```bash
LLM_PROVIDER=openai_compat
LLM_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-deepseek-xxx
LLM_MODEL=deepseek-chat
REWRITE_LLM_MODEL=deepseek-chat
```

**切到 OpenAI：**
```bash
LLM_PROVIDER=openai_compat
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-openai-xxx
LLM_MODEL=gpt-4o
```

**对话 OpenAI + Embedding 用通义原生 SDK：**
```bash
LLM_PROVIDER=openai_compat
LLM_BASE_URL=https://api.openai.com/v1
LLM_API_KEY=sk-openai-xxx
LLM_MODEL=gpt-4o
EMBEDDING_PROVIDER=dashscope
EMBEDDING_MODEL=text-embedding-v4
```

完整配置项见 [utils/config.py](utils/config.py) 的 `LLM_*` 系列环境变量。

---

## 七、配置说明（关键环境变量）

| 变量 | 默认值 | 说明 |
|---|---|---|
| `HOST` | `0.0.0.0` | FastAPI 监听地址 |
| `PORT` | `8000` | FastAPI 端口 |
| `MYSQL_*` | - | MySQL 连接配置 |
| `REDIS_*` | - | Redis 连接配置 |
| `MILVUS_HOST` | - | Milvus 地址 |
| `MILVUS_PORT` | `19530` | Milvus 端口 |
| `MILVUS_COLLECTION_PREFIX` | `enterprise_rag_` | 集合名前缀 |
| `ES_URL` | `http://localhost:9200` | ES 地址 |
| `LLM_PROVIDER` | `openai_compat` | LLM 厂商：`openai_compat` / `dashscope` |
| `LLM_API_KEY` | (回退 DASHSCOPE_API_KEY) | LLM 统一 Key |
| `LLM_BASE_URL` | (回退 DASHSCOPE_BASE_URL) | LLM 统一 BaseURL |
| `LLM_MODEL` | `qwen3.6-plus` | 主对话模型 |
| `REWRITE_LLM_MODEL` | `qwen3.6-flash` | 问题改写模型 |
| `EMBEDDING_MODEL` | `text-embedding-v4` | Embedding 模型 |
| `EMBEDDING_DIMENSIONS` | `1536` | Embedding 向量维度 |
| `EMBEDDING_PROVIDER` | (跟随 LLM_PROVIDER) | Embedding 厂商 |
| `LLM_TIMEOUT_MAIN` | `120` | 主对话超时（秒） |
| `LLM_TIMEOUT_REWRITE` | `60` | 改写超时（秒） |
| `LLM_TIMEOUT_EVALUATOR` | `60` | 评估超时（秒） |
| `CHUNK_SIZE` | `500` | 文档分块大小 |
| `CHUNK_OVERLAP` | `50` | 分块重叠 |
| `TOP_K` | `5` | 检索召回数 |
| `RERANK_TOP_K` | `3` | 重排后保留数 |
| `ENABLE_RERANK` | `true` | 是否启用 CrossEncoder 重排 |
| `MAX_HISTORY_ROUNDS_CACHE` | `50` | 会话历史缓存轮数 |
| `MAX_HISTORY_TOKENS` | `4000` | 历史最大 Token |
| `USE_ES_RETRIEVER` | `true` | `true`=Milvus+ES 混合；`false`=Milvus+BM25 内存 |
| `MINERU_API_KEY` | - | MinerU 复杂文档解析 Key |
| `FILE_STORAGE_TYPE` | `local` | `local` / `oss` |
| `OSS_*` | - | 阿里云 OSS（当 FILE_STORAGE_TYPE=oss） |
| `SECRET_KEY` | - | JWT 签名密钥（生产必须修改） |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `1440` | Token 有效期 |
| `CELERY_TASK_RETRY_MAX` | `3` | Celery 任务最大重试 |
| `CELERY_TASK_RETRY_DELAY` | `5` | 重试延迟（秒） |

---

## 八、RAG 核心流程

### 8.1 文档入库（异步）

```
用户上传 → services/document_service.upload_document
  ├─ 1. 计算 hash + 保存文件
  ├─ 2. 写 MySQL（status=0 处理中）
  ├─ 3. 投递 Celery 任务（async_process_document.delay）
  └─ 4. 毫秒级返回 doc_id

Celery Worker (celery_task.async_process_document)
  ├─ 1. utils.rag_utils.recursive_split_document    文档切分
  ├─ 2. utils.rag_utils.add_doc_to_vector_db        写入 Milvus
  ├─ 3. 索引到 ElasticSearch
  └─ 4. 更新 MySQL status=1
```

### 8.2 RAG 对话（流式）

```
用户提问 → services/rag_service.rag_chat_stream
  ├─ 1. JWT 鉴权 + 租户隔离
  ├─ 2. utils.rag_utils.rewrite_query              历史感知的问题改写
  ├─ 3. utils.rag_utils.get_smart_chat_history     智能历史（语义+Token）
  ├─ 4. utils.rag_utils.build_retriever            混合检索器
  │     └─ Milvus 向量 (k=TOP_K)  ⊕  ES 关键词 (k=TOP_K)  → 70/30 加权
  ├─ 5. utils.rag_utils.rerank_documents           CrossEncoder 重排 → Top RERANK_TOP_K
  ├─ 6. utils.rag_utils.format_context             上下文格式化（按 chunk_idx 排序）
  ├─ 7. Prompt 拼接 + LLM 流式生成（get_chat_model("main")）
  └─ 8. SSE 流式返回 + utils.rag_utils.save_chat_message + record_rag_log
```

---

## 九、测试

```bash
# RAG 主流程
python tests/test_rag.py

# Celery 任务
python tests/test_celery.py

# 健康检查
python tests/test_health_check.py

# Milvus 探针
python tests/milvus_tester.py
```

---

## 十、评估

```bash
# 准备评估数据集（参考 evaluation/sample_eval_data.json 格式）
cp evaluation/sample_eval_data.json evaluation/my_eval_data.json
# 编辑 my_eval_data.json，填入 query / expected_answer / relevant_doc_ids

# 一键全量评估（检索 + 生成 + 端到端）
python evaluation/run_eval.py --dataset evaluation/my_eval_data.json

# 报告输出到 evaluation/results/eval_report_<时间戳>.md
```

评估指标：

| 类别 | 指标 |
|---|---|
| 检索 | Recall@K / Precision@K / MRR / Hit Rate |
| 生成 | Faithfulness（忠实度） / Relevance（相关性） / Hallucination Rate（幻觉率） / Answer Similarity（相似度） / Completeness（完整性） |
| 端到端 | 任务完成率 / 平均响应时延 |

---

## 十一、生产部署清单

- [ ] 修改 `SECRET_KEY` 为强随机字符串
- [ ] 数据库密码 / Redis 密码 改为强密码
- [ ] 关闭 FastAPI `--reload`
- [ ] Celery worker 启用 `prefork` 池（Linux 生产环境）
- [ ] 启用 HTTPS（前置 Nginx / SLB）
- [ ] 配置日志收集（Filebeat / Loki）
- [ ] Milvus 改为分布式集群部署
- [ ] 监控告警（Prometheus + Grafana）
- [ ] 定期备份 MySQL / Milvus 元数据
- [ ] 启用 API 限流（slowapi / Kong）

---

## 十二、常见问题

**Q1：Windows 启动 Celery 报 `ValueError: not enough values to unpack`？**
A：Windows 默认的 prefork 池不兼容，务必加 `-P solo` 或 `-P eventlet`：
```bash
celery -A celery_task worker -l info -P solo
```

**Q2：上传文档后 Celery 报 `No module named 'services'`？**
A：在 `celery_task.py` 顶部已加 `sys.path` 防御性修复，确保从**项目根目录**启动 worker。

**Q3：Milvus 连接超时？**
A：检查 `MILVUS_HOST/PORT`，Docker 部署时需用服务名（`milvus`）而非 `localhost`。

**Q4：如何切换 LLM 厂商？**
A：改 `.env` 中 `LLM_PROVIDER` / `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL`，重启即可，**无需改代码**。详见 [第六章](#六统一-llm-客户端utilsllm_clientpy)。

**Q5：Embedding 维度变更后需要做什么？**
A：修改 `EMBEDDING_DIMENSIONS` + `EMBEDDING_MODEL` 后，**需清空 Milvus 旧集合重新入库**（维度不匹配会报错）。

---

## 十三、许可证

仅供学习与企业内部使用。