# AI Avatar Chat System

相关源文件

- [AiAvatarChatController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java)
- [ChatMessageAddRequest.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageAddRequest.java)
- [ChatMessageQueryRequest.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/chat/ChatMessageQueryRequest.java)
- [AiAvatarChatHistoryService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java)
- [DifyService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java)
- [UserAiAvatarService.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/UserAiAvatarService.java)
- [AiAvatarChatHistoryServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java)
- [DifyServiceImpl.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java)

本文档提供了AI Avatar Chat System的技术参考，它是SmartClass后端的核心组件，用于在用户和AI头像之间实现对话交互。该系统集成了Dify API，提供智能且上下文感知的响应，并支持阻塞和流式两种模式。

有关管理AI头像的信息，请参见[AI Avatar Management](https://deepwiki.com/Ubanillx/smartclass-backend/2.3-ai-avatar-management)。

## 概述

AI Avatar Chat System使用户能够与定制的AI个性（头像）进行对话。每次对话都作为一个会话进行管理，并具有持久的历史记录。系统支持同步（阻塞）和异步（流式）响应模式、包括图像在内的多模态输入以及文本到音频的转换。

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java46-63](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L46-L63) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java39-53](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L39-L53)

## 架构和组件

AI Avatar Chat System采用分层架构构建，包括控制器、服务和数据访问层，并与Dify AI平台集成。

### 核心组件

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java46-63](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L46-L63) [src/main/java/com/ubanillx/smartclass/service/DifyService.java12-157](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L12-L157) [src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java16-142](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/AiAvatarChatHistoryService.java#L16-L142)

### 关键类及其职责

| 类 | 职责 |
| --- | --- |
| `AiAvatarChatController` | 处理聊天功能的HTTP请求、会话管理和聊天历史记录检索 |
| `DifyService` | 定义与Dify AI API交互的方法的接口 |
| `DifyServiceImpl` | 实现与错误处理和重试逻辑的Dify API集成 |
| `AiAvatarChatHistoryService` | 管理聊天历史记录存储和检索的接口 |
| `AiAvatarChatHistoryServiceImpl` | 实现持久化和检索聊天会话和消息的功能 |
| `ChatMessageHelper` | 创建标准化消息对象的工具 |

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java46-63](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L46-L63) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java36-53](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L36-L53)

## 聊天消息流程

系统支持两种交互模式：阻塞（同步）和流式（异步）。

### 阻塞模式消息流程

"数据库""Dify API""AiAvatarChatHistoryService""DifyServiceImpl""AiAvatarChatController"客户端"数据库""Dify API""AiAvatarChatHistoryService""DifyServiceImpl""AiAvatarChatController"POST /chat/message/send验证请求如果需要则创建会话sendChatMessage()保存用户消息存储消息buildChatRequest()POST /chat-messages完整响应保存AI响应存储响应返回AiAvatarChatHistory转换为ChatMessageVOReturn response

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java99-185](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L99-L185) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java55-178](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L55-L178)

### 流式模式消息流程

"数据库""Dify API""AiAvatarChatHistoryService""DifyServiceImpl""AiAvatarChatController"客户端"数据库""Dify API""AiAvatarChatHistoryService""DifyServiceImpl""AiAvatarChatController"循环[对于每个块]POST /chat/message/stream验证请求如果需要则创建会话创建SseEmittersendChatMessageStreaming()保存用户消息存储消息buildChatRequest()POST /chat-messages (流式传输)流式传输响应块转发块发送SSE事件保存完整的AI响应存储响应发送完成事件

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java194-363](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L194-L363) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java180-404](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L180-L404)

## 数据模型

AI Avatar Chat System的主要实体是`AiAvatarChatHistory`，它存储了用户和AI头像之间交换的所有消息。

