weixin_72661020/t0-alpha
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

t0-alpha 昇腾 NPU 部署文档

1. 模型简介

模型名称: t0-alpha(theforecastingcompany/t0-alpha)

模型链接: theforecastingcompany/t0-alpha

模型描述: t0-alpha 是 The Forecasting Company 发布的首个开源时序预测基础模型(t0 系列),基于解码器风格的 patch transformer,输出多分位数概率预测(probabilistic multi-horizon forecasting),原生支持单变量/多变量预测、带历史或已知未来协变量的预测以及多步长(multi-horizon)预测。模型在 GIFT-Eval 上 CRPS 0.4941 / MASE 0.7240,fev-bench Skill score 42.2。官方实现见 theforecastingcompany/tfc-t0。

模型架构:

  • decoder-style patch transformer(patch_size=32),时间轴自注意力 + 变体轴 group 自注意力交替(每 3 层 1 个 group-attention 层)
  • 时间轴自注意力使用 time-aware rotary embeddings;变体轴 group attention 让同一样本的变体互相 attend
  • pre-norm RMSNorm + SwiGLU 前馈 + quantile head;推理时目标与历史变体用因果滑动统计归一化(arcsinh 变换)
  • 训练时原生分位数:0.1 / 0.25 / 0.5 / 0.75 / 0.9(请求其他分位数由推理时插值生成)
  • 单次前向解码最长 1024 步;更长 horizon 用自回归 rollout

关键超参(config.json): embed_dim=512,num_layers=24(16 时间注意力 + 8 group 注意力),num_heads=8,mlp_hidden_dim=2048,patch_size=32,dropout=0.1

参数规模: 约 102M(实测加载 101.64M),FP32 权重约 0.4GB(model.safetensors)。

2. 环境依赖

依赖项版本说明
Python3.11系统 /usr/local/python3.11.14
torch / torch_npu2.9.0 / 2.9.0.post1昇腾 NPU 适配版本(系统安装)
t0(tfc-t0)0.3.0官方源码包(GitHub,未发布 PyPI),拷到 libs 直接 import
rotary-embedding-torch0.9.x官方时间注意力依赖
jaxtyping / typeguard0.3.x / 4.x形状注解 / 类型守卫
einops / safetensors / huggingface-hub / numpy系统已装权重加载与张量运算
昇腾 CANN8.5.1昇腾驱动/运行时

依赖安装(独立目录,勿污染共享环境):

mkdir -p /app/t0-alpha/libs
# 纯依赖 --no-deps 安装(--target 若不加 --no-deps 会把 CUDA torch 装进 libs,遮蔽系统 torch_npu!)
pip install --target /app/t0-alpha/libs --no-deps -i https://pypi.tuna.tsinghua.edu.cn/simple \
    rotary-embedding-torch jaxtyping typeguard
# 官方 t0 源码包(PyPI 无 tfc-t0,GitHub 拉源码拷 t0/ 进 libs)
git clone --depth 1 https://github.com/theforecastingcompany/tfc-t0.git /tmp/tfc-t0
cp -r /tmp/tfc-t0/t0 /app/t0-alpha/libs/
# 运行时叠加:
export PYTHONPATH=/app/t0-alpha/libs

3. 推理步骤

3.1 环境准备

source /usr/local/Ascend/ascend-toolkit/latest/set_env.sh
npu-smi info            # 检查 NPU 设备
export PYTHONPATH=/app/t0-alpha/libs

3.2 运行推理

# 方式一:只传 --model_path(内置确定性示例序列,自动验证预测质量)——与批量实测命令一致
python3 inference.py --model_path /app/models/t0-alpha

# 方式二:指定预测步长 / 上下文长度
python3 inference.py --model_path /app/models/t0-alpha --horizon 128 --context_len 1024

# 方式三:用自有数据(npy/npz/csv/txt,shape (B,T) 或 (T,))
python3 inference.py --model_path /app/models/t0-alpha --input series.npy

# 方式四:bf16 加速(默认 fp32)
python3 inference.py --model_path /app/models/t0-alpha --bf16

# 方式五:结果写 JSON
python3 inference.py --model_path /app/models/t0-alpha --output_json result.json

3.3 推理参数说明

