冬
gcw_IDzXRVNw/time-series-transformer-tourism-monthly-ascend
Model Introduction
Files & versions
Pull Requests
Discussion
Analysis

Time-Series-Transformer-Tourism-Monthly 昇腾 NPU 适配部署文档

1. 模型简介

Time Series Transformer 是基于 Transformer 架构的时间序列预测模型,在 tourism-monthly 数据集上训练了 30 个 epoch。

该模型采用标准的 Encoder-Decoder Transformer 结构进行时间序列预测,训练方式类似于机器翻译任务。推理时,模型自回归地生成样本。

模型架构

属性值
模型类型TimeSeriesTransformerForPrediction
参数量0.0305M (30.5K)
d_model26
Encoder 层数2
Decoder 层数2
Context Length24
Prediction Length24
Feature Size27
Attention Heads2 (encoder), 2 (decoder)
Distribution Outputstudent_t
权重精度float32

模型特点

  • Encoder-Decoder 架构: 标准 Transformer 编码器-解码器结构
  • 自回归生成: 推理时逐时间步生成预测
  • 多分布输出: 使用 student_t 分布进行预测
  • 并行采样: 支持生成多个候选预测 (num_parallel_samples=100)
  • 数据标准化: 内置 scaling 机制

输入输出格式

  • past_values: 形状 (batch_size, past_length) 的历史时间序列
  • past_time_features: 形状 (batch_size, past_length, num_time_features) 的时间特征
  • past_observed_mask: 形状 (batch_size, past_length) 的观测掩码
  • static_categorical_features: 形状 (batch_size, 1) 的静态类别特征
  • static_real_features: 形状 (batch_size, 1) 的静态实数特征
  • future_time_features: 形状 (batch_size, prediction_length, num_time_features) 的未来时间特征
  • 输出: 形状 (batch_size, num_parallel_samples, prediction_length) 的预测序列

2. 环境依赖清单

2.1 硬件要求

  • 华为昇腾系列 AI 处理器(Ascend 910B/310P 等)
  • 建议 ≥ 64 MB NPU 显存(TimeSeriesTransformer-Tourism 推理峰值约 6.6 MB)
  • 本次实测使用 910B2(单卡 64 GB)

2.2 软件依赖

依赖项版本要求说明
操作系统CentOS 7.6+ / Ubuntu 18.04+支持主流 Linux 发行版
CANN5.0.RC2+华为昇腾计算架构
Python3.10 / 3.12推荐 3.10+
PyTorch2.0.0+推荐 2.10
torch_npu与 PyTorch 版本匹配昇腾 PyTorch 扩展
transformers4.40.1模型加载(必须此版本)

2.3 安装方式

# 1) 激活已预装 torch / torch_npu 的 conda 环境
conda activate pt2100

# 2) 安装模型依赖(使用华为云源)
pip install --index-url https://repo.huaweicloud.com/repository/pypi/simple \
    transformers==4.40.1

# 3) 验证环境
python -c "
import torch, torch_npu
print('torch:', torch.__version__)
print('torch_npu:', torch_npu.__version__)
print('NPU 可用:', torch.npu.is_available())
"

3. 分步推理操作流程

步骤 1:准备工作目录

# 进入适配目录
cd /workspace/agent/time-series-transformer-tourism-monthly-ascend

# 确认上游权重存在
ls -la /workspace/agent/time-series-transformer-tourism-monthly/

# 期望输出:config.json model.safetensors (~130KB) ...

步骤 2:检查 NPU 环境

# 检查 NPU 设备状态
npu-smi info

# 验证 torch_npu 安装
python -c "import torch; import torch_npu; print('NPU 可用:', torch.npu.is_available())"

步骤 3:运行推理脚本

# 基本用法
python inference.py --device npu:0

# 查看 NPU 显存使用
python inference.py --device npu:0 --show_npu_memory

# 指定其他 NPU 卡
python inference.py --device npu:1

# CPU 模式(仅在 NPU 不可用时使用)
python inference.py --device cpu

4. 完整测试用例

测试用例 1:标准预测(NPU:0)

conda activate pt2100
cd /workspace/agent/time-series-transformer-tourism-monthly-ascend
python inference.py --device npu:0 --show_npu_memory

实际输出:

