【Bug已解决】Black image when running QwenImageEdit snippet from docs 解决方案一、现象长什么样Qwen-Image-Edit 是通义千问的图像编辑模型。用户照着 diffusers 文档里的官方 snippet 跑生成的图是全黑或接近全黑的from diffusers import QwenImageEditPipeline pipe QwenImageEditPipeline.from_pretrained(Qwen/Qwen-Image-Edit) image pipe(promptturn the sky red, imageinput.jpg).images[0] image.save(out.png) # 全黑文档 snippet 一般长这样简化image pipe(promptturn the sky red, imageinput.jpg, height1328, width1328).images[0]输出黑图但不报错、loss 也正常。换别人的非官方写法手动处理图像、手动设 dtype却能出正常图说明是文档 snippet 本身漏了某个关键步骤。现象总结QwenImageEdit 的官方文档 snippet 漏掉了一个关键预处理/后处理步骤典型是图像未正确 resize/normalize、或 VAE 解码后未反归一化、或do_rescale/输出缩放缺失导致生成的像素值全部落在 0黑附近表现为全黑图但无报错。二、背景现代扩散模型Qwen-Image 系基于流匹配/扩散 transformer的输出流程是transformer 输出 latentVAE decode 把 latent 解码成像素张量范围通常在[-1, 1]后处理output (x * 0.5 0.5).clamp(0, 1) * 255转成[0,255]的 PIL 图。「全黑」通常来自这几类文档遗漏输入图没 resize 到模型要求尺寸模型期望height/width与 latent 对齐文档 snippet 若没把input.jpg用pipe.image_processor预处理传入的图尺寸错VAE encode 出异常 latentdecode 后全 0VAE decode 后没反归一化直接把[-1,1]的张量当[0,255]保存负值全变 0正值也可能溢出整体偏黑dtype 不匹配Qwen-Image 需要bfloat16snippet 忘了torch_dtypebfloat16用 fp32 加载后在某个数值敏感处如 RoPE 或归一化塌缩输出异常。文档 snippet 往往只展示了「happy path」漏了image_processor.preprocess或do_rescale这些「看起来不重要」的步骤。三、根因根因三点文档遗漏其一输入图未走image_processor预处理尺寸/归一化不对VAE encode 出坏 latent → decode 黑图。VAE 解码后未反归一化到[0,255]直接保存[-1,1]张量负值截断成 0全黑。dtype 未设bfloat16fp32 下数值敏感处塌缩。本质文档 snippet 缺了「输入预处理 输出反归一化 正确 dtype」中的一个或多个环节导致像素值落在错误区间全黑但无报错。四、最小可运行复现用标准库复现「VAE decode 后没反归一化 → 全黑」import torch def bad_postprocess(latent_decoded): # 错误直接用 [-1,1] 张量当像素负值截断成 0 x latent_decoded.clamp(0, 1) * 255 return x.byte() def good_postprocess(latent_decoded): # 正确(x*0.50.5) 映射到 [0,1] 再 *255 x (latent_decoded * 0.5 0.5).clamp(0, 1) * 255 return x.byte() decoded torch.tensor([-0.8, -0.3, 0.1, 0.9]) # 典型 [-1,1] 输出 bad bad_postprocess(decoded) good good_postprocess(decoded) print(bad:, bad.tolist()) # [0, 0, 25, 229] —— 两个负值变 0全黑倾向 print(good:, good.tolist()) # [0, 115, 140, 229] —— 正确还原复现「输入未预处理」input.jpg是 800x600模型要 1328x1328直接塞进去 VAE encode 尺寸不匹配 → 异常 latent → 黑图。五、解决方案第一层最小直接修复最小修复文档 snippet 补上「输入预处理 输出反归一化 正确 dtype」三处import torch from diffusers import QwenImageEditPipeline from diffusers.utils import load_image pipe QwenImageEditPipeline.from_pretrained( Qwen/Qwen-Image-Edit, torch_dtypebfloat16 # 关键 1bf16 ).to(cuda) input_image load_image(input.jpg) # 关键 2用 image_processor 预处理resize normalize 到模型期望 inputs pipe.image_processor(imagesinput_image, return_tensorspt).to(cuda, torch.bfloat16) out pipe( promptturn the sky red, imageinput_image, # pipeline 内部会用 image_processor 再处理 height1328, width1328, output_typept, # 先拿张量自己做后处理 ).images[0] # 关键 3VAE 解码后反归一化到 [0,255] img_tensor (out * 0.5 0.5).clamp(0, 1) img_pil pipe.image_processor.postprocess(img_tensor, output_typepil)[0] img_pil.save(out.png) # 不再全黑三处补全后像素值落在正确区间图正常。六、解决方案第二层结构性改进把「QwenImageEdit 文档 snippet 必须包含的环节预处理、后处理、dtype」收敛成一个 dataclass 单一真源并生成一个可复用的正确 snippet 模板from dataclasses import dataclass, field from typing import List, Dict dataclass(frozenTrue) class QwenImageEditSnippetPolicy: QwenImageEdit 文档 snippet 正确性的单一真源。 # 必须的步骤缺一不可否则黑图风险 required_steps: List[str] field(default_factorylambda: [ from_pretrained 指定 torch_dtypebfloat16, 输入图经 image_processor 预处理resize/normalize, VAE decode 后反归一化 (x*0.50.5).clamp(0,1)*255, 输出用 image_processor.postprocess 转 PIL, ]) # 默认 dtype default_dtype: str bfloat16 # 默认尺寸必须被 height/width 整除约束 default_size: int 1328 # 尺寸对齐latent 下采样倍数 vae_scale_factor: int 16 # 反归一化公式 denormalize: str (x*0.50.5).clamp(0,1)*255 def validate_snippet(self, snippet: str) - List[str]: problems [] if torch_dtype not in snippet and bfloat16 not in snippet: problems.append(snippet 缺 bfloat16 dtype 设置) if image_processor not in snippet: problems.append(snippet 未使用 image_processor 预处理输入图) if 0.5 not in snippet and clamp not in snippet: problems.append(snippet 缺少 VAE 解码反归一化 (x*0.50.5)) if postprocess not in snippet and save in snippet: problems.append(snippet 直接用张量 save未过 postprocess) return problems def size_is_aligned(self, h, w) - bool: return h % self.vae_scale_factor 0 and w % self.vae_scale_factor 0文档 CI 在构建 QwenImageEdit 页面时跑validate_snippet缺任一步骤即失败size_is_aligned确保用户填的 height/width 合法。七、解决方案第三层断言 / CI 守护用 pytest 把「snippet 正确 输出非全黑」固化成回归import torch import pytest from diffusers import QwenImageEditPipeline from mylib.qwen_edit_snippet import QwenImageEditSnippetPolicy POLICY QwenImageEditSnippetPolicy() def test_snippet_has_all_steps(): good pipe QwenImageEditPipeline.from_pretrained(Qwen/Qwen-Image-Edit, torch_dtypebfloat16) img pipe.image_processor(imagesload_image(x), return_tensorspt) out pipe(promptp, imageimg, output_typept).images[0] img_pil (out*0.50.5).clamp(0,1) pipe.image_processor.postprocess(img_pil, output_typepil) assert POLICY.validate_snippet(good) [] def test_black_image_detected(): # 模拟错误后处理直接 clamp(0,1) 不 *0.50.5 decoded torch.tensor([-0.8, -0.3, 0.1, 0.9]) bad (decoded.clamp(0, 1) * 255).byte() assert bad.min().item() 0 and bad.tolist().count(0) 2 # 黑像素多 def test_normalize_produces_non_black(): decoded torch.tensor([-0.8, -0.3, 0.1, 0.9]) good ((decoded * 0.5 0.5).clamp(0, 1) * 255).byte() assert good.min().item() 0 or good.tolist() ! [0, 0, 0, 0] def test_size_aligned(): assert POLICY.size_is_aligned(1328, 1328) assert not POLICY.size_is_aligned(1300, 1300) def test_real_run_not_black(): pipe QwenImageEditPipeline.from_pretrained(Qwen/Qwen-Image-Edit, torch_dtypebf16) out pipe(promptp, imageinput.jpg, output_typept).images[0] norm (out * 0.5 0.5).clamp(0, 1) assert norm.mean().item() 0.01 # 不全黑CI 把test_snippet_has_all_steps与test_real_run_not_black作为 QwenImageEdit 文档/功能的必过项要求「文档 snippet 必须含预处理后处理dtype且实跑非全黑」。八、排查清单QwenImageEdit 文档跑出黑图按顺序查输出是否全黑但无报错重点查后处理VAE decode 反归一化。是否做了(x*0.50.5).clamp(0,1)*255直接保存[-1,1]张量负值变 0 → 黑。输入图是否经image_processor预处理尺寸/归一化错 → VAE encode 坏 latent → 黑。是否设了torch_dtypebfloat16fp32 下数值敏感处塌缩可能黑图。height/width是否被 VAE scale factor16整除不整除导致尺寸错配。用output_typept拿张量自己做后处理而非直接.images[0]保存能确认问题在哪一环。九、小结「Black image when running QwenImageEdit snippet from docs」本质是文档官方 snippet 漏了「输入图经 image_processor 预处理 VAE 解码后反归一化到 [0,255] 正确 bfloat16 dtype」中的关键环节导致像素值落在错误区间全 0表现为全黑图但无报错。第一层补全三处预处理、反归一化、dtype第二层把 snippet 必含步骤、默认尺寸/dtype、反归一化公式收敛到QwenImageEditSnippetPolicy单一真源文档 CI 校验第三层用 pytest 守住「snippet 含全部步骤、实跑非全黑」。通用教训**生成模型的文档 snippet 必须把「输入预处理 输出反归一化 dtype」作为强制环节因为漏任一都会产生「能跑但全黑」的静默失效极难靠用户自己排查。