Four MoE models expose `aux_loss` in their output type and never set it

快速结论：当你在 Transformers 中加载 AFMoE、Cohere2-MoE、HY-V3、Zaya 这类 MoE 模型并开启 output_router_logits=True 时，输出对象里会出现 aux_loss 字段，但它的值是 None。这通常不是运行报错，而是输出类型与实际实现不一致导致的困惑，优先排查模型是否属于“用 bias 做负载均衡、不产生 auxiliary loss”的这一类。

适用环境：Issue 中确认的环境为 transformers 5.17.0.dev0、Linux x86_64 (glibc 2.35)、Python 3.13.13、PyTorch 2.13.0+cu130、GPU 可用；同时列出 huggingface_hub 1.29.0 与 accelerate 1.14.0。触发模型类型包括 qwen3_moe、afmoe、cohere2_moe、hy_v3、zaya。

最快修复方案：暂无确认的一步修复方案。Issue 的最终处理方向是：不追求新增输出类型，而是在 modeling_outputs.py 中把该字段的含义补充清楚，并由训练库（如 TRL）自行决定是否使用 auxiliary loss。相关文档补充已在 #48920 合并。

注意事项：不要把 aux_loss=None 直接判断为模型损坏或配置错误。对于 AFMoE、HY-V3、Zaya，这来自“bias 均衡、不返回 auxiliary loss”的设计；Cohere2-MoE 的情况在 Issue 中并未最终确认是设计如此还是遗漏。若下游代码依赖 aux_loss，仍应在运行时检查是否为 None。

问题场景

用户在 Transformers 中通过 AutoModelForCausalLM 加载 MoE 模型，并传入 output_router_logits=True，期望拿到 router logits 与 auxiliary loss。实际运行后，router logits 能正常返回，但 outputs.aux_loss 始终是 None。Issue 中的最小复现覆盖 qwen3_moe、afmoe、cohere2_moe、hy_v3、zaya 五种模型类型，其中只有 qwen3_moe 返回了非空的 aux_loss。

报错原文

Four MoE models expose `aux_loss` in their output type and never set it

qwen3_moe      router_logits=True  aux_loss=2.001878023147583
afmoe          router_logits=True  aux_loss=None
cohere2_moe    router_logits=True  aux_loss=None
hy_v3          router_logits=True  aux_loss=None
zaya           router_logits=True  aux_loss=None

`HYV3ForCausalLM` says so in the code: `aux_loss=None,  # Not used in this model`.

原因分析

这些 MoE 模型共用或暴露了带 aux_loss 字段的输出类型 MoeCausalLMOutputWithPast，但实现上并没有计算 auxiliary loss。AFMoE、HY-V3、Zaya 使用 per-expert bias 加在 routing scores 上再 top-k 的“aux-loss-free”均衡方案，因此没有 auxiliary loss 可返回；AFMoE、HY-V3、Zaya 还在 config 中声明了 output_router_logits，容易让使用者误以为模型支持 auxiliary loss。Cohere2-MoE 既没有 auxiliary loss，也没有找到 bias 均衡逻辑，Issue 中未确认这是否符合 Cohere 的原始配方。维护者后续指出，判断某个模型“是否有 aux loss”本不属于 Transformers 的职责，负载均衡损失是训练期概念，应由训练库决定；Transformers 需要保证的是 router logits 能稳定返回。另有 17 个 MoE 模型在 gate 中计算 router logits 却在输出前丢弃，导致 output_router_logits=True 实际无效，该问题由 #48911 跟踪、#48920 修复。

环境排查

确认 transformers 版本是否为 5.17.0.dev0 或包含 #48920 之后的版本。
确认 Python 版本、PyTorch 版本与 CUDA/GPU 是否与当前模型要求匹配；Issue 环境为 Python 3.13.13、PyTorch 2.13.0+cu130。
确认是否安装了 accelerate、huggingface_hub 等相关依赖；Issue 中分别为 1.14.0、1.29.0。
确认调用的模型类型：qwen3_moe、afmoe、cohere2_moe、hy_v3、zaya。
确认是否传入 output_router_logits=True，以及下游代码是否直接假设 aux_loss 非空。

解决步骤

先用 Issue 中的最小复现脚本检查目标模型是否真的返回 router logits，以及 aux_loss 是否为 None。
如果 router_logits 为 None，说明该模型可能属于“计算了 router logits 但未返回”的情况，需要检查是否已包含 #48920 的修复。
如果 router_logits 能返回而 aux_loss 为 None，不要在该模型上强行读取 aux_loss；改为在下游训练代码中自行判断是否需要以及如何计算负载均衡损失。
如果下游库（如 TRL）已经通过 outputs.aux_loss is not None 做运行时保护，保持该保护即可，不要把 None 当作异常中断。
如果使用 Cohere2-MoE 并需要均衡损失，Issue 未给出确认结论，可优先尝试参照同类 bias-free 或 bias-balanced 模型的处理方式，但需自行验证训练效果。

验证方法

重新运行最小复现脚本，确认目标模型的 router_logits 是否为 True。对于 AFMoE、HY-V3、Zaya，aux_loss 为 None 是预期现象；对于 Qwen3-MoE，应能看到非 None 的 aux_loss。同时确认升级到包含 #48920 的版本后，相关字段的 docstring 已说明 bias-balanced router 下该字段为 None。最终验收标准应以你的下游训练代码能否在 aux_loss is None 时正常分支为准。