开发指南
AI大模型手册

AI 图片生成

AI 图片生成，基于 AI 大模型，实现使用文本（以及参考图）生成图片的功能。所有模型统一在一个创作工作台中使用，目前接入的是：

分类	平台	模型标识示例	调用方式
通用模型	通义千问（通义万相）	`wanx-v1`、`wanx2.1-t2i-turbo`	Spring AI Alibaba 的 DashScopeImageModel
通用模型	硅基流动	`Qwen/Qwen-Image`、`Kwai-Kolors/Kolors`	项目实现的 SiliconFlowImageModel
通用模型	OpenAI	`gpt-image-1`、`dall-e-3`	Spring AI 的 OpenAiImageModel
通用模型	StabilityAI	`stable-diffusion-v1-6`	Spring AI 的 StabilityAiImageModel
Seedream	字节豆包（火山方舟）	`doubao-seedream-5-0-flash-260915`	火山方舟官方 SDK 的 ArkService
Midjourney	Midjourney 中转	`midjourney`、`niji`	项目实现的 MidjourneyApi

AI 绘图

整个功能，涉及到 3 个表：

【配置】ai_api_key：API 密钥表
【配置】ai_model：模型表
【绘画】ai_image：绘画表

补充说明：

ai_api_key、ai_model 已经在《功能开启》讲解，就不重复赘述。

# 1. 前置准备

# 1.1 配置模型

你想使用哪个模型绘画，可以参考对应的文档，配置 API 密钥：

通义千问的万相模型：《【模型接入】通义千问》
硅基流动的图片模型：《【模型接入】硅基流动》
字节豆包的 Seedream 模型：《【模型接入】字节豆包》
OpenAI 的图片模型：《【模型接入】OpenAI》
StabilityAI 的 Stable Diffusion 模型：《【模型接入】Stable Diffusion》
Midjourney 的 Midjourney 模型：《【模型接入】Midjourney》

然后，在 [AI 大模型 -> 控制台 -> 模型配置] 菜单，新增一个模型：

所属平台：选择上述平台之一，并且与所选「API 秘钥」的平台一致，否则绘图时会提示平台不一致
模型类型：选择「图片」，对应 AiModelTypeEnum 的 IMAGE（type 为 2）
模型标识：填写平台的模型标识，例如说 wanx-v1、doubao-seedream-5-0-flash-260915

友情提示：

一般情况下，建议先使用《【模型接入】通义千问》模块，因为免费送了一些 tokens，可以先体验一下。

# 1.2 开启定时任务

① AiImageTimeoutJob 任务（JobHandler 名字为 aiImageTimeoutJob）：超过 10 分钟仍在「进行中」的绘画，置为「已失败」。例如说，服务重启中断了异步绘制、Midjourney 中转一直没有回调。未开启时，这类作品会一直停留在「进行中」。建议每 1 分钟执行一次，即 Cron 表达式 0 * * * * ?。

② AiMidjourneySyncJob 任务（JobHandler 名字为 aiMidjourneySyncJob）：只有使用 Midjourney 时需要，定时查询中转的任务进展，作为回调的补充。建议每 10 秒执行一次，即 Cron 表达式 0/10 * * * * ?。

具体怎么配置定时任务，可以参考《定时任务》文档。

# 2. AI 图片生成

前端对应 [AI 大模型 -> AI 图片生成] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/image/index 目录，提供给普通用户使用。

左边是创作面板：先选择模型，再填写对应的创作表单；右边是【我的作品】【公开画廊】。后端 HTTP 接口，由 yudao-module-ai 模块的 image 包的 AiImageController 实现。

模型下拉框按「通用模型」「Seedream」「Midjourney」分组，只展示已开启的图片模型。表单显示哪些参数、可选值和上限，由前端的 @/views/ai/image/constants/imageCapabilities.ts 能力常量决定：

按「平台:模型标识」精确匹配，例如说 ALIBABA:wanx2.1-t2i-turbo。新的模型要开放更多参数，在这里新增一项即可
未登记的模型标识，按平台的保守能力处理：只开放 1024x1024 文生图，下拉框中标注「未登记 · 仅文生图」。未登记的豆包模型不可选

# 2.1 通用模型

选择通义、硅基流动、OpenAI、Stability 的模型时，使用通用的创作表单：

