|
|
@@ -1,324 +0,0 @@
|
|
|
-# 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。
|
jinshihui