com.microsoft.MatMulNBitsQkv

com.microsoft · ONNX Runtime contrib operator · contrib since_version 1

Description

Fuses RMS normalization with three block-quantized attention projections: A_norm = RMSNorm(A + skip, norm_scale) (or without skip), followed by Q, K, and V projections. The optional fourth output returns A + skip. Only 4-bit weights with block_size = 32 are supported; projection biases, bfloat16, and non-default accuracy_level values are not implemented.

See the ONNX Runtime MatMulNBitsQkv contrib-operator spec for the reference semantics.

Inputs

Name	Bind key	Logical dtype	Rank	Shape	Description	Presence
`A`	`aT`	`T1`	—	—	Shared activation of rank 2 `(M, K)` or rank 3 `(batch, sequence, K)`; only the last axis is the reduction axis.	required
`skip`	`skipT`	`T1`	—	—	Residual added to A before the normalization, with A's shape.	optional
`norm_scale`	`normScaleT`	`T1`	`1`	—	Simplified-layer-normalization (RMS) gain of shape `[K]`.	required
`q_B`	`qBT`	`T2`	`3`	—	Bit-packed uint8 Q weights of shape `(Nq, k_blocks, blob_size)`.	required
`q_scales`	`qScalesT`	`T1`	`2`	—	Per-block Q scales of shape `(Nq, k_blocks)`. Quantization is symmetric: there is no zero-point input, so codes are offset by the midpoint `2^(bits - 1)`.	required
`k_B`	`kBT`	`T2`	`3`	—	Bit-packed K weights of shape `(Nkv, k_blocks, blob_size)`.	required
`k_scales`	`kScalesT`	`T1`	`2`	—	Per-block K scales of shape `(Nkv, k_blocks)`.	required
`v_B`	`vBT`	`T2`	`3`	—	Bit-packed V weights of shape `(Nkv, k_blocks, blob_size)`.	required
`v_scales`	`vScalesT`	`T1`	`2`	—	Per-block V scales of shape `(Nkv, k_blocks)`.	required

Outputs

Name	Bind key	Logical dtype	Rank	Shape	Description	Presence
`Q`	`qT`	`T1`	same as `A`	derived; see description	Query projection: A's leading axes with a trailing Nq.	required
`K`	`kT`	`T1`	same as `A`	derived; see description	Key projection: A's leading axes with a trailing Nkv.	required
`V`	`vT`	`T1`	same as `A`	derived; see description	Value projection: A's leading axes with a trailing Nkv.	required
`input_skip_bias_sum`	`residualT`	`T1`	same as `A`	same as `A`	The residual sum A + skip, with A's shape. Requires the skip input.	optional

Attributes

Attributes and default values (overridable per request):

Attribute	Default	Description
`accuracy_level`	`0`	Minimum internal accuracy level, following MatMulNBits semantics; this implementation supports the standard default 0.
`bits`	`4`	Bit width used to quantize all three weight matrices; only 4 is supported.
`epsilon`	`9.999999974752427e-7`	Epsilon used by the simplified layer-normalization reduction.
`K`	—	Input feature dimension shared by the normalized input and all projection weights.
`Nq`	—	Output feature dimension of the Q projection.
`Nkv`	—	Output feature dimension shared by the K and V projections.
`block_size`	—	Size of each quantization block along K; only 32 is supported.

Type constraints

Variable	Allowed dtypes
`T1`	`float32`, `float16`
`T2`	`uint8`

Files

metadata.json — kernel metadata (id, digests, provenance)
manifest.json — the op contract (source of truth)
test.json — correctness cases
bench.json — benchmark + tuning cases
matmul-nbits-fused-rms-norm.wgsl.jinja
qkv-projection.wgsl.jinja

Use with `@huggingface/kernels`

The loader derives every required output's shape and logical dtype from the manifest contract and this call. It then allocates the result tensors automatically.

The version: 1 option selects the published kernel contract; it is independent of any operator opset, contrib since_version, or model version.

Replace each *Data placeholder with a typed array containing the corresponding input data.

import { getKernel } from "@huggingface/kernels";

const kernel = await getKernel("webgpu-kernels/com.microsoft.MatMulNBitsQkv", { version: 1 });
const { qT, kT, vT } = await kernel({
  aT: { data: aTData, shape: [2, 32] },
  normScaleT: { data: normScaleTData, shape: [32] },
  qBT: { data: qBTData, shape: [5, 1, 16] },
  qScalesT: { data: qScalesTData, shape: [5, 1] },
  kBT: { data: kBTData, shape: [3, 1, 16] },
  kScalesT: { data: kScalesTData, shape: [3, 1] },
  vBT: { data: vBTData, shape: [3, 1, 16] },
  vScalesT: { data: vScalesTData, shape: [3, 1] },
}, {
  attrs: {
    K: 32,
    Nq: 5,
    Nkv: 3,
    block_size: 32,
  },
});

Downloads last month: -

kernel

webgpu

wgsl

apache-2.0

WebGPU

Requires WebGPU support. See the compatibility table.