# Spring AI Demo

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

[![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)

## ✨ 特性

- 🌐 **智能对话** - 基于 OpenAI/Ollama 的自然语言交互
- 📡 **流式响应** - 实时逐字输出，体验流畅
- 📝 **Markdown 支持** - 完整渲染代码块、表格、列表等格式
- 👨‍💻 **代码高亮** - Highlight.js 自动语言检测与语法着色
- 🖼️ **向量数据库** - Milvus 集成（预留 RAG 扩展能力）
- 📔 **PDF 解析** - Apache PDFBox 文档处理支持
- 🎨 **精美界面** - 深色主题响应式设计

## 🚀 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- [Ollama](https://ollama.ai/) 本地服务

### 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 | - |
| 响应式编程 | Spring WebFlux | 3.2.0 |
| 向量数据库 | Milvus Store | 1.0.0-M3 |
| 文档处理 | Apache PDFBox | 2.0.29 |

### 前端

| 技术 | 用途 |
|:---|:---|
| HTML5 + CSS3 | 页面结构与样式 |
| Marked.js | Markdown 解析渲染 |
| Highlight.js | 代码语法高亮 |

## 📁 项目结构

```
springAiDemo/
├── src/
│   └── main/
│       ├── java/com/demo/
│       │   ├── MyApplication.java          # Spring Boot 启动入口
│       │   └── controller/
│       │       └── ChatController.java       # AI 聊天 REST API
│       └── resources/
│           ├── application.yaml              # 应用配置
│           └── static/                       # 前端静态资源
│               ├── index.html                # 主页面
│               ├── css/style.css             # 深色主题样式
│               └── js/app.js                 # 流式响应逻辑
├── pom.xml
└── README.md
```

## 💬 API 文档

### 端点列表

| 方法 | 端点 | 描述 | 参数 |
|:---|:---|:---|:---|
| GET | `/api/chat/test` | 健康检查 | - |
| GET | `/api/chat/ai` | 同步 AI 对话 | `msg` |
| GET | `/api/chat/ai/stream` | 流式 AI 对话 | `msg` |

### 请求示例

**同步对话：**
```bash
curl "http://localhost:8080/api/chat/ai?msg=什么是Spring AI"
```

**流式对话：**
```bash
curl "http://localhost:8080/api/chat/ai/stream?msg=讲一个故事"
```

### 响应格式

- **同步**: `text/plain` - 完整回复文本
- **流式**: `text/html;charset=UTF-8` - Server-Sent Events 分块传输

## 🎨 界面预览

🧩 **现代化深色主题**
- 渐变标题与毛玻璃效果
- 流畅的消息气泡动画
- Markdown 代码块高亮
- 流式响应动画指示器

📝 **Markdown 支持**
- 代码块与行内代码
- 加粗、斜体、删除线
- 有序/无序列表
- 引用块、表格、链接

## 🛠️ 配置说明

### 模型配置 (`application.yaml`)

```yaml
spring:
  ai:
    openai:
      base-url: http://localhost:11434    # Ollama 服务地址
      chat:
        options:
          model: gpt-oss:120b-cloud       # 当前模型
          temperature: 0.7                # 生成温度
```

**支持模型**（需在 Ollama 中预先拉取）：
- `gpt-oss:120b-cloud` - 默认模型
- `kimi-k2.5:cloud` - Kimi 模型
- `gemma4:e2b` - Google Gemma 模型

## 🎬 架构图

```
┌─────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Client    │────▶│ ChatController  │────▶│  ChatClient     │
│  (HTTP)     │     │  (Spring MVC)    │     │  (Spring AI)    │
└─────────────┘     └──────────────────┘     └────────┬────────┘
                                                      │
                                                      ▼
                                            ┌─────────────────┐
                                            │  Ollama/OpenAI  │
                                            │  (LLM Provider) │
                                            └─────────────────┘
```

## 📄 预留功能

以下依赖已集成，可按需启用：

- 🔍 **Milvus 向量数据库** - RAG 语义搜索
- 📔 **PDF 文档解析** - 文档上传与处理
- 🗨️ **Embedding 服务** - 文本向量化

## 👷 已知限制

1. 暂无对话历史持久化
2. 暂未实现请求频率限制
3. JUnit 版本较旧（3.8.1），建议升级至 JUnit 5

## 📖 待办事项

- [ ] 添加全局异常处理
- [ ] 实现 RAG 文档问答
- [ ] 对话历史存储
- [ ] 动态模型切换 API
- [ ] Docker 部署支持
- [ ] 单元测试完善

## 📤 更新日志

### v1.0.0 (2026-04-17)
- 🎉 初始版本发布
- 支持流式 AI 对话
- Markdown 渲染与代码高亮
- 深色主题 Web 界面

## 📗 License

MIT © 2026 Spring AI Demo

---

🚀 **Made with Spring AI**