# responsive-server

**Repository Path**: ekiadasb/responsive-server

## Basic Information

- **Project Name**: responsive-server
- **Description**: 个人毕业设计的知识库demo，能在win上基于docker部署启动，完全离线，实测3060 12G可以运行。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-27
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Responsive RAG — 智能知识库问答系统

基于 Flask + vLLM + Milvus + MySQL 的完全离线 RAG 问答系统，支持文档解析、CAP（上下文感知预处理）管道、LoRA 过滤、WebSocket 实时进度推送。

## 核心特性

- **知识库管理**：创建知识库、上传文档（HTML/TXT/MD/PDF/DOCX）、索引策略配置
- **CAP 处理管道**：聚类 → LoRA 过滤 → LLM 预解析 → 向量化嵌入
- **实时进度**：WebSocket 推送每个文件的处理阶段和进度，弹窗关闭后后台持续监控
- **智能问答**：基于 Milvus 向量检索 + 本地 LLM 生成，支持多轮对话历史上下文
- **会话管理**：历史会话列表、会话预览、会话删除
- **完全离线**：所有模型本地部署，无需外部 API 调用
- **Docker 一键部署**：MySQL + Milvus + Attu + Backend + Nginx + vLLM 全部容器化

## 技术栈

| 组件 | 技术 |
|------|------|
| 后端框架 | Flask + Flask-SocketIO (eventlet) |
| 数据库 | MySQL 8.0 |
| 向量数据库 | Milvus 2.4 (standalone, 内嵌 etcd) |
| 模型推理 | vLLM (Qwen2.5-3B-Instruct + LoRA) |
| 嵌入模型 | sentence-transformers/multi-qa-mpnet-base-cos-v1 |
| 前端 | Vue 3 + Vite + Element Plus |
| 反向代理 | Nginx (Alpine) |
| 调试工具 | Attu (Milvus GUI) |
| 容器化 | Docker + Docker Compose |

## 项目结构

```
responsive-server/
├── app/                          # 后端源码
│   ├── app.py                    # Flask 应用入口 + SocketIO 初始化
│   ├── config/config.py          # 配置（环境变量读取）
│   ├── db/models.py              # 数据模型
│   ├── modules/
│   │   ├── auth/                 # 认证模块
│   │   ├── chat/                 # 对话模块（RAG 问答）
│   │   └── knowledge/            # 知识库模块
│   ├── services/
│   │   ├── document_parser.py    # 文档解析（懒加载 embedding）
│   │   ├── embedding_service.py  # 向量嵌入
│   │   ├── llm_service.py        # LLM 调用（本地 vLLM + LoRA）
│   │   ├── milvus_service.py     # Milvus CAP 检索
│   │   ├── preprocessor.py       # CAP 管道（聚类+过滤+预解析）
│   │   ├── raptor.py             # RAPTOR 聚类（GMM）
│   │   ├── task_processor.py     # 异步任务处理 + WS 进度推送
│   │   └── task_queue_service.py # 任务队列
│   └── socket_events.py          # WebSocket 事件（/knowledge namespace）
├── frontend/                     # 前端源码 + 编译产物
│   ├── src/                      # Vue 源码
│   ├── dist/                     # 编译产物（Nginx 直接挂载）
│   ├── package.json
│   └── vite.config.ts
├── vllm/                         # vLLM 容器
│   ├── entrypoint.sh             # 自动下载模型 + LoRA 加载
│   └── lora_modules/             # filter-lora 权重
├── lora_modules/                 # LoRA 适配器权重
├── docker-compose.yml            # 6 容器编排
├── Dockerfile                    # 后端容器（基于 python:3.12-slim）
├── docker-entrypoint.sh          # 后端容器启动脚本（自动安装依赖）
├── nginx.conf                    # 前端 + API 反向代理
├── start.sh                      # 一键启动
├── run.py                        # 后端入口
└── requirements.txt              # Python 依赖（从 conda 环境导出）
```

## 一键部署

### 前置要求

- **Docker** + **Docker Compose**
- **NVIDIA GPU** + **nvidia-docker**（vLLM 需要，至少 12GB 显存）
- 约 40GB 磁盘空间（模型下载 + Docker 镜像 + Python 依赖）

### 启动

```bash
cd responsive-server
chmod +x start.sh
./start.sh
```

