Transformer时间序列预测代码库：统一框架与15个主流模型深度优化-平芜编程栈

简介：本资源是面向时间序列预测与分析领域的研究者及算法工程师的Transformer架构实践合集，聚焦长时间序列建模这一核心挑战，覆盖Autoformer、Informer、TimesNet、DLinear等15种主流改进模型。资源包共1378个文件，含228个可执行Shell脚本（用于环境配置与训练调度）、137个Python主程序及模块（含数据加载、模型定义、训练循环与评估逻辑）、774份PDF文档（含论文原文、技术报告与实验分析），辅以CSV/NPY格式的多源真实数据集（电力负荷、ETT油温、交通流量、天气、外汇及医疗病情等）。压缩包大小为182.2MB，结构清晰，支持开箱即用与模块化调试。已有3448人学习下载，读者可直接复现各模型在不同场景下的预测性能，获取完整训练流程、跨数据集适配方案及典型超参配置经验，显著降低长时序建模的入门与调优门槛。

1. 项目概述：为什么我们需要一个长时间序列Transformer代码库？

如果你正在做时间序列预测，特别是那种需要处理很长历史数据的项目，比如电力负荷预测、气象预报、金融量化交易，那你一定绕不开Transformer。这个在自然语言处理领域大杀四方的模型，因为其强大的序列建模能力，被大家寄予厚望。但当你兴冲冲地打开一篇论文，想复现里面的Informer或者Autoformer时，往往会发现一个尴尬的现实：论文里的代码要么是“伪代码”，要么是高度抽象、依赖特定框架的片段，不同论文的代码风格、数据接口、评估标准五花八门。你想对比一下Autoformer和FEDformer在你自己数据集上的效果？光是统一数据加载和评估指标，可能就得花上几天时间。

这就是我动手整理这个“基于Transformer的长时间序列代码汇总”项目的初衷。它不是一个简单的代码打包，而是一个统一、可复现、深度优化的代码基准框架。我集成了包括Autoformer, FEDformer, Informer, Pyraformer, Non-stationary Transformer等在内的15个主流算法，确保它们能在同一个标准下公平对比。更重要的是，我花了大量时间在工程实现上做了优化和调试，把那些论文里没写、但实际跑代码时一定会踩的坑，都提前填平了。无论你是刚入门想跑通一个baseline，还是资深研究员想进行公平的模型对比与消融实验，这个项目都能让你省下大量“造轮子”和“调环境”的时间，直接聚焦于核心问题。

2. 核心架构与设计哲学：如何构建一个公平的“擂台”？

2.1 统一框架下的模块化设计

要让15个算法同台竞技，首要原则是“公平”和“可扩展”。我采用了高度模块化的设计，将整个时间序列预测流程拆解为彼此独立、接口清晰的组件。

数据模块：这是所有实验的起点。我设计了一个通用的DataFactory类，它不关心你用的是ETTh1（电力变压器温度）数据集还是Exchange（汇率）数据集。你只需要通过一个配置文件指定数据集名称、预测长度（pred_len）和历史长度（lookback_len），它就能自动处理数据下载、缺失值填充、标准化（我默认使用RobustScaler，对异常值更鲁棒），并生成统一的PyTorch DataLoader。这样做的好处是，任何新模型接入时，完全无需关心数据是怎么来的，只需要从DataLoader里取batch就行。

模型模块：这是核心。每个模型（如Informer、Autoformer）都是一个独立的PyTorch Module子类。但它们都继承自一个公共的基类BaseModel。这个基类定义了所有模型必须实现的接口，比如forward函数必须返回预测结果和（可选的）注意力权重。更重要的是，我在基类里统一了模型参数的初始化策略（如Xavier初始化）和一些共用的子模块（如位置编码）。这样既能保证各模型独特的创新点得以保留，又避免了大量重复代码。

训练与验证循环：我实现了一个Experiment类来统领整个训练流程。它封装了标准的训练epoch、验证epoch和测试流程。损失函数（默认为平滑L1 Loss）、优化器（AdamW）、学习率调度器（CosineAnnealingLR with warmup）都在这里统一配置。最关键的是，评估指标的计算也被标准化了。我实现了MSE, MAE, RMSE, MAPE, SMAPE等常见指标，并确保它们在所有模型上的计算方式完全一致，杜绝了因指标计算细微差别导致的性能误判。

2.2 工程实现的关键优化点

论文里的模型往往追求数学上的优雅和实验指标的漂亮，但工程实现上常有“坑”。我在集成这些模型时，做了大量优化以确保其高效和稳定。

