Prhub
← 返回仓库详情

#20679 [diffusion] fix: fix accuracy for some image models

sgl-project/sglang · 作者 mickqian · 合并时间 2026-03-22 15:11

分析状态 已生成
文件变更 20提交数 27 · 评论 12
代码增减 +600 / -199
diffusion bugfix performance

执行摘要

修复多个图像扩散模型的准确性问题，通过对齐官方实现和修复序列并行偏差。

PR body中说明需要修复准确性，具体包括：为Qwen-Image引入true_cfg_scale以对齐官方CFG行为；为Qwen-Image-Edit尊重负图像提示，使无条件分支使用negative_prompt；保持Qwen2.5-VL vision rotary frequencies在fp32以减少编码器漂移；修复Z-Image的prompt tokenization和dtype问题；修正序列并行下的caption token分片逻辑，确保单GPU与多GPU输出一致。

建议扩散模型开发者和维护者精读此PR，特别是qwen_image.py和zimage.py中的序列并行处理设计，以及USPAttention的扩展实现，以学习多GPU下注意力机制的优化策略和对齐官方实现的技巧。

讨论亮点

Review讨论较少，仅gemini-code-assist[bot]在review评论中确认USPAttention参数修改正确，无争议点。Issue评论中用户Rockdu提供了量化测试结果，显示修复后cosine相似度达到1.0000，验证了修复的有效性。讨论聚焦于测试验证，结论是修复成功解决了SP精度问题。

实现拆解

实现按模型和层次拆解：

  1. 基类扩展：在base.py中添加钩子函数如postprocess_cfg_noise、get_latent_dtype和gather_noise_pred_for_sp，支持模型特定CFG变体和SP并行。
  2. Qwen-Image：在qwen_image.py中实现true-CFG的norm rescale逻辑，通过postprocess_cfg_noise匹配官方行为，并添加SP分片函数_shard_qwen_edit_img_cache_for_sp。
  3. Qwen-Image-Edit：保持旋转频率为fp32，修复负提示处理，并扩展SP支持。
  4. Z-Image：在zimage.py中更新tokenization使用渲染后的聊天模板，移除caption token分片改为复制后缀，并修复RoPE偏移；在模型层扩展USPAttention支持num_replicated_suffix。
  5. 通用层修改：在attention/layer.py中扩展USPAttention以支持复制后缀；在denoising.py中优化CFG归一化和重缩放逻辑。
文件 模块 状态 重要度
python/sglang/multimodal_gen/configs/pipeline_configs/qwen_image.py diffusion pipeline configs modified 8.0
python/sglang/multimodal_gen/configs/pipeline_configs/zimage.py diffusion pipeline configs modified 8.0
python/sglang/multimodal_gen/runtime/layers/attention/layer.py runtime layers modified 7.0
python/sglang/multimodal_gen/runtime/pipelines_core/stages/denoising.py pipeline stages modified 6.0
python/sglang/multimodal_gen/configs/pipeline_configs/base.py diffusion pipeline configs modified 5.0

分析完成后，这里会展示 LLM 生成的相对完整源码片段和详细注释。

关键符号

postprocess_cfg_noise get_classifier_free_guidance_scale _shard_qwen_edit_img_cache_for_sp _build_zimage_sp_plan forward (in USPAttention with num_replicated_suffix)

评论区精华

测试验证结果 正确性

Issue 评论中用户 Rockdu 提供了量化测试数据，显示修复后模型输出与单 GPU 参考的 cosine 相似度从 0.5039 提升至 1.0000，验证了 SP 精度问题的修复。

结论：修复有效，准确性得到充分验证。 · 已解决

风险与影响

技术风险包括：1) CFG修改在qwen_image.py中的norm rescale逻辑可能影响其他继承基类的模型，需回归测试；2) SP并行修改在qwen_image.py和zimage.py中可能引入多GPU对齐偏差，特别是在旋转缓存分片和caption token处理上；3) 浮点数精度调整（如保持fp32旋转频率）可能轻微影响性能；4) USPAttention扩展需确保向后兼容性，避免破坏现有注意力机制。

