Skip to content

Support head dimension 72 in Metal full attention - #4330

Merged
zcbenz merged 1 commit into
ml-explore:mainfrom
dhiltgen:headdim72
Aug 18, 2026
Merged

zcbenz merged 1 commit into
ml-explore:mainfrom
dhiltgen:headdim72

Conversation

@dhiltgen

Copy link
Copy Markdown
Contributor

Proposed changes

Instantiate the head dimension 72 variant of the Steel full-attention kernel and allow scaled dot product attention to select it. This avoids the unfused fallback for full-attention workloads with that head dimension.

Head dim 72 is the vision tower shape of the Qwen3-VL family (hidden_size 1152 / num_heads 16), shared by the public 8B, 30B-A3B, 32B and 235B-A22B versions. The unfused path materializes the full [B, H, N, N] score tensor, and N is the patch count, so its memory is quadratic in image resolution: a 24MP image needs a single ~125GiB allocation and fails outright (ollama/ollama#17804).

NAX tiles the head dimension in units of 16 and steps TD by 2, so it needs a multiple of 32. Head dim 72 therefore joins the existing 80 carve-out and takes the classic Steel kernel.

Add aligned and unaligned correctness coverage across float16, bfloat16, and float32, including unmasked, additive, boolean, and causal masks. Add head dimension 72 cases to the existing SDPA benchmark.

Benchmarks

M3 Ultra, bfloat16, batch 1, 16 heads, sequence 8192, head dimension 72, no mask:

Path Median latency Peak allocation
Unfused fallback 27.13 ms 2.09 GiB
Fused kernel from this PR 14.30 ms 72.00 MiB
Improvement 1.90x faster 29.7x lower

Head dimensions this PR does not touch move by at most 0.12% in the same runs (64, 80, 96, 128).

On NAX hardware peak allocation improves 12x to 58x over sequence 4096-16384, but the isolated kernel is 6-11% slower: head dim 72 lands on the classic Steel kernel, while the fallback's two GEMMs dispatch to NAX. That does not carry through end to end — on the Qwen3-VL-8B vision tower the patched build is 12% faster overall, because across 27 layers the score-tensor traffic saved outweighs the GEMM advantage. Bringing head dim 72 onto NAX would recover the isolated difference too, but that needs a more involved change to the NAX tiling and seems better as a follow-up.

Checklist

Put an x in the boxes that apply.

  • I have read the CONTRIBUTING document
  • I have run pre-commit run --all-files to format my code / installed pre-commit prior to committing changes
  • I have added tests that prove my fix is effective or that my feature works
  • I have updated the necessary documentation (if needed)

Qwen3-VL style vision towers use head dim 72 (hidden 1152 / 16 heads), which
is not in the supported set for the fused full-attention kernel. Those towers
therefore fall back to the unfused path, which materializes the full
[B, H, N, N] score matrix -- for a 24MP image that is a 124GiB allocation and a
hard failure rather than a slow path.

The steel kernel tiles the head dim on kFragSize=8, so 72 fits (TD=9) with the
same loader geometry as the existing dims. NAX tiles on kU=16 and steps TD by
2, so it needs a multiple of 32; 72 joins 80 on the classic steel kernel.

@zcbenz zcbenz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can confirm the speedup, thanks!

@zcbenz
zcbenz merged commit 3a62199 into ml-explore:main Aug 18, 2026
135 of 140 checks passed
@BrewTestBot BrewTestBot mentioned this pull request Aug 18, 2026
1 task done
@dhiltgen
dhiltgen deleted the headdim72 branch August 18, 2026 14:09
davidtai added a commit to Layr-Labs/mlx that referenced this pull request Aug 25, 2026
* Return tuple in meshgrid (ml-explore#4229)

* Add endpoint parameter to linspace (ml-explore#4184)

Co-authored-by: Cheng <[email protected]>

* Fix vmap of partition/argpartition dropping the kth argument (ml-explore#4116)

* Fix nan_to_num replacing inf with 0 for float16 and bfloat16 (ml-explore#4222)

Co-authored-by: codeAnqiang-ma <[email protected]>
Co-authored-by: Cheng <[email protected]>

* Fix einsum not broadcasting batch dimensions in batched tensordot (ml-explore#4125)

Co-authored-by: Cheng <[email protected]>

* Dequantize in float32 (ml-explore#4241)

* chore: Reject complex in erf and erfinv (ml-explore#4243)

* Fix cpu compilation failure of abs with uint (ml-explore#4240)

Co-authored-by: Cheng <[email protected]>

* Fix quantize matrix multiplication floor issue (ml-explore#4251)

* Only use MPI backend for world size > 1 (ml-explore#4210)

* chore: Reject complex in expm1, sigmoid and arctan2 (ml-explore#4257)

* Decompose small kernel-depth 3D convs into 2D convs (ml-explore#3785)

Co-authored-by: katlun-lgtm <[email protected]>
Co-authored-by: Cheng <[email protected]>

* Fix Metal sort of a view with a negative stride (ml-explore#4252)

* Mirror the depth axis in the decomposed 3D conv when flipped (ml-explore#4277)

* Fix Metal row reductions on negative-stride views (ml-explore#4267)

Co-authored-by: Fu Xiaonan <[email protected]>

* [CUDA] Fix custom kernel cache collision for same name, different source (ml-explore#4273)

Co-authored-by: Cheng <[email protected]>

* Fix ops rejecting integers larger than INT32_MAX (ml-explore#4255)

Co-authored-by: Feli <[email protected]>
Co-authored-by: Cheng <[email protected]>

* Fix var/std for complex numbers (ml-explore#4260)

* Fix int32 overflow in conv padded input and pad shapes (ml-explore#4258)

Co-authored-by: Cheng <[email protected]>

* chore: Reject complex in remainder (ml-explore#4270)

* chore: Compare the macOS SDK version as a version when gating JACCL (ml-explore#4286)

* Clamp ring socket transfers so a payload of 2 GiB or more can be sent (ml-explore#4281)

Co-authored-by: Cheng <[email protected]>

* chore: Use normalize_axis_index in split/unstack/partition/topk (ml-explore#4288)

* Remove grouped output in CI (ml-explore#4195)

* [CUDA] Fix finding cuda 13 headers in JIT compilation (ml-explore#3995)

* Refactor wheel building script (ml-explore#3818)

* Make mx.compile cache erasing thread safe (ml-explore#4248)

Co-authored-by: yentur <[email protected]>

* Add builds for free-threaded python (ml-explore#3812)

* Fix int32 overflow in concatenate/repeat/kron (ml-explore#4303)

* python: Widen list elements that do not fit in int32 to int64 (ml-explore#4305)

* Propagate CPU errors to events (ml-explore#3742)

Co-authored-by: Alessio Pollero <[email protected]>

* Fix mx.arange dtype inference overflow regression (ml-explore#4324)

* Add workflow to update pull request limit bypass list (ml-explore#4320)

* Support head dimension 72 in Metal full attention (ml-explore#4330)

* Patch bump to 0.32.2 (ml-explore#4333)

* Preserve subnormal float values when casting to bool (ml-explore#4224)

* python: Support assigning through a bare Ellipsis index (ml-explore#4314)

* Fix divmod truncating the quotient for floats (ml-explore#4108)

Co-authored-by: Cheng <[email protected]>

* Add force_fused option to scaled_dot_product_attention (ml-explore#4185)

* chore: Reject negative eps in the normalization layers (ml-explore#4312)

* Bound GGUF metadata string/array values against the file mapping (ml-explore#4212)

Co-authored-by: x14ngch3n <[email protected]>
Co-authored-by: Cheng <[email protected]>

* Read each K/V byte once in gqa-8 decode attention (ml-explore#4077)

* Fix fft vmap and jvp for transforms over a subset of axes (ml-explore#4138)

* Fix median dropping NaN (ml-explore#4146)

* Fix the CPU scan over a size one axis with a padded stride (ml-explore#4139)

Co-authored-by: Cheng <[email protected]>

* chore: Validate the optimizer betas at construction (ml-explore#4310)

Co-authored-by: Cheng <[email protected]>

* `RMSNormVJP` backward writes a full `{n_rows, D}` `gw_temp` intermediate (ml-explore#4293)

* [Bug]: add default none value to axis parameter of the take_along_axis (ml-explore#4357)

Co-authored-by: Anastasiia Filippova <[email protected]>

* Add a fused full-attention path for head_dim 256 on NAX devices (ml-explore#3842)

Co-authored-by: Cheng <[email protected]>

* Update nanobind to 2.15.0 (ml-explore#4337)

* Skip unnecessary simdgroup computations for quantised MOE matmuls on NAX (ml-explore#4352)

* Add AI usage policy (ml-explore#4331)

Co-authored-by: Jake Bowhay <[email protected]>

* Raise cpu stream errors from synchronize (ml-explore#4338)

Co-authored-by: Cheng <[email protected]>

* chore: Validate eps in Adam at construction (ml-explore#4361)

Co-authored-by: Anastasiia Filippova <[email protected]>

* Bound winograd conv2d working set by tiling the batch (ml-explore#4102)

Co-authored-by: Cheng <[email protected]>

* Use a 32-row block in qmm_t_nax when one block covers all of M (ml-explore#4171)

* chore: Deduplicate fftshift and ifftshift (ml-explore#4318)

* Fix Log and Equal is_equivalent ignoring primitive state (ml-explore#4266)

Co-authored-by: Cheng <[email protected]>

* Stabilize reduced-precision InstanceNorm (ml-explore#4230)

* chore: Normalize negative axes in sort and argsort (ml-explore#4332)

* Clean up main thread compile cache before python interpreter shuts down (ml-explore#4373)

* chore: Check malformed jaccl hostfile that miss rdma in pairs (ml-explore#4284)

Co-authored-by: Cheng <[email protected]>

* Round mxfp8 block scales up to avoid saturation (ml-explore#4353)

Co-authored-by: Daniel Hiltgen <[email protected]>
Co-authored-by: Cheng <[email protected]>

* Add support for the __array_namespace_info__  (ml-explore#4334)

* Stop a failed CUDA graph commit from poisoning the encoder (ml-explore#4356)

Co-authored-by: Cheng <[email protected]>

* Fix quantized kernels in JIT build (ml-explore#4372)

Co-authored-by: Cheng <[email protected]>

* Avoid zero work in stride-2 ConvTranspose3d (ml-explore#4343)

* [CUDA] Ce fused kernel (ml-explore#3947)

* Fix cpu exclusive scan for complex numbers (ml-explore#4272)

Co-authored-by: Cheng <[email protected]>

* Support Relocatable CUDA DLLs on Windows (ml-explore#4382)

* Use cast_to for fused AsType in compiled Metal kernels (ml-explore#4351)

Co-authored-by: katlun-lgtm <[email protected]>
Co-authored-by: Cheng <[email protected]>

* python: Declare DLPackCompatible protocol members as methods (ml-explore#4384)

* Fix quantizing sliced arrays (ml-explore#4381)

* Fix einsum dropping a trailing empty subscript (ml-explore#4299)

Co-authored-by: Cheng <[email protected]>

* Add script to run python tests (ml-explore#4393)

* Hold GIL in AttachedData destructor (ml-explore#4391)

* Bound Metal buffer COUNT, not just bytes, in MetalAllocator

The Metal allocator throws `[metal::malloc] Resource limit (N) exceeded`
when num_resources_ (the live+cached Metal buffer COUNT) reaches
resource_limit_ (the iogpu.rsrc_limit sysctl, default ~499000). Freed
buffers are recycled into a size-keyed cache whose only trim is by BYTES
(release_cached_buffers takes a bytes-to-free target, max_pool_size_ ~=
physical RAM). Under churn with many distinct buffer shapes (varied prompt
lengths, growing KV caches, multiple co-resident models) the cache fills
with entries never reused at that exact size, so the COUNT climbs to the
limit while byte usage stays modest and the byte trim never fires — the
process crashes mid-inference on a machine with most of its RAM free.

malloc() now also reclaims by count: when num_resources_ crosses a 90%
high-water mark of resource_limit_, it clears the (pure-reuse) buffer
cache so the count drops back to the live working set. Clearing the cache
only costs re-allocation, never correctness, so the count limit becomes
unreachable by any request mix or batching method while the existing byte
limits keep total memory bounded.

Adds get_num_resources()/get_resource_limit() to the public memory API
(metal + no_gpu + cuda backends) so the count and its ceiling are
observable from callers. Adds an MLX_RESOURCE_LIMIT env override that can
only LOWER the ceiling (clamped to the OS limit, strictly validated) to
exercise the trim deterministically and as an operator safety valve.

* perf(mlx): opt-in Gemma 4 expert-QMM tile kernel with parallel descriptor builder (#4)

* perf(mlx): add opt-in Gemma 4 expert-QMM tile kernel with parallel descriptor builder

Adds a distinctly-named expert QMM implementation for the Gemma 4
26B-A4B MoE production shapes, gated by MLX_GATHER_QMM_EXPERT_SLICES:

- qmm_t_expert_impl: BM32 expert tile body (BM16 fallback rows) taking a
  private/by-value row count; the shared qmm_t_impl constant-address ABI
  and all ordinary gathered/batched/dense QMM routes are unchanged.
- build_gemma4_sorted_expert_tiles_bm32: one 128-thread threadgroup
  replaces the reference design's single-GPU-thread serial builder;
  parallel expert-range binary search, Hillis-Steele scan, and strided
  upper-bound descriptor emission.
- Selector runs after the NAX-first route and requires affine BF16
  transposed inputs, 4-bit gs=64 weights, 128 experts, assignment counts
  of exactly 4096/8192/16384, and the exact gate/up or down rank-3
  shapes; every miss keeps the legacy route. NAX engagement is
  non-engagement, never bypassed.
- device.{h,cpp}: one-shot request resolution, nonthrowing dual-symbol
  AOT probe/prewarm, relaxed-atomic diagnostics (requested, aotAvailable,
  naxAvailable, hits, per-class fallbacks).
- gpu_tests: exact-shape arithmetic parity, fallback, and counter
  invariant probes.

Retention standing (2026-08-09 production matrix): opt-in experiment.
Standalone profile dropped (prefill -10.2% vs bracket); paired
weighted-unsort+R1 profile retained-final (prefill +1.8%, TTFT -7.5%,
decode +3.3%, arrival E2E +12.0%). NOTE: this source post-dates the
benchmarked binaries/metallib (post-measurement kernel-body edit);
rebuild and re-verify before any performance claim.

* fix(mlx): fail-safe sortedness check in gemma expert tile builder; counter/atomic hygiene

Review-wave fixes for the R1 expert-QMM path:

- N1 (sortedness trust): build_gemma4_sorted_expert_tiles_bm32 now
  verifies each thread's post-binary-search segment boundary against the
  generalized invariant indices[start - 1] < lid <= indices[start]
  (edge threads check their single neighbor), votes per simdgroup via
  simd_or, folds the votes through threadgroup memory, and on any
  violation retracts count[0] to 0 (tile kernel then early-returns) and
  records the violation in count[1]; the buffer ABI is unchanged
  (count index 1 was previously unused). try_gemma4_expert_qmm allocates
  the second count element, drains the encoder after the builder, and
  re-routes a retracted call to the order-agnostic legacy path instead of
  dispatching the tile kernel (zero count is unambiguous: the selector's
  assignment gate guarantees M is 4096/8192/16384).
- N2 (route-condition duplication): the sorted-RHS gate literal that
  appeared (negated) in the diagnostics record and in the dispatch
  decision is now the shared static constexpr predicate
  takes_sorted_rhs_route, so future tuning of the 16/4 thresholds cannot
  desynchronize counter vs route.
- N3 (per-call bias normalization): gather_qmm_rhs no longer spends
  ensure_row_contiguous on biases before classification reads the raw
  tensor's fields; normalization runs only inside the winning-route
  branch (hit semantics unchanged; the legacy block keeps its own
  normalization point and ordering).
- N4 (armed_ data race): Gemma4ExpertQMMCounters::armed_ is now
  std::atomic<bool> with relaxed loads/stores in armed(), snapshot(),
  snapshot_and_disarm() (read-then-write order preserved) and
  clear_and_arm(); the class remains non-copyable, now enforced.

* fix(mlx): make the R1 sortedness fail-safe sound; proper retract attribution

F1: the per-expert boundary vote was a partial detector -- an inversion
inside a segment used by no other expert's boundary could escape, so
"re-route on any violation" overclaimed. build_gemma4_sorted_expert_tiles_bm32
now also runs a strided adjacent-pair scan: thread lid checks
indices[i-1] <= indices[i] for i = lid+1; i < M; i += 128, covering every
adjacent pair in [1, M) exactly once (1..128 iterations at the reachable
M in {4096,8192,16384}). Adjacent-pair monotonicity is transitive, so a
clean scan is a sound and complete sortedness oracle; it folds into the
same simd_or/threadgroup vote and the same retract (count[0]=0, count[1]=1).
The boundary checks stay as cheap, precise diagnostics.

F2: retracts were write-only in count[1] and surfaced as
fallback_metallib_unavailable -- misattribution in the only observable
surface. A dedicated fallback_sortedness_retracted counter now rides the
GemmA4 route counters and the C diagnostics ABI
(sizeof 80 -> 88, new uint64 at offset 80; existing offsets unchanged).
try_gemma4_expert_qmm returns the route class: count[0]==0 with count[1]==1
records fallback_sortedness_retracted, any other unusable build keeps
fallback_metallib_unavailable, then re-routes to the legacy path as before.

F4: new doctest drives the full armed() -> clear_and_arm() ->
snapshot_and_disarm() cycle and the attempts == hits + fallbacks invariant
including the new class; the route-table and counter-invariant tests now
cover fallback_sortedness_retracted.

Verified: cmake tests 262/262 + 3550 assertions pass; metal -Wall -Wextra
-fno-fast-math compile of kernels/quantized.metal is warning-free.

* perf(metal): E=256 expert-tile route + trust + gpu::eval UAF fix — darkbloom-base mirror (#7)

* perf(metal): instantiate E=256 expert-tile route for Qwen 3.5/3.6 MoE prefill (mirror of Cmlx/mlx 58fab46)

* fix(metal): use-after-free in gpu::eval for primitives that synchronize mid-eval (mirror)

* perf(metal): trust mode skips retract readback (mirror)

* fix(compile): preserve all-cache binding cleanup

---------

Co-authored-by: JasonHonKL <[email protected]>
Co-authored-by: AK <[email protected]>
Co-authored-by: Cheng <[email protected]>
Co-authored-by: Adityaj0 <[email protected]>
Co-authored-by: anchor <[email protected]>
Co-authored-by: codeAnqiang-ma <[email protected]>
Co-authored-by: Rohan Gautam <[email protected]>
Co-authored-by: Ayaan Gazali <[email protected]>
Co-authored-by: Erwin Zhang <[email protected]>
Co-authored-by: katlun-lgtm <[email protected]>
Co-authored-by: katlun-lgtm <[email protected]>
Co-authored-by: robertomeroni <[email protected]>
Co-authored-by: Fu Xiaonan <[email protected]>
Co-authored-by: Fu Xiaonan <[email protected]>
Co-authored-by: Hao Xu <[email protected]>
Co-authored-by: Feli <[email protected]>
Co-authored-by: Feli <[email protected]>
Co-authored-by: Eyüp Can Akman <[email protected]>
Co-authored-by: Cheng <[email protected]>
Co-authored-by: yentur <[email protected]>
Co-authored-by: Alessio Pollero <[email protected]>
Co-authored-by: Zhiqi Zhang <[email protected]>
Co-authored-by: Daniel Hiltgen <[email protected]>
Co-authored-by: Tanish Jain <[email protected]>
Co-authored-by: hojin12312 <[email protected]>
Co-authored-by: Xiang Chen <[email protected]>
Co-authored-by: x14ngch3n <[email protected]>
Co-authored-by: Duhyeon, Kim <[email protected]>
Co-authored-by: rohith <[email protected]>
Co-authored-by: Ishaan Samantray <[email protected]>
Co-authored-by: Aaishwarya Mishra <[email protected]>
Co-authored-by: Anastasiia Filippova <[email protected]>
Co-authored-by: Yanzhao Wang <[email protected]>
Co-authored-by: XXXXRT666 <[email protected]>
Co-authored-by: Jake Bowhay <[email protected]>
Co-authored-by: vraj patel <[email protected]>
Co-authored-by: Gusanidas <[email protected]>
Co-authored-by: Dwijen Patel <[email protected]>
Co-authored-by: Vladimir Iglovikov <[email protected]>
Co-authored-by: Brian C. <[email protected]>
Co-authored-by: Daniel Hiltgen <[email protected]>
Co-authored-by: YH Yan <[email protected]>
Co-authored-by: katlun-lgtm <[email protected]>
Co-authored-by: anupsv <[email protected]>
Co-authored-by: Gajesh Naik <[email protected]>
Co-authored-by: David Tai <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants