kennethcheng
80eb5eb590
新增接口： - POST /api/chat/stream - 流式 RAG 问答 (SSE) - POST /api/documents/upload - PDF 文件上传 - POST /api/documents/upload/stream - 带进度 PDF 上传 新增功能： - CorsConfig 跨域配置（支持 localhost:8081, 5173） - FileUploadResponse/FileUploadProgress DTO - PDF 文本提取与向量化存储 - MD5 文件去重机制 配置更新： - embedding 模型更新为 BAAI/bge-m3 - multipart max-file-size: 100MB - ChatRequest topK 默认值 3 → 10
285 lines
9.5 KiB
Markdown
285 lines
9.5 KiB
Markdown
# Spring AI Demo
|
||
|
||
> 🤖 一个简洁优雅的 Spring AI 对话演示项目，基于 Spring Boot 3.2.0 与 Spring AI 1.0.0-M3 构建，支持流式响应、Markdown 渲染与 RAG 智能问答。
|
||
|
||
[](https://spring.io/projects/spring-boot)
|
||
[](https://spring.io/projects/spring-ai)
|
||
[](https://openjdk.org/)
|
||
[](LICENSE)
|
||
|
||
## ✨ 特性
|
||
|
||
- 🌐 **AI 智能对话** - 基于 Ollama 的自然语言交互
|
||
- 📡 **流式响应** - 实时逐字输出，体验流畅
|
||
- 📝 **Markdown 支持** - 完整渲染代码块、表格、列表等格式
|
||
- 👨💻 **代码高亮** - Highlight.js 自动语言检测与语法着色
|
||
- 📚 **RAG 智能问答** - 基于向量检索的上下文感知回答
|
||
- 📤 **PDF 文件上传** - PDF 文本提取与向量化存储
|
||
- 📊 **上传进度流** - 实时上传进度反馈
|
||
- 🔍 **语义检索** - Milvus 向量数据库相似度搜索
|
||
- 🔗 **引用溯源** - 回答附带文档来源引用
|
||
- 🗃️ **向量数据库** - Milvus 分布式向量数据库
|
||
- 🔍 **Embedding 服务** - SiliconFlow BAAI/bge-m3
|
||
- 🌐 **CORS 跨域** - 支持多端访问
|
||
- 🎨 **精美界面** - 深色主题响应式设计
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- JDK 17+
|
||
- Maven 3.8+
|
||
- [Ollama](https://ollama.ai/) 本地服务
|
||
- Milvus 向量数据库
|
||
|
||
### 1. 安装 Ollama
|
||
|
||
```bash
|
||
# macOS/Linux
|
||
curl -fsSL https://ollama.ai/install.sh | sh
|
||
|
||
# 拉取模型
|
||
ollama pull gpt-oss:120b-cloud
|
||
|
||
# 启动服务 (默认端口 11434)
|
||
ollama serve
|
||
```
|
||
|
||
### 2. 启动项目
|
||
|
||
```bash
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
### 3. 访问应用
|
||
|
||
- **Web 界面**: http://localhost:8080
|
||
- **健康检查**: http://localhost:8080/api/chat/test
|
||
|
||
## 🔧 技术栈
|
||
|
||
### 后端
|
||
|
||
| 组件 | 技术 | 版本 |
|
||
|:---|:---|:---|
|
||
| 基础框架 | Spring Boot | 3.2.0 |
|
||
| AI 框架 | Spring AI | 1.0.0-M3 |
|
||
| AI 模型 | OpenAI/Ollama | - |
|
||
| Embedding | SiliconFlow BAAI/bge-m3 | - |
|
||
| 向量数据库 | Milvus | 2.3.4 |
|
||
| PDF 处理 | Apache PDFBox | 2.0.29 |
|
||
| 文件上传 | Commons FileUpload | 1.5 |
|
||
| 响应式编程 | Spring WebFlux | 3.2.0 |
|
||
|
||
### 前端
|
||
|
||
| 技术 | 用途 |
|
||
|:---|:---|
|
||
| HTML5 + CSS3 | 页面结构与样式 |
|
||
| Marked.js | Markdown 解析渲染 |
|
||
| Highlight.js | 代码语法高亮 |
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
springAiDemo/
|
||
├── src/main/java/com/demo/
|
||
│ ├── MyApplication.java # Spring Boot 启动入口
|
||
│ ├── config/
|
||
│ │ ├── CorsConfig.java # CORS 跨域配置
|
||
│ │ └── RagConfig.java # RAG 配置类
|
||
│ ├── controller/
|
||
│ │ ├── ChatController.java # AI 聊天 API
|
||
│ │ └── DocumentController.java # 文档处理 API
|
||
│ ├── dto/
|
||
│ │ ├── ApiResponse.java # 统一响应封装
|
||
│ │ ├── ChatRequest.java # 聊天请求 DTO
|
||
│ │ ├── ChatResponse.java # 聊天响应 DTO
|
||
│ │ ├── FileUploadProgress.java # 上传进度 DTO
|
||
│ │ └── FileUploadResponse.java # 上传响应 DTO
|
||
│ └── service/
|
||
│ ├── ChatService.java # RAG 聊天服务
|
||
│ └── DocumentService.java # 文档处理服务
|
||
├── data/
|
||
│ └── doris_intro.md # RAG 示例文档
|
||
└── src/main/resources/
|
||
├── application.yaml # 应用配置
|
||
└── static/ # 前端资源
|
||
```
|
||
|
||
## 💬 API 文档
|
||
|
||
### 聊天接口
|
||
|
||
| 方法 | 端点 | 描述 | 参数/Body |
|
||
|:---|:---|:---|:---|
|
||
| GET | `/api/chat/test` | 健康检查 | - |
|
||
| GET | `/api/chat/ai` | 流式 AI 对话 | `msg` |
|
||
| POST | `/api/chat` | RAG 智能问答 | `{ "question": "...", "topK": 10 }` |
|
||
| POST | `/api/chat/stream` | 流式 RAG 问答 | `{ "question": "..." }` (SSE) |
|
||
|
||
### 文档接口
|
||
|
||
| 方法 | 端点 | 描述 | 参数 |
|
||
|:---|:---|:---|:---|
|
||
| POST | `/api/documents/import` | 导入 RAG 文档 | - |
|
||
| POST | `/api/documents/upload` | 上传 PDF 文件 | `file` (multipart) |
|
||
| POST | `/api/documents/upload/stream` | 上传 PDF (带进度) | `file` (multipart) |
|
||
|
||
### 请求示例
|
||
|
||
**RAG 智能问答：**
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/chat \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"question": "Apache Doris 是什么？"}'
|
||
```
|
||
|
||
**流式 RAG 问答 (SSE)：**
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/chat/stream \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"question": "Apache Doris 性能如何？"}'
|
||
```
|
||
|
||
**PDF 文件上传：**
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/documents/upload \
|
||
-F "file=@/path/to/document.pdf"
|
||
```
|
||
|
||
**导入 RAG 文档：**
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/documents/import
|
||
```
|
||
|
||
### 响应格式
|
||
|
||
**POST /api/chat 响应：**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"answer": "Apache Doris 是一个...",
|
||
"references": ["data/doris_intro.md"],
|
||
"timestamp": 1713000000000
|
||
}
|
||
}
|
||
```
|
||
|
||
**POST /api/documents/upload/stream 响应 (SSE)：**
|
||
```json
|
||
{"percent":0,"status":"STARTING","message":"开始上传..."}
|
||
{"percent":30,"status":"EXTRACTING","message":"正在提取文本..."}
|
||
{"percent":60,"status":"PROCESSING","message":"正在向量化..."}
|
||
{"percent":100,"status":"COMPLETED","message":"上传完成"}
|
||
```
|
||
|
||
## 📚 RAG 文档问答
|
||
|
||
### 工作原理
|
||
|
||
```
|
||
用户问题 → Embedding → 向量检索 → 构建上下文 → LLM 生成回答 → 返回答案+引用
|
||
```
|
||
|
||
### 使用步骤
|
||
|
||
1. **方式一**：将 `.md` / `.txt` 文档放入 `data/` 目录，调用导入接口
|
||
2. **方式二**：直接上传 PDF 文件，系统自动提取文本并向量化
|
||
3. 通过 POST `/api/chat` 或流式 `/api/chat/stream` 提问
|
||
|
||
## 🛠️ 配置说明
|
||
|
||
### CORS 跨域配置
|
||
|
||
```yaml
|
||
cors:
|
||
allowed-origins: http://localhost:8081,http://localhost:5173
|
||
allowed-methods: GET,POST,PUT,DELETE,OPTIONS
|
||
```
|
||
|
||
### 文件上传配置
|
||
|
||
```yaml
|
||
spring:
|
||
servlet:
|
||
multipart:
|
||
max-file-size: 100MB
|
||
max-request-size: 100MB
|
||
```
|
||
|
||
### Embedding 配置
|
||
|
||
```yaml
|
||
spring:
|
||
ai:
|
||
openai:
|
||
embedding:
|
||
api-key: your-siliconflow-api-key
|
||
base-url: https://api.siliconflow.cn
|
||
model: BAAI/bge-m3
|
||
dimensions: 1024
|
||
```
|
||
|
||
## 🎬 架构图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ Client │
|
||
│ ┌─────────────────┐ ┌─────────────────────────────────┐│
|
||
│ │ Web UI │ │ POST /api/chat ││
|
||
│ │ (流式/非流式) │────▶│ POST /api/chat/stream (SSE) ││
|
||
│ └─────────────────┘ └─────────────────────────────────┘│
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ ChatController │
|
||
│ POST /api/chat → ChatService │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
│
|
||
┌───────────────┴───────────────┐
|
||
▼ ▼
|
||
┌─────────────────────────┐ ┌─────────────────────────┐
|
||
│ VectorStore │ │ ChatClient │
|
||
│ (Milvus 语义检索) │ │ (Ollama LLM) │
|
||
└─────────────────────────┘ └─────────────────────────┘
|
||
```
|
||
|
||
## 📖 更新日志
|
||
|
||
### v1.0.0 (2026-04-19)
|
||
- 🎉 初始版本发布
|
||
- 支持流式 AI 对话
|
||
- Markdown 渲染与代码高亮
|
||
- 深色主题 Web 界面
|
||
|
||
### v1.1.0 (2026-04-19)
|
||
- ✨ 新增 RAG 文档问答功能
|
||
- ✨ 配置 SiliconFlow Embedding 服务
|
||
- ✨ 集成 Milvus 向量数据库
|
||
|
||
### v1.2.0 (2026-04-19)
|
||
- ✨ 新增 POST /api/chat RAG 智能问答接口
|
||
- ✨ 新增 ChatService RAG 核心服务
|
||
- ✨ 新增引用溯源功能
|
||
|
||
### v1.3.0 (2026-04-20)
|
||
- ✨ 新增 POST /api/chat/stream 流式 RAG 问答接口 (SSE)
|
||
- ✨ 新增 PDF 文件上传接口 (POST /api/documents/upload)
|
||
- ✨ 新增带进度流式 PDF 上传 (POST /api/documents/upload/stream)
|
||
- ✨ 新增 CorsConfig 跨域配置
|
||
- ✨ embedding 模型更新为 BAAI/bge-m3
|
||
- ✨ ChatRequest topK 默认值调整为 10
|
||
- 🐛 修复文件重复上传问题 (MD5 去重)
|
||
|
||
## 📗 License
|
||
|
||
MIT © 2026 Spring AI Demo
|
||
|
||
---
|
||
|
||
🚀 **Made with Spring AI**
|