# demo-ai

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

## Basic Information

- **Project Name**: demo-ai
- **Description**: Spring AI + 通义千文 完整示例
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2026-02-12
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring AI + 通义千文 完整示例

基于 Gradle + Spring Boot 3 + 阿里云 DashScope SDK 的通义千文大模型集成示例项目。

## 功能特性

- ✅ 基于阿里云 DashScope SDK 直接调用通义千文
- ✅ 支持简单问答和模板化问答
- ✅ 实现实时流式响应（SSE）
- ✅ 内存级聊天记忆功能
- ✅ 响应式编程（WebFlux + Reactor）
- ✅ 完整的依赖管理和配置
- ✅ 标准化的代码注释规范

## 技术栈

- Java 17+
- Spring Boot 3.4.5
- Spring WebFlux（响应式Web框架）
- 阿里云 DashScope SDK 2.13.0
- Lombok 1.18.30
- Gradle 8.5+

## 快速开始

### 1. 获取阿里云 API Key

1. 访问 [阿里云百炼控制台](https://bailian.console.aliyun.com/)
2. 注册/登录账号
3. 创建应用并获取 API Key
4. 记录你的 API Key（在 `application.yml` 中配置）

### 2. 配置项目

#### 修改 API Key

编辑 `src/main/resources/application.yml` 文件：

```yaml
spring:
  ai:
    alibaba:
      qwen:
        api-key: your-dashscope-api-key  # 替换为你的 API Key
        model: qwen-plus                 # 模型选择
        timeout: 30000                   # 超时时间（毫秒）
```

#### 模型选择说明

- `qwen-turbo`: 基础版（响应速度快，适合简单问答）
- `qwen-plus`: 增强版（功能更丰富，平衡性能）
- `qwen-max`: 旗舰版（能力最强，适合复杂任务）

### 3. 构建和运行

#### 使用 Gradle 命令

```bash
# 构建项目
./gradlew clean build

# 运行应用
./gradlew bootRun
```

#### 或者使用 IDE

1. 在 IntelliJ IDEA 中打开项目
2. 等待 Gradle 依赖同步完成
3. 运行 `Application.java` 主类

### 4. 访问接口

应用启动后，默认端口为 `8080`。

#### 测试接口示例

1. **简单问答接口**
    ```bash
    curl "http://localhost:8080/chat/simple?message=介绍一下Spring AI"
    ```

2. **模板化问答接口**
    ```bash
    curl "http://localhost:8080/chat/template?subject=人工智能&count=3"
    ```

3. **流式问答接口**
    ```bash
    curl -N "http://localhost:8080/chat/stream?message=介绍一下Spring AI"
    ```

4. **带记忆的聊天接口**
    ```bash
    # 第一次对话
    curl "http://localhost:8080/chat/memory?sessionId=user123&message=你好，我叫张三"
    
    # 第二次对话（保持上下文）
    curl "http://localhost:8080/chat/memory?sessionId=user123&message=我刚才说了什么"
    ```

5. **清理会话记忆**
    ```bash
    curl "http://localhost:8080/chat/memory/clear?sessionId=user123"
    ```

## 项目结构

```
src/main/java/com/devxz/
├── Application.java              # Spring Boot主启动类
├── controller/
│   └── QwenController.java        # HTTP接口控制器
└── service/
    ├── QwenAiService.java         # 通义千文AI服务实现
    └── ChatMemoryService.java     # 聊天记忆服务（内存缓存）

src/main/resources/
└── application.yml               # 应用配置文件

src/test/java/com/devxz/
└── ApplicationTests.java         # 应用测试类
```

## 核心功能详解

### 1. 简单问答 (`simpleChat`)

直接向通义千文发送用户消息并返回结果：

```java
public String simpleChat(String message) {
    GenerationParam param = GenerationParam.builder()
            .model(modelName)
            .prompt(message)
            .apiKey(apiKey)
            .build();

    GenerationResult result = generation.call(param);
    return result.getOutput().getText();
}
```

### 2. 模板化问答 (`templateChat`)

使用参数化提示词生成特定格式的内容：

```java
public String templateChat(String subject, int count) {
    String prompt = String.format("请为%s生成%s条简短宣传语，每条不超过20字", subject, count);
    return simpleChat(prompt);
}
```

### 3. 流式响应 (`streamChat`)

使用 Reactor 的 Flux 实现真正的流式输出：

```java
public Flux<String> streamChat(String message) {
    return Flux.create(sink -> {
        // 异步调用流式API
        Flowable<GenerationResult> flowable = generation.streamCall(param);
        flowable.subscribe(
                result -> sink.next(result.getOutput().getText()),
                error -> sink.error(error),
                () -> sink.complete()
        );
    });
}
```

### 4. 聊天记忆功能

基于内存缓存实现会话级别的上下文管理：

```java
// 保存聊天历史
chatMemoryService.saveUserMessage(sessionId, message);
chatMemoryService.

saveAssistantMessage(sessionId, response);

// 构建上下文
String context = chatMemoryService.buildContext(sessionId, 10);

// 构造带历史的提示词
String prompt = String.format("基于以下聊天历史回答：%s\n用户：%s\n助手：", context, message);
```

## 依赖说明

### 核心依赖

- `com.alibaba:dashscope-sdk-java:2.13.0`: 阿里云通义千文官方SDK
- `org.springframework.boot:spring-boot-starter-webflux`: 响应式Web支持
- `org.projectlombok:lombok:1.18.30`: 代码简化工具

### 依赖排除

```gradle
implementation('com.alibaba:dashscope-sdk-java:2.13.0') {
    exclude group: 'org.slf4j', module: 'slf4j-simple'  // 避免日志冲突
}
```

## 配置说明

### application.yml 关键配置

```yaml
spring:
  ai:
    alibaba:
      qwen:
        api-key: ${ALIBABA_API_KEY:your-alibaba-api-key}  # 支持环境变量
        model: qwen-plus                                  # 默认模型
        timeout: 30000                                    # 超时时间
server:
  port: 8080                                             # 服务端口
logging:
  level:
    org.springframework.ai: DEBUG                        # 调试日志
    com.devxz: DEBUG                                     # 应用日志
```

## 性能优化

### 1. 线程池配置

```java
private final ExecutorService executorService = Executors.newFixedThreadPool(5);
```

### 2. 内存缓存策略

- 使用 `ConcurrentHashMap` 实现线程安全的内存缓存
- 支持按会话ID管理聊天历史
- 可配置历史消息数量限制

### 3. 响应式编程

- 使用 WebFlux 和 Reactor 实现非阻塞IO
- 流式响应提升用户体验
- 异步处理避免线程阻塞

## 常见问题

### 1. API Key 配置错误

**现象**: 返回认证失败或401错误  
**解决**: 检查 `application.yml` 中 `api-key` 配置是否正确

### 2. 模型访问限制

**现象**: 返回429或403错误  
**解决**: 检查阿里云账号额度和权限设置

### 3. 流式响应中断

**现象**: 流式输出中途停止  
**解决**: 检查网络连接和超时配置

### 4. 内存占用过高

**现象**: 长时间运行后内存持续增长  
**解决**: 定期清理过期会话或限制历史消息数量

## 扩展建议

1. **持久化存储**: 将聊天历史存储到Redis或数据库
2. **多模型支持**: 集成其他大模型（如GPT、Claude等）
3. **安全增强**: 添加API密钥验证和请求频率限制
4. **监控告警**: 集成Prometheus和Grafana监控
5. **负载均衡**: 部署多个实例并使用负载均衡
6. **缓存优化**: 使用Redis缓存热点查询结果

## 参考文档

- [阿里云百炼文档](https://help.aliyun.com/zh/bailian/)
- [通义千文模型文档](https://help.aliyun.com/zh/dashscope/developer-reference/qwen)
- [DashScope SDK 文档](https://help.aliyun.com/zh/dashscope/developer-reference/sdk-download)
- [Spring Boot 官方文档](https://docs.spring.io/spring-boot/reference/)
- [Spring WebFlux 文档](https://docs.spring.io/spring-framework/reference/web/webflux.html)
- [Reactor 官方文档](https://projectreactor.io/docs/core/release/reference/)

---

**注意**: 本项目仅用于学习和测试目的，生产环境使用请遵循阿里云相关服务条款和服务协议。