# demo-alibaba-ai

**Repository Path**: devxz/demo-alibaba-ai

## Basic Information

- **Project Name**: demo-alibaba-ai
- **Description**: 这是一个基于 Spring AI Alibaba 框架集成通义千问大模型的完整示例项目，包含前后端一体化的AI助手应用。
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-02-27
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 通义千问 Spring AI Alibaba 集成完整示例

这是一个基于 Spring AI Alibaba 框架集成通义千问大模型的完整示例项目，包含前后端一体化的AI助手应用。

## 🌟 核心功能

### 💬 智能对话功能
- ✅ **基础聊天对话** - 简单的AI问答交互
- ✅ **带上下文对话** - 支持系统提示词定制
- ✅ **记忆聊天对话** - 基于会话ID的对话历史保持
- ✅ **流式响应支持** - 实时逐字输出，提升用户体验

### 🛠️ 专业AI服务
- ✅ **多语言翻译** - 支持中英日韩等多种语言互译
- ✅ **代码解释分析** - 多编程语言代码详细解释
- ✅ **智能问答系统** - 专业领域知识问答

### ⚡ 性能优化
- ✅ **智能缓存机制** - 减少重复API调用，提升响应速度
- ✅ **会话管理** - 完整的对话历史管理和统计功能

## 🏗️ 技术架构

### 后端技术栈
- **核心框架**: Spring Boot 3.2.4
- **AI集成**: Spring AI Alibaba 1.1.2.0
- **大模型**: 通义千问 (Qwen-Plus)
- **构建工具**: Gradle 8.x
- **编程语言**: Java 17+
- **响应式编程**: WebFlux + Reactor

### 前端技术栈
- **核心框架**: 原生HTML5 + CSS3 + JavaScript
- **UI设计**: 响应式布局，支持PC和移动端
- **交互体验**: 实时流式数据显示

## 🚀 快速开始

### 1. 环境准备
确保已安装：
- JDK 17 或更高版本
- Gradle 8.x（项目包含wrapper）

