执行摘要

• 一句话：新增 FlashInfer NVFP4 4over6 支持
• 推荐动作：此 PR 值得精读，展示了如何集成上游量化新特性，并通过环境变量控制运行时行为。重点关注 environ.py 中环境变量的定义规范和 flashinfer_trtllm.py 中条件量化的实现模式。

功能与动机

为了集成 FlashInfer 的 4over6 NVFP4 特性，允许用户在 per-token 激活量化路径中选择更灵活的缩放因子，从而提高 FP4 量化的模型精度。PR body 关联 flashinfer 的 #3264 和 sglang 的 #22918。

实现拆解

1. 新增环境变量：在 python/sglang/srt/environ.py 的 Envs 类中添加 FLASHINFER_NVFP4_4OVER6 和 FLASHINFER_NVFP4_4OVER6_E4M3_USE_256，均默认为 False，用于控制 FlashInfer NVFP4 4over6 模式。
2. 调整量化逻辑：在 python/sglang/srt/layers/moe/moe_runner/flashinfer_trtllm.py 的 fused_experts_none_to_flashinfer_trtllm_fp4 函数中，当 SGLANG_FLASHINFER_NVFP4_PER_TOKEN_ACTIVATION 启用时，根据新增环境变量决定 e4m3_max 为 448 或 256，进而计算量化缩放因子 1.0 / (e4m3_max * 6.0)。
3. 更新文档：在 docs_new/docs/references/environment_variables.mdx 的环境变量表格中添加新变量的说明，描述其用途和默认值。

关键文件：

• python/sglang/srt/layers/moe/moe_runner/flashinfer_trtllm.py（模块 量化逻辑；类别 source；类型 core-logic）: 核心改动：根据环境变量调整量化缩放参数，实现 4over6 支持。
• python/sglang/srt/environ.py（模块 环境配置；类别 source；类型 configuration）: 定义两个新环境变量，作为功能开关。
• docs_new/docs/references/environment_variables.mdx（模块 文档；类别 other；类型 documentation）: 记录新环境变量的用途和默认值，便于用户查阅。

关键符号：fused_experts_none_to_flashinfer_trtllm_fp4

关键源码片段

python/sglang/srt/layers/moe/moe_runner/flashinfer_trtllm.py

核心改动：根据环境变量调整量化缩放参数，实现 4over6 支持。

# 文件 : python/sglang/srt/layers/moe/moe_runner/flashinfer_trtllm.py
# 函数 : fused_experts_none_to_flashinfer_trtllm_fp4
​
# 在 per-token 激活量化分支中 (if envs.SGLANG_FLASHINFER_NVFP4_PER_TOKEN_ACTIVATION.get()):
e4m3_max = 448.0 # FP4 的默认 E4M3 最大值
# 如果启用了 4over6 模式，并且指定使用 256 作为最大值，则覆盖
if (
    envs.FLASHINFER_NVFP4_4OVER6.get()
    and envs.FLASHINFER_NVFP4_4OVER6_E4M3_USE_256.get()
):
    e4m3_max = 256.0
​
# 使用 e4m3_max 计算全局缩放因子 (1 / (e4m3_max * 6))
hs_fp4_bytes, hs_sf_bytes, per_token_scale = nvfp4_quantize(
    hidden_states,
    1.0 / (e4m3_max * 6.0), # 动态缩放因子
    sfLayout=SfLayout.layout_linear,
    per_token_activation=True,
)

python/sglang/srt/environ.py

定义两个新环境变量，作为功能开关。

# 文件 : python/sglang/srt/environ.py
# 类 : Envs
​
# 在 Flashinfer 相关环境变量区域添加（位于 SGLANG_FLASHINFER_NVFP4_PER_TOKEN_ACTIVATION 之后）：
# SGLang needs to know FlashInfer NVFP4 4over6 config to compute the global scale factor.
FLASHINFER_NVFP4_4OVER6 = EnvBool(False) # 启用 NVFP4 4over6 模式
FLASHINFER_NVFP4_4OVER6_E4M3_USE_256 = EnvBool(False) # 使用 256 作为 E4M3 最大尺度

评论区精华

在 review 中，@b8zhong 建议将来将这些实验性环境变量移到专门的 RL 部分，因为可能不是常规用户使用的。@zianglih 回应称这些变量确实可以用于正常使用以改进 FP4 精度，因此保持当前文档位置。讨论已解决。

• 文档中环境变量的位置 (documentation): 作者认为可用于正常用户以提高精度，因此保持当前文档位置。

风险与影响

• 风险：风险较低。新增的环境变量默认关闭，不影响现有路径。但需注意：
  • 环境变量名称缺少 SGLANG_ 前缀，可能与其他库的环境变量冲突。
  • 未包含单元测试，依赖上游 FlashInfer 的正确性。
  • 仅修改了 per-token 激活量化路径，与 block 量化路径无关。
  • 影响：影响范围小。仅影响启用了 SGLANG_FLASHINFER_NVFP4_PER_TOKEN_ACTIVATION 且设置新环境变量的用户。对其他 MoE 路径和量化方案无影响。无需迁移。
  • 风险标记：无直接测试覆盖, 环境变量无 SGLANG 前缀

关联脉络

• 暂无明显关联 PR