执行摘要

• 一句话：将页面对齐逻辑重构为 RadixKey 类方法，统一缓存 API 并提升封装性。
• 推荐动作：值得精读，特别是关注 RadixKey.page_aligned 方法的设计和其在各缓存类中的集成方式，这体现了面向对象封装的优势。同时，提交历史中的返工展示了 API 设计迭代的过程，对理解技术决策有价值。

功能与动机

PR body 指出这是对 #23106 的跟进，旨在清理 API，将页面对齐逻辑从自由函数移到 RadixKey 类中，从而提高封装性和代码一致性。动机是使 'page alignment is now a view on the key, not a free function over raw tokens'。

实现拆解

1. 新增 RadixKey.page_aligned 方法：在 python/sglang/srt/mem_cache/radix_cache.py 的 RadixKey 类中添加 page_aligned 方法，根据 page_size 截断 token_ids 并返回新 RadixKey 实例，保持 O(1) 视图特性。
2. 更新缓存类的 match_prefix 和 insert 方法：在 RadixCache、SWARadixCache、UnifiedRadixCache、HiRadixCache 中，将原有的 inline 页面对齐逻辑替换为调用 key.page_aligned(self.page_size)，并调整 value 截断以确保长度匹配。
3. 删除 page_align_keys 辅助函数：从 radix_cache.py 模块中移除 page_align_keys 函数，并更新相关导入语句，简化模块接口。
4. 同步测试文件：修改所有相关测试文件（如 test_mamba_unittest.py、test_swa_unittest.py 等），更新测试用例以使用新的 API 模式，确保测试覆盖和正确性。
5. 提交历史中的迭代：提交列表显示多次返工（如 revert commits），最终确定 API 设计，体现了开发过程中的权衡和优化。

关键文件：

• python/sglang/srt/mem_cache/radix_cache.py（模块 缓存层；类别 source；类型 core-logic；符号 page_aligned, page_align_keys）: 核心变更所在，定义了 RadixKey 类和新增的 page_aligned 方法，并修改了缓存逻辑入口点。
• python/sglang/srt/mem_cache/swa_radix_cache.py（模块 缓存层；类别 source；类型 core-logic）: SWA 缓存实现，更新了 insert 和 cache_finished_req 等方法以使用 RadixKey.page_aligned，移除对 page_align_keys 的依赖。
• test/registered/unit/mem_cache/test_mamba_unittest.py（模块 测试套件；类别 test；类型 test-coverage）: 测试文件更新示例，反映了新 API 的使用模式，确保测试覆盖和正确性。

关键符号：RadixKey.page_aligned, RadixCache.match_prefix, RadixCache.insert, SWARadixCache.insert, UnifiedRadixCache.match_prefix, HiRadixCache.match_prefix

关键源码片段

python/sglang/srt/mem_cache/radix_cache.py

核心变更所在，定义了 RadixKey 类和新增的 page_aligned 方法，并修改了缓存逻辑入口点。

def page_aligned(self, page_size: int) -> "RadixKey":
    # 如果页面大小为 1，无需对齐，直接返回自身以保持效率。
    if page_size == 1:
        return self
    # 计算页面对齐后的长度：通过整数除法截断到最近的页面边界。
    aligned_len = len(self) // page_size * page_size
    # 使用切片操作返回新的 RadixKey 实例，利用 O(1) 视图避免数据复制。
    return self[:aligned_len]

评论区精华

PR 中没有 review 评论，但提交历史显示多次返工（如 'Revert' commits），表明开发过程中对 API 设计进行了调整。最终决策是将页面对齐逻辑内化到 RadixKey 类中，以提升封装性并简化调用方代码。

• 暂无高价值评论线程

风险与影响

• 风险：回归风险：修改了缓存核心路径的匹配和插入逻辑，若 page_aligned 方法实现错误或调用顺序不当，可能导致缓存命中失败、数据不一致或性能下降。
  兼容性风险：删除了 page_align_keys 函数，任何直接依赖此函数的内部代码将 break，但鉴于它是模块级辅助函数，影响范围可控。
  测试覆盖风险：虽然更新了多个测试文件，但需确保新 API 在所有边缘情况（如 page_size=1、bigram 模式）下正确，否则可能遗漏 bug。

• 影响：对系统：提升缓存模块的代码组织和可维护性，API 更一致；键值长度不变性的显式化有助于预防潜在 bug。
  对用户：无直接影响，因为是内部重构，不改变外部接口。
  对团队：开发者需适应新的 RadixKey API，但长期看减少了代码重复和复杂度。

• 风险标记：核心路径变更, API 破坏性变更, 测试覆盖依赖

关联脉络

• PR #23106 [Perf] Make EAGLE bigram key an O(1) view on RadixKey: 本 PR 是其后续，清理 API 并统一页面对齐逻辑，延续了性能优化和代码简化的方向。