100d1a06eb
- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
451 lines
16 KiB
Markdown
451 lines
16 KiB
Markdown
# RAG 服务架构与部署方案
|
||
|
||
## 一、系统架构概览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 前端应用 │
|
||
│ (Vue/React Web/App) │
|
||
└─────────────────────────────────────┬───────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────────────────────┐
|
||
│ 后端网关 │
|
||
│ (Nginx / API Gateway / Spring Cloud) │
|
||
│ │
|
||
│ 职责： │
|
||
│ • 用户认证 (登录/Token验证) │
|
||
│ • 权限控制 (角色/部门/接口权限) │
|
||
│ • Header 注入 (X-User-ID, X-User-Role, X-User-Department) │
|
||
│ • 请求路由与负载均衡 │
|
||
└─────────────────────────────────────┬───────────────────────────────────────┘
|
||
│
|
||
┌─────────────────┴─────────────────┐
|
||
│ │
|
||
▼ ▼
|
||
┌───────────────────────────────┐ ┌───────────────────────────────────────┐
|
||
│ 后端业务服务 │ │ RAG 服务 │
|
||
│ (Java/Spring Boot/Go) │ │ (Python/Flask) │
|
||
│ │ │ │
|
||
│ 职责： │ │ 职责： │
|
||
│ • 用户账户管理 │ │ • 向量存储 (ChromaDB) │
|
||
│ • 组织架构/角色权限 │ │ • BM25 索引 │
|
||
│ • 会话管理 (对话历史) │ │ • 文档解析与分块 │
|
||
│ • 审计日志 │ │ • 知识库问答 (RAG) │
|
||
│ • 反馈记录 │ │ • 文档同步与向量化 │
|
||
│ • 业务主数据 (学生/课程等) │ │ • 出题能力 │
|
||
│ • 题库/试卷管理 │ │ │
|
||
│ │ │ │
|
||
│ 数据库： │ │ 数据存储： │
|
||
│ • MySQL/PostgreSQL │ │ • ChromaDB (向量库) │
|
||
│ │ │ • 文件系统 (documents/) │
|
||
│ │ │ • SQLite (同步状态哈希) │
|
||
└───────────────────────────────┘ └───────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、职责分工详解
|
||
|
||
### 2.1 RAG 组（本项目）负责
|
||
|
||
| 模块 | 功能 | 数据存储 |
|
||
|------|------|----------|
|
||
| **向量存储** | ChromaDB 向量库管理 | `vector_store/chroma/` |
|
||
| **BM25 索引** | 关键词检索 | 内存/文件 |
|
||
| **文档解析** | PDF/Word/Excel 解析与分块 | 临时处理 |
|
||
| **知识库问答** | Agentic RAG 问答引擎 | - |
|
||
| **文档同步** | 文件变更检测与向量化 | SQLite (哈希记录) |
|
||
| **出题能力** | 基于知识库生成题目 | 无状态 |
|
||
|
||
### 2.2 后端组负责
|
||
|
||
| 模块 | 功能 | 数据存储 |
|
||
|------|------|----------|
|
||
| **用户认证** | 登录/注册/Token 管理 | MySQL/PostgreSQL |
|
||
| **权限控制** | 角色/部门/接口权限 | MySQL/PostgreSQL |
|
||
| **会话管理** | 对话历史记录 | MySQL/PostgreSQL |
|
||
| **审计日志** | 操作日志记录 | MySQL/PostgreSQL |
|
||
| **反馈系统** | 用户反馈收集 | MySQL/PostgreSQL |
|
||
| **业务主数据** | 学生/课程/组织架构 | MySQL/PostgreSQL |
|
||
| **题库管理** | 题目存储/试卷管理 | MySQL/PostgreSQL |
|
||
| **网关路由** | 请求路由/Header 注入 | - |
|
||
|
||
### 2.3 数据归属对照表
|
||
|
||
| 数据类型 | 存储位置 | 管理方 | 说明 |
|
||
|----------|----------|--------|------|
|
||
| 向量数据 | ChromaDB | RAG 组 | 文档 embedding |
|
||
| 文档哈希 | SQLite | RAG 组 | 同步状态检测 |
|
||
| 原始文档 | 文件系统 | RAG 组 | documents/ 目录 |
|
||
| 用户账户 | MySQL/PG | 后端组 | 账号密码信息 |
|
||
| 会话历史 | MySQL/PG | 后端组 | 对话记录 |
|
||
| 审计日志 | MySQL/PG | 后端组 | 操作日志 |
|
||
| 反馈记录 | MySQL/PG | 后端组 | 用户反馈 |
|
||
| 题库数据 | MySQL/PG | 后端组 | 题目/试卷 |
|
||
|
||
---
|
||
|
||
## 三、接口协作规范
|
||
|
||
### 3.1 后端调用 RAG 服务
|
||
|
||
后端通过 HTTP 调用 RAG API，需注入 Header：
|
||
|
||
```
|
||
X-User-ID: 用户唯一标识
|
||
X-User-Name: 用户名（可选）
|
||
X-User-Role: 用户角色（可选）
|
||
X-User-Department: 部门（可选）
|
||
```
|
||
|
||
### 3.2 RAG 服务提供的接口
|
||
|
||
#### 问答接口
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/chat` | POST | 普通聊天 |
|
||
| `/rag` | POST | 知识库问答 |
|
||
| `/rag/stream` | POST | 流式问答 |
|
||
| `/search` | POST | 混合检索 |
|
||
|
||
#### 向量库管理
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/collections` | GET | 向量库列表 |
|
||
| `/collections` | POST | 创建向量库 |
|
||
| `/collections/<name>` | PUT | 修改向量库 |
|
||
| `/collections/<name>` | DELETE | 删除向量库 |
|
||
|
||
#### 文档管理
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/documents/upload` | POST | 上传文件 |
|
||
| `/documents/batch-upload` | POST | 批量上传 |
|
||
| `/documents/list` | GET | 文档列表 |
|
||
| `/documents/<path>` | DELETE | 删除文档 |
|
||
| `/documents/<path>/status` | GET | 处理状态 |
|
||
|
||
#### 切片管理
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/documents/<path>/chunks` | GET | 查看切片 |
|
||
| `/chunks` | POST | 新增切片 |
|
||
| `/chunks/<id>` | PUT | 修改切片 |
|
||
| `/chunks/<id>` | DELETE | 删除切片 |
|
||
|
||
#### 同步服务
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/sync` | POST | 触发同步 |
|
||
| `/sync/status` | GET | 同步状态 |
|
||
|
||
#### 出题接口
|
||
| 接口 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `/exam/generate` | POST | 生成题目 |
|
||
| `/exam/grade` | POST | 批改答案 |
|
||
|
||
### 3.3 后端需要提供的接口
|
||
|
||
RAG 服务可能需要调用后端获取用户信息：
|
||
|
||
```
|
||
GET /api/users/{user_id}
|
||
|
||
响应:
|
||
{
|
||
"user_id": "xxx",
|
||
"username": "用户名",
|
||
"name": "真实姓名",
|
||
"role": "admin/manager/user",
|
||
"department": "部门名称"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 四、合并前准备工作
|
||
|
||
### 4.1 RAG 组需完成
|
||
|
||
- [x] 权限控制简化（依赖后端网关）
|
||
- [x] 移除会话管理依赖
|
||
- [x] 移除审计日志依赖
|
||
- [x] 更新 API 文档
|
||
- [ ] 清理测试数据和临时文件
|
||
- [ ] 整理依赖列表 (requirements.txt)
|
||
- [ ] 准备环境变量配置模板
|
||
|
||
### 4.2 后端组需完成
|
||
|
||
- [ ] 设计数据库表结构
|
||
- [ ] 实现用户认证接口
|
||
- [ ] 实现会话管理接口
|
||
- [ ] 实现审计日志接口
|
||
- [ ] 配置网关路由和 Header 注入
|
||
- [ ] 提供 RAG 服务调用的接口
|
||
|
||
### 4.3 双方需确认
|
||
|
||
- [ ] 接口协议和字段格式
|
||
- [ ] 错误码规范
|
||
- [ ] 部署环境和网络配置
|
||
- [ ] 文件存储方案（本地/NFS/OSS）
|
||
|
||
---
|
||
|
||
## 五、Linux 部署方案
|
||
|
||
### 5.1 部署架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Linux 服务器 │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
|
||
│ │ Nginx │ │ 后端服务 │ │ RAG 服务 │ │
|
||
│ │ :80/443 │───▶│ :8080 │ │ :5001 │ │
|
||
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
|
||
│ │ │ │ │
|
||
│ │ ▼ ▼ │
|
||
│ │ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ │ MySQL/PG │ │ ChromaDB │ │
|
||
│ │ └─────────────┘ └─────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────┐ │
|
||
│ │ documents/ │ ◀── 文档存储目录 │
|
||
│ └─────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.2 环境准备
|
||
|
||
```bash
|
||
# 1. 系统依赖
|
||
sudo apt update
|
||
sudo apt install -y python3.10 python3.10-venv python3-pip
|
||
|
||
# 2. 创建部署用户
|
||
sudo useradd -m -s /bin/bash rag
|
||
sudo su - rag
|
||
|
||
# 3. 创建目录结构
|
||
mkdir -p /home/rag/rag-service/{app,documents,vector_store,logs}
|
||
```
|
||
|
||
### 5.3 RAG 服务部署
|
||
|
||
```bash
|
||
# 1. 上传代码
|
||
cd /home/rag/rag-service
|
||
# 将项目代码上传到 app/ 目录
|
||
|
||
# 2. 创建虚拟环境
|
||
python3.10 -m venv venv
|
||
source venv/bin/activate
|
||
|
||
# 3. 安装依赖
|
||
pip install -r app/requirements.txt
|
||
|
||
# 4. 配置环境变量
|
||
cat > .env << EOF
|
||
# 生产环境配置
|
||
DEV_MODE=false
|
||
DOCUMENTS_PATH=/home/rag/rag-service/documents
|
||
VECTOR_STORE_PATH=/home/rag/rag-service/vector_store
|
||
|
||
# API 配置（如果需要）
|
||
DASHSCOPE_API_KEY=your_api_key
|
||
EOF
|
||
|
||
# 5. 初始化向量库
|
||
python -c "from knowledge.manager import get_kb_manager; get_kb_manager()"
|
||
|
||
# 6. 测试启动
|
||
cd app && python main.py --port 5001
|
||
```
|
||
|
||
### 5.4 Systemd 服务配置
|
||
|
||
```bash
|
||
# 创建服务文件
|
||
sudo cat > /etc/systemd/system/rag-service.service << 'EOF'
|
||
[Unit]
|
||
Description=RAG Knowledge Service
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=rag
|
||
Group=rag
|
||
WorkingDirectory=/home/rag/rag-service/app
|
||
Environment="PATH=/home/rag/rag-service/venv/bin"
|
||
EnvironmentFile=/home/rag/rag-service/.env
|
||
ExecStart=/home/rag/rag-service/venv/bin/python main.py --port 5001
|
||
Restart=always
|
||
RestartSec=5
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
EOF
|
||
|
||
# 启动服务
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable rag-service
|
||
sudo systemctl start rag-service
|
||
|
||
# 查看状态
|
||
sudo systemctl status rag-service
|
||
```
|
||
|
||
### 5.5 Nginx 配置
|
||
|
||
```nginx
|
||
# /etc/nginx/sites-available/rag-service
|
||
upstream rag_backend {
|
||
server 127.0.0.1:5001;
|
||
}
|
||
|
||
server {
|
||
listen 80;
|
||
server_name your-domain.com;
|
||
|
||
# 请求体大小限制（文件上传）
|
||
client_max_body_size 50M;
|
||
|
||
# RAG API 代理
|
||
location /rag-api/ {
|
||
proxy_pass http://rag_backend/;
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
|
||
# 注入用户信息（由认证模块设置）
|
||
proxy_set_header X-User-ID $http_x_user_id;
|
||
proxy_set_header X-User-Name $http_x_user_name;
|
||
proxy_set_header X-User-Role $http_x_user_role;
|
||
proxy_set_header X-User-Department $http_x_user_department;
|
||
|
||
# SSE 支持
|
||
proxy_buffering off;
|
||
proxy_cache off;
|
||
proxy_read_timeout 300s;
|
||
}
|
||
|
||
# 图片文件
|
||
location /images/ {
|
||
alias /home/rag/rag-service/documents/images/;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.6 网关 Header 注入示例
|
||
|
||
后端网关在转发请求到 RAG 服务时注入 Header：
|
||
|
||
```java
|
||
// Spring Cloud Gateway 示例
|
||
@Bean
|
||
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
|
||
return builder.routes()
|
||
.route("rag-service", r -> r.path("/rag-api/**")
|
||
.filters(f -> f
|
||
.stripPrefix(1)
|
||
.addRequestHeader("X-User-ID", "#{request.getAttribute('userId')}")
|
||
.addRequestHeader("X-User-Role", "#{request.getAttribute('userRole')}")
|
||
.addRequestHeader("X-User-Department", "#{request.getAttribute('userDept')}")
|
||
)
|
||
.uri("http://127.0.0.1:5001"))
|
||
.build();
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 六、联调测试清单
|
||
|
||
### 6.1 后端接口测试
|
||
|
||
- [ ] 用户认证接口可用
|
||
- [ ] 网关正确注入 Header
|
||
- [ ] 会话管理接口可用
|
||
|
||
### 6.2 RAG 接口测试
|
||
|
||
```bash
|
||
# 测试 RAG 服务（带 Header）
|
||
curl -X POST http://localhost:5001/rag \
|
||
-H "Content-Type: application/json" \
|
||
-H "X-User-ID: test-user" \
|
||
-H "X-User-Role: admin" \
|
||
-d '{"message": "测试问题"}'
|
||
|
||
# 测试向量库列表
|
||
curl -X GET http://localhost:5001/collections \
|
||
-H "X-User-ID: test-user"
|
||
|
||
# 测试文件上传
|
||
curl -X POST http://localhost:5001/documents/upload \
|
||
-H "X-User-ID: test-user" \
|
||
-F "file=@test.pdf" \
|
||
-F "collection=public_kb"
|
||
```
|
||
|
||
### 6.3 端到端测试
|
||
|
||
- [ ] 前端 → 后端 → RAG 请求链路通
|
||
- [ ] 用户认证正确传递
|
||
- [ ] 权限控制生效
|
||
- [ ] 文件上传下载正常
|
||
- [ ] 问答功能正常
|
||
|
||
---
|
||
|
||
## 七、运维监控
|
||
|
||
### 7.1 日志管理
|
||
|
||
```bash
|
||
# RAG 服务日志
|
||
tail -f /home/rag/rag-service/logs/rag.log
|
||
|
||
# Systemd 日志
|
||
journalctl -u rag-service -f
|
||
```
|
||
|
||
### 7.2 健康检查
|
||
|
||
```bash
|
||
# 添加到监控脚本
|
||
curl -f http://localhost:5001/health || alert "RAG service down"
|
||
```
|
||
|
||
### 7.3 备份策略
|
||
|
||
```bash
|
||
# 备份向量库
|
||
tar -czf backup_$(date +%Y%m%d).tar.gz vector_store/
|
||
|
||
# 备份文档
|
||
rsync -av documents/ backup/documents/
|
||
|
||
# 备份同步状态
|
||
sqlite3 data/knowledge.db ".backup backup/knowledge.db"
|
||
```
|
||
|
||
---
|
||
|
||
## 八、故障排查
|
||
|
||
| 问题 | 可能原因 | 解决方案 |
|
||
|------|----------|----------|
|
||
| 401 未认证 | 缺少 X-User-ID | 检查网关 Header 注入 |
|
||
| 向量检索失败 | ChromaDB 损坏 | 重建向量库 |
|
||
| 文件上传失败 | 权限/空间问题 | 检查目录权限和磁盘空间 |
|
||
| 内存不足 | 向量模型占用 | 增加 swap 或内存 |
|
||
| 服务启动慢 | 模型加载 | 预热模型或使用更小模型 |
|