简介：这是一份轨迹预测项目的完整源码包，面向希望学习长短期记忆网络、门控循环单元等循环神经网络在序列预测中应用的开发者与学生。项目不仅实现了两种主流序列模型，还加入逻辑回归作为对比实验，配套数据读取与预处理脚本，并留存训练好的模型检查点与索引文件，可直接体验从数据加载到推理的完整流程。压缩包内共十一个文件，以七个Python脚本为核心，涵盖模型定义、数据读取和对比实验，另含csv数据集、检查点及模型分块文件，其中csv提供轨迹样本，检查点保存训练权重，整体压缩后大小仅723KB。已有二百三十人学习，特别适合希望快速掌握轨迹预测建模思路的初学者，也适合作为深度学习序列预测的入门参考实现。
1. “完整代码.zip轨迹预测”到底解决什么问题
收到一个叫「完整代码.zip」的压缩包，第一反应通常是既安心又心虚：安心的是别人已经帮你把框架搭好了，心虚的是你不确定它到你手里还跑不跑得起来。轨迹预测这件事本身很直接——给出一段历史位置，比如过去 3 秒的 GPS 坐标或雷达点迹，预测接下来几秒它会在哪。自动驾驶要预判行人走向，仓库小车要提前规划路径，无人机要绕开障碍，核心都是同一个问题。这篇笔记就围绕「完整代码.zip轨迹预测」这个包展开：它一般装了什么、怎么把它跑起来、参数怎么调、最常翻车的位置在哪。
2. 轨迹预测代码包里的模型选型：先看数据再看结构
2.1 轨迹预测本质上是序列回归，不是曲线拟合
把轨迹预测拆开看，它要做的是从一段历史坐标序列 Xₜ₋L₊₁…Xₜ 映射到未来坐标 Xₜ₊₁…Xₜ₊ₕ，输入输出都是坐标点序列，建模的核心单位是时间和位置。很多人第一次上手时容易把它当成多项式拟合来做，用历史点去拟合一条曲线再外推。这个思路在匀速直线段确实有效，但遇到转弯、变速、停顿，外推结果几乎一定是平滑且错误的，因为曲线拟合假设了运动模式是不变的，而实际轨迹会切换运动状态。
代码包里最常见的建模方式是递归网络，尤其是 LSTM。原因是轨迹天然是时序数据，LSTM 能在隐状态里保留长时记忆，适合学习“上一段怎么走、接下来大概怎么走”这种条件分布。它不如 Transformer 或者图神经网络表达能力那么强，但好处是数据量要求低。用一段几千步的模拟轨迹就能把整个训练流程跑通，这在调试阶段太重要了。我一般会先看代码包里的数据规模再判断该学谁：几千样本用 LSTM，上百万样本才值得上 Transformer，否则大概率过拟合然后开始怀疑人生。
2.2 完整代码.zip 通常长什么样，先按结构判断“完整”程度
一个能被称得上“完整代码.zip”的轨迹预测包，至少要包含五类东西：入口说明、依赖清单、数据读取、训练脚本、评估脚本。我的习惯是拿到压缩包后先不急着装环境，而是先列目录，看它的组织方式是不是可复现的工程结构，而不是一堆命名混乱的脚本。
# 先看整体结构，再决定从哪切入 unzip 完整代码.zip -d trajectory_prediction cd trajectory_prediction tree -L 2常见做法是下面这种布局：
trajectory_prediction/ ├── README.md ├── requirements.txt ├── config.yaml ├── data/ │ ├── raw_tracks.csv │ └── split.py ├── models/ │ └── lstm_net.py ├── train.py ├── evaluate.py └── utils/ ├── normalize.py └── metrics.py检查压缩包时我会重点关注几个标志。首先看 README 里是否写了入口命令，没写入口说明的代码包，就算代码本身再完整，到别人手里也很难跑起来。其次看 requirements.txt 是否存在，这决定了你是否需要在环境上花两个小时排错。最后看有没有评估脚本，一个只训练不评估的包，你无法判断模型是好是坏。如果这三样都齐全，这个 zip 基本算是合格工程。
2.3 选型理由：运动学模型做基线，LSTM 做主力，Transformer 再做增强
判断一个轨迹预测模型好不好，标准不是单一的误差大小，而是在不同运动模式下的稳定性。代码包里如果只给你一种模型，你要能判断它适合什么场景。我习惯对比三类方法：
| 模型类型 | 数据需求 | 建模能力 | 适合场景 | 主要劣势 |
|---|---|---|---|---|
| 运动学模型（恒速/恒加速） | 几十个点即可 | 只能外推匀速直线运动 | 简单车辆轨迹、快速出基线 | 转弯处明显不准 |
| LSTM | 千级样本 | 能学转弯、变速、停顿等状态切换 | 行人、车辆、机器人轨迹 | 长序列上有隐状态衰减 |
| Transformer | 十万级样本起步 | 长程依赖强，可建模多目标交互 | 高速密集场景、大规模数据集 | 调参困难，CPU 上训练极慢 |
我用 LSTM 当主力还有一个现实原因的考量：训练资源。轨迹预测项目往往需要反复调参，一次训练几分钟和一次训练几个小时决定了你能迭代多少轮。LSTM 在这类规模的数据上收敛快，而且几乎不会出现训练过程不稳定的状况。运动学模型虽然笨，但它是一个非常公平的参照物，如果 LSTM 跑出来还不如恒速外推的误差低，那多半是数据预处理出了问题，而不是模型能力不行。
2.4 输入特征与输出目标：不要把原始坐标直接丢给模型
轨迹预测最容易忽视的一点是特征设计。坐标本身只是一个“位置”，它对模型来说缺少运动语义。我一般会在代码包里找一个预处理函数，看它是否做了差分、速度或航向角的提取。加入一阶差分特征例如速度分量，往往能让 LSTM 的收敛速度明显变快，尤其在目标做匀速运动的场景下。
还要注意输入输出的坐标空间。如果数据是经纬度，直接把经纬度当平面坐标喂给模型会在高纬度地区产生畸变，训练出来的模型在低纬度能跑，换一个城市就完蛋。稳妥的做法是转换成局部平面坐标（以某点为原点的东北天坐标），再进模型。这一条在代码包落地时踩的人不在少数，看起来是同一个模型，换个地区测试精度掉一半，原因多半就在这里。
3. 从解压到出预测结果：手把手跑通轨迹预测流水线
3.1 先用模拟轨迹验证代码链路，别急着上真实数据
拿到完整代码.zip 之后，我建议先把包里的数据替换成一段自己生成的模拟轨迹，跑通训练和评估全流程。这样做的好处是：模拟数据的真值完全干净，如果模型连模拟数据都拟合不好，那一定是代码链路有 bug，而不是数据噪声的问题。等链路验证完毕，再换真实数据，排查范围就小很多。
# data_prep.py # 生成一段带噪声的匀速转弯轨迹，模拟车辆或行人的典型运动 import numpy as np def simulate_trajectory(n_steps=500, dt=0.1, noise_scale=0.05): """生成二维轨迹样本 Args: n_steps: 轨迹点数 dt: 采样间隔，单位秒 noise_scale: 位置噪声标准差，单位米 Returns: (n_steps, 2) 的坐标数组，单位为米 """ t = np.arange(n_steps) * dt radius = 10.0 # 转弯半径 angular_speed = 0.3 # 角速度 # 匀速圆周运动叠加一个缓慢直线漂移，模拟运动模式的切换 x = radius * np.cos(angular_speed * t) + 0.02 * t y = radius * np.sin(angular_speed * t) + 0.01 * t xy = np.stack([x, y], axis=-1) rng = np.random.default_rng(0) xy += rng.normal(0.0, noise_scale, size=xy.shape) return xy这里的关键参数是noise_scale。它模拟传感器误差，设得太小模型会过度拟合干净轨迹，换到真实数据就崩；设得太大模型会认为运动无规律。我一般把噪声设为位移尺度的大约 2% 到 5%。dt决定了采样频率，也间接决定了lookback窗口对应多长的时间跨度。
3.2 滑窗切片与归一化：把轨迹变成监督学习的样本
整段轨迹不能直接塞给模型，要切成“输入窗口 + 预测窗口”的样本对。这是轨迹预测代码里最机械但最容易出错的环节。窗口长度、滑窗步长、训练集和验证集的边界，三个参数决定了你的样本量和数据相关性。
# data_prep.py 续 def make_sequences(xy, lookback=10, horizon=5, stride=1): """把整段轨迹切成监督学习样本 Args: lookback: 用过去多少个点做输入 horizon: 预测未来多少个点 stride: 滑窗步长，步长越大样本相关性越小 Returns: X: (n_samples, lookback, 2) Y: (n_samples, horizon, 2) """ X, Y = [], [] for i in range(0, len(xy) - lookback - horizon + 1, stride): X.append(xy[i : i + lookback]) Y.append(xy[i + lookback : i + lookback + horizon]) return np.array(X), np.array(Y) def normalize(xy): """min-max 归一化到 [-1, 1] 注意：这个函数只应在训练集上计算统计量， 验证集要用训练集的 lo/scale 来做变换，否则会造成数据泄漏。 """ lo = xy.min(axis=0) hi = xy.max(axis=0) scale = hi - lo scale[scale < 1e-6] = 1.0 return (xy - lo) / scale * 2.0 - 1.0, lo, scalelookback设 10，horizon设 5，在 10Hz 采样下对应 1 秒历史和 0.5 秒预测。如果做行人轨迹，这个配置偏短，建议lookback拉到 20 以上。stride设 1 会让相邻样本高度重叠，模型容易过拟合；设太大则样本量不足。我做实验时会先用stride=1跑通流程，再调大步长看验证集指标是不是反而提升。
归一化是轨迹预测的隐形地雷。很多人把训练集和验证集拼在一起算最小值和最大值，这会导致验证集的信息提前泄漏到训练过程里，验证指标虚高，上线后原形毕露。正确做法是先按轨迹文件切分，再在训练集上计算统计量，验证集只做变换，不做统计计算。
3.3 定义 LSTM 模型：输入输出形状先确认再动手
模型层数、隐藏维度、dropout 这三个参数是 LSTM 的核心旋钮，但它们不是独立调的。隐藏维度决定了网络的表达能力，在轨迹预测这种低维输入（通常是 2 维或 4 维特征）场景里，64 通常够用，128 并不会带来质变，只会让训练变慢。层数 2 层是性价比最高的选择，1 层表达力不够，3 层以上在小数据集上非常容易过拟合。
# model.py import torch import torch.nn as nn class TrajLSTM(nn.Module): """轨迹预测 LSTM 输入: (batch, lookback, n_features) 输出: (batch, horizon, n_features) """ def __init__(self, n_features=2, hidden_size=64, num_layers=2, horizon=5, dropout=0.2): super().__init__() self.encoder = nn.LSTM( input_size=n_features, hidden_size=hidden_size, num_layers=num_layers, batch_first=True, dropout=dropout if num_layers > 1 else 0.0, ) self.head = nn.Sequential( nn.Linear(hidden_size, 64), nn.SiLU(), nn.Linear(64, horizon * n_features), ) self.horizon = horizon self.n_features = n_features def forward(self, x): # x: (B, lookback, n_features) out, _ = self.encoder(x) # out: (B, lookback, hidden_size) last = out[:, -1, :] # 取最后一个时间步的隐状态 flat = self.head(last) # (B, horizon * n_features) return flat.view(-1, self.horizon, self.n_features)注意out[:, -1, :]取的是 LSTM 最后一层的最后一个时间步输出，这意味着网络只用历史窗口最后时刻的隐状态来做预测。这是 LSTM 做轨迹预测最常见的两种结构之一。另一种是用所有时间步的输出做注意力加权，但小规模数据上后者优势不明显。view把展平的特征还原成(horizon, n_features)，这里必须确保 Linear 的输出维度计算正确，如果horizon改了，输出维度要同步改，否则训练时字符串维度对不上。
3.4 训练循环：损失函数、优化器、梯度裁剪缺一不可
训练一个小型 LSTM 用 MSE 还是 SmoothL1，在轨迹预测里有讲究。MSE 对离群点惩罚太重，会让模型倾向于给出保守预测来避免大误差；SmoothL1 在误差较大时是线性惩罚，在误差小时则退化为 L2，对轨迹这种带噪声的数据更稳，我通常默认用它。优化器选 AdamW 并给一个小的 weight decay 即可。梯度裁剪很多人忽略，但 LSTM 在长序列上很容易梯度爆炸，剪到 5.0 是一个比较保守且有效的默认值。
# train.py import numpy as np import torch import torch.nn as nn from torch.utils.data import TensorDataset, DataLoader def train_loop(model, train_X, train_Y, val_X, val_Y, epochs=50, batch_size=64, lr=1e-3, device="cpu"): model = model.to(device) train_ds = TensorDataset(torch.from_numpy(train_X).float(), torch.from_numpy(train_Y).float()) train_ld = DataLoader(train_ds, batch_size=batch_size, shuffle=True) optimizer = torch.optim.AdamW(model.parameters(), lr=lr, weight_decay=1e-4) scheduler = torch.optim.lr_scheduler.CosineAnnealingLR(optimizer, T_max=epochs) loss_fn = nn.SmoothL1Loss() best_val = float("inf") for epoch in range(epochs): model.train() train_loss = 0.0 for xb, yb in train_ld: xb, yb = xb.to(device), yb.to(device) optimizer.zero_grad() pred = model(xb) loss = loss_fn(pred, yb) loss.backward() nn.utils.clip_grad_norm_(model.parameters(), max_norm=5.0) optimizer.step() train_loss += loss.item() * xb.size(0) scheduler.step() model.eval() val_tensor_x = torch.from_numpy(val_X).float().to(device) val_tensor_y = torch.from_numpy(val_Y).float().to(device) with torch.no_grad(): val_pred = model(val_tensor_x) val_loss = loss_fn(val_pred, val_tensor_y).item() if val_loss < best_val: best_val = val_loss torch.save(model.state_dict(), "best_model.pt") print(f"epoch {epoch+1}/{epochs} train_loss={train_loss:.5f} val_loss={val_loss:.5f}")训练时我习惯把训练集和验证集的形状打印出来确认一次，很多维度问题在数据准备阶段就埋下了，等到模型跑起来才发现view报错。best_model.pt保存的是验证集 loss 最低的权重，而不是最后一个 epoch 的权重，防止验证集过拟合后保存了一个更差的模型。训练过程如果 val_loss 持续上升而 train_loss 下降，说明过拟合发生了，此时应优先减小 hidden_size 或增加 weight decay，而不是盲目加数据。
3.5 评估与可视化：误差指标和轨迹图一起看
评估轨迹预测模型，只看一个综合 loss 全是盲人摸象。业界通常用两个指标：平均位移误差 ADE，衡量所有预测点的平均偏差；最终位移误差 FDE，只看预测终点和真实终点的距离。这两个指标要分开报告，因为一个模型可能在中间点都准、终点飘了，另一个模型可能整体偏一点但终点很准，它们的应用场景完全不同。
# evaluate.py import numpy as np def compute_metrics(pred, true): """计算 ADE 和 FDE Args: pred, true: (n_samples, horizon, 2)，单位与原始坐标一致 Returns: ade: 平均位移误差，单位与坐标一致 fde: 最终位移误差，单位与坐标一致 """ # 还原到原始坐标后再算，这一步必须在逆归一化之后 diff = pred - true step_err = np.linalg.norm(diff, axis=-1) # (n_samples, horizon) ade = float(step_err.mean()) fde = float(step_err[:, -1].mean()) return ade, fde跑完评估后，我会在可视化上花同样多的时间。误差数字有可能骗人，但轨迹图不会。画图时把历史轨迹、预测轨迹、真实轨迹画在同一张图上，再看一次运动趋势合不合理。如果预测轨迹方向错了，哪怕 ADE 不高，这个模型在实际部署里也不可用，因为它可能把目标预测到了反方向。
# visualize.py import matplotlib.pyplot as plt def plot_prediction(history, pred, true, save_path="traj_demo.png"): """history: (lookback, 2) pred/true: (horizon, 2)""" plt.figure(figsize=(5, 5)) plt.plot(history[:, 0], history[:, 1], "o-", label="history") plt.plot(true[:, 0], true[:, 1], "s-", label="ground truth") plt.plot(pred[:, 0], pred[:, 1], "x--", label="prediction") plt.legend() plt.gca().set_aspect("equal") plt.grid(True, alpha=0.3) plt.savefig(save_path, dpi=150)set_aspect("equal")很重要，否则横纵轴比例不一致时，轨迹看起来的弯曲程度和真实运动不符，容易误判。画图的最主要用途不是展示，而是诊断：预测轨迹的拐弯是否平滑、是否滞后于真实轨迹、是否出现了明显的方向突变，这些信息在数值指标里都看不出来。
4. 轨迹预测代码包落地避坑：五条高频踩坑与排查记录
4.1 解压后第一步就报错：路径中的中文与空格
现象：压缩包解压到桌面或带中文名的文件夹里，运行入口脚本时马上报文件找不到或者 python 模块导入失败。
原因：压缩包内的脚本里写死了相对路径，而解压路径包含了中文和空格。某些脚本在 Linux 下用os.path处理路径没有问题，但如果是 Windows 上下载的包再拷贝到 Linux 上，路径编码不一致就会触发 UnicodeDecodeError。还有一个容易被忽略的坑：压缩软件解压时改变了内层目录的层级结构，让from models.lstm_net import TrajLSTM这种导入直接断裂。
解决：把压缩包解压到纯英文路径下，例如/home/user/work/trajectory_prediction，先执行pwd && ls -la确认当前目录与 README 描述一致。再检查models、utils等目录下是否有__init__.py文件，没有的话补充空文件。这两步做完，百分之八十的“入口报错”都能解决。
4.2 依赖安装后 import torch 报错或版本不匹配
现象：按照 requirements.txt 安装完毕，运行训练脚本时 CUDA 不可用，或者模型参数加载时报权重维度不匹配、算子不存在。
原因：requirements.txt 里通常只锁了包名，没有锁与 CUDA 的对应关系。常见的坑是代码包用 PyTorch 2.x 加 CUDA 11.8 开发，而你的环境默认装的是 CPU 版 PyTorch，cuDNN 算子缺失导致模型初始化失败。另一种情况是 numpy 版本过新，旧代码用了np.float这类已被移除的别名，直接 AttributeError。
解决：先跑python -c "import torch; print(torch.__version__, torch.cuda.is_available())"确认 torch 版本和 CUDA 可用性。如果不需要 GPU，优先用 CPU 版本把链路跑通，不要一上来就折腾 CUDA。如果代码里导入了np.float之类的新版 numpy 已经删除的东西，全局搜索替换成np.float64即可，这类兼容性修复通常十分钟就能完成。
4.3 训练 loss 震荡不下降，归一化范围和特征尺度不一致
现象：训练了几十个 epoch，loss 一直在 0.05 到 0.2 之间剧烈震荡，看不到明显的下降趋势，调低学习率也只是让震荡变缓而不是收敛。
原因：最常见的是输入特征的量纲不一致。x、y 坐标如果单位是米，范围在几十到几百之间，而速度特征如果是米每秒，范围可能只有个位数，两个特征直接拼在一起，模型会天然偏向于拟合数值大的特征。还有一种情况是归一化用了全场统计量，但训练数据和验证数据分布不同，导致模型在不同 batch 上梯度方向相互冲突。
解决：先把特征拆开观察，确认 x、y、vx、vy 分别的取值区间。所有特征统一归一化到 [-1, 1]，保存统计量并在验证、测试时使用同一套统计量。如果归一化后 loss 仍然震荡，把初始化方式从默认改成均匀分布初始化并降低学习率到 3e-4 重新训练，通常是有效的。
4.4 预测轨迹滞后真实轨迹，看起来像把上一步复制过去
现象：可视化时预测轨迹的方向基本正确，但是明显滞后，预测曲线的形状接近“把历史窗口最后一个位置平移到未来”，拐弯被磨平了。
原因：模型学到了最简单的策略——复制最近位置作为未来预测，因为在这种策略下 loss 已经能降到很低的水平。造成这种现象的直接原因是lookback窗口太短，模型看的历史信息不足以推断运动趋势；另一个常见原因是损失函数只惩罚平均误差，没有对运动趋势施加速度约束，模型觉得“保持原地不动”比“正确外推”更安全。
解决：把lookback从 10 拉到 20 或 30，给模型更长的时间上下文，让它能区分匀速、加速和转弯。特征里加上一阶差分和航向角，强迫模型利用速度信息。还有一个笨但有效的办法：在训练时同时计算预测轨迹的一阶差分与真实轨迹的一阶差分的误差，把它作为辅助损失加进总损失，模型就不敢“原地踏步”了。
4.5 验证集指标虚高，上线后精度骤降，问题几乎都出在预处理
现象：代码包里自带验证集跑出来的 ADE 很漂亮，但换成自己准备的测试数据后误差翻倍，怎么调参都找不回原来的效果。
原因：统计泄漏几乎一定是罪魁祸首。之前的处理方式是先拼接所有数据再归一化，验证集的“未来信息”统计进了训练集归一化的尺度里。另一个原因是滑窗切片时没有按轨迹文件边界切分，同一条轨迹的前半段进了训练集、后半段进了验证集，模型等于在验证集上“见过”了一半。
解决：严格按轨迹文件划分数据集，划分之后再计算归一化统计量。检查预处理代码，确保验证集只经过transform而没有参与fit。判断泄漏有个很简单的自查办法：把模型换成“恒定速度外推”这个基线，如果 LSTM 的验证集指标比基线好很多而测试集上优势消失，几乎可以断定预处理泄漏了。
5. 怎么确认模型真的会预测：分误差段的可视化验证与调参顺序
当 LSTM 跑通之后，千万别急着宣布大功告成。我发现一个特别有效的验证技巧是：按预测时长拆误差，画一条误差曲线。把 horizon 里的第 1 步误差、第 2 步误差、第 5 步误差分别算出来，看误差是怎么增长。正常情况下误差随预测步长单调上升；如果误差在第 1 步就很高，说明模型还没学会“起步”；如果误差到第 4 步突然暴涨，说明模型在长时预测端不稳定，可能需要在训练时增加 horizon 内后期时段的权重。这两种问题的修法完全不同，只看一个平均 ADE 根本分不出来。
另一个要养成的习惯是先跑一个足够笨的基线。用最后一个历史位置作为未来所有预测值，或者用最后两个位置的连线做匀速外推，把基线指标记下来，再跑 LSTM。如果 LSTM 连这种最幼稚的基线都打不过，问题基本不在模型而在数据。我用这个办法排查过很多次，至少一半情况是预处理泄漏，剩下的则是窗口切分导致训练样本之间存在大量重叠，模型死记硬背了训练样本的形态。
调参顺序上我的建议是：先固定 horizon，然后依次调 lookback、hidden_size、学习率、损失函数，最后才考虑层数。一次只动一个变量，记录下每个配置的 ADE 和 FDE，不要连 CPU 的num_workers和 GPU 的batch_size一起变动，否则你永远说不清是哪一步让指标变好的。每次调参的教训我后来都习惯就地写在实验记录文件里，省得三天后问自己“这个参数为什么改回来”。可视化验证再加误差分段统计，这两个习惯能帮你避开绝大多数轨迹预测项目的坑。希望帮到你。
本文还有配套的精品资源，点击获取