影响范围：所有使用Qwen-Image、Qwen-Image-Edit和Z-Image模型的用户将获得更准确的图像输出，提升用户体验。系统层面需重新测试这些模型的序列并行场景，确保跨GPU一致性。团队需关注配置管理，防止变更引入跨模型兼容性问题。影响程度中等，涉及核心生成路径但非全局架构变更。

SP 并行偏差风险 CFG 对齐兼容性 精度变化影响

关联 Issue

未识别关联 Issue

当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。

完整报告

Markdown PDF

执行摘要

本PR修复了Qwen-Image、Qwen-Image-Edit和Z-Image等多个图像扩散模型的准确性偏差问题，通过对齐官方diffusers实现、修正序列并行（SP）处理逻辑，确保单GPU与多GPU输出一致。变更影响扩散管道配置和注意力层，提升了模型生成质量，是扩散模块的重要改进。

功能与动机

动机源于这些模型在特定场景下输出与官方diffusers库不一致，尤其是在使用负提示、CFG（Classifier-Free Guidance）和SP并行时。PR body中明确指出需要"align CFG with official diffusers"、"respect negative-image"和"fix accuracy"，目标是消除偏差，提供更可靠的图像生成。具体问题包括Qwen-Image的CFG未匹配官方norm rescale、Qwen-Image-Edit的负提示处理不当、旋转频率精度漂移，以及Z-Image在SP下的tokenization和caption分片错误。

实现拆解

实现按模型和模块拆解，关键代码逻辑如下：

模型/模块 关键改动 代码示例（简要）
Qwen-Image 引入true_cfg_scale，重写postprocess_cfg_noise进行norm匹配 noise_pred * (cond_norm / noise_norm) in qwen_image.py
Qwen-Image-Edit 保持旋转频率为fp32，添加SP分片函数_shard_qwen_edit_img_cache_for_sp img_cache = shard_rotary_emb_for_sp(...) in qwen_image.py
Z-Image 移除caption token分片，改为复制后缀，修复RoPE偏移 num_replicated_suffix参数在zimage.py和layer.py中
通用层 扩展USPAttention支持num_replicated_suffix，优化CFG逻辑 _forward_with_replicated_suffix in layer.py
基类 添加钩子如get_latent_dtype和gather_noise_pred_for_sp 在base.py中定义默认实现

评论区精华

Review讨论较少，仅有gemini-code-assist[bot]确认修改正确。Issue评论中用户Rockdu提供了关键测试结果：

Rockdu: "Thanks for fixing this SP precision issue, here are some quantized test results on our side for reference ... Worst-case min_cosine vs single_gpu_ref ... Z-Image-Turbo: model_output 0.5039 → 1.0000 ✅ Fixed (exact match)"

这显示修复显著提升了多GPU下的输出一致性，无争议点，团队认可修复效果。

风险与影响

风险分析：

  • 回归风险：CFG修改在qwen_image.py中可能影响其他继承基类的模型，需全面回归测试。
  • SP并行风险：zimage.py中的caption token处理变更在复杂SP场景下可能引入新偏差，需验证多GPU对齐。
  • 性能影响：保持fp32旋转频率可能轻微增加内存使用，但确保了精度。
  • 兼容性：USPAttention扩展需确保不破坏现有注意力后端。

影响评估：

  • 用户影响：直接受益于更准确的图像生成，提升产品可靠性。
  • 系统影响：需更新模型配置和测试套件，确保跨环境一致性。
  • 团队影响：加强扩散模型维护流程，关注官方对齐和SP优化。

关联脉络

与近期PR的关联揭示扩散模块的持续演进：

  • PR #20862（添加FireRed-Image-Edit模型）：共享扩散模型配置框架，显示团队在扩展模型支持。
  • PR #21122（清理扩散Triton内核）：技术领域重叠，聚焦性能优化和代码现代化。
    本PR作为准确性修复的关键一环，补全了扩散模型在SP并行下的短板，与这些PR共同推动生态系统成熟。

参与讨论