ai.onnx.Conv

ai.onnx · standard ONNX operator · ONNX opset ≥ 11

Description

Applies an N-dimensional convolution to the input tensor X using filter weights W and an optional bias B. Supports grouped convolution, explicit per-axis padding, dilation, and stride along each spatial dimension.

See the ONNX Conv spec for the reference semantics.

Inputs

Outputs

Attributes

Attributes and default values (overridable per request):

Type constraints

Implementation variants

One implementation is selected per call from the device capabilities, the request shapes and the dtypes; these notes say what each one covers.

• pointwise_channel_reduce — Handles pointwise unit-stride convolution with few output channels by assigning one invocation to each spatial position and accumulating every output channel in registers. It does not materialize im2col scratch.
• pointwise_channel_reduce_bias — Handles pointwise unit-stride convolution with few output channels by assigning one invocation to each spatial position and accumulating every output channel in registers. It does not materialize im2col scratch.
• gemm_1x1_subgroup_matrix — Multiplies 1x1 weights directly by NCHW input. Complete output-channel tiles use direct subgroup-matrix loads, eliminating input staging and reduction-loop barriers; partial tiles retain guarded staging. Tile geometry follows the device's workgroup limits.
• gemm_1x1_subgroup_matrix_bias — Multiplies 1x1 weights directly by NCHW input. Complete output-channel tiles use direct subgroup-matrix loads, eliminating input staging and reduction-loop barriers; partial tiles retain guarded staging. Tile geometry follows the device's workgroup limits.
• im2col_gemm_subgroup_matrix — Materializes convolution windows as a column matrix, then multiplies it by the weights with subgroup-matrix operations. It applies when reduction and spatial extents are tile-aligned and column scratch fits.
• im2col_gemm_subgroup_matrix_bias — Materializes convolution windows as a column matrix, then multiplies it by the weights with subgroup-matrix operations. It applies when reduction and spatial extents are tile-aligned and column scratch fits.
• im2col_direct_f32_subgroup_matrix — Materialize tile-aligned convolution columns and load weights and columns directly into subgroup matrices, removing operand staging and K-loop barriers. Retain f32 accumulation, existing split-K reduction order, and the implicit gather preference below the measured channel-tile reuse threshold.
• im2col_direct_f16_subgroup_matrix — Materialize tile-aligned convolution columns and load weights and columns directly into subgroup matrices, removing operand staging and K-loop barriers. Retain f32 accumulation, existing split-K reduction order, and the implicit gather preference below the measured channel-tile reuse threshold.
• im2col_direct_f32_subgroup_matrix_bias — Materialize tile-aligned convolution columns and load weights and columns directly into subgroup matrices, removing operand staging and K-loop barriers. Retain f32 accumulation, existing split-K reduction order, and the implicit gather preference below the measured channel-tile reuse threshold.
• im2col_direct_f16_subgroup_matrix_bias — Materialize tile-aligned convolution columns and load weights and columns directly into subgroup matrices, removing operand staging and K-loop barriers. Retain f32 accumulation, existing split-K reduction order, and the implicit gather preference below the measured channel-tile reuse threshold.
• implicit_im2col_subgroup_matrix — Gathers each logical im2col tile directly from X instead of materializing a column matrix, trading extra address arithmetic for the scratch and bandwidth that materialization would cost. It applies when the output has few output-channel tiles, so the gather is not repeated across many tiles.
• implicit_im2col_subgroup_matrix_bias — Gathers each logical im2col tile directly from X instead of materializing a column matrix, trading extra address arithmetic for the scratch and bandwidth that materialization would cost. It applies when the output has few output-channel tiles, so the gather is not repeated across many tiles.
• implicit_im2col3d_subgroup_matrix — Gathers each logical 3-D im2col tile directly from X instead of materializing a column matrix, trading extra address arithmetic for the scratch and bandwidth a volumetric materialization would cost. It applies when the output has few output-channel tiles, so the gather is not repeated across many tiles.
• implicit_im2col3d_subgroup_matrix_bias — Gathers each logical 3-D im2col tile directly from X instead of materializing a column matrix, trading extra address arithmetic for the scratch and bandwidth a volumetric materialization would cost. It applies when the output has few output-channel tiles, so the gather is not repeated across many tiles.
• implicit_im2col_subgroup_matrix_splitk — Partitions the implicit-im2col reduction across workgroups when the unsplit output grid is too small, then combines raw partial sums from scratch. The combine reassociates floating-point addition relative to the unsplit route.
• implicit_im2col_subgroup_matrix_bias_splitk — Partitions the implicit-im2col reduction across workgroups when the unsplit output grid is too small, then combines raw partial sums from scratch. The combine reassociates floating-point addition relative to the unsplit route.
• im2col_gemm_subgroup_matrix_padded — Materializes a zero-padded column matrix before a subgroup-matrix multiply, allowing logical reduction and spatial extents that are not tile-aligned. Padded values contribute zero and are excluded from the logical output.
• im2col_gemm_subgroup_matrix_padded_bias — Materializes a zero-padded column matrix before a subgroup-matrix multiply, allowing logical reduction and spatial extents that are not tile-aligned. Padded values contribute zero and are excluded from the logical output.
• im2col_gemm_subgroup_matrix_padded_splitk — Materializes a zero-padded column matrix, partitions its subgroup-matrix reduction across workgroups, and combines raw partial sums from scratch. It preserves the padded route for low-parallelism outputs; the combine reassociates floating-point addition.
• im2col_gemm_subgroup_matrix_padded_bias_splitk — Materializes a zero-padded column matrix, partitions its subgroup-matrix reduction across workgroups, and combines raw partial sums from scratch. It preserves the padded route for low-parallelism outputs; the combine reassociates floating-point addition.
• implicit_im2col_tiled_bias_reg_m32 — Gathers logical im2col elements directly from X while filling register-blocked GEMM tiles. It avoids column scratch and provides the portable implicit route without subgroup-matrix support.
• implicit_im2col_tiled_reg — Gathers logical im2col elements directly from X while filling register-blocked GEMM tiles. It avoids column scratch and provides the portable implicit route without subgroup-matrix support.
• implicit_im2col_tiled_bias_reg — Gathers logical im2col elements directly from X while filling register-blocked GEMM tiles. It avoids column scratch and provides the portable implicit route without subgroup-matrix support.
• implicit_im2col_tiled_reg_splitk — Partitions the register-blocked implicit-im2col reduction across workgroups when the unsplit output grid is too small, then combines raw partial sums. The combine reassociates floating-point addition relative to the unsplit route.
• implicit_im2col_tiled_bias_reg_splitk — Partitions the register-blocked implicit-im2col reduction across workgroups when the unsplit output grid is too small, then combines raw partial sums. The combine reassociates floating-point addition relative to the unsplit route.
• gemm_1x1_tiled_reg_splitk — Partitions the register-blocked 1x1 GEMM reduction across additional workgroups when the output grid is small, then combines raw partial sums. The combine reassociates floating-point addition relative to the unsplit route.
• gemm_1x1_tiled_bias_reg_splitk — Partitions the register-blocked 1x1 GEMM reduction across additional workgroups when the output grid is small, then combines raw partial sums. The combine reassociates floating-point addition relative to the unsplit route.

