简介：时空序列预测的核心难点在于同时建模节点间的空间依赖与序列中的长程时间依赖。这份资源包给出了图神经网络（GNN）与Transformer结合的完整Python实现，面向有一定深度学习基础、从事交通流量、网络负载等时空预测任务的研究者与算法工程师。压缩包内共2个文件，分别是一个Python脚本和一个CSV数据文件，整体仅28.36MB。脚本搭建了端到端的时空预测模型：先通过GNN聚合邻居信息提取空间特征，再利用Transformer自注意力机制捕获长期时间关联；配套的CSV文件为Abilene骨干网的OD流量数据，可直接加载并复现实验。目前已有267人学习，借助代码与真实数据，读者既能快速验证模型效果，也能深入理解空间图信息与时间注意力机制融合的工程实现细节，方便迁移到其他时空序列预测场景。

1. GNN+Transformer组合拳：先搞清楚这套架构解决的是哪类时序问题

如果你手里的时序数据是多变量、通道之间还存在明显空间或拓扑关系，比如交通路网的车流量、气象站的温度/气压分布、电网节点的负荷值，那么单一Transformer往往只能学到时间维上的依赖，却很难把站点之间那种“相邻即相关”的结构信息利用起来。把GNN作为空间编码器、Transformer作为时间编码器拼在一起，是目前处理这类复杂时空序列的主流做法。这套组合并不适合所有场景，但只要你面对的是“多个传感器/节点、彼此有物理或逻辑连接、每个节点都在持续产生观测值”这样的数据，它就是收益最明确的方向之一。本文会从为什么这样拆、怎么建图、怎么搭模型、在哪踩坑，一步步把方案讲透。

2. 为什么是GNN负责空间、Transformer负责时间：双编码器的设计动机

2.1 单一Transformer处理多节点时序时，到底缺了什么

你可以把Transformer看作一个擅长“按位置找关联”的序列模型。给它一条长度T的序列，它能通过自注意力算出每个时间步之间的关系。但把多个节点的数据堆成一个高维输入，Transformer天然不知道节点A和节点B是邻居还是毫无关系。你当然可以让注意力自己去学，但问题是：交通路网上相距很远的两个路口可能流量模式相似，而相邻路口反而可能因为信号灯周期出现相位差。如果完全交给Transformer学习节点间关系，它需要大量数据才能隐式建模这种结构，而且训练难度会明显上升。

GNN解决的问题恰恰是这个：它把“节点之间的连接关系”作为先验知识直接注入模型。在图卷积中，每个节点更新表征时会显式汇总邻居节点的信息，这样空间依赖就不是靠注意力隐式发现，而是被结构直接约束。常见做法是构建邻接矩阵A，A[i][j]表示节点i和节点j之间的连接强度，图卷积层通过A做特征传播。GNN的作用不是预测，而是把原始节点特征转成带有空间上下文的结构化表征。

这就是为什么要把GNN放在Transformer之前：先把每个时间步上的节点特征做一次空间聚合，让每个位置的表征已经包含了它在图上的邻居信息。Transformer再在这个聚合后的序列上建模时间演化，两个编码器各管一个维度，职责清晰，不会出现一个模块同时建模双维度导致的优化困难。

2.2 构建邻接矩阵和滑窗样本：两个决定上限的细节

建图方式没有统一答案，但有几个常用方案可以直接上手。如果你的数据自带距离信息，比如气象站经纬度、电网节点的地理坐标，用高斯核计算边的权重是稳定的做法：两个节点距离越近，边的权重越大。公式是A_ij=exp(-(dist_ij^2)/(2*sigma^2))，sigma控制影响半径。如果数据没有坐标，但有业务逻辑关系，比如股票之间属于同一行业板块、传感器属于同一设备组，那就直接用0/1邻接矩阵，有业务关系就置1。

建图时有个参数很容易被忽略：自环。GNN在聚合邻居信息时，如果邻接矩阵对角线上没有1，节点自己的特征会被自身权重乘以0从而丢失，所有节点的表征都被迫只能来自邻居。第一次跑通后记得给A加上单位阵，即Ã=A+I，再按行归一化。否则你会看到模型训练loss降得很慢，甚至收敛后预测值比真实值整体偏平。

