Checks / structure
GQA numHeads not divisible by numKVHeads
Check R16. Runs in the editor as you build, in CI through the
GitHub Action, and over the wire at
POST /api/v1/check. Milliseconds, before any GPU is billed.
block
structure
R16
| Trigger | A groupedQueryAttention component has params where numHeads % numKVHeads != 0. |
|---|---|
| Why | GQA groups query heads; the group size must divide the head count. Mis-set ratios crash on the first attention forward. |
| Source | Ainslie et al. 2023, GQA. |
The evidence behind it
In a 264-graph study (two seeds, torch 2.8), all 96 graphs blocked by the structural checks crashed PyTorch forward and all 80 that passed ran clean. Read the study.
Why it is not a lint you can ignore
A structural mistake does not fail at review time and it does not fail at import
time. It fails when the module is constructed on the training node, after the job was queued and
the dataset was downloaded. That is why this runs before the spend and not after it.
See this check fire on a planted example
One click, no account, runs in your browser
Every check
41 structural checks: 6 guardrail gates and 35 architecture advisor rules. See the full catalogue.
← R15 MoE without auxiliary loss ยท R17 SwiGLU intermediateSize convention →