RuoYi-Vue-Plus/ruoyi-modules/ruoyi-ai/README.md

# AI图片生成模块

## 功能概述

AI图片生成模块提供了基于AI的图片生成和编辑功能，支持本地开源模型和云服务双模式切换。

## 核心功能

### 1. 文生图（Text-to-Image）
- 根据文字描述生成图片
- 支持自定义图片尺寸（如750×1440、200×200等）
- 支持负面描述（不希望在图片中出现的内容）
- 支持多种参数调节（步数、CFG值、采样器等）

### 2. 局部修改（Image-to-Image/Inpainting）
- 对已有图片进行局部编辑
- 支持蒙版编辑（指定编辑区域）
- 支持区域编辑（指定坐标和尺寸）
- 保持原图风格的一致性

### 3. 双模式支持
- **本地模式**：基于Stable Diffusion开源模型
- **云服务模式**：基于阿里云通义万相等云服务
- 支持模式切换和自动降级

## 技术架构

### 模块结构
```
ruoyi-ai/
├── ruoyi-ai-api/          # API接口定义
├── ruoyi-ai-service/      # 业务逻辑实现  
└── ruoyi-ai-starter/      # 自动配置启动器
```

### 核心组件

#### 1. 生成器接口（AiImageGenerator）
```java
public interface AiImageGenerator {
    AiImageVO generateImage(AiImageGenerateDTO dto);
    AiImageVO editImage(AiImageEditDTO dto);
    String getType();
    boolean isAvailable();
}
```

#### 2. 生成器工厂（AiImageGeneratorFactory）
- 管理所有生成器实例
- 根据模式选择合适的生成器
- 支持生成器自动降级

#### 3. 具体生成器实现
- **StableDiffusionGenerator**：本地Stable Diffusion模型
- **AliyunWanxiangGenerator**：阿里云通义万相云服务

### 性能优化

#### 1. 并发控制
- 本地模型：最大并发数3
- 云服务：最大并发数5
- 支持QPS=10的并发要求

#### 2. 缓存机制
- 相同描述直接返回缓存结果
- 缓存过期时间60分钟
- 最大缓存数量1000条

#### 3. 异步处理
- 大图片生成采用异步模式
- 支持超时控制（60秒）

#### 4. 图片存储
- 自动生成缩略图（200×200）
- OSS存储，支持CDN加速
- 图片格式自动识别和处理

## 配置说明

### 1. 基础配置
```yaml
ai:
  image:
    default-mode: LOCAL  # 默认模式：LOCAL/CLOUD
    local-model:
      sd-api-url: http://localhost:7860  # Stable Diffusion API地址
      default-model: stable-diffusion-v1-5  # 默认模型
      timeout: 60  # 超时时间（秒）
      max-concurrency: 3  # 最大并发数
    cloud-service:
      provider: ALIYUN  # 云服务提供商
      api-key: your-api-key  # API密钥
      secret-key: your-secret-key  # 密钥
      region: cn-shanghai  # 区域
      timeout: 60  # 超时时间（秒）
      max-concurrency: 5  # 最大并发数
```

### 2. 存储配置
```yaml
ai:
  image:
    storage:
      bucket-name: ai-images  # OSS存储桶名称
      path-prefix: ai/image/  # 存储路径前缀
      generate-thumbnail: true  # 是否生成缩略图
      thumbnail-width: 200  # 缩略图宽度
      thumbnail-height: 200  # 缩略图高度
```

### 3. 限流配置
```yaml
ai:
  image:
    rate-limit:
      enabled: true  # 是否启用限流
      max-requests-per-second: 10  # 每秒最大请求数
      max-requests-per-minute: 100  # 每分钟最大请求数
      max-requests-per-hour: 500  # 每小时最大请求数
```

### 4. 缓存配置
```yaml
ai:
  image:
    cache:
      enabled: true  # 是否启用缓存
      expire-minutes: 60  # 缓存过期时间（分钟）
      max-cache-size: 1000  # 最大缓存数量
```

## API接口

### 1. 生成图片
```http
POST /ai/image/generate
Content-Type: application/json

{
  "prompt": "一只可爱的猫咪在草地上玩耍",
  "width": 750,
  "height": 1440,
  "negativePrompt": "模糊,低质量",
  "steps": 20,
  "cfgScale": 7.5,
  "generateMode": "LOCAL"
}
```