### 2. 获取API密钥
访问 [阿里云百炼平台](https://help.aliyun.com/zh/bailian/) 获取 DashScope API 密钥。

### 3. 配置API密钥
在系统环境变量中设置：
```bash
# Windows (CMD)
set ALIBABA_API_KEY=your-dashscope-api-key

# Windows (PowerShell)  
$env:ALIBABA_API_KEY="your-dashscope-api-key"

# Linux/Mac
export ALIBABA_API_KEY=your-dashscope-api-key
```

或者在 `application.yml` 中直接配置：
```yaml
spring:
  ai:
    dashscope:
      api-key: ${ALIBABA_API_KEY:your-dashscope-api-key}
```

### 4. 构建和运行
```bash
# Windows环境下使用
gradlew.bat clean build

# 运行应用
gradlew.bat bootRun

# 或者打包后运行
gradlew.bat build
java -jar build/libs/demo-alibaba-ai-0.0.1-SNAPSHOT.jar
```

应用启动后访问：`http://localhost:8080`

## 📡 API接口文档

### 基础对话接口
```
GET  /api/chat/simple          # 基础聊天
POST /api/chat/context         # 带上下文对话
GET  /api/chat/stream          # 流式响应聊天
```

### 专业服务接口
```
POST /api/chat/translate       # 文本翻译
POST /api/chat/explain-code    # 代码解释
POST /api/chat/qa             # 智能问答
```

### 流式响应接口
```
POST /api/chat/stream-explain-code  # 流式代码解释
POST /api/chat/stream-qa           # 流式智能问答
```

### 缓存相关接口
```
GET  /api/chat/cached-simple      # 带缓存的基础聊天
POST /api/chat/cached-translate   # 带缓存的翻译
POST /api/chat/cached-explain-code # 带缓存的代码解释
```

### 会话管理接口
```
POST /api/chat/memory-chat        # 带记忆的聊天
GET  /api/chat/session-stats      # 会话统计
DELETE /api/chat/clear-session    # 清理会话
GET  /api/chat/total-sessions     # 总会话数
```

## 📁 项目结构

```
src/main/java/com/devxz/
├── config/                      # 配置类
│   └── ChatConfig.java         # AI聊天配置
├── controller/                  # 控制器层
│   ├── ChatController.java     # 聊天API控制器
│   └── HomeController.java     # 前端页面控制器
├── model/                       # 数据模型
│   ├── CodeExplainRequest.java # 代码解释请求
│   ├── ContextChatRequest.java # 上下文聊天请求
│   ├── QARequest.java          # 问答请求
│   └── TranslateRequest.java   # 翻译请求
├── service/                     # 服务层
│   ├── ChatService.java        # 聊天服务接口
│   └── impl/                   # 服务实现
│       ├── ChatHistoryCache.java # 聊天历史缓存
│       └── ChatServiceImpl.java  # 聊天服务实现
└── SpringAiAlibabaDemoApplication.java  # 主启动类

src/main/resources/
├── static/                      # 静态资源
│   └── index.html              # 前端主页面
└── application.yml             # 应用配置
```

## ⚙️ 核心配置说明

### AI模型配置 (ChatConfig.java)
```java
@Bean
public DashScopeChatModel dashScopeChatModel() {
    return DashScopeChatModel.builder()
            .dashScopeApi(dashScopeApi())
            .build();
}
```
- **默认模型**: qwen-plus
- **温度参数**: 0.7 (平衡创造性和准确性)
- **最大token数**: 2000

### 缓存机制
项目使用自定义的内存缓存实现：
- **ChatHistoryCache**: 基于ConcurrentHashMap的会话历史缓存
- **手动缓存**: 在Service层实现的简单内存缓存
- **LRU策略**: 自动淘汰最久未使用的缓存项

## 🔧 开发指南

### 添加新的AI功能
1. 在 `model` 包中创建请求数据类
2. 在 `ChatService` 接口中定义方法
3. 在 `ChatServiceImpl` 中实现业务逻辑
4. 在 `ChatController` 中添加API端点

### 扩展缓存功能
```java
// 使用Spring Cache注解
@Cacheable(value = "customCache", key = "#request.id")
public String cachedMethod(CustomRequest request) {
    // 业务逻辑
}
```

### 自定义系统提示词
```java
StringBuilder systemPrompt = new StringBuilder();
systemPrompt.append("你是").append(domain).append("领域的专家。");
systemPrompt.append("请提供准确详细的答案。");
```

## 🐛 常见问题排查

### API调用失败
- 检查API密钥是否正确配置
- 确认网络连接正常
- 验证阿里云账户余额充足

### 缓存问题排查
- 检查内存使用情况，避免OOM
- 验证缓存键的唯一性
- 确认缓存清理机制正常工作

### 前端页面无法访问
- 确认应用已正常启动
- 检查端口是否被占用
- 验证静态资源配置

## 📈 性能优化建议

### 生产环境配置
```yaml
server:
  port: 8080
  tomcat:
    max-connections: 8192
    accept-count: 1000
    
spring:
  ai:
    dashscope:
      api-key: ${ALIBABA_API_KEY:your-api-key}
```

### 监控和日志
- 集成Micrometer进行指标收集
- 配置详细的访问日志
- 添加异常监控告警

## 🔒 安全建议

### API密钥管理
- 生产环境使用配置中心管理密钥
- 避免将密钥硬编码在代码中
- 定期轮换API密钥

### 访问控制
- 添加请求频率限制
- 实现用户认证授权
- 配置API网关防护

## 🤝 贡献指南

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

1. Fork项目仓库
2. 创建功能分支
3. 提交更改
4. 发起Pull Request

## 📚 参考资料

- [Spring AI Alibaba官方文档](https://help.aliyun.com/zh/bailian/developer-reference/spring-ai-alibaba)
- [通义千问官方文档](https://help.aliyun.com/zh/qwen/)
- [DashScope API文档](https://help.aliyun.com/zh/bailian/developer-reference/api-details)
- [Spring WebFlux官方文档](https://docs.spring.io/spring-framework/reference/web/webflux.html)

## 📄 许可证

本项目采用 MIT License 开源协议。

---
**作者**: dev小筑 | **更新时间**: 2026-02-27 | **版本**: 1.1.0