# PR #28238 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[PD] Remove outdated backend whitelist for decode radix cache
- 合并时间：2026-06-15 22:36
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/28238

---

# 执行摘要

- 一句话：移除 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 允许测试，验证新的校验行为。

```python
# 测试 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，简化了条件分支。

```python
# 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 帮助文本更新：同步修改参数描述，反映新的约束。

```python
# 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，是本次清理的前提。