# RAG

**Repository Path**: lc8026/rag

## Basic Information

- **Project Name**: RAG
- **Description**: RAG 文档问答系统
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RAG 文档问答系统

基于 Spring Boot + Vue 3 + Milvus 构建的检索增强生成（RAG）文档问答 Demo。支持文档上传、向量化存储、智能问答、流式响应等功能。

## 功能特性

- 📄 **文档上传**：支持 PDF、TXT、Word 等多种格式文档上传
- 🔍 **向量检索**：基于 Milvus 向量数据库，毫秒级相似度检索
- 💬 **智能问答**：基于 RAG 技术，根据文档内容精准回答
- ⚡ **流式响应**：支持 SSE 流式输出，打字机效果展示
- 📝 **Markdown 渲染**：回答内容支持 Markdown 格式化显示
- 📚 **参考来源**：展示回答引用的文档片段
- 🗂️ **对话管理**：多会话支持，本地持久化历史记录

## 技术栈

### 后端
- **框架**：Spring Boot 4.1.0 + Spring AI 2.0.0
- **向量数据库**：Milvus v2.4.17
- **构建工具**：Maven
- **JDK**：Java 17
- **嵌入式容器**：Tomcat 11.0.x（Spring Boot 4 已移除 Undertow 支持，不兼容 Servlet 6.1）

### 前端
- **框架**：Vue 3 + Vite
- **UI 组件**：Element Plus
- **Markdown 渲染**：marked
- **SSE**：Fetch API + ReadableStream

### 部署
- **容器化**：Docker + Docker Compose
- **反向代理**：Nginx

## 项目结构

```
.
├── backend/                # 后端 Spring Boot 项目
│   ├── src/
│   │   └── main/
│   │       ├── java/com/rag/demo/
│   │       │   ├── config/       # 配置类
│   │       │   ├── controller/   # 控制器
│   │       │   ├── dto/          # 数据传输对象
│   │       │   ├── service/      # 业务逻辑
│   │       │   └── RagDemoApplication.java
│   │       └── resources/
│   │           └── application.yml
│   ├── Dockerfile
│   └── pom.xml
├── frontend/               # 前端 Vue 项目
│   ├── src/
│   │   ├── api/            # API 封装
│   │   ├── views/          # 页面组件
│   │   ├── router/         # 路由
│   │   └── utils/          # 工具函数
│   ├── Dockerfile
│   ├── nginx.conf
│   └── package.json
├── deploy/                 # 部署相关配置
│   ├── DEPLOY_GUIDE.md     # 部署指南
│   ├── DEEPSEEK_SWITCH.md  # DeepSeek 切换指南
│   ├── nginx.conf          # Nginx 配置
│   └── env.production      # 环境变量示例
├── docker-compose.yml      # Docker Compose 配置
└── .env.example            # 环境变量示例
```

## 快速开始

### 环境要求

- Docker & Docker Compose
- 至少 4GB 可用内存
- 通义千问 API Key（或兼容 OpenAI 协议的模型服务）

### 1. 克隆项目

```bash
git clone https://gitee.com/lc8026/rag.git
cd rag
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的 API Key：

```env
# 通义千问 API 配置
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
DASHSCOPE_CHAT_MODEL=qwen-plus
DASHSCOPE_EMBEDDING_MODEL=text-embedding-v3

# Milvus 配置（Docker 部署默认即可）
MILVUS_HOST=milvus
MILVUS_PORT=19530

# RAG 配置
RAG_TOP_K=4
```

### 3. 启动服务

```bash
docker compose up -d
```

首次启动会拉取镜像并构建，可能需要几分钟。

### 4. 访问应用

- 前端页面：http://localhost
- 后端 API：http://localhost:8080
- Milvus 管理：http://localhost:9091

### 5. 停止服务

```bash
docker compose down
```

## 本地开发

### 后端开发

```bash
cd backend

# 安装依赖
mvn clean install

# 启动（需要本地运行 Milvus 或配置远程 Milvus）
mvn spring-boot:run
```

### 前端开发

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器
npm run dev
```

## API 接口

### 文档管理

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/documents/upload` | 上传文档 |
| GET | `/api/documents` | 获取文档列表 |
| DELETE | `/api/documents/{id}` | 删除文档 |

### 对话问答

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/chat` | 普通问答（一次性返回） |
| POST | `/api/chat/stream` | 流式问答（SSE） |

### 普通问答请求

```json
POST /api/chat
Content-Type: application/json

{
  "sessionId": "可选，会话ID",
  "message": "你的问题"
}
```

### 流式问答（SSE）

```json
POST /api/chat/stream
Content-Type: application/json
Accept: text/event-stream

{
  "sessionId": "可选，会话ID",
  "message": "你的问题"
}
```

**SSE 事件类型：**

- `sources` - 参考文档信息
- `content` - 回答内容片段
- `done` - 回答结束
- `error` - 错误信息

## 配置说明

### 模型切换（DeepSeek）

详细步骤见 [deploy/DEEPSEEK_SWITCH.md](deploy/DEEPSEEK_SWITCH.md)

主要修改环境变量：

```env
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx
DASHSCOPE_BASE_URL=https://api.deepseek.com
DASHSCOPE_CHAT_MODEL=deepseek-chat
DASHSCOPE_EMBEDDING_MODEL=text-embedding-v3
```

> 注意：DeepSeek 没有嵌入模型，嵌入模型仍需使用通义千问或其他服务。

### Milvus 向量维度

不同嵌入模型的向量维度不同，需对应配置：

| 模型 | 维度 |
|------|------|
| text-embedding-v3（通义千问） | 1024 |
| text-embedding-ada-002（OpenAI） | 1536 |

修改 `MILVUS_EMBEDDING_DIMENSION` 环境变量，然后删除旧的 Milvus 数据卷重新创建集合。

## 部署指南

详细的服务器部署步骤见 [deploy/DEPLOY_GUIDE.md](deploy/DEPLOY_GUIDE.md)

### 部署到腾讯云轻量服务器

1. 安装 Docker 和 Docker Compose
2. 上传项目文件到服务器
3. 配置环境变量
4. 启动服务
5. 配置 Nginx 反向代理和 SSL

## 常见问题

### 1. Milvus 启动失败

检查内存是否足够（至少 2GB），查看日志：

```bash
docker compose logs milvus
```

### 2. 向量维度不匹配

删除旧集合，重新创建：

```bash
docker compose down -v
docker compose up -d
```

### 3. API 请求超时

- 检查网络连接
- 增加超时配置（`CHAT_TIMEOUT`、`EMBEDDING_TIMEOUT`）
- 确认是否使用 IPv4（已在 JVM 参数中配置）

### 4. 前端构建失败

确保 `package.json` 中包含所有依赖，使用 `--no-cache` 重新构建：

```bash
docker compose build --no-cache frontend
```

## 许可证

MIT License