来源：[src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java32-64](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java#L32-L64)

## 关键特性

### 会话管理

系统管理聊天会话并执行以下操作：

1. **会话创建**：当用户开始与AI头像对话时生成UUID作为会话ID
2. **会话检索**：用户可以访问他们之前的对话并继续进行
3. **会话命名**：使用AI生成的对话摘要自动命名会话
4. **会话删除**：用户可以本地删除他们的聊天历史记录，并可选地在Dify平台上删除

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java76-90](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L76-L90) [src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java75-83](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java#L75-L83) [src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java197-221](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/AiAvatarChatHistoryServiceImpl.java#L197-L221)

### 多模态交互

系统支持以下多模态输入：

1. **文本消息**：基于标准的文本对话
2. **图像上传**：用户可上传图片，AI可以分析并做出回应
3. **文本转语音**：AI回复可以转换为语音

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java649-728](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L649-L728) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java714-784](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L714-L784) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java788-912](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L788-L912)

## 与Dify API的集成

系统通过`DifyServiceImpl`中的全面实现与Dify AI平台集成。

### 关键集成点

1. **身份验证**：每个对Dify的请求都包含一个特定头像的身份验证令牌
2. **会话管理**：系统处理会话创建、消息交换和删除
3. **流式支持**：支持服务器发送事件（SSE）以实现实时流式响应
4. **错误处理**：为常见的故障场景实现强大的错误处理和重试逻辑
5. **文件上传**：支持上传图像以进行多模态对话

来源：[src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java36-71](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L36-L71) [src/main/java/com/ubanillx/smartclass/service/DifyService.java12-157](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/DifyService.java#L12-L157)

### API集成详情

| Dify端点 | 功能 | 实现 |
| --- | --- | --- |
| `/chat-messages` | 发送聊天消息 | `sendChatMessage()`, `sendChatMessageWithFiles()` |
| `/chat-messages` (流式) | 流式传输聊天响应 | `sendChatMessageStreaming()`, `sendChatMessageStreamingWithFiles()` |
| `/chat-messages/summarize` | 获取会话摘要 | `getSessionSummary()` |
| `/text-to-audio` | 文本转语音 | `textToAudio()` |
| `/files/upload` | 上传图片 | `uploadFile()` |
| `/conversations/{id}` | 删除会话 | `deleteConversation()` |

来源：[src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java401-501](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L401-L501) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java504-570](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L504-L570) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java572-646](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L572-L646)

## 错误处理与可靠性

系统实现了多种策略以确保可靠性：

1. **会话恢复**：如果Dify一侧不存在会话，系统将创建一个新的会话并继续
2. **重试逻辑**：为常见故障场景如过期会话实现重试逻辑
3. **错误传播**：为阻塞模式和流式模式提供结构化的错误响应
4. **事务管理**：数据库操作被包裹在事务中以确保一致性

来源：[src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java77-178](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L77-L178) [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java210-404](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L210-L404)

## 使用示例

### 创建聊天会话

```
POST /chat/session/create?aiAvatarId=123
```

### 发送消息（阻塞模式）

```
POST /chat/message/send
{
  "aiAvatarId": 123,
  "sessionId": "uuid-string",
  "content": "Hello, how are you today?"
}
```

### 发送消息（流式模式）

```
POST /chat/message/stream
{
  "aiAvatarId": 123,
  "sessionId": "uuid-string",
  "content": "Tell me a long story."
}
```

### 检索聊天历史记录

```
GET /chat/history?sessionId=uuid-string
```

### 文本转语音

```
POST /chat/text-to-audio
{
  "aiAvatarId": 123,
  "text": "Hello world"
}
```

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java76-90](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L76-L90) [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java99-185](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L99-L185) [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java194-363](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L194-L363) [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java388-416](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L388-L416) [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java649-728](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L649-L728)

## 安全考虑

1. **身份验证**：所有端点都需要用户身份验证
2. **授权**：用户只能访问自己的聊天会话
3. **API密钥保护**：Dify API密钥与特定AI头像关联，并且不暴露给客户端
4. **输入验证**：所有用户输入在处理前都会进行验证

来源：[src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java82-85](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L82-L85) [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java404-407](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L404-L407) [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java546-549](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L546-L549)

## 结论

AI Avatar Chat System为用户和AI头像之间的对话交互提供了一个强大的框架。它支持各种交互模式，处理会话持久性，并无缝集成了Dify AI平台以提供智能响应。系统的架构强调了可靠性、安全性和可扩展性，能够在SmartClass平台上实现丰富的对话体验。