参数默认值说明
--model_path/app/models/t0-alpha模型目录(含 config.json / model.safetensors)
--horizon64预测步长(未来时间步数)
--context_len512历史上下文长度
--batch2内置示例的批量序列数
--quantiles0.1,0.5,0.9请求分位数(逗号分隔,升序,(0,1))
--input / --input_file(内置示例)输入文件(npy/npz/csv/txt)
--bf16 / --fp32fp32NPU 推理精度(bf16 仅 autocast forward,权重保持 fp32)
--seed42内置示例随机种子
--output_json(空)结果写入 JSON

4. 测试样例及输出结果

样例 1:内置确定性序列(fp32, NPU, 统一实测命令)

python3 inference.py --model_path /app/models/t0-alpha

输出:

[INFO] 设备类型: npu
[INFO] 使用 fp32 推理
[INFO] 模型加载完成, 参数量: 101.64M, device: npu:0
[INFO] 使用内置确定性示例序列 (B=2, 长度=576)
[1/1] 时序概率预测 (B=2, context=512 -> horizon=64, quantiles=3):
      分位数预测形状: quantiles (2, 64, 3) (B, horizon, Q)
      中位数(0.5)形状: median (2, 64)
      中位数末 4 步: 28.81266 28.71635 28.55317 28.34018
      末步分位带: Q10=27.74353  Q50=28.34018  Q90=28.93166
      确定性信号回归: RMSE(模型中位数)=0.50500  RMSE(last-value基线)=1.73618  提升 3.4x
      耗时=0.506s (elapsed=0.505s)

推理耗时:约 0.506s(Ascend910_9362 单卡,fp32;B=2,context 512 → horizon 64)

样例 2:bf16 加速(NPU)

python3 inference.py --model_path /app/models/t0-alpha --bf16 --horizon 32

输出:

[INFO] 使用 bf16 autocast(权重保持 fp32,forward 自动混合精度)
[1/1] 时序概率预测 (B=2, context=512 -> horizon=32, quantiles=3):
      分位数预测形状: quantiles (2, 32, 3) (B, horizon, Q)
      中位数末 4 步: 25.98809 26.11281 26.33585 26.60326
      末步分位带: Q10=26.19592  Q50=26.60326  Q90=26.98840
      确定性信号回归: RMSE(模型中位数)=0.25107  RMSE(last-value基线)=1.09820  提升 4.4x
      耗时=0.506s (elapsed=0.596s)

5. Agent适配截图

5.1 Agent适配全过程截图

agent_workflow

5.2 NPU设备调用截图

npu_device_call

5.3 模型适配结果截图

model_result

6. 注意事项

  • 非 transformers 标准类:t0-alpha 是自定义架构(T0Forecaster,继承 PyTorchModelHubMixin),不能 AutoModel.from_pretrained 加载。官方实现只通过 tfc-t0 包分发,PyPI 上没有该包(需从 GitHub theforecastingcompany/tfc-t0 拉源码,把 t0/ 目录放入 PYTHONPATH 即可 from t0 import T0Forecaster)。
  • --target 安装依赖必须加 --no-deps:rotary-embedding-torch 声明依赖 torch,不加 --no-deps 会把一套 CUDA torch(如 2.13)装进 /app/t0-alpha/libs,运行时 sys.path 优先会把系统 torch_npu 对应的 torch 2.9.0 遮蔽,导致 NPU 不可用。
  • huggingface_hub 版本:系统 0.36 可直接 from_pretrained(本地目录) 加载 config.json + model.safetensors(实测通过);模型代码对 dtype 参数的转发按 huggingface_hub 1.x 设计,本脚本不依赖该转发,bf16 通过直接设置 model._amp_dtype 实现,规避版本差异。
  • NPU 精度与输入:输入序列必须 float32(predict() 内部已统一转 float32);bf16 时仅 autocast forward(matmul/linear 走 bf16,softmax/norm 保持 fp32),权重仍为 fp32,精度损失极小。
  • 推理 API:model.predict(context, horizon=, quantiles=) → out.quantiles (B,horizon,Q)、out.median (B,horizon);context 支持 [T] / [B,T] / [B,V,T],NaN 视为缺失,长序列 >1024 步 horizon 自动自回归 rollout。
  • 依赖隔离:所有模型专属包装到 /app/t0-alpha/libs,运行时 PYTHONPATH 叠加,不污染共享环境;torch / torch_npu / einops / safetensors / huggingface-hub 用系统安装版本。
  • 权重:model.safetensors(约 0.4GB)不入库,存放于 /app/models/t0-alpha;许可证 Apache-2.0。