画面描述：最多 1200 字。可以点击【生成专业绘画指令】按钮，使用 [模型配置] 中排序最靠前、已开启的对话模型，把描述改写为专业的绘画提示词；也可以点击【随机热词】
尺寸：固定尺寸，或者像素宽高（部分模型支持自定义）
画质、参考图、不希望出现的内容、高级参数：只在模型支持时显示

通用模型

已登记的通用模型，能力如下：

模型	尺寸	其它参数
OpenAI `gpt-image-1`	1024x1024、1536x1024、1024x1536	画质：auto、high、medium、low
OpenAI `dall-e-3`	1024x1024、1792x1024、1024x1792	画质：standard、hd
通义 `wanx2.1-t2i-turbo`	1024x1024 等 4 种，可自定义 512 ~ 1440	-
硅基流动 `Kwai-Kolors/Kolors`	1024x1024 等 5 种	参考图 1 张、不希望出现的内容、随机种子、推理步数、引导系数
Stability `stable-diffusion-v1-6`	512x512、768x768、1024x1024，可自定义 320 ~ 1536	随机种子、推理步数、引导系数、采样方法、风格预设、CLIP 引导

另外，ALIBABA:wan2.7-image 也已登记，但当前 DashScope SDK 没有它的接口路由，下拉框中标注「不可用」，不可选择。

# 2.2 Seedream

选择豆包 Seedream 模型时，使用 Seedream 的创作表单：

画面描述：最多 1000 字（按版本不同），比例需要在描述中说明
尺寸档位：doubao-seedream-5-0-flash-260915 只开放 2K
固定参数与写法建议：展开后可以查看实际提交的固定参数，以及官方建议的提示词写法

Seedream

后端使用火山方舟官方 SDK 的 ArkService 调用，固定参数为：单图输出（不传 sequential_image_generation）、response_format 为 url、watermark 为 false、optimize_prompt_options.mode 为 standard。生成成功后，结果图片转存到项目的文件服务，并按实际的结果尺寸记录宽高。

# 2.3 Midjourney

选择 Midjourney 模型时，使用 Midjourney 的创作表单，支持五种模式：

模式	输入图片	后端接口
文生图	无	`/ai/image/midjourney/imagine`
图生图	参考图 1 ~ 5 张，可调图片权重 `--iw`	`/ai/image/midjourney/imagine`
融图	融图图片 2 ~ 5 张，可选竖图 2:3、方图 1:1、横图 3:2	`/ai/image/midjourney/blend`
换脸	来源脸 + 目标图，把来源脸换到目标图上	`/ai/image/midjourney/swap-face`
一致性	角色参考 `--cref`、风格参考 `--sref`，至少 1 张	`/ai/image/midjourney/imagine`

Midjourney 文生图

版本：Midjourney V8.2、V8.1、V7（默认）、V6.1，以及 Niji 7、Niji 6。不同版本可用的参数不同，例如说 --q、--raw、--hd、--cref 只在部分版本显示，不可用时会说明原因。Omni Reference、V8 Edit 暂未适配，置灰展示
比例：1:1、2:3、16:9 等 9 种
更多参数：风格化 --s、创意度 --c、随机种子 --seed、平铺 --tile、不希望出现的内容 --no 等
提交预览：展示最终提交给 Midjourney 的完整提示词，与后端 AiImageUtils 的 #buildMidjourneyPrompt(...) 拼接规则一致

其它四种模式的表单，如下图所示：

Midjourney 图生图

Midjourney 融图

Midjourney 换脸

Midjourney 一致性

Midjourney 中转的申请、配置及回调地址，见《【模型接入】Midjourney》。

# 2.4 我的作品

在【我的作品】中，以卡片的形式分页展示自己的作品。有作品在生成中时，每 3 秒自动刷新；提交新作品后，回到第 1 页。

卡片：左上角展示生成方式（或 Seedream）标签；生成中展示进度，失败展示失败原因
操作：【详情】【下载】【重新生成】（把参数回填到左侧表单），【更多】中可以公开、取消公开（只有已完成的作品可以公开）、删除

# 2.5 Midjourney 按钮与局部重绘

Midjourney 作品完成后，卡片上展示中转返回的按钮：U1 ~ U4（放大）、V1 ~ V4（变化）按四宫格位置排列，其它按钮收进【更多】下拉。点击后生成一条新的作品，parent_id 记录来源作品，并沿用来源作品的 API 密钥。换脸的结果没有 U、V 按钮；CustomZoom 暂不支持，不展示。

