Skip to content

fix(hicache): TP/PP write-through & load-back consensus (#28429) - #31425

Open
yorsen wants to merge 4 commits into
sgl-project:mainfrom
yorsen:hicache-tp-consensus-pr
Open

yorsen wants to merge 4 commits into
sgl-project:mainfrom
yorsen:hicache-tp-consensus-pr

Conversation

@yorsen

@yorsen yorsen commented Jul 16, 2026

Copy link
Copy Markdown

Motivation

Under TP/PP > 1 with HiCache write_through, the prefill node hangs after a
while and gets killed by the NCCL watchdog (see #28429). Host/device pool
occupancy is per-rank physical state, so a naive per-rank alloc in
write_backup / load_back can succeed on some ranks and fail on others.
That diverges the radix tree across ranks, so the next forward's collectives
mismatch in shape/count and deadlock.

Modifications

  • managers/cache_controller.py: split the controller write into a two-phase
    reserve_write (alloc only) / commit_write (enqueue DMA + ack) /
    abort_write (free reservation); add WriteReservation (msgspec.Struct).
  • mem_cache/hybrid_cache/hybrid_cache_controller.py: mirror the split for the
    indexer/aux pool_transfers.
  • mem_cache/hiradix_cache.py:
    • write_backup: reserve → all_reduce(MIN) consensus → commit on all ranks
      or abort on all ranks (skipping a write-through is harmless).
    • load_back: transactional consensus — load on all ranks or roll back on
      all (free device indices); multi-rank never does the conditional
      evict-and-retry that would re-introduce divergence.
  • Tests: CPU unit tests covering the consensus branches and the evict_host
    retry path (registered via register_cpu_ci).

Accuracy Tests

No change to model outputs; the fix only governs when a rank mutates shared
HiCache/radix-tree state. New CPU unit tests pass (17 cases).

Speed Tests and Profiling

Adds one all_reduce(MIN) (CPU/gloo) per node on the write/load path; no main
NCCL traffic. Multi-GPU (TP≥2) soak validation pending on a GPU host.

Checklist

  • Format code with pre-commit
  • Add unit tests
  • Update documentation (N/A)
  • Accuracy/speed benchmarks (multi-GPU validation pending)
  • Follow SGLang code style

CI States

Latest PR Test (Base): ❌ Run #29743947689
Latest PR Test (Extra): ❌ Run #29743947558

…28429)

HiCache write-through hangs under TP/PP>1: host/device pool occupancy is
per-rank physical state, so a naive per-rank alloc can succeed on some ranks
and fail on others, diverging the radix tree and desyncing the next forward's
collectives.

Split the controller write into a two-phase reserve/commit/abort and reach an
all_reduce(MIN) consensus in write_backup (commit on all ranks or abort on all)
and load_back (load on all ranks or roll back on all; multi-rank never
evict-retries). Adds CPU unit tests covering the consensus branches and the
evict_host retry path.

Closes sgl-project#28429
@gemini-code-assist

Copy link
Copy Markdown
Contributor

Warning

You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!

@github-actions github-actions Bot added the hicache Hierarchical Caching for SGLang label Jul 16, 2026
@yorsen

yorsen commented Jul 16, 2026

Copy link
Copy Markdown
Author

Hi maintainers, this fixes the HiCache TP/PP write-through hang (#28429).
CI is blocked on the permission gate — could someone authorize a run?
@merrymercy @hzh0425 /tag-and-rerun-ci
Happy to address any review feedback. Thanks!

Leoyzen added a commit to Leoyzen/sglang that referenced this pull request Aug 25, 2026
…1425) not active on unified path

Production DSV4-Flash runs UnifiedRadixCache (hybrid_swa), not
HiRadixCache. These two cherry-picks only modified hiradix_cache.py
(+ cache_controller two-phase API consumed solely by hiradix) and thus
never take effect in production, misleading future readers:

- sgl-project#33862 Host mirror release: hiradix-only (unified path has no
  equivalent; SGLANG_HICACHE_MIRROR_RELEASE env was a no-op). Also
  staged 248 lines of unrelated pyproject.toml dep churn.
- sgl-project#31425 TP/PP write-through & load-back consensus: the all_reduce(MIN)
  consensus lives in hiradix_cache.py only; unified's _execute_kv_backup
  calls hybrid_cache_controller.write() and never triggers it.

Keep: sgl-project#30689 (base_prefix_cache InsertParams.is_finished field is a
dependency of the unified is_finished guard) and sgl-project#26837 (metrics, shared).
Keep: 072c953 unified is_finished guard (the actual production fix).

Reverts commits 4266d89 and 29b0753.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

hicache Hierarchical Caching for SGLang

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant