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 提供的接口：

单次对话 (/aliAi/single)
- 支持文本输入和 Word 文档内容解析
- 返回完整的 AI 响应结果
- 包含思考过程和最终回答
多轮对话 (/aliAi/multiwheel)
- 支持上下文连续对话
- 通过 Redis 缓存会话历史
- 维护对话的连贯性
流式对话 (/aliAi/stream)
- 基于 Server-Sent Events (SSE) 的实时流式响应
- 使用 WebFlux 的 Flowable 实现响应式流
- 支持大文本的流式输出

ZmAiController 提供的接口：

智能聊天 (/zmAi/chat)
- 支持阿里云和本地模型切换
- 支持跨域请求
- 使用 SSE 实现实时响应

2. 文件处理功能

Word 文档解析
- 使用 Apache POI 解析 Word 文档
- 提取文档内容作为 AI 对话上下文
- 支持控制字符转义
FTP 文件存储
- 支持文件上传到 FTP 服务器
- 生成唯一文件标识
- 支持文件的存储和检索

3. 多数据源配置

模块配置了两个数据源：

AI 数据源: 用于 AI 相关业务数据
企微数据源: 用于企业微信相关业务数据

配置说明

应用配置 (application.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)

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:

{
"content": "用户输入的问题",
"filePath": "Word文档路径（可选）"
}

Response:

{
"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:

{
"content": "聊天内容",
"filePath": "文件路径（可选）"
}

Response: SseEmitter 对象，支持流式输出

开发指南

环境要求

JDK 1.8+
Maven 3.5+
Redis 3.0+（用于会话缓存）
MySQL 5.7+
FTP 服务器（文件存储）

本地开发

配置修改
- 修改 Constant.java 中的 API Key
- 配置 application.properties 中的 FTP 连接信息
- 确保数据库和 Redis 连接正常

启动步骤

# 构建项目
mvn clean install

# 启动应用
mvn spring-boot:run

代码规范

API Key 安全
- 生产环境应使用环境变量或配置中心存储 API Key
- 避免将密钥硬编码在代码中
异常处理
- 统一使用 SystemException 处理业务异常
- 记录详细的错误日志
资源清理
- 及时关闭 FTP 连接
- 管理 SSE 连接的生命周期

扩展开发

添加新的 AI 模型

在 Constant.java 中添加模型常量
在 AliAiUtils.java 中实现调用方法
在 Controller 中添加对应的接口

自定义文件处理

扩展 WordUtils.java 支持更多文件格式
在 FileController.java 中添加新的处理接口
配置相应的文件解析器

集成其他 AI 服务

添加新的 SDK 依赖到 pom.xml
创建新的工具类封装 API 调用
实现 Controller 层的接口

部署说明

Docker 部署

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）

注意事项

API Key 安全
- 当前代码中的 API Key 仅用于测试
- 生产环境必须使用安全的配置管理方案
性能优化
- 大文件处理建议使用异步方式
- 合理设置 Redis 过期时间
- FTP 连接池复用
监控告警
- 添加 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。

CLAUDE.md 9.0 KB تاريخچه خام