# PR #38621 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Model] Support GLM-5.3 Flash NVFP4 loading
- 合并时间：2026-09-10 04:51
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/38621

---

# 执行摘要

- 一句话：修复 GLM-5.3-Flash-NVFP4 混合精度模型加载问题，禁用无效的共享专家融合。
- 推荐动作：本 PR 是一个有针对性、高质量的兼容性修复。其价值在于：
 1) 解决了真实用户（发布者 nvidia）遇到的实际加载问题；
 2) 修改范围小且精准，逻辑清晰；
 3) 提供了全面的单元测试，覆盖了两种主要检查点变体和关键逻辑分支；
 4) 讨论中体现了对兼容性细节的仔细考量。建议相关领域的工程师精读此 PR，以学习如何为混合精度模型添加健壮的加载守卫条件。特别值得关注的是 `shared_experts_fusion_disable_reason` 方法中新增的量化特定检查逻辑，以及测试中如何模拟量化配置和并行环境。

# 功能与动机

根据 PR body，"nvidia/GLM-5.3-Flash-NVFP4 是一个混合精度的 ModelOpt 检查点：注意力模块和共享专家模块保持未量化，而路由专家使用 NVFP4。两个 GLM-5 特有的不匹配目前阻止了检查点加载：
1. 模型量化的排除模式使用 Hugging Face 名称在 `model.language_model.*` 下，而对应的 SGLang 模块在 `model.*` 下。权重加载器已执行此重命名，但精度选择没有。
2. 共享专家融合无法将检查点的未量化共享专家与其 NVFP4 路由专家组合。" 本 PR 旨在修复这些特定兼容性问题，而非进行更广泛的重构。

# 实现拆解

1. **添加权重名称映射器**：在 `glm5_next.py` 的 `Glm5NextForConditionalGeneration` 类中，新增了 `hf_to_sglang_mapper` 属性。该映射器使用 `WeightsMapper` 将 Hugging Face 的权重名称（如 `model.language_model.` 和 `model.visual`）转换为 SGLang 内部模块的名称（如 `model.` 和 `visual`）。这确保了量化配置在匹配排除模式时，使用正确的模块路径。
2. **增强共享专家融合守卫条件**：在同一个类的 `shared_experts_fusion_disable_reason` 类方法中，增加了针对 `modelopt_fp4` 量化的特定检查。该逻辑遍历所有 MoE 层，如果发现某个层的共享专家（`mlp.shared_experts`）被排除在量化之外，而其对应的路由专家（`mlp.experts`）却被量化，则返回一个原因字符串，从而禁用融合。这解决了混合精度组合的兼容性问题。
3. **新增单元测试覆盖**：创建了 `test/registered/unit/models/test_glm5_next_modelopt.py` 测试文件。其中包含三个关键测试：`test_checkpoint_exclusions_match_sglang_module_names` 验证了 NVIDIA 和 RadixArk 两种检查点变体的排除模式能正确匹配 SGLang 模块名；`test_nvidia_mixed_precision_shared_experts_disable_fusion` 验证了混合精度组合下融合被正确禁用；`test_radixark_uniform_fp4_shared_experts_keep_fusion` 验证了统一量化配置下融合保持启用。测试通过模拟和断言确保了新逻辑的正确性。

关键文件：
- `python/sglang/srt/models/glm5_next.py`（模块 模型定义；类别 source；类型 data-contract；符号 Glm5NextForConditionalGeneration.hf_to_sglang_mapper, Glm5NextForConditionalGeneration.shared_experts_fusion_disable_reason）: 这是实现修复的核心源码文件。新增了权重名称映射器以对齐 HuggingFace 和 SGLang 的模块命名，并在关键方法 `shared_experts_fusion_disable_reason` 中添加了混合精度守卫逻辑，直接解决了模型加载和融合的兼容性问题。
- `test/registered/unit/models/test_glm5_next_modelopt.py`（模块 GLM-5 测试；类别 test；类型 test-coverage；符号 TestGlm5NextModelOpt, test_checkpoint_exclusions_match_sglang_module_names, test_nvidia_mixed_precision_shared_experts_disable_fusion, test_radixark_uniform_fp4_shared_experts_keep_fusion）: 这是新增的单元测试文件，为本次修复提供了关键的测试覆盖。它验证了权重名映射的正确性、混合精度场景下融合禁用逻辑的触发，以及统一量化场景下融合保持启用的行为。

关键符号：Glm5NextForConditionalGeneration.shared_experts_fusion_disable_reason, Glm5NextForConditionalGeneration.hf_to_sglang_mapper, ModelOptFp4Config.is_layer_excluded, ModelOptFp4Config.apply_weight_name_mapper

## 关键源码片段

### `python/sglang/srt/models/glm5_next.py`

这是实现修复的核心源码文件。新增了权重名称映射器以对齐 HuggingFace 和 SGLang 的模块命名，并在关键方法 `shared_experts_fusion_disable_reason` 中添加了混合精度守卫逻辑，直接解决了模型加载和融合的兼容性问题。

