999个分位数里藏着什么:kumo-tabular-small-regressor-ONNX输出解码与不确定性估计实战

原创2026-10-30 22:53:142,130 阅读
文章标签:人工智能机器学习本地部署

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 给出了一句话版的后处理流程,展开就是三步:

排序 → 乘以上下文标准差 → 加上上下文均值

  1. 排序(sort):模型输出的 999 个分位数理论上应已有序,但为保险起见按升序排一遍;
  2. 还原尺度(destandardize):每个分位数 乘以 y_context 的总体标准差,再加上上下文均值,从标准化空间回到真实的业务量纲;
  3. 得到点估计: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 生态:

  1. 输入:拼接好的上下文+查询行 x、标准化目标值 y_context、类别列掩码 categorical_mask;
  2. 解码:排序 → ×标准差 + 均值 → 取均值即点估计;
  3. 不确定性:任取分位位置就是区间预测,q05/q95、q25/q75 随取随用。

配合 WebGPU,这套表格预测 + 不确定性估计完全可以在浏览器里离线运行,数据不出页面——对隐私敏感的结构化数据场景来说,这正是它的杀手锏。模型权重遵循 LICENSE 中的 OpenMDW-1.1 协议,商用前记得先阅读条款。

登录后查看全文
kumo-tabular-small-regressor-ONNX