# spring-stream-ai

**Repository Path**: HuangTeng/spring-stream-ai

## Basic Information

- **Project Name**: spring-stream-ai
- **Description**: demo+sse
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-25
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🤖 Spring Boot AI 聊天系统

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-2.7.18-green" alt="Spring Boot Version" />
  <img src="https://img.shields.io/badge/Java-8+-blue" alt="Java Version" />
  <img src="https://img.shields.io/badge/License-Apache%202.0-orange" alt="License" />
</p>

## 📋 项目简介

基于 **Spring Boot 2.7.18** 的 AI 对话平台，深度集成 **DeepSeek 大模型**，提供流畅的实时流式对话体验。系统采用现代化的前后端分离架构，支持 SSE (Server-Sent Events) 流式传输技术。

### 🔧 核心特性
- 🚀 **实时流式对话** - 支持 SSE 流式响应，用户体验更流畅
- 🔐 **安全配置管理** - API 密钥通过环境变量配置，保障安全性
- 📊 **健康监控** - 集成 Spring Boot Actuator，提供完善的健康检查
- 🎨 **现代化界面** - 响应式设计的聊天界面，支持移动端访问
- ⚡ **高性能架构** - 异步处理机制，支持高并发场景

## 🚀 快速开始

### 环境要求
- **Java**: 8 或更高版本
- **Maven**: 3.6+ 
- **操作系统**: Windows/Linux/macOS

### 安装部署

#### 1. 克隆项目
```bash
git clone <repository-url>
cd spring-stream-ai
```

#### 2. 配置环境变量
在 Windows PowerShell 中设置 DeepSeek API 密钥：
```powershell
$env:DEEPSEEK_API_KEY="your-deepseek-api-key-here"
```

或者在 Linux/macOS 中：
```bash
export DEEPSEEK_API_KEY=your-deepseek-api-key-here
```

#### 3. 构建并运行
```bash
# 清理并编译项目
mvn clean package

# 运行应用程序
mvn spring-boot:run
```

### 访问应用
应用启动后，可通过以下地址访问：

| 功能 | 地址 | 说明 |
|------|------|------|
| 🏠 主页 | http://localhost:8080 | 聊天界面入口 |
| 🩺 健康检查 | http://localhost:8080/actuator/health | 系统状态监控 |
| 📊 应用信息 | http://localhost:8080/actuator/info | 应用详细信息 |

## 📡 API 接口文档

### 核心接口列表

| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| 普通对话 | POST | `/api/deepseek/complete` | 同步对话接口 |
| 流式对话 | GET | `/api/deepseek/stream` | SSE 流式对话 |
| 健康检查 | GET | `/api/deepseek/health` | API 健康状态 |

### 接口详情

#### 1. 普通对话接口
```http
POST /api/deepseek/complete
Content-Type: application/json

{
  "message": "你好，介绍一下你自己"
}
```

响应示例：
```json
{
  "message": "我是基于DeepSeek大模型的AI助手...",
  "status": "success"
}
```

#### 2. 流式对话接口
```http
GET /api/deepseek/stream?message=你好世界
Accept: text/event-stream
```

SSE 事件类型：
- `connection`: 连接建立
- `chunk`: 数据块传输
- `complete`: 传输完成
- `error`: 错误信息

#### 3. 健康检查接口
```http
GET /api/deepseek/health
```

响应示例：
```json
{
  "status": "ok",
  "service": "Improved DeepSeek Integration",
  "timestamp": 1708852800000,
  "configured": true
}
```

## ⚙️ 系统配置

### application.yml 配置项

```yaml
server:
  port: 8080

spring:
  application:
    name: springboot-vue-demo
  
  # DeepSeek AI 配置
  ai:
    deepseek:
      api-key: ${DEEPSEEK_API_KEY:sk-default-key}
      base-url: https://api.deepseek.com
      chat:
        options:
          model: deepseek-chat
          temperature: 0.7
          max-tokens: 2048
          top-p: 1.0

# 应用自定义配置
app:
  ai:
    service-name: "DeepSeek AI Service"
    timeout:
      connect: 30000
      read: 60000
      stream: 120000
    retry:
      max-attempts: 3
      delay: 1000

# 监控配置
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics
  endpoint:
    health:
      show-details: always
```