点击局部重绘（Inpaint）按钮，会打开「局部重绘」弹窗：使用画笔涂抹需要重绘的区域（支持橡皮擦、撤销、清空、调整笔刷大小），并描述重绘区域的内容。提交时，前端按原图尺寸生成黑底白色的蒙版，上传到文件服务后，调用 /ai/image/midjourney/modal 接口。

# 2.6 公开画廊

公开的作品，会展示在【公开画廊】中，同一租户的其它用户都可以查看、下载。只展示已完成的作品，不展示用户、API 密钥、任务编号、失败原因和蒙版等信息。

公开画廊

# 2.7 作品详情

点击作品的【详情】，可以查看作品的完整信息：

提示词：画面描述、不希望出现的内容，以及 Midjourney 的最终提示词
参数：模型、尺寸、各平台的绘制参数
输入图片：按参考图、融图、来源脸、目标图、角色参考、风格参考、蒙版等角色展示
来源与派生：Midjourney 按钮、局部重绘产生的作品，与来源作品互相关联

作品详情

# 3. 图片管理

前端对应 [AI 大模型 -> 控制台 -> 图片管理] 菜单，对应 yudao-ui-admin-vue3 项目的 @/views/ai/image/manager 目录，提供给管理员使用，查看所有用户的绘画记录：

筛选：用户、平台、生成方式、提示词、绘画状态、是否发布、创建时间
列表：图片、生成方式、平台、模型、状态、进度、来源（点击可查看来源作品）等
操作：查看详情（包含派生的作品）、修改是否发布（只有已完成的作品可以发布）、删除

图片管理

# 4. 绘画表

ai_image：绘画表，每次生成一条记录。Midjourney 按钮、局部重绘产生的作品，也各是一条记录。

省略 creator/create_time/updater/update_time/deleted/tenant_id 等通用字段