启动过程说明：
1. 拉取 Docker Hub 公共基础镜像（python:3.12-slim、mysql:8.0、milvus、nginx 等）
2. 后端容器首次启动自动创建虚拟环境并安装 Python 依赖（通过清华 PyPI 镜像）
3. vLLM 容器首次启动自动从 ModelScope 下载 Qwen2.5-3B-Instruct 模型
4. 后续重启跳过依赖安装，快速启动

### 访问地址

| 服务 | 地址 |
|------|------|
| 前端 | `http://localhost` |
| API | `http://localhost:51018` |
| Attu (Milvus) | `http://localhost:8081` |

### 无 GPU 模式

```bash
docker compose up -d responsive-mysql responsive-milvus responsive-attu responsive-backend responsive-nginx
```

不启动 vLLM，知识库问答功能不可用（文档索引仍可进行，但无 LLM 推理能力）。

## 处理流程

```
上传文档 → 解析分块 → RAPTOR 聚类 → LoRA 过滤 → LLM 预解析 → 向量嵌入 → 存入 Milvus
                                                                              ↓
用户提问 → Embedding → Milvus 检索 → 本地 LLM 生成回答（带历史上下文）
```

### WebSocket 实时进度

- Namespace: `/knowledge`
- 知识库进度 room: `kb_progress_{kb_id}`
- 文件进度 room: `kb_file_progress_{file_id}`
- 弹窗打开：订阅 KB + 所有文件进度
- 弹窗关闭：取消文件进度，保留 KB 整体监控
- KB 完成：自动更新卡片状态，清理房间

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DATABASE_URL` | 数据库连接串 | `mysql+pymysql://root:root@responsive-mysql:3306/responsive_rag2` |
| `MILVUS_HOST` | Milvus 地址 | `responsive-milvus` |
| `MILVUS_PORT` | Milvus 端口 | `19530` |
| `PREPROCESSING_BASE_URL` | 预处理器 LLM 地址 | `http://responsive-vllm:13000/v1` |
| `GENERATION_BASE_URL` | 生成模型地址 | `http://responsive-vllm:13000/v1` |
| `EMBEDDING_MODEL` | 嵌入模型 | `sentence-transformers/multi-qa-mpnet-base-cos-v1` |
| `CHUNK_SIZE` | 分块大小 | `100` |
| `CHUNK_OVERLAP` | 分块重叠 | `10` |
| `SECRET_KEY` | Flask 密钥 | - |
| `JWT_SECRET_KEY` | JWT 密钥 | - |

> **安全提示**：生产环境请务必修改 `SECRET_KEY`、`JWT_SECRET_KEY` 和数据库密码。环境变量通过 `docker-compose.yml` 注入，不依赖 `.env` 文件。

## API 接口

### 认证
- `POST /api/v1/auth/register` — 注册
- `POST /api/v1/auth/login` — 登录

### 知识库
- `GET /api/v1/knowledge/knowledge-bases` — 列表
- `POST /api/v1/knowledge/knowledge-bases` — 创建
- `GET /api/v1/knowledge/knowledge-bases/{id}` — 详情
- `DELETE /api/v1/knowledge/knowledge-bases/{id}` — 删除
- `POST /api/v1/knowledge/knowledge-bases/{id}/files` — 添加文件
- `POST /api/v1/knowledge/knowledge-bases/{id}/process` — 开始索引
- `POST /api/v1/knowledge/knowledge-bases/{id}/pause` — 暂停
- `POST /api/v1/knowledge/knowledge-bases/{id}/resume` — 恢复

### 文件
- `POST /api/v1/knowledge/files` — 上传
- `GET /api/v1/knowledge/files` — 列表
- `DELETE /api/v1/knowledge/files/{id}` — 删除

### 对话
- `POST /api/v1/chat/conversations` — 创建会话
- `GET /api/v1/chat/conversations` — 列表
- `POST /api/v1/chat/conversations/{id}/messages` — 发送消息

完整 API 文档：启动后访问 `http://localhost:51018/apidocs/`

## 开发

```bash
# 安装依赖（需先创建 conda 环境）
conda create -n responsive python=3.12
conda activate responsive
pip install -r requirements.txt

# 安装前端依赖
cd frontend && npm install

# 启动后端（开发模式）
python run.py

# 启动前端（开发模式，热更新）
cd frontend && npm run dev
```

## License

MIT