# 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%，结合自动降级与熔断策略