# PR #36974 完整报告

- 仓库：`sgl-project/sglang`
- 标题：config: the dead record parameters go
- 合并时间：2026-08-29 19:20
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/36974

---

# 执行摘要

- 一句话：移除 srt 中 10 个死 server_args 参数及 18 个调用点
- 推荐动作：建议值得精读，尤其是配合系列 PR 一起看：36896 → 36972 → 36973 → 36974 → 36975。值得关注的设计决策是区分接口契约与自由函数死参数的分类方式、迭代到定点的删除策略，以及 ratchet 测试如何主动暴露新产生的死参数。此外，PR body 中关于 create_kt_config_from_server_args 的 AttributeError 分析揭示了裸 except 吞异常的隐患，值得结合 #36921 阅读。

# 功能与动机

PR body 明确指出：一旦函数不再读取 record，它接收的参数就是死重，而一个死的 server_args 参数比噪音更糟糕，因为下一个读者会假定该函数查阅了配置（"a dead `server_args` parameter is worse than noise, because the next reader assumes the function consults the configuration when it does not"）。这是本系列清理的动机：让参数传递如实反映数据流，避免误导。

# 实现拆解

1. **普查与分类**：对全仓库 256 个带 server_args 但从不读取的函数做了普查，区分两类：接口契约型（如 multimodal_gen 流水线阶段的 forward 72/33、component_uses 16/29、create_pipeline_stages 13/31，以及 SRTPlatform.apply_server_args_defaults、CustomSpecAlgo.handle_server_args、StackStrategy.build 家族等，参数属于签名而非函数体）和真正死参数的自由函数；srt/ 内最终确认 10 个死函数。
2. **签名瘦身**：validation_hook.py 中 validate_buckets_rule(server_args, arg_name, buckets_rule) 与 validate_ib_devices(server_args, device_str) 去掉 server_args；cuda_graph_hook.py 中 generate_prefill_cuda_graph_batch_sizes(server_args, max_bs) 变为 (max_bs)；platform_hook.py 中 handle_hardware_runtime_validation 变为无参；hybrid_pool_assembler.py 中 build_kv_only_stack、build_hybrid_swa_stack、build_deepseek_v4_hicache_stack、build_hybrid_mamba_stack、build_hybrid_mamba_swa_stack、build_anchor_sidecar_stack 从 kwargs 移除 server_args。
3. **调用点联动**：parallel_hook.py 的 DP CUDA graph max_bs clamp 与 elastic EP mooncake IB 校验、pd_disaggregation_hook.py 的 encoder 分离 IB 校验等 18 个调用点同步去参；hiradix_cache.py 中 attach_hybrid_minimax_sparse_pool_to_hiradix_cache 及其 DSA 兄弟因只负责转发 record，在转发目标去参后自身也变成死参数持有者，被 ratchet 捕获并清理；model_hook.py、memory_hook.py、pipeline.py 各有 1 行配套调整。
4. **测试联动**：test/registered/cpu/test_server_args_backend.py 删除为 _validate_ib_devices 构造裸 ServerArgs.__new__(ServerArgs) 的代码；test_dead_server_args_parameter_ratchet 扫描 268 个文件返回 0 命中。
5. **验证**：62 形状解析探针与 base 提交逐字节一致；覆盖受影响文件的测试套件与 main 的失败集相同（test_fp8_blockwise_linear_backends 的 5 个失败是 PyTorch 解释器断言，两侧都存在）。

