---
license: openmdw-1.1
library_name: onnx
base_model: nvidia/Kumo-Relational
base_model_relation: quantized
pipeline_tag: tabular-classification
tags:
  - onnx
  - onnxruntime-web
  - webgpu
  - relational-foundation-model
  - structured-data-models
  - tabular-classification
  - tabular-regression
  - in-context-learning
---

# KumoRelational for onnxruntime-web

An unofficial ONNX conversion of NVIDIA's [Kumo Relational](https://huggingface.co/nvidia/Kumo-Relational)
(revision `v1.0.1`), a foundation model for classification and regression
across related tables, made for Tabular Data Workbench, which runs it in the
browser with onnxruntime-web on WebGPU or WebAssembly. The weights are
NVIDIA's: unchanged in the `fp32` variant, and with the larger ones rounded to
float16 in the `f16w` variant. NVIDIA has not reviewed or endorsed this
conversion.

## Files

Each head (`classifier`, `regressor`) is cut into five graphs:

| file | inputs | output |
| --- | --- | --- |
| `<head>-col.<v>.onnx` | `X` (columns, rows, 3), `y` (train), `keys` (keys) | `E` (columns, rows, 128) |
| `<head>-row.<v>.onnx` | `E` (columns, rows, 128) | `Z` (rows, 512) |
| `<head>-hop.<v>.onnx` | `x` (nodes, 512), `src`, `dst`, `edge_type` (edges), `noise` (types, 512), `deg` (nodes, 1) | `h` (nodes, 512) |
| `<head>-out.<v>.onnx` | `x` (readouts, 512) | `z` (readouts, 512) |
| `<head>-icl.<v>.onnx` | `Z` (tokens, 512), `y` (train) | `out` (queries, 10 logits or 999 quantiles) |

`col` and `row` embed each table's rows, `hop` is one round of relational
message passing (run once per hop), `out` is the readout and `icl` is the
in-context block over the task's context and query rows. The graph neural
network's segment reductions are written as ScatterND, and the graphs contain
no int64 shape arithmetic.

Each graph comes in two variants (`<v>`):

- `fp32`: the checkpoint's weights as they are (244 MB for both heads).
- `f16w`: every float32 weight of 1,024 or more elements stored as float16
  and cast back to float32 on load (123 MB). Compute stays float32.

`manifest.json` lists every file with its size and sha256, the graphs'
inputs and outputs, each head's empty-row embedding and the parity figures
below. The time-aware neighbour sampler, the task tables, the encoders and
the ensemble stay outside the graphs; the app implements them in TypeScript.

onnxruntime 1.30's CPU ScatterND with a reduction is not deterministic with
more than one intra-op thread when indices repeat, which they do in the hop
graph. Run it single-threaded where results must be reproducible.

## How they were made

Source: `nvidia/Kumo-Relational` at `v1.0.1` (`classifier.pt`,
`regressor.pt`), loaded through NVIDIA's
[structured-data-models](https://github.com/NVIDIA/structured-data-models)
at commit `2b1696f4fdc22004cc757c44703a69cf326c0a11`.

```sh
node models/rfm/dump_shop.mjs   # once, from the repository root: the sample tables
cd models/rfm
uv run export.py                # writes public/models/rfm/
```

`export.py` (in `models/rfm/` of Tabular Data Workbench) exports the parts
defined in `exportable.py` with `torch.onnx` (dynamo, opset 18, PyTorch 2.14
on CPU) and removes the exporter's node metadata and doc strings. It checks
each graph against PyTorch, then checks the five graphs chained against
structured-data-models' own forward pass on inputs captured from a real run
over the app's sample shop tables.

## Parity

Chained graphs (onnxruntime 1.30, CPU, one thread) against
structured-data-models' forward pass, maximum absolute difference:

| head | task | fp32 | f16w | largest output |
| --- | --- | --- | --- | --- |
| classifier | churn (logits) | 8.6e-3 | 1.2e-2 | 10.6 |
| regressor | spend (quantiles) | 1.6e-3 | 6.5e-3 | 4.9 |

Each graph alone, on random inputs, matches PyTorch to 1.1e-5 (fp32).

## Licence

The weights are released by NVIDIA under the OpenMDW License Agreement 1.1
(`LICENSE`, Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES). It allows
use, modification and redistribution provided that the agreement and the
notices of origin travel with the weights, and it ends the rights of anyone
who sues claiming the model infringes a patent or copyright.

Kumo Relational fine-tunes the TabICLv2 weights (Soda team, Inria),
licensed under BSD-3-Clause; `THIRD-PARTY-NOTICES.txt` is NVIDIA's notice
with that licence's full text. The graphs were exported from
structured-data-models' model code, licensed under Apache-2.0
(`LICENSE.structured-data-models`).

Keep `LICENSE`, `THIRD-PARTY-NOTICES.txt` and
`LICENSE.structured-data-models` with the graphs when redistributing them.