f
fbybl/time-series-transformer-tourism-monthly
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Time Series Transformer Tourism Monthly 适配部署文档

简介

本项目基于 Hugging Face 社区提供的 huggingface/time-series-transformer-tourism-monthly 模型,在昇腾 910 NPU 环境下完成适配与部署。该模型专门针对 monash_tsf 基准中的旅游月度数据训练,能够根据历史 24 个月的客流量数据,自动学习周期性模式(如年度旺季波动)并输出未来 24 个月的概率预测结果。

模型采用经典的 Seq2Seq Transformer 架构,编码器和解码器各 2 层,注意力头数为 2,隐藏层维度 26。整体模型体量极小(仅 30K 参数),加载速度快,适合资源受限场景下的快速部署。输出的 Student-t 分布通过 100 路并行采样生成预测区间,为业务决策提供完整的置信度信息。

部署方式采用 transformers 运行时直接加载模型权重,配合 FastAPI 提供 HTTP 服务接口。模型权重存放在本地路径,无需每次启动从远端拉取。所有算子均通过 PyTorch 原生接口经 torch_npu 桥接至昇腾 CANN 后端执行,无需修改模型源代码或引入额外适配层。

验证环境

以下为本次适配过程中实际使用的环境配置,供复现时参考对照:

项目配置
NPU 型号Ascend 910 (HBM 64GB)
物理芯片编号Phy-ID 14 (Chip 0)
CANN 工具包8.5.1
npu-smi 版本25.5.5
操作系统架构aarch64
Python 解释器3.11.14
PyTorch 版本2.9.0
torch_npu2.9.0.post1
HuggingFace Transformers4.57.6
依赖管理pip (requirements.txt)

环境检查命令:

python -c "import torch; print('torch:', torch.__version__)"
python -c "import torch_npu; print('torch_npu:', torch_npu.__version__, 'NPU available:', torch.npu.is_available())"
python -c "import transformers; print('transformers:', transformers.__version__)"
npu-smi info

服务启动

安装依赖

使用 pip 一键安装所需依赖库:

pip install -r requirements.txt

命令行模式

无需额外参数即可运行默认推理示例:

python inference.py

程序会加载模型并自动构造一组模拟的旅游客流量序列(包含季节性和趋势成分),随后输出未来 24 个月的预测统计结果。如需自定义输入,准备 JSON 文件并指定 --input 参数:

python inference.py --input my_data.json

HTTP 服务模式

通过 --serve 参数启动推理服务,默认监听 8010 端口:

python inference.py --serve --port 8010

服务启动后,可通过 RESTful 接口调用:

# 健康检查:确认服务是否就绪
curl http://127.0.0.1:8010/health

# 推理请求:传入历史数据获取预测
curl -X POST http://127.0.0.1:8010/predict \
  -H "Content-Type: application/json" \
  -d '{"past_values": [5100, 5750, 6200, 7000, 6750, 6400, 6250, 6650, 7400, 8100, 7700, 7100, 6750, 7350, 7950, 8550, 8250, 7850, 7450, 8050, 8750, 9350, 8950, 8450, 8050, 8650, 9450, 9750, 9250, 8850, 8350, 8950, 9650, 10150, 9750, 9250, 8750, 9350, 9950, 10550, 10050, 9550, 9050, 9650, 10250, 10750, 10350, 9850, 9350, 9950, 10550, 11150, 10650, 10150, 9650, 10250, 10850, 11450, 10950, 10450, 9950]}'

Smoke 验证

部署就绪后,快速执行以下步骤确认服务处于正常工作状态:

第一步:检查模型加载是否成功

python inference.py 2>&1 | grep "参数量"

返回示例:参数量=30,537

第二步:确认服务接口响应正常

curl -s http://127.0.0.1:8010/health | python3 -c "import sys,json;print(json.load(sys.stdin)['status'])"

返回:ok

第三步:验证预测结果格式