滑窗样本的构建也直接决定模型看到的上下文长度。对每个样本，输入形状是[B, T_in, N, D]，B是batch size，T_in是历史窗口长度，N是节点数，D是每个节点的特征维度。输出形状是[B, T_out, N, 1]，T_out是预测步数。窗口长度建议从T_in=12、T_out=3这种比例起步，即用12个历史时间步预测未来3步，而不是一次性预测到很远。预测距离越长，误差累积越明显，后续想优化也需要单独处理。

3. 从零搭一个GNN+Transformer时序预测模型：PyTorch实现

3.1 数据准备：从原始表格到图结构样本

第一步是把数据整理成模型能吃的格式。假设你有一个CSV文件，每行是一个时间戳，每列是一个传感器节点。先完成缺失值填充、标准化，然后构建邻接矩阵，最后生成滑窗样本。

import numpy as np import pandas as pd import torch from torch.utils.data import Dataset, DataLoader def build_adjacency(dist_matrix, sigma=1.0): """根据距离矩阵构建高斯核邻接矩阵""" adj = np.exp(-(dist_matrix ** 2) / (2 * sigma ** 2)) np.fill_diagonal(adj, 1.0) # 加自环，保留自身特征 adj = adj / adj.sum(axis=1, keepdims=True) # 按行归一化 return adj class TimeSeriesGraphDataset(Dataset): def __init__(self, data, adj, t_in=12, t_out=3): self.data = data # shape: [T, N] self.adj = adj # shape: [N, N] self.t_in = t_in self.t_out = t_out # 数据标准化：按每个节点独立做z-score self.mean = data.mean(axis=0) self.std = data.std(axis=0) + 1e-6 self.data_norm = (data - self.mean) / self.std def __len__(self): # 每个样本用t_in个历史步预测t_out个未来步 return len(self.data_norm) - self.t_in - self.t_out + 1 def __getitem__(self, idx): x = self.data_norm[idx : idx + self.t_in] # [T_in, N] y = self.data_norm[idx + self.t_in : idx + self.t_in + self.t_out] # [T_out, N] return torch.FloatTensor(x), torch.FloatTensor(y)

数据标准化必须按每个节点单独计算均值和标准差，不做全局归一化。原因很直接：不同节点的数值范围可能差出数量级，比如主干道车流量和支路车流量，全局归一化后支路节点的特征数值会被压到接近0，模型几乎学不到它的变化模式。实现里的1e-6是防止某个节点长时间无变化导致std=0的除零错误，这是实际数据里很容易碰到的边界条件。

3.2 模型结构：GCN编码加Transformer时间建模

模型由三个模块组成：一个GCN把原始节点特征映射为空间聚合表示，一个线性投影对齐Transformer的输入维度，一个TransformerEncoder完成时间建模，最后通过回归头输出预测值。

import torch.nn as nn import torch.nn.functional as F from torch_geometric.nn import GCNConv class SpatialTemporalTransformer(nn.Module): def __init__(self, n_nodes, in_dim, hidden_dim, t_in, t_out, n_heads=4, gcn_layers=2, dropout=0.1): super().__init__() self.n_nodes = n_nodes self.t_out = t_out # 空间编码：两层GCN，逐层聚合邻居信息 self.gcn1 = GCNConv(in_dim, hidden_dim) self.gcn2 = GCNConv(hidden_dim, hidden_dim) # 时间投影：T_in个时刻共享一组参数 self.input_proj = nn.Linear(hidden_dim, hidden_dim) # 时间建模：标准TransformerEncoder encoder_layer = nn.TransformerEncoderLayer( d_model=hidden_dim, nhead=n_heads, dim_feedforward=hidden_dim * 4, dropout=dropout, batch_first=True ) self.transformer = nn.TransformerEncoder(encoder_layer, num_layers=3) # 回归头：对每个节点的每个预测时刻输出1个值 self.reg_head = nn.Linear(hidden_dim, 1) def forward(self, x, edge_index): # x: [B, T_in, N, D]，edge_index: [2, E] B, T, N, D = x.shape # 时间维平铺成batch，让GCN同时处理所有时刻 x = x.reshape(B * T, N, D) x = F.relu(self.gcn1(x, edge_index)) x = F.relu(self.gcn2(x, edge_index)) x = x.reshape(B, T, N, -1) # 交换N和T维，让Transformer沿时间轴建模 x = x.permute(0, 2, 1, 3) # [B, N, T, D] x = self.input_proj(x) x = self.transformer(x) # [B, N, T, D] # 对每个时间步输出预测 x = self.reg_head(x) # [B, N, T, 1] return x.squeeze(-1).permute(0, 2, 1) # [B, T_out, N]

