TabSTAR 在昇腾 NPU 上的部署

TabSTAR：一种具有语义目标感知表示的基础表格模型 （arXiv:2505.18125，MIT 许可 © Alan Arazi 等）——已部署于昇腾 910 NPU，基于 torch_npu 运行。

alana89/TabSTAR 是一种表格基础模型，专为包含自由文本列的表格数据的迁移学习而设计。它解冻了预训练的文本编码器（intfloat/e5-small-v2），并将目标令牌作为输入，使模型能够学习任务特定的嵌入表示。其架构不依赖任何数据集特定参数：

• 文本编码器 —— intfloat/e5-small-v2（BERT，隐藏层维度 384），解冻状态，输入为语言化特征字符串（Predictive Feature: <col>\nFeature Value: <value>）及目标令牌（Target Feature: <label>\nFeature Value: <class>）。
• 数值融合模块（NumericalFusion） —— 逐列标量嵌入器 + 两层 Transformer 融合块，将每个文本嵌入与其数值嵌入进行融合。
• 交互编码器（InteractionEncoder） —— 6 层 Transformer 编码器（d_model 384，6 个注意力头），作用于特征序列之上。
• 预测头（PredictionHead） —— 基于目标令牌位置的多层感知机，输出类别逻辑值（或单个回归值）。

运行时：torch_npu + FastAPI 服务（/v1/classify、/v1/regress）。vLLM-Ascend 0.18 不适用：其注册表中没有非自回归表格 LLM 条目，且该模型是自定义的 TabStarModel（model_type 为 tabstar），因此推理直接在 NPU 上运行基础模型权重。

环境配置

文件说明

• inference.py —— TabSTAR 推理引擎（在 NPU 上加载基础权重，零样本预测）
• server.py —— FastAPI 服务（/health、/v1/classify、/v1/regress）
• start_serve.sh —— 一键启动脚本（npu:1:8040）
• download_model.py —— 幂等权重下载脚本（hf-mirror + sha256 校验）
• npu_smoke.py / test_server.py / verify_npu_vs_cpu.py —— 验证脚本
• tabstar/ —— 内置的 tabstar 包，包含 NPU 补丁（patches/tabstar_ascend_npu.patch）

快速开始

pip install -r requirements.txt            # peft skrub joblib ...
python3 download_model.py                  # weights -> /data/.cache/models
bash start_serve.sh                        # npu:1:8040
python3 test_server.py                     # classify + regress smoke tests
python3 verify_npu_vs_cpu.py               # NPU vs CPU numerical agreement

该服务提供两个零样本推理端点。每个请求携带一个带标签的小型训练表（用于拟合语义标签映射器/缩放器）以及一个无标签的测试表：

curl -s localhost:8040/v1/classify -H 'Content-Type: application/json' \
  -d '{"dataset":"imdb","test_size":0.1}'
# convenience demo using the official imdb.csv quickstart

或发送原始表格：

{
  "train": [{"review": "A hilarious comedy", "rating": 7.2, "label": "comedy"}, ...],
  "target": "label",
  "test": [{"review": "A touching drama", "rating": 6.8}, ...]
}

适配说明（NPU）

针对内置的 tabstar 包应用了两处小型补丁（见 patches/tabstar_ascend_npu.patch）：

1. arch/arch.py — 强制将 E5-BERT 文本编码器的 attn_implementation 设为 "eager" （aclnnFlashAttentionScore 在 torch_npu 上针对该模型历来不稳定）。
2. preprocessing/feat_types.py — 将 pandas str 类型（pandas≥3.0）视为 is_numerical_feature 中的文本特征（上游期望 object 类型，否则会报错）。

模型的其余部分（eager 模式 Transformer 块、linear/ReLU/softmax 头、scaler）天然 兼容 NPU，无需修改即可运行。

测试用例

官方快速上手演示 — IMDB 电影表（Genre_is_Drama，文本 + 数值列）， 零样本（无微调）：

许可证与来源

模型权重：alana89/TabSTAR（cc-by-4.0），通过 hf-mirror.com 拉取。代码：MIT © Alan Arazi 等（tabstar 1.1.16 包，内置并附带 2 个 NPU 补丁）。