### 2. 编辑图片
```http
POST /ai/image/edit
Content-Type: application/json

{
  "originalImageUrl": "https://oss.example.com/image.jpg",
  "editPrompt": "将猫咪的眼睛变成蓝色",
  "x": 100,
  "y": 100,
  "width": 200,
  "height": 200,
  "editMode": "LOCAL"
}
```

### 3. 查询记录
```http
GET /ai/image/page?pageNum=1&pageSize=10&status=SUCCESS
```

### 4. 删除记录
```http
DELETE /ai/image/{id}
```

## 使用示例

### 1. 基础文生图
```java
AiImageGenerateDTO dto = new AiImageGenerateDTO();
dto.setPrompt("一只可爱的猫咪在草地上玩耍");
dto.setWidth(750);
dto.setHeight(1440);
dto.setGenerateMode("LOCAL");

AiImageVO result = aiImageService.generateImage(dto);
```

### 2. 高级参数设置
```java
AiImageGenerateDTO dto = new AiImageGenerateDTO();
dto.setPrompt("一只可爱的猫咪在草地上玩耍");
dto.setNegativePrompt("模糊,低质量,变形");
dto.setWidth(1024);
dto.setHeight(1024);
dto.setSteps(30);
dto.setCfgScale(8.0);
dto.setSampler("DPM++ 2M Karras");
dto.setSeed(12345L);
dto.setGenerateMode("CLOUD");
```

### 3. 局部编辑
```java
AiImageEditDTO dto = new AiImageEditDTO();
dto.setOriginalImageUrl("https://oss.example.com/cat.jpg");
dto.setEditPrompt("将猫咪的眼睛变成蓝色");
dto.setX(150);
dto.setY(120);
dto.setWidth(80);
dto.setHeight(60);
dto.setEditMode("LOCAL");

AiImageVO result = aiImageService.editImage(dto);
```

## 部署说明

### 1. 本地Stable Diffusion部署
```bash
# 使用Docker部署
docker run -d --name stable-diffusion \
  -p 7860:7860 \
  -v /path/to/models:/app/models \
  --gpus all \
  stable-diffusion-webui:latest
```

### 2. 阿里云通义万相配置
1. 注册阿里云账号
2. 开通DashScope服务
3. 获取API密钥
4. 配置到application.yml

### 3. 数据库表结构
```sql
CREATE TABLE `ai_image` (
  `id` bigint NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `image_url` varchar(500) DEFAULT NULL COMMENT '图片URL',
  `thumbnail_url` varchar(500) DEFAULT NULL COMMENT '缩略图URL',
  `original_image_url` varchar(500) DEFAULT NULL COMMENT '原图片URL',
  `prompt` text COMMENT '生成描述',
  `negative_prompt` text COMMENT '负面描述',
  `width` int DEFAULT NULL COMMENT '图片宽度',
  `height` int DEFAULT NULL COMMENT '图片高度',
  `file_size` bigint DEFAULT NULL COMMENT '文件大小',
  `file_format` varchar(10) DEFAULT NULL COMMENT '文件格式',
  `generate_mode` varchar(20) DEFAULT NULL COMMENT '生成模式',
  `model_name` varchar(100) DEFAULT NULL COMMENT '模型名称',
  `generate_time` bigint DEFAULT NULL COMMENT '生成耗时',
  `status` varchar(20) DEFAULT NULL COMMENT '生成状态',
  `error_message` text COMMENT '错误信息',
  `generate_params` text COMMENT '生成参数',
  `create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
  `create_time` datetime DEFAULT NULL COMMENT '创建时间',
  `update_by` varchar(64) DEFAULT NULL COMMENT '更新人',
  `update_time` datetime DEFAULT NULL COMMENT '更新时间',
  `del_flag` char(1) DEFAULT '0' COMMENT '删除标志',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='AI图片生成记录';
```

## 性能指标

- **并发能力**：最大QPS=10
- **响应时间**：图片生成最慢不超过60秒
- **图片质量**：支持多种分辨率和格式
- **稳定性**：支持自动降级和故障转移
- **扩展性**：支持多种AI模型和云服务

## 注意事项

1. **资源消耗**：AI图片生成需要大量计算资源，建议部署在GPU服务器
2. **成本控制**：云服务按调用次数收费，注意设置限流和监控
3. **内容审核**：生成的图片需要符合相关法律法规
4. **版权保护**：注意生成图片的版权问题
5. **数据安全**：敏感图片需要加密存储和传输