Skip to content

[codex] Add Metal TurboQuant KV cache#124

Draft
Chedrian07 wants to merge 2 commits into
antirez:mainfrom
Chedrian07:codex/turboquant-decode-optimization
Draft

[codex] Add Metal TurboQuant KV cache#124
Chedrian07 wants to merge 2 commits into
antirez:mainfrom
Chedrian07:codex/turboquant-decode-optimization

Conversation

@Chedrian07
Copy link
Copy Markdown

Summary

  • Add Metal TurboQuant KV cache modes (DS4_KV_TURBO=3 and DS4_KV_TURBO=4) using PolarQuant/WHT packed rows instead of materialized FP8 compressed attention rows.
  • Keep the server/API wire format unchanged, including KV disk checkpoint save/load, and add live server verification coverage for cache reuse and streaming/non-streaming requests.
  • Optimize ratio-4 decode by dequantizing only selected top-k compressed rows, feeding a compact f16 selected-row path, and exposing DS4_METAL_DECODE_INDEXER_TOP_K for fast non-quality runs.

Why

Long-context Metal sessions spend a large amount of memory on compressed KV rows. TurboQuant reduces that footprint while keeping decode on the sparse indexed attention path instead of expanding the whole compressed cache every token. The selected-row decode path keeps the default 512-row behavior for quality and lets experiments lower the decode top-k without changing the API.

Local results

M4 Max, --ctx 384000, prompt 22204 tokens, decode 128 tokens:

mode context buffers decode
FP8 6732.77 MiB 24.22 t/s
Turbo4 top-k 512 3871.22 MiB 25.08 t/s
Turbo4 top-k 128 3871.22 MiB 27.11 t/s
Turbo3 top-k 512 3760.35 MiB 24.85 t/s

A deterministic needle-retrieval probe passed for Turbo4 top-k 512, 256, 128, and 64. One longer 44k-token sequential benchmark run hit a transient Metal GPU hang during Turbo4 prefill; repeated 22k-token Turbo4 runs and server cache validation passed.

Validation

  • make -B ds4.o ds4_metal.o ds4_server.o ds4_test.o ds4 ds4-server ds4_test
  • ./ds4_test --metal-kernels
  • ./ds4_test --server
  • DS4_VERIFY_COMPARE=0 DS4_VERIFY_CTX=8192 DS4_VERIFY_KV_DIR=/tmp/ds4-kv-turbo4-pr-smoke DS4_VERIFY_OUT_DIR=/tmp/ds4-turbo4-pr-smoke tests/verify_turbo_server.sh --primary 4 --no-compare --no-bench
  • git diff --check

김승중 added 2 commits May 14, 2026 09:09
Add PolarQuant/WHT turbo3 and turbo4 KV cache storage, selected-row dequant for indexed attention, and live server verification/benchmark coverage.
@antirez
Copy link
Copy Markdown
Owner

antirez commented May 14, 2026

Not sure what's the point of that. Turbo quants, especially in an already compressed KV cache that carries "more" signal per row, is going likely to have some degradation effect. And deepseek v4 KV cache is already compact. I don't believe TQ here is a good idea.

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.

2 participants