Skip to content

Latest commit

 

History

History
163 lines (120 loc) · 11.5 KB

skill.md

File metadata and controls

163 lines (120 loc) · 11.5 KB

qwen-image-forge —— Qwen-Image 出图与提示词契约

本技能把「用户的口语需求」变成「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 没起来或没装权重:如实说明这条前置条件(见下「后端」),不要反复重试

意图路由(三步)

  1. 有没有参考图?
    • 没有 → Text-to-Image:照 references/t2i_rules.md 写「成品画面描述」。
    • 有 → Edit:照 references/edit_rules.md 写「修改指令」,并按规则标注 <image1>、<image2>…。
  2. 画幅比从哪来? 用户明说了就用用户的;没说就按被画主体的朝向定(横的主体偏宽、竖的主体偏高)。比例只出现在 wh_ratio 字段里,绝不写进提示词正文。
  3. 要不要立刻出图? 用户是在下订单(「给我画一张…」「把这张改一下」)→ 改写完直接调工具 (无参考图 → 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 就新建一个画板(用提示词首行命名)。适合「新题材的第一张」。
  • 同一组图继续出图 / 改图时,把上一次返回的 board.id 传回 board 参数—— 这样新图和来源落在同一块画板上,用户在工作台里能在一块画布上看到整个演进。 board 也收名字(大小写不敏感);没见过的值会被当作新画板的名字,不会报错。

「出图后的收尾」里向用户报画板时用返回 summary 末尾那句(画板名 + id),不要自己编 id。

后端:只有本机 ComfyUI 一条路

本插件不自带任何本地运行时——不建 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,写错一处就白等几十分钟下载。

两个权重家族:base 与 turbo

配置 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> 标注、画幅互斥)