执行摘要

• 一句话：运行时配置调整路由至命名空间bag
• 推荐动作：值得精读，特别是对配置管理和运行时架构感兴趣的工程师。本PR设计决策（命名空间bag、只读启动记录、覆盖写入）为未来配置一致性奠定了基础。但当前实现存在多个未解决的技术债务（draft worker配置丢失、报告不一致），建议后续跟进的PR中修复。对于reviewer，应重点关注Codex提出的P1问题。

功能与动机

PR body指出：为了引入结构化的RuntimeContext配置API，实现resolved config通过domain namespaces读取，ServerArgs成为只读记录。后发布的配置调整如果继续修改ServerArgs，会破坏这个只读模型，导致配置修改路径不统一，可能产生写一个存储读另一个的去同步问题。因此需要将所有运行时配置调整路由到命名空间bag，确保配置修改和读取路径一致。

实现拆解

1. 为ParallelContext添加_config支持和__getattr__方法（runtime_context.py）：ParallelContext新增_config slot用于存放并行配置bag，并实现__getattr__以同名属性方式查询bag中的配置叶子（如pp_max_micro_batch_size）。实时拓扑属性（tp_size等）通过@property优先返回，保证同名字段一致。
2. 在set_server_args中链接并行配置bag（runtime_context.py）：当ServerArgs发布时，_build_config_bags构建所有命名空间bag，同时将parallel bag赋值给self.parallel._config，使ParallelContext可以服务于配置叶子读取。
3. 将_record_kv_cache_dtype改为写入模型bag（model_runner.py）：ModelRunner._record_kv_cache_dtype不再调用declare_load_time_override或直接修改server_args，而是通过get_context().override写入模型bag；configure_kv_cache_dtype中增加kv_cache_dtype_str属性供注意后端直接使用，避免draft worker误读目标bag。
4. 调整get_internal_state和set_internal_state使用context方法（scheduler.py）：get_internal_state改用get_context().resolved_server_args_dict()来融合启动记录和运行时覆盖；set_internal_state改用get_context().override写入bag，同时日志不再输出server_args对象。
5. 修改KV缓存配置相关代码使用get_model().kv_cache_dtype（kv_cache_configurator.py、pool_configurator.py等）：原来直接从server_args.kv_cache_dtype读取的地方改为访问get_model().kv_cache_dtype，确保读到的是解析后的值。同步在多个测试文件中添加setUpModule和测试用例验证新的访问路径。

关键文件：

• python/sglang/srt/runtime_context.py（模块 运行时上下文；类别 source；类型 core-logic；符号 getattr, resolved_server_args_dict）: 核心更改，实现了配置命名空间bag的构建、并行配置的__getattr__路由和resolved_server_args_dict序列化。
• python/sglang/srt/model_executor/model_runner.py（模块 模型运行器；类别 source；类型 data-contract）: 修改了kv_cache_dtype的记录和读取方式，新增kv_cache_dtype_str属性，确保解析后的类型被正确写入bag。
• python/sglang/srt/managers/scheduler.py（模块 调度器；类别 source；类型 dependency-wiring）: 修改了pp_max_micro_batch_size的默认值设置和/set_internal_state后发布报告，改为通过context方法。
• python/sglang/srt/mem_cache/kv_cache_configurator.py（模块 缓存配置；类别 source；类型 dependency-wiring）: 将多个kv_cache_dtype读取点从self.server_args改为get_model().kv_cache_dtype，确保读取解析后的值。
• test/registered/unit/test_runtime_context_override.py（模块 测试；类别 test；类型 test-coverage；符号 test_set_internal_state_fields_reach_parallel_and_spec, test_kv_cache_dtype_override_reaches_get_model_not_server_args）: 添加两个测试用例验证配置覆盖通过bag后能通过get_parallel()和get_model()正确读取，且server_args保持不变。

关键符号：ParallelContext.getattr, ParallelContext.init, RuntimeContext.set_server_args, RuntimeContext.override, RuntimeContext.resolved_server_args_dict, ModelRunner._record_kv_cache_dtype, ModelRunner.configure_kv_cache_dtype, Scheduler.get_internal_state, Scheduler.set_internal_state, KVCacheConfigurator._build_fp4_quant_method, KVCacheConfigurator._build_hybrid_swa_kv_pool, KVCacheConfigurator._build_mha_kv_pool

关键源码片段

python/sglang/srt/runtime_context.py

核心更改，实现了配置命名空间bag的构建、并行配置的__getattr__路由和resolved_server_args_dict序列化。

