first commit

2026-02-22 12:12:02 +08:00
commit b236048a24
1467 changed files with 160403 additions and 0 deletions
@@ -0,0 +1,549 @@
+# AI模块 (ruoyi-ai)
+
+## 模块简介
+
+`ruoyi-ai` 是 PoJie 项目的 AI 服务中心模块，提供统一的 AI 能力接入，标准化接入主流模型与平台，支持聊天、流式对话、AI创作、智能PPT、多模态理解、代码助手、RAG增强与统一监控等功能。
+
+## 功能特性
+
+### 1. Provider 管理与编排 ✅
+- ✅ 统一接口：`AiProviderManager` 管理所有模型提供商，支持热切换
+- ✅ 智能路由：`AiOrchestrationEngine` 支持最快响应、最佳质量、成本最优、负载均衡等策略
+- ✅ 自动降级：错误率>30%或响应超时自动熔断与故障转移
+- ✅ 多模型接入：统一调度 OpenAI、Azure、ChatGLM、通义千问、智谱等主流模型
+
+### 2. 聊天与流式交互 ✅
+- ✅ 同步/异步聊天
+- ✅ SSE 流式推送
+- ✅ WebSocket 实时通道 (`/ws/ai/chat`)
+- ✅ 聊天历史管理：自动保存聊天记录到Redis，支持历史查询、清除和会话统计
+
+### 3. AI 辅助编码 ✅
+- ✅ 代码分析：提供代码审查与重构建议
+- ✅ 脚手架生成：自动生成项目结构与配置
+
+### 4. Simple AI & RAG ✅
+- ✅ 知识库问答：基于知识库的精准问答
+- ✅ 向量检索：支持多模型向量相似度搜索
+
+### 5. AI 创作与多模态 ✅
+- ✅ 绘画调度：统一管理 DALL·E-3、MidJourney、Stable Diffusion 任务
+- ✅ 智能 PPT：文本生成 PPTX，支持导出图片序列
+- ✅ 多模态：文件解析（PDF/Word）、OCR识别、图像理解
+
+### 6. 平台集成 ✅
+- ✅ FastGPT：深度对接 FastGPT 平台
+- ✅ Coze：深度对接 Coze 平台（SSE流式）
+- ✅ DIFY：深度对接 DIFY 平台
+
+### 7. MCP 生态 ✅
+- ✅ 工具注册：`McpToolRegistry` 支持动态工具加载与调用
+- ✅ 工具模板：提供多个内置工具（ProjectScaffold、DataTransform、ApiCall、AlgorithmCompute、FileParse、HttpFetch）
+
+### 8. 安全与监控 ✅
+- ✅ 安全卫士：`AiSecurityManager` 提供内容过滤、IP黑白名单、速率限制
+- ✅ 全链路监控：实时监控队列深度、模型健康度、响应时间与 Token 消耗
+- ✅ 使用统计：记录和统计AI使用情况
+
+## 数据库表
+
+- `ai_provider_config` - AI Provider配置表
+- `ai_provider_config_history` - AI Provider配置历史表
+- `ai_chat_record` - AI聊天记录表
+- `ai_usage_stats` - AI使用统计表
+- `ai_rating_record` - AI评价记录表
+
+详细表结构请参考：`script/sql/ry_ai.sql`
+
+## 模块结构
+
+```
+org.dromara.ai
+├── config/              # 模块配置类
+│   ├── AiAutoConfiguration.java
+│   ├── AiGatewayProperties.java
+│   ├── AiProviderRegistrar.java
+│   └── *ProviderConfig.java (各Provider配置)
+├── controller/          # REST API控制器
+│   ├── admin/                         # 管理端接口
+│   │   ├── AdminAiChatRecordController.java    # 聊天记录管理接口
+│   │   ├── AdminAiUsageStatsController.java    # 使用统计管理接口
+│   │   ├── AdminAiProviderController.java      # Provider管理接口
+│   │   └── AdminSysModelController.java        # 系统模型管理接口
+│   └── app/                           # 用户端接口
+│       ├── AiChatController.java                # 聊天接口
+│       ├── AiAssistantController.java           # 代码助手接口
+│       ├── AiPaintingController.java            # 绘画接口
+│       ├── AiImageController.java               # DALL·E-3接口
+│       ├── PptController.java                   # PPT生成接口
+│       ├── MultimodalController.java            # 多模态接口
+│       ├── SimpleAiController.java              # Simple AI接口
+│       ├── FastGptController.java               # FastGPT接口
+│       ├── CozeController.java                  # Coze接口
+│       ├── DifyController.java                  # DIFY接口
+│       ├── McpController.java                   # MCP工具接口
+│       └── QueueMetricsController.java          # 队列指标接口
+├── domain/              # 数据传输对象 (DTO) 与枚举
+│   ├── dto/
+│   └── enums/
+│       └── AiProviderType.java
+├── provider/            # 模型 Provider 实现
+│   ├── AiProvider.java
+│   ├── AiProviderManager.java
+│   ├── OpenAiProvider.java
+│   ├── AzureOpenAiProvider.java
+│   ├── QwenProvider.java
+│   ├── ZhipuAiProvider.java
+│   └── *Provider.java
+├── service/             # 核心业务服务
+│   ├── AiChatService.java
+│   ├── AiChatHistoryService.java
+│   ├── AiCodingAssistantService.java
+│   ├── AiModelService.java
+│   ├── AiPaintingService.java
+│   └── SimpleAiService.java
+├── orchestration/       # AI 编排引擎
+│   └── AiOrchestrationEngine.java
+├── painting/            # 绘画服务与 Provider
+│   ├── PaintingEngineType.java
+│   ├── PaintingTask.java
+│   ├── PaintingStatus.java
+│   └── provider/
+├── platform/            # 外部平台集成
+│   ├── FastGptService.java
+│   ├── CozeService.java
+│   └── DifyClientService.java
+├── mcp/                 # MCP 工具链与集成
+│   ├── McpToolRegistry.java
+│   ├── McpTool.java
+│   └── tools/
+├── queue/               # 任务队列服务
+│   └── TaskQueueService.java
+├── security/            # 安全管理器
+│   ├── AiSecurityManager.java
+│   ├── AiContentFilterService.java
+│   └── AiAccessControlService.java
+├── monitor/             # 监控指标与度量
+│   ├── AiMonitorService.java
+│   └── *Metrics.java
+├── websocket/           # WebSocket 处理器
+│   ├── ChatWebSocketConfig.java
+│   └── ChatWebSocketHandler.java
+└── error/               # 全局异常处理
+    └── AiErrorHandler.java
+```
+
+## 配置说明
+
+在 `application.yml` 中添加以下配置：
+
+```yaml
+ai:
+  gateway:
+    enabled: true
+    auth-required: true
+    base-path: /api/ai
+  provider:
+    timeout-ms: 60000
+    retry: 1
+
+ruoyi:
+  ai:
+    enabled: true
+    external-ai:
+      openai:
+        base-url: https://api.openai.com
+        api-key: sk-xxxx
+      azure-openai:
+        endpoint: https://your-endpoint.openai.azure.com
+        api-key: your-api-key
+        api-version: 2023-12-01-preview
+      qwen:
+        base-url: https://dashscope.aliyuncs.com/api/v1
+        api-key: sk-xxxx
+      zhipu:
+        base-url: https://open.bigmodel.cn/api/paas/v4
+        api-key: sk-xxxx
+      sd:
+        base-url: http://localhost:7860
+      midjourney:
+        base-url: https://mj.example.com
+        token: mj-xxxx
+    ocr:
+      base-url: https://ocr.example.com
+    platform:
+      fastgpt:
+        base-url: https://fastgpt.example.com
+        token: fgpt-xxxx
+      coze:
+        base-url: https://coze.example.com
+        token: coze-xxxx
+      dify:
+        base-url: https://dify.example.com
+        token: dify-xxxx
+```
+
+## API接口
+
+### 聊天接口 (`/ai/chat`)
+
+#### 同步聊天
+- `POST /ai/chat/sync` - 同步聊天（返回完整响应）
+
+#### 异步聊天
+- `POST /ai/chat/async` - 异步聊天（返回任务ID）
+
+#### 流式聊天
+- `POST /ai/chat/stream` - SSE流式聊天
+- `POST /ai/chat/stream-chunks` - 流式聊天（分块返回）
+
+#### 批量聊天
+- `POST /ai/chat/batch` - 批量聊天请求
+
+#### 聊天历史
+- `GET /ai/chat/history/{sessionId}` - 获取聊天历史
+- `DELETE /ai/chat/history/{sessionId}` - 清除聊天历史
+
+#### 会话统计
+- `GET /ai/chat/stats/{sessionId}` - 获取会话统计
+
+### AI代码助手接口 (`/ai/assistant`)
+
+- `POST /ai/assistant/analyze` - 代码分析
+- `POST /ai/assistant/scaffold` - 生成项目脚手架
+
+### Provider管理接口 (`/ai/provider`)
+
+- `GET /ai/provider/list` - 列出所有Provider
+- `GET /ai/provider/models` - 列出所有模型
+- `GET /ai/provider/default` - 获取默认Provider
+- `POST /ai/provider/setDefault` - 设置默认Provider
+- `GET /ai/provider/stats/system` - 系统统计
+- `GET /ai/provider/stats/providers` - Provider统计
+- `POST /ai/provider/stats/reset` - 重置统计
+
+### Simple AI接口 (`/ai`)
+
+- `POST /ai/ask` - 知识库问答
+- `POST /ai/search` - 向量搜索
+- `GET /ai/stats/{knowledgeId}` - 知识库统计
+- `GET /ai/model/check/{modelName}` - 检查模型可用性
+- `GET /ai/models` - 获取可用模型列表
+- `GET /ai/health` - 健康检查
+
+### 绘画接口 (`/ai/painting`)
+
+- `POST /ai/painting/task` - 创建绘画任务
+- `GET /ai/painting/status/{taskId}` - 查询任务状态
+- `GET /ai/painting/stream/{taskId}` - SSE流式获取任务进度
+
+### DALL·E-3接口
+
+- `POST /dall3` - 文生图
+- `POST /dall3/edit` - 图片编辑（image+mask）
+- `POST /dall3/variations` - 图片变体
+
+### 智能PPT接口 (`/ppt`)
+
+- `POST /ppt/generate` - 生成PPTX文件
+- `POST /ppt/export/pngs` - 导出PNG序列
+
+### 多模态接口 (`/multimodal`)
+
+- `POST /multimodal/extract` - 文件解析（PDF/Word等）
+- `POST /multimodal/ocr` - OCR识别
+- `POST /multimodal/analyze/text` - 文本分析
+- `POST /multimodal/analyze/image` - 图像识别（占位）
+- `POST /multimodal/caption` - 图生文（占位）
+
+### 平台集成接口
+
+#### FastGPT (`/ai/fastgpt`)
+- `POST /ai/fastgpt/knowledge/search` - 知识搜索
+- `POST /ai/fastgpt/workflow/run` - 运行工作流
+- `GET /ai/fastgpt/context/{sessionId}` - 获取上下文
+
+#### Coze (`/ai/coze`)
+- `POST /ai/coze/stream` - SSE流式对话
+
+#### DIFY (`/ai/dify`)
+- `GET /ai/dify/apps` - 获取应用列表
+- `POST /ai/dify/apps` - 创建/更新应用
+
+### MCP工具接口 (`/ai/mcp`)
+
+- `GET /ai/mcp/tools` - 获取工具列表
+- `POST /ai/mcp/invoke/{name}` - 调用工具
+
+### 队列指标接口 (`/ai/queue`)
+
+- `GET /ai/queue/metrics` - 获取队列指标
+
+## WebSocket实时通道
+
+### 聊天WebSocket
+- **端点**: `ws://localhost:8080/ws/ai/chat`
+- **协议**: JSON格式 `AiChatRequest`，支持实时双向对话
+
+## 依赖模块
+
+- `ruoyi-common-core` - 通用核心工具
+- `ruoyi-common-web` - Web通用组件
+- `ruoyi-common-redis` - Redis缓存
+- `ruoyi-common-security` - 安全组件
+- `ruoyi-common-log` - 日志组件
+- `ruoyi-common-mybatis` - MyBatis组件
+- `ruoyi-knowledge` - 知识库模块（RAG增强，可选）
+
+## 使用示例
+
+### 1. 聊天与流式对话
+
+```bash
+# 同步聊天
+curl -X POST http://localhost:8080/api/ai/chat/sync \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}],"sessionId":"session_123"}'
+
+# 流式聊天
+curl -X POST http://localhost:8080/api/ai/chat/stream \
+  -H "Authorization: Bearer <token>" \
+  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}],"stream":true,"sessionId":"session_123"}'
+
+# 获取聊天历史
+curl -X GET "http://localhost:8080/api/ai/chat/history/session_123?limit=50" \
+  -H "Authorization: Bearer <token>"
+```
+
+### 2. AI代码助手
+
+```bash
+# 代码分析
+curl -X POST http://localhost:8080/api/ai/assistant/analyze \
+  -d 'code=public void test(){...}&model=gpt-4'
+
+# 生成脚手架
+curl -X POST http://localhost:8080/api/ai/assistant/scaffold \
+  -d 'appType=SpringBoot&options={"db":"mysql"}'
+```
+
+### 3. Simple AI (RAG)
+
+```bash
+# 知识库问答
+curl -X POST "http://localhost:8080/api/ai/ask?knowledgeId=kb_123&question=合同流程是怎样的"
+
+# 向量搜索
+curl -X POST "http://localhost:8080/api/ai/search?knowledgeId=kb_123&queryText=条款&topK=3"
+```
+
+### 4. AI绘画任务
+
+```bash
+# 创建绘画任务
+curl -X POST http://localhost:8080/api/ai/painting/task \
+  -H "Content-Type: application/json" \
+  -d '{"engine":"DALL_E_3","prompt":"未来城市","params":{"size":"1024x1024"}}'
+
+# 查询任务状态
+curl http://localhost:8080/api/ai/painting/status/{taskId}
+```
+
+### 5. 智能PPT生成
+
+```bash
+curl -X POST "http://localhost:8080/api/ai/ppt/generate?content=第一页标题\n内容1\n第二页标题\n内容2"
+```
+
+### 6. MCP工具调用
+
+```bash
+curl -X POST http://localhost:8080/api/ai/mcp/invoke/api_call \
+  -H "Content-Type: application/json" \
+  -d '{"url":"https://httpbin.org/get"}'
+```
+
+## 安全与合规
+
+`AiSecurityManager` 默认开启，提供以下保护：
+
+- **API密钥验证**：校验请求中的 `apiKey`
+- **IP访问控制**：基于策略拦截非法IP
+- **内容过滤**：输入/输出双向敏感词过滤（Moderate策略）
+- **资源限额**：基于Token数与模型复杂度的动态配额扣除
+- **速率限制**：防止API滥用
+
+## 监控与统计
+
+### 监控指标
+- 队列深度监控
+- 模型健康度监控
+- 响应时间监控
+- Token消耗监控
+- 错误率监控
+
+### 使用统计
+- 用户使用统计（按用户、Provider、模型）
+- 请求次数统计
+- 成功率统计
+- 成本统计
+
+## 注意事项
+
+1. **密钥安全**：生产环境务必通过环境变量注入 API Key，不要将密钥写入配置文件
+2. **流式代理**：Nginx/Gateway 需配置 `proxy_buffering off` 以支持 SSE
+3. **依赖服务**：Redis 必须可用，用于存储任务状态与缓存
+4. **性能优化**：建议对热点数据使用Redis缓存
+5. **错误处理**：模块提供自动降级和熔断机制，但建议监控错误率
+6. **并发控制**：Provider支持最大并发数配置，合理设置以避免资源耗尽
+
+## 扩展开发
+
+### 添加新的Provider
+
+1. 实现 `AiProvider` 接口
+2. 创建对应的配置类（如 `XxxProviderConfig.java`）
+3. 在 `AiProviderRegistrar` 中注册Provider
+4. 在 `AiProviderType` 枚举中添加新的Provider类型
+
+### 添加新的MCP工具
+
+1. 实现 `McpTool` 接口
+2. 在 `AiProviderRegistrar` 中注册工具
+3. 工具会自动出现在工具列表中
+
+## 相关文档
+
+- [API详细文档](docs/API.md)
+- [配置说明](docs/CONFIG.md)
+- [集成指南](docs/INTEGRATION.md)
+- [AI创作系统开发指南](#ruoyi-ai-创作系统开发指南)
+
+---
+
+# RuoYi-AI 创作系统开发指南
+
+本指南介绍 `ruoyi-ai` 模块中的 AI 创作能力，包括绘画引擎接入、智能 PPT 生成、多模态内容理解，以及统一的任务流与接口规范。
+
+> 该文档同时覆盖平台深度集成（FastGPT/Coze/DIFY）、MCP生态扩展、RAG增强、队列与长任务监控、质量与性能保障等内容，便于端到端落地与运维。
+
+## 模块概览
+
+### 绘画引擎集成（DALL·E-3 / MidJourney / Stable Diffusion）
+- 统一引擎枚举：`painting/PaintingEngineType.java`
+- 任务模型：`painting/PaintingTask.java`
+- 任务状态：`painting/PaintingStatus.java`
+- 引擎适配：
+  - DALL·E-3：`painting/provider/DallE3Provider.java`
+  - MidJourney：`painting/provider/MidJourneyProvider.java`
+  - Stable Diffusion：`painting/provider/StableDiffusionProvider.java`
+- 统一服务：`service/AiPaintingService.java`
+- 控制器：`controller/AiPaintingController.java`
+
+### 智能 PPT 生成
+- 控制器：`controller/PptController.java`
+- 能力：按文本生成 PPTX、导出每页 PNG 序列、主题占位与扩展点
+
+### 多模态内容理解
+- 控制器：`controller/MultimodalController.java`
+- 能力：文件解析（Tika）、文本分析、OCR占位、图像识别占位、图生文占位
+
+### DALL·E-3 扩展
+- 控制器：`controller/AiImageController.java`
+- 能力：文生图、编辑（image+mask）、变体（variations）
+
+### 平台接入与统一API
+- FastGPT：服务 `platform/FastGptService.java`，接口 `controller/FastGptController.java`
+- Coze：服务 `platform/CozeService.java`，接口 `controller/CozeController.java`（SSE流式）
+- DIFY：服务 `platform/DifyClientService.java`，接口 `controller/DifyController.java`
+
+### MCP生态扩展
+- 工具注册：`mcp/McpToolRegistry.java`（动态加载/版本管理/热重载）
+- 工具模板：`mcp/tools/*.java`（≥5个：ProjectScaffold/DataTransform/ApiCall/AlgorithmCompute/FileParse/HttpFetch）
+- 控制器：`controller/McpController.java`（工具列表与调用）
+
+### 统一模型调度与降级
+- 管理器：`provider/AiProviderManager.java`（模型优先→性能优选→近似轮询、自动降级）
+- 管理接口：`controller/admin/AdminAiProviderController.java`（列表/模型/默认/统计）
+
+### 队列与长任务
+- 服务：`queue/TaskQueueService.java`（优先级队列、任务状态与指标）
+- 指标接口：`controller/QueueMetricsController.java`
+
+## 配置项
+
+### OpenAI
+- `ruoyi.ai.external-ai.openai.base-url`（默认 `https://api.openai.com`）
+- `ruoyi.ai.external-ai.openai.api-key`
+
+### Azure OpenAI
+- `ruoyi.ai.external-ai.azure-openai.endpoint`
+- `ruoyi.ai.external-ai.azure-openai.api-key`
+- `ruoyi.ai.external-ai.azure-openai.api-version`
+
+### MidJourney
+- `ruoyi.ai.external-ai.midjourney.base-url`
+- `ruoyi.ai.external-ai.midjourney.token`
+
+### Stable Diffusion
+- `ruoyi.ai.external-ai.sd.base-url`（例如 `http://localhost:7860`）
+
+### OCR
+- `ruoyi.ai.ocr.base-url`
+
+### 平台
+- `ruoyi.ai.platform.fastgpt.base-url`、`ruoyi.ai.platform.fastgpt.token`
+- `ruoyi.ai.platform.coze.base-url`、`ruoyi.ai.platform.coze.token`
+- `ruoyi.ai.platform.dify.base-url`、`ruoyi.ai.platform.dify.token`
+
+## API 速览
+
+### 绘画任务统一接口（REST + SSE）
+- 创建任务：`POST /ai/painting/task`
+  - body：`{"engine":"DALL_E_3","prompt":"海边日落","params":{"size":"1024x1024"}}`
+  - 返回：`{"taskId":"..."}`（任务 ID）
+- 查询状态：`GET /ai/painting/status/{taskId}`
+- 进度流：`GET /ai/painting/stream/{taskId}`（SSE，[DONE] 结束）
+
+### DALL·E-3
+- 文生图：`POST /dall3`（`prompt`,`size`）
+- 编辑：`POST /dall3/edit`（`prompt`,`size`,`image`,`mask?`）
+- 变体：`POST /dall3/variations`（`size`,`image`）
+
+### 智能 PPT
+- 生成 PPTX：`POST /ppt/generate`（按行拆分内容为多页）
+- 导出 PNG 序列：`POST /ppt/export/pngs`（返回 `data:image/png;base64,...` 列表）
+
+### 多模态
+- 文件解析：`POST /multimodal/extract`（`multipart/form-data:file`）
+- OCR识别：`POST /multimodal/ocr`（需配置 OCR 服务）
+- 文本分析：`POST /multimodal/analyze/text`（返回 `title/summary/keywords`）
+- 图像识别占位：`POST /multimodal/analyze/image`
+- 图生文占位：`POST /multimodal/caption`
+
+## 流式与实时
+
+- **SSE**：`/ai/painting/stream/{taskId}` 推送任务状态与进度；统一以 `[DONE]` 结束
+- **WebSocket**：模块已提供聊天通道 `ws/ai/chat`；如需绘画通道，可参考该模式新增 `/ws/ai/painting`
+
+## 任务与历史
+
+- 任务创建后进入线程池异步执行，状态与结果存储于 Redis：键 `ai:painting:task:{taskId}`
+- 可基于该结构扩展作品历史管理、检索与归档
+
+## 扩展建议
+
+- **引擎负载均衡**：为 Provider 增加实例列表与健康检查，依据权重分配
+- **任务队列**：接入消息队列（如 Kafka/RabbitMQ）实现更大的并发与可靠性
+- **权限与用量**：接入 `sa-token` 与用量计费，限制频率与配额
+- **监控与审计**：统一接入日志、指标与告警，便于运维与合规
+- **RAG增强**：在 `ruoyi-knowledge` 实现 `VectorDbClient` 接入层（Milvus/Weaviate/Qdrant），集成 BGE-large-zh-v1.5 批量嵌入与缓存，混合检索（关键词+向量）召回≥90%
+- **队列看板**：在管理端提供队列深度/处理速率可视化与失败重试控制
+
+## 测试与质量
+
+- **单元测试**：建议使用 MockWebServer 模拟外部 API，覆盖率目标 ≥ 80%
+- **性能**：核心 API 响应时间 < 500ms（外部调用除外），并发可通过线程池与队列扩展至 1000+
+- **压测与限流**：模拟 1000+ 并发，结合令牌桶限流，P99 延迟控制在 2s 以内
+- **可用性**：关键服务可用性目标 ≥ 99.9%，结合自动降级与熔断策略