内存效率优化：Transformer的核心操作是自注意力，其复杂度是序列长度的平方（O(L²)）。对于长时间序列（比如lookback_len=720），这会导致巨大的内存开销。我针对每个模型的特点进行了优化：

Informer：实现了其提出的ProbSparse自注意力，有效降低了计算复杂度。
Autoformer：高效实现了其序列分解模块（Series Decomposition Block）和Auto-Correlation机制。特别是Auto-Correlation中的快速傅里叶变换（FFT），我使用了PyTorch内置的torch.fft模块，并确保其在CPU和GPU上都能高效运行。
FEDformer：其核心是傅里叶基和随机选择的傅里叶分量。我优化了傅里叶变换和逆变换的流程，并提供了配置项来控制所使用的分量数量，以在精度和速度间取得平衡。

训练稳定性技巧：Transformer模型，尤其是深层的，容易训练不稳定。我集成了几个经过验证的技巧：

梯度裁剪（Gradient Clipping）：这是必须的。我将全局梯度范数限制在1.0，有效防止了训练初期的梯度爆炸。
学习率预热（Learning Rate Warmup）：在训练的前5%个step里，学习率从0线性增长到设定值。这给了模型参数一个稳定的“热身”期。
标签平滑（Label Smoothing）：在计算损失时，对真实标签加入一个小的均匀分布噪声（如0.1）。这相当于一种正则化，可以缓解模型对训练数据的过拟合，提升泛化能力，在时间序列预测中效果显著。

可复现性保障：我固定了所有随机种子（包括Python, NumPy, PyTorch, CUDA），确保每次运行同一组配置，得到的结果是完全一致的。这对于严谨的实验对比至关重要。

3. 核心模型代码深度解析与实操要点

在这个部分，我会挑选几个最具代表性、也最容易在实现上出问题的模型，深入剖析其代码实现的关键细节和我的优化心得。

3.1 Informer：ProbSparse自注意力的高效实现

Informer的核心创新是ProbSparse自注意力，它通过选择性地计算最重要的Q-K对，将注意力复杂度从O(L²)降到了O(L log L)。论文中的描述比较理论，实现时有几个关键点：

prob_sparse_attention函数的实现：

def prob_sparse_attention(self, Q, K, V): # Q, K, V: [batch_size, n_heads, seq_len, d_head] B, H, L, D = Q.shape # 1. 采样关键位置：计算K的均值作为“度量” M = self.sample_factor * int(math.log(L)) # 采样点数 K_mean = K.mean(dim=-2) # [B, H, D] # 计算Q与K_mean的相似度，选取Top-M个查询 scores = torch.matmul(Q, K_mean.transpose(-2, -1)) # [B, H, L] top_indices = scores.topk(M, dim=-1).indices # [B, H, M] # 2. 只计算被选中的Q与所有K的注意力 Q_selected = Q.gather(dim=-2, index=top_indices.unsqueeze(-1).expand(-1, -1, -1, D)) attn_scores = torch.matmul(Q_selected, K.transpose(-2, -1)) / math.sqrt(D) attn = F.softmax(attn_scores, dim=-1) # 3. 计算输出 context = torch.matmul(attn, V) # [B, H, M, D] # 需要将输出映射回原始序列位置（这里简化处理，实际Informer有更复杂的操作） # ...

注意：上述代码是一个高度简化的示意，用于说明原理。实际项目中，我完整实现了Informer论文中的ProbAttention类，并处理了padding_mask和attn_mask，确保其在训练和推理时行为正确。一个常见的坑是采样因子sample_factor的设置，太小会导致信息丢失严重，太大则失去了稀疏化的意义。我的经验是，对于大多数时间序列任务，设为5是一个不错的起点。

3.2 Autoformer：Auto-Correlation机制与序列分解

Autoformer用自相关（Auto-Correlation）机制替代了传统自注意力，并引入了序列分解（Series Decomposition）作为模型的基本单元。这是两个非常巧妙的创新。

序列分解模块（SeriesDecomp）：

