# AI模块结构说明 ## 模块简介 `ruoyi-ai` 是 PoJie 项目的 AI 服务中心模块，提供统一的 AI 能力接入，标准化接入主流模型与平台，支持聊天、流式对话、AI创作、智能PPT、多模态理解、代码助手、RAG增强与统一监控等功能。 ## 模块结构 `ruoyi-ai` 是一个独立的业务模块，采用分层架构设计： ``` org.dromara.ai ├── config/ # 模块配置类 │ ├── AiAutoConfiguration.java # 自动配置类 │ ├── AiGatewayProperties.java # 网关配置属性 │ ├── AiProviderRegistrar.java # Provider注册器 │ ├── AiConfigurationManager.java # 配置管理器 │ ├── AiApiConfig.java # API配置 │ └── *ProviderConfig.java # 各Provider配置类（OpenAI、Azure、Qwen、Zhipu等） ├── controller/ # REST API控制器 │ ├── admin/ # 管理端接口 │ │ ├── AdminAiChatRecordController.java # 聊天记录管理接口 │ │ ├── AdminAiUsageStatsController.java # 使用统计管理接口 │ │ ├── AdminAiRatingRecordController.java # 评价记录管理接口 │ │ ├── AdminAiProviderController.java # Provider管理接口 │ │ ├── AdminAiProviderConfigController.java # Provider配置管理接口 │ │ ├── AdminAiProviderConfigHistoryController.java # Provider配置历史管理接口 │ │ ├── AdminAiSensitiveWordController.java # 敏感词管理接口 │ │ ├── AdminAiPaintingRecordController.java # 绘画历史记录管理接口 │ │ ├── AdminAiPaintingTemplateController.java # 绘画参数模板管理接口 │ │ ├── AdminAiPaintingFavoriteController.java # 绘画作品收藏管理接口 │ │ ├── AdminAiUserQuotaController.java # 用户配额管理接口 │ │ └── 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 # 队列指标接口 │ ├── AppAiRatingRecordController.java # 评价记录接口（用户端） │ ├── AppAiPaintingFavoriteController.java # 绘画作品收藏接口（用户端） │ └── AppAiUserQuotaController.java # 用户配额接口（用户端） ├── domain/ # 领域对象 │ ├── AiChatRecord.java # 聊天记录实体 │ ├── AiUsageStats.java # 使用统计实体 │ ├── AiRatingRecord.java # 评价记录实体 │ ├── AiProviderConfig.java # Provider配置实体 │ ├── AiProviderConfigHistory.java # Provider配置历史实体 │ ├── AiSensitiveWord.java # 敏感词实体 │ ├── AiPaintingRecord.java # 绘画历史记录实体 │ ├── AiPaintingTemplate.java # 绘画参数模板实体 │ ├── AiPaintingFavorite.java # 绘画作品收藏实体 │ ├── AiUserQuota.java # 用户配额实体 │ ├── bo/ # 业务对象(BO) │ │ ├── AiChatRecordBo.java # 聊天记录BO │ │ ├── AiUsageStatsBo.java # 使用统计BO │ │ ├── AiRatingRecordBo.java # 评价记录BO │ │ ├── AiProviderConfigBo.java # Provider配置BO │ │ ├── AiProviderConfigHistoryBo.java # Provider配置历史BO │ │ ├── AiSensitiveWordBo.java # 敏感词BO │ │ ├── AiPaintingRecordBo.java # 绘画历史记录BO │ │ ├── AiPaintingTemplateBo.java # 绘画参数模板BO │ │ ├── AiPaintingFavoriteBo.java # 绘画作品收藏BO │ │ └── AiUserQuotaBo.java # 用户配额BO │ ├── vo/ # 视图对象(VO) │ │ ├── AiChatRecordVo.java # 聊天记录VO │ │ ├── AiUsageStatsVo.java # 使用统计VO │ │ ├── AiRatingRecordVo.java # 评价记录VO │ │ ├── AiProviderConfigVo.java # Provider配置VO │ │ ├── AiProviderConfigHistoryVo.java # Provider配置历史VO │ │ ├── AiSensitiveWordVo.java # 敏感词VO │ │ ├── AiPaintingRecordVo.java # 绘画历史记录VO │ │ ├── AiPaintingTemplateVo.java # 绘画参数模板VO │ │ ├── AiPaintingFavoriteVo.java # 绘画作品收藏VO │ │ └── AiUserQuotaVo.java # 用户配额VO │ ├── dto/ # 数据传输对象(DTO) │ │ ├── AiChatRequest.java # 聊天请求DTO │ │ ├── AiChatResponse.java # 聊天响应DTO │ │ └── AiModelInfo.java # 模型信息DTO │ └── enums/ # 枚举类 │ └── AiProviderType.java # Provider类型枚举 ├── provider/ # 模型 Provider 实现 │ ├── AiProvider.java # Provider接口 │ ├── AbstractAiProvider.java # Provider抽象基类 │ ├── AiProviderManager.java # Provider管理器 │ ├── OpenAiProvider.java # OpenAI Provider │ ├── AzureOpenAiProvider.java # Azure OpenAI Provider │ ├── QwenProvider.java # 通义千问 Provider │ ├── ZhipuAiProvider.java # 智谱AI Provider │ ├── FastGptProvider.java # FastGPT Provider │ ├── CozeProvider.java # Coze Provider │ ├── DifyProvider.java # DIFY Provider │ └── impl/ # Provider实现 │ └── MockAiProvider.java # Mock Provider（测试用） ├── service/ # 核心业务服务 │ ├── AiChatService.java # 聊天服务 │ ├── AiChatHistoryService.java # 聊天历史服务 │ ├── AiCodingAssistantService.java # 代码助手服务 │ ├── AiModelService.java # 模型服务 │ ├── AiPaintingService.java # 绘画服务 │ └── SimpleAiService.java # Simple AI服务 ├── orchestration/ # AI 编排引擎 │ └── AiOrchestrationEngine.java # 编排引擎（智能路由、负载均衡、降级） ├── painting/ # 绘画服务与 Provider │ ├── PaintingEngineType.java # 绘画引擎类型枚举 │ ├── PaintingTask.java # 绘画任务模型 │ ├── PaintingStatus.java # 绘画状态枚举 │ ├── PaintingProvider.java # 绘画Provider接口 │ └── provider/ # 绘画Provider实现 │ ├── DallE3Provider.java # DALL·E-3 Provider │ ├── MidJourneyProvider.java # MidJourney Provider │ └── StableDiffusionProvider.java # Stable Diffusion Provider ├── platform/ # 外部平台集成 │ ├── FastGptService.java # FastGPT服务 │ ├── CozeService.java # Coze服务 │ └── DifyClientService.java # DIFY客户端服务 ├── mcp/ # MCP 工具链与集成 │ ├── McpToolRegistry.java # MCP工具注册表 │ ├── McpTool.java # MCP工具接口 │ ├── McpIntegrationService.java # MCP集成服务 │ └── tools/ # MCP工具实现 │ ├── ProjectScaffoldTool.java # 项目脚手架工具 │ ├── DataTransformTool.java # 数据转换工具 │ ├── ApiCallTool.java # API调用工具 │ ├── AlgorithmComputeTool.java # 算法计算工具 │ ├── FileParseTool.java # 文件解析工具 │ └── HttpFetchTool.java # HTTP获取工具 ├── queue/ # 任务队列服务 │ └── TaskQueueService.java # 任务队列服务（优先级队列、任务状态管理） ├── security/ # 安全管理器 │ ├── AiSecurityManager.java # 安全管理器 │ ├── AiContentFilterService.java # 内容过滤服务 │ └── AiAccessControlService.java # 访问控制服务 ├── monitor/ # 监控指标与度量 │ ├── AiMonitorService.java # 监控服务 │ ├── BaseMetrics.java # 基础指标 │ ├── SystemMetrics.java # 系统指标 │ ├── ProviderMetrics.java # Provider指标 │ ├── ModelMetrics.java # 模型指标 │ └── UserMetrics.java # 用户指标 ├── websocket/ # WebSocket 处理器 │ ├── ChatWebSocketConfig.java # WebSocket配置 │ └── ChatWebSocketHandler.java # WebSocket处理器 ├── error/ # 全局异常处理 │ └── AiErrorHandler.java # AI异常处理器 └── model/ # 通用模型 └── ApiResult.java # API结果模型 ``` ## 已完成工作 ### 1. 模块结构 - ✅ 创建了完整的模块目录结构 - ✅ 创建了 `pom.xml` 配置文件 - ✅ 配置了模块依赖关系（ruoyi-common-*、ruoyi-knowledge等） ### 2. 自动配置 - ✅ 创建了 `AiAutoConfiguration` 自动配置类 - ✅ 配置了组件扫描 - ✅ 支持通过 `ruoyi.ai.enabled` 配置启用/禁用模块 ### 3. Provider 管理与编排 ✅ - ✅ 统一接口：`AiProviderManager` 管理所有模型提供商，支持热切换 - ✅ 智能路由：`AiOrchestrationEngine` 支持最快响应、最佳质量、成本最优、负载均衡等策略 - ✅ 自动降级：错误率>30%或响应超时自动熔断与故障转移 - ✅ 多模型接入：统一调度 OpenAI、Azure、ChatGLM、通义千问、智谱等主流模型 - ✅ Provider配置管理：支持数据库配置和动态更新 - ✅ Provider配置可视化界面（管理端）：CRUD管理、启用/禁用、导出功能 - ✅ Provider配置历史管理：自动记录配置变更历史，支持查询、导出 ### 4. 聊天与流式交互 ✅ - ✅ 同步/异步聊天接口 - ✅ SSE 流式推送 - ✅ WebSocket 实时通道 (`/ws/ai/chat`) - ✅ 聊天历史管理：自动保存聊天记录到Redis和数据库，支持历史查询、清除和会话统计 - ✅ 聊天记录持久化：Redis + 数据库双重存储 - ✅ 聊天记录管理：查询、导出、批量删除 - ✅ 批量聊天支持 ### 5. AI 辅助编码 ✅ - ✅ 代码分析：提供代码审查与重构建议 - ✅ 脚手架生成：自动生成项目结构与配置 ### 6. Simple AI & RAG ✅ - ✅ 知识库问答：基于知识库的精准问答 - ✅ 向量检索：支持多模型向量相似度搜索 - ✅ 知识库统计 ### 7. AI 创作与多模态 ✅ - ✅ 绘画调度：统一管理 DALL·E-3、MidJourney、Stable Diffusion 任务 - ✅ 绘画历史管理：数据库存储、CRUD管理、查询、导出功能 - ✅ 绘画参数模板：数据库存储、CRUD管理、公开/私有模板、用户模板管理 - ✅ 绘画作品收藏：数据库存储、CRUD管理、收藏/取消收藏、收藏列表查询 - ✅ 智能 PPT：文本生成 PPTX，支持导出图片序列 - ✅ 多模态：文件解析（PDF/Word）、OCR识别、图像理解（部分占位） ### 8. 平台集成 ✅ - ✅ FastGPT：深度对接 FastGPT 平台 - ✅ Coze：深度对接 Coze 平台（SSE流式） - ✅ DIFY：深度对接 DIFY 平台 ### 9. MCP 生态 ✅ - ✅ 工具注册：`McpToolRegistry` 支持动态工具加载与调用 - ✅ 工具模板：提供多个内置工具（ProjectScaffold、DataTransform、ApiCall、AlgorithmCompute、FileParse、HttpFetch） ### 10. 安全与监控 ✅ - ✅ 安全卫士：`AiSecurityManager` 提供内容过滤、IP黑白名单、速率限制 - ✅ 敏感词库管理：数据库存储、CRUD管理、启用/禁用、导出功能 - ✅ 全链路监控：实时监控队列深度、模型健康度、响应时间与 Token 消耗 - ✅ 使用统计：记录和统计AI使用情况 ### 11. 数据库 - ✅ 创建了 `script/sql/ry_ai.sql` 文件 - ✅ 添加了 Provider配置表（`ai_provider_config`） - ✅ 添加了 Provider配置历史表（`ai_provider_config_history`） - ✅ 添加了聊天记录表（`ai_chat_record`） - ✅ 添加了使用统计表（`ai_usage_stats`） - ✅ 添加了评价记录表（`ai_rating_record`） - ✅ 添加了敏感词库表（`ai_sensitive_word`） - ✅ 添加了绘画历史记录表（`ai_painting_record`） - ✅ 添加了绘画参数模板表（`ai_painting_template`） - ✅ 添加了绘画作品收藏表（`ai_painting_favorite`） - ✅ 添加了用户配额管理表（`ai_user_quota`） ### 12. 文档 - ✅ 创建了模块 README.md 文件 ## 数据库表结构说明 ### 1. AI Provider配置表 (ai_provider_config) - **功能**: 存储AI模型提供商的配置信息 - **关键字段**: `provider_name`, `provider_type`, `enabled`, `priority`, `weight`, `max_concurrency`, `timeout_seconds`, `max_retries`, `api_config`, `model_config` - **索引**: `uk_provider_name` (唯一), `idx_provider_type`, `idx_enabled`, `idx_priority` - **状态说明**: - `enabled`: 0=禁用, 1=启用 - **配置说明**: - `priority`: 优先级（数字越小优先级越高） - `weight`: 权重（用于负载均衡） - `max_concurrency`: 最大并发数 - `timeout_seconds`: 超时时间（秒） - `max_retries`: 最大重试次数 - `api_config`: API配置（JSON格式，包含apiKey、baseUrl等） - `model_config`: 模型配置（JSON格式，包含defaultModel、supportedModels等） ### 2. AI Provider配置历史表 (ai_provider_config_history) - **功能**: 记录Provider配置的变更历史 - **关键字段**: `config_id`, `provider_name`, `config_data`, `operation_type`, `operation_time`, `operation_by` - **索引**: `idx_config_id`, `idx_provider_name`, `idx_operation_time` - **操作类型说明**: - CREATE: 创建配置 - UPDATE: 更新配置 - DELETE: 删除配置 ### 3. AI聊天记录表 (ai_chat_record) - **功能**: 存储AI聊天记录 - **关键字段**: `session_id`, `user_id`, `provider_name`, `model_name`, `message_type`, `content`, `tokens_used`, `cost`, `response_time`, `is_stream` - **索引**: `idx_session_id`, `idx_user_id`, `idx_provider_name`, `idx_create_time` - **消息类型说明**: - USER: 用户消息 - ASSISTANT: AI助手消息 - **状态说明**: - `is_stream`: 0=非流式, 1=流式响应 ### 4. AI使用统计表 (ai_usage_stats) - **功能**: 按用户、Provider、模型、日期统计AI使用情况 - **关键字段**: `user_id`, `provider_name`, `model_name`, `stat_date`, `request_count`, `success_count`, `error_count`, `total_tokens`, `total_cost`, `avg_response_time` - **索引**: `uk_user_provider_date` (唯一), `idx_provider_name`, `idx_stat_date` - **统计说明**: - `request_count`: 请求次数 - `success_count`: 成功次数 - `error_count`: 错误次数 - `total_tokens`: 总Token数 - `total_cost`: 总成本 - `avg_response_time`: 平均响应时间（毫秒） ### 5. AI评价记录表 (ai_rating_record) - **功能**: 记录用户对AI回复的评价 - **关键字段**: `message_id`, `user_id`, `provider_name`, `rating`, `feedback`, `dimension`, `anonymous` - **索引**: `uk_message_user` (唯一), `idx_provider_name`, `idx_rating`, `idx_create_time` - **评价说明**: - `rating`: 评分（1-5） - `dimension`: 评价维度（可选） - `anonymous`: 0=非匿名, 1=匿名 ## 功能清单 ### 已实现功能 ✅ #### 1. Provider 管理与编排 - ✅ Provider配置管理（数据库配置、动态更新） - ✅ Provider注册与发现 - ✅ 智能路由策略（最快响应、最佳质量、成本最优、负载均衡） - ✅ 自动降级与熔断 - ✅ Provider健康检查 - ✅ Provider统计与监控 #### 2. 聊天与流式交互 - ✅ 同步聊天接口 - ✅ 异步聊天接口 - ✅ SSE流式推送 - ✅ WebSocket实时通道 - ✅ 聊天历史管理（Redis存储） - ✅ 会话统计 - ✅ 批量聊天支持 #### 3. AI 辅助编码 - ✅ 代码分析（代码审查、重构建议） - ✅ 项目脚手架生成 #### 4. Simple AI & RAG - ✅ 知识库问答（基于ruoyi-knowledge模块） - ✅ 向量检索 - ✅ 知识库统计 #### 5. AI 创作与多模态 - ✅ 绘画任务管理（DALL·E-3、MidJourney、Stable Diffusion） - ✅ 绘画任务状态查询 - ✅ 绘画任务流式进度推送（SSE） - ✅ 智能PPT生成（文本生成PPTX） - ✅ PPT导出PNG序列 - ✅ 文件解析（PDF/Word等，基于Apache Tika） - ✅ 文本分析 - ✅ OCR识别（占位接口，需配置OCR服务） - ⏳ 图像识别（占位接口） - ⏳ 图生文（占位接口） #### 6. 平台集成 - ✅ FastGPT平台集成（知识搜索、工作流运行、上下文管理） - ✅ Coze平台集成（SSE流式对话） - ✅ DIFY平台集成（应用列表、创建/更新应用） #### 7. MCP 生态 - ✅ MCP工具注册与管理 - ✅ 工具调用接口 - ✅ 内置工具（ProjectScaffold、DataTransform、ApiCall、AlgorithmCompute、FileParse、HttpFetch） #### 8. 安全与监控 - ✅ 内容过滤 - ✅ IP访问控制（黑白名单） - ✅ 速率限制 - ✅ 全链路监控（队列深度、模型健康度、响应时间、Token消耗） - ✅ 使用统计（用户、Provider、模型维度） #### 9. AI评价功能 ✅ - ✅ 评价记录管理（用户评价AI回复） - ✅ 评价记录查询与导出 - ✅ 评价记录统计（平均评分） - ✅ 用户端评价接口（提交评价、查询评价） #### 10. 系统模型管理 - ✅ 模型信息查询 - ✅ 模型可用性检查 ### 待实现功能 ⏳ #### 1. 聊天功能增强 - ✅ 聊天记录持久化到数据库（Redis + 数据库双重存储） - ✅ 聊天记录导出（Excel格式） - ✅ 聊天记录搜索（支持多条件查询） - ✅ 聊天记录批量删除 - ✅ 聊天记录归档（删除指定日期之前的记录） - [ ] 多轮对话上下文优化 #### 2. Provider管理增强 - ✅ Provider配置可视化界面（管理端） - ✅ Provider配置导入导出（Excel导出） - ✅ Provider配置版本管理增强（配置历史记录、查询、导出） - [ ] Provider性能分析报告 - [ ] Provider成本分析 - [ ] Provider自动故障恢复 #### 3. 监控与统计增强 - ✅ 使用统计报表导出（Excel格式） - [ ] 使用趋势分析（图表） - [ ] 成本分析报表 - [ ] 性能分析报表 - [ ] 异常告警（邮件、短信、Webhook等） - [ ] 实时大屏展示 #### 4. 安全功能增强 - ✅ 敏感词库管理（可配置）：数据库存储、CRUD管理、启用/禁用、导出功能 - ✅ 用户配额管理：数据库存储、CRUD管理、配额重置、使用量统计 - [ ] 内容审核规则配置 - [ ] 企业级权限控制 - [ ] 审计日志 #### 5. 多模态功能完善 - [ ] OCR识别完整实现（集成OCR服务） - [ ] 图像识别完整实现 - [ ] 图生文完整实现 - [ ] 视频理解（占位） - [ ] 音频处理（占位） #### 6. 绘画功能增强 - ✅ 绘画历史管理：数据库存储、CRUD管理、查询、导出功能 - ✅ 绘画参数模板：数据库存储、CRUD管理、公开/私有模板、用户模板管理 - ✅ 绘画作品收藏：数据库存储、CRUD管理、收藏/取消收藏、收藏列表查询 - ✅ 绘画作品分享：分享码生成、取消分享、通过分享码查看作品（无需登录） - [ ] 批量绘画任务 #### 7. PPT功能增强 - [ ] PPT主题模板管理 - [ ] PPT样式自定义 - [ ] PPT动画支持 - [ ] PPT导出PDF - [ ] PPT在线预览 #### 8. MCP工具生态扩展 - [ ] 工具市场/插件系统 - [ ] 工具版本管理 - [ ] 工具权限控制 - [ ] 工具性能监控 - [ ] 自定义工具开发框架 #### 9. 代码助手增强 - [ ] 代码生成（根据需求生成代码） - [ ] 代码优化建议 - [ ] 代码测试用例生成 - [ ] 代码文档生成 - [ ] 代码安全扫描集成 #### 10. RAG功能增强 - [ ] 多知识库联合检索 - [ ] 检索结果排序优化 - [ ] 检索结果来源标注 - [ ] RAG效果评估 - [ ] 知识库更新通知 #### 11. 平台集成扩展 - [ ] 更多平台集成（如：LangChain、LlamaIndex等） - [ ] 平台配置管理界面 - [ ] 平台使用统计 #### 12. 其他功能 - [ ] 用户评价反馈系统完善 - [ ] 客服机器人集成 - [ ] 多语言支持 - [ ] API限流策略细化 - [ ] 任务队列持久化（当前仅内存） - [ ] 分布式任务调度 ## API接口详细说明 ### 管理端接口 #### 1. AI聊天记录管理 (`/ai/chat/record`) - `GET /ai/chat/record/list` - 查询AI聊天记录列表（分页、多条件搜索） - `GET /ai/chat/record/{id}` - 获取AI聊天记录详情 - `DELETE /ai/chat/record/{ids}` - 批量删除AI聊天记录 - `POST /ai/chat/record/export` - 导出AI聊天记录到Excel - `POST /ai/chat/record/archive` - 归档聊天记录（删除指定日期之前的记录） #### 2. AI使用统计管理 (`/ai/usage/stats`) - `GET /ai/usage/stats/list` - 查询AI使用统计列表（分页、多条件搜索） - `GET /ai/usage/stats/{id}` - 获取AI使用统计详情 - `POST /ai/usage/stats/export` - 导出AI使用统计到Excel - `GET /ai/usage/stats/summary` - 获取汇总统计 - `GET /ai/usage/stats/user/{userId}` - 获取用户统计 - `GET /ai/usage/stats/provider/{providerName}` - 获取Provider统计 - `GET /ai/usage/stats/trend` - 获取趋势数据 #### 3. 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` - 重置统计 #### 3.1. Provider配置管理 (`/ai/provider/config`) - `GET /ai/provider/config/list` - 查询Provider配置列表（分页、多条件搜索） - `GET /ai/provider/config/{id}` - 获取Provider配置详情 - `POST /ai/provider/config` - 新增Provider配置 - `PUT /ai/provider/config` - 修改Provider配置 - `DELETE /ai/provider/config/{ids}` - 批量删除Provider配置 - `POST /ai/provider/config/export` - 导出Provider配置到Excel - `PUT /ai/provider/config/changeEnabled` - 启用/禁用Provider配置 - `GET /ai/provider/config/name/{providerName}` - 根据Provider名称查询配置 #### 3.2. Provider配置历史管理 (`/ai/provider/config/history`) - `GET /ai/provider/config/history/list` - 查询Provider配置历史列表（分页、多条件搜索） - `GET /ai/provider/config/history/{id}` - 获取Provider配置历史详情 - `GET /ai/provider/config/history/config/{configId}` - 根据配置ID查询历史记录列表 - `DELETE /ai/provider/config/history/{ids}` - 批量删除Provider配置历史 - `POST /ai/provider/config/history/export` - 导出Provider配置历史到Excel #### 4. 系统模型管理 (`/system/model`) - `GET /system/model/modelList` - 获取模型列表（用于前端下拉选择） - `GET /system/model/list` - 根据分类获取模型列表 #### 5. AI评价记录管理 (`/ai/rating/record`) - `GET /ai/rating/record/list` - 查询AI评价记录列表（分页、多条件搜索） - `GET /ai/rating/record/{id}` - 获取AI评价记录详情 - `DELETE /ai/rating/record/{ids}` - 批量删除AI评价记录 - `POST /ai/rating/record/export` - 导出AI评价记录到Excel - `GET /ai/rating/record/average/{providerName}` - 获取指定Provider的平均评分 #### 6. AI敏感词管理 (`/ai/sensitive/word`) - `GET /ai/sensitive/word/list` - 查询AI敏感词列表（分页、多条件搜索） - `GET /ai/sensitive/word/{id}` - 获取AI敏感词详情 - `POST /ai/sensitive/word` - 新增AI敏感词 - `PUT /ai/sensitive/word` - 修改AI敏感词 - `DELETE /ai/sensitive/word/{ids}` - 批量删除AI敏感词 - `POST /ai/sensitive/word/export` - 导出AI敏感词到Excel - `PUT /ai/sensitive/word/changeEnabled` - 启用/禁用敏感词 #### 7. AI绘画历史记录管理 (`/ai/painting/record`) - `GET /ai/painting/record/list` - 查询AI绘画历史记录列表（分页、多条件搜索） - `GET /ai/painting/record/{id}` - 获取AI绘画历史记录详情 - `GET /ai/painting/record/task/{taskId}` - 根据任务ID获取记录 - `DELETE /ai/painting/record/{ids}` - 批量删除AI绘画历史记录 - `POST /ai/painting/record/export` - 导出AI绘画历史记录到Excel - `POST /ai/painting/record/{id}/share` - 生成分享码 - `DELETE /ai/painting/record/{id}/share` - 取消分享 #### 8. AI绘画参数模板管理 (`/ai/painting/template`) - `GET /ai/painting/template/list` - 查询AI绘画参数模板列表（分页、多条件搜索） - `GET /ai/painting/template/{id}` - 获取AI绘画参数模板详情 - `POST /ai/painting/template` - 新增AI绘画参数模板 - `PUT /ai/painting/template` - 修改AI绘画参数模板 - `DELETE /ai/painting/template/{ids}` - 批量删除AI绘画参数模板 - `POST /ai/painting/template/export` - 导出AI绘画参数模板到Excel #### 9. AI绘画作品收藏管理 (`/ai/painting/favorite`) - `GET /ai/painting/favorite/list` - 查询AI绘画作品收藏列表（分页、多条件搜索） - `GET /ai/painting/favorite/{id}` - 获取AI绘画作品收藏详情 - `DELETE /ai/painting/favorite/{ids}` - 批量删除AI绘画作品收藏 - `POST /ai/painting/favorite/export` - 导出AI绘画作品收藏到Excel #### 10. AI用户配额管理 (`/ai/user/quota`) - `GET /ai/user/quota/list` - 查询AI用户配额列表（分页、多条件搜索） - `GET /ai/user/quota/{id}` - 获取AI用户配额详情 - `GET /ai/user/quota/user/{userId}` - 根据用户ID获取配额信息 - `POST /ai/user/quota` - 新增AI用户配额 - `PUT /ai/user/quota` - 修改AI用户配额 - `DELETE /ai/user/quota/{ids}` - 批量删除AI用户配额 - `POST /ai/user/quota/reset/{userId}` - 重置用户配额（按日/按月） - `POST /ai/user/quota/export` - 导出AI用户配额到Excel ### 用户端接口 #### 1. 聊天接口 (`/ai/chat`) #### 同步聊天 - `POST /ai/chat/sync` - 同步聊天（返回完整响应） - 请求体：`AiChatRequest`（包含model、messages、sessionId等） - 响应：`AiChatResponse`（包含content、tokensUsed、cost等） #### 异步聊天 - `POST /ai/chat/async` - 异步聊天（返回任务ID） - 请求体：`AiChatRequest` - 响应：`CompletableFuture` #### 流式聊天 - `POST /ai/chat/stream` - SSE流式聊天 - 请求体：`AiChatRequest`（stream=true） - 响应：SSE流（事件类型：chunk、done、error） - `POST /ai/chat/stream-chunks` - 流式聊天（分块返回） - 请求体：`AiChatRequest` - 响应：分块响应列表 #### 批量聊天 - `POST /ai/chat/batch` - 批量聊天请求 - 请求体：批量`AiChatRequest`列表 - 响应：批量`AiChatResponse`列表 #### 聊天历史 - `GET /ai/chat/history/{sessionId}` - 获取聊天历史 - 路径参数：`sessionId`（会话ID） - 查询参数：`limit`（限制数量，可选） - 响应：聊天记录列表 - `DELETE /ai/chat/history/{sessionId}` - 清除聊天历史 - 路径参数：`sessionId`（会话ID） #### 会话统计 - `GET /ai/chat/stats/{sessionId}` - 获取会话统计 - 路径参数：`sessionId`（会话ID） - 响应：会话统计数据（消息数、Token数、成本等） #### 2. AI代码助手接口 (`/ai/assistant`) - `POST /ai/assistant/analyze` - 代码分析 - 请求参数：`code`（代码内容）、`model`（模型名称，可选） - 响应：代码分析结果（审查建议、重构建议等） - `POST /ai/assistant/scaffold` - 生成项目脚手架 - 请求参数：`appType`（应用类型）、`options`（选项JSON） - 响应：项目结构（文件列表、内容等） #### 3. Simple AI接口 (`/ai`) - `POST /ai/ask` - 知识库问答 - 查询参数：`knowledgeId`（知识库ID）、`question`（问题） - 响应：问答结果 - `POST /ai/search` - 向量搜索 - 查询参数：`knowledgeId`（知识库ID）、`queryText`（查询文本）、`topK`（返回数量，可选） - 响应：搜索结果列表 - `GET /ai/stats/{knowledgeId}` - 知识库统计 - 路径参数：`knowledgeId`（知识库ID） - 响应：知识库统计数据 - `GET /ai/model/check/{modelName}` - 检查模型可用性 - 路径参数：`modelName`（模型名称） - 响应：模型可用性状态 - `GET /ai/models` - 获取可用模型列表 - 响应：可用模型列表 - `GET /ai/health` - 健康检查 - 响应：健康状态 #### 4. 绘画接口 (`/ai/painting`) - `POST /ai/painting/task` - 创建绘画任务 - 请求体：`{"engine": "DALL_E_3", "prompt": "描述", "params": {...}}` - 响应：`{"taskId": "..."}` - `GET /ai/painting/status/{taskId}` - 查询任务状态 - 路径参数：`taskId`（任务ID） - 响应：任务状态（pending、processing、completed、failed） - `GET /ai/painting/stream/{taskId}` - SSE流式获取任务进度 - 路径参数：`taskId`（任务ID） - 响应：SSE流（任务状态更新） #### 5. AI绘画参数模板 (`/ai/painting/template`) - `GET /ai/painting/template/list/{engineType}` - 查询可用的模板列表（公开模板 + 用户私有模板） - `GET /ai/painting/template/{id}` - 获取模板详情 - `POST /ai/painting/template` - 新增用户私有模板 - `PUT /ai/painting/template` - 修改用户私有模板 - `DELETE /ai/painting/template/{id}` - 删除用户私有模板 #### 6. AI绘画作品收藏 (`/ai/painting/favorite`) - `GET /ai/painting/favorite/list` - 查询当前用户的收藏列表 - `POST /ai/painting/favorite` - 收藏绘画作品 - `DELETE /ai/painting/favorite/{paintingRecordId}` - 取消收藏 - `GET /ai/painting/favorite/check/{paintingRecordId}` - 检查是否已收藏 #### 6.1. AI绘画作品分享 (`/app/ai/painting/record`) - `POST /app/ai/painting/record/{id}/share` - 生成分享码 - `DELETE /app/ai/painting/record/{id}/share` - 取消分享 - `GET /app/ai/painting/record/share/{shareCode}` - 根据分享码查看作品（无需登录） #### 7. DALL·E-3接口 (`/dall3`) - `POST /dall3` - 文生图 - 请求体：`{"prompt": "描述", "size": "1024x1024"}` - 响应：图片URL或Base64 - `POST /dall3/edit` - 图片编辑（image+mask） - 请求体：`{"prompt": "描述", "image": "base64", "mask": "base64", "size": "1024x1024"}` - 响应：编辑后的图片URL或Base64 - `POST /dall3/variations` - 图片变体 - 请求体：`{"image": "base64", "size": "1024x1024"}` - 响应：变体图片URL或Base64 #### 8. 智能PPT接口 (`/ppt`) - `POST /ppt/generate` - 生成PPTX文件 - 查询参数：`content`（内容，按行分隔，空行分隔不同页） - 响应：PPTX文件（下载） - `POST /ppt/export/pngs` - 导出PNG序列 - 查询参数：`content`（内容） - 响应：PNG图片Base64列表 #### 9. 多模态接口 (`/multimodal`) - `POST /multimodal/extract` - 文件解析（PDF/Word等） - 请求：`multipart/form-data`，字段：`file` - 响应：解析后的文本内容 - `POST /multimodal/ocr` - OCR识别 - 请求：`multipart/form-data`，字段：`file` - 响应：OCR识别结果（需配置OCR服务） - `POST /multimodal/analyze/text` - 文本分析 - 请求体：`{"text": "文本内容"}` - 响应：分析结果（title、summary、keywords等） - `POST /multimodal/analyze/image` - 图像识别（占位） - 请求：`multipart/form-data`，字段：`file` - 响应：识别结果（占位接口） - `POST /multimodal/caption` - 图生文（占位） - 请求：`multipart/form-data`，字段：`file` - 响应：图片描述（占位接口） #### 10. 平台集成接口 ##### FastGPT (`/ai/fastgpt`) - `POST /ai/fastgpt/knowledge/search` - 知识搜索 - 请求体：`{"query": "查询内容"}` - 响应：搜索结果 - `POST /ai/fastgpt/workflow/run` - 运行工作流 - 请求体：`{"workflowId": "...", "inputs": {...}}` - 响应：工作流执行结果 - `GET /ai/fastgpt/context/{sessionId}` - 获取上下文 - 路径参数：`sessionId`（会话ID） - 响应：上下文信息 ##### Coze (`/ai/coze`) - `POST /ai/coze/stream` - SSE流式对话 - 请求体：`{"botId": "...", "message": "消息内容"}` - 响应：SSE流 ##### DIFY (`/ai/dify`) - `GET /ai/dify/apps` - 获取应用列表 - 响应：应用列表 - `POST /ai/dify/apps` - 创建/更新应用 - 请求体：应用配置 - 响应：应用信息 #### 11. MCP工具接口 (`/ai/mcp`) - `GET /ai/mcp/tools` - 获取工具列表 - 响应：可用工具列表 - `POST /ai/mcp/invoke/{name}` - 调用工具 - 路径参数：`name`（工具名称） - 请求体：工具参数（JSON） - 响应：工具执行结果 #### 12. 队列指标接口 (`/ai/queue`) - `GET /ai/queue/metrics` - 获取队列指标 - 响应：队列指标（队列深度、处理速率等） #### 13. AI评价接口 (`/ai/rating`) - `POST /ai/rating/submit` - 提交评价（用户对AI回复进行评价） - 请求体：`AiRatingRecordBo`（包含messageId、rating、feedback等） - `GET /ai/rating/{messageId}` - 查询评价记录（根据消息ID查询当前用户的评价记录） #### 13. AI用户配额 (`/ai/user/quota`) - `GET /ai/user/quota` - 查询当前用户的配额信息 ## WebSocket实时通道 ### 聊天WebSocket - **端点**: `ws://localhost:8080/ws/ai/chat` - **协议**: JSON格式，支持实时双向对话 - **消息格式**: `AiChatRequest`（JSON） - **响应格式**: `AiChatResponse`（JSON） ## 模块依赖关系 ``` ruoyi-ai (AI模块) ├── 依赖: ruoyi-common-core (通用核心工具) ├── 依赖: ruoyi-common-web (Web通用组件) ├── 依赖: ruoyi-common-redis (Redis缓存) ├── 依赖: ruoyi-common-security (安全组件) ├── 依赖: ruoyi-common-log (日志组件) ├── 依赖: ruoyi-common-mybatis (MyBatis组件) ├── 依赖: ruoyi-common-doc (文档组件) ├── 依赖: ruoyi-knowledge (知识库模块，RAG增强) └── 外部依赖: ├── okhttp (HTTP客户端) ├── okhttp-sse (SSE支持) ├── jackson (JSON解析) ├── spring-boot-starter-websocket (WebSocket支持) ├── poi-ooxml (PPT生成) └── tika-core (文件解析) ``` ## 技术栈与开发规范 ### 技术栈 - **框架**: Spring Boot 3.x - **ORM**: MyBatis-Plus（部分功能） - **数据库**: MySQL 8.0+ - **缓存**: Redis - **认证**: Sa-Token（通过ruoyi-common-security） - **API文档**: Swagger/OpenAPI 3.0 - **构建工具**: Maven - **HTTP客户端**: OkHttp - **JSON解析**: Jackson - **WebSocket**: Spring WebSocket ### 开发规范 #### 包结构规范 - `config` - 配置类（自动配置类、属性配置类） - `controller` - 控制器层（REST API） - `controller/admin` - 管理端接口（需要权限控制） - `controller/app` - 用户端接口 - `domain` - 数据传输对象（包含 `dto` 和 `enums` 子包） - `provider` - Provider实现（模型提供商实现） - `service` - 服务接口和实现 - `orchestration` - 编排引擎 - `painting` - 绘画相关（任务模型、Provider等） - `platform` - 外部平台集成 - `mcp` - MCP工具链 - `queue` - 任务队列 - `security` - 安全管理 - `monitor` - 监控指标 - `websocket` - WebSocket处理器 - `error` - 异常处理 #### 代码规范 - 统一使用 Lombok 简化代码 - 统一异常处理，使用 `ServiceException` 抛出业务异常 - 统一返回格式，使用 `R` 封装返回结果 - 统一日志记录，使用 `@Log` 注解记录操作日志 - 统一权限控制，管理端接口使用 `@SaCheckPermission` 注解 - Provider实现需继承 `AbstractAiProvider` 或实现 `AiProvider` 接口 - 配置类使用 `@ConfigurationProperties` 绑定配置属性 #### 数据库设计规范 - 表名使用 `ai_` 前缀 - 字段命名使用下划线命名法（snake_case） - 必须包含 `create_by`, `create_time`, `update_by`, `update_time` 字段 - 删除标记使用逻辑删除（`deleted` 字段，如需要） - 状态字段统一使用 `status` 或 `enabled`，0表示禁用/异常，1表示启用/正常 - JSON字段使用 `json` 类型存储配置信息 #### API设计规范 - RESTful 风格设计 - 接口路径： - 管理端接口：`/ai/{module}/{resource}` 或 `/system/{resource}` - 用户端接口：`/ai/{module}/{resource}` - 使用 HTTP 标准方法：GET（查询）、POST（新增/操作）、PUT（修改）、DELETE（删除） - 统一使用 JSON 格式进行数据交互 - 使用 Swagger 注解完善接口文档 - 管理端接口使用 `@SaCheckPermission` 进行权限控制 - 流式接口使用 SSE（Server-Sent Events）或 WebSocket ## 模块集成说明 ### 知识库模块集成 (ruoyi-knowledge) - **集成方式**: Maven依赖 - **核心功能**: - RAG增强（知识库问答） - 向量检索 - 知识库管理 - **配置要求**: 在 `application.yml` 中配置知识库相关配置 ### Redis集成 - **用途**: - 聊天历史存储 - 任务状态缓存 - 会话管理 - 缓存热点数据 - **配置要求**: 在 `application.yml` 中配置Redis连接信息 ### 外部服务集成 - **OpenAI**: 通过API Key访问 - **Azure OpenAI**: 通过Endpoint和API Key访问 - **通义千问**: 通过API Key访问 - **智谱AI**: 通过API Key访问 - **FastGPT/Coze/DIFY**: 通过平台API访问 - **OCR服务**: 需配置OCR服务地址（可选） ## 开发指南 ### 新增Provider开发步骤 1. **创建Provider配置类** - 在 `config` 包下创建配置类（如 `XxxProviderConfig.java`） - 使用 `@ConfigurationProperties` 绑定配置 2. **实现Provider接口** - 实现 `AiProvider` 接口或继承 `AbstractAiProvider` - 实现核心方法：`chat()`、`chatStream()`等 3. **注册Provider** - 在 `AiProviderRegistrar` 中注册Provider - 在 `AiProviderType` 枚举中添加新的Provider类型 4. **配置数据库** - 在 `ai_provider_config` 表中添加Provider配置记录 - 配置API密钥等信息 5. **测试验证** - 编写单元测试 - 使用Swagger UI测试接口 - 验证Provider功能 ### 新增MCP工具开发步骤 1. **实现工具接口** - 实现 `McpTool` 接口 - 实现 `execute()` 方法 2. **注册工具** - 在 `McpToolRegistry` 中注册工具（可通过Spring Bean自动注册） - 工具会自动出现在工具列表中 3. **测试验证** - 使用 `/ai/mcp/tools` 接口查看工具列表 - 使用 `/ai/mcp/invoke/{name}` 接口测试工具调用 ### 新增功能开发步骤 1. **数据库设计**（如需要） - 在 `script/sql/ry_ai.sql` 中设计表结构 - 确保字段命名规范，包含必要的索引 2. **创建DTO/实体类**（如需要） - 在 `domain/dto` 包下创建DTO类 - 创建对应的请求/响应对象 3. **创建Service** - 在 `service` 包下创建Service接口 - 在 `service/impl` 包下创建Service实现类（如需要） 4. **创建Controller** - 管理端接口：在 `controller/admin` 包下创建Controller - 用户端接口：在 `controller/app` 包下创建Controller - 添加Swagger注解完善接口文档 - 管理端接口添加权限控制注解（`@SaCheckPermission`） 5. **测试验证** - 编写单元测试（可选） - 使用Swagger UI测试接口 - 验证业务逻辑正确性 ## 后续功能完善计划 ### 短期计划（1-2个月） 1. **聊天功能增强** ✅（大部分已完成） - ✅ 聊天记录持久化到数据库 - ✅ 聊天记录导出功能（Excel） - ✅ 聊天记录搜索功能 - ✅ 聊天记录批量删除功能 2. **监控与统计增强** - 使用统计报表导出 - 使用趋势分析图表 - 异常告警功能 3. **多模态功能完善** - OCR识别完整实现 - 图像识别完整实现 - 图生文完整实现 4. **安全功能增强** - 敏感词库管理 - 用户配额管理 - 审计日志 ### 中期计划（3-6个月） 1. **Provider管理增强** - Provider配置可视化界面 - Provider性能分析报告 - Provider成本分析 2. **绘画功能增强** - 绘画历史管理 - 绘画作品收藏 - 批量绘画任务 3. **PPT功能增强** - PPT主题模板管理 - PPT样式自定义 - PPT导出PDF 4. **代码助手增强** - 代码生成功能 - 代码优化建议 - 代码测试用例生成 5. **RAG功能增强** - 多知识库联合检索 - 检索结果排序优化 - RAG效果评估 ### 长期计划（6个月以上） 1. **MCP工具生态扩展** - 工具市场/插件系统 - 工具版本管理 - 自定义工具开发框架 2. **平台集成扩展** - 更多平台集成 - 平台配置管理界面 3. **系统优化** - 分布式任务调度 - 任务队列持久化 - 性能优化与扩展 4. **企业级功能** - 多租户支持 - 企业级权限控制 - 数据隔离 ## 注意事项 1. **密钥安全**：生产环境务必通过环境变量注入 API Key，不要将密钥写入配置文件或代码中 2. **流式代理**：Nginx/Gateway 需配置 `proxy_buffering off` 以支持 SSE 3. **依赖服务**：Redis 必须可用，用于存储任务状态与缓存 4. **性能优化**：建议对热点数据使用Redis缓存 5. **错误处理**：模块提供自动降级和熔断机制，但建议监控错误率 6. **并发控制**：Provider支持最大并发数配置，合理设置以避免资源耗尽 7. **成本控制**：建议设置使用配额和成本预警，避免意外高额费用 8. **内容安全**：启用内容过滤和安全检查，防止不当内容生成 9. **数据隐私**：注意用户数据隐私保护，敏感信息加密存储 10. **API限流**：合理配置API限流策略，防止API滥用 11. **监控告警**：建议配置监控告警，及时发现和解决问题 12. **版本兼容**：升级Provider SDK时注意API兼容性 13. **文档更新**：新增功能时及时更新API文档和README 14. **测试覆盖**：关键功能建议编写单元测试和集成测试 15. **日志规范**：关键操作记录日志，便于问题排查