核心思路是分步处理：GCN只做空间信息聚合，不跨越时间维度，每个时间步独立做图卷积。之后把N和T两个维度交换，让Transformer在时间维上计算自注意力。这里有个容易写错的地方——permute(0, 2, 1, 3)这行。原始张量是[B, T, N, D]，交换后成了[B, N, T, D]，如果不做这一步交换，Transformer会在N维上做注意力，那等于把节点当成了序列，学习的是“节点之间”的关系，整个模型的意义就变了。调通后建议打印一下每一层的输出shape，逐层确认维度是否符合预期，这个习惯能省下大量排错时间。

3.3 训练循环和必调参数：学习率、权重衰减和图边稀疏化

import torch.optim as optim def train_model(model, train_loader, adj, epochs=60, lr=3e-4): device = torch.device("cuda" if torch.cuda.is_available() else "cpu") model = model.to(device) edge_index = torch.nonzero(torch.FloatTensor(adj > 0.1), as_tuple=False).T.to(device) optimizer = optim.AdamW(model.parameters(), lr=lr, weight_decay=1e-4) scheduler = optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs) loss_fn = nn.MSELoss() for epoch in range(epochs): model.train() epoch_loss = 0 for x, y in train_loader: x = x.to(device) y = y.to(device) optimizer.zero_grad() pred = model(x.unsqueeze(-1), edge_index) loss = loss_fn(pred, y) loss.backward() nn.utils.clip_grad_norm_(model.parameters(), max_norm=5.0) optimizer.step() epoch_loss += loss.item() scheduler.step() if (epoch + 1) % 10 == 0: print(f"Epoch {epoch+1}/{epochs}, Loss: {epoch_loss/len(train_loader):.6f}")

loss输出在epoch10以后出现明显下降，通常说明网络结构没有大问题。如果一直在0.9以上原地踏步，优先怀疑数据标准化出了问题，其次检查GCN的edge_index构建，最后才考虑调学习率。

一个关键超参是邻接矩阵的稀疏化阈值。很多项目直接拿全连接图训练，但全连接图会让每个节点聚合全部节点的信息，GCN退化成全局平均池化，空间分辨能力大幅下降。训练速度也会受影响。建议先统计邻接矩阵的权重分布，把低于某个阈值的边置零，让每个节点只连接最相关的几个邻居。常见做法是保留权重最大的5到10个邻居，这样既有空间聚合效果，又不至于信息过载。阈值参数需要根据具体数据的空间相关性试几次，一般0.1到0.5之间会有个明显的性能拐点。

4. 训练GNN+Transformer时的五个高频坑：现象、原因和解决办法

4.1 Loss不降或下降极慢，输出接近均值

模型训练完，预测结果几乎是所有样本的平均值，完全没有波动。这个现象在GNN+Transformer里非常常见，尤其是数据存在明显周期性时。起因是回归头输出的L2 loss在优化时偏向“保守策略”——预测一个接近均值的常数，比预测一个会波动的曲线产生的平均误差更小，尤其在数据信噪比不高的时候。解决思路分两步走：第一，检查标准化是否合理，如果std非常小，模型学不到有效梯度信号，考虑改用MAPE或Huber Loss；第二，把学习率从3e-4降到1e-4，配合warmup阶段让Transformer的注意力矩阵先稳定下来，再开始充分训练。这也是为什么训练循环里加了梯度裁剪——TransformerEncoder在深度较深时容易梯度爆炸，clip可以保证初期不崩。

4.2 transformer时序预测近期拟合好但远期崩坏

如果你用12步输入预测12步输出，通常前3步的预测曲线还能跟上真实趋势，4步以后就明显偏离甚至发散。这不代表模型不行，而是自回归式的误差累积在这个架构里被放大：Transformer每个输出步都是独立预测，但输入序列的末尾部分对远期输出的注意力权重较低。两种解决路径比较有效。第一种是把监督目标改成多步损失加权，让离当前越近的预测步权重越高，比如[l 1.0, 0.9, 0.8]这样的递减权重。第二种是改变任务定义，把12步预测改成滚动预测：训练时每次只预测一步，预测结果作为下一次输入的一部分，推理时循环12次。单步预测的准确率明显更高，但推理时间会增加到12倍，需要根据业务需求取舍。