# 文件 : python/sglang/srt/runtime_context.py
# ParallelContext 现在通过 __getattr__ 从配置 bag 中提供并行配置叶子（如
# pp_max_micro_batch_size），而不改变实时拓扑属性（如 tp_size）的 @property 读取方式。
​
class ParallelContext:
    """Parallel-topology namespace.
​
    Live topology (size / rank / group) is read-through via ``@property`` (the
    canonical getters). Parallel **config** leaves (``nccl_port``,
    ``pp_max_micro_batch_size``, ``enable_dp_attention``, …) come from the
    published ``parallel`` config bag via ``__getattr__``. Where a config leaf
    shares a name with a live property (``tp_size`` …), the property (the live
    fact) wins; the same-name==same-value invariant holds once dist is up.
    """
​
    __slots__ = ("_overrides", "_config")
​
    def __init__(self):
        self._overrides = {}
        self._config = None # parallel config bag, wired at publish
​
    def __getattr__(self, name):
        # Reached only for names that are neither a live @property nor a slot:
        # serve parallel config leaves from the published bag.
        try:
            config = object.__getattribute__(self, "_config")
        except AttributeError:
            config = None
        if config is not None and name in config:
            return getattr(config, name)
        detail = (
            "not a published parallel config leaf"
            if config is not None
            else "config not published"
        )
        raise AttributeError(f"ParallelContext has no {name!r} ({detail})")
​
    # ... 以下为原有 @property 和 override 方法保持不变 ...

python/sglang/srt/model_executor/model_runner.py

修改了kv_cache_dtype的记录和读取方式，新增kv_cache_dtype_str属性，确保解析后的类型被正确写入bag。

# 文件 : python/sglang/srt/model_executor/model_runner.py
# 在配置 kv_cache_dtype 时，将解析后的结果写入模型 bag，保留 server_args 为原始输入。
​
def _record_kv_cache_dtype(self, resolved: str) -> None:
    # 将权重解析后的 kv_cache_dtype 写入配置 bag，使得 get_model().kv_cache_dtype
    # 的读者能看到解析后的值。server_args 保持为未经解析的原始输入记录，
    # configure_kv_cache_dtype 将其作为解析器的输入读取。
    # 对于 draft / mock runner（其 server_args 不是已发布的对象），保持私有 bag 写入。
    from sglang.srt.runtime_context import get_context
​
    if get_context()._server_args is self.server_args:
        get_context().override(
            "ModelRunner.configure_kv_cache_dtype", kv_cache_dtype=resolved
        )
    else:
        self.server_args.override(
            "ModelRunner.configure_kv_cache_dtype", kv_cache_dtype=resolved
        )
​
​
def configure_kv_cache_dtype(self):
    # ...
    resolved_kv_cache_dtype, self.kv_cache_dtype = (
        kv_cache_dtype.configure_kv_cache_dtype(
            # 使用原始 server_args 作为解析器输入，而不是已解析的 bag 值
            server_args_kv_cache_dtype=self.server_args.kv_cache_dtype,
            # ...
        )
    )
    # 为当前 runner 保留自己的 resolved dtype 字符串（目标或 draft）。
    # 注意力后端直接读取该属性而非进程全局的 get_model() bag，
    # 以避免 draft runner 错误地读取目标 runner 的 dtype。
    self.kv_cache_dtype_str = (
        resolved_kv_cache_dtype
        if resolved_kv_cache_dtype is not None
        else self.server_args.kv_cache_dtype
    )
    if resolved_kv_cache_dtype is not None:
        self._record_kv_cache_dtype(resolved_kv_cache_dtype)

python/sglang/srt/managers/scheduler.py

修改了pp_max_micro_batch_size的默认值设置和/set_internal_state后发布报告，改为通过context方法。

# 文件 : python/sglang/srt/managers/scheduler.py
​
# 在初始化目标内存池时，读取并行配置叶子（pp_max_micro_batch_size）
# 现在通过 get_parallel() 而不是 get_server_args()。
if not get_parallel().pp_max_micro_batch_size:
    get_context().override(
        "scheduler.pp_max_micro_batch_size_default",
        pp_max_micro_batch_size=max(
            self.max_running_requests // self.ps.pp_size, 1
        ),
    )
​
# get_internal_state 改为使用解析后的配置（启动记录 + 运行时覆盖）
def get_internal_state(self, recv_req: GetInternalStateReq):
    ret = get_context().resolved_server_args_dict() # 包含所有 override 覆盖
    ret["last_gen_throughput"] = self.metrics_reporter.last_gen_throughput
    # ...
​
# set_internal_state 改为写入 bag 而非直接修改 server_args
if remaining:
    get_context().override(source="update_server_args", **remaining)
    logger.info(f"Config updated via context override: {remaining}")

评论区精华

Review评论中自动化工具Codex提出了多个技术建议，重点关注：

