# Dify集成

相关源文件：

- [README.md](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/README.md)
- [DifyAPI.md](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/doc/DifyAPI.md)
- [AiAvatarChatController.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java)
- [DifyChatRequest.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatRequest.java)
- [DifyChatResponse.java](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatResponse.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)

本文档描述了SmartClass后端如何与Dify AI API集成，以通过AI头像提供智能对话功能。它涵盖了此集成的架构、工作流程和实现细节。

有关聊天会话在系统内部管理的信息，请参阅[聊天会话管理](https://deepwiki.com/Ubanillx/smartclass-backend/2.2-chat-session-management)。

## 1. 概述

SmartClass平台利用Dify AI来驱动其AI头像聊天功能。该集成使用户能够与AI角色进行互动对话，支持阻塞（同步）和流式（异步）响应模式、文本转音频转换和图像处理。

**来源：**

- [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) 主要实现显示与其他服务的连接。
- [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java50-67](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L50-L67) 显示依赖关系的控制器组件。

## 2. 架构组件

Dify集成由三个主要组件组成：

1. **AiAvatarChatController**：前端面向的REST控制器，用于处理用户的聊天请求
2. **DifyService/DifyServiceImpl**：核心服务，管理与Dify API的通信
3. **AiAvatarChatHistoryService**：用于持久化和检索聊天历史的服务

**来源：**

- [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java39-73](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L39-L73) DifyServiceImpl类定义。
- [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java46-67](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L46-L67) AiAvatarChatController类定义。

## 3. 数据传输对象

该集成使用多个数据传输对象（DTOs）与Dify API通信：

### 3.1 DifyChatRequest

这个对象封装了Dify Chat API的请求参数：

**来源：**

- [src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatRequest.java12-51](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatRequest.java#L12-L51)

### 3.2 DifyChatResponse

这个对象代表来自Dify Chat API的响应：

**来源：**

- [src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatResponse.java12-96](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatResponse.java#L12-L96)

### 3.3 DifyStreamChunk

用于流式传输响应，表示来自Dify API的数据块。

## 4. 关键工作流程

### 4.1 基本聊天工作流程

标准的阻塞聊天工作流程：

DifyAPIAiAvatarChatHistoryServiceDifyServiceImplAiAvatarChatController用户DifyAPIAiAvatarChatHistoryServiceDifyServiceImplAiAvatarChatController用户alt[新会话创建]alt[结束聊天请求]POST /chat/message/sendsendChatMessage(userId, aiAvatarId, sessionId, content, baseUrl, avatarAuth)保存用户消息buildChatRequest(userId, sessionId, content)POST /chat-messages (阻塞模式)返回聊天响应更新会话ID保存AI响应返回AI聊天历史记录返回ChatMessageVOgetSessionSummary(sessionId, baseUrl, avatarAuth)POST /chat-messages/summarize返回摘要updateSessionSummary(sessionId, summary)

**来源：**

- [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) 控制器中的sendMessage方法。
- [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java55-75](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L55-L75) sendChatMessage方法。
- [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java80-178](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L80-L178) sendChatMessageWithRetry方法。

### 4.2 流式聊天工作流程

使用服务器发送事件（SSE）的流式聊天工作流程：

DifyAPIAiAvatarChatHistoryServiceDifyServiceImplAiAvatarChatController用户DifyAPIAiAvatarChatHistoryServiceDifyServiceImplAiAvatarChatController用户循环[每个块]POST /chat/message/stream创建SseEmitter发送初始连接事件sendChatMessageStreaming(userId, aiAvatarId, sessionId, content, baseUrl, avatarAuth, callback)保存用户消息POST /chat-messages (流模式)流响应块callback.onMessage(chunk)通过SSE流块累计完整响应消息结束事件保存完整的AI响应callback.onComplete(fullResponse)发送完成事件完成SSE发射器

**来源：**

- [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) sendMessageStream方法。
- [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) sendChatMessageStreaming和sendStreamingWithRetry方法。

### 4.3 文件上传和多模态聊天

上传文件和发送带有文件的聊天消息的工作流程：

DifyAPIDifyServiceImplAiAvatarChatController用户DifyAPIDifyServiceImplAiAvatarChatController用户POST /chat/file/uploaduploadFile(userId, fileName, fileInputStream, mimeType, baseUrl, avatarAuth)POST /files/upload返回文件ID返回文件ID返回UploadFileResponsePOST /chat/message/send (带fileIds)sendChatMessageWithFiles(userId, aiAvatarId, sessionId, content, fileIds, baseUrl, avatarAuth)buildChatRequestWithFiles(userId, sessionId, content, fileIds)POST /chat-messages (带文件)返回聊天响应返回AI聊天历史记录返回ChatMessageVO

**来源：**

- [src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java796-833](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java#L796-L833) uploadFile方法。
- [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java712-784](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L712-L784) uploadFile方法。
- [src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java787-912](https://github.com/Ubanillx/smartclass-backend/blob/0873c502/src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java#L787-L912) sendChatMessageWithFiles方法。
## 5. 配置和认证

Dify集成使用以下认证机制：

**来源：**

- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java98-100 认证头设置。
- src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java127-135 从AiAvatar实体中检索认证数据。

## 6. 错误处理

Dify集成了强大的错误处理机制：

|错误类型|处理策略|
|---|---|
|会话未找到 (404)|自动重试并创建新会话|
|连接错误|带有详细错误信息的异常|
|令牌限制|错误传递给客户端|
|流失败|优雅地终止SSE连接|

**来源：**

- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java105-129 错误响应处理。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java171-177 404错误的重试机制。
- src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java299-315 流式响应中的错误处理。

## 7. API端点

Dify集成使用以下Dify API端点：

|端点|目的|实现|
|---|---|---|
|`/chat-messages`|发送聊天消息|`sendChatMessage`, `sendChatMessageStreaming`|
|`/chat-messages/summarize`|获取会话摘要|`getSessionSummary`|
|`/conversations/{id}`|删除对话|`deleteConversation`|
|`/text-to-audio`|文本转音频|`textToAudio`|
|`/chat-messages/{id}/stop`|停止流响应|`stopStreamingResponse`|
|`/files/upload`|上传文件|`uploadFile`|

**来源：**

- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java93 聊天消息端点。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java448 摘要端点。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java512 对话端点。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java583 文本到音频端点。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java658 停止流端点。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java731 文件上传端点。

## 8. 请求流程

为了更好地理解请求如何通过系统流动，以下是聊天消息的详细序列图：

Dify API OkHttpUtils AiAvatarChatHistoryService ChatMessageHelper DifyServiceImpl AiAvatarChatController 用户 Dify API OkHttpUtils AiAvatarChatHistoryService ChatMessageHelper DifyServiceImpl AiAvatarChatController 用户 alt[新对话创建] alt[结束聊天请求] alt[响应成功] [响应失败] 发送消息 获取用户 & AiAvatar sendChatMessage() createUserMessage() 返回用户消息对象 save(userMessage) buildChatRequest() postJson() HTTP POST请求 HTTP响应 响应对象 解析响应 更新会话ID createAiResponse() 返回AI消息对象 save(aiResponse) 返回AI消息 getSessionSummary() 获取摘要 Summary updateSessionSummary() 响应消息 处理错误 抛出异常 错误响应

**来源：**

- src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java99-185 控制器中的完整流程。
- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java55-178 服务中的完整流程。

## 9. 结论

Dify集成在SmartClass应用程序中为AI驱动的对话提供了坚实的基础。通过支持阻塞和流模式、文件上传和音频转换，它可以通过AI头像实现丰富的交互体验。

此集成的关键优势包括：

- 灵活的响应模式（阻塞和流）
- 自动会话管理
- 错误恢复机制
- 支持多模态交互（文本、图像、音频）

有关聊天会话在系统内部管理的更多细节，请参阅聊天会话管理。

有关AI头像创建和配置的信息，请参阅AI头像管理。

**来源：**

- src/main/java/com/ubanillx/smartclass/service/impl/DifyServiceImpl.java
- src/main/java/com/ubanillx/smartclass/controller/AiAvatarChatController.java
- src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatRequest.java
- src/main/java/com/ubanillx/smartclass/model/dto/dify/DifyChatResponse.java