init: RAG 知识库服务初始提交
- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
This commit is contained in:
lacerate551
450
docs/架构与部署方案.md
Normal file
450
docs/架构与部署方案.md
Normal file
@@ -0,0 +1,450 @@
|
||||
# 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 或内存 |
|
||||
| 服务启动慢 | 模型加载 | 预热模型或使用更小模型 |
|
||||
Reference in New Issue
Block a user