PR #22360 分析报告
执行摘要
该PR修复了扩散模型中因加载多个精度变体检查点导致的不一致性bug，通过过滤重复文件和添加快速失败检查，确保权重加载确定性，提升Sana等模型的稳定性，属于重要的扩散模块维护性修复。
功能与动机
为什么做：根据PR body，动机是解决Sana（及其他如mova模型）的一致性波动问题。根本原因是目录中同时存在多个精度变体的safetensors文件（例如foo.safetensors和foo.fp16.safetensors），加载时重复的参数名称导致最终权重依赖于文件加载顺序，从而引发非确定性行为。
实现拆解
按模块拆解改动：
- transformer_load_utils.py：新增
_filter_duplicate_precision_variant_safetensors函数，使用正则表达式_PRECISION_VARIANT_SUFFIX_RE识别精度后缀（如.fp16），当存在非精度变体的规范文件时，过滤掉重复变体。
canonical_path = f"{match.group('stem')}{match.group('shard') or ''}{match.group('ext')}"
if canonical_path in canonical_paths:
removed.append(path)
- weight_utils.py：新增
_raise_if_duplicate_safetensors_keys函数，在迭代safetensors文件时检测重复tensor键，并抛出ValueError快速失败，避免加载顺序依赖。
- 测试文件：更新
consistency_threshold.json中多个模型的阈值（如qwen_image_t2i_cache_dit_enabled的CLIP阈值从0.92提升至0.99），反映修复后稳定性提升；新增test_transformer_quant.py单元测试，覆盖过滤逻辑。
评论区精华
review讨论中的关键交锋：仅有一个review评论，由gemini-code-assist[bot]提出，但话题偏离核心变更。评论指出scheduler的warmup过程在多节点环境中会因临时目录路径不共享而失败，建议使用固定路径或共享存储方案。然而，此评论针对的文件scheduler.py未在本PR中修改，可能是一个无关反馈或误关联。
引用评论要点："The use of tempfile.mkdtemp() on the source rank followed by broadcasting the absolute path to all other ranks will cause failures in multi-node deployments."
风险与影响
具体风险：
- 过滤误判：正则表达式可能错误匹配文件路径，导致必要精度变体被过滤，影响模型精度或加载失败。
- 快速失败过度：
_raise_if_duplicate_safetensors_keys函数可能因误报重复键而中断合法加载场景，尤其是在复杂分片配置下。
影响评估：
- 用户影响：修复后，扩散模型（如Sana、Wan）的输出更稳定，减少性能波动。
- 系统影响：增强加载模块的鲁棒性，降低因文件打包错误导致的不确定风险。
- 团队影响：为类似权重加载问题提供了设计参考，例如优先规范文件和防御性检查。
关联脉络
与历史PR的关系：
- PR #21817：同为扩散模块修复，针对warmup图像初始化的秩安全问题，共享一致性和加载主题。
- PR #22127：涉及扩散模型的NVFP4量化测试，反映团队在扩散和量化领域的持续投入。
演进趋势：近期多个PR（如#21861、#21610）关注性能优化和内核扩展，而本PR侧重核心加载路径的确定性修复，表明仓库在功能扩展的同时，也加强基础模块的稳定性和可靠性。
参与讨论