curl -s -X POST http://127.0.0.1:8010/predict -H "Content-Type: application/json" -d '{"past_values": [5100, 5750, 6200, 7000, 6750, 6400, 6250, 6650, 7400, 8100, 7700, 7100, 6750, 7350, 7950, 8550, 8250, 7850, 7450, 8050, 8750, 9350, 8950, 8450, 8050, 8650, 9450, 9750, 9250, 8850, 8350, 8950, 9650, 10150, 9750, 9250, 8750, 9350, 9950, 10550, 10050, 9550, 9050, 9650, 10250, 10750, 10350, 9850, 9350, 9950, 10550, 11150, 10650, 10150, 9650, 10250, 10850, 11450, 10950, 10450, 9950]}' | python3 -c "import sys,json;d=json.load(sys.stdin);print('Prediction mean (first 3):', d['predictions_summary']['mean'][:3])"

正常返回为三个浮点数构成的预测均值列表。

性能参考

基于实际运行环境采集的性能数据如下:

测试项耗时备注
模型加载(含权重初始化)1.15s首次加载,后续可缓存
单次推理(100 样本)0.51s生成 24 步预测及分布统计
单次推理(50 样本)0.26s减少样本数可降低延迟
服务启动到就绪~3s含模型加载和端口监听

NPU 资源占用情况(推理期间):

  • AICore 利用率:< 1%(模型过小,未充分饱和)
  • 显存占用:约 116 MB
  • 功耗:整卡约 164W(含同卡其他进程)

延迟优化建议:若对实时性要求较高,可考虑减少并行样本数(修改 config.num_parallel_samples),或使用 ONNX 导出进行推理加速。

精度测评

利用包含季节性周期和线性趋势的模拟数据进行精度验证,评估模型在昇腾 NPU 上的推理输出质量:

预测统计量验证(24 步预测):

  • 均值的范围:约 8700 ~ 10700 之间,呈现与输入数据一致的年度季节性波动
  • 标准差:1300 ~ 1800,反映旅游客流量在旺季和淡季的波动差异
  • 中位数与均值接近,说明预测分布相对对称

样本多样性验证:

  • 100 个并行样本在预测步长内呈现合理的多样性
  • 早期预测步(前 6 步)样本间标准差较小,置信度较高
  • 远期预测步(后 6 步)样本发散度增大,置信区间自然展宽

与 CPU 推理对比:

  • NPU 推理输出与 CPU 推理结果在统计分布上一致
  • 数值误差在 1e-5 量级以内,归因于浮点运算顺序差异
  • 无精度损失或系统性偏差

注意事项

  1. 数据长度要求:输入数组长度必须为 61,不可多也不可少。这是因为模型内部需要从历史序列中提取 16 个不同滞后步(从 lag-1 到 lag-37)的特征,少于 61 步会因滞后越界而报错。
  2. 设备选择:如果系统有多张 NPU 卡,可通过 --device npu:1 指定在空闲卡上运行。建议运行前先执行 npu-smi info 查看各卡负载情况,避免与已有任务争抢资源。
  3. 端口占用:服务默认使用 8010 端口。如果提示端口已被占用,请换用其他端口(如 8011、8012 等),同时注意不要与其他窗口正在运行的推理服务端口冲突。
  4. 数据预处理:本仓的 build_time_features 函数使用简化的周期性编码,实际业务场景中建议替换为基于真实日历(月份、季度、节假日等)的时间特征,以获得更准确的预测结果。
  5. 首次运行:模型首次加载时会触发 PyTorch 的 JIT 编译和算子缓存,可能略慢于后续调用。建议服务启动后先发送一次 warmup 请求再进入正式使用。
  6. 版本兼容性:该模型在 transformers 4.27.0 及以上版本中可用。如果遇到 TimeSeriesTransformerForPrediction 导入错误,请先升级 transformers 到最新版本。
  7. 模型仓标签:本仓库在 hardware 标签中标注了 NPU,搜索时可通过此标签快速定位。