读懂模型接口:kumo-tabular-small-regressor-ONNX 输入输出张量完全参考(x、y_context、categorical_mask、999分位数logits)

原创2026-10-30 11:40:031,751 阅读
文章标签:人工智能机器学习本地部署

读懂模型接口:kumo-tabular-small-regressor-ONNX 输入输出张量完全参考(x、y_context、categorical_mask、999分位数logits)

kumo-tabular-small-regressor-ONNX 是 NVIDIA Kumo Tabular 小型回归模型(small regressor)的 ONNX 转换版,一个免训练的表格数据(tabular data)预测模型:给它一批带标签的上下文行,一次前向推理就能预测查询行的目标值。本文带你完整读懂它的 3 个输入张量(x、y_context、categorical_mask)和 1 个输出张量(999 分位数 logits),帮你快速打通"数据进、预测出"的整条链路。

📦 这个模型是什么

  • 任务:表格回归(tabular regression),基于上下文学习(in-context learning),无需微调训练
  • 文件:onnx/model.onnx + onnx/model.onnx_data,fp32 精度,约 120 MB(外部数据格式)
  • 特点:行数和列数均为动态形状,支持 WebGPU / WASM / CPU 推理,可用 Transformers.js 的 AutoModel(device: "webgpu")加载

模型元信息(大小、任务、输入说明)可在 config.json 中查到;权重许可证见 LICENSE(OpenMDW-1.1)。

🔍 输入张量速查表

该模型图是内部模型 _KumoTabular.forward 的直接导出,共 3 个输入(见 conversion/export_onnx.py 中的输入命名):

张量名 形状 类型 含义
x [R, C] float32 特征矩阵:上下文行在前,查询行在后,且必须是预处理后的值
y_context [R_context] float32 上下文行的目标值,已用上下文均值和总体标准差标准化
categorical_mask [C] bool 每一列是否来自类别特征(categorical feature)

几个新手最容易踩的点:

  • x 是一整块矩阵:上下文行和查询行拼在一起喂进去,而不是分两次调用;查询行数 = R - R_context
  • y_context 只对应上下文行:长度是上下文行数 R_context,不包含查询行
  • 输入必须"预处理完毕":模型图不含数据清洗逻辑,它期望的是已完成标准化的数值(详见下文)

📐 动态形状边界

从 conversion/export_onnx.py 可见导出的动态维度约束:

  • 总行数 R:4 ~ 65536
  • 上下文行数 R_context:2 ~ 65536
  • 列数 C:1 ~ 512

也就是说,同一份模型文件可以处理大小差异很大的表格,无需重新导出。

📤 输出:999 个分位数的 logits

输出只有一个张量 logits,形状 [R_query, 999]:

  • 每一行对应一个查询行,999 列是标准化目标值上 q001…q999 分位数的预测(升序排列)
  • 换算成真实预测值的三步:排序 → 乘以上下文标准差 → 加上上下文均值
  • 点估计(point estimate) 就是这 999 个分位数的均值

为什么不直接输出一个数?输出完整分位数分布让模型能表达"不确定性":你可以取均值做点估计,也可以取 q010/q090 等构造预测区间。回归头的输出列数 num_outputs: 999 同样写在 config.json 里,与分类头的 10 个类别概率形成对照。

⚙️ 输入预处理:你必须自己做的部分

模型图期待的是上游配方(sdm 的 recipe)处理过的数值,主要包括:

  1. 数值列:转 float、标准化(standardize)、截断到 ±100、sigma-clip(4σ 截断)
  2. 类别列:类别对齐编码 + 高频类别计数列(min_cardinality=50),再走数值管线
  3. 目标列:用上下文均值/标准差标准化

仓库内 conversion/fixtures.py 保留了这份确定性配方的完整实现(deterministic_recipe),是理解每个张量取值规则的最佳参照;浏览器端 TypeScript 移植也用它做了逐值对拍。

🧪 精度验证与推理环境

  • 导出方式:torch.onnx.export(dynamo,opset 20),其中 aten.remainder.Scalar 自定义降级为 ONNX Mod
  • ONNX Runtime(CPU)对照 PyTorch:真实数据集(diabetes 442×10、California housing 1500×8)最大误差 4.4e-5
  • WebGPU(Chrome + M3 Pro):最大误差 ≤ 2e-4,端到端点估计与 sdm 的相对误差在 6e-6 以内

验证细节见 README.md 的"Conversion and checks"小节。

❓ 常见问题

Q:能不能直接把原始 CSV 的数值喂给 x? 不能。必须先完成标准化、截断、sigma-clip 等预处理,否则输出会严重偏离。参考 conversion/fixtures.py 中的配方顺序。

Q:categorical_mask 全为 false 可以吗? 可以,只要你的数据全是数值列;一旦有类别列(哪怕已编码成整数),对应列必须标 true,模型内部依赖它做列分组。

Q:查询行为 0 行会发生什么? 导出约束要求 R ≥ 4 且 R_context ≥ 2,查询行数 = R - R_context,请保证至少 1 行查询。

📁 相关文件清单

文件 说明
README.md 模型图接口、转换与校验说明
config.json 架构名 KumoTabular、输入描述、num_outputs: 999
onnx/model.onnx ONNX 计算图
onnx/model.onnx_data 外置权重数据
conversion/export_onnx.py 导出脚本与输入/输出命名定义
conversion/fixtures.py 确定性预处理配方与黄金测试数据生成
LICENSE OpenMDW-1.1 许可证

读懂了这 4 个张量(x、y_context、categorical_mask → logits),你就能在任何支持 ONNX 的环境中调用 kumo-tabular-small-regressor-ONNX:把预处理做对,分位数换算做对,一次前向推理即可拿到预测值。

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