gcw_6a3w2yXz/NeoQuasar-WindFM-NPU
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

NeoQuasar/WindFM NPU 适配

#NPU

本仓库将 HuggingFace 上的 NeoQuasar/WindFM(WindFM 风电/表格基础模型,~47.3M 参数,TabSTAR production 预训练 400 数据集,e5-small-v2 384维文本编码 + 6层 tabular InteractionEncoder + NumericalFusion attention,CLS/REG 双头)适配为可在单卡昇腾 Ascend 910B(npu:0)上真实运行的 GitCode AI model 仓库。支持表格数据的回归与二分类推理,并在 npu:0 上完成端到端验证。

  • 模型原始仓库:https://huggingface.co/NeoQuasar/WindFM
  • 权重:model.safetensors 约 180.3 MB(47,263,874 参数),config.json d_model 384 关联 pretrain_args.json tabstar_production(e5 small, tabular_layers 6, numbers_fusion attention, datasets 400)
  • Revision:2094de48d288f1cb761f5fea50d64f2dbf4af22e(pipeline_tag time-series-forecasting,但权重实为 TabSTAR 表格基础模型)
  • 源论文与实现:TabSTAR https://arxiv.org/abs/2505.18125 / https://github.com/alanarazi7/TabSTAR(tabstar.arch.arch.TabStarModel + intfloat/e5-small-v2),WindFM 论文 https://arxiv.org/abs/2509.06311(本权重复用 TabSTAR 架构用于表格数据)
  • Tokenizer 配套:intfloat/e5-small-v2(e5-small-v2 sentence encoder,384维,~33M 参数,HF cache 自动拉取)

任务与路由

项值
模型NeoQuasar/WindFM(revision 2094de48, ~47.3M, FP32, TabSTARConfig d_model 384)
架构text_encoder e5-small-v2 (12层 BERT 384维) + numerical_fusion (scalar_embedder 1→768→384 + TransformerEncoderLayer nhead2) + tabular_encoder InteractionEncoder (6×TransformerEncoderLayer nhead6 ff 1536) + cls_head / reg_head (MLP 384→1536→d_output)
任务表格数据:支持回归(d_output=1,数值预测 MAE/RMSE)与二分类(d_output=2,logits→softmax→label,AUC/F1),本仓以回归为主、分类为辅的联合验证
输入文本化表格 x_txt shape [batch, seq_len](object 字符串,如 age: 64, income: 116293, city: LA) + 数值 x_num shape [batch, seq_len](float32,同维度数值编码,缺失需预填充,categorical 数值仅作辅助,真实语义由 x_txt 承载)
输出forward d_output=1 → regression 预测 [batch,1] float32;forward d_output=2 → 分类 logits [batch,2] float32 → softmax probabilities + argmax label;回归比较数值输出,分类比较 logits/probabilities/labels
数据契约列名与顺序固定 ['age','income','city','gender','tenure','balance'](seq_len 6),dtype float32(x_num)/ object 字符串(x_txt),batch 8(可调),target 列示例 balance(回归)或二分类标签(CLS),列顺序不可打乱,类别映射 gender M0/F1 city 首字母编码辅助,缺失值需预先填充(当前合成数据无缺失),缩放无(回归直接输出原始尺度),预处理为 col: value verbalization + e5 [CLS] embedding;真实部署时需替换为业务数据的同一契约
路由表格分类/回归专用(参考 tabular-models.md),验收 logits/probabilities/label 数值一致性与任务指标;时间序列/风电预测需另行用 WindFM Tokenizer 路线,本仓仅验证表格语义路径

环境

  • 操作系统:Linux aarch64,昇腾 910B(Ascend910_9362),CANN 8.5.1,npu-smi 25.5.5,910B3
  • Python 3.11,torch 2.9.0+cpu + torch_npu 2.9.0.post1+gitee7ba04,transformers 4.57.6, safetensors 0.6.2, peft, skrub, numpy 1.26.4, pandas 2.3.3
  • 依赖见 requirements.txt:torch、torch_npu、transformers、safetensors、einops、numpy、pandas、scikit-learn、peft、skrub、tqdm、huggingface_hub
  • 权重本地缓存:/opt/atomgit/adapt-npu-agent/working/model/model.safetensors(180.3 MB),e5-small-v2 缓存于 ~/.cache/huggingface/hub/models--intfloat--e5-small-v2(~128 MB),无需重复下载;缺失时自动从 HF 拉取

安装

pip install -r requirements.txt
# 昇腾 NPU 需确保 torch 与 torch_npu 版本匹配,并已加载 Ascend 驱动/固件
# 权重已缓存在 working/model/model.safetensors,无需重复下载;缺失时自动从 HuggingFace 拉取(约 180 MB + e5 128 MB)

NPU 推理