CREATE TABLE `ai_image` (
  `id`                 bigint        NOT NULL AUTO_INCREMENT COMMENT '编号',
  `user_id`            bigint        NOT NULL COMMENT '用户编号',
  `public_status`      bit(1)        NOT NULL DEFAULT b'0' COMMENT '是否发布',

  `platform`           varchar(64)   NOT NULL COMMENT '平台',
  `mode`               tinyint       NOT NULL DEFAULT 10 COMMENT '生成方式',
  `model_id`           bigint        NULL     COMMENT '模型编号',
  `model`              varchar(64)   NOT NULL COMMENT '模型',
  `api_key_id`         bigint        NULL     COMMENT 'API 密钥编号',

  `prompt`             varchar(2000) NOT NULL COMMENT '提示词',
  `negative_prompt`    varchar(2000) NULL     COMMENT '不希望出现的内容',
  `input_images`       text          NULL     COMMENT '输入图片',
  `width`              int           NOT NULL COMMENT '图片宽度',
  `height`             int           NOT NULL COMMENT '图片高度',
  `options`            json          NULL     COMMENT '绘制参数',
  `midjourney_options` text          NULL     COMMENT 'Midjourney 绘制参数',
  `seedream_options`   text          NULL     COMMENT 'Seedream 绘制参数',

  `status`             tinyint       NOT NULL COMMENT '绘画状态',
  `progress`           tinyint       NOT NULL DEFAULT 0 COMMENT '进度（0-100）',
  `pic_url`            varchar(2048) NULL     COMMENT '图片地址',
  `error_message`      varchar(1024) NULL     COMMENT '错误信息',
  `finish_time`        datetime      NULL     COMMENT '完成时间',

  `task_id`            varchar(1024) NULL     COMMENT '任务编号',
  `parent_id`          bigint        NULL     COMMENT '来源记录编号',

  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_user_id_id` (`user_id`, `id`),
  KEY `idx_public_status_mode` (`public_status`, `status`, `mode`, `id`),
  KEY `idx_status_platform` (`status`, `platform`),
  KEY `idx_task_id` (`task_id`(255)),
  KEY `idx_parent_id` (`parent_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI 绘画表';

① user_id 字段：对应 system_users 表的 id 字段，表示哪个用户的作品。

public_status 字段：是否发布（公开），默认为 false 不公开。只有已完成的作品可以公开，公开后展示在【公开画廊】中。

② platform 字段：平台，对应 AiPlatformEnum 枚举。

mode 字段：生成方式，对应 AiImageModeEnum 枚举、ai_image_mode 字典：

值	生成方式	说明
10	AI 生图	通用模型、Seedream
20	MJ 文生图
21	MJ 图生图
22	MJ 融图
23	MJ 换脸
24	MJ 一致性
30	MJ 按钮动作	U、V 等按钮产生的作品，`parent_id` 为来源
31	MJ 局部重绘	局部重绘产生的作品，`parent_id` 为来源

model_id、model、api_key_id 字段：提交时使用的模型和 API 密钥。Midjourney 的按钮、局部重绘、同步进度，都使用记录绑定的 api_key_id，即使模型后来换了密钥也不受影响。

③ prompt 字段：提示词，即画面描述。融图、换脸没有提示词。

negative_prompt 字段：不希望出现的内容。Midjourney 拼接为 --no 参数，硅基流动映射为 negative_prompt 参数。

input_images 字段：输入图片，JSON 数组，例如说 [{"role":"reference","url":"..."}]。其中 role 对应 AiImageInputRoleEnum 枚举：reference 参考图、blend 融图、swap_source 来源脸、swap_target 目标图、cref 角色参考、sref 风格参考、mask 蒙版；url 为文件服务的地址。

width、height 字段：图片宽高。通用模型为所选尺寸；Seedream 生成前未知，记为 0，成功后按实际的结果尺寸回写；Midjourney 记录所选比例的数值（例如说 16:9 记为 16、9），换脸没有比例，记为 0。

④ options、midjourney_options、seedream_options 字段：绘制参数，JSON 格式，按平台只写其中一个，对应 AiImageDO 的内部类：

options：通用模型（OpenAI、通义、硅基流动、Stability）的参数，对应 Options 类，包括 quality 画质、aspectRatio 比例（只用于回填）、seed 随机种子、steps 推理步数、cfgScale 引导系数、sampler 采样方法、stylePreset 风格预设、clipGuidancePreset CLIP 引导
midjourney_options：Midjourney 的参数，对应 MidjourneyOptions 类。请求参数有 version、aspectRatio、quality、stylize、chaos、seed、tile、raw、hd、imageWeight、characterWeight、styleWeight、styleVersion、dimensions（融图尺寸）、customId（执行的按钮）；由服务端写入的元数据有 finalPrompt（最终提示词）、buttons（中转返回的按钮）、actionLabel（按钮名称）、providerStatus（中转的任务状态）、modalProtocol（局部重绘的中转流程）
seedream_options：Seedream 的参数，对应 SeedreamOptions 类。请求参数有 size（尺寸档位）、optimizePromptMode、watermark；由服务端写入的元数据有 resultSize（结果尺寸）、usage（用量）、errorCode（上游错误码）

⑤ status 字段：绘画状态，对应 AiImageStatusEnum 枚举，目前有 10 进行中、20 已完成、30 已失败。因为绘图比较耗时，所以整体流程是：

通用模型、Seedream：先插入一条 10 进行中的记录，再异步调用模型生成。成功后，把图片转存到项目的文件服务，更新为 20 已完成
Midjourney：先插入一条 10 进行中的记录，再提交到中转，记录返回的 task_id；提交被拒绝或异常时，直接更新为 30 已失败。之后，由中转回调 /ai/image/midjourney/notify 接口，或 AiMidjourneySyncJob 定时同步，更新进度、按钮和结果
超过 10 分钟仍未完成的，由 AiImageTimeoutJob 更新为 30 已失败
以上更新都只针对进行中的记录，超时、完成后迟到的回调，不会覆盖结果

progress 字段：进度（0-100），生成中展示在作品卡片上。

pic_url 字段：图片地址，生成成功后，存储转存到文件服务后的地址。

error_message 字段：错误信息，生成失败后，存储失败原因。

finish_time 字段：完成时间，已完成、已失败时记录。

⑥ task_id 字段：上游的任务编号，目前用于 Midjourney 中转。因为中转可能复用已有的任务，所以不唯一。

parent_id 字段：来源记录编号，对应 ai_image 表的 id 字段，用于 Midjourney 按钮、局部重绘产生的作品。

最最最关键的代码！！！大家可以重点看看！！！

AiImageServiceImpl：通用模型、Seedream 的绘制，Midjourney 五种模式、按钮、局部重绘的提交，以及回调、同步、超时的实现
AiImageUtils：各平台请求参数的构建，例如说 #buildImageOptions(...)、#buildSeedreamRequest(...)、#buildMidjourneyPrompt(...)
MidjourneyApi：调用 Midjourney 中转接口的实现，可见《【模型接入】Midjourney》
前端 imageCapabilities.ts：各模型的能力常量

← AI 对话 AI 知识库→