[W819 06:00:28.866541060 FunctionLoader.cpp:48] Warning: LD_PRELOAD detected...
[W819 06:00:35.876352450 VariableFallbackKernel.cpp:250] Warning: CAUTION: The operator 'aten::_standard_gamma' is not currently supported on the NPU backend and will fall back to run on the CPU...
[设备] npu:0
NPU设备数量: 1
  设备 0: Ascend910B2
[权重信息] 文件: /workspace/agent/time-series-transformer-tourism-monthly/model.safetensors
[配置] 模型类型: time_series_transformer
[配置] d_model: 26
[配置] encoder_layers: 2
[配置] decoder_layers: 2
[配置] context_length: 24
[配置] prediction_length: 24
[配置] feature_size: 27
[配置] distribution_output: student_t
[参数量] 0.0305M

加载模型...

模型: TimeSeriesTransformer (Tourism Monthly)
  - 任务: 时间序列预测 (Encoder-Decoder Transformer)
  - 参数量: 0.0305M
  - Context长度: 24
  - 预测长度: 24
[NPU显存 · 模型加载后] 总显存=61.0GB | 已分配=0.2MB | 缓存=2.00MB | 峰值=0.2MB

构建测试输入: 随机时间序列 (past_length=61)
past_values形状: (1, 61)
past_time_features形状: (1, 61, 2)

运行推理...
[NPU显存 · 推理完成后] 总显存=61.0GB | 已分配=0.2MB | 缓存=8.00MB | 峰值=6.6MB

==============================================================================
输出摘要
==============================================================================
  模型: TimeSeriesTransformer (Tourism Monthly)
  past_values形状: (1, 61)
  输出形状: (1, 100, 24)
  (batch_size, num_samples, prediction_length)
  总耗时: 0.52s
  输出 finite: True
  输出均值: 0.6293
  输出标准差: 0.9626
  输出范围: [-12.2153, 14.2845]

✅ 验证要点:

  • 输出形状 (1, 100, 24): batch=1, num_samples=100 (并行采样), prediction_length=24
  • NPU 推理稳定: 单次推理 0.52 秒
  • NPU 显存峰值: 仅约 6.6 MB,极轻量模型
  • 输出有限值: 所有输出均为有限值,无 NaN/Inf

5. 常见问题解答

Q1:提示 "NPU 不可用" 怎么办?

解决方案:

  1. 确认已安装 CANN 驱动并设置环境变量(source /usr/local/Ascend/ascend-toolkit/latest/set_env.sh)
  2. 运行 npu-smi info 检查设备状态
  3. 确认 PyTorch 和 torch_npu 版本匹配

Q2:为什么使用 transformers 4.40.1?

解决方案:TimeSeriesTransformer 模型与 transformers 4.40.1 兼容。更高版本可能存在 API 变化。

Q3:past_observed_mask 必须是 2D 吗?

解释:是的。根据模型设计,past_observed_mask 应为 2D 形状 (batch_size, past_length),不是 3D。

Q4:模型支持多步预测吗?

解释:该模型支持固定的 prediction_length (24)。对于更长预测,需要迭代调用或使用其他模型。

6. 文件结构

time-series-transformer-tourism-monthly-ascend/
├── inference.py              # 推理脚本(torch_npu 推理)
├── README.md                 # 本文档
├── requirements.txt          # 依赖列表
└── assets/                   # 资源占位目录

上游权重目录(只读,未被修改):

/workspace/agent/time-series-transformer-tourism-monthly/
├── config.json               # 模型配置
├── model.safetensors         # 权重(0.0305M, ~130KB)
├── pytorch_model.bin         # PyTorch 格式权重
└── README.md                 # 原始文档

7. requirements.txt - 依赖列表

# TimeSeriesTransformer-Tourism-Monthly 昇腾 NPU 推理环境依赖

# 核心依赖(必须)
torch>=2.0.0
torch_npu>=2.0.0
transformers==4.40.1
safetensors>=0.4.0
numpy>=1.21.0

使用方式:

# 激活环境
conda activate pt2100

# 安装依赖(华为云源)
pip install --index-url https://repo.huaweicloud.com/repository/pypi/simple -r requirements.txt

8. 参考资源

  • TimeSeriesTransformer 论文
  • HuggingFace Time Series Transformer 文档
  • HuggingFace 模型页
  • Monash Time Series Forecasting Dataset
  • 华为昇腾文档
  • torch_npu GitHub