# PR #34472 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[Misc] Sanitize the structure of environ.py
- 合并时间：2026-08-12 07:31
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/34472

---

# 执行摘要

- 一句话：重排 environ.py 环境变量分组，清理废弃开关
- 推荐动作：值得快速浏览 diff，学习如何组织超大型 Envs 类（按功能主题分区、删除死开关）；不适合精读，因无算法和设计决策。建议合并后 grep 全仓库确认被删键无残留引用，并关注 CI 失败是否已另行处理。

# 功能与动机

PR body 只有贡献模板，未填写实质动机。从标题 '[Misc] Sanitize the structure of environ.py' 和 diff 推断：environ.py 长期作为全局环境变量的唯一汇聚点，近期不断追加开关（HiSparse、ZMQ、K3、DSA Q8KV8 等），区块顺序混乱、主题交错，需要按功能主题分区并删除已废弃或已迁移的声明，提升可维护性与可检索性。

# 实现拆解

1. **清理废弃 / 已迁移声明**：在 Envs 类中删除 DSA Backend 簇（SGLANG_DSA_FUSE_TOPK、SGLANG_DSA_TOPK_FLASHINFER_DETERMINISTIC、SGLANG_ENABLE_DSA_Q8KV8_BORN_FP8_Q、SGLANG_OPT_Q8KV8_QPREP_VARIANT 等）、TRT-LLM-gen SiTU（SGLANG_TRTLLM_GEN_MOE_CUBIN_POOL）、K3 系列（SGLANG_K3_AR_FUSION、SGLANG_K3_SP_COLLECTIVE、SGLANG_K3_SP_ATTN_RES、SGLANG_K3_GEMM_AR、SGLANG_K3_FUSED_FRONT）、SGLANG_M3_ALLOW_CUSTOM_AR、SGLANG_KIMI_K3_VIT_CUDA_GRAPH_* 等约 50 行声明。
2. **新增主题区块**：在 HiSparse 之后插入 Unified radix cache（SGLANG_OPT_UNIFIED_CACHE_FREE_OUT_OF_WINDOW_SLOTS）、DeepGemm Mega MoE（SGLANG_OPT_USE_DEEPGEMM_MEGA_MOE、FP4/MXF4 子开关）、TopK（SGLANG_OPT_USE_FUSED_HASH_TOPK、SGLANG_OPT_USE_JIT_KERNEL_FUSED_TOPK、SGLANG_OPT_USE_JIT_KERNEL_GROUPED_TOPK、SGLANG_OPT_USE_TOPK_V2）三个区块。
3. **归拢既有配置**：将 DeepSeek V4、CUDA kernels、SWA radix cache、GEMM/kernel fusion、TokenizerManager、ZBAL 等原本散落的变量整理为独立注释块，使文件结构清晰一致。
4. **语义保持**：所有保留的 EnvBool / EnvInt / EnvStr 默认值不变，Envs 类在 import 时求值的语义未变，重排不引入行为变化。
5. **配套缺失**：无测试、文档、配置改动；PR 页显示最新 PR Test 与 PR Test Extra 均为失败状态，合并未附带绿色 CI。

关键文件：
- `python/sglang/srt/environ.py`（模块 环境配置；类别 source；类型 configuration；符号 Envs）: 唯一变更文件，Envs 类整体结构重排：删除 DSA/K3/Kimi-K3 ViT 等废弃开关，新增 Unified radix cache、DeepGemm Mega MoE、TopK 区块，并归拢 DSV4、CUDA kernels 等配置，是全仓库环境变量的唯一汇聚点。

关键符号：未识别

## 关键源码片段

### `python/sglang/srt/environ.py`

唯一变更文件，Envs 类整体结构重排：删除 DSA/K3/Kimi-K3 ViT 等废弃开关，新增 Unified radix cache、DeepGemm Mega MoE、TopK 区块，并归拢 DSV4、CUDA kernels 等配置，是全仓库环境变量的唯一汇聚点。