```python
# 在 Glm5NextForConditionalGeneration 类定义中，新增了 hf_to_sglang_mapper 属性。
# 它使用 WeightsMapper 定义字符串替换规则，将 HuggingFace 权重路径前缀
# "model.language_model." 和 "model.visual" 分别映射到 SGLang 内部的 "model." 和 "visual"。
# 这确保了量化配置在匹配 exclude_modules 时，使用的是 SGLang 模块路径。
class Glm5NextForConditionalGeneration(nn.Module):
    hf_to_sglang_mapper = WeightsMapper(
        orig_to_new_substr={
            "model.language_model.": "model.",
            "model.visual": "visual",
        }
    )

    # ... 其他定义 ...

    @classmethod
    def shared_experts_fusion_disable_reason(cls, hf_config, quant_config):
        """
        判断是否应禁用共享专家融合，并返回禁用原因。
        保持与下方门控逻辑同步：若不一致，会丢失共享专家权重并运行未初始化的融合槽位。
        """
        text_config = getattr(hf_config, "text_config", hf_config)
        if not getattr(text_config, "n_shared_experts", None):
            return "No shared experts are defined in the config."
        
        # 新增：针对 ModelOpt FP4 量化的混合精度检查
        if quant_config is not None and quant_config.get_name() == "modelopt_fp4":
            first_sparse_layer = getattr(text_config, "first_k_dense_replace", 0)
            # 遍历所有 MoE 层
            for layer_id in range(first_sparse_layer, text_config.num_hidden_layers):
                moe_prefix = f"model.layers.{layer_id}.mlp"
                # 检查：共享专家被排除（未量化）但路由专家未被排除（已量化）
                if quant_config.is_layer_excluded(
                    f"{moe_prefix}.shared_experts"
                ) and not quant_config.is_layer_excluded(f"{moe_prefix}.experts"):
                    return (
                        "ModelOpt FP4 keeps shared experts unquantized while routed "
                        "experts are quantized."
                    )
        
        if not _is_cuda:
            return "Shared experts fusion currently requires CUDA devices."
        if _device_sm is not None and _device_sm < 80:
            return "Shared experts fusion requires SM80 or newer GPUs."
        if get_parallel().moe_ep_size > 1:
            return (
                "Shared experts fusion is not supported together with expert "
                "parallelism yet."
            )
        if get_moe_a2a_backend().is_deepep():
            return (
                "Shared experts fusion is not supported when Deepep MoE backend "
                "is enabled."
            )
        return None

```

# 评论区精华

1. **关于 RadixArk 兼容性的疑问**：nvpohanh 提问新增的融合禁用逻辑是否也适用于 RadixArk/GLM-5.3-Flash-NVFP4 检查点。作者自己回复确认可以，因为 RadixArk 的排除模式不排除共享专家，因此守卫条件不会触发，融合得以保留。后续提交（d378591c71）明确加入了对此的测试覆盖。
2. **测试文件位置讨论**：mmangkad 建议测试应放在 `test/registered/unit/model_loader/test_modelopt_loader.py`。YAMY1234 反驳了这一建议，指出三个测试中有两个测试的是模型侧的 `shared_experts_fusion_disable_reason` 门控逻辑，而非加载器逻辑，因此 `unit/models/` 是更合适的位置，并引用了其他类似测试（如 `test_qwen3_5_modelopt_fp4.py`）作为先例。最终测试文件位置得以保留。
3. **CI 状态**：评论中提到了 CI 的不稳定性，并确认了相关测试在重新运行后通过。YAMY1234 和 mmangkad 最终都批准了 PR。

- RadixArk 检查点兼容性 (correctness): 逻辑对 RadixArk 变体同样有效，并且在后续提交（d378591c71）中添加了明确的测试用例（test_radixark_uniform_fp4_shared_experts_keep_fusion）来验证这一点。
- 测试文件放置位置 (design): 测试文件保留在 test/registered/unit/models/test_glm5_next_modelopt.py，与被测试的代码（模型定义）位于同一模块层级。

# 风险与影响

- 风险：
 1. **逻辑正确性风险**：新添加的融合禁用条件依赖于对 MoE 层的遍历和排除模式的精确匹配。如果未来模型层结构或量化配置的命名约定发生变化，此处的硬编码前缀（`model.layers.{layer_id}.mlp`）可能需要同步更新，否则可能导致逻辑失效。
 2. **回归风险**：虽然变更范围较小，但修改了 `shared_experts_fusion_disable_reason` 这一关键路径的返回值，影响了所有使用 GLM-5 模型并启用 ModelOpt FP4 量化的部署。测试覆盖了 NVIDIA 和 RadixArk 两个主要变体，降低了回归风险，但可能未涵盖所有潜在的量化配置组合。
 3. **维护性风险**：新逻辑将量化配置的名称（`modelopt_fp4`）硬编码在模型代码中，增加了模型与量化格式之间的耦合。虽然这解决了当前问题，但可能不是最灵活的长期设计。
- 影响：
 1. **用户影响**：直接影响尝试加载 `nvidia/GLM-5.3-Flash-NVFP4` 和类似混合精度 GLM-5 检查点的用户。修复后，这些检查点可以直接加载，无需修改检查点元数据或传递额外参数（如 `--disable-shared-experts-fusion`），显著简化了部署流程。
 2. **系统影响**：增强了 SGLang 对 ModelOpt FP4 量化格式的兼容性处理，特别是混合精度场景。变更集中在模型定义和量化配置交互点，影响范围限于 GLM-5 模型家族和 ModelOpt 量化路径。
 3. **团队影响**：为处理类似混合精度量化问题提供了明确的解决模式和测试范例。但同时，也提醒团队注意模型命名约定与量化配置匹配之间可能出现的不一致。
 - 风险标记：模型 - 量化格式耦合 , 硬编码前缀路径

# 关联脉络

- PR #38725 Relax GSM8K thresholds for the GLM-5.2 DSA-MTP variants: 同属 GLM-5 模型家族，调整了测试阈值以解决 CI 间歇性失败，与本 PR 的测试稳定性主题相关。