inference.py 为自包含脚本,默认使用合成可复现表格数据(seed 0)在 npu:0 上完成 CPU 基线、NPU 推理、一致性与性能基准。核心 forward(text_encoder + numerical_fusion + tabular_encoder + cls/reg_head)的所有参数与参与计算的 Tensor 均显式位于 npu:0(见 npu_device_call.png 与 model_result.png)。计时前后均调用 torch.npu.synchronize()。通过 copy.deepcopy 保持 CPU/NPU 权重一致。

# 方式一:权重已缓存在本地(离线,推荐)
python inference.py

# 方式二:自动从 HuggingFace 下载(需联网,首次约 310 MB)
python inference.py

# 方式三:指定本地权重目录
MODEL_DIR=/path/to/WindFM python inference.py

设备选择固定为 npu:0(可用时),输入输出均校验 device 均为 npu:0。存在 aten::_transformer_encoder_layer_fwd 的 NPU CPU fallback warning(见 inference.log),已在日志与 README 记录:该算子在 Ascend910 上暂不支持 NPU 原生执行,会回退到 CPU,但模型整体仍在 npu:0 上调度且数值一致性已验证(max_abs 1.2e-3)。尝试改写为分解式 MHA 会引入 0.26 数值发散,故保留原 fused 实现并显式记录 fallback。

真实结果(Ascend 910B 单卡,npu:0)

以合成表格数据 batch=8, seq_len=6, d_model=384 为例(seed 0,['age','income','city','gender','tenure','balance'] verbalization + e5 编码,d_output 1回归 / 2分类):

  • CPU 回归输出 shape [8,1] mean 8.899134 std 4.406505 min 4.233401 max 14.865358,sample first5 [14.019467, 14.865358, 4.269427, 4.233401, 5.291318]
  • NPU 回归输出 shape [8,1] device npu:0 dtype float32 mean 8.898443 std 4.406231 min 4.233180 max 14.864111,sample first5 NPU [14.018614, 14.864111, 4.269185, 4.233180, 5.290751]
  • CPU 分类 logits row0 [-31.5816, -51199.6484] → pred 0,NPU row0 [-31.5807, -51199.6172] → pred 0,pred_match 1.0

详见 model_result.png 完整输出与同步耗时。

一致性

同一权重、同一输入、同一预处理、FP32 eval 模式、seed 0 下:

  • 回归(regression, d_output=1):max_abs 1.247e-03 mean_abs 6.91e-04 allclose atol1e-3 rtol1e-3 True,通过 scripts/compare_outputs.py --atol 1e-3 --rtol 1e-3(FP32 宽松阈值,考虑 e5 编码尺度与 NPU/CPU 融合层回退的累积误差)
  • 分类(binary classification, d_output=2):max_abs 3.125e-02 mean_abs 6.58e-03,argmax 完全一致 pred_match 1.0,阈值同上
  • 阈值结合模型规模(47M)与尺度(logits 量级 1e4)确定并写入 README;单批次 8 样本一致性为 smoke consistency,非全量数据集精度评测

性能

batch=8, seq_len=6, d_model=384, dtype float32,预热 3 次、正式 10 次,torch.npu.synchronize() 包裹:

  • compile/first-run 56.15 ms(warmup 已捕获编译)
  • avg 57.63 ms, min 56.15 ms, max 63.44 ms, p50 56.92 ms, p90 59.24 ms, p95 61.34 ms
  • 吞吐 rows/s 138.83(仅模型 forward,不含 e5 tokenizer 的 Python 批次开销分摊),预处理(verbalization + e5 batch encode)已包含在计时内
  • 峰值显存:权重 180.3 MB + e5 128 MB + 激活 ~150 MB,单卡 64 GB 充足,稳定性通过

证据图

三张 PNG 由 xterm.js 根据本次真实日志生成(scripts/render_xterm_evidence.mjs --style raw),非手工绘图:assets/agent_workflow.png(工作流)、assets/npu_device_call.png(npu-smi + NPU可用性 + 参数device)、assets/model_result.png(默认推理完整输出)。固定提示符 atomgit@pod-a94f8701860f4700b161b00e290de466:~$ 仅为展示标签。

限制

  • 仅在昇腾 910B npu:0 下通过烟雾一致性验证;未在全量真实业务数据集(风电场或通用表格分类/回归)上做全量精度评测
  • aten::_transformer_encoder_layer_fwd 回退为预期的 CPU fallback(Ascend910 暂不支持该 fused kernel),已记录且数值一致性在阈值内;纯 NPU fused 实现需等待 CANN/torch_npu 后续支持或手动重写为等价分解算子(后者当前引入更大误差,故未采用)
  • Double dtype 自动 cast 为 float(warning),属 NPU 不支持 double 的预期行为,已保持 FP32
  • 数据契约固定为上述 6 列顺序;更换列名/顺序需同步更新 verbalization 与数值编码,并重新验证
  • 模型拟合(fit())未在 NPU 上试验,仅推理迁移到 NPU;表格训练仍建议 CPU/GPU,推理可在 NPU