4.3 GNN的graph卷积层数加深后性能反而下降

把GCN从2层加到4层，预期是捕获更远距离的空间依赖，但验证集误差反而上升。这是GNN的过平滑问题：层数越多，每个节点的表征被聚合得越均匀，最后所有节点趋向同一个向量，模型失去分辨力。另一个诱因是图本身有连通性较强的社区结构，多层传播会把不相关的节点信息带进来。解决方式是回到2层，如果确实需要更广阔的视野，不靠加深GCN，而是把邻接矩阵的高次幂预计算出来，即用A^2、A^3作为额外边，或者改用GAT让模型自己学习每条边的注意力权重。GAT比GCN在多节点数据上更稳定，缺点是内存占用更大，节点超过500个时要注意显存限制。

4.4 验证集上指标很好，换一个时段就全面崩盘

模型在测试集上表现不错，但把数据按月份切分，用1-2月的模型直接跑3月的数据，误差翻倍。这个现象通常指向两个问题。一是训练/测试切分不够严谨，可能是随机切分导致相邻时间戳的样本相互泄漏，比如用2月1日的数据预测2月2日，而2月2日的数据恰好也在训练集中。解决方法是按时间顺序切分，训练集用前70%，验证集用中间15%，测试集用最后15%，并且每个样本之间距离至少T_out步。二是数据分布漂移，比如交通流量在工作日和节假日的模式完全不同，单一模型很难覆盖全部模式。先把节假日样本单独筛选出来，单独训练一个专用模型，比硬塞进同一个模型更有效。这是实践中经常被忽视的一条。

4.5 位置编码在时序预测里容易帮倒忙

Transformer自带的PositionalEncoding是针对自然语言设计的，时序预测里直接套用会导致模型过度依赖位置索引而不是序列本身的数值模式。常见现象是预测曲线和真实曲线形状接近，但存在固定相移，模型总在提前或滞后一两个时间步。解决办法是只保留TransformerEncoderLayer，不自带位置编码，改成在输入线性投影后拼一个可学习的位置参数，该参数随训练更新。如果预测窗口固定（比如恒为12步），直接创建一个shape为[1, 12, D]的参数矩阵加入输入。另一个备选方案是改用Time2Vec这类为时间序列设计的编码，把时间索引映射到多个频率的三角函数。如果相移现象不严重，通常可学习的position embedding就够用了，这也是实现成本最低的修正。

5. 进阶技巧：把信号解耦后让GNN和Transformer各干各的

模型跑通后，下一步值得做的改造是信号分解。实测中，把原始序列拆成趋势项、季节项和残差项分别建模，比让一个模型硬学混合信号效果更好。趋势项代表低频、缓慢变化的部分，空间相邻节点的趋势高度相关，这部分可以单独用GCN预测或者直接用线性外推；季节项包含周期性模式，比如日周期、周周期，这部分交给Transformer学注意力关系效果最好；残差项是除去趋势和季节后的随机扰动，这部分预测难度极高，不必追求精确拟合，只需给出方差估计。

具体做法是先用STL或移动平均分解出三个分量，然后修改模型输入，让GCN接收的趋势分量和Transformer接收的季节分量在进入模块之前拆分，最后把三个分量的预测结果相加得到最终输出。这样做的收益有两个：一是让Transformer的注意力集中在周期性模式上，极大减少过拟合；二是模型对数据漂移的鲁棒性增强，比如某个节点在周末出现异常突变，残差分量会吸收这个突变，不至于把整个预测曲线拉偏。我个人的习惯是，在模型调优后期花一周时间做这个拆分，效果通常比盲目堆模型层数和调参更可靠。如果特征维度里还有其他物理量，比如同时还记录了湿度、风速，也要在分解之后按通道分别建模，而不是混在一起，否则GCN的输入表达能力会被不同量纲的特征拖累。最后想说一句：把GNN和Transformer拼在一起不是终点，真正的工程价值在于把时序预测拆成空间相关和时间演化两个清晰的问题，然后分别用最合适的工具去解。希望帮到你。

本文还有配套的精品资源，点击获取