执行摘要

• 一句话：删除 ServerArgs.derive，per-runner 配置改走构造参数
• 推荐动作：值得精读。这个 PR 是配置对象生命周期治理的关键一步，展示了如何通过"删除 API + 收紧测试"来消除一类系统性缺陷。建议重点关注三点：一是 server_args_variant 对 dataclass 字段与类属性双通道校验的设计（为什么允许覆盖 use_mla_backend 方法）；二是 override_server_args 从 derive 迁移到 _apply_fields 时对未知字段 fail-loud 的处理；三是 SKILL.md 中文档与代码同步演进的 review 流程。对从事推理框架配置系统或长期维护公共 API 的团队有参考价值。

功能与动机

PR body 明确指出：after resolution the instance is the read-only record the config bags were projected from. A mutable copy-and-edit API invites publishing stale variants — the defect class this series has been removing. Every value that once needed a variant now travels as a constructor argument to the runner that owns it。也就是说，derive 的存在会让开发者误以为可以将解析后的配置复制一份再修改，从而产生与已发布配置不一致的"过期变体"；这次演进要把所有这种需求收拢为构造参数传递。

实现拆解

按 4 步拆解实现：

1. 删除核心 API（python/sglang/srt/server_args.py）：移除 derive() 方法及 import copy，同步更新 __setattr__ 的报错文案，把"请用 server_args.derive(...) 构建变体"改为"单个 runner 拥有的值作为构造参数传递"。这是整个 PR 的语义核心：配置对象解析后为只读记录，不再提供任何拷贝-编辑入口。
2. 迁移生产调用点（python/sglang/srt/disaggregation/encode_server.py）：MMEncoder.__init__ 新增 gpu_id: Optional[int] = None 参数，self.gpu_id = server_args.base_gpu_id + rank if gpu_id is None else gpu_id；run_dp_worker 不再调用 server_args.derive("encode_server.dp_worker", base_gpu_id=gpu_id, tp_size=1)，而是直接 MMEncoder(server_args, rank=0, gpu_id=gpu_id)。PR body 说明 tp_size=1 原本就是死写（encoder DP 模式在 spawn 前已校验 --tp-size 1），而设备是单实例的放置信息而非配置差异。
3. 改造测试基架（python/sglang/srt/runtime_context.py + python/sglang/test/test_utils.py）：override_server_args.install() 不再借用 derive，改为先从 sglang.srt.arg_groups.overrides 引入 _apply_fields，写入前校验所有非下划线字段必须是 dataclass 字段，未知字段直接 ValueError；同时新增 server_args_variant 工具函数，用 copy.deepcopy 生成测试用配置副本，校验字段集合为 dataclass 字段 ∪ 类属性，从而允许 attention kit 用 fixture 值覆盖 use_mla_backend 方法。
4. 测试与文档联动：删除 test/registered/unit/test_server_args_derive.py；把 test_server_args_no_instance_mutation_entry.py 升级为 test_the_methods_are_gone + test_nothing_derives（用正则扫描整个包，确保没有任何 .derive( 调用残留）；speculative_draft_runner.py 与 test_flashinfer_mla_chunk_metadata.py 改用 server_args_variant；.claude/skills/sglang-runtime-context/SKILL.md 更新为"per-runner 值 = 构造参数"的新语义。

关键文件：

• python/sglang/srt/server_args.py（模块 配置对象；类别 source；类型 core-logic；符号 derive, setattr, _late_resolution）: 核心变更文件：删除 derive() 方法及 copy 导入，更新 __setattr__ 报错文案，是整轮配置治理的语义中枢。
• python/sglang/srt/disaggregation/encode_server.py（模块 编码服务；类别 source；类型 core-logic；符号 MMEncoder.init, run_dp_worker）: 生产代码最后一个 derive 调用点：MMEncoder 新增 gpu_id 构造参数，run_dp_worker 改为直接传参，移除死写 tp_size=1。
• python/sglang/srt/runtime_context.py（模块 运行时上下文；类别 source；类型 dependency-wiring；符号 RuntimeContext.install, _apply_fields）: override_server_args.install() 从 derive 迁移到 _apply_fields，并新增未知字段拒绝逻辑，是测试基架行为收紧的关键点。
• python/sglang/test/test_utils.py（模块 测试工具；类别 test；类型 test-coverage；符号 server_args_variant）: 新增 server_args_variant 测试工具，替代生产代码中的 derive，供测试 double 生成配置副本，校验 dataclass 字段与类属性。
• test/registered/unit/test_server_args_no_instance_mutation_entry.py（模块 配置测试；类别 test；类型 test-coverage；符号 test_the_methods_are_gone, test_nothing_derives）: 约束测试升级：test_the_methods_are_gone 同时断言 override 和 derive 都不存在，新增 test_nothing_derives 用正则扫描全包确保无 .derive( 残留。
• test/registered/unit/test_server_args_derive.py（模块 配置测试；类别 test；类型 deletion；符号 TestServerArgsDerive, test_the_receiver_is_untouched, test_provenance_is_recorded）: 为 derive 编写的整套行为测试（receiver 不变、变体冻结、provenance 记录等）随 API 删除而移除，是变更的正面证据。
• python/sglang/test/kits/attention_unittest/runner_modes/speculative_draft_runner.py（模块 草稿测试；类别 test；类型 test-coverage；符号 _configure_runner_for_eagle_draft, _build_frozen_kv_mtp_fixture）: attention kit 中两个 draft fixture 从 derive 迁移到 server_args_variant，验证了测试工具能覆盖 use_mla_backend 方法 shadow 的场景。
• .claude/skills/sglang-runtime-context/SKILL.md（模块 开发文档；类别 docs；类型 documentation）: 运行时上下文技能文档同步更新，明确"per-runner 值 = 构造参数"而非 config copy；review 讨论的文档一致性问题均在此文件修复。
• test/registered/unit/test_runtime_context.py（模块 运行时测试；类别 test；类型 test-coverage；符号 test_unknown_fields_are_rejected）: test_fields_carry_provenance 改为 test_unknown_fields_are_rejected，验证 override_server_args 现在对未知字段 fail-loud。
• test/registered/attention/unittests/hybrid_linear/test_flashinfer_mla_chunk_metadata.py（模块 注意力测试；类别 test；类型 test-coverage；符号 _ChunkKVMLARunner）: MLA chunk-metadata fixture 改用 server_args_variant，确认无生产代码依赖 derive 后 attention 测试仍通过。

关键符号：ServerArgs.derive, ServerArgs.setattr, MMEncoder.init, run_dp_worker, server_args_variant, RuntimeContext.install, _apply_fields, test_the_methods_are_gone, test_nothing_derives

关键源码片段

python/sglang/srt/server_args.py

核心变更文件：删除 derive() 方法及 copy 导入，更新 __setattr__ 报错文案，是整轮配置治理的语义中枢。

# server_args.py：配置对象在 materialization 之后进入只读状态。
# 本 PR 删除 derive() 拷贝 - 编辑入口，per-runner 的值改为构造参数
# 传递；唯一保留下来的受控写入路径是 late resolution。
def __setattr__(self, name, value):
    # materialization 之后，字段就是已解析的启动配置，是 config bags
    # 投影出的那份只读记录。对已解析配置的改动必须走
    # get_context().override(source, ...) 写 bags；单个 runner 独有的
    # 值则作为构造参数传给它的 owner。
    if (
        not name.startswith("_")
        and getattr(self, "_declarations_materialized", False)
        and not getattr(self, "_internal_write", False)
    ):
        raise AttributeError(
            f"server_args.{name} assigned after resolution; server_args is "
            "read-only -- use get_context().override(source, ...) to change "
            "resolved config; a value one runner owns travels as a "
            "constructor argument."
        )
    object.__setattr__(self, name, value)

python/sglang/srt/disaggregation/encode_server.py

生产代码最后一个 derive 调用点：MMEncoder 新增 gpu_id 构造参数，run_dp_worker 改为直接传参，移除死写 tp_size=1。

# encode_server.py：MMEncoder 的 GPU 放置从“配置拷贝”改为“构造参数”。
class MMEncoder:
    def __init__(
        self,
        server_args: ServerArgs,
        schedule_path=None,
        dist_init_method=None,
        rank: int = 0,
        gpu_id: Optional[int] = None,
    ):
        # gpu_id 把编码器固定到某个设备，而不是 base_gpu_id + rank；
        # 这是 DP launcher 为每个 worker 选择的放置，属于实例自身的
        # 值，不是配置差异，因此作为参数传入。
        ...
        self.gpu_id = server_args.base_gpu_id + rank if gpu_id is None else gpu_id
        ...
​
# run_dp_worker：不再拷贝 - 编辑配置，直接传 gpu_id。
async def run_dp_worker(server_args, dp_rank, gpu_id, dispatch_path, result_path):
    # gpu_id 是父进程 maybe_reindex_device_id 选中的设备：
    # CVD 固定单卡时为 0，否则为绝对 id。rank=0，所以
    # MMEncoder 默认落在 base_gpu_id；显式 gpu_id 覆盖它。
    enc = MMEncoder(
        server_args,
        dist_init_method=f"tcp://127.0.0.1:{get_free_port()}",
        rank=0,
        gpu_id=gpu_id,
    )

python/sglang/test/test_utils.py

新增 server_args_variant 测试工具，替代生产代码中的 derive，供测试 double 生成配置副本，校验 dataclass 字段与类属性。

# test_utils.py：测试替身用来生成修改过的配置副本的工具函数。
# 生产代码不再拷贝 - 编辑配置，但测试 double 仍需要 fixture 变体，
# 所以把 deepcopy 收拢到测试工具里，并保持副本的只读 guard。
def server_args_variant(server_args, **fields):
    """A modified deep copy of a config, for a test double whose fixture
    differs from the (possibly published, read-only) config it starts from.
    The receiver is untouched; the copy keeps its read-only guard.
​
    A name may also shadow a method with a fixture value (the runner kits set
    ``use_mla_backend``, a method ModelRunner itself overwrites at init);
    names that exist nowhere on the class fail loudly."""
    variant = copy.deepcopy(server_args)
    cls = type(variant)
    # 允许写入的集合 = dataclass 字段 ∪ 类属性；这样既能覆盖配置项，
    # 也能用 fixture 值覆盖方法（如 use_mla_backend），完全模拟
    # ModelRunner 在 init 时对实例属性的覆盖行为。
    unknown = {
        name
        for name in fields
        if name not in cls.__dataclass_fields__ and not hasattr(cls, name)
    }
    if unknown:
        raise ValueError(f"unknown ServerArgs field(s): {sorted(unknown)}")
    for name, value in fields.items():
        object.__setattr__(variant, name, value)
    return variant

评论区精华

Review 全部由作者 ch-wan 自审完成，共 4 条评论，集中在 .claude/skills/sglang-runtime-context/SKILL.md 的文档一致性上：

• [nit] "the last two" 指代不清：合并 bullet 后，"最后两个"的指代对象消失。作者在更新栈中修复为显式点名"late resolution or per-runner construction"。
• [suggestion] 未改造段落仍描述旧模式：SKILL.md 中一段未改动的文字仍声称 encode-server DP workers 在各自 config copy 上特化 base_gpu_id——这正是本 PR 删除的模式。作者在 3375d3ae22 中改写为 MMEncoder(gpu_id=...) 实例状态。

• 外部用户质疑 API 稳定性：Issue 评论中 Broduker 提问"why are there several times incompatible API/interface changes in quick succession?"，反映出频繁移除配置 API 对下游开发者的困扰，但 PR 内未回应。

  • SKILL.md 合并 bullet 后 "the last two" 指代不清 (documentation): 在更新栈 3375d3ae22 中修复，改为显式点名 "late resolution or per-runner construction"。
  • SKILL.md 未改动段落仍描述 encode DP worker 在 config copy 上特化 base_gpu_id (documentation): 在 3375d3ae22 中改写为 MMEncoder(gpu_id=...) 实例状态，父进程 base_gpu_id 仅作为种子的描述。
  • 外部用户质疑短时间内多次不兼容 API 变更 (question): PR 内未给出回应；这属于持续演进带来的兼容性摩擦，值得维护团队在发布说明中补充迁移指引。

风险与影响

• 风险：主要风险集中在 4 点：

1. API 移除的兼容性风险：ServerArgs.derive 是公开面，任何未入库的外部代码调用都会直接 AttributeError。库内有 test_nothing_derives 用正则扫描兜底，但库外无法覆盖，Broduker 的评论已反映这一担忧。
2. override_server_args 行为收紧：runtime_context.py 的 install() 现在会拒绝未知字段，原本静默写入的字段会变成 ValueError。如果某些测试或工具依赖旧行为（例如把私有名当普通字段写），会立即失败；这也是 PR 刻意为之的 fail-loud 设计，但需要关注 CI 的遗漏。
3. _apply_fields 副作用差异：derive 用 setattr 循环写字段，而新路径走 _apply_fields；若 _apply_fields 包含额外的校验、缓存种子或类型转换逻辑，行为可能与旧路径不完全一致。PR 已用单元测试覆盖下划线私名种子行为，但仍需留意隐蔽差异。
4. encode_server 部署路径回归：MMEncoder 的 gpu_id 默认值需保持非 DP 路径的 base_gpu_id + rank 语义，改动集中在 self.gpu_id 一行；若 run_dp_worker 的调用方传入的 gpu_id 语义变化（如绝对 id 与相对 id），可能影响多卡编码器放置。
   - 影响：影响范围与程度：

• 对开发者的影响（中高）：配置生命周期模型收敛为"解析后只读 + 构造参数传递"，所有新增 per-runner 配置的开发都必须遵循新范式，直接向 MMEncoder、ModelRunner、TpModelWorker 等构造函数传参，不能再从 config 派生副本。
• 对用户的影响（中低）：本 PR 未改变任何启动参数或运行时行为（除 unknown field 校验），但 ServerArgs.derive 的移除属于公开 API 收缩，依赖该方法的第三方工具会受影响，Broduker 的评论代表了这类外部反馈。
• 对测试体系的影响（高）：测试基架统一收口到 server_args_variant，override_server_args 的字段校验由宽松改为严格，约束 ratchet 从"禁止 override 调用"扩展到"禁止 derive 调用"，未来配置演进会被这些测试强制约束。
• 对文档的影响（中）：runtime-context skill 是 Claude 代码助手的工作文档，更新后能防止后续改动重新引入旧的 config-copy 模式。
• 风险标记：公开 API 移除的兼容性风险, 测试基架行为收紧, 配置只读约束强化, 文档同步滞后

关联脉络

• PR #35200 [AMD] Fix Quark Shared Experts Fusion Gate after load-time-override Removal: 同属 ServerArgs/override 机制演进：该 PR 修复 load-time-override 移除后引入的 gate 回归，与本 PR 删除 derive 一样是在收束配置变异入口，体现同一轮配置治理方向。
• PR #35225 refactor: rename chat response token IDs: 同属 API 契约收敛：对公开字段改名并同步测试，与本 PR 删除公开 API 的节奏一致，共同反映 sglang 正在收紧接口表面的趋势。