简介T-GCN图卷积神经网络-交通流预测项目包面向智能交通、深度学习与数据挖掘领域的研究者提供利用图卷积网络建模城市道路拓扑、完成交通流预测的完整代码与数据。压缩包共129个文件约35.11MB包含Python脚本、CSV交通数据、JPG可视化图、TensorFlow检查点文件等py文件覆盖数据预处理、图构建与训练流程csv含道路速度实测记录checkpoint和h5为已训练好的模型权重另有md文档与配置文件可辅助理解模型结构与参数设置。目前已有1156人学习下载。对照源码可系统理解GCN处理非欧几里得数据的原理掌握道路网络到图结构的映射、多层卷积与时间窗机制的设计并可直接复现真实路网上的交通流预测实验为信号灯智能调控等应用提供参考也适合作为相关论文复现与算法优化的入门模板。1. 为什么交通流预测绕不开 T-GCN图卷积加循环网络的组合拳做交通流预测的人迟早会撞上 T-GCN。这个把图卷积神经网络GCN和门控循环单元GRU拼在一起的模型在 2020 年被提出后迅速成为各类交通数据集上的常驻基线也是论文里做对比实验时最先碰到的门槛。它最吸引人的地方在于把路网拓扑当成图把传感器流量当成图上的信号GCN 聚合一跳一跳邻居的空间影响GRU 再在时间轴上滚动更新空间和时间两个维度一次建模。这份 T-GCN图卷积神经网络-交通流预测zip 资源适合刚把 PyTorch 跑通、想从 LSTM 摸到图模型的开发者也适合需要快速拉一个可复现基线去写实验对比的人。提前泼一盆冷水它不是解压就能跑出漂亮数字的开箱即用包中间有几个非常隐蔽的坑稍后会逐个拆开。2. 拆开 T-GCN 的组合逻辑GCN 负责空间、GRU 负责时间的分工边界2.1 为什么非要用图结构路网拓扑是比数据更硬的先验交通流预测和普通时序预测最大的差别在于空间强相关。两个相隔几十米的路口上游拥堵会在十几分钟后传导到下游一个传感器读到的流量突然下降往往不是因为自身道路空闲而是下游拥堵回溢。LSTM 这类模型只能按时间顺序读单个节点的历史它天然没有“邻居”概念无论你给多少历史数据它也难以自发学会上下游关系。这里的本质是归纳偏置问题模型结构里没有图这个概念就只能靠海量数据硬猜空间关系代价是样本效率和泛化能力双双下降。T-GCN 的出发点就是把这个空间先验显式写进网络。路网天然是一张图节点是传感器或路口边是道路连接流量、速度、占有率这些信号就是定义在图上的特征。GCN 做的事情是用邻接矩阵控制每一层的信息流动节点的新特征等于自己和邻居特征的加权组合。这样一来模型不需要从零学习“哪两个传感器有联系”路网结构已经替它把约束给好了。这也是为什么在结构清晰的路网数据上T-GCN 通常比纯 LSTM 或纯全连接网络更容易收敛、效果也更稳。2.2 图卷积层到底在算什么邻接矩阵、拉普拉斯与切比雪夫近似要把 GCN 用到真实路网上第一步是定义邻接矩阵 A形状是 N×NN 是节点数。两个节点直接相连A 里对应位置为 1自环在数学上一般额外加上单位阵 I。直接拿 A 做卷积会出现一个问题不同节点的度不一样和度大的节点相连会把特征值放大或缩小层数一深数值就失控。所以通常要先做对称归一化得到拉普拉斯矩阵 LL I - D^{-1/2} A D^{-1/2}其中 D 是度矩阵D 对角线的第 i 个元素是 A 第 i 行的和。D^{-1/2} 的作用是对特征做一次尺度校正大度节点不再天然主导小度节点也不会被淹没。图卷积的通用形式是 H^{(l1)} σ(L H^{(l)} W^{(l)})H 是节点特征矩阵W 是可学习的权重矩阵σ 是激活函数。一层图卷积相当于让每个节点看到一跳邻居堆叠两层能看到两跳邻居这个“感受野”的含义和 CNN 里的感受野很像。实际代码里很多人直接用两层 GraphConv 堆叠不做完整的切比雪夫多项式展开因为对大多数路网数据集来说两跳已经覆盖了上下游干道的绝大部分影响。真正影响效果的不是阶数多高而是拉普拉斯矩阵有没有做正确归一化。这一条会在后面的避坑章节展开。2.3 前向传播的数据流T 个时间步各自过图卷积再按时间喂给 GRUT-GCN 的核心不是复杂网络深堆而是模块组合的顺序。输入数据形状通常是 (B, T, N, F)B 是批次大小T 是历史时间窗口长度N 是节点数F 是特征维度比如流量、平均速度、占有率。模型前向传播时先把每个时间步 t 单独切出来形状是 (B, N, F)经过共享权重的图卷积层变成 (B, N, H)H 是隐藏维度。这一步提取的是当前时刻的空间特征含义是“该时刻下每个节点以及它邻居的信号”。然后把这 T 个空间特征按时间顺序排列送入 GRU。GRU 的输入序列长度为 T每个时间步的输入维度是 H。GRU 的状态 h 在时间轴上不断更新最后取最后一个时间步的隐藏状态经过一层全连接输出 (B, N, 1) 的预测值。整个过程可以理解成图卷积在做空间特征提取GRU 在做时间信息累积职责清晰、互不重叠。所以一旦某个环节出错比如把 N 误当成 T 送进 GRU运行结果会非常奇怪而且不容易一眼查出来。2.4 损失函数与评价指标为什么先盯 RMSE再看 MAE 和 MAPE训练阶段一般用均方误差MSE或平均绝对误差MAE做损失。MSE 对大幅误差惩罚更重会把模型推向优先拟合拥堵时段的极端值MAE 对离群点更鲁棒但容易让模型牺牲对极端场景的敏感度。常见做法是训练用 MSE评估时三个指标一起看。RMSE 的单位和流量一致能直观反映预测和真实值的平均偏离MAPE 看起来更可解释但它的分子是绝对误差除以真实值一旦某个节点流量接近零MAPE 会瞬间被拉爆单个异常点就能污染整个均值。所以后面做实验对比时永远要同时保留 RMSE 和 MAE 两个口径别只看 MAPE 的漂亮数字。3. 把 zip 跑起来目录结构、数据预处理与最小训练脚本3.1 解压之后先看配置不要上来就运行 train解压这份 zip 之后别急着找 train.py 直接跑。先花两分钟把目录结构过一遍心里有数再动手。标准一点的 T-GCN 实现会分成这样几个模块data/ 放原始流量矩阵和邻接矩阵常见格式是 CSV 或 npzmodel/ 放 TGCN.py内容包括图卷积和循环网络的定义utils/ 放数据加载、归一化和切窗函数config.py 集中管理所有超参数train.py 和 evaluate.py 分别是训练和评估入口。我一般会先打开 config.py一个参数一个参数读过去。zip 里给出的参数不一定适合你手头的数据尤其是序列长度、学习率和归一化区间稍后都要改。你还需要确认邻接矩阵文件和你数据集的路网结构是否一致。节点顺序、边连接关系一旦错位整个图卷积都是在瞎算。3.2 数据预处理归一化统计量只能来自训练集数据预处理的通用套路是把所有节点的流量序列拼成一个大矩阵形状为 (时间步数, 节点数, 特征数)。对交通流来说不同节点的均值差异很大城市快速路和地面道路的量级可能差一个数量级所以第一步是归一化。z-score 归一化代码很简短但关键在统计量的计算范围mean train_data.mean(axis(0, 1, 2), keepdimsTrue) std train_data.std(axis(0, 1, 2), keepdimsTrue) x_train (train_data - mean) / (std 1e-6) x_val (val_data - mean) / (std 1e-6) x_test (test_data - mean) / (std 1e-6)这四行里最容易踩坑的就是 mean 和 std 怎么算。正确做法是只在训练集上计算 mean 和 std验证集和测试集直接复用。这里不能反过来更不能用全量数据一起算否则测试阶段就已经知道了未来的分布信息评估结果会失真。这个问题的隐蔽之处在于复用同一份统计量时 loss 仍然下降但泛化误差会被低估。加一个 1e-6 是为了防止某节点序列全为零时除零报错实测中这个细节能省掉很多莫名其妙的 nan。切窗函数是另一个容易搞混的地方。给定历史长度 T 和预测步长 horizon样本从第 i 个时间步开始取连续 T 步作为输入再取接下来 horizon 步作为标签def make_samples(data, T, horizon): X, Y [], [] for i in range(len(data) - T - horizon 1): X.append(data[i : i T]) Y.append(data[i T : i T horizon]) return np.stack(X), np.stack(Y)返回的 X 形状是 (样本数, T, N, F)Y 形状是 (样本数, horizon, N, F)。注意切窗时步长默认为 1相邻样本之间有大量重叠这没问题训练时靠 DataLoader 随机打乱来消除样本间相关性。如果你希望降低重叠度可以把采样步长设成 5 或 10代价是样本数变少。3.3 最小训练脚本先把 loss 曲线跑起来图卷积层和 T-GCN 主网络的定义比较固定下面是一份能直接跑通的最小实现import torch import torch.nn as nn class GraphConv(nn.Module): def __init__(self, in_dim, out_dim): super().__init__() self.w0 nn.Linear(in_dim, out_dim) # 0 阶切比雪夫项只看自身 self.w1 nn.Linear(in_dim, out_dim) # 1 阶项聚合一跳邻居 def forward(self, x, lap): # x: (B, N, F) # lap: (N, N) 对称归一化拉普拉斯 t0 x # 节点自身的特征 t1 torch.einsum(bnf,nm-bmf, x, lap) # 邻居加权和 return self.w0(t0) self.w1(t1) # 两阶相加 class TGCN(nn.Module): def __init__(self, in_dim, hidden_dim, out_dim): super().__init__() self.gconv GraphConv(in_dim, hidden_dim) self.gru nn.GRU(hidden_dim, hidden_dim, batch_firstTrue) self.fc nn.Linear(hidden_dim, out_dim) def forward(self, x_seq, lap): # x_seq: (B, T, N, F) B, T, N, F x_seq.shape gcn_seq torch.stack( [self.gconv(x_seq[:, t], lap) for t in range(T)], dim1 ) # (B, T, N, H) # 把 N 并入 batch 维让 GRU 只在时间维度上滚动 gcn_seq gcn_seq.permute(0, 2, 1, 3).reshape(B * N, T, -1) out, _ self.gru(gcn_seq) # (B*N, T, H) out out[:, -1].reshape(B, N, -1) return self.fc(out) # (B, N, out_dim)图卷积里把节点数 N 并入 batch 维是 T-GCN 最常见的实现方式。GRU 的批量维度变成了 B*N序列维度是 T这样所有节点共享同一组 GRU 参数但各自独立演化隐藏状态。如果你把 N 放在序列维度上等于让一个节点的历史去带动另一个节点的状态更新结果必然是乱的这个坑在第 5 章会详细说。训练循环本身不复杂关注的是数据形状对不对齐model TGCN(in_dimF, hidden_dim64, out_dim1) opt torch.optim.Adam(model.parameters(), lr0.005) criterion nn.MSELoss() for epoch in range(100): model.train() total_loss 0.0 for xb, yb in train_loader: B, T, N, F xb.shape pred model(xb, lap) # (B, N, 1) yb yb.reshape(B, N, -1) # 把标签也对齐成 (B, N, horizon) loss criterion(pred, yb) opt.zero_grad() loss.backward() opt.step() total_loss loss.item() * B常见做法是训练用 MSE评估时再算 RMSE、MAE 和 MAPE。学习率 0.005 搭配 Adam 是稳妥起点如果 loss 在头几个 epoch 震荡不降先把学习率降到 0.001而不是急着换优化器。3.4 判断训练是否健康的两个信号训练 loss 在前 20 个 epoch 应该快速下降这是第一个健康信号。第二个信号是验证集 RMSE 跟着下降两者同步才说明模型在学。如果训练 loss 下降但验证集完全不跌优先怀疑归一化泄漏或者模型过拟合。如果 loss 一开始就是 nan 或者忽高忽低不要调网络结构先检查拉普拉斯矩阵的数值范围再检查输入里有没有 nan 或 inf。4. 参数与评估口径邻接矩阵、序列长度、隐藏维度怎么定4.1 邻接矩阵的三种构建方式距离阈值、高斯核与数据驱动邻接矩阵的质量直接决定图卷积能学到什么。有路网坐标时最常见的是距离阈值法两个节点之间的实际距离小于某个阈值就算连通。def build_adjacency(dist, threshold): N dist.shape[0] A np.zeros((N, N)) A[dist threshold] 1 np.fill_diagonal(A, 1) # 补自环 D np.diag(A.sum(axis1)) # 对称归一化拉普拉斯 L I - D^{-1/2} A D^{-1/2} D_inv_sqrt np.linalg.inv(np.sqrt(D)) L np.eye(N) - D_inv_sqrt A D_inv_sqrt return L注意 np.fill_diagonal(A, 1) 这行不能省。没有自环的话图卷积每一层都会丢失节点自己的原始特征只保留邻居信息深层之后所有节点特征会趋于一致。高斯核是距离阈值法的平滑版本A_ij exp(-(dist_ij^2) / σ^2)它把硬阈值换成连续权重对噪声更鲁棒。还有一种数据驱动做法直接用历史流量的皮尔逊相关系数构造邻接矩阵适合没有路网坐标、只有传感器编号的情况。这种方式要小心伪相关两条不相邻的道路如果同时受红绿灯影响相关系数会很高但空间上完全不连通图上会多出不该有的边。4.2 关键超参数先定一组保守值再逐个放开超参数之间不是独立的调参时一次只动一个变量才有意义。下面这组是我在多个数据集上试下来比较稳的起点参数常见取值我的建议历史长度 T6 / 12 / 24先试 12看收益递减再往上加预测步长 horizon1 到 12调参用 1验证用 3 或 6隐藏维度 hidden_dim32 到 12864 起步显存够就上 128图卷积层数1 到 3大多数路网 2 层够用学习率0.01 到 0.0001Adam 0.005震荡就降批量大小16 到 6432 兼顾速度和稳定性训练轮数100 到 300配早停看验证集 RMSE历史长度 T 是最敏感的参数。T 太短模型看不到完整的早晚高峰起落预测会滞后T 太长GRU 要背很久以前的梯度训练变慢且容易过拟合。常见做法是从 12 开始如果加到 24 后验证集 RMSE 基本没变就退回去用 12省下的训练时间可以拿去调别的东西。4.3 评估口径RMSE、MAE、MAPE 各自暴露什么问题RMSE 对大误差敏感能反映模型在拥堵时段的实际表现MAE 更稳健适合观察整体水平MAPE 的可解释性最强但在流量趋近于零的深夜时段会失真。实际项目里我习惯按节点分群统计把节点按平均流量分成高、中、低三组分别看 RMSE。如果低流量组的误差居高不下往往不是模型问题而是归一化时这些节点被压缩得太厉害训练时没有获得足够的梯度权重。还有一点容易被忽略评估时要把数据还原到原始量纲再算指标。如果你直接对归一化后的预测值算 RMSE那个数字没有业务含义。做法很简单预测完成后乘回 std 再加 mean再和真实值做差。这一步很多教程都不提但它决定了你报告的 RMSE 能不能被人直接理解。5. 避坑T-GCN 复现中常见的五个坑5.1 邻接矩阵归一化不对loss 直接变成 nan现象训练刚开始几个 epoch loss 正常第 10 轮左右突然变成 nan或者换了随机种子后同样的代码有时收敛有时爆炸。原因邻接矩阵没有加自环或者用了不对称的行归一化 D^{-1}A。大度节点会把特征尺度放得很大图卷积层数一多数值就溢出。更隐蔽的是如果某个节点度为 0D 的对角线为 0np.linalg.inv 会直接报错或者产生 inf。解决用对称归一化拉普拉斯L I - D^{-1/2} A D^{-1/2}并且 np.fill_diagonal(A, 1) 补自环。计算逆矩阵前对 D 的对角线做 clip例如 np.clip(degree, 1e-6, None)从根上杜绝除零。5.2 归一化统计量泄漏到验证集和测试集现象训练 loss 和验证 RMSE 都很漂亮但模型换到新时段或者新区域后效果崩盘和论文报告的数字差一大截。原因预处理时把 train、val、test 拼在一起算 mean 和 std或者每次运行时重新 fit 了 Scaler。测试阶段因此已经知道整段数据的分布信息评估结果虚高。解决只对训练集计算 mean 和 std保存成文件验证集和测试集都加载同一份。我一般会把统计量存成 npz和模型权重放在一起避免推理时重新算。再进一步还可以记录每个节点的均值和方差而不是全数据集共享一组能保留节点间的差异性。5.3 图卷积输出被误当时间序列维度错位查了半天现象报错 RuntimeError 说 GRU 输入维度不匹配或者网络能跑但输出形状是 (B, N, T) 而不是 (B, N, 1)预测结果明显错位。原因把 N节点数当成 GRU 的序列维度。GRU 的 batch_firstTrue 时输入第二维是时间步 T第三维才是特征。如果你把 (B, N, F) 直接喂进去GRU 会在节点之间做循环等于强行让节点 A 的当前状态去预测节点 B 的下一时刻空间关系全乱。解决在前向入口加断言强制确认输入形状再往下走assert x_seq.dim() 4 and x_seq.shape[1] T, x_seq must be (B, T, N, F)然后按第 3 章的方式把 N 并入 batch 维再做 GRU。这个处理看似绕路实则是把空间和时间两个维度的职责彻底分开图卷积管空间、GRU 管时间互不污染。5.4 固定了随机种子指标却还在跳现象明明在代码开头设了 torch.manual_seed(0)跑三次验证集 RMSE 却差出千分之一甚至百分之一实验对比无法自洽。原因PyTorch 只是固定了它自己的随机数生成器numpy、DataLoader 的 worker 进程、cuDNN 的自动调优算法都有自己的随机源。T-GCN 的初始化涉及图卷积权重和 GRU 的多个参数矩阵任何一处没固定结果都会波动。解决训练入口统一做四件事torch.manual_seed、np.random.seed、DataLoader 设置 worker_init_fn并打开 torch.backends.cudnn.deterministic True。注意打开 deterministic 后训练速度会变慢一点这是为了换取可复现性值得。我一般还会把每次训练的 seed 写进日志文件名方便回溯。5.5 只看整体 MAE拥堵节点被平均掩盖现象整体 MAPE 不到 12%看起来效果不错但把预测值和真实值按时间序列画出来发现早晚高峰时段的误差特别大甚至预测值明显滞后于真实值一个时间步。原因MAPE 和 MAE 都是全局平均低流量时段的误差很小会把高峰时段的误差稀释掉。模型学到的主要是夜间平峰模式高峰段的突变没被充分惩罚。解决评估时按节点和时段分别统计。我会把一天按 6 点到 9 点、9 点到 16 点、16 点到 20 点分三段分别计算 RMSE再看是否有某一段误差异常。如果高峰段 RMSE 远高于平峰段检查一下训练样本里高峰样本的占比必要时对高峰时段做加权采样。6. 进阶验证滚动预测与节点级误差分析6.1 滚动多步预测一步预测准不代表多步准T-GCN 常见的实验设定是输入 T 个历史步输出下一步。但真实业务里要预测的是未来 30 分钟甚至 1 小时也就是连续多步。做法有两种直接多步输出或者滚动递归预测。直接多步要求模型输出维度是 horizon参数更多、训练更难收滚动预测则不断把模型自己的输出写回输入序列操作简单但误差会累积。def rolling_forecast(model, x_input, lap, horizon): # x_input: (B, T, N, F)已完成归一化 forecasts [] cur x_input for step in range(horizon): pred model(cur, lap) # (B, N, 1) forecasts.append(pred) new_step pred.unsqueeze(1) # (B, 1, N, 1) cur torch.cat([cur[:, 1:, :, :], new_step], dim1) return torch.cat(forecasts, dim-1) # (B, N, horizon)观察误差累积速度比整体 RMSE 数字更有价值如果第 3 步开始误差快速翻倍说明模型学到的其实是短期惯性而不是真正的交通演化规律如果误差是平缓线性增长说明模型对路网动态有真实理解。我一般在调参阶段就用第 12 步的滚动预测误差作为衡量标准而不是一步预测的 RMSE因为前者更接近业务落地时的真实表现。6.2 节点级误差热力图找出模型的盲区整体指标只能回答“平均误差多大”回答不了“哪里预测不好”。我习惯在测试集上把预测误差按节点和时间画成热力图横轴是时间纵轴是节点颜色代表预测误差。结果通常很明确靠近信号灯区域或匝道口的节点误差总是远高于平均。这不是 T-GCN 独有的问题但它提醒你评估一定要看得足够细否则换模型时不知道往哪个方向改进。有一次我是靠节点级误差图才发现邻接矩阵里漏了一条连接匝道和主干路的边导致那个节点完全学不到上游信息。修正邻接矩阵后该节点 RMSE 几乎立刻下降了三成整体指标却没怎么变。从那以后我每次复现 T-GCN 都会强制走一遍滚动预测加节点级误差图确认这两件事都正常才敢把实验结论写进对比报告。希望这个流程也能帮到你。本文还有配套的精品资源点击获取