# Spring AI Demo

> 🤖 一个简洁优雅的 Spring AI 对话演示项目，基于 Spring Boot 3.2.0 与 Spring AI 1.0.0-M3 构建，支持流式响应、Markdown 渲染与 RAG 智能问答。

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.2.0-brightgreen)](https://spring.io/projects/spring-boot)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-1.0.0--M3-blue)](https://spring.io/projects/spring-ai)
[![JDK](https://img.shields.io/badge/JDK-17%2B-orange)](https://openjdk.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](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**