# PR #26678 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[mem_cache][3/N] refactor: move HiSparse allocators to allocator/hisparse.py
- 合并时间：2026-06-11 19:50
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/26678

---

# 执行摘要

- 一句话：将 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: 修复了分配器释放映射问题，与本次移动的分配器属于同一子系统。