Skip to content

server: persist slot checkpoints to .ckpt sidecar (LSCKPT2)#24028

Open
LuminaNAO wants to merge 1 commit into
ggml-org:masterfrom
LuminaNAO:pr/slot-checkpoint-sidecar
Open

server: persist slot checkpoints to .ckpt sidecar (LSCKPT2)#24028
LuminaNAO wants to merge 1 commit into
ggml-org:masterfrom
LuminaNAO:pr/slot-checkpoint-sidecar

Conversation

@LuminaNAO

Copy link
Copy Markdown

Problem

llama_state_seq_save_file / llama_state_seq_load_file persist the active slot KV state, but NOT the prompt-checkpoint list — which is exactly what hybrid-arch models need to avoid cold prefill on prompt switching.

On UMA systems (AMD Strix Halo, Apple Silicon, DGX Spark) where RAM = VRAM, this means checkpoint caching actively competes with model weights and KV cache for the same limited resource.

Solution

Extends both save/restore call sites with a .ckpt sidecar that serializes the std::list<common_prompt_checkpoint> alongside the main slot blob.

Sidecar format (LSCKPT2)

magic[8]    = "LSCKPT2\0"
count       : uint64                    (number of checkpoints)
for each checkpoint:
  pos_min   : int32  (llama_pos)
  pos_max   : int32
  n_tokens  : int64
  size_tgt  : uint64
  size_dft  : uint64                    (zero if no draft / no MTP)
  bytes[size_tgt]
  bytes[size_dft]

Benefits

  • Hybrid/recurrent models (Qwen 3.5, etc.) avoid cold prefill on prompt switch because checkpoint lists survive slot save/restore cycles
  • UMA systems eliminate the trade-off between checkpoint count and available context/layers
  • Multi-user / multi-agent setups benefit from near-unlimited checkpoint persistence without consuming unified memory

Testing

Tested on AMD Strix Halo (Ryzen AI Max+ 395, 128 GB unified memory) with Qwen3.5-122B-A10B (Q5_K_XL, ~85 GB) at 220k context via Vulkan backend.


Closes #20697

Note: This is complementary to PR #17428 (which creates checkpoints during prompt processing). This PR persists existing checkpoints to disk — the two features work together.

llama_state_seq_save_file / llama_state_seq_load_file persist the active
slot KV state, but NOT the prompt-checkpoint list — which is exactly what
hybrid-arch models need to avoid cold prefill on prompt switching.

This extends both call sites with a .ckpt sidecar that serializes the
std::list<common_prompt_checkpoint> alongside the main slot blob.

Sidecar format (LSCKPT2):
  magic[8]    = "LSCKPT2\0"
  count       : uint64                    (number of checkpoints)
  for each checkpoint:
    pos_min   : int32  (llama_pos)
    pos_max   : int32
    n_tokens  : int64
    size_tgt  : uint64
    size_dft  : uint64                    (zero if no draft / no MTP)
    bytes[size_tgt]
    bytes[size_dft]

Benefits:
- Hybrid/recurrent models (Qwen 3.5, etc.) avoid cold prefill on prompt
  switch because checkpoint lists survive slot save/restore cycles.
- On UMA systems (AMD Strix Halo, Apple Silicon, DGX Spark) where RAM =
  VRAM, this eliminates the trade-off between checkpoint count and
  available context/layers.
- Multi-user / multi-agent setups benefit from near-unlimited checkpoint
  persistence without consuming unified memory.

Closes ggml-org#20697
@LuminaNAO LuminaNAO requested a review from a team as a code owner June 2, 2026 15:08
@ggml-gh-bot

ggml-gh-bot Bot commented Jun 2, 2026

Copy link
Copy Markdown

Hi @LuminaNAO, thanks for your contribution!

Per our contribution guidelines, the automated PR checker found the following issue(s) that need your attention:

  • AI-generated content: This project does not accept PRs, descriptions or commit messages that are fully or predominantly AI-generated. If you have used AI to assist you in writing code, please make sure to disclose that explicitly.

Please note that maintainers reserve the right to make final decisions on PRs. If you believe there is a mistake, please comment below.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: Disk-based context checkpoint offloading (--cache-disk)

1 participant