简介一份基于Transformer的时间序列预测完整项目面向具备一定机器学习基础的中高级开发者可应用于天气预测、股票分析、电力负荷等需要挖掘长距离时序依赖的场景。压缩包共91个文件大小约48.85MB以40个ipynb代码文件与24个Python脚本为主体覆盖数据可视化、模型训练、基准对比、超参数搜索、交叉验证与模型导出等完整流程同时附带RST说明文档、PNG图表及运行依赖文件。已有299人学习项目从自注意力、多头注意力到位置编码均给出可运行实现同时包含损失函数定义与数据集预处理工具并设计了学习曲线与跨模型对比脚本帮助评估过拟合程度以及相对LSTM、ARIMA的优势。资源目录清晰训练、评估、工具模块分层明确便于边阅读代码边复现实验也可直接用于学术研究或业务预测的原型搭建。1. 基于transformer的时间序列预测拆开这个zip之前先想清楚一个反直觉的问题把“基于transformer的时间序列的预测.zip”这个压缩包解压、跑通里面的demo通常只需要几分钟——PyTorch搭一个编码器、喂一段正弦波、画一张拟合曲线看起来一切顺利。但当你把同一份代码扔到金融序列、设备寿命或流量指标上loss不降、曲线滞后、结果飘忽不定这些问题会一个个冒出来。这个标题背后的真实任务是先弄懂Transformer怎么被改造成时序预测器再把一份“能跑”的代码变成“能用”的基线。这篇笔记就按这个路径来写顺序是解包看结构、理解注意力在时序上的落点、复现并调参、排坑、最后改成业务方案。适合刚接触Transformer时序预测、想从demo走向实际数据的从业者也适合被预测曲线滞后和随机性折腾过的人。2. 先看懂zip里装了什么项目结构、数据定义和Transformer落在时序上的原理2.1 从压缩包到可运行拿到的第一件事是检查结构和依赖常见做法是把压缩包解压到一个独立目录然后立刻用tree看整体结构。不急着跑先确认三件事有没有README、依赖清单、数据文件。很多所谓“基于transformer的时间序列预测”项目核心文件就那么几个数据生成脚本、模型定义、训练入口再加一个画图的脚本。我一般会用下面的命令做第一轮入场检查unzip 基于transformer的时间序列的预测.zip -d ts_transformer cd ts_transformer tree -L 2 cat requirements.txt 2/dev/null || echo no requirements查看目录结果是第一道门槛。如果压缩包里有requirements.txt就按里面的版本来没有就按PyTorch官方默认组合装。这里要说明两个容易踩的版本问题一是PyTorch 2.x对注意力mask的写法有调整老代码里src_key_padding_mask的传参方式可能不变但内部实现变了影响的是显存占用和速度不影响正确性二是如果项目用了torch.utils.data的Dataset类注意NumPy和Pandas版本老代码经常出现np.float被删除导致的报错。确认目录后找到入口脚本。绝大多数项目入口叫train.py里面会有一个if __name__ __main__往下读就是数据加载和训练循环。到这里不用改任何代码先跑一遍默认参数把“能不能跑通”和“效果对不对”分开。跑通的意思是loss有下降趋势、能出预测图效果对不对是后面的事。2.2 数据与任务定义单变量还是多变量、预测步长多少、窗口多长这三个必须读明白Transformer本身不关心数据是时间序列还是图像它只接受“一组带位置信息的向量”。因此在读代码前先确认数据侧的三件事特征维度、预测视野、滑动窗口长度。大多数demo用正弦函数生成数据属于单变量、单步或多步预测。而业务场景里常见的是多变量多个传感器、历史统计特征、外部协变量这些变量会拼在最后一个维度上。一个典型的数据和窗口构造逻辑如下import numpy as np def make_windows(data, in_len, out_len): # data: (样本数, 特征维度) 或 (样本数,) X, Y [], [] for i in range(len(data) - in_len - out_len): X.append(data[i : i in_len]) # 过去的 in_len 个时间步 Y.append(data[i in_len : i in_len out_len]) # 未来的 out_len 个时间步 return np.array(X), np.array(Y)这里in_len是编码器能看到的过去长度out_len是要求模型预测的未来长度。两者的比例直接决定任务难度预测步长越长误差累积越明显。你会在很多项目里看到in_len96, out_len24这类配置意思是“看过去96个时间步预测未来24个”。这个比例不是拍脑袋定的它和数据的周期性强相关如果业务数据有日周期窗口至少要覆盖一个完整周期。参数上我建议先记住一个锚点in_len不小于out_len的三倍否则模型几乎只能学出“复制最近时刻”的行为。2.3 Transformer凭什么能做时间序列预测把QKV翻译成时序语言抛开数学符号注意力机制在时间序列里的含义非常直白。Query是当前时间步在问“我该参考过去的哪些时刻”Key是过去每个时间步给出的“我代表什么模式”的索引Value是这些时间步对应的实际数值。注意力权重做的就是当前这个点要更多参考昨天同一时刻还是上一小时的变化趋势。多头注意力则让模型同时用多套尺度去找关系一个头专注短时波动另一个头专注周期规律。这是Transformer做时序预测的核心优势它不像LSTM那样必须按时间顺序把信息一步步传下来而是允许任意两个时间步直接建立联系理论上能捕捉长时间距离的依赖。代价是它天然不知道先后顺序——这是Transformer和时序预测之间最大的裂缝。位置编码就是用来补上这一点的。没有位置编码模型只看见一组无序向量预测出来的曲线会像把输入时间步打乱重排后的结果。顺带说明预测头的两种设计。常见做法一编码器输出所有时间步的表示取最后一个时间步接一个全连接层直接输出未来out_len个值一步到位。常见做法二自回归方式每次只预测一个值把预测值重新作为输入往后滚。zip里的demo一般是第一种简单稳定我这个笔记后面的实现也按第一种来。自回归适合长期预测但误差会随时间步累积计算成本也更高。3. 复现这份代码位置编码、多头注意力、预测头和训练参数怎么设3.1 位置编码和输入嵌入这一步决定了模型是否知道“先来后到”Transformer里没有循环结构所以必须显式注入位置信息。经典的三角函数位置编码长这样import torch import torch.nn as nn import math class PositionalEncoding(nn.Module): def __init__(self, d_model, max_len5000): super().__init__() pe torch.zeros(max_len, d_model) position torch.arange(0, max_len, dtypetorch.float).unsqueeze(1) div_term torch.exp(torch.arange(0, d_model, 2).float() * (-math.log(10000.0) / d_model)) pe[:, 0::2] torch.sin(position * div_term) pe[:, 1::2] torch.cos(position * div_term) pe pe.unsqueeze(0) # (1, max_len, d_model) self.register_buffer(pe, pe) def forward(self, x): return x self.pe[:, : x.size(1), :]设计思路是偶数维度用正弦、奇数维度用余弦频率从低到高铺开这样模型既能区分绝对位置也能通过三角恒等式间接算出相对距离。d_model是每个时间步被嵌入后的向量维度同时是自注意力机制的隐藏维度它决定了位置编码能承载多少信息。这里有个实战经验如果你的序列长度超过max_len模型不会报错但超出部分拿不到位置编码相当于裸奔。所以要么把max_len设成比训练数据最大长度大一个量级要么改成可学习的位置编码。输入嵌入同样重要。常见做法是先对原始数值做归一化再经过一个线性层映射到d_model维最后与位置编码相加。如果不做归一化数值范围差异过大会直接把注意力权重压扁。后面避坑章节会再提到这一点因为这是时序预测里最隐蔽的问题之一。3.2 多头自注意力模块三个形状贯穿整个模型PyTorch封装了现成的TransformerEncoderLayer但复现时要清楚它内部发生了什么否则换数据后无法调参。数据在模型里流动的形状是(batch_size, seq_len, d_model)其中seq_len就是in_len。batch_size是一次喂进去的样本数d_model是特征维度经过嵌入后的维度。多头注意力做的事情是把d_model切分成nhead个头每个头独立计算注意力权重然后再拼回去。nhead的选择要保证d_model能被它整除这是新手最容易碰到的第一个报错。dim_feedforward是前馈网络中间层的维度一般取d_model * 4。dropout建议在0.1到0.3之间数值越小越不容易欠拟合。import torch.nn as nn encoder_layer nn.TransformerEncoderLayer( d_model128, nhead8, dim_feedforward512, dropout0.1, batch_firstTrue, ) encoder nn.TransformerEncoder(encoder_layer, num_layers2)batch_firstTrue让输入形状为(batch_size, seq_len, d_model)符合大多数人的习惯。num_layers2是编码器堆叠的层数层数越多表达能力越强但时序任务里层数超过4层往往收益递减反而加大训练难度和过拟合风险。对于中小规模的时序数据集我建议从2层起步不要一上来就堆6层。3.3 预测头和训练循环从高维特征变回一条未来曲线编码器输出的还是(batch_size, seq_len, d_model)预测时常见做法是取序列最后一个时间步的向量接一个线性层映射到out_len维。为什么取最后一个时间步因为注意力已经把整个序列的信息汇聚到每个时间步而最后一个时间步天然能“看到”前面所有步的信息。完整的模型定义和训练循环如下class TimeSeriesTransformer(nn.Module): def __init__(self, in_len, out_len, d_model, nhead, num_layers, dropout0.1): super().__init__() self.input_proj nn.Linear(1, d_model) self.pos_encoder PositionalEncoding(d_model) self.encoder nn.TransformerEncoder( nn.TransformerEncoderLayer( d_modeld_model, nheadnhead, dim_feedforwardd_model * 4, dropoutdropout, batch_firstTrue, ), num_layersnum_layers, ) self.head nn.Linear(d_model, out_len) def forward(self, x): # x: (batch_size, in_len, 1) x self.input_proj(x) # 线性映射到 d_model x self.pos_encoder(x) # 加位置编码 x self.encoder(x) # 过Transformer编码器 return self.head(x[:, -1, :]) # 取最后时间步映射到out_len训练循环里最值得关注的三个地方损失函数、优化器、学习率策略。时序预测常用的损失是均方误差因为突出大误差适合连续值回归。优化器选Adam默认学习率1e-3算保险起步。学习率策略我用ReduceLROnPlateauloss不降就自动衰减比手动调省事。关于批次大小这里有一个常见权衡Transformer的显存占用随in_len平方级增长因为注意力分数矩阵的形状是(batch_size, nhead, in_len, in_len)。如果你把in_len从96提高到192显存占用不是翻倍是变成四倍。loss_fn nn.MSELoss() optimizer torch.optim.Adam(model.parameters(), lr1e-3) scheduler torch.optim.lr_scheduler.ReduceLROnPlateau(optimizer, factor0.5, patience5)训练参数我常用的起点值汇总如下实际差别很大但可以作为第一次实验的基准。参数建议起点调整方向d_model64~128数据复杂度高时增大nhead8必须整除d_modelnum_layers2过拟合时减小欠拟合时增大in_len96不小于out_len的三倍out_len24越大误差越大batch_size32~64显存不足就减半learning_rate1e-3不收敛就降到3e-4dropout0.1过拟合时升到0.24. 跑Transformer时序预测最容易翻车的5个坑现象、原因、解决4.1 训练了好几轮loss纹丝不动现象train loss在初始值附近震荡不下降也不暴涨。原因通常有两类。第一类是数据没归一化数值的大小差距悬殊比如销售额在几千到几万而模型内部对特征向量的初始化权重是围绕0的前向传播出的预测值可能离目标值很远梯度要么爆炸要么消失。第二类是学习率不合适Transformer对学习率异常敏感太大导致loss震荡不降太小则更新慢到看不出变化。解决先做标准化用训练集的均值和标准差而不是全量数据的避免信息泄露。然后检查学习率从1e-3降到3e-4再试。还有一个被忽略的检查点确认你取的是x[:, -1, :]而不是x[:, 0, :]这个bug的表现就是模型loss缓慢下降但预测曲线形态完全不对。4.2 预测曲线比真实值整体“晚了一步”现象画出预测值和真实值的对比预测曲线看起来像真实曲线向右平移了一个时间步。这是时间序列预测里最经典的滞后现象尤其在金融序列和流量预测中高频出现。原因在于MSE损失会把“预测值接近上一个真实值”当作次优解——因为序列自相关性高上一个值本身就是一个很强的基线模型发现与其冒险预测突变不如复制最近值损失反而更低。解决思路有三个方向。一是让模型不看原始值改看差分序列即预测t时刻与t-1时刻的差值这个序列的自相关性低模型被迫去学真实变化规律。二是用分位数损失替换MSE分位数损失对方向性误差不对称模型预测偏高和偏低的代价不同能缓解滞后。三是缩短out_len预测步长越长滞后越明显先验证短步长下的效果再逐步拉长。4.3 显存OOMbatch_size怎么调都没用现象训练刚开始就报CUDA out of memory把batch_size降到8还是崩。原因是注意力分数矩阵的平方级增长。很多人只想到降batch忽略了in_len。如果in_len512注意力矩阵是512*512batch_size32时跑一次前向就要占掉大量显存。解决先把in_len减半试比如从512降到256显存占用会立刻降为四分之一。如果业务要求长窗口改用稀疏注意力或分块注意力实现PyTorch 2.x的scaled_dot_product_attention已经内置了内存高效实现也可以在TransformerEncoderLayer里开启torch.backends.cuda.enable_flash_sdp(True)。还有一个容易忽略的点老代码里的src_key_padding_mask如果传了一个(batch, seq_len)的布尔张量在batch不相等时容易构造出错排查OOM时先把它注释掉验证。4.4 换成长序列数据后模型效果断崖式下跌现象训练集和验证集loss都正常但在真实长序列上预测结果完全乱掉。常见原因是位置编码的长度上限。默认max_len5000看起来很充裕但如果你的窗口是滑动采样实际编码器输入是in_len个时间步而位置编码表的索引是按seq_len走的。一旦某个batch的序列长度超过了训练时见过的最大长度模型就没见过该位置的编码向量输出自然崩掉。解决把max_len设一个比最大可能seq_len大一倍以上的值比如业务序列最多2000步就设4000。另一个更稳的做法是改用可学习位置编码让模型在训练中自己调整位置向量避免固定编码在长序列上的外推失效。经验上固定三角函数编码在“训练长度以内”表现好可学习编码在“超过训练长度”时更稳。4.5 同一个zip两次运行结果完全不一样现象不加任何修改跑两遍训练预测曲线差别明显。原因就是随机性没有被控制。数据划分、权重初始化、dropout、优化器的每个随机环节都会导致结果漂移。有人把这个当玄学其实是可以控制的。解决在所有入口处固定随机种子。PyTorch要在三个层面同时设置torch.manual_seed、np.random.seed、random.seed。如果用了CUDA还需要设置torch.cuda.manual_seed_all(seed)。注意即使都设置了不同Python版本或PyTorch版本的随机算法实现也可能导致结果微有差异所以报告结果时要把环境和种子一起写清楚。固定种子的意义不是“每次结果一模一样”而是“结果可复现、可对比”——这在调参时几乎是必须的否则你没法判断某次效果提升是来自参数改动还是随机噪声。5. 把这份代码变成业务预测基线三类数据改造、滚动验证、值不值得上Transformer5.1 从正弦函数到真实业务三种最常见的数据改造正弦波demo的问题在于它无限重复、无缺失、无量纲。真实数据第一要务是标准化我建议用训练集的均值方差做标准化然后把标准化参数存下来预测时用同样的参数反变换回原始数值。第二是多变量拼接把外部协变量如星期几、是否节假日、相关指标同步拼到特征维度上d_model的线性层入口也要从1改成feat_dim。第三是缺失值和异常值的处理时间序列预测对历史窗口内的异常点非常敏感一个极端值会通过自注意力污染整段窗口的所有时间步建议先用中位数平滑或插值把幅度异常压掉再做标准化。mean train_data.mean(axis0) std train_data.std(axis0) train_norm (train_data - mean) / std # 预测完成后用 pred * std mean 还原这段代码的逻辑是先用训练集的全局统计量归一化再把归一化后的数据送入模型。这里特别强调用训练集的统计量——如果你把全量数据一起算均值方差会导致验证集信息泄露评估指标虚高。5.2 用滚动回测验证模型别用随机K折要用时序切片时间序列不能随机打乱做交叉验证原因很简单模型要学习的是时间顺序依赖随机打乱会破坏这种依赖而且预测未来时要求用过去的数据不允许用未来的片段。我常用的验证方式是滚动回测模拟线上真实预测环境def rolling_backtest(data, in_len, out_len, step1): for start in range(0, len(data) - in_len - out_len, step): train data[: start in_len] test data[start in_len : start in_len out_len] model.fit(train) pred model.predict(in_len, out_len) yield test, pred每次只把历史数据喂给模型预测下一个窗口然后窗口往前滚。这样做出来的误差指标才是可信的。评估指标用MAE看平均绝对误差、RMSE看大误差惩罚MAPE看相对误差但MAPE在真实值接近0时会爆炸业务序列经常出现这种情况建议加一个小值epsilon保护。更关键的是要和naive基线对比——naive基线就是“预测值等于上一个时刻的值”如果Transformer连这个基线都打不过说明你还没有理由用它。5.3 该不该上Transformer算清楚这笔账再看做技术选型时我习惯把Transformer和另外两个常见方案放在同一张表里看而不是单独夸它。方案适用场景数据量要求训练成本主要短板ARIMA单变量、平稳或差分后平稳几百个时间步即可低非线性关系捕捉能力弱LSTM中等长度序列、非线性模式千级以上中长距离依赖容易衰减Transformer长序列、多变量、周期性复杂建议至少数万时间步高数据少时容易过拟合训练慢以我的经验这个标题里的zip在正弦函数demo上表现惊艳因为正弦波是注意力机制最擅长捕捉的模式。到了真实业务里如果样本量不大、模式相对平稳LSTM甚至ARIMA都可能和它打平。我自己的判断标准是序列长度超过500个时间步、有明显长距离依赖、且你有足够的计算资源就值得上Transformer。如果只是短时外推先用轻量方案。就我个人的习惯来说拿到这类项目后第一件事永远是拿小模型、短窗口、固定种子跑通一个最简基线确认数据没有泄露、验证流程可靠再去追求模型结构的复杂度。预测曲线的滞后问题不要指望调参解决它更像是任务定义和数据预处理的问题。把位置编码的max_len、注意力矩阵的显存账、标准化参数的保存这三件事记在心理清单上基本能避开我踩过的大多数坑。这里再补充一个值得做的进阶动作把注意力权重可视化看模型在预测每个点时重点参考哪些时间步你很快会发现它学到的不只是最近点还有周期性位置。这个发现会帮你更合理地去定in_len。希望这些踩坑记录能帮你少走一段弯路让你从“跑通demo”到“上线基线”这一步走得更稳。本文还有配套的精品资源点击获取