WeHub Tabular Intelligence API

5 分钟开始

先通过 [email protected] 向 WeHub 申请一枚 preview credential。请把它保存在权限受控的本机文件或 secret manager 中，不要写进 notebook、Git、URL 或日志。

export WEHUB_API_KEY="<API_KEY>"

curl -sS https://tabular.wehub.us/v1/models \
  -H "Authorization: Bearer ${WEHUB_API_KEY}"

curl -sS https://tabular.wehub.us/v1/models/tabpfn-v3-regression/predict \
  -H "Authorization: Bearer ${WEHUB_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

可交互 schema 位于 /docs；机器可读定义位于 /openapi.json。公开 health 不会加载模型。

到底传过去的是什么？

是数据。更准确地说，一次请求传的是一个自包含的监督回归任务：原始语义列、带标签的参考数据，以及需要预测的 query rows。它不是已经 one-hot 的矩阵，也不只是一个孤立的待预测样本。

columns

原始列名和 numeric、categorical、boolean 语义类型。

x_train + y_train

本次任务的带标签参考表；backend 只从这里建立 preprocessing / prediction context。

x_query

真正需要模型输出预测值的行；列顺序与 columns 完全一致。

可选的 dataset 只描述名称、固定 split 与 provenance。调用 /evaluate 时可以再提供 y_query；它只在 gateway 计算 RMSE、MAE、R²，不进入模型 worker、fit 或 preprocessing。

数据路径：payload 通过 HTTPS 到达 DGX2。当前服务不把 features、targets 或 predictions 写入日志或磁盘，但仍是 research preview；请勿发送敏感、受监管或生产数据。

为什么当前选择 typed JSON？

JSON 不是在宣称“表格天然应该长成 JSON”，它是三个不同模型之间的一层稳定 transport contract。

类型显式：CSV 会把数字、类别代码、布尔值和缺失状态压成文本并触发猜测；columns.kind 让语义在进入模型前可检查。
不强迫 one-hot：调用方保留原始 semantic columns；每个 backend 可以使用符合自身机制的 preprocessing。
跨语言、易调试：Python、JavaScript、R、Java 或普通 curl 都能生成同一 request。
先验证再占 GPU：shape、类型、行数、cells 和 body size 可以在模型加载前 fail closed。
可复核：规范化后的 payload 可以生成稳定 request fingerprint，并和 source、checkpoint、configuration、timing 一起写入 receipt。

因此 typed JSON 是内部的 canonical request；未来增加文件上传，也应该先把文件转换成这份 contract，再进入现有验证和模型路径。

能否直接上传 CSV / Parquet？

可以，而且是合理的下一层接口；但当前公网 v0.4 尚未开放文件上传 route。 现在的 /predict 和 /evaluate 只接受 JSON。

一个裸表格文件本身不足以安全地产生预测：服务还必须知道哪一列是 target、哪些行属于 train/query，以及哪些自动类型推断需要人工覆盖。若这些信息靠猜测，最危险的结果不是报错，而是用错误 split 或错误变量类型成功运行。

建议的单文件约定是：文件保留原始特征列，另有一个显式 role column；调用参数声明 target 和 role，不靠空值猜 split。

POST /v1/models/{model_id}/predict-file
Content-Type: multipart/form-data

file: table.parquet              # 或 table.csv
target_column: price
role_column: __role__            # 值只能是 train / query
schema_overrides: optional       # 覆盖有歧义的类型推断

__role__,area,city,has_elevator,price
train,80.5,Shanghai,true,520.0
train,120.0,Beijing,false,610.0
query,95.0,Beijing,true,

内部 ingestion 应按固定顺序工作：安全解析文件 → 依据显式 role 切分 → 只在 train rows 上推断或绑定类型 → 转成 typed JSON → 运行现有 contract validation → 调用模型。响应还应增加 ingestion receipt，记录文件 hash、列映射、推断类型、覆盖项、train/query 行数与 warning。

建议的支持顺序：先做 CSV（普及）和 Parquet（类型保真）；Excel 的多 sheet、公式、日期与宏带来更多歧义和攻击面，等真实需求出现后再决定。服务不应接受远程 URL、宿主机路径或可执行内容。

Typed-table contract

列的语义类型由 columns 显式给出；缺失值使用 JSON null。服务不会要求调用者先把 categorical column one-hot 展开成普通 dense matrix。

{
  "profile": "baseline-v1",
  "dataset": {"name": "demo", "split_id": "train-query-v1"},
  "columns": [
    {"name": "age", "kind": "numeric"},
    {"name": "city", "kind": "categorical"},
    {"name": "is_member", "kind": "boolean"}
  ],
  "x_train": [[21, "Shanghai", true], [37, "Beijing", false], [null, "Shanghai", true]],
  "y_train": [1.2, 2.7, 1.8],
  "x_query": [[29, "Beijing", true]]
}

/evaluate 比 /predict 多一个与 x_query 等长的 y_query；它只在 gateway 计算 RMSE、MAE 与 R²，不会传给模型 worker。

可用模型

tabpfn-v3-regression

TabPFN v3 regression，当前默认模型；8 estimators，fixed random state 22。

tabfm-v1-regression

TabFM v1 regression；32 estimators。upstream policy：research-only、non-commercial、non-production。

limix-2m-regression

LimiX-2M regression。upstream policy：academic research；commercial use requires authorization。

模型列表和每个 checkpoint 的 hash、source/config 信息通过 GET /v1/models 与 GET /v1/models/{model_id} 返回。API 不改变上游代码或权重许可。

Routes

Route	Auth	行为
`GET /health/live`	公开	进程存活；不加载模型
`GET /health/ready`	公开	队列和 worker lifecycle；不加载模型
`GET /v1/models`	Bearer	发现模型、配置和资产 receipt
`GET /v1/models/{id}`	Bearer	单模型信息；不加载模型
`POST /v1/models/{id}/predict`	Bearer	返回 predictions 与 receipt
`POST /v1/models/{id}/evaluate`	Bearer	另返回 RMSE、MAE、R²

响应中的 X-Request-ID 可由客户端用合法的 X-Request-ID 提供，或由服务生成。receipt 包含 request fingerprint、source/checkpoint hash、configuration 与 cold start、fit、predict、queue wait、total service timing。

容量与队列

原始 semantic features	1–500
train rows	2–10,000
query rows	1–10,000
train + query cells	最多 2,000,000
request body	最多 32 MiB
GPU concurrency	1 个 active inference；最多 4 个等待请求
idle lifecycle	模型 worker 默认空闲 900 秒后释放

这些是 API 的当前工程 guard，不是任何模型的 benchmark eligibility 定义。特别是：categorical one-hot 后的 transformed dimension 不参与原始 feature gate。

Evidence boundary

这是 invite-only research preview，不是 production SLA。 当前 origin 在 DGX2，单节点、单 shared credential、单 GPU 串行 inference；没有 durable async job、per-customer quota、HA、计费或敏感数据合规承诺。

上线验收包含 unit tests、公开 TLS/auth/models probe，以及至少一次真实 GPU inference。单任务结果只证明该 request path 与模型 artifact 可工作，不证明模型在全部 heterogeneous regression tasks 上的普遍优越性。

错误处理

401：缺少或错误 Bearer credential。
404：未知 model ID。
413：request body 超过服务限制。
422：typed-table schema、shape、值或容量验证失败。
429：串行 inference 队列已满；尊重 Retry-After。
500：模型 inference 失败；记录 X-Request-ID 后联系 WeHub，不要发送 secret 或完整敏感 payload。