Device requirements

Some implementation variants require subgroup-matrix, shader-f16, and subgroups. These are route-specific capabilities, not package-wide requirements; availability also depends on the request shape and dtype.

Files

• metadata.json — kernel metadata (id, digests, per-variant templates, provenance)
• manifest.json — the op contract (source of truth)
• test.json — correctness cases
• bench.json — benchmark + tuning cases
• conv-1x1-channel-reduce.wgsl.jinja
• conv-1x1-gemm-tiled-reg.wgsl.jinja
• conv-1x1-gemm-tiled.wgsl.jinja
• conv-1x1-subgroup-matrix.wgsl.jinja
• conv-direct-nd.wgsl.jinja
• conv-direct-unrolled.wgsl.jinja
• conv-im2col-ncdhw.wgsl.jinja
• conv-im2col-nchw.wgsl.jinja
• conv-splitk-reduce.wgsl.jinja
• conv1d-tiled-reg.wgsl.jinja
• conv2d-grouped-large-w4.wgsl.jinja

Use with @huggingface/kernels

npm install --save-exact @huggingface/kernels@0.0.1-preview.2

Required output shapes and logical data types are inferred from the supplied inputs and attributes; result tensors are allocated automatically.

The version: 1 option selects the published kernel contract; it is independent of any operator opset, contrib since_version, or model version. It follows the v1 branch as fixes land. To pin exact artifact bytes, pass a 40-character commit revision instead of 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/ai.onnx.Conv", { version: 1 });
const { y } = await kernel({
  x: { data: xData, shape: [1, 1, 7] },
  w: { data: wData, shape: [1, 1, 1] },
});