关键文件：
- `python/sglang/srt/arg_groups/validation_hook.py`（模块 参数校验；类别 source；类型 core-logic；符号 validate_buckets_rule, validate_ib_devices）: 本次清理的两个核心校验函数 validate_buckets_rule 与 validate_ib_devices 都定义在这里，签名变化最集中，是后续所有调用点联动的基础。
- `python/sglang/srt/mem_cache/hybrid_cache/hybrid_pool_assembler.py`（模块 混合缓存；类别 source；类型 core-logic；符号 build_kv_only_stack, build_hybrid_swa_stack, build_deepseek_v4_hicache_stack, build_hybrid_mamba_stack）: 6 个 build_*_stack 工厂函数从 kwargs 中删除 server_args，并在 StackStrategy.build 的所有分支调用点去掉对应实参，是本 PR 最大的删除块（-16 行），覆盖 HiCache、Mamba、SWA、anchor sidecar 多种缓存栈构建路径。
- `python/sglang/srt/arg_groups/cuda_graph_hook.py`（模块 CUDA 图；类别 source；类型 core-logic；符号 generate_prefill_cuda_graph_batch_sizes）: generate_prefill_cuda_graph_batch_sizes 是 CUDA graph bucket 生成工具，签名去掉 server_args 后，apply_deepep_adjustments 与 parallel_hook.py 两处调用点同步适配。
- `python/sglang/srt/arg_groups/parallel_hook.py`（模块 并行配置；类别 source；类型 core-logic；符号 handle_data_parallelism, handle_elastic_ep）: 两个调用点联动：DP 调整中 CUDA graph max_bs clamp 调用 generate_prefill_cuda_graph_batch_sizes，elastic EP 的 mooncake IB 校验调用 validate_ib_devices，是签名变化传播的关键路径。
- `python/sglang/srt/arg_groups/platform_hook.py`（模块 平台校验；类别 source；类型 core-logic；符号 handle_hardware_runtime_validation）: handle_hardware_runtime_validation 从带 server_args 变为无参，是 SRT 平台启动时硬件校验的入口，体现本 PR 对平台级 hook 的处理方式。
- `python/sglang/srt/arg_groups/pd_disaggregation_hook.py`（模块 PD 配置；类别 source；类型 core-logic；符号 handle_encoder_disaggregation）: encoder 分离的 IB 设备校验调用点同步适配 validate_ib_devices 新签名，是 disaggregation 路径上唯一需要修改的调用点。
- `python/sglang/srt/mem_cache/hiradix_cache.py`（模块 HiCache；类别 source；类型 core-logic；符号 attach_hybrid_minimax_sparse_pool_to_hiradix_cache）: attach_hybrid_minimax_sparse_pool_to_hiradix_cache 及其 DSA 兄弟因转发目标函数已去参而变成死参数持有者，被 ratchet 测试捕获并清理，体现了迭代到定点的删除策略。
- `test/registered/cpu/test_server_args_backend.py`（模块 后端测试；类别 test；类型 test-coverage）: 测试中为 _validate_ib_devices 构造裸 ServerArgs.__new__(ServerArgs) 的调用因签名变化而被移除，是源码与测试联动的直接体现。

关键符号：validate_buckets_rule, validate_ib_devices, generate_prefill_cuda_graph_batch_sizes, handle_hardware_runtime_validation, build_kv_only_stack, build_hybrid_swa_stack, build_deepseek_v4_hicache_stack, build_hybrid_mamba_stack, build_hybrid_mamba_swa_stack, build_anchor_sidecar_stack, attach_hybrid_minimax_sparse_pool_to_hiradix_cache


# 评论区精华

本 PR 没有人工 review 评论，唯一的外部评论来自 chatgpt-codex-connector bot 的自动 Codex review 摘要，显示审查已完成但没有提出具体问题。PR body 自己给出了审查引导："Pure deletion; the only thing to check is the interface/free-function split above"，即审查重点在于区分接口契约型参数（保留）与自由函数死参数（删除）。另外，PR body 披露了一个重要发现：create_kt_config_from_server_args 调用 server_args.get_hf_config()，但该方法不存在，调用被裸 except Exception: pass 吞掉，num_layers 恒为 None，相关分支从未触发；该问题已拆到 #36921 处理。

- 未死的第十一个候选揭示隐藏 bug (correctness): 该函数不是死参数，因此不在本 PR 删除范围，已拆分为 #36921 单独修复。
- 唯一的外部评论是 Codex 自动审查 (other): 无公开争议，PR 以纯删除方式合并。

# 风险与影响

- 风险：风险集中在签名变更的联动上：validate_ib_devices、generate_prefill_cuda_graph_batch_sizes、validate_buckets_rule 都是 arg_groups 内部的 hook 函数，仓库内所有调用点已同步修改且 ratchet 全仓 0 命中，内部回归风险很低；但如果仓库外的下游代码直接导入这些内部函数并传旧签名，会因参数不匹配报错。handle_hardware_runtime_validation 变为无参后，pipeline.py 中的注册调用必须同步匹配，已在本 PR 完成。运行时行为无变化，因为被删除参数原本就没有被读取；隐藏的 AttributeError 问题不影响本 PR，已移交 #36921 修复。
- 影响：从用户视角没有任何行为变化；从开发者视角，server_args 的传递链更干净，消除了未来读者误判配置依赖的认知负担；从团队视角，ratchet 测试（test_dead_server_args_parameter_ratchet）为后续配置重构提供了自动化防线。对缓存栈构建路径（HiCache、Mamba、SWA、anchor sidecar）的函数签名有一定影响，但都在仓库内部闭环。总体影响面小但具有样板价值。
- 风险标记：hook 签名变更 , 纯删除零行为变更 , 外部扩展兼容风险 , ratchet 防回归

# 关联脉络

- PR #36975 config: the lazy imports that buy nothing become eager: 同一系列中的下一个 PR，延续 config/import 清理，修改范围与 arg_groups/model_hook 等文件高度重叠。
- PR #36834 [HiCache] buffer mode: decide staged-fetch fate against the live tree: 同一 HiCache 子系统（hybrid_cache / unified_radix_cache）的近期改动，与 #36974 对缓存栈构建路径的清理有共同背景。
- PR #36958 [misc] Keep `req.kv` non-optional and key KV ownership on `req_pool_idx`: 同为 SRT KV 缓存 / 调度重构脉络，触及 mem_cache 与 pipeline 等文件，体现近期对缓存持有权与参数语义的治理方向。