### 环境变量配置

| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `DEEPSEEK_API_KEY` | `sk-default-key` | DeepSeek API 密钥 |
| `SERVER_PORT` | `8080` | 服务端口 |

## 🧪 测试验证

### 单元测试
```bash
# 运行所有测试
mvn test

# 运行特定测试类
mvn test -Dtest=FrontendIntegrationTest
```

### 集成测试
项目包含完整的集成测试套件：

```bash
# 编译项目
mvn clean compile

# 运行前端集成测试
java -cp target/classes com.tc.ht.test.FrontendIntegrationTest
```

测试覆盖范围：
- ✅ 首页访问测试
- ✅ API 健康检查
- ✅ 流式接口连通性测试
- ✅ 响应格式验证

## 📁 项目结构

```
spring-stream-ai/
├── src/
│   ├── main/
│   │   ├── java/com/tc/ht/
│   │   │   ├── Application.java                  # 应用启动类
│   │   │   ├── controller/
│   │   │   │   └── ImprovedDeepSeekController.java # 核心控制器
│   │   │   └── test/
│   │   │       └── FrontendIntegrationTest.java   # 集成测试
│   │   └── resources/
│   │       ├── static/
│   │       │   └── index.html                     # 前端聊天界面
│   │       └── application.yml                   # 应用配置文件
├── pom.xml                                       # Maven 配置
├── README.md                                     # 项目文档
└── LICENSE                                       # 许可证文件
```

### 核心组件说明

| 组件 | 路径 | 功能描述 |
|------|------|----------|
| **启动类** | `Application.java` | Spring Boot 应用入口点 |
| **控制器** | `ImprovedDeepSeekController.java` | 处理所有 AI 对话相关请求 |
| **前端界面** | `index.html` | 用户交互的聊天界面 |
| **配置文件** | `application.yml` | 应用配置和 AI 服务参数 |
| **集成测试** | `FrontendIntegrationTest.java` | 自动化测试验证 |

## 🛠️ 技术栈

### 后端技术
- **Spring Boot 2.7.18** - 核心框架
- **Spring Web MVC** - Web 层处理
- **Spring Boot Actuator** - 应用监控
- **Lombok** - 代码简化工具
- **Jackson** - JSON 处理库
- **Reactor Core** - 响应式编程支持

### 前端技术
- **原生 HTML/CSS/JavaScript** - 轻量级实现
- **Server-Sent Events (SSE)** - 实时通信协议
- **响应式设计** - 移动端适配

### 开发工具
- **Maven 3.6+** - 项目构建管理
- **Java 8+** - 开发语言
- **IntelliJ IDEA** - 推荐 IDE

## 📈 性能优化

### 已实现优化
- ⚡ 异步流式处理，避免阻塞主线程
- 🔄 连接池管理和超时控制
- 📦 响应数据压缩优化
- 🔧 可配置的重试机制

### 配置建议
```yaml
# 生产环境推荐配置
server:
  tomcat:
    max-connections: 8192
    accept-count: 100
    max-threads: 200

spring:
  ai:
    deepseek:
      chat:
        options:
          temperature: 0.7      # 平衡创造力和准确性
          max-tokens: 2048      # 合理的响应长度限制
```

## 🔒 安全考虑

### 最佳实践
- 🔐 API 密钥通过环境变量注入，不硬编码
- 🛡️ 请求超时和重试机制防止单点故障
- 📊 详细的日志记录便于问题追踪
- 🔍 健康检查端点监控服务状态

### 安全配置示例
```bash
# 生产环境安全配置
export DEEPSEEK_API_KEY="your-production-api-key"
export SERVER_PORT=8443  # HTTPS 端口
```

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request 来改进项目！

### 开发流程
1. Fork 项目仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 **Apache License 2.0** 开源协议。详细信息请参见 [LICENSE](LICENSE) 文件。

---

<p align="center">Made with ❤️ using Spring Boot and DeepSeek AI</p>