执行摘要

• 一句话：移除 decode radix cache 后端白名单，仅拒绝 fake
• 推荐动作：建议合并。这是一个及时的清理性变更，消除过时限制，提升灵活性和正确性。变更简洁，测试充分，只需确认 ascend 后端确实完全支持即可。

功能与动机

在 PR #26288 之后，几乎所有后端都已支持 PD 模式下的 decode radix cache，原有的白名单（nixl、mooncake、mori）已过时。此外，ascend 后端因继承 Mooncake 协议被错误地拒绝，而 mooncake_tcp 则通过重写为 mooncake 后仍然可用。因此需要清理白名单，改为仅拒绝不支持的 fake 后端。

实现拆解

1. 修改核心校验逻辑（python/sglang/srt/arg_groups/pd_disaggregation_hook.py）：将原先的 if backend not in ("nixl", "mooncake", "mori") 替换为 if backend == "fake"，即仅当后端为 fake 时抛出异常。其他后端默认通过。
2. 更新 CLI 帮助文本（python/sglang/srt/server_args.py）：将 --disaggregation-decode-enable-radix-cache 参数的 help 从“Requires ... backend nixl, mooncake or mori”改为“Incompatible with ... --disaggregation-transfer-backend fake”，反映新的校验约束。
3. 调整单元测试（test/registered/unit/server_args/test_server_args.py）：重命名原测试 test_pd_decode_radix_cache_rejects_unknown_backend 为 test_pd_decode_radix_cache_rejects_fake_backend，并修改断言内容以匹配新的异常消息。新增两个测试：test_pd_decode_radix_cache_allows_ascend 验证 ascend 后端被允许；test_pd_decode_radix_cache_allows_mooncake_tcp 验证 mooncake_tcp 被允许且 backend 被重写为 mooncake。

关键文件：

• test/registered/unit/server_args/test_server_args.py（模块 参数校验；类别 test；类型 test-coverage；符号 test_pd_decode_radix_cache_rejects_fake_backend, test_pd_decode_radix_cache_allows_ascend, test_pd_decode_radix_cache_allows_mooncake_tcp）: 测试文件：更新了原有测试并新增 ascend 和 mooncake_tcp 允许测试，验证新的校验行为。
• python/sglang/srt/arg_groups/pd_disaggregation_hook.py（模块 PD 参数校验；类别 source；类型 core-logic）: 核心校验逻辑：移除了后端白名单，改为仅拒绝 fake，简化了条件分支。
• python/sglang/srt/server_args.py（模块 参数定义；类别 source；类型 core-logic）: CLI 帮助文本更新：同步修改参数描述，反映新的约束。

关键符号：handle_pd_disaggregation

关键源码片段

test/registered/unit/server_args/test_server_args.py

测试文件：更新了原有测试并新增 ascend 和 mooncake_tcp 允许测试，验证新的校验行为。

# 测试 decode radix cache 参数校验的新行为
# 旧测试：拒绝 unknown backend，断言包含白名单元组
# 新测试：只拒绝 "fake" 后端，并允许 ascend 和 mooncake_tcp
​
def test_pd_decode_radix_cache_rejects_fake_backend(self):
    with self.assertRaises(ValueError) as context:
        ServerArgs(
            model_path="dummy",
            disaggregation_mode="decode",
            disaggregation_decode_enable_radix_cache=True,
            disaggregation_transfer_backend="fake",
        )
    # 新错误消息：明确指向 fake 后端不兼容
    self.assertIn(
        "--disaggregation-decode-enable-radix-cache is incompatible "
        "with --disaggregation-transfer-backend fake",
        str(context.exception),
    )
​
def test_pd_decode_radix_cache_allows_ascend(self):
    server_args = ServerArgs(
        model_path="dummy",
        disaggregation_mode="decode",
        disaggregation_decode_enable_radix_cache=True,
        disaggregation_transfer_backend="ascend",
    )
    # Ascend 后端应被允许，radix cache 不应被禁用
    self.assertFalse(server_args.disable_radix_cache)
​
def test_pd_decode_radix_cache_allows_mooncake_tcp(self):
    server_args = ServerArgs(
        model_path="dummy",
        disaggregation_mode="decode",
        disaggregation_decode_enable_radix_cache=True,
        disaggregation_transfer_backend="mooncake_tcp",
    )
    # mooncake_tcp 应被允许，且 backend 重写为 mooncake
    self.assertFalse(server_args.disable_radix_cache)
    self.assertEqual(server_args.disaggregation_transfer_backend, "mooncake")

python/sglang/srt/arg_groups/pd_disaggregation_hook.py

核心校验逻辑：移除了后端白名单，改为仅拒绝 fake，简化了条件分支。

# pd_disaggregation_hook.py 中 handle_pd_disaggregation 函数片段
# 变更前：if backend not in ("nixl", "mooncake", "mori"): raise ...
# 变更后：只拒绝 fake 后端，其他全部放行
​
if server_args.disaggregation_mode == "decode":
    if server_args.disaggregation_decode_enable_radix_cache:
        if server_args.enable_hisparse:
            raise ValueError(
                "--disaggregation-decode-enable-radix-cache is incompatible "
                "with --enable-hisparse"
            )
        # 移除了白名单：只拒绝 fake 后端
        if server_args.disaggregation_transfer_backend == "fake":
            raise ValueError(
                "--disaggregation-decode-enable-radix-cache is incompatible "
                "with --disaggregation-transfer-backend fake"
            )
        # 保留其他不兼容检查（speculative decoding、SWA/SSM 等未改动）
        ...

python/sglang/srt/server_args.py

CLI 帮助文本更新：同步修改参数描述，反映新的约束。

# server_args.py 中 add_cli_args 方法片段
parser.add_argument(
    "--disaggregation-decode-enable-radix-cache",
    action="store_true",
    # 旧文本 : "Requires --disaggregation-transfer-backend nixl, mooncake or mori"
    # 新文本 : 删除后端要求，只声明不兼容项
    help="Enable radix cache on decode server (PD mode). Caches KV prefixes to avoid redundant transfers. Incompatible with --enable-hisparse, speculative decoding, and --disaggregation-transfer-backend fake.",
)

评论区精华

PR 无 review 评论，仅作者自测后触发 CI 并确认通过。讨论主要集中在 PR body 中：作者指出 ascend 后端继承 Mooncake 协议且已支持 decode_prefix_len，因此不应被拒绝；mooncake_tcp 通过重写为 mooncake 后也应允许。

• 暂无高价值评论线程

风险与影响

• 风险：风险较低：
  • 回退风险：如果某个后端（如新增的 ascend）实际上不支持 decode radix cache，启用后可能导致错误。但 PR 说明指出 Ascend 已支持 decode_prefix_len，且有单元测试验证。
  • 测试覆盖：新增的 ascend 和 mooncake_tcp 测试确保了基本通过路径，但缺少对其他后端（如 nixl、mori）的显式允许测试。不过它们已在原有白名单中，移除后自然允许。
  • 兼容性：CLI help 文本更新可能影响已有脚本的文档解析，但无功能破坏。
  • 影响：影响范围中等：主要影响 PD 模式下使用 decode radix cache 的用户。启用此功能的用户现在可以使用更多后端（ascend、mooncake_tcp 等），而无需担心白名单限制。对于使用 fake 后端的用户，错误信息更清晰。
  • 风险标记：暂无

关联脉络

• PR #26288 [未提供]: PR body 提到此 PR 之后几乎所有后端都支持 decode radix cache，是本次清理的前提。