本技能把「用户的口语需求」变成「Qwen-Image 认的提示词」,并把同一个契约里的画幅比直接交给工具参数,一步出图。
关键词:Qwen-Image、千问生图、通义万相出图、wh_ratio、提示词改写、改图/融图。
Qwen-Image 的提示词规范给出的答案不是一段随便的描述,而是一份结构化契约:一段描述性散文 + 一个画幅比。
出图插件通常只收「成品 prompt」,画幅比要靠人再翻译一遍像素宽高——本插件把这一步去掉:
契约里的 wh_ratio 就是 qwen_image_generate 的一等参数,原样传过去即可。
职责边界:改写提示词由你(模型)完成;工具只负责出图与落盘。工具不会替你润色 prompt。
- 用户想「画一张图 / 生成图片 / 出个海报 / 做个头像」,并且希望走 Qwen-Image
- 用户给了一段口语需求,需要先按契约改写成提示词再出图
- 用户要按指定的画幅比出图(横版、竖版、方图、宽屏)
- 用户要改图 / 融图(给了一张或多张参考图)——此时用 Edit 契约,见
references/edit_rules.md, 并把成品指令与参考图交给qwen_image_edit
- 用户只是问「Qwen-Image 怎么用」「帮我写一段提示词」而不要出图:只做改写与讲解,不要调用生成工具(不要凭空消耗额度)
- 用户要的是像素级后处理(抠图、放大、裁剪、去水印):本插件只做生成与参考图编辑,不做后处理
- 用户想指定别的模型(Midjourney / SD / 豆包等):本插件只面向 Qwen-Image
- 用户本机 ComfyUI 没起来或没装权重:如实说明这条前置条件(见下「后端」),不要反复重试
- 有没有参考图?
- 没有 → Text-to-Image:照
references/t2i_rules.md写「成品画面描述」。 - 有 → Edit:照
references/edit_rules.md写「修改指令」,并按规则标注<image1>、<image2>…。
- 没有 → Text-to-Image:照
- 画幅比从哪来? 用户明说了就用用户的;没说就按被画主体的朝向定(横的主体偏宽、竖的主体偏高)。比例只出现在
wh_ratio字段里,绝不写进提示词正文。 - 要不要立刻出图? 用户是在下订单(「给我画一张…」「把这张改一下」)→ 改写完直接调工具
(无参考图 →
qwen_image_generate;有参考图 →qwen_image_edit);用户是在咨询(「这种需求提示词怎么写」)→ 只给契约结果,等用户点头再出图。
T2I:
{"rewritten_prompt": "<一段描述性散文>", "wh_ratio": "16:9"}Edit:
{"rewritten_prompt": "<一段修改指令>", "wh_ratio": "", "ratio_follow": "<image1>"}规则:wh_ratio 与 ratio_follow 互斥,一个非空另一个必须是空字符串。
用户要 JSON 形态时只输出这一行 JSON(不要代码围栏、不要解释);日常对话里就直接给出可复制的提示词正文 + 一句画幅比说明,不必非套 JSON。
把这个契约原样交给工具:
- 无参考图 →
rewritten_prompt传给qwen_image_generate.prompt,wh_ratio传给它的wh_ratio。 - 有参考图 →
rewritten_prompt传给qwen_image_edit.prompt,参考图按顺序传给它的images(绝对路径或 data URI),ratio_follow原样传给它的ratio_follow("<image1>"写成"image1"),wh_ratio原样传给它。 不要自己把 ratio_follow 换算成比例:插件会量出那张参考图的实际像素再挑 32 对齐的画布, 并在返回里给出ratio_deviation_percent/ratio_follow_image;你在回复里照着它说一句即可。 两个字段都为空时不用猜——编辑器默认跟随第一张参考图(第 1 张就是编辑目标)。
| 工具 | 职责 | 什么时候用 |
|---|---|---|
qwen_image_generate |
出图主入口。收成品 prompt,wh_ratio 一等参数(官方 7 档),可选 width/height 覆盖、steps、seed、count、preset、board |
用户要从零出图时 |
qwen_image_edit |
参考图编辑(图生图)。收成品改图 prompt + images(1–10 张绝对路径或 data URI),ratio_follow 让画布跟随某张参考图(与 wh_ratio 互斥,都可省略=跟随第一张),其余参数同上 |
用户给了一张或多张参考图、要按它们改图/融图时 |
qwen_image_status |
只读体检:本机 ComfyUI 是否在跑(探过哪几个端口、三个权重能不能被它的加载器枚举到、显卡型号与显存余量)、输出目录能不能写。不产图、不写盘、不改配置 | 出图失败、或不确定后端是否就绪时先跑它 |
结果会记录到一个画板(工作台按它组织画布与素材页)。规则只有两条:
- 省略
board就新建一个画板(用提示词首行命名)。适合「新题材的第一张」。 - 同一组图继续出图 / 改图时,把上一次返回的
board.id传回board参数—— 这样新图和来源落在同一块画板上,用户在工作台里能在一块画布上看到整个演进。board也收名字(大小写不敏感);没见过的值会被当作新画板的名字,不会报错。
「出图后的收尾」里向用户报画板时用返回 summary 末尾那句(画板名 + id),不要自己编 id。
本插件不自带任何本地运行时——不建 venv、不下权重、不拉进程,也不再提供云端 API: 出图与改图都跑在用户自己装好的 ComfyUI 与三个 Qwen-Image 权重上,零下载、零转换、完全离线。 没有别的后端档位,工具参数里也没有选后端的入口。
- ComfyUI 没起来或缺权重时,报错会点名缺什么(探测过哪些端口、缺哪个文件、放进哪个目录),
并指向
docs/comfyui-deployment.md。此时不要重试,先让用户照文档把环境补齐。
用户问「我要把本地跑起来 / 怎么部署」时:让他照 docs/comfyui-deployment.md 走——桌面版下载 →
建实例 → 从 hf-mirror 下三个权重 → 放进 ComfyUI 的 models/unet|clip|vae → sha256 校验,逐步可执行。
不要凭记忆报下载地址或目录名:桌面版的目录叫 unet/clip/vae,不是 HF 仓库里的
diffusion_models/text_encoders,写错一处就白等几十分钟下载。
配置 comfyModel 决定跑哪一档(默认 base):
turbo:8 步出图,同一画质下比 base 快约 2.7×。日常默认建议 turbo。base:25 步。写实人像、画面里要出现中文文字、古典/绘画性构图这三类切 base——turbo 在这些题材上掉细节。comfyModel: "turbo"是请求不是保证:/object_info里没有 turbo unet 时会自动回落 base, 并在结果comfyui.turbo_fallback里说明。别据此向用户承诺速度。
显存由 ComfyUI 自己管,插件不再做显存门禁。8 GB 卡上的实测经验:
文生图 1312×736 约 2 s/步;1.5MP 画布的 8 步编辑 19–23 s。
显存真不够时是干净的 CUDA OOM(ComfyUI 报错回传),不是插件拒绝。
卡上同时开着别的吃显存程序(第二个 ComfyUI 实例、游戏、Blender)会显著拖慢甚至 OOM——
必要时让用户先关掉,或用 ComfyUI 自己的 /free 交回显存。
wh_ratio 只有官方 7 档,工具按 ~1.5MP 预算把它们换算成 32 对齐的像素(下表是工具的确定性换算结果,
也写在 qwen_image_generate 的返回里,不要自己另算一套):
wh_ratio |
像素 | 情形 |
|---|---|---|
1:1 |
1248×1248 | 方图、头像、图标、专辑封面 |
4:3 |
1408×1056 | 横版、平板、演示页 |
3:4 |
1056×1408 | 竖版、证件照、小红书 |
3:2 |
1536×1024 | 横版默认档(大多数横构图) |
2:3 |
1024×1536 | 竖版默认档、海报 |
16:9 |
1664×928 | 宽屏、视频封面、PPT |
9:16 |
928×1664 | 手机壁纸、竖屏短视频封面 |
- 用户给了非官方档(
21:9、18:39、5:7…):挑最接近的官方档,并在回复里说明你改用了哪一档。 - 改图且要跟随参考图(
ratio_follow):不要自己挑档,把ratio_follow原样交给qwen_image_edit; 它量的是参考图的实际像素,所以2048×1152这类非官方档也能跟随(结果里会给出实际像素与比例偏差)。 - 用户给了显式像素(
1920x1080):先换算成比例再挑档;只有用户坚持要具体像素时,才用width/height覆盖(必须是 32 的倍数)。 - 用户说「4K / 高清」这类词:那是画质形容,不是画幅比,不要据此推断比例。
- 想换构图但比例不变:改提示词里的机位与裁切,不要动
wh_ratio。
qwen_image_generate / qwen_image_edit 都会把图落盘并回传 markdown 字段。逐字复制那几行  到你的回复正文——
客户端的文件路由会把本地绝对路径渲染成真图片,这是图片能在聊天框里显示的唯一可靠路径(工具结果里再贴一遍 JSON 只是给机器读的)。
向用户交代结果时带上画板:summary 末尾会写「画板「名字」(新建),id b…」。用户想继续改同一组图时,
你后续调用必须把这个 id 传回 board(见「画板」一节)。
- 把比例、分辨率、「8K」「masterpiece」这类空话写进提示词正文 → 契约里这些只在字段里,正文不许出现
- 用中文写 T2I 描述性散文 → 散文永远英文;只有「图里要显示的文字」留在双引号里用原文
- 把用户对任务的要求(「用双引号」「不要有硬边」)当成画面内容写进散文 → 静默遵守,不要复述
- 一次调用里既给
wh_ratio又给width/height→ 以width/height为准,但请不要自相矛盾地给两者 - 改图时既给
wh_ratio又给ratio_follow→ 工具会直接报错(官方契约里这两者互斥),请只留一个 - 把参考图路径写成相对路径 / 把图省掉 → 工具会点名
images[n]报错;参考图必须绝对路径或 data URI - 出图失败就直接重试同一份参数 → 先
qwen_image_status看清是 ComfyUI 没起来,还是权重没装 - 改图报「ComfyUI 不可用」→ 改图只有本机 ComfyUI 一条路;这不是重试能解决的,
照
docs/comfyui-deployment.md装好再跑,或如实告诉用户缺什么 - 8GB 卡上连发 2K 改图 → 显存不够会 CUDA OOM;编辑走 ComfyUI 时它自己按画布缩放参考图,
没有插件侧的可调档位,尺寸真的要压就传更小的
width/height - 以为有云端 API 或免安装的出图通道 → 不存在。本插件只有本机 ComfyUI 一条路, 没装 ComfyUI 就如实说明,不要许诺云端出图
references/t2i_rules.md—— 文生图改写规则(散文覆盖哪些维度、按什么顺序写、哪些词必须避免)references/edit_rules.md—— 改图/融图规则(属性解耦、语言决策、<imageN>标注、画幅互斥)