简介本资源是一份面向深度学习初学者与时间序列分析实践者的Transformer长期预测完整实现方案聚焦将NLP领域经典模型迁移至时序预测任务解决传统RNN/LSTM难以建模长程依赖的痛点。压缩包共38个文件含13个核心Python源码涵盖TransformerBlocks、Embedding、Invertible等模块、3个实测CSV数据集ETTh1训练/测试集、1个可视化结果PNG图、1个训练权重PTH文件及requirements.txt等配套文件整体26.48MB结构清晰模块解耦度高便于理解模型构建逻辑与定制化训练个人数据。已有984人学习下载资源提供从原理讲解、PyTorch代码实现、数据预处理、模型训练到结果可视化的全流程支持附带metrics.py、masking.py等实用工具函数及OT-ForecastResults.csv预测输出样例可直接复现、调试并拓展至电力负荷、交通流量等真实场景。1. Transformer 做时间序列长期预测不是调个包就能出图而是得把位置编码、通道对齐、反归一化三道关全过一遍你手头有一组连续 720 小时的电力负荷数据想让模型往后推 96 小时——这不算长但足够让多数 LSTM 模型开始“记混”季节性节奏你试过直接套用 Hugging Face 的BertModel结果训练崩在torch.nn.Embedding维度不匹配上你甚至把ETTh1.csv里的时间戳列删了再跑可视化出来的曲线平得像尺子量过。这不是模型不行是时间序列场景下Transformer 的每个模块都得被重新拧紧螺丝原始 NLP 的词嵌入token embedding必须替换成时间特征数值联合嵌入标准正弦位置编码得改造成可学习的、适配小时/日/周多周期的时间位置编码而最关键的——预测结果从模型输出到最终results.png上那条带置信区间的蓝线中间隔着一层 invertible transformation可逆变换和两层反归一化逻辑。这份资源不是“Transformer 时间序列教程”它是一份已通过 ETTh1 全量测试、含完整训练-验证-推理闭环的 PyTorch 工程快照适合正在调试长期预测 pipeline 的算法工程师、需要复现论文结果的研究生以及想甩开 Prophet 等传统方法、真正动手搭一个可解释、可调试、可部署的深度时序模型的从业者。2. 从main.py入口拆解为什么这个 Transformer 不是 NLP 模型的简单移植2.1 主流程骨架main.py如何串联数据、模型与评估打开main.py第一眼看到的不是model Transformer(...)而是args argparse.ArgumentParser() args.add_argument(--data, typestr, defaultETTh1, helpdataset type) args.add_argument(--seq_len, typeint, default96, helpinput sequence length) args.add_argument(--pred_len, typeint, default96, helpprediction sequence length) args.add_argument(--enc_in, typeint, default7, helpencoder input size) args.add_argument(--dec_in, typeint, default7, helpdecoder input size) args.add_argument(--c_out, typeint, default7, helpoutput size)注意enc_in/dec_in/c_out这三个参数——它们直接对应数据集字段数ETTh1 是 7 维OT 6 个辅助变量而非 NLP 中的 vocab_size。这意味着整个模型输入端根本没走nn.Embedding(vocab_size, d_model)而是靠data_loader.py里DataLoader实例返回的x_enc,x_dec,y三元组全部是 shape(B, L, D)的 float32 张量。main.py第 87 行的model Model(args).float()调用的是models/Transformer.py中重写的__init__它内部会实例化Encoder,Decoder,Projection三层完全绕开了nn.Transformer这个 PyTorch 原生封装类。这是第一个关键判断这不是一个调用torch.nn.Transformer的轻量封装而是一个从零实现 Encoder-Decoder 架构、并针对时序任务深度定制的模型。提示models/Transformer.py中Encoder类继承自nn.Module但其forward方法里没有调用nn.TransformerEncoderLayer而是显式调用TransformerBlocks模块堆叠。这种写法牺牲了 PyTorch 原生接口的简洁性换来了对每一层 attention mask、positional encoding 注入点的绝对控制权——比如你在TransformerBlocks.py第 42 行能看到x x self.pos_encoding(x)这里的self.pos_encoding是Embedding.py里自定义的TimeFeatureEmbedding不是nn.PositionalEncoding。2.2 数据加载器data_loader.py如何把 CSV 变成(B, L, D)张量data_loader.py的核心是Dataset_ETT_hour类它不直接读 CSV而是先调用data_factory.py加载ETTh1.csv再经timefeatures.py提取时间特征# timefeatures.py 第 32 行 def time_features(dates, freqh): # dates: pd.DatetimeIndex, e.g., [2016-07-01 00:00:00, ..., 2017-07-01 00:00:00] return np.vstack([ dates.hour / 23.0, dates.day / 31.0, dates.weekday / 6.0, dates.dayofyear / 366.0, dates.month / 12.0, dates.year % 100 / 100.0 ]).transpose(1, 0) # shape: (len(dates), 6)注意这里返回的是 6 维时间特征而ETTh1.csv原始数据有 7 列OT 6 辅助变量。Dataset_ETT_hour.__getitem__在第 128 行执行# data_loader.py 第 128 行 x_enc self.data_x[r_begin:r_end] # shape: (seq_len, 7) x_mark_enc self.timeenc[r_begin:r_end] # shape: (seq_len, 6) x_enc np.concatenate([x_enc, x_mark_enc], axis1) # shape: (seq_len, 13)也就是说模型真正的输入维度是enc_in 13而非7。args.enc_in参数实际只用于初始化Embedding层的d_model而真实输入拼接发生在数据加载阶段。这个细节决定了你若想换自己的数据集不能只改c_out必须同步修改timefeatures.py的特征生成逻辑并确保x_enc拼接后维度与模型enc_in匹配。data_loader.py第 156 行的scaler.fit_transform(x_enc)执行的是按列标准化Z-score这也是后续Invertible.py必须存在的根本原因——所有预测值都需反向还原到原始量纲。2.3 模型核心TransformerBlocks.py里的自注意力如何适配时序局部性TransformerBlocks.py中AttentionLayer类第 19 行重写了forward关键在attn_mask的构造# TransformerBlocks.py 第 58 行 if attn_mask is None: attn_mask TriangularCausalMask(B, L, devicex.device) # TriangularCausalMask 定义在 masking.py 中 class TriangularCausalMask(): def __init__(self, B, L, devicecpu): mask_shape [B, 1, L, L] with torch.no_grad(): self._mask torch.triu(torch.ones(mask_shape, dtypetorch.bool), diagonal1).to(device)注意这里用的是torch.triu(..., diagonal1)生成上三角掩码左上角为 True意味着每个时间步只能 attend to 自身及之前步严格遵循时序因果性。这与 NLP 中nn.MultiheadAttention默认的 full attention允许未来 token 注意当前 token有本质区别。更关键的是AttentionLayer第 72 行scores torch.einsum(blhd,bshd-blhs, query, key) / np.sqrt(d_k) # query.shape (B, L, H, D//H), key.shape (B, S, H, D//H) # scores.shape (B, L, S, H)einsum显式指定了blhd,bshd-blhs说明 query 和 key 的序列长度L与S可以不同encoder 输入长度 vs decoder 输入长度这正是 long-term forecasting 所需的 encoder-decoder asymmetry。如果你强行把seq_len和pred_len设为相同值模型仍能跑通但 attention score map 会浪费一半计算量——因为 decoder 的S实际应为pred_len seq_lenteacher-forcing 阶段而L是pred_len。这个设计细节直接决定了模型能否在 96 步预测中稳定捕捉跨日周期模式。3. 关键模块源码精读Invertible.py为何是反归一化的“后悔药”3.1InvertibleTransform类如何用雅可比行列式保障可逆性Invertible.py的核心是InvertibleTransform类第 12 行它并非简单做x * std mean而是实现了Glow-style 可逆归一化# Invertible.py 第 28 行 class InvertibleTransform(nn.Module): def __init__(self, num_features, affineTrue): super().__init__() self.num_features num_features self.affine affine if affine: self.weight nn.Parameter(torch.ones(num_features)) self.bias nn.Parameter(torch.zeros(num_features)) else: self.register_parameter(weight, None) self.register_parameter(bias, None) def forward(self, x, reverseFalse): if not reverse: # forward: x - z if self.affine: z x * self.weight self.bias else: z x return z else: # reverse: z - x if self.affine: x (z - self.bias) / self.weight else: x z return x注意forward方法的reverse参数——它控制方向。在main.py第 198 行训练循环中# main.py 第 198 行 outputs model(batch_x, batch_x_mark, batch_y, batch_y_mark) f_dim -1 if args.features MS else 0 outputs outputs[:, -args.pred_len:, f_dim:] # 此时 outputs 是模型原始输出未归一化 pred inverse_transform(outputs, scaler) # ← 这里调用 invertible.py而inverse_transform函数定义在util/metrics.py第 15 行实际调用的是InvertibleTransform.forward(z, reverseTrue)。重点在于self.weight和self.bias是在data_loader.py初始化scaler时由scaler.fit_transform()计算得到的std和mean并作为nn.Parameter注册进模型。这意味着——归一化参数随模型一起保存在model.pth中。当你用torch.load(model.pth)加载模型时InvertibleTransform的weight/bias已同步加载无需额外传入 scaler 对象。这是工程落地的关键模型文件是自包含的部署时不用打包scaler.pkl。3.2Projection.py为什么输出层要加nn.Linearnn.SigmoidProjection.py第 8 行定义了Conv1DProjection类其forward方法如下# Projection.py 第 22 行 def forward(self, x): x self.conv1(x.permute(0, 2, 1)) # (B, D, L) - conv1d - (B, D, L) x self.dropout(x) x self.conv2(x) # (B, D, L) - (B, c_out, L) x self.projection(x.permute(0, 2, 1)) # (B, L, c_out) x torch.sigmoid(x) # ← 关键 return xtorch.sigmoid(x)这行常被初学者忽略。ETTh1 的 OTOil Temperature列取值范围是[0, 100]但原始数据经过scaler.fit_transform()后分布被拉到[-2, 2]区间。如果Projection层不做约束模型可能输出[-5, 5]的值反归一化后变成负数或超百的异常值。sigmoid将输出强制映射到(0, 1)再乘以scaler.scale_标准差并加scaler.mean_均值最终保证预测值落在合理物理区间内。这不是数学上的必要操作而是工程鲁棒性设计。你可以注释掉sigmoid测试会发现验证集 MAE 下降 0.3%但测试集某天凌晨 3 点的预测值跳变到 -12.7℃——这就是没加约束的代价。3.3Embedding.py时间位置编码如何同时建模小时/日/周周期Embedding.py中TimeFeatureEmbedding类第 35 行是本项目最硬核的创新点之一# Embedding.py 第 42 行 class TimeFeatureEmbedding(nn.Module): def __init__(self, d_model, embed_typetimeF, freqh): super().__init__() freq_map {h: 4, t: 5, s: 6, m: 6, a: 4, w: 4, d: 4, b: 4} d_inp freq_map[freq] # for h, d_inp 4 self.embed nn.Linear(d_inp, d_model, biasFalse) def forward(self, x): # x: (B, L, d_inp), e.g., (32, 96, 4) return self.embed(x) # (B, L, d_model)注意freq_map[h] 4但timefeatures.py生成了 6 维时间特征。这里做了降维TimeFeatureEmbedding只取前 4 维hour, day, weekday, dayofyear丢弃 month 和 year。nn.Linear(d_inp, d_model)将 4 维手工特征映射到d_model512的高维空间再与数值数据x_enc13 维拼接后的d_model维度对齐。这种设计比正弦位置编码更灵活——正弦编码假设时间是线性增长的标量而TimeFeatureEmbedding显式编码了离散周期如 weekday0~6让模型能区分“周一早 8 点”和“周二早 8 点”的本质差异。你在main.py第 102 行能看到x_mark_enc time_features(pd.to_datetime(df_stamp[date]), freqargs.freq)freqh确保了特征提取与TimeFeatureEmbedding的d_inp匹配。若你用分钟级数据freqtd_inp变为 5必须同步修改timefeatures.py的返回维度否则nn.Linear会报size mismatch。4. 避坑指南训练/预测中五个血泪经验换来的具体问题排查4.1 现象训练 loss 在 epoch 3 后突然爆炸1e5grad_norm超过 1000原因TransformerBlocks.py中AttentionLayer的dropout默认为 0.05但在ETTh1这种高信噪比数据上过强的 dropout 会导致 attention score 不稳定梯度在 softmax 后剧烈震荡。解决在models/Transformer.py的Encoder初始化中将dropout0.05改为dropout0.01或在main.py中添加梯度裁剪torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm1.0)。4.2 现象results.png中预测曲线与真实值完全不重合但OT-ForecastResults.csv数值看起来合理原因util/metrics.py的inverse_transform函数默认使用scaler的mean_和scale_但ETTh1-Test.csv的统计量与训练集ETTh1.csv不同。代码中scaler是在data_loader.py的__init__里用训练集拟合的而ETTh1-Test.csv未被重新标准化。解决在main.py的test函数中第 235 行添加test_scaler StandardScaler().fit(test_data_x)并用test_scaler替换inverse_transform的 scaler 参数或更稳妥地在data_loader.py的Dataset_ETT_hour类中将scaler改为全局单例确保训练/测试/验证使用同一 scaler。4.3 现象CUDA out of memory即使batch_size16也报错原因TransformerBlocks.py的FullAttention类第 102 行中scores torch.matmul(query, key.transpose(-2, -1))生成(B, H, L, S)张量。当seq_len96,pred_len96时LS192单头 attention map 占用32*8*192*192*4 ≈ 36MBfloat328 头即 288MB。GPU 显存被__pycache__编译文件和results.png缓存挤占。解决删除项目根目录下所有__pycache__和.idea文件夹在main.py开头添加import gc; gc.collect(); torch.cuda.empty_cache()将args.n_heads从 8 降至 4。4.4 现象predict-Transformer-data-ETTh1/model.pth加载后model.eval()报AttributeError: NoneType object has no attribute eval原因models/Transformer.py的Model类__init__中self.encoder和self.decoder初始化顺序错误。第 68 行self.encoder Encoder(...)后第 72 行self.decoder Decoder(...)依赖self.encoder的d_model但Encoder的d_model是在__init__结尾才赋值。解决将Encoder和Decoder的d_model参数显式传入而非从self.encoder.d_model动态获取或在Encoder.__init__第 1 行就self.d_model d_model。4.5 现象requirements.txt安装后torch1.12.1与numpy1.23.5冲突pip install失败原因requirements.txt未锁定torch与numpy的兼容版本。torch1.12.1编译时链接的numpy版本为1.21.x而1.23.5的 C API 有变更。解决手动编辑requirements.txt将numpy1.21.0改为numpy1.21.6或运行pip install torch1.12.1cu113 -f https://download.pytorch.org/whl/torch_stable.html指定 CUDA 版本。5. 可视化与结果验证从OT-ForecastResults.csv到results.png的全链路校验5.1OT-ForecastResults.csv文件结构解析与可信度校验OT-ForecastResults.csv是模型预测结果的原始数据快照共 5 列date,real,pred,lower,upper。其中date列来自ETTh1-Test.csv的时间戳real是测试集真实值pred是模型主预测lower/upper是 95% 置信区间由util/metrics.py的cal_confidence_interval函数生成。校验第一步检查date是否连续。用 pandas 读取后执行import pandas as pd df pd.read_csv(OT-ForecastResults.csv) print(Date range:, df[date].min(), to, df[date].max()) print(Is continuous?, len(df) (pd.to_datetime(df[date].max()) - pd.to_datetime(df[date].min())).total_seconds() // 3600 1)若输出False说明data_loader.py的test_set切片有 gap需检查ETTh1-Test.csv是否缺失行。第二步验证pred与real的量纲一致性。ETTh1 的 OT 列理论范围是[0, 100]若df[pred].min() 0或df[pred].max() 100则Projection.py的sigmoid未生效需回查models/Transformer.py中Projection层是否被正确调用。5.2results.png生成逻辑与自定义绘图参数results.png由main.py第 265 行plot_results函数生成其核心是matplotlib.pyplot的fill_between# main.py 第 265 行 def plot_results(df, save_path): plt.figure(figsize(12, 6)) plt.plot(df[date], df[real], labelGround Truth, linewidth2) plt.plot(df[date], df[pred], labelPrediction, linewidth2) plt.fill_between(df[date], df[lower], df[upper], alpha0.2, label95% CI) plt.xlabel(Time) plt.ylabel(OT Value) plt.legend() plt.grid(True) plt.xticks(rotation30) plt.tight_layout() plt.savefig(save_path, dpi300) plt.close()注意plt.fill_between的alpha0.2控制置信区间透明度。若你发现results.png中置信区间过宽如upper-real 15说明模型不确定性估计偏保守可调整util/metrics.py中cal_confidence_interval的confidence_level0.95为0.8或在main.py的test函数中将pred的标准差计算从torch.std(pred, dim0)改为torch.quantile(torch.abs(pred - real), 0.95, dim0)分位数法。5.3 长期预测稳定性验证滚动预测 vs 单次预测的误差对比表长期预测的核心挑战是误差累积。本项目提供两种预测模式单次预测One-shot用最后seq_len96小时数据一次性预测未来pred_len96小时滚动预测Rolling每预测 1 小时将该预测值加入输入滑动窗口再预测下一步共 96 轮。预测模式MAEETTh1 TestRMSEETTh1 Test预测耗时RTX 3090适用场景One-shot0.420.610.8s快速推演、资源受限部署Rolling0.380.5742s高精度要求、离线批量分析验证方法在main.py中取消注释# args.roll_test True第 45 行运行python main.py --roll_test。滚动预测的MAE降低 9.5%证明误差未指数级放大——这是 Transformer 自注意力机制优于 RNN 的直接证据。但耗时增加 52 倍说明在边缘设备部署时必须选择 one-shot 模式。注意滚动预测的results.png会覆盖原图建议先备份。新图中pred曲线更贴合real但lower/upper区间会因每步不确定性叠加而变宽这是正常现象。6. 进阶技巧如何用这份代码快速适配你的私有数据集含三步清洗模板6.1 数据格式转换从任意 CSV 到ETTh1.csv兼容格式你的私有数据集可能是my_data.csv含列timestamp, temp, humidity, pressure。要接入本项目必须满足三个条件timestamp列为YYYY-MM-DD HH:MM:SS格式且无缺失所有数值列必须为 float无字符串或空值时间间隔必须严格均匀如每小时 1 条。执行以下清洗脚本保存为preprocess_my_data.pyimport pandas as pd import numpy as np df pd.read_csv(my_data.csv) # 步骤1统一 timestamp 格式 df[timestamp] pd.to_datetime(df[timestamp]) df df.sort_values(timestamp).reset_index(dropTrue) # 步骤2检查时间间隔以小时为单位 interval_hours (df[timestamp].diff().dt.total_seconds() / 3600).median() if not np.isclose(interval_hours, 1.0, atol1e-2): raise ValueError(fTime interval must be 1 hour, got {interval_hours}) # 步骤3填充缺失值用前向填充线性插值 df df.set_index(timestamp).resample(H).first().interpolate(methodlinear).reset_index() # 步骤4导出为 ETTh1 格式首列为 date其余为数值列 df.rename(columns{timestamp: date}, inplaceTrue) df.to_csv(ETTh1.csv, indexFalse) print(✅ Preprocessing done. Saved as ETTh1.csv)运行python preprocess_my_data.py生成的ETTh1.csv即可直接替换原文件。注意ETTh1-Test.csv需从ETTh1.csv末尾切出 96 行tail -n 96 ETTh1.csv ETTh1-Test.csv确保测试集时间连续。6.2 模型参数微调针对小样本数据的seq_len/pred_len黄金组合若你的私有数据仅 30 天720 小时seq_len96会吃掉 1/7 数据导致训练不稳定。实测黄金组合如下基于 720 小时数据数据量小时推荐seq_len推荐pred_len理由300–6002412确保seq_len≥ 最短周期日周期为 24hpred_len≤seq_len/2防过拟合600–12004824平衡长期依赖捕获与显存占用12009696充分利用 Transformer 的长程建模能力修改方式在main.py第 42 行附近将args.seq_len 96改为args.seq_len 24并同步修改args.pred_len 12。注意data_loader.py的Dataset_ETT_hour中self.seq_len和self.pred_len会自动读取args无需改动。6.3 可视化增强在results.png中叠加关键事件标注ETTh1数据中存在已知事件如 2016-08-15 的设备维护你想在图中用红色虚线标注。在main.py的plot_results函数中插入# main.py 第 272 行plt.grid(True) 后 event_dates [2016-08-15, 2016-12-25, 2017-01-01] for event in event_dates: plt.axvline(pd.to_datetime(event), colorred, linestyle--, alpha0.7, labelfEvent: {event}) # 去重图例 handles, labels plt.gca().get_legend_handles_labels() by_label dict(zip(labels, handles)) plt.legend(by_label.values(), by_label.keys())这样results.png会显示垂直事件线便于业务方快速定位预测偏差根源。从那以后我每次交付预测报告都强制走一遍事件标注——哪怕客户没提也能提前发现模型在节假日模式下的失效点。希望帮到你。本文还有配套的精品资源点击获取