class SeriesDecomp(nn.Module): def __init__(self, kernel_size): super().__init__() self.moving_avg = nn.AvgPool1d(kernel_size=kernel_size, stride=1, padding=kernel_size//2) def forward(self, x): # x: [Batch, Length, Channel] x = x.permute(0, 2, 1) # 转换为 [Batch, Channel, Length] 以适应1D卷积 trend = self.moving_avg(x) seasonal = x - trend return trend.permute(0, 2, 1), seasonal.permute(0, 2, 1) # 恢复形状

这个模块通过移动平均来提取序列的长期趋势项（trend），原始序列减去趋势项得到季节性项（seasonal）。关键在于kernel_size的选择。如果设置得太小（如3），趋势项会包含太多高频噪声；如果太大（如25），可能会过度平滑，丢失真实趋势。我通常根据数据的周期性和预测长度来调整，例如对于每小时数据，kernel_size=24（一天）是一个有物理意义的尝试。

自相关机制（AutoCorrelation）：自相关的核心思想是发现序列基于周期的依赖关系，而不是基于点对点的依赖。实现的重点是快速计算时延自相关并通过Softmax选择最相关的几个时延。

def auto_correlation(self, queries, keys, values): # 使用FFT快速计算自相关 q_fft = torch.fft.rfft(queries, dim=-1) k_fft = torch.fft.rfft(keys, dim=-1) corr = torch.fft.irfft(q_fft * torch.conj(k_fft), dim=-1) # [B, H, L, 2*L-1]? # 在实际实现中，需要处理维度对齐和Top-K时延选择 # 选择自相关最高的Top-k个时延 top_k_corr, top_k_lags = torch.topk(corr, k=self.top_k, dim=-1) # 根据时延，对values进行滚动对齐和聚合 # ...

实操心得：Auto-Correlation的计算涉及复数FFT，需要特别注意张量的维度。PyTorch的torch.fft模块在CUDA和CPU上的行为完全一致，但确保输入张量是torch.float32或torch.float64类型。另一个性能优化点是，对于固定的序列长度L，可以预先计算好所有可能的时延索引，在训练中通过gather操作来聚合values，这比在循环中动态roll要高效得多。

3.3 FEDformer：频率增强的Transformer

FEDformer在频率域（傅里叶域和小波域）进行注意力操作，其实现的关键在于如何高效、稳定地在时域和频域之间转换，并操作选定的频率分量。

傅里叶变换分支的实现要点：

class FourierBlock(nn.Module): def __init__(self, d_model, freq_sel_method='random', num_freqs=None): super().__init__() self.freq_sel_method = freq_sel_method # 随机选择频率分量 if freq_sel_method == 'random': assert num_freqs is not None self.selected_indices = torch.randperm(d_model // 2)[:num_freqs] # 随机选择实数FFT后一半频率中的一部分 def forward(self, x): # x: [B, L, D] B, L, D = x.shape x_ft = torch.fft.rfft(x, dim=1) # 沿时间维度做FFT, 得到 [B, L//2+1, D] # 只操作选中的频率分量 if self.freq_sel_method == 'random': # 对选中的频率分量应用一个简单的MLP进行变换 selected_freqs = x_ft[:, :, self.selected_indices] # 这是一个简化的示意，实际维度处理更复杂 # ... 进行频率域的特征交互 ... # 逆变换回时域 # ...

注意事项：FEDformer论文中提到了两种频率选择方式：‘random’和‘low’。‘random’方式通常效果更好，但引入了随机性。为了实验的可复现性，必须在初始化模型时固定随机种子，并保存这个selected_indices，否则每次模型初始化都会选择不同的频率分量，导致结果无法比较。在我的实现中，我将这个选择逻辑封装起来，并确保在加载预训练模型时，频率选择模式保持一致。

4. 从零开始的完整实验流程与参数调优指南

有了统一的代码框架，如何设计并运行一个完整的实验来验证或对比模型呢？下面我以一个具体的场景为例：在ETTh1（电力负荷）数据集上，对比Informer、Autoformer和FEDformer在96点预测任务上的表现。

4.1 环境配置与数据准备

首先，你需要克隆项目并安装依赖。我强烈建议使用Conda或虚拟环境来管理依赖。

# 克隆项目 git clone [项目仓库地址] cd time-series-transformers-benchmark # 创建并激活虚拟环境 (以conda为例) conda create -n ts_transformer python=3.9 conda activate ts_transformer # 安装核心依赖 pip install torch==1.13.1+cu117 torchvision==0.14.1+cu117 torchaudio==0.13.1 --extra-index-url https://download.pytorch.org/whl/cu117 pip install -r requirements.txt # 这里面包含了pandas, numpy, scikit-learn, matplotlib等

数据准备非常简单。项目根目录下有一个configs/文件夹，里面存放了各种数据集和模型的配置文件。例如，configs/ETTh1.yaml定义了ETTh1数据集的路径、预测长度、历史长度、训练/验证/测试集划分比例等。你通常不需要修改它，除非你想尝试不同的数据划分策略。

4.2 模型训练与超参数调优

训练一个模型主要通过运行scripts/train.py并指定配置文件来完成。

python scripts/train.py --config configs/ETTh1_Informer.yaml

让我们深入看一下这个配置文件的关键部分，并解释如何调优：

# configs/ETTh1_Informer.yaml data: name: 'ETTh1' root_path: './data/ETT/' data_path: 'ETTh1.csv' features: 'M' # 多元预测，也可以是'S'（单变量）或'MS'（多元预测单变量） target: 'OT' # 目标列名 lookback_len: 96 # 输入序列长度 pred_len: 96 # 预测序列长度 scale: True # 是否标准化 model: name: 'Informer' d_model: 512 # 模型隐藏层维度 n_heads: 8 # 注意力头数 e_layers: 2 # 编码器层数 d_layers: 1 # 解码器层数 d_ff: 2048 # 前馈网络维度 dropout: 0.05 # Dropout率 attn: 'prob' # 注意力类型，'prob'代表ProbSparse factor: 5 # ProbSparse的采样因子 train: epochs: 10 batch_size: 32 learning_rate: 0.0001 loss: 'mse' lradj: 'type1' # 学习率调整策略

超参数调优实战指南：

d_model(模型维度)：这是最重要的参数之一。更大的d_model意味着更强的表示能力，但也意味着更多的参数和计算量。对于ETTh1这种中等复杂度的数据集，512是一个很好的平衡点。如果数据集非常小（如少于1万个样本），可以尝试降低到256或128以防止过拟合；如果数据集很大且模式复杂，可以尝试768。
lookback_len和pred_len(历史与预测长度)：这两个参数需要根据数据的周期性来设定。对于每小时数据，lookback_len=168（一周）和pred_len=24（一天）是常见组合。我的建议是，lookback_len至少应包含2-3个完整周期，而pred_len应根据你的实际业务需求设定。
dropout：Transformer模型容易过拟合，dropout是有效的正则化手段。我从一个较小的值开始（如0.05），如果训练损失和验证损失差距很大（过拟合），就逐步增加到0.1或0.2。对于解码器层，有时可以设置比编码器更高的dropout率。
学习率与优化器：我默认使用AdamW优化器，它对权重衰减的处理比Adam更正确。学习率是另一个关键。对于Transformer，较小的学习率（1e-4到1e-5）通常更稳定。配合学习率预热（我已集成）和余弦退火调度，可以有效提升模型最终性能。

4.3 结果可视化与模型对比

训练完成后，日志和模型检查点会保存在results/目录下。我编写了一个评估脚本scripts/eval.py，可以加载训练好的模型，在测试集上运行并生成详细的评估报告和可视化图表。

python scripts/eval.py --config configs/ETTh1_Informer.yaml --checkpoint results/ETTh1_Informer/best_model.pth

评估脚本会输出MSE、MAE等指标的数值，并生成两种关键图表：

预测对比图：将测试集上某一段的真实序列与模型预测序列绘制在一起，直观感受预测效果。
指标对比柱状图：如果你用同样的配置训练了多个模型（如Informer, Autoformer, FEDformer），可以运行一个批量评估脚本，生成所有模型在MSE、MAE等指标上的柱状对比图，一目了然。

如何解读结果：

如果训练损失持续下降，但验证损失很早就开始上升，这是典型的过拟合。需要增加dropout、使用更激进的数据增强、或者减少模型容量（如降低d_model或层数）。
如果训练和验证损失都下降得很慢，可能是学习率太小、模型容量不足，或者数据本身噪声太大、难以学习。
对比不同模型时，不要只看一个指标（如MSE）。同时关注MAE和SMAPE。MSE对异常值敏感，MAE更稳健。SMAPE是百分比误差，便于理解预测的平均偏差比例。一个稳健的模型应该在多个指标上都表现良好。

5. 常见问题排查与实战经验实录

即使有了完善的代码，在实际操作中你还是会遇到各种问题。下面是我在开发和调试这个项目过程中，遇到的一些最具代表性的“坑”及其解决方案。

5.1 内存溢出（OOM）问题

这是训练Transformer，尤其是长时间序列模型时最常见的问题。

症状：训练开始不久，程序崩溃，PyTorch报错CUDA out of memory。

原因与排查：

Batch Size过大：这是首要怀疑对象。尝试将batch_size从32降低到16或8。虽然这会减慢训练速度，但能最直接地缓解内存压力。
序列长度过长：检查你的lookback_len。如果设置为720或更高，即使batch size很小也可能OOM。考虑是否真的需要这么长的历史信息。可以尝试使用模型的稀疏注意力变体（如Informer）或频率域模型（如FEDformer），它们对长序列更友好。
模型参数过多：检查d_model,d_ff,e_layers,d_layers这些参数。一个d_model=1024, d_ff=4096, e_layers=4的模型，参数量会非常庞大。对于大多数时间序列任务，从较小的配置开始（如512/2048/2）是更稳妥的。
梯度累积：如果你的GPU只能支持很小的batch size，导致训练不稳定，可以使用梯度累积。例如，设置batch_size=8并累积4步，其效果近似于batch_size=32，但峰值内存占用只有前者的1/4。在我的训练脚本中，可以通过设置gradient_accumulation_steps参数来实现。

5.2 训练不收敛或损失为NaN

症状：训练损失在几个epoch后不再下降，或者突然变成NaN。

排查与解决：

检查数据标准化：确保数据标准化（scale: True）是正确的。我使用的是RobustScaler，它对异常值不敏感。如果数据中存在极端异常值，可以先进行裁剪（clipping）或 winsorization 处理。一个快速检查的方法是，打印出标准化后数据的均值和标准差，它们应该接近0和1。
检查学习率：过大的学习率会导致优化“过冲”，损失震荡甚至爆炸。尝试将学习率降低一个数量级（例如从1e-3降到1e-4）。同时，务必启用学习率预热（Warmup），这在我的代码中是默认开启的。
启用梯度裁剪：这是防止梯度爆炸、稳定训练的关键技术。我已经在训练循环中默认加入了梯度裁剪（max_norm=1.0）。如果你遇到NaN，可以尝试将这个值调小，比如到0.5。
检查损失函数：对于某些包含比例计算（如MAPE）的损失函数，如果真实值中有零，会导致除零错误。确保你的目标变量没有零值，或者使用平滑版本的损失函数（如SmoothL1Loss，我已默认使用）。
降低模型复杂度：如果以上方法都无效，可能是模型过于复杂，对于当前数据量来说难以优化。尝试减少网络层数或隐藏层维度。

5.3 预测结果存在明显的滞后（Lag）或相位偏差

症状：模型预测的曲线形状与真实曲线相似，但在时间轴上整体向后偏移了几个时间步。

原因与解决：这是时间序列预测中一个经典问题，表明模型没有学会“提前”变化，而是倾向于输出与最近输入值相似的序列（一种保守策略）。

调整损失函数：MSE损失容易导致“平均主义”，产生滞后预测。尝试使用分位数损失（Quantile Loss）或分位数回归。例如，预测中位数（0.5分位数）而不是均值，对异常值更鲁棒。也可以同时预测多个分位数（如0.1, 0.5, 0.9）来获得预测区间。我在项目中提供了分位数损失的选项。
引入差分特征：除了原始序列值，将序列的一阶差分（x[t] - x[t-1]）甚至二阶差分也作为模型输入特征。这相当于让模型直接学习“变化量”，有助于捕捉转折点。
使用更强大的解码器：一些模型（如Autoformer）的分解架构，显式地建模趋势项，有助于缓解滞后问题。可以尝试对比不同模型在这个问题上的表现。
数据层面：检查是否存在“数据泄露”（Data Leakage）。确保在构建训练样本时，用于预测未来pred_len步的特征，绝对不能包含那pred_len步之后的信息。我的数据加载器已经严格确保了这一点。

5.4 如何在自己的数据集上使用这个框架？

这是大家最关心的问题。我的框架设计目标之一就是易于扩展。

步骤：

准备数据：将你的数据整理成一个CSV文件，每一行是一个时间点，每一列是一个特征（变量）。确保有一列是时间戳（可选），并明确哪一列是你的预测目标（target）。
创建数据集类：在data/目录下，参照dataset_ett.py创建一个新的数据集类（例如dataset_mydata.py）。这个类需要继承BaseDataset，并实现__init__,__getitem__,__len__方法。核心逻辑就是读取CSV，进行必要的预处理（处理缺失值、类型转换），然后根据lookback_len和pred_len滑动窗口生成样本。
修改数据工厂：在data/data_factory.py的get_dataset函数中，添加一个条件分支，当data_name为你的数据集名称时，实例化你刚创建的数据集类。
创建配置文件：复制一份现有的配置文件（如ETTh1.yaml），修改data_path,target,features等参数指向你的数据。
开始训练：使用新配置文件启动训练。python scripts/train.py --config configs/mydata.yaml