简介轨迹预测项目完整代码以zip压缩包形式提供面向需要开展序列数据预测研究与开发的学习者涵盖数据读取、模型构建、训练与评估等环节适合有一定Python基础的开发者参考。压缩包共11个文件含7个Python脚本、1个模型检查点、1个CSV数据集及配套数据分块文件整体仅723KB结构紧凑。脚本中实现了LSTM、GRU及逻辑回归三种模型并对同一轨迹数据集进行对比实验可直观看出传统机器学习与深度循环网络在预测效果上的差异另有专用数据处理模块、轨迹分析代码及测试脚本覆盖从数据加载到结果验证的完整链路。长短期记忆网络与门控循环单元分别独立成脚本逻辑回归则作为对照模型用户可直接运行这些脚本观察结果模型文件采用分块存储格式体现了深度学习项目常见的工程化处理方式对学习模型保存与加载亦有帮助。附带checkpoint保存了训练中间状态便于恢复训练或复现模型结果数据读取脚本则有助于理解数据清洗与组织方式可迁移至其他序列任务。目前已有230人学习适合作为入门进阶轨迹预测任务的参考实现与二次开发基础。1. 完整代码.zip里的轨迹预测到底能直接落地吗有一次我接手一个模拟项目X同事发来一个压缩包文件名就叫“完整代码.zip”说是轨迹预测的完整实现解压就能跑。结果装完依赖模型权重下载失败数据字段对不上最后把预测点画出来全在马路牙子外面。后来花了两天排查坐标系和窗口切分模型才真正动起来。这件事让我对这类代码包的印象一致核心模型不难跑难的是外围的数据约定和参数。轨迹预测解决的是这样一个问题给定目标过去几秒的位置序列预测未来一段时间的位置序列通常会输出多条候选轨迹和对应概率。它和单目标跟踪不一样跟踪是估计当前状态预测是往未来推。自动驾驶、仓储机器人避障、安防行为分析都会用到。下面会从这套代码包解压、训练、推理到评估的路径拆开讲新手能照着跑通熟手能避开那些不算复杂但极易翻车的边界问题。2. 轨迹预测在预测什么从运动模型到多模态学习模型2.1 传统运动模型为什么没被淘汰卡尔曼滤波与航迹外推轨迹预测并不是深度学习时代才有的问题。早年间雷达跟踪、摄像头的多目标跟踪里最常见的做法是给每个目标建立一个运动学模型比如恒速度模型、恒加速度模型、恒转弯率和恒速度模型也就是 CTRV然后用卡尔曼滤波估计目标的位置、速度、加速度。每来一帧新观测先做数据关联再用滤波器更新状态最后把滤波后的状态带入运动方程往外推几帧这个外推结果就是最早的轨迹预测。这套方案在什么情况下依然值得用我一般这样判断业务只关心未来 0.5 到 2 秒的碰撞预警且目标类别有限比如只有车辆或只有行人的低速园区那恒速度模型加卡尔曼滤波往往够用。它不需要标注数据不需要 GPU也不会在分布外数据上输出离谱结果。缺点是每个目标只能给出一条轨迹不会说“它可能左转也可能直行”遇到遮挡、突然变道、行人回头这类情况外推误差会快速变大。学习型轨迹预测真正想解决的是更长时、更复杂交互下的多模态预测问题。当你拿到“完整代码.zip”这类项目包时大概率里面放的不会是卡尔曼滤波而是一个端到端的深度学习模型。不要急着看模型结构先把自己的问题定义清楚预测时长是多少目标之间会不会互相影响场景里有没有地图、车道线这些先验这些问题直接决定模型选型和参数设置。2.2 学习型模型在做什么多模态轨迹的输入输出长什么样学习型轨迹预测把任务建模成序列到序列的映射。输入通常是一段历史观测序列每条样本的形状是[obs_len, feature_dim]有时还会拼接全局场景信息或目标之间的相对交互特征输出是未来多个时间步的坐标序列而且往往不止一条而是 K 条候选轨迹和对应概率这个 K 在配置里常见为 3 到 6。代码里常见的张量形状是这样训练时输入[batch, obs_len, feat_dim]模型内部经过编码器把历史序列编码成固定维度的特征向量解码器从这个特征向量出发生成[batch, num_modes, fut_len, 2]的输出。如果加了地图语义一般会在编码阶段用 CNN 把地图栅格变成向量再和轨迹特征拼接输入形状变成[batch, obs_len, feat_dim map_dim]。损失函数通常是组合式一个分类损失负责挑选最接近真实轨迹的候选模式一个回归损失负责缩小预测坐标和真实坐标的距离最常用的是 minADE、minFDE 或负对数似然损失。从训练角度看模型在学两件事一是目标自身的运动惯性二是目标与场景、目标与目标之间的交互约束。前一种靠历史序列就够后一种必须依赖交互特征或地图特征。所以同样的轨迹预测代码包放在空旷十字路口和密集人流里表现差很远。如果你拿到的完整代码包默认带栅格地图模块先确认你的场景有没有对应的地图数据没有就宁可在配置里关掉它只在纯序列特征上训练。2.3 坐标系归一化先写代码再谈训练几乎所有学习型轨迹预测代码包都会做坐标系归一化但注释往往写得非常隐晦。统一约定是每个训练样本不用全局世界坐标而是把当前时刻目标位置当作原点把目标朝向旋转到 x 轴正方向历史轨迹和未来轨迹全部转到这个局部坐标系里。这样做的原因有几点模型学的是相对运动而不是绝对位置否则目标出现在地图哪个位置都会影响输出不同场景绝对坐标范围差异很大不归一化会让网络初始训练非常不稳局部坐标系里可以做左右翻转增强左转右转样本能共享参数。这个归一化过程容易写错尤其是角度符号。一个实现长这样import numpy as np def to_local_frame(hist): # hist: [T, 2]全局坐标系下的 x, y cur hist[-1].copy() # 当前帧位置作为原点 rel hist - cur rel_prev rel[-2] - rel[-1] # 用最近两帧估计朝向 theta np.arctan2(rel_prev[1], rel_prev[0]) rot np.array([ [np.cos(theta), -np.sin(theta)], [np.sin(theta), np.cos(theta)] ]) local rel rot.T # 旋转到朝向为 x 轴的局部坐标 return local, cur, theta这段代码的关键点是cur取了hist[-1]也就是当前观测的最后一帧而不是第一帧。如果你用第一帧做原点训练时每个样本起点被拉到原点推理时又拿最后时刻做原点模型输出和真实轨迹之间会产生一个时间偏移最终表现是预测轨迹整体偏移。theta用最近两帧位移方向估计比单帧速度更稳定如果跟踪器已经输出航向角直接用航向角更合理。推理时要逆变换回全局坐标。写法是pred_local rot origin不是 rot.T。因为局部坐标由rel rot.T得到所以恢复就是右乘rot如果你在训练代码里用了相反方向的旋转那就两边保持一致。这类坐标系操作建议封装成独立函数并在项目里放一个单元测试用一条已知轨迹验证来回转换能还原。3. 解压完整代码包之后先改配置再跑通最小示例3.1 目录结构里先看这三个文件requirements.txt、config、data_loader拿到“完整代码.zip”解压后先不要急着打开模型文件。我一般按固定顺序看三样东西第一是requirements.txt确定依赖版本第二是configs目录下的 yaml 或 py 配置确认数据集路径和训练超参第三是data_loader目录下的读取逻辑明确它到底接受什么格式的数据。先在终端里把环境底数摸清cd 完整代码 # 解压后的根目录 ls -la python --version nvcc --version # 没有 nvcc 不代表不能用 CPU但要看 torch 是否编译了 CUDA如果requirements.txt存在直接pip install -r requirements.txt。如果不存在也不用慌轨迹预测代码包常见依赖就是numpy、torch、pyyaml、pandas手动装即可。最容易翻车的是 PyTorch 的 CUDA 版本和本机驱动不匹配装完以后执行下面这行确认 GPU 是否可用import torch print(torch.__version__, torch.cuda.is_available()) # 返回 False 时先用 CPU 跑通流程不要卡在环境上torch.cuda.is_available()输出False时别急着换驱动。先看配置里有没有默认调用 GPU 的算子如果没有特殊实现直接用 CPU 把最小流程跑通后面再调整 PyTorch 安装方式能省大量时间。配置里最值得先改的是数据路径和日志路径因为很多完整代码包默认写的是打包者本机的路径不改第一轮就报文件不存在。3.2 最小训练命令用一个 epoch 验证环境环境准备好之后目标不是立刻训练到收敛而是先用一个 epoch 跑通整条链路。常见做法是在train.py后加--epochs 1并且先只用一小部分数据。如果train.py没有这个参数就直接临时改配置文件里的 epochs 字段。python train.py --config configs/train.yaml --epochs 1 # 如果 train.py 没有 --epochs 参数就临时改配置文件里的 epochs 字段这条命令跑起来之后要观察几个点。日志里有没有稳定打印每一步的 loss如果 loss 是nan多半是数据里有缺失值或者坐标未经归一化GPU 显存有没有被占满如果只占 200MB可能是模型没有真正加载到 GPU最后看训练结束是否生成了 checkpoint 文件。至少这几个点满足再谈调参。如果训练脚本报ModuleNotFoundError大部分是因为项目路径没有加入sys.path。常见做法是在运行命令前加export PYTHONPATH.或者把train.py所在的根目录作为工程根目录打开而不是在上一级目录运行。这一步做对了后面省很多事。3.3 最小推理从 checkpoint 到预测轨迹数组做完一次最小训练后我会写一个只有 20 行的推理脚本把 checkpoint 加载进来跑一条真实样本。这个脚本的核心逻辑是读历史轨迹、局部坐标变换、模型前向、逆变换回全局坐标。下面这段代码展示了最重要的流程import torch import numpy as np def rot_mat(theta): return np.array([ [np.cos(theta), -np.sin(theta)], [np.sin(theta), np.cos(theta)] ]) def predict_track(model, hist, obs_len, fut_len): # hist: 全局坐标下的历史轨迹 [obs_len, 2] local, origin, theta to_local_frame(hist) # 复用归一化函数 inp torch.from_numpy(local).float().unsqueeze(0) # [1, obs_len, 2] with torch.no_grad(): pred model(inp) # 输出 [1, num_modes, fut_len, 2] pred_local pred[0].cpu().numpy() # 取第一个 batch restored [] for k in range(pred_local.shape[0]): x pred_local[k] rot_mat(theta) origin # 逆变换回全局坐标 restored.append(x) return np.stack(restored), origin这里obs_len必须和训练时的obs_len完全一致否则模型里线性层输入维度不匹配或者 Transformer 位置编码索引越界。另外多数代码包的 checkpoint 保存的是一个字典不一定直接是state_dict我通常先打印checkpoint.keys()再决定用ckpt[model_state]还是ckpt[state_dict]加载。不要迷信load_state_dict一次成功缺 key 时看报错再补加载。4. 数据格式与配置文件真正要改的是 data_config.yaml4.1 原始轨迹 CSV 怎么切历史窗口和未来窗口几乎每个完整代码包都配套一个内部数据集格式但自己手头的数据很难直接对齐。最常见的是 CSV列里有帧号、目标 ID、x、y甚至还有置信度。这时要做两件事按目标 ID 和帧号排序再按obs_len和pred_len切窗口。切窗口看起来简单实际很讲究。import pandas as pd import numpy as np df pd.read_csv(tracks.csv) df df.sort_values([track_id, frame]).reset_index(dropTrue) for tid, g in df.groupby(track_id): xy g[[x, y]].to_numpy() # 至少要有 obs_len pred_len 帧才构成一个样本 if len(xy) cfg.obs_len cfg.pred_len: continue hist xy[:cfg.obs_len] fut xy[cfg.obs_len:cfg.obs_len cfg.pred_len] # 这里可以做坐标系归一化然后把 hist/fut 存成 npy切窗口最容易犯的错误是每帧滑动取样本忽略了相邻样本高度重叠带来的重复样本过拟合问题。常见做法是每隔stride帧取一条样本stride设为 2 或 3。另外数据时间间隔是 0.1 秒obs_len8表示看过去 0.8 秒如果你的数据是 20Hz8 帧只有 0.4 秒模型看到的信息量完全不同所以这个参数一定要结合采集频率调。4.2 轨迹预测 4 个必调参数obs_len、pred_len、latent_dim、batch_size下面给一张参数表方便拿到任何一份完整代码包时按这个思路去修改。参数含义与单位常见初始值调参时重点看什么obs_len历史观测帧数810Hz 下约 0.8s太短无法估计朝向太长对遮挡和丢帧更敏感pred_len预测帧数1210Hz 下约 1.2spred 拉太长且没有地图输入误差会快速上升num_modes输出候选轨迹条数6太多会产生重复轨迹太少会漏掉变道分支latent_dim编码器特征维度64小数据集 64 一般够用128 以上需要更多训练数据否则过拟合明显batch_size每次迭代样本数64显存不够不要硬降改成梯度累积或关掉地图特征这里我最想强调pred_len。有的完整代码包默认把pred_len写成 30 帧对应 3 秒。如果没有车道线约束纯轨迹序列预测 3 秒本来就很难新手一看训练出来的 ADE 很高就认为模型不行其实只是预测任务本身超出了模型能力边界。我一般从pred_len12开始跑基线再逐步加长对比 ADE/FDE 变化而不是一步到位。配置文件里对应内容大概是这样的data: train_path: ./data/train.csv val_path: ./data/val.csv obs_len: 8 pred_len: 12 model: num_modes: 6 latent_dim: 64 train: batch_size: 64 learning_rate: 0.001 epochs: 50改配置时注意不要只改数字还要看train_path指向的文件是否存在以及 CSV 的列名是否和data_loader里写的一致。很多时候报错并不是参数不对而是列名对不上。4.3 训练日志怎么看loss 下降、mode collapse 与验证集异常训练日志要看的东西很多但一开始不必纠结训练集 loss 是否降到零重点看 loss 是怎么下降的。多数代码包会把总 loss 拆成回归 loss 和分类 loss 分别打印。如果回归 loss 一直在下降分类 loss 基本不动大概率是模型把所有概率都给了一条候选轨迹对应多模态塌缩。这时增大num_modes或调整分类 loss 的权重可能有用。另一个常见现象是训练 loss 在下降但验证集 ADE/FDE 上升或波动很大。这通常是训练集和验证集分布不一致比如训练集里目标大多直行验证集里弯道很多。折中做法是按目标出现的位置或时间段做交叉验证而不是随机打乱样本评估结果会更接近真实场景。还有一个诊断技巧每个 epoch 结束后把验证集上预测概率分布打出来看看熵是否过低。熵过低说明模型过分自信在轨迹预测里并不是好信号。# 假设 pred 是 [batch, num_modes, fut_len, 2]probs 是 [batch, num_modes] print(probs:, probs[0].detach().cpu().numpy().round(3))如果输出是[0.0, 0.0, 1.0, 0.0, 0.0, 0.0]模型对多条候选轨迹完全没有区分能力。此时先检查训练数据里每个样本的终点分布是否多样如果数据里 90% 都是直行模型只要押在直行上就能得到很低的损失这个坑不是调参能解决的而是数据本身偏置。需要对转弯样本做过采样。5. 轨迹预测避坑清单坐标、缺帧和评估口径最容易翻车5.1 预测结果整体偏移检查归一化中心点现象预测轨迹的形状看起来是对的但整条轨迹和目标真实位置之间固定偏移偏移方向随目标朝向变化。原因推理阶段做逆变换时使用的原点不是当前时刻而是历史轨迹的第一帧或者训练时用了第一帧做归一化推理时用了最后一帧。解决统一归一化和逆变换的原点在代码里写死约定。处理办法是把归一化逻辑抽成公共函数训练和推理都调用同一个函数。torch 里如果用torch.matmul旋转矩阵的维度顺序和 numpy 不同不要一边用np.arctan2(y, x)一边用atan2(x, y)角度定义不一致时输出看起来像是整个坐标系被旋转了 90 度。# 统一逆变换local_pred rot origin restored (pred_local rot_mat(theta)) origin5.2 ADE/FDE 高但可视化还行评估口径和输出头不对齐现象训练日志里验证集 FDE 是 2.3 米但可视化里预测结果几乎贴在真值上主观感觉误差不到 0.5 米。原因评估脚本计算 FDE 时取的帧号和可视化脚本取的帧号不是同一个或者评估用了最优模式的 minFDE可视化画的是最大概率模式。解决先统一谁和谁比。多模态预测评估标准是 minADE 和 minFDE也就是在 K 条预测里取最接近真实轨迹的那一条来计算。建议在代码包里加一个最小评估函数def evaluate_metrics(pred, gt): # pred: [num_modes, fut_len, 2], gt: [fut_len, 2] dist np.linalg.norm(pred[:, -1] - gt[-1], axis1) min_fde dist.min() idx dist.argmin() min_ade np.mean(np.linalg.norm(pred[idx] - gt, axis1)) return min_ade, min_fde把这段函数和分析循环放在一起避免不同的人写不同脚本导致指标对不上。另外预测轨迹的第一帧通常应当与当前帧重合评估时从第二帧开始算 ADE 更合理避免初始点偏差把结果带偏。5.3 轨迹缺帧直接崩插值还是丢弃现象训练到某个 epoch 时 loss 变成 NaN或者某个 batch 的输入长度不一致。原因原始数据里目标不是每一帧都被检测到某条轨迹从第 3 帧到第 5 帧之间缺了两帧data loader 没有处理直接拼接成序列。解决先按目标 ID 检查每段轨迹的帧序号是否连续缺帧少的用线性插值补上缺帧多的直接丢弃。# 简单线性插值适合缺少数帧的情况 def interpolate_track(xy, frame_ids): full_frames np.arange(frame_ids[0], frame_ids[-1] 1) return np.array([ np.interp(full_frames, frame_ids, xy[:, i]) for i in range(2) ]).T如果缺帧特别多插值会让模型学到一段平滑但虚假的运动不如直接丢弃。还有一种做法是在输入特征里加入真实时间戳 delta让模型自己学到帧间隔但大多数完整代码包不支持这种输入格式改起来成本高不建议新手一上来就做。5.4 GPU 显存不足与训练速度慢不是改 batch_size 那么简单现象训练脚本一跑就报CUDA out of memory于是把 batch_size 从 64 改成 16结果每个 epoch 变慢损失抖动变大。原因显存不够只是表象真正吃显存的是模型输入里的场景地图特征或反向传播时保存的中间变量过多。解决先看配置里有没有use_scene_map、use_lane这类开关先关掉再跑再把pred_len从 30 降到 12直接减少显存。如果还不够用梯度累积替代硬缩 batch。# 模拟梯度累积每 4 个 step 更新一次参数 optimizer.zero_grad() for i, (batch_x, batch_y) in enumerate(dataloader): loss model_step(batch_x, batch_y) / accum_steps loss.backward() if (i 1) % accum_steps 0: optimizer.step() optimizer.zero_grad()accum_steps4等效于 batch_size 放大 4 倍。注意 loss 要除以accum_steps否则梯度大小会随累积次数变化学习率怎么调都不收敛。如果训练数据本身不大优先关掉地图特征而不是加机器因为小数据集上强上大模型收益有限。6. 把轨迹预测接进自己的系统离线评估和一个小技巧6.1 用可视化脚本快速发现预测模式问题模型训练完最关键的一步不是存 checkpoint而是把预测结果和真值放到同一张图里看。轨迹预测可视化不能只看单条要看多模态历史轨迹用灰色真实未来用黑色虚线K 条预测按概率越大越不透明。画图的目的是快速发现偏移、旋转、mode collapse。import matplotlib.pyplot as plt # hist: [obs_len,2], preds: [K,fut_len,2], gt: [fut_len,2] plt.plot(hist[:, 0], hist[:, 1], o-, colorgray, labelhistory) plt.plot(gt[:, 0], gt[:, 1], k--, labelground truth) for k, pr in enumerate(preds): alpha 0.3 0.7 * prob[k] plt.plot(pr[:, 0], pr[:, 1], alphaalpha, labelfmode {k}) plt.legend() plt.savefig(vis.png)如果大部分预测轨迹缩成一条线说明模型没有学到多态性如果预测轨迹全部往一个方向偏优先查坐标系归一化而不是改网络结构。验证时随机抽 50 个样本拼成一张大图比逐个开图更有效率。6.2 一个真正能提分的技巧把预测结果喂回跟踪器轨迹预测在完整系统里往往不是终点。把预测的未来帧位置作为跟踪器的门限中心可以让跟踪器在当前帧检测丢失时用预测位置继续匹配减少 ID Switch。这个做法对多目标跟踪特别有效。实现时只需要在每次预测完成后把下一帧的预测均值连同协方差一起送给跟踪器而不是继续用匀速模型外推。我自己的习惯是在项目根目录放一个 README把坐标系约定、帧率、obs_len 和 pred_len 写死并在推理脚本里加断言。这个习惯是被血泪教训逼出来的有一次正是因为旋转矩阵方向写反从白天调到半夜。希望帮到你。本文还有配套的精品资源点击获取