执行摘要

• 一句话：将 HiSparse 分配器类移至独立文件
• 推荐动作：本 PR 适合作为代码重构的范例阅读：如何在不改变行为的前提下通过机械移动拆分文件，并利用 git blame -C -C -C 保持代码历史可追溯。团队应关注 codex bot 提出的导入风险，但鉴于当前 HiSparse 的使用场景受限，该决策可接受。

功能与动机

这是 issue #25371 (parent #24335) allocator-promotion 系列的第 3 个 PR。原文件 hisparse_memory_pool.py 同时包含设备池、主机池和分配器，职责过重。将分配器类抽离到 allocator/hisparse.py 后，剩余的设备池和主机池将在后续重构中分别迁入 pool/ 和 pool_host/。

实现拆解

1. 创建新文件 python/sglang/srt/mem_cache/allocator/hisparse.py：从 hisparse_memory_pool.py 拷贝 HiSparseTokenToKVPoolAllocator 和 DeepSeekV4HiSparseTokenToKVPoolAllocator 两个类体，仅保留必要的导入（base allocator、paged allocator、deepseek_v4 pools、kvcacheio shim 以及回引的 HiSparseDSATokenToKVPool）。类体完全不变。
2. 清理旧文件：从 hisparse_memory_pool.py 中删除这两个类及其相关导入，原有设备池 HiSparseDSATokenToKVPool 和主机池 DeepSeekV4SingleKVPoolHost 继续留在原文件等待后续迁移。
3. 更新全部导入点：修改 model_runner_kv_cache_mixin.py、hisparse_coordinator.py、schedule_policy.py、chunk_cache.py、test_hisparse_unit.py 等 5 个文件中的导入语句，将 from sglang.srt.mem_cache.hisparse_memory_pool import DeepSeekV4HiSparseTokenToKVPoolAllocator, HiSparseTokenToKVPoolAllocator 改为 from sglang.srt.mem_cache.allocator.hisparse import ...。同时保持 HiSparseDSATokenToKVPool 仍从原文件导入。
4. 新增 allocator/__init__.py：在 allocator/ 包中创建 __init__.py，重新导出新分离的分配器类，使得 from sglang.srt.mem_cache.allocator import ... 语法仍然有效（原有 base.py、paged.py 的导入保持不变）。
5. 测试调整：更新测试文件 test_hisparse_unit.py 的导入路径，确保 CI 通过。

关键文件：

• python/sglang/srt/mem_cache/allocator/hisparse.py（模块 内存缓存；类别 source；类型 dependency-wiring；符号 HiSparseTokenToKVPoolAllocator, DeepSeekV4HiSparseTokenToKVPoolAllocator, init, size_full）: 核心新增文件，包含两个分配器类的全部逻辑，是本次重构的目标文件。
• python/sglang/srt/mem_cache/hisparse_memory_pool.py（模块 内存缓存；类别 source；类型 dependency-wiring；符号 HiSparseTokenToKVPoolAllocator, DeepSeekV4HiSparseTokenToKVPoolAllocator, init, size_full）: 被删除两个分配器类的源文件，剩余设备池和主机池类等待后续迁移。
• python/sglang/srt/model_executor/model_runner_kv_cache_mixin.py（模块 模型执行器；类别 source；类型 data-contract）: 运行器关键导入迁移点，影响所有模型初始化时 KV 缓存分配器的创建。
• python/sglang/srt/managers/hisparse_coordinator.py（模块 调度器；类别 source；类型 dependency-wiring）: HiSparse 协调器是使用分配器的核心模块，导入路径必须同步更新。
• python/sglang/srt/managers/schedule_policy.py（模块 调度器；类别 source；类型 dependency-wiring）: 调度策略中引用了 DeepSeekV4HiSparseTokenToKVPoolAllocator，需要更新导入。
• python/sglang/srt/mem_cache/chunk_cache.py（模块 内存缓存；类别 source；类型 dependency-wiring）: chunk_cache 引用了 DeepSeekV4HiSparseTokenToKVPoolAllocator，需要更新导入。
• test/registered/unit/managers/test_hisparse_unit.py（模块 测试；类别 test；类型 test-coverage）: 单元测试需要导入分配器类，测试通过验证了移动的正确性。

关键符号：HiSparseTokenToKVPoolAllocator, DeepSeekV4HiSparseTokenToKVPoolAllocator, init, size_full, size, available_size, get_kvcache, alloc, alloc_logical_only

评论区精华

唯一的技术评论来自 chatgpt-codex-connector[bot] 的 P2 建议：指出 allocator/__init__.py 直接把 hisparse 模块导入到包级别，会导致所有 allocator 的调用者（即使只需要 base allocator）都会加载 allocator.hisparse 及其依赖的 sgl_kernel.kvcacheio；在 CUDA/ROCm 环境之外该依赖可能引发早期加载异常。作者未回复，但两位评审者仍批准了 PR。这意味着团队可能认为该影响目前可控（因为 HiSparse 仅用于支持 CUDA/ROCm 的场景），或计划后续再优化导入路径。

• allocator/init.py 中直接导入 hisparse 模块的副作用 (design): 作者未直接回复，但两位 reviewers（xiezhq-hermann, ispobock）均 approve 了 PR，表明团队认为在当前使用场景下（HiSparse 仅用于 CUDA/ROCm）该风险可接受，或者后续再优化。

风险与影响

• 风险：低风险。变更仅为机械移动，类体和行为完全不变。主要风险点：
  • 导入副作用（来自 review 中提到的 __init__.py 过早加载）：在非 CUDA/ROCm 平台上引入 sgl_kernel.kvcacheio 可能引起启动时 ImportError，但实际 HiSparse 分配器只能在这些平台上使用，且原有代码已有条件导入，新文件通过直接导入去掉了条件判断；如果调度器或其他模块在非 HiSparse 场景下也经过 allocator 入口，可能导致不必要的异常。
  • 遗漏导入更新：共修改 7 个文件，若某处仍有旧的导入路径，编译不会报错但会错过更新，导致运行时引用旧文件的分配器（已删除）。但测试已覆盖关键路径。
  • git blame 可追溯性：作者通过 git blame -C -C -C 验证了 99.4% 的行可追溯到原始提交，剩余 3 行是新的导入头部，可以放心追溯。
  • 影响：影响范围：仅影响 static cache 模块的代码组织，运行时无行为变更。对开发者影响：需要学习新的分配器路径。对系统无影响。
  • 风险标记：导入路径变更, 依赖副作用

关联脉络

• PR #27759 [UnifiedTree]: HybridModel launches HiCache via UnifiedTree by default.: 同属于 mem_cache 重构系列，涉及 HiCache 与 UnifiedTree 集成。
• PR #27779 Fix paged SWA free mapping cleanup: 修复了分配器释放映射问题，与本次移动的分配器属于同一子系统。