Checkpoint conversion silently loads transposed fused-expert weights when the swapped dims are equal (Transpose(check_dims=True), qwen3_vl_m

快速结论：该报错属于隐性问题，在使用 Transformers 加载 Qwen3-VL-MoE 旧版布局检查点时触发，当模型中间层维度恰好等于隐藏层维度或其二分之一时，专家权重会被静默转置加载，模型输出变成垃圾数据且不报任何警告。优先排查 moe_intermediate_size 与 hidden_size 是否满足平方关系。

适用环境：Transformers 5.12.1（截至 2026-07-02 的 main 分支代码一致）、PyTorch 2.11.0、CPU 环境可复现。

最快修复方案：暂无官方确认的一步修复方案。官方 Issue 中提出了两种补丁方案但尚未合并；可优先尝试在 Transpose.convert 中加入平方维度警告，或采用配对转换器方案。

注意事项：官方 Qwen3-VL-MoE 检查点维度非平方，因此该问题当前不会影响官方模型；但裁剪/蒸馏后的社区版本或小维度测试配置可能触发。所有修复方案均停留在提议阶段，未经官方合并验证。

问题场景

使用 Transformers 库加载 Qwen3-VL-MoE 模型检查点时触发。具体来说，conversion_mapping.py 中定义的 qwen3_vl_moe 转换器使用 Transpose(1, 2, check_dims=True) 来兼容两种专家权重布局：旧版预分组布局 (E, H, 2I)/(E, I, H) 和 v5 F.linear 布局 (E, 2I, H)/(E, H, I)。当被交换的两个维度相等时，形状比较无法区分布局，检查点会被静默转置加载。

报错原文

Checkpoint conversion silently loads transposed fused-expert weights when the swapped dims are equal (Transpose(check_dims=True), qwen3_vl_moe)
# The shapes are the same: do NOT transpose
if tensor.shape == expected_shape:
    return {target_pattern: tensor}
# No warning, finite outputs, garbage model.

原因分析

可能原因：Transpose.convert 中的 check_dims=True 逻辑通过形状比较判断是否需要进行转置。当两个被交换的维度相等时（tensor.shape[self.dim0] == tensor.shape[self.dim1]），形状比较失去判别能力，”不转置”分支总是胜出，导致旧版布局的检查点以错误的张量方向加载。该问题存在两个触发变体：2 * moe_intermediate_size == hidden_size 影响 gate_up_proj，moe_intermediate_size == hidden_size 影响 down_proj。需要说明的是，{gate_up_proj, down_proj} 这一对不可能同时都是平方维度——2I == H 时 down_proj 形状为 (H, I) 非平方，I == H 时 gate_up_proj 形状为 (2I, H) 非平方——因此模块中总是存在一个可确定布局的无歧义兄弟张量。

环境排查

确认 Transformers 版本是否为 5.12.1 或更新（2026-07-02 之后未修复的 main 分支版本）
确认 PyTorch 版本（Issue 中使用 torch 2.11.0 复现）
检查模型配置中的 moe_intermediate_size 与 hidden_size 是否满足平方关系
确认检查点是否使用 Transformers ≤4.x 或保留旧版布局的工具导出的格式
如果涉及 microsoft/DeepSpeed 或 Unsloth 相关工具链，确认版本是否低于 2026-07-20（unsloth 已修复同类问题）

解决步骤

确认是否受影响：检查 moe_intermediate_size 是否等于 hidden_size 或 hidden_size / 2；若为官方 Qwen3-VL-MoE 检查点（非平方维度），则不受影响。
诊断问题：在加载后检查 gate_up_proj 和 down_proj 权重是否与预期一致，可对比参考模型输出验证。
优先尝试方案一（警告）：在 Transpose.convert 中添加平方维度警告，当 tensor.shape[self.dim0] == tensor.shape[self.dim1] 时提示布局歧义，避免静默加载错误模型。
优先尝试方案二（配对转换器）：将 gate_up_proj 与 down_proj 的单张量转换器替换为配对转换器（类似 Ernie expert fuse/split 操作的 ConversionOps），利用非平方兄弟张量确定布局。
检查同源问题：如果使用 Unsloth 相关工具，验证 preprocess_weight 是否已包含配对兄弟消歧修复（unslothai/unsloth-zoo#913 已合并修复）。
提交反馈：如果遇到此问题且需要官方修复，可在 #47031 中评论推动补丁合并。

验证方法

加载模型后，对 mlp.experts.gate_up_proj 和 mlp.experts.down_proj 权重执行 torch.equal 与参考值对比；如果模型能正常输出且与预期结果一致，则问题已解决。如使用补丁方案，验证平方维度配置下加载的权重方向正确（可将权重转置后与参考对比，确认布局匹配）。注意：官方 Issue 中的修复方案尚未合并，验证应基于本地补丁。