• P1: draft worker的resolved dtype读取：flashattention_backend.py、xpu_backend.py、lightning_backend.py等注意力后端在初始化时仍直接读取model_runner.server_args.kv_cache_dtype，但PR已将该字段改为保留原始输入，导致实际运行时draft worker可能使用错误的缓存类型。建议改为读取model_runner.kv_cache_dtype_str或通过get_model()。
• P1: context重新发布时丢失解析后的kv_cache_dtype：model_runner._record_kv_cache_dtype只写入当前config bag，当draft worker构建时调用set_server_args重建bag，会导致解析后的值丢失，回退到auto，后续池分配使用错误类型。
• P1: DeepSeek注意力层读取全局bag而不是draft runner自身解析值：deepseek_v2.py中使用get_model().kv_cache_dtype，在draft runner上下文中可能读到目标的bag值。
• P2: 并行配置上下文未在restore时清理：_ServerArgsOverride.restore()未清理_config，导致临时配置泄露。

• P2: /server_info仍报告原始启动记录：虽然get_internal_state已改用resolved_server_args_dict，但/server_info端点仍序列化pristine server_args。
  此外，多个测试模块被无条件跳过（pytestmark skip），覆盖范围减少，存在回归风险。

• Draft worker kv_cache_dtype 解析丢失 (correctness): 未在本次PR中解决，需后续跟进。PR作者可能预期当前方案是行为保持的，但Codex指出了潜在问题。

• 注意力后端读取全局bag而不是draft runner的resolved dtype (correctness): 部分后端在PR中已更新为getattr(model_runner, 'kv_cache_dtype_str', ...)（如lightning_backend.py），但flash和xpu仍使用get_model()。需进一步修复。
• DeepSeek注意力使用全局bag (correctness): 未解决，Codex标记为P1。
• 并行配置上下文在restore时未清理 (design): 未解决，需设计修复。
• /server_info端点仍报告原始启动记录 (design): 未解决，需在后续PR中更新/server_info。
• 测试模块被无条件跳过影响覆盖 (testing): 建议在配置API稳定后重新启用。当前PR暂时跳过了这些测试。

风险与影响

• 风险：
  1. 丢失运行时覆盖：在draft worker构建等场景中，如果set_server_args被重新调用，之前通过_record_kv_cache_dtype写入的配置会丢失，因为bag被重建。Codex P1评论指出此问题，当前实现未处理。
  2. draft worker配置错误：注意力后端和模型层（如deepseek_v2.py）在draft worker中读取get_model().kv_cache_dtype可能获得目标进程的bag值，而不是draft runner自身解析的值。PR添加了kv_cache_dtype_str但在多个后端未使用。
  3. 配置上下文泄露：_ServerArgsOverride.restore()未清理ParallelContext._config，可能导致临时配置在退出作用域后仍然有效。
  4. 报告不一致：/server_info端点仍直接序列化server_args，不包含运行时覆盖；get_internal_state已改为使用resolved，产生线上线下不一致。
  5. 测试覆盖缺失：多个测试模块被暂时跳过（pytestmark skip），包括pool_configurator和deepseek_v4_shared_expert_fusion测试，可能掩盖回归。
  6. 并行配置叶子读取路径变化：原来通过get_server_args().pp_max_micro_batch_size读取的地方改为get_parallel().pp_max_micro_batch_size，如果parallel bag未发布（如早期启动阶段），会导致AttributeError而不是返回默认值，可能影响部分检查点。
     - 影响：影响范围：大。本PR改变了整个SGLang运行时的配置读写路径，涉及调度器、模型运行器、KV缓存配置、推测解码、HTTP入口点等多个子系统。对使用ServerArgs.override()或直接修改server_args字段的扩展和自定义脚本有break影响，必须改为通过get_context().override()和命名空间访问器。对最终用户影响较小，因为高层API（启动参数、/set_internal_state）行为保持不变，但内部状态报告（/server_info）需要额外更新才能反映运行时修改。团队需要确保所有现有和未来的配置访问都使用新的访问器模式。
     - 风险标记：draft worker配置丢失, 后端读取全局bag而非本地值, 上下文泄露, 报告不一致, 测试暂时跳过, 并行配置叶子读取可能失败

关联脉络

• PR #31811 config: load-time declarations write the config bags: 本PR stacked on #31811，是系列的一部分，实现后续运行时配置写入bag。
• PR #31814 config: read resolved config via namespace accessors: 系列中的另一个PR，实现了配置读取通过命名空间访问器，与本PR的写入对应。
• PR #31813 runtime_context: record the publishing process role: 为配置发布添加进程角色记录，与本PR的配置发布和执行角色相关。