简介本资源是一套基于PyTorch实现的Transformer模型长期时间序列预测完整代码工程面向深度学习初学者与时间序列分析实践者聚焦解决传统RNN在长程依赖建模中的梯度衰减与并行性不足问题。项目复现了Transformer核心结构含多头自注意力、位置编码、Encoder-Decoder堆叠并适配ETTh1电力负荷数据集完成端到端训练、滚动预测及结果可视化适用于能源预测、工业时序建模等实际场景。压缩包共39个文件含13个核心Python源码如Transformer.py、layers/目录下模块、data_loader.py、metrics.py等、3个CSV数据文件、1张预测效果对比图results.png、1个模型权重.pth及requirements.txt等整体26.49MB结构清晰、模块解耦便于逐层理解与二次开发。目前已有276人学习下载读者可直接运行main.py复现全流程获取可解释的预测曲线、误差指标输出及完整训练日志快速掌握Transformer在非NLP任务中的迁移应用方法。1. 长期预测不是“多跑几轮”就能赢这个Transformer项目专治ETTh1数据集上720步5天单变量负荷预测的玄学翻车你是不是也试过把标准Transformer直接套在电力负荷、气象或工业传感器这类长周期时序上结果训练loss掉得挺欢一到test阶段——预测曲线平得像尺子或者突然炸开成毛线团这不是你调参手抖是原始Transformer的因果掩码固定解码长度设计天生对「长期依赖建模」和「自回归误差累积」缺乏防御机制。这个项目不玩概念包装它用一套可复现、带完整数据流的PyTorch实现在ETTh1Electric Transformer Temperature这个工业级温度预测基准数据集上实打实跑出720步即5天每15分钟一个点的单变量长期预测并把真实值、预测值、分解趋势线全画在一张图里——不是截图是results.png里能看清每个拐点的矢量图。它适合两类人一类是刚啃完《Attention is All You Need》但卡在“怎么让模型真能看懂未来一周温度走势”的算法新手另一类是手头有IoT设备时序数据、急需一个可调试底座而非黑匣子API的嵌入式/边缘计算开发者。代码结构干净没有Hugging Face的抽象层裹挟从data_loader.py读CSV开始到Transformer.py里每一行nn.Linear的维度定义再到main.py里那个决定预测长度的关键参数pred_len720全部裸露可改。2. 项目结构与核心模块拆解从ETTh1.csv到results.png的6层数据穿透链这个项目不是“Transformermatplotlib”的简单拼接而是一条贯穿数据预处理、特征解耦、模型架构、预测策略、指标计算、可视化输出的完整链路。目录里那些.py文件名看似普通但每个都承担着长期预测场景下的特殊职责。下面按数据流向逐层拆解重点标出为什么这么设计而不是“它是什么”。2.1 数据加载与时间特征工程data_loader.py和timefeatures.py的双保险长期预测最怕“时间信息被吃掉”。ETTh1.csv里只有两列date2016-07-01 00:00:00格式和OT目标温度。如果直接丢给模型它根本分不清“周一早8点”和“周日晚8点”的物理意义差异。timefeatures.py干的就是这件事——它把date字符串解析成year,month,day,hour,minute五个离散特征再通过sin/cos编码转成连续向量。关键代码在timefeatures.py第42行def time_features(dates, freqh): dates pd.to_datetime(dates) feat_set [year, month, day, hour, minute] data [] for feat in feat_set: if feat year: data.append(dates.year) elif feat month: data.append(dates.month) elif feat day: data.append(dates.day) elif feat hour: data.append(dates.hour) elif feat minute: data.append(dates.minute % 15) # ETTh1采样间隔为15min取余归一化 return np.stack(data, axis1).astype(np.float32)注意minute % 15这一行是针对ETTh1数据的硬编码适配。如果你换用每小时采样的气象数据这里必须改成% 60否则时间特征会错位。这是新手最容易忽略的“数据-代码耦合点”。data_loader.py则负责把原始CSV切分成训练/验证/测试集并构造输入输出对。它的核心逻辑不是简单滑窗而是分段重叠采样seq_len96, label_len48, pred_len720。seq_len96代表用过去96个点即24小时作为输入label_len48是解码器的起始引导序列类似teacher forcing的前48步pred_len720才是真正的预测长度。这种三段式设计是避免纯自回归预测误差爆炸的关键缓冲。2.2 序列分解模块decomposition.py—— 长期预测的“去噪后悔药”标准Transformer对突变点如设备启停导致的温度骤升极其敏感长期预测时一个小误差会被指数级放大。这个项目没硬扛而是加了一道Invertible.py里的可逆序列分解层。它把原始序列x拆成趋势项T和残差项R公式为x T R且T由移动平均平滑得到R保留高频细节。关键在decomposition.py第28行class SeriesDecompose(nn.Module): def __init__(self, kernel_size): super(SeriesDecompose, self).__init__() self.kernel_size kernel_size self.avg nn.AvgPool1d(kernel_sizekernel_size, stride1, padding0) def forward(self, x): # x: [B, L, D] - [B, D, L] x x.permute(0, 2, 1) # 移动平均求趋势 trend self.avg(x) # 补零对齐长度AvgPool1d会缩短序列 trend F.pad(trend, (0, x.shape[-1] - trend.shape[-1])) # 恢复形状 trend trend.permute(0, 2, 1) residual x.permute(0, 2, 1) - trend return trend, residual提示F.pad补零是为了保持输入输出长度一致否则后续Transformer的Positional Encoding维度会报错。这个padding不是随便填0而是沿时间轴末尾补最后的trend值保证趋势连续性。模型实际预测的是residual部分再把预测的residual和原始trend相加得到最终结果。这相当于给Transformer喂了一个“更平稳”的子任务大幅降低学习难度。2.3 核心Transformer架构Transformer.py里的Encoder-Only精简版别被标题骗了——这个项目没有Decoder。长期预测场景下标准Encoder-Decoder结构因需要逐点自回归生成会导致720步预测耗时不可接受O(n²)复杂度。它采用的是Informer式Encoder-Only架构把pred_len长度的空白token用torch.zeros初始化和label_len长度的真实历史拼在一起作为Decoder的输入但所有注意力层都取消因果掩码让未来位置也能看到未来位置——这听起来反直觉但正是长期预测的突破口模型一次性学习整个预测区间内的全局依赖而非串行纠错。Transformer.py中EncoderLayer的定义很精炼class EncoderLayer(nn.Module): def __init__(self, attention, d_model, d_ffNone, dropout0.1, activationrelu): super(EncoderLayer, self).__init__() d_ff d_ff or 4*d_model self.attention attention # 这里attention是FullAttention非causal self.conv1 nn.Conv1d(in_channelsd_model, out_channelsd_ff, kernel_size1) self.conv2 nn.Conv1d(in_channelsd_ff, out_channelsd_model, kernel_size1) self.norm1 nn.LayerNorm(d_model) self.norm2 nn.LayerNorm(d_model) self.dropout nn.Dropout(dropout) self.activation F.relu if activation relu else F.gelu def forward(self, x, attn_maskNone): # 第一跳自注意力无mask new_x self.attention(x, x, x, attn_maskattn_mask)[0] x x self.dropout(new_x) x self.norm1(x) # 第二跳FFN y x.transpose(1,2) y self.dropout(self.activation(self.conv1(y))) y self.dropout(self.conv2(y)) y y.transpose(1,2) x x y x self.norm2(x) return x关键参数说明attn_maskNone是默认值意味着完全放开注意力。如果你要迁移到需要因果性的任务比如实时预警就在这里传入generate_square_subsequent_mask()。2.4 预测头与逆变换Projection.py和Invertible.py的闭环设计预测头不是简单的nn.Linear。Projection.py里定义了一个CrossProjection类它把Encoder输出的高维特征通过两个线性层激活函数映射到pred_len长度的输出空间class CrossProjection(nn.Module): def __init__(self, d_model, pred_len, c_out): super(CrossProjection, self).__init__() self.pred_len pred_len self.c_out c_out self.linear1 nn.Linear(d_model, d_model) self.linear2 nn.Linear(d_model, c_out * pred_len) # 输出维度pred_len * c_out def forward(self, x): # x: [B, L, D] - 先过一层线性 x torch.relu(self.linear1(x)) # 再拉平并投影到最终形状 [B, pred_len, c_out] x self.linear2(x.mean(dim1)) # 对时间维度取均值聚合全局信息 x x.view(-1, self.pred_len, self.c_out) return x注意x.mean(dim1)——它把整个输入序列的特征压缩成一个向量再展开为预测序列。这是Encoder-Only方案的核心用全局表征驱动整个预测区间而非逐点生成。Invertible.py则负责把预测结果从“分解域”映射回原始尺度。它保存了训练集的均值和标准差在inverse_transform()方法中执行y_pred * std mean。这个逆变换必须和data_loader.py中的标准化操作严格配对否则results.png里的曲线会整体漂移。2.5 可视化与评估metrics.py和main.py的落地校验metrics.py提供了MSE、MAE、MAPE三个工业界硬指标计算逻辑直白def metric(pred, true): mae np.mean(np.abs(pred - true)) mse np.mean((pred - true) ** 2) mape np.mean(np.abs((pred - true) / (true 1e-8))) * 100 return mae, mse, mapemain.py第156行调用visual(true, preds, f./results/{setting}.png)生成图表。visual()函数用matplotlib绘制三条线蓝色true真实值、红色preds预测值、绿色trend分解出的趋势线X轴标注为“Time Step”Y轴为“Temperature (°C)”。这张图不是装饰它是你判断模型是否学到物理规律的第一道防线——如果绿色趋势线和蓝色真实线高度重合说明分解有效如果红色预测线在绿色线上下小幅度波动说明残差拟合成功。3. 环境配置与一键运行从requirements.txt到results.png的3步实操这个项目对环境要求极简没用CUDA加速也能跑通当然GPU更快。所有依赖都在requirements.txt里列明但有几个版本坑必须提前踩平。3.1 创建隔离环境并安装依赖不要用系统Python。用conda或venv创建干净环境避免包冲突# 推荐conda更稳 conda create -n transformer-forecast python3.8 conda activate transformer-forecast pip install -r requirements.txtrequirements.txt内容如下已验证兼容性numpy1.21.6 pandas1.3.5 torch1.10.2 matplotlib3.5.3 scikit-learn1.0.2注意torch1.10.2是关键。新版PyTorch1.12的nn.MultiheadAttention默认启用batch_firstTrue而本项目代码假设batch_firstFalse即[L, B, D]格式。如果强行升级会在TransformerBlocks.py第89行attn_output, _ self.attn(query, key, value)处报维度错。血泪经验宁可降级PyTorch也不要改batch_first参数去适配新版本。3.2 准备数据ETTh1.csv的格式与存放路径项目期望数据放在./data/目录下且文件名必须是ETTh1.csv和ETTh1-Test.csv。这两个文件已在压缩包里提供但你要确认它们的内容ETTh1.csv共17420行date列从2016-07-01 00:00:00到2018-06-30 23:45:00OT列是float型温度值。ETTh1-Test.csv共2880行是2018-07-01 00:00:00起的最后5天数据用于独立测试。如果文件名不对data_loader.py第62行df_raw pd.read_csv(os.path.join(root_path, data_path))会直接报FileNotFoundError。别试图用ETTh2.csv替换——ETTh2的采样频率和时间范围不同timefeatures.py里的minute % 15会失效。3.3 启动训练与预测main.py的4个必改参数main.py是总入口所有实验配置集中在此。打开它找到if __name__ __main__:下方的args字典修改以下4个键args { model: Transformer, # 模型名必须和models/下文件夹名一致 data: ETTh1, # 数据集名决定读哪个csv features: S, # SSingle-variate, MMulti-variate target: OT, # 目标列名必须和csv里列名完全一致 seq_len: 96, # 输入长度96*15min 24小时 label_len: 48, # 引导长度48*15min 12小时 pred_len: 720, # 预测长度720*15min 5天 ← 这是长期预测的核心 e_layers: 2, # Encoder层数2层足够ETTh1 d_layers: 1, # Decoder层数本项目为0但代码仍占位 factor: 5, # Informer式采样因子越大越稀疏 enc_in: 1, # 输入通道数单变量1 dec_in: 1, # 解码器输入通道数 c_out: 1, # 输出通道数 d_model: 512, # 模型隐层维度 d_ff: 2048, # FFN中间层维度 n_heads: 8, # 多头注意力头数 dropout: 0.05, # Dropout率长期预测不宜过大 embed: timeF, # 嵌入方式timeF时间特征fixed固定位置编码 freq: h, # 时间频率hhourly对应ETTh1的15min采样需手动理解为15min activation: gelu, # 激活函数 output_attention: False, # 是否输出注意力权重调试用关掉省显存 do_predict: True, # 关键设为True才跑预测并生成results.png cols: None, # 多变量时指定列单变量留None num_workers: 0, # Windows用户必须设0否则DataLoader报错 itr: 1, # 实验重复次数1次够验证 train_epochs: 10, # 训练轮数ETTh1上10轮足够收敛 batch_size: 32, # 批大小GPU显存8G建议调到16 patience: 3, # 早停耐心值 learning_rate: 0.0001, # 学习率Transformer对lr敏感别乱调 des: Exp, # 实验描述 loss: mse, # 损失函数 lradj: type1, # 学习率调整策略 use_amp: False, # 混合精度小显存慎开 inverse: True, # 关键设为True才做逆变换否则results.png是标准化后的值 }避坑 / 常见问题 / 排查现象1运行python main.py后卡在Data loading...10分钟没反应原因num_workers0在Windows上触发多进程bugDataLoader死锁解决强制设num_workers: 0虽慢但稳现象2RuntimeError: expected scalar type Float but found Double原因ETTh1.csv里OT列被pandas读成float64而PyTorch默认float32解决在data_loader.py第75行df_raw df_raw[[OT]]后加df_raw df_raw.astype(np.float32)现象3results.png里预测线是直线且和真实线完全不重合原因inverseTrue没设或data_loader.py里标准化用的train_mean/std没保存下来解决检查main.py中args[inverse]是否为True确认data_loader.py第120行self.scaler.fit(train_data)执行成功现象4训练loss降到0.001后不再下降但test MAE高达8.5远超baseline的3.2原因pred_len720太大模型过拟合训练集短期模式解决降低d_model到256或增加dropout到0.1或减少train_epochs到5现象5ImportError: cannot import name BatchNorm1d from torch.nn原因PyTorch版本太低1.8解决按前述pip install torch1.10.2重装3.4 查看结果results.png和OT-ForecastResults.csv的双重验证运行结束后你会在根目录看到results.png主可视化图包含真实值蓝、预测值红、趋势线绿results/文件夹里面是Transformer_ETTh1_S_96_48_720这样的子文件夹含每次实验的checkpoint.pth和result_long_term_forecast.txtOT-ForecastResults.csv结构化预测结果列名为date, true, pred, trend可直接导入Excel分析打开results.png第一眼盯住X轴末尾——那里是第720步第5天最后一刻。如果红色预测线在此处仍紧贴蓝色真实线说明长期泛化能力成立如果此处发散则需回头调d_model或dropout。OT-ForecastResults.csv则让你用Excel的CORREL()函数算true和pred的相关系数0.95才算过关。4. 模块级改造指南把ETTh1方案迁移到你的业务数据上这个项目的价值不在跑通ETTh1而在提供一个可手术刀式修改的骨架。我把它拆成4个可独立替换的模块每个都附上你改时必查的3个文件、2个参数、1个验证点。4.1 替换数据源从ETTh1到你的CSV模块必查文件必改参数验证点数据路径main.py第58行root_pathdata_loader.py第62行data_pathroot_path./your_data/data_pathyour_file.csv运行后打印df_raw.shape确认行数列数符合预期时间列解析timefeatures.py第42行freq第55行minute % 15freq15min或hminute % your_interval如% 60print(time_features(df_raw[date]).shape)应为(N, 5)目标列名main.py第72行targetdata_loader.py第75行df_raw[[OT]]targetyour_column_namedf_raw[[your_column_name]]df_raw[your_column_name].dtype np.float32实操技巧你的数据如果有缺失值别在data_loader.py里插值——在main.py读取后、传入Dataset前用df.fillna(methodffill)一次补齐。否则SeriesDecompose的移动平均会出NaN。4.2 调整预测长度从720步到任意步长pred_len不是越大越好。它和seq_len构成输入-输出比例直接影响模型容量需求。我们用一张表说明如何平衡业务场景seq_lenpred_lenlabel_len理由说明电力负荷日级9624h9624h4812h日内调度需覆盖完整周期label_len提供强引导工业设备周级1687d33614d1687d周期性强用整周数据作输入预测两周label_len等于seq_len增强稳定性气象预报小时级2424h1687d2424h小时级数据噪声大缩短输入长度防过拟合拉长pred_len靠Encoder全局建模弥补改法只动main.py里的pred_len和label_len其他参数按上表比例缩放。切记pred_len必须是数据采样间隔的整数倍否则timefeatures.py的minute % interval会报错。4.3 替换模型组件从Transformer到Informer或Autoformer项目预留了model参数开关。当前model: Transformer指向models/Transformer/Transformer.py。若想换Informer更适合长序列只需把models/Informer/文件夹需自行实现或从GitHub克隆放到同级目录改main.py中model: Informer在models/Informer/Informer.py里确保forward()接口和Transformer.py一致接收x_enc, x_mark_enc, x_dec, x_mark_dec返回pred关键适配点Informer的ProbSparse注意力需要factor参数而Autoformer的Auto-Correlation需要moving_avg窗口大小。这些参数都在main.py的args字典里预留了位置factor: 5,moving_avg: 25改模型时顺手填上即可。4.4 定制可视化从results.png到交互式Dashboardmain.py第156行visual()函数是可视化入口。它调用util/tools.py里的plot_prediction()。如果你想加置信区间改tools.py第201行def plot_prediction(true, preds, path): plt.figure(figsize(12, 6)) plt.plot(true, labelTrue, colorblue) plt.plot(preds, labelPred, colorred) # 新增假设你有lower/upper边界从模型输出获得 # plt.fill_between(range(len(true)), lower, upper, alpha0.2, colorred) plt.legend() plt.savefig(path, bbox_inchestight) plt.close()生产建议别用matplotlib出图。把preds和true写入results.json用flask搭个轻量API前端用ECharts渲染动态折线图。这样客户能拖拽看任意时间段比静态results.png实用十倍。5. 二次开发实战给Transformer加上“物理约束”让预测不违背热力学常识这是我在线上项目踩过的最深的坑模型预测出“变压器温度在凌晨3点比正午还高10°C”数学上MSE很低物理上完全荒谬。单纯靠数据无法教会模型热传导定律必须在损失函数里注入先验知识。下面教你三步给这个Transformer项目加上可微分的物理约束。5.1 构造物理损失项热平衡不等式变压器温度变化受散热速率限制。设T[t]为t时刻温度Δt15min则理论最大升温速率为k*(T_env - T[t])其中k是散热系数T_env是环境温度。我们把它转化为可微分的软约束# 在main.py的train_one_epoch()函数里loss计算后追加 def physical_loss(pred, env_temp, k0.01): # pred: [B, pred_len, 1], env_temp: [B, pred_len, 1]需你提供环境温度序列 dt 15 / 60 # 小时 # 计算相邻时刻温差 delta_T pred[:, 1:, 0] - pred[:, :-1, 0] # [B, pred_len-1] # 计算理论最大允许温差 max_delta_T k * (env_temp[:, 1:, 0] - pred[:, :-1, 0]) * dt # 软约束超出部分的L2惩罚 violation torch.relu(delta_T - max_delta_T) return torch.mean(violation ** 2) # 在train_one_epoch()中 loss criterion(outputs, true) phy_loss physical_loss(outputs, env_temp_batch) # env_temp_batch需从data_loader提供 total_loss loss 0.5 * phy_loss # 权重0.5可调 total_loss.backward()注意env_temp_batch必须和outputs同batch同长度。你得在data_loader.py的__getitem__里把环境温度作为额外列读进来并在main.py的data_parser中扩展enc_in。5.2 修改数据加载器注入环境温度特征data_loader.py第75行后插入# 假设你的CSV多一列EnvTemp df_raw df_raw[[OT, EnvTemp]] # 读两列 # 后续标准化时对两列分别做 self.scaler.fit(df_raw[[OT]]) self.env_scaler StandardScaler() self.env_scaler.fit(df_raw[[EnvTemp]])然后在__getitem__返回时把env_temp也打包进去return seq_x, seq_y, seq_x_mark, seq_y_mark, env_temp_seq_ymain.py里接收时加一句seq_x, seq_y, seq_x_mark, seq_y_mark, env_temp batch5.3 验证物理约束生效用梯度检查法别等训练完看results.png。在train_one_epoch()里加断点检查phy_loss是否随epoch下降if epoch % 10 0: print(fEpoch {epoch}, PhyLoss: {phy_loss.item():.6f}) # 检查梯度是否回传到embedding层 grad_norm torch.norm(model.enc_embedding.token_emb.weight.grad) print(fEmbedding grad norm: {grad_norm:.6f})如果PhyLoss从0.12降到0.003且Embedding grad norm始终0说明约束已生效。此时再跑results.png你会发现凌晨预测温度不再异常飙升而是平缓跟随环境温度曲线——这才是工程可用的预测。从那以后我每次做时序预测项目都强制走一遍“物理定律→数学不等式→可微分损失”的推导。不是为了炫技是让模型学会敬畏现实世界的规则。希望帮到你。本文还有配套的精品资源点击获取