执行摘要

• 一句话：三个配置读取器改用 bag，消除 record 残留
• 推荐动作：该 PR 值得精读，尤其适合理解 SGLang 配置解析与 publish 机制，以及进行大规模重构时的渐进式策略。关注点：如何判断读取器是否在 publish 之后运行、如何通过测试保障迁移安全。可作为配置系统重构的参考模式。

功能与动机

PR body 明确指出：pool_configurator、mem_cache/registry 和 unified_radix_cache 读取的是传入的 ServerArgs 上解析后的配置，但 record 保存的是操作者的原始输入，因此读到的是解析前的值，而 bag 才是解析后的值。这个改动是逐步淘汰 override_server_args 的 write-through 机制的第一步，通过实验发现不能一次性迁移所有 94 处读取，否则会产生大量测试失败。

实现拆解

1. 定位读取点：在 pool_configurator.py、mem_cache/registry.py、unified_radix_cache.py 中识别从 server_args 读取解析后配置的字段，共 8 处。
2. 迁移到对应 bag：
   • max_total_tokens 和 page_size 改用 get_schedule()。
   • enable_hisparse、radix_cache_backend、hicache_host_memory_mode、enable_session_radix_cache 改用 get_memory()。
   • enable_streaming_session 改用 get_serving()。
   • extra_metric_labels 改用 get_observability()。
3. 保留 max_speculative_num_draft_tokens：因为它是派生属性，没有对应 bag。
4. 更新测试：test_pool_configurator.py 中从 record 读取的 page_size 改为从 get_schedule() 读取，并添加必要的导入。
5. 验证：运行 2171 个测试通过，159 个注册测试与 base 有相同的失败集合，且每步都伴随测试。

关键文件：

• python/sglang/srt/mem_cache/registry.py（模块 注册中心；类别 source；类型 dependency-wiring；符号 create_tree_cache）: 核心的缓存后端选择逻辑，从 server_args 读取 radix_cache_backend、hicache_host_memory_mode 等，迁移到 get_memory() 和 get_serving()，影响缓存初始化路径。
• python/sglang/srt/mem_cache/unified_radix_cache.py（模块 缓存核心；类别 source；类型 dependency-wiring；符号 init_hicache）: HiCache 初始化时读取 hicache_host_memory_mode 和 extra_metric_labels，迁移到 get_memory() 和 get_observability()，涉及缓存核心逻辑。
• python/sglang/srt/model_executor/pool_configurator.py（模块 池配置器；类别 source；类型 data-contract；符号 DefaultPoolConfigurator.init, DeepSeekV4TokenToKVPoolConfigurator.init）: 内存池配置核心，读取 max_total_tokens 和 enable_hisparse，迁移到 get_schedule() 和 get_memory()，影响内存池大小计算。
• test/registered/unit/model_executor/test_pool_configurator.py（模块 测试；类别 test；类型 test-coverage；符号 _run, test_constraint_memory_within_budget, _tokens）: 同步更新测试，将 page_size 读取从 record 改为 get_schedule()，确保可发布配置。

关键符号：create_tree_cache, init_hicache, DefaultPoolConfigurator.init, DeepSeekV4TokenToKVPoolConfigurator.init, calculate_pool_sizes

关键源码片段

python/sglang/srt/mem_cache/registry.py

核心的缓存后端选择逻辑，从 server_args 读取 radix_cache_backend、hicache_host_memory_mode 等，迁移到 get_memory() 和 get_serving()，影响缓存初始化路径。

def create_tree_cache(ctx: TreeCacheBuildContext) -> BasePrefixCache:
    """Route to the matching factory to construct Radix Cache."""
    # 从解析后的内存配置中读取后端名称，而非原始 record
    name = get_memory().radix_cache_backend
    if name:
        factory = get_radix_cache_factory(name)
        if factory is None:
            raise ValueError(
                f"--radix-cache-backend={name!r} is not registered. "
                f"Registered backends: {registered_radix_cache_backends()}."
            )
        cache = factory(ctx)
        source = f"registered({name!r})"
    else:
        cache = default_radix_cache_factory(ctx)
        source = "default"
​
    # 读取 HiCache 相关配置也统一走 bag
    if (
        get_memory().enable_hierarchical_cache
        and get_memory().hicache_host_memory_mode == "buffer_only"
    ):
        ...
    if get_memory().enable_session_radix_cache and not getattr(
        cache, "enable_session_radix_cache", False
    ):
        ...
    if (
        get_serving().enable_streaming_session
        and not cache.supports_streaming_session()
    ):
        ...

python/sglang/srt/mem_cache/unified_radix_cache.py

HiCache 初始化时读取 hicache_host_memory_mode 和 extra_metric_labels，迁移到 get_memory() 和 get_observability()，涉及缓存核心逻辑。

def init_hicache(self, server_args: ServerArgs, params: CacheInitParams) -> None:
    """Initialize HiCache infrastructure."""
    # 从解析后的内存配置中读取 host 内存模式，而非 record
    self.host_memory_mode = get_memory().hicache_host_memory_mode
    if self.host_memory_mode == "buffer_only":
        ...
    # 监控标签从 observability bag 读取
    self.extra_metric_labels = get_observability().extra_metric_labels
    ...

评论区精华

该 PR 没有 review 评论，但 PR body 中阐述了设计决策：不能机械地一次性迁移所有 94 处读取，因为许多单元测试只传入 record 从未 publish，且 HttpServerEngineAdapter 在调用方进程构造 ServerArgs 也不 publish。因此采用逐个模块推进的方式，每个模块都伴随测试验证，确保不发生回归。此外，作者强调迁移的可行性取决于读取器进程是否 publish，而非字段是否映射到 namespace。

• 暂无高价值评论线程

风险与影响

• 风险：风险主要在于迁移后如果读取器运行在 publish 之前，会读取到未初始化的 bag 值，导致错误配置或运行时异常。pool_configurator 是模型执行的核心，读取 max_total_tokens 和 enable_hisparse 等关键配置，若迁移顺序不当可能影响内存池配置，导致 OOM 或性能退化。registry.py 的 radix_cache_backend 和 hicache_host_memory_mode 影响缓存后端选择，错误值可能导致不兼容或崩溃。unified_radix_cache.py 的 hicache_host_memory_mode 影响 HiCache 初始化，extra_metric_labels 影响监控。需确保这些读取器均在对应的 publish 之后执行。
• 影响：影响范围限于配置读取路径，用户无感知，但为后续淘汰 override_server_args 的 write-through 机制铺平道路，降低配置系统复杂度，提升可维护性。影响程度中等偏低，因为改动较小且测试覆盖充分。对团队而言，明确了配置读取的正确模式，后续模块可参照此模式迁移。
• 风险标记：读取顺序依赖, 核心路径变更, 测试覆盖有限

关联脉络

• PR #36738 [HiCache] Fence load-back behind the forward stream: 同为 HiCache 相关的调度与缓存一致性变更，涉及 cache_controller 与 scheduler，本 PR 的 registry.py 与 unified_radix_cache.py 也属于 HiCache 配置读取路径。
• PR #36382 [HiCache] Key storage prefetch by the request namespace: 修改了 unified_radix_cache.py 和 registry.py，与本 PR 在缓存配置读取上有重叠，且都涉及 HiCache 的初始化参数。
• PR #36792 config: the forwarding slots go; the dispatcher calls the family directly: 与本 PR 同属配置机制重构的系列工作，PR#36792 已移除 ServerArgs 转发槽位，本 PR 继续迁移读取器，两者共同推进配置系统简化。