```python
# python/sglang/srt/environ.py —— PR #34472 重排后的 Envs 类局部示意
# 本次变更把散落各处的开关按功能主题聚成区块，以下为新增 / 重排的代表片段。

class Envs:
    # ---------- Unified radix cache ----------
    # 统一哈希缓存回收窗口外空闲 slot 的开关，配合 Mamba 前缀复用使用。
    SGLANG_OPT_UNIFIED_CACHE_FREE_OUT_OF_WINDOW_SLOTS = EnvBool(False)

    # ---------- DeepGemm Mega MoE ----------
    # Mega-MoE 主开关；默认以 FP8 E4M3 打包 x slot。
    SGLANG_OPT_USE_DEEPGEMM_MEGA_MOE = EnvBool(False)
    SGLANG_OPT_DEEPGEMM_MEGA_MOE_NUM_MAX_TOKENS_PER_RANK = EnvInt(8192)
    # 切换为 FP4 E2M1 打包，减半 symm-buffer 占用，
    # 同时导出 DG_USE_FP4_ACTS=1 让 DeepGEMM 侧感知 FP4 布局。
    SGLANG_OPT_DEEPGEMM_MEGA_MOE_USE_FP4_ACTS = EnvBool(False)
    # 将 L1+L2 mainloop 切换为 dense MXF4 (K=64)，
    # 仅在启用 FP4 acts 时生效，DeepGEMM 主机侧会校验该组合。
    SGLANG_OPT_DEEPGEMM_MEGA_MOE_USE_MXF4_KIND = EnvBool(False)

    # ---------- TopK ----------
    # 统一 fused TopK 入口：hash / JIT kernel 默认打开，
    # grouped TopK 仍走 flashinfer 生产路径，Triton 路由作为逃生舱。
    SGLANG_OPT_USE_FUSED_HASH_TOPK = EnvBool(True)
    SGLANG_OPT_USE_JIT_KERNEL_FUSED_TOPK = EnvBool(True)
    SGLANG_OPT_USE_JIT_KERNEL_GROUPED_TOPK = EnvBool(False)
    SGLANG_OPT_USE_TOPK_V2 = EnvBool(True)

```

# 评论区精华

本 PR 没有 review 评论与讨论线程，由作者 Fridge003 自行合并（self-merge），因此没有公开的设计权衡交锋可供提炼。

- 暂无高价值评论线程

# 风险与影响

- 风险：删除约 180 行声明可能遗留未被清理的引用点：若 sglang/srt 中仍有模块读取 environ.SGLANG_K3_AR_FUSION、SGLANG_DSA_TOPK_BROADCAST 等被删键，会触发 AttributeError。environ.py 是全局配置汇聚点，影响面覆盖所有后端与模型。该 PR 无测试配套，且 PR 页显示 CI（PR Test 与 PR Test Extra）均为失败状态，回归风险未通过 CI 充分验证。重排本身不改变保留变量默认值，核心风险集中在被删除的配置键。
- 影响：对用户：保留的开关默认值不变，运行时行为不变；被删除的开关多为内部调试或性能实验开关，若外部使用者依赖其中某个键（如 SGLANG_K3_AR_FUSION）则会出现配置失效。对系统：环境变量加载路径无变化，正常启动不受影响。对团队：环境变量查找、审查与新增更直观，后续扩展配置时有明确归属区块，降低误用与重复定义的概率。
- 风险标记：无测试覆盖 , 删除配置键兼容性风险 , CI 失败未处理 , 全局配置汇聚点

# 关联脉络

- PR #34450 Raise PD zmq per-context socket cap via SGLANG_DISAGGREGATION_ZMQ_MAX_SOCKETS: 同文件 python/sglang/srt/environ.py 的近期改动，说明 environ.py 仍在持续增长，本次 PR 是对该文件膨胀后的结构整理。
- PR #34329 HiSparse: shared-index (IndexShare) plan-then-IO swap-in prefetch: 向 environ.py 注入 HiSparse 预取开关，本 PR 保留了 HiSparse 段并调整其位置。
- PR #33075 [Fix] Allow flashinfer_sparse_mla DSA backend for HiSparse on SM120 FP8 KV: DSA 后端配置与 HiSparse 相关，本 PR 将 environ.py 中 DSA 老开关整体移除，DSA 配置重心可能已转向 arg_groups 体系。
- PR #30700 [NVIDIA] Add flashinfer MNNVL backend for allreduce only: K3 AR fusion 相关功能背景，本 PR 删除了 SGLANG_K3_AR_FUSION 等声明，K3 相关配置路径正在收敛。