999个分位数里藏着什么:kumo-tabular-small-regressor-ONNX输出解码与不确定性估计实战
999个分位数里藏着什么:kumo-tabular-small-regressor-ONNX输出解码与不确定性估计实战
kumo-tabular-small-regressor-ONNX 是 NVIDIA Kumo Tabular 表格基础模型(tabular foundation model)的 ONNX 转换版,它只需一次前向推理就能对表格数据做无训练预测(in-context learning),并且输出 999 个分位数——这 999 个数就是完整的不确定性估计。本文将带你彻底搞懂这个 ONNX 回归模型(Kumo Tabular ONNX)的输入输出接口、如何解码 logits,以及如何用分位数做区间预测。
它是什么:不用训练,看几行样例就能预测表格数据
传统做法是:拿到一张带标签的 CSV,训练一个回归模型,再用来预测新行。Kumo Tabular 换了思路——把带标签的"上下文行"和没有标签的"查询行"拼成一张表一起喂给模型,模型在一次前向传播里直接给出新行的预测值(tabular regression,in-context learning)。
kumo-tabular-small-regressor-ONNX 就是其中 Small 尺寸、回归任务头(regressor head)的 ONNX 版本,专为 Transformers.js / ONNX Runtime 生态设计,可以在浏览器(WebGPU/WASM/CPU)或服务器上直接运行,数据无需离开页面。
仓库克隆地址(如需源码和模型文件):
git clone https://gitcode.com/hf_mirrors/onnx-community/kumo-tabular-small-regressor-ONNX
先看文件:ONNX 图、权重与配置文件
仓库结构非常精简,核心就三处:
| 文件/目录 | 作用 |
|---|---|
| onnx/model.onnx + onnx/model.onnx_data | ONNX 计算图 + 外置权重(fp32,合计约 120 MB) |
| config.json | 模型元信息:model_type: kumo_tabular、num_outputs: 999 |
| conversion/export_onnx.py | 导出脚本,记录了输入输出接口与动态形状 |
| conversion/fixtures.py | 黄金测试数据,定义了确定性的预处理配方与输出后处理 |
| README.md | 官方说明:接口定义、精度验证、许可协议 |
在 config.json 里可以直接看到关键参数:
"num_outputs": 999,
"inputs": "x [R, C] float32 (context rows first), y_context [Rc] float32, categorical_mask [C] bool"
也就是说:每个查询行都会得到 999 个输出。接下来就拆解这三个输入和这个输出。
输入输出接口:一次看会,终身受用
三个输入
x:形状[R, C],float32。上下文行在前,查询行在后,且已经过预处理(标准化、裁剪、类别编码等)。y_context:形状[R_context],float32。上下文行的目标值,且已经用上下文自身的均值和总体标准差做了标准化(standardize)。categorical_mask:形状[C],bool。标记哪些列来自分类特征(categorical features)。
conversion/export_onnx.py 中用动态形状导出了该模型:行数 R(4~65536)、上下文行数 Rc(2~65536)、列数 C(1~512)都可以变化,所以同一份 ONNX 图能适配任意规模的表格。
一个输出:logits 里的 999 个分位数
模型只有一个输出:
logits:形状[R_query, 999],即每个查询行输出 999 个数,它们是按序排列的分位数 q001…q999,且是在标准化后的目标值空间(standardized target)里定义的。
这是整个模型最有意思的设计:它不输出一个"最可能的值",而是输出目标值完整的概率分布轮廓(quantile regression)。想知道分布偏不偏、尾巴长不长、预测有多不确定,答案全在这 999 个数里。
输出解码三步走:从分位数到最终预测值
README.md 给出了一句话版的后处理流程,展开就是三步:
排序 → 乘以上下文标准差 → 加上上下文均值
- 排序(sort):模型输出的 999 个分位数理论上应已有序,但为保险起见按升序排一遍;
- 还原尺度(destandardize):每个分位数
乘以 y_context 的总体标准差,再加上上下文均值,从标准化空间回到真实的业务量纲; - 得到点估计:999 个分位数的平均值就是最终回归预测值(point estimate)。
用公式表达(s 为上下文目标值的标准差,m 为均值,q_i 为标准化分位数):
真实分位数_i = s × q_i + m
点估计(预测值)= mean(q_1 … q_999) × s + m
conversion/fixtures.py 中回归任务的输出管道正是 SortQuantiles → AverageEstimators,与上述流程一一对应。
不确定性估计实战:区间预测就是这么简单
有了 999 个分位数,做不确定性估计(uncertainty estimation)几乎不需要额外工作:
- 50% 区间:取第 250 位与第 750 位分位数(约 q25~q75),落在该区间的概率约为 50%;
- 90% 区间:取约第 50 位与第 950 位(q05~q95);
- 尾部风险:q99 与点估计的差距,可以直观回答"最坏情况比预期差多少"。
举一个业务场景:预测客户生命周期价值(LTV)。点估计说"这个客户值 800 元",但如果 q05~q95 是 620~1050 元,说明分布很宽、预测不确定性高,做定价时要留足缓冲;反之若区间收窄到 780~820 元,则可放心下注。这种"预测值 + 置信区间"的输出,正是分位数回归相比单点回归的核心优势。
预处理要求:模型只吃"喂好"的数据
需要注意,ONNX 图里封装的是模型本身(_KumoTabular.forward),不包含预处理。README.md 明确指出它期望上游完成 sdm 风格的预处理:
- 数值列:标准化(standardize)→ 裁剪到 ±100 → sigma-clip(阈值 4.0);
- 分类列:类别对齐编码 + 追加类别计数列(cardinality ≥ 50 时)→ 再走数值处理;
- 目标列:用上下文均值与总体标准差标准化;
- 列数上限 500(超出取前 500 列)。
conversion/fixtures.py 里这份"确定性配方"(去掉了 FlipSign、ShuffleColumns 等随机增强)是浏览器端 TypeScript 实现逐值对齐的基准,如果你要自己接数据,照它写预处理即可。
精度验证:ONNX 与 PyTorch 几乎一致
官方在 README.md 中给出了两套基准的对比结果(用真实数据集 diabetes 442×10、California housing 1500×8 抓取的输入):
| 运行环境 | 与 PyTorch 输出的最大绝对误差 |
|---|---|
| ONNX Runtime(CPU) | ≤ 4.4e-5 |
| ONNX Runtime(WebGPU,Chrome + M3 Pro) | ≤ 2e-4 |
换算到浏览器端到端的点估计上,相对误差在 6e-6 以内——也就是说,你在浏览器里跑 ONNX 得到的预测值,与在 PyTorch 里跑原生模型基本是同一组数。
转换本身用的是 torch.onnx.export(dynamo,opset 20),其中 aten.remainder.Scalar(列分组里的 index % num_columns)做了一个自定义降维,映射为 ONNX 的 Mod 算子,实现见 conversion/export_onnx.py。
小结
kumo-tabular-small-regressor-ONNX 把"999 个分位数"这个设计从 PyTorch 带到了 ONNX 生态:
- 输入:拼接好的上下文+查询行
x、标准化目标值y_context、类别列掩码categorical_mask; - 解码:排序 →
×标准差 + 均值→ 取均值即点估计; - 不确定性:任取分位位置就是区间预测,q05/q95、q25/q75 随取随用。
配合 WebGPU,这套表格预测 + 不确定性估计完全可以在浏览器里离线运行,数据不出页面——对隐私敏感的结构化数据场景来说,这正是它的杀手锏。模型权重遵循 LICENSE 中的 OpenMDW-1.1 协议,商用前记得先阅读条款。