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

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

快速开始

1. 数据库初始化

执行SQL脚本创建表结构：

-- 执行 ruoyi-modules/ruoyi-ai/docs/ai_image.sql

2. 配置OSS存储

在application.yml中配置OSS存储：

# 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

# 拉取镜像
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

模型下载

# 下载常用模型（放置在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：

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

使用示例

1. 基础文生图

// 创建生成请求
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. 高级参数设置

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. 局部编辑

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. 查询生成记录

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. 生成图片测试

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. 编辑图片测试

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. 查询记录测试

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. 日志配置

logging:
  level:
    org.dromara.ai: DEBUG  # 开启详细日志

3. 性能监控

• 使用Spring Boot Actuator
• 配置Prometheus + Grafana
• 设置告警规则

扩展开发

1. 添加新的生成器

@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. 添加限流策略

@Component
public class CustomRateLimiter {
    // 实现自定义限流逻辑
}

3. 添加缓存策略

@Component
public class CustomCacheManager {
    // 实现自定义缓存逻辑
}