RuoYi-Vue-Plus/ruoyi-modules/ruoyi-ai/docs/USAGE.md

# AI图片生成模块 - 使用说明

## 快速开始

### 1. 数据库初始化

执行SQL脚本创建表结构：
```sql
-- 执行 ruoyi-modules/ruoyi-ai/docs/ai_image.sql
```

### 2. 配置OSS存储

在application.yml中配置OSS存储：
```yaml
# OSS配置（已有配置，确保正确）
oss:
  endpoint: https://oss-cn-region.aliyuncs.com
  accessKey: your-access-key
  secretKey: your-secret-key
  bucketName: your-bucket

# AI图片生成配置
ai:
  image:
    default-mode: LOCAL  # 默认使用本地模型
    storage:
      bucket-name: ai-images  # 存储桶名称
      path-prefix: ai/image/  # 存储路径前缀
      generate-thumbnail: true  # 生成缩略图
```

### 3. 本地模型部署（可选）

#### Docker部署Stable Diffusion
```bash
# 拉取镜像
docker pull automatic1111/stable-diffusion-webui:latest

# 运行容器
docker run -d --name stable-diffusion \
  -p 7860:7860 \
  -v /path/to/models:/app/models \
  --gpus all \
  automatic1111/stable-diffusion-webui:latest \
  --api --listen --port 7860

# 验证服务
curl http://localhost:7860/sdapi/v1/memory
```

#### 模型下载
```bash
# 下载常用模型（放置在models/Stable-diffusion目录）
# Stable Diffusion v1.5
wget https://huggingface.co/runwayml/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.ckpt

# 中文优化模型
wget https://huggingface.co/IDEA-CCNL/Taiyi-Stable-Diffusion-1B-Chinese-v0.1/resolve/main/Taiyi-Stable-Diffusion-1B-Chinese-v0.1.ckpt
```

### 4. 云服务配置（可选）

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

```yaml
ai:
  image:
    cloud-service:
      provider: ALIYUN
      api-key: your-dashscope-api-key
      region: cn-shanghai
```

## 使用示例

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

// 调用生成接口
AiImageVO result = aiImageService.generateImage(dto);

// 获取生成的图片URL
String imageUrl = result.getImageUrl();
```

### 2. 高级参数设置
```java
AiImageGenerateDTO dto = new AiImageGenerateDTO();
dto.setPrompt("一只可爱的猫咪在草地上玩耍，阳光温暖，卡通风格");
dto.setNegativePrompt("模糊,低质量,变形,扭曲");
dto.setWidth(1024);
dto.setHeight(1024);
dto.setSteps(30); // 生成步数，质量更高但速度更慢
dto.setCfgScale(8.0); // CFG值，提示词引导强度
dto.setSampler("DPM++ 2M Karras"); // 采样器
dto.setSeed(12345L); // 固定种子可复现相同图片
dto.setGenerateMode("LOCAL");
```

### 3. 局部编辑
```java
AiImageEditDTO dto = new AiImageEditDTO();
dto.setOriginalImageUrl("https://your-oss.com/cat.jpg");
dto.setEditPrompt("将猫咪的眼睛变成蓝色，更加明亮");

// 指定编辑区域（可选）
dto.setX(150); // 左上角X坐标
dto.setY(120); // 左上角Y坐标
dto.setWidth(80); // 编辑区域宽度
dto.setHeight(60); // 编辑区域高度

// 或使用蒙版图片（可选）
dto.setMaskImageUrl("https://your-oss.com/mask.png");

dto.setEditMode("LOCAL");

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

### 4. 查询生成记录
```java
AiImagePageQueryDTO queryDTO = new AiImagePageQueryDTO();
queryDTO.setPageNum(1);
queryDTO.setPageSize(10);
queryDTO.setStatus("SUCCESS"); // 只查询成功的记录
queryDTO.setPromptKeyword("猫咪"); // 按描述关键词搜索

TableDataInfo<AiImageVO> pageResult = aiImageService.getImagePage(queryDTO);
List<AiImageVO> records = pageResult.getRows();
long total = pageResult.getTotal();
```

## API接口测试

### 1. 生成图片测试
```bash
curl -X POST http://localhost:8080/ai/image/generate \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "一只可爱的猫咪在草地上玩耍",
    "width": 750,
    "height": 1440,
    "negativePrompt": "模糊,低质量",
    "steps": 20,
    "cfgScale": 7.5,
    "generateMode": "LOCAL"
  }'
```

### 2. 编辑图片测试
```bash
curl -X POST http://localhost:8080/ai/image/edit \
  -H "Content-Type: application/json" \
  -d '{
    "originalImageUrl": "https://your-oss.com/cat.jpg",
    "editPrompt": "将猫咪的眼睛变成蓝色",
    "x": 150,
    "y": 120,
    "width": 80,
    "height": 60,
    "editMode": "LOCAL"
  }'
```

### 3. 查询记录测试
```bash
curl "http://localhost:8080/ai/image/page?pageNum=1&pageSize=10&status=SUCCESS"
```

## 性能优化建议

### 1. 本地模型优化
- 使用GPU加速（NVIDIA显卡，至少8GB显存）
- 选择合适的模型（平衡质量和速度）
- 调整并发参数（根据硬件配置）

### 2. 云服务优化
- 开启CDN加速
- 合理设置缓存策略
- 监控API调用量和费用

### 3. 系统优化
- 调整数据库连接池大小
- 配置Redis缓存
- 设置合理的超时时间
- 监控生成任务队列

## 常见问题

### 1. 本地模型连接失败
- 检查Stable Diffusion服务是否启动
- 确认API地址和端口正确
- 验证网络连通性
- 查看服务日志

### 2. 生成图片质量不佳
- 调整steps参数（20-50）
- 优化prompt描述
- 使用负面提示词
- 尝试不同采样器

### 3. 生成速度过慢
- 使用GPU加速
- 减少图片尺寸
- 降低steps参数
- 使用云服务模式

### 4. OSS上传失败
- 检查OSS配置
- 验证权限设置
- 查看网络连接
- 检查存储空间

## 监控和日志

### 1. 关键指标监控
- 生成成功率
- 平均生成时间
- 并发请求数
- 错误率统计

### 2. 日志配置
```yaml
logging:
  level:
    org.dromara.ai: DEBUG  # 开启详细日志
```

### 3. 性能监控
- 使用Spring Boot Actuator
- 配置Prometheus + Grafana
- 设置告警规则

## 扩展开发

### 1. 添加新的生成器
```java
@Component
public class CustomGenerator implements AiImageGenerator {
    @Override
    public AiImageVO generateImage(AiImageGenerateDTO dto) {
        // 实现生成逻辑
    }
    
    @Override
    public AiImageVO editImage(AiImageEditDTO dto) {
        // 实现编辑逻辑
    }
    
    @Override
    public String getType() {
        return "CUSTOM";
    }
    
    @Override
    public boolean isAvailable() {
        // 检查服务可用性
    }
}
```

### 2. 添加限流策略
```java
@Component
public class CustomRateLimiter {
    // 实现自定义限流逻辑
}
```

### 3. 添加缓存策略
```java
@Component
public class CustomCacheManager {
    // 实现自定义缓存逻辑
}
```