|
|
@@ -0,0 +1,324 @@
|
|
|
+# LinkWeChat AI 模块开发文档
|
|
|
+
|
|
|
+## 模块概述
|
|
|
+
|
|
|
+linkwe-ai 是 LinkWeChat 项目中的 AI 助手功能模块,虽然项目描述中标注"该项目没有用到",但实际上该模块实现了基于阿里云大模型的 AI 对话功能。该模块集成了阿里云通义千问(DashScope)服务,提供了单次对话、多轮对话和流式对话等 AI 交互能力。
|
|
|
+
|
|
|
+## 技术架构
|
|
|
+
|
|
|
+### 核心技术栈
|
|
|
+- **Spring Boot 2.6.6**: 基础框架
|
|
|
+- **Spring Cloud**: 微服务架构支持
|
|
|
+- **MyBatis-Plus**: 数据访问层框架
|
|
|
+- **Druid**: 数据库连接池
|
|
|
+- **Redis**: 缓存服务
|
|
|
+- **Nacos**: 服务注册与配置中心
|
|
|
+- **WebFlux**: 响应式编程支持(用于流式响应)
|
|
|
+- **Apache Commons Net**: FTP 客户端支持
|
|
|
+
|
|
|
+### AI 服务集成
|
|
|
+- **阿里云 DashScope SDK** (版本 2.18.2): 通义千问大模型服务
|
|
|
+- **支持的模型**:
|
|
|
+ - deepseek-r1: DeepSeek 推理模型
|
|
|
+ - qwen-plus: 通义千问增强版
|
|
|
+ - qwq-32b: 通义千问 32B 参数模型
|
|
|
+
|
|
|
+## 项目结构
|
|
|
+
|
|
|
+```
|
|
|
+linkwe-ai/
|
|
|
+├── src/main/java/com/linkwechat/coal/
|
|
|
+│ ├── LinkweAiApplication.java # 应用程序入口
|
|
|
+│ ├── config/
|
|
|
+│ │ └── Constant.java # 常量配置类
|
|
|
+│ ├── datasource/
|
|
|
+│ │ ├── AiDataSourceConfig.java # AI 数据源配置
|
|
|
+│ │ └── QwDataSourceConfig.java # 企微数据源配置
|
|
|
+│ ├── exception/
|
|
|
+│ │ └── SystemHandlerException.java # 系统异常处理
|
|
|
+│ ├── filter/
|
|
|
+│ │ └── HttpServletRequestWrapperFilter.java # 请求过滤器
|
|
|
+│ └── modules/
|
|
|
+│ ├── ai/
|
|
|
+│ │ ├── controller/
|
|
|
+│ │ │ ├── AliAiController.java # 阿里云 AI 控制器
|
|
|
+│ │ │ ├── FileController.java # 文件处理控制器
|
|
|
+│ │ │ └── ZmAiController.java # 智能AI控制器
|
|
|
+│ │ ├── domain/dto/
|
|
|
+│ │ │ ├── AliAiTextDto.java # AI 文本交互 DTO
|
|
|
+│ │ │ └── RequestIdDto.java # 请求 ID DTO
|
|
|
+│ │ ├── mapper/
|
|
|
+│ │ │ ├── SysUserMapper1.java # 用户 Mapper1
|
|
|
+│ │ │ └── SysUserMapper2.java # 用户 Mapper2
|
|
|
+│ │ ├── service/impl/
|
|
|
+│ │ │ └── FtpStorageService.java # FTP 存储服务
|
|
|
+│ │ └── utils/
|
|
|
+│ │ ├── AliAiUtils.java # 阿里 AI 工具类
|
|
|
+│ │ ├── FileUtils.java # 文件工具类
|
|
|
+│ │ ├── SSEHelper.java # SSE (Server-Sent Events) 辅助类
|
|
|
+│ │ └── WordUtils.java # Word 文档处理工具
|
|
|
+│ └── qw/mapper/
|
|
|
+│ └── SysUserMapper1.java # 企微用户 Mapper
|
|
|
+├── src/main/resources/
|
|
|
+│ ├── application.properties # 应用配置
|
|
|
+│ └── spy.properties # P6Spy 监控配置
|
|
|
+├── bin/ # 构建输出目录
|
|
|
+├── pom.xml # Maven 配置文件
|
|
|
+└── CLAUDE.md # 本文档
|
|
|
+```
|
|
|
+
|
|
|
+## 核心功能
|
|
|
+
|
|
|
+### 1. AI 对话功能
|
|
|
+
|
|
|
+#### AliAiController 提供的接口:
|
|
|
+
|
|
|
+1. **单次对话** (`/aliAi/single`)
|
|
|
+ - 支持文本输入和 Word 文档内容解析
|
|
|
+ - 返回完整的 AI 响应结果
|
|
|
+ - 包含思考过程和最终回答
|
|
|
+
|
|
|
+2. **多轮对话** (`/aliAi/multiwheel`)
|
|
|
+ - 支持上下文连续对话
|
|
|
+ - 通过 Redis 缓存会话历史
|
|
|
+ - 维护对话的连贯性
|
|
|
+
|
|
|
+3. **流式对话** (`/aliAi/stream`)
|
|
|
+ - 基于 Server-Sent Events (SSE) 的实时流式响应
|
|
|
+ - 使用 WebFlux 的 Flowable 实现响应式流
|
|
|
+ - 支持大文本的流式输出
|
|
|
+
|
|
|
+#### ZmAiController 提供的接口:
|
|
|
+
|
|
|
+1. **智能聊天** (`/zmAi/chat`)
|
|
|
+ - 支持阿里云和本地模型切换
|
|
|
+ - 支持跨域请求
|
|
|
+ - 使用 SSE 实现实时响应
|
|
|
+
|
|
|
+### 2. 文件处理功能
|
|
|
+
|
|
|
+1. **Word 文档解析**
|
|
|
+ - 使用 Apache POI 解析 Word 文档
|
|
|
+ - 提取文档内容作为 AI 对话上下文
|
|
|
+ - 支持控制字符转义
|
|
|
+
|
|
|
+2. **FTP 文件存储**
|
|
|
+ - 支持文件上传到 FTP 服务器
|
|
|
+ - 生成唯一文件标识
|
|
|
+ - 支持文件的存储和检索
|
|
|
+
|
|
|
+### 3. 多数据源配置
|
|
|
+
|
|
|
+模块配置了两个数据源:
|
|
|
+- **AI 数据源**: 用于 AI 相关业务数据
|
|
|
+- **企微数据源**: 用于企业微信相关业务数据
|
|
|
+
|
|
|
+## 配置说明
|
|
|
+
|
|
|
+### 应用配置 (application.properties)
|
|
|
+
|
|
|
+```properties
|
|
|
+# 应用名称
|
|
|
+spring.application.name=linkwe-ai
|
|
|
+
|
|
|
+# FTP 服务器配置
|
|
|
+ftp.server=ftp.example.com
|
|
|
+ftp.port=21
|
|
|
+ftp.username=your_username
|
|
|
+ftp.password=your_password
|
|
|
+ftp.base-dir=/path/to/base/directory
|
|
|
+```
|
|
|
+
|
|
|
+### 常量配置 (Constant.java)
|
|
|
+
|
|
|
+```java
|
|
|
+public class Constant {
|
|
|
+ // 阿里云 API Key (注意:生产环境应从配置中心或环境变量获取)
|
|
|
+ public static String KEY = "sk-1f095e5103dd4567a9afec6b17ec0187";
|
|
|
+
|
|
|
+ // 支持的模型
|
|
|
+ public static String DEEPSEEK_R1 = "deepseek-r1";
|
|
|
+ public static String QWEN_PLUS = "qwen-plus";
|
|
|
+ public static String QWQ_32B = "qwq-32b";
|
|
|
+
|
|
|
+ // 文件上传路径
|
|
|
+ public static final String FILE_UPLOAD_PATH = "path/to/upload/directory";
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+## API 接口文档
|
|
|
+
|
|
|
+### 1. 阿里云 AI 接口
|
|
|
+
|
|
|
+#### 单次对话
|
|
|
+- **URL**: `/aliAi/single`
|
|
|
+- **Method**: POST
|
|
|
+- **Request Body**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "content": "用户输入的问题",
|
|
|
+ "filePath": "Word文档路径(可选)"
|
|
|
+}
|
|
|
+```
|
|
|
+- **Response**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "code": 200,
|
|
|
+ "msg": "success",
|
|
|
+ "data": {
|
|
|
+ "output": {
|
|
|
+ "choices": [{
|
|
|
+ "message": {
|
|
|
+ "reasoning_content": "AI的思考过程",
|
|
|
+ "content": "AI的最终回答"
|
|
|
+ }
|
|
|
+ }]
|
|
|
+ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+#### 多轮对话
|
|
|
+- **URL**: `/aliAi/multiwheel`
|
|
|
+- **Method**: POST
|
|
|
+- **Request Body**: 同单次对话
|
|
|
+- **Features**: 支持会话上下文管理
|
|
|
+
|
|
|
+#### 流式对话
|
|
|
+- **URL**: `/aliAi/stream`
|
|
|
+- **Method**: POST
|
|
|
+- **Content-Type**: `text/event-stream`
|
|
|
+- **Response**: 流式返回 GenerationResult
|
|
|
+
|
|
|
+### 2. 智能聊天接口
|
|
|
+
|
|
|
+#### 聊天对话
|
|
|
+- **URL**: `/zmAi/chat`
|
|
|
+- **Method**: POST
|
|
|
+- **CORS**: 支持跨域
|
|
|
+- **Request Body**:
|
|
|
+```json
|
|
|
+{
|
|
|
+ "content": "聊天内容",
|
|
|
+ "filePath": "文件路径(可选)"
|
|
|
+}
|
|
|
+```
|
|
|
+- **Response**: SseEmitter 对象,支持流式输出
|
|
|
+
|
|
|
+## 开发指南
|
|
|
+
|
|
|
+### 环境要求
|
|
|
+
|
|
|
+1. **JDK 1.8+**
|
|
|
+2. **Maven 3.5+**
|
|
|
+3. **Redis 3.0+**(用于会话缓存)
|
|
|
+4. **MySQL 5.7+**
|
|
|
+5. **FTP 服务器**(文件存储)
|
|
|
+
|
|
|
+### 本地开发
|
|
|
+
|
|
|
+1. **配置修改**
|
|
|
+ - 修改 `Constant.java` 中的 API Key
|
|
|
+ - 配置 `application.properties` 中的 FTP 连接信息
|
|
|
+ - 确保数据库和 Redis 连接正常
|
|
|
+
|
|
|
+2. **启动步骤**
|
|
|
+ ```bash
|
|
|
+ # 构建项目
|
|
|
+ mvn clean install
|
|
|
+
|
|
|
+ # 启动应用
|
|
|
+ mvn spring-boot:run
|
|
|
+ ```
|
|
|
+
|
|
|
+### 代码规范
|
|
|
+
|
|
|
+1. **API Key 安全**
|
|
|
+ - 生产环境应使用环境变量或配置中心存储 API Key
|
|
|
+ - 避免将密钥硬编码在代码中
|
|
|
+
|
|
|
+2. **异常处理**
|
|
|
+ - 统一使用 `SystemException` 处理业务异常
|
|
|
+ - 记录详细的错误日志
|
|
|
+
|
|
|
+3. **资源清理**
|
|
|
+ - 及时关闭 FTP 连接
|
|
|
+ - 管理 SSE 连接的生命周期
|
|
|
+
|
|
|
+## 扩展开发
|
|
|
+
|
|
|
+### 添加新的 AI 模型
|
|
|
+
|
|
|
+1. 在 `Constant.java` 中添加模型常量
|
|
|
+2. 在 `AliAiUtils.java` 中实现调用方法
|
|
|
+3. 在 Controller 中添加对应的接口
|
|
|
+
|
|
|
+### 自定义文件处理
|
|
|
+
|
|
|
+1. 扩展 `WordUtils.java` 支持更多文件格式
|
|
|
+2. 在 `FileController.java` 中添加新的处理接口
|
|
|
+3. 配置相应的文件解析器
|
|
|
+
|
|
|
+### 集成其他 AI 服务
|
|
|
+
|
|
|
+1. 添加新的 SDK 依赖到 `pom.xml`
|
|
|
+2. 创建新的工具类封装 API 调用
|
|
|
+3. 实现 Controller 层的接口
|
|
|
+
|
|
|
+## 部署说明
|
|
|
+
|
|
|
+### Docker 部署
|
|
|
+
|
|
|
+```dockerfile
|
|
|
+FROM openjdk:8-jre-alpine
|
|
|
+COPY target/lw-ai.jar app.jar
|
|
|
+EXPOSE 8080
|
|
|
+ENTRYPOINT ["java", "-jar", "/app.jar"]
|
|
|
+```
|
|
|
+
|
|
|
+### 配置管理
|
|
|
+
|
|
|
+- 使用 Nacos 配置中心管理动态配置
|
|
|
+- API Key、数据库连接等信息应外部化配置
|
|
|
+- 支持多环境配置切换(dev/test/prod)
|
|
|
+
|
|
|
+## 注意事项
|
|
|
+
|
|
|
+1. **API Key 安全**
|
|
|
+ - 当前代码中的 API Key 仅用于测试
|
|
|
+ - 生产环境必须使用安全的配置管理方案
|
|
|
+
|
|
|
+2. **性能优化**
|
|
|
+ - 大文件处理建议使用异步方式
|
|
|
+ - 合理设置 Redis 过期时间
|
|
|
+ - FTP 连接池复用
|
|
|
+
|
|
|
+3. **监控告警**
|
|
|
+ - 添加 API 调用量监控
|
|
|
+ - 设置异常响应时间告警
|
|
|
+ - 监控文件存储使用情况
|
|
|
+
|
|
|
+## 常见问题
|
|
|
+
|
|
|
+### Q: 如何切换不同的 AI 模型?
|
|
|
+A: 在调用 `AliAiUtils` 的方法时传入不同的 model 参数,支持的模型见 `Constant.java`。
|
|
|
+
|
|
|
+### Q: Word 文档解析失败怎么办?
|
|
|
+A: 检查文档格式是否为 `.docx`,确保文档没有损坏,查看 `WordUtils.java` 的错误日志。
|
|
|
+
|
|
|
+### Q: 流式响应中断如何处理?
|
|
|
+A: 检查网络连接,查看 SSE 连接状态,参考 `SSEHelper.java` 的错误处理逻辑。
|
|
|
+
|
|
|
+### Q: 如何扩展支持本地大模型?
|
|
|
+A: 参考 `ZmAiController.java` 中的 LOCAL 模式实现,添加新的配置和调用逻辑。
|
|
|
+
|
|
|
+## 版本历史
|
|
|
+
|
|
|
+- **v3.1.0**: 初始版本,集成阿里云 DashScope 服务
|
|
|
+- 支持单次、多轮、流式对话
|
|
|
+- 集成 Word 文档解析
|
|
|
+- 支持 FTP 文件存储
|
|
|
+
|
|
|
+## 联系方式
|
|
|
+
|
|
|
+如有问题或建议,请联系项目维护团队或提交 Issue。
|