shuolol/PoJie

Fork 0

Files

T

shuolol b236048a24 first commit

2026-02-22 12:12:02 +08:00

20 KiB

Raw Permalink Blame History

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 中添加以下配置：

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. 聊天与流式对话

# 同步聊天
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代码助手

# 代码分析
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)

# 知识库问答
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绘画任务

# 创建绘画任务
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生成

curl -X POST "http://localhost:8080/api/ai/ppt/generate?content=第一页标题\n内容1\n第二页标题\n内容2"

6. MCP工具调用

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、模型）
请求次数统计
成功率统计
成本统计

注意事项

密钥安全：生产环境务必通过环境变量注入 API Key，不要将密钥写入配置文件
流式代理：Nginx/Gateway 需配置 proxy_buffering off 以支持 SSE
依赖服务：Redis 必须可用，用于存储任务状态与缓存
性能优化：建议对热点数据使用Redis缓存
错误处理：模块提供自动降级和熔断机制，但建议监控错误率
并发控制：Provider支持最大并发数配置，合理设置以避免资源耗尽

扩展开发

添加新的Provider

实现 AiProvider 接口
创建对应的配置类（如 XxxProviderConfig.java）
在 AiProviderRegistrar 中注册Provider
在 AiProviderType 枚举中添加新的Provider类型

添加新的MCP工具

实现 McpTool 接口
在 AiProviderRegistrar 中注册工具
工具会自动出现在工具列表中

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

20 KiB Raw Permalink Blame History Unescape Escape