vLLM Metal v0.29.0

v0.29.0 tracks the vLLM v0.29.0 core. The release contains 45 merged pull requests from 14 contributors since vLLM Metal v0.28.0.

Highlights

vLLM 0.29.0 core: the plugin follows upstream's KV-cache layout refactor (slots derived from tensor byte addresses, the worker reports Metal's LBNHC page order), stays on the V1 model runner now that V2 is upstream's default, and drops its auto-fit null-block patch because upstream reserves the block itself (#744).
More hybrid families: LFM2/LFM2.5 serve on paged state with prefix caching, Nemotron-H runs its Mamba-2 mixers on paged state and through the decode pipeline, and hybrid models route through a state-family table (#598, #710, #735, #696).
Embeddings: official Qwen3-Embedding checkpoints load, Matryoshka dimensions are supported, and multilingual E5 serves with encoder mean pooling (#736, #738, #742).
Speculative decoding fixes: the first draft window after prefill and draft-KV sync with a zero dynamic K are corrected (#721, #716).
Logprobs: requested token logprobs are honored and prompt logprobs are populated on both runner paths (#667, #694, #726).
Dependencies: MLX 0.32.1 with a matching mlx-lm pin, transformers unpinned so MLX-quantized Qwen3.5/3.6 serve natively, and mlx-vlm 0.6.8 (#723, #733, #712, #725).

Requirements:

Stable channel:

curl -fsSL https://raw.githubusercontent.com/vllm-project/vllm-metal/main/install.sh | bash -s -- --stable

The installer downloads prebuilt vllm-metal and vLLM wheels. It does not invoke a C++ or Metal compiler.

The release attaches a native Python 3.12 wheel for macOS 15 arm64:

vllm_metal-0.29.0-cp312-cp312-macosx_15_0_arm64.whl

The compatible upstream core is the prebuilt vLLM v0.29.0 macOS arm64 wheel.

Null block reserved in non-paged scheduler capacity (#672).
SDPA metadata cached across layers (#688).
QK norm placement is architecture-aware, fixing Hunyuan dense (#664).
Gemma 2 attn_logit_softcapping reaches the paged attention kernel (#666).
Paged attention fixes for mlx-lm DeepseekAttention, EXAONE 4.0 32B, StableLM scale, and Phi-1/1.5 (#678, #676, #687, #704).
Hybrid geometry lives behind a family owner and reuses vLLM's hybrid state dtypes (#668, #718).
Repeated Metal frame captures work (#717).

LoRA: BF16 adapters load natively in MLX and the configured LoRA dtype is honored (#690, #699).
GGUF: local sharded files fail fast, cached references resolve offline, and remote plain-typed reference tags are accepted (#720, #732, #739).
Whisper audio features match the reference (#729).
VLLM_USE_MODELSCOPE=1 no longer falls back to Hugging Face, and model revisions are preserved across Metal loading paths (#683, #719).

vllm-metal and vLLM core are both versioned 0.29.0 for this release.
MLX is pinned to exactly 0.32.1, matching the prebuilt native extension ABI (#723).
transformers requires 5.10.4 or newer and huggingface_hub 1.28.0 or newer, following vLLM 0.29.0 (#744).
VLLM_USE_V2_MODEL_RUNNER defaults to 0 when Metal is selected; setting it to 1 is rejected at startup because MetalWorker implements the V1 runner contract (#744).
A live MLX parity checker (tools/check_parity.py) and nightly model parity CI (#705, #706).
CI builds Metal shaders once, lints only on macOS, and rejects HTTP errors in smoke health checks (#698, #697, #702, #701).
Docs: README architecture figure, speculative ingest chunk setting, logos fetched from upstream (#663, #669, #741).

Hybrid GDN prefix caching remains experimental: cache-on versus cache-off parity still diverges on a subset of divergent-suffix prompts, unchanged from v0.28.0, and GDN block accounting still charges each block to both the state and KV pools (#584).
Nemotron-H keeps one private Mamba-2 state slot per request, so prefix caching is downgraded to off for it.