简介：这份压缩包面向具备一定深度学习基础、希望复现轨迹预测实验的开发者与学习者，核心是用循环神经网络处理序列型轨迹数据并完成预测与模型对比。包内共11个文件，以7个Python脚本为主，另含模型检查点、CSV数据集及分片权重文件，压缩包约723KB，体积轻便，便于直接解压阅读和二次调试。已有230人学习，说明其在小规模轨迹预测练手项目中具备一定参考价值。代码覆盖数据读取与预处理、LSTM与GRU模型实现、逻辑回归对比实验、训练权重保存及轨迹分析等环节，读者可据此梳理从数据到建模、评估的完整流程，理解不同模型在轨迹预测任务上的差异，并在此基础上调整网络结构或替换数据集开展自己的实验。
1. 一个路口场景先摆出来：轨迹预测这套完整代码交付了什么
园区门口装了个摄像头，一个人走进画面一秒，接下来五秒他会不会突然横穿、会不会拐进车道？目标检测只能告诉你“现在他在哪”，答不了“下一步往哪”。这套轨迹预测完整代码干的就是这件事：输入 8 帧历史坐标，约 3.2 秒，输出未来 12 帧、4.8 秒的 6 条候选轨迹，每条带一个概率，取概率最高的那条就是模型给出的“最可能走向”。工程按软件插件的思路分层，模型、损失、数据集都能单独替换，解压后把数据路径改掉就能跑。适合做感知后处理、园区行为分析、时序预测课题的三类人；想找几个 notebook 片段拼一拼的，这包东西对你反而偏重。
2. 工程骨架与技术选型：这套轨迹预测代码为什么能当插件塞进现有流程
拿到一个 zip，我第一件事不是看 README，是看目录树。目录长什么样，基本决定了这项目是“能二次开发”还是“只能跑一次给人看”。这套代码属于前者：数据集、模型、损失、训练引擎、脚本五层切开，层与层之间只通过张量字典和配置文件耦合，你想把 GRU 编码器换成 Transformer，改一个文件、在注册表里换一行字符串就行，不用动 dataloader，也不用动 trainer。
2.1 目录结构：八个包各自负责什么
解压后根目录大致是这个样子，我给每个目录标了职责，后面几章的代码都能对得上位置：
trajpred/ ├── configs/ # yaml 配置，一份 base + 一份数据集专属 │ ├── base.yaml │ └── campus.yaml ├── data/ │ ├── raw/ # 原始标注（txt / csv 都行） │ └── processed/ # 转成 npy 的序列文件，训练直接读这里 ├── datasets/ │ ├── traj_dataset.py # 滑窗切样本 + 归一化 │ └── collate.py # 变长邻居补齐 ├── models/ │ ├── registry.py # 名字 -> 类的注册表，插件式替换的入口 │ ├── encoder.py # 历史轨迹编码 │ ├── social.py # 邻域交互 │ ├── decoder.py # 多模态轨迹头 │ └── traj_pred.py # 把上面三块拼成完整网络 ├── losses/ │ └── wta.py # winner-takes-all + 分类损失 ├── engine/ │ ├── trainer.py # 训练循环、混合精度、断点续训 │ └── evaluator.py # minADE / minFDE / MR ├── utils/ │ ├── config.py # yaml 加载 + 点号取值 │ ├── logger.py │ └── visualize.py # 画历史轨迹 + 预测扇形 └── scripts/ ├── train.py ├── eval.py └── demo.py # 单条轨迹推理，改两行就能接自己的数据这个布局里有一个容易被忽略的细节：data/raw和data/processed是分开的。原始标注格式千奇百怪，有的用像素坐标，有的用世界坐标，有的帧率是 2.5Hz，有的是 30Hz；但转成processed/*.npy之后，格式统一成“一条序列 = 一个目标的一段时间轨迹”，训练侧永远只认这一种。你换数据集，只需要重写一个转换脚本，模型和训练代码一行不动。这是我判断一份代码能不能长期用的第一条标准。
models/registry.py是第二个关键点。它就是一个字典，把字符串映射到类：
# models/registry.py from models.encoder import GRUEncoder, TransformerEncoder from models.social import SocialPool, NoSocial from models.decoder import MultimodalDecoder ENCODER = {"gru": GRUEncoder, "transformer": TransformerEncoder} SOCIAL = {"attn": SocialPool, "none": NoSocial} DECODER = {"multi": MultimodalDecoder} def build(cfg): # cfg 里写 encoder: gru，这里就实例化成 GRUEncoder enc = ENCODER[cfg.model.encoder](**cfg.model.encoder_args) soc = SOCIAL[cfg.model.social](**cfg.model.social_args) dec = DECODER[cfg.model.decoder](**cfg.model.decoder_args) return enc, soc, dec参数说明：cfg.model.encoder是一个字符串，cfg.model.encoder_args是这个类自己的构造参数（隐藏维度、层数等），分开写的好处是换模块时只改一个字段，参数跟着模块走，不会出现“换了编码器但 learning rate 还是按旧结构调的”这种糊涂账。逻辑上这就是最朴素的工厂模式，没什么高深，但它把“改模型”这件事从改代码降级成了改配置。
2.2 一条样本的生命周期：从原始坐标到模型输入张量
顺着一条数据走一遍，比看十页文档都清楚。原始文件里是一堆(frame_id, obj_id, x, y)的记录，转换脚本按obj_id分组、按frame_id排序，过滤掉连续出现帧数少于 20 的碎片轨迹（太短的切不出一个完整窗口），得到一条条ndarray，形状[T, 2]。这些序列打包成一个 list，用np.save(..., allow_pickle=True)存成train.npy。
Dataset 读进来之后做两件事：在时间轴上滑窗切样本，然后做坐标归一化。切出来的每条样本是[8, 2]的观测和[12, 2]的标签；归一化的结果是坐标全部变成“相对观测末帧的位移”，数值范围从几百像素压到个位数。到 collate 那一步，再补上邻居张量，最终喂给模型的是一个字典：
| 字段 | 形状 | 含义 |
|---|---|---|
| obs | [B, 8, 2] | 目标自身 8 帧归一化坐标 |
| nbrs | [B, N, 8, 2] | 最多 N 个邻居的归一化坐标 |
| nbr_mask | [B, N] | 该邻居是否真实存在 |
| pred | [B, 12, 2] | 真值，训练时用 |
| origin | [B, 2] | 归一化原点，可视化时还原用 |
origin这个字段看着多余，其实是后悔药。模型输出的是相对坐标，你直接拿去画图会全部堆在原点附近，看着像模型崩了，其实是忘了平移回去。我在第一版里就栽过一次，盯着可视化的图怀疑了半天人生。
2.3 技术栈与依赖：别一上来就上重装备
依赖清单写得很克制，核心就四样：PyTorch 做网络和自动求导，NumPy 做数据转换，PyYAML 读配置，Matplotlib 画图。没有分布式训练框架，没有实验管理平台，没有一堆花里胡哨的调度库。原因很实际：这个规模的模型（百万参数级别）单卡十几分钟一轮，加那些东西只会让环境装不起来。
# requirements.txt torch>=2.0 numpy>=1.23 pyyaml>=6.0 matplotlib>=3.6 tqdm>=4.65版本策略是“下限锁死、上限放开”。轨迹预测这类项目最怕的不是版本新，是环境装不上——CUDA 版本、显卡驱动、torch 版本三者对不上，能折腾掉一个下午。所以我一般会把torch装好之后再pip install -r requirements.txt，让 pip 自己判断要不要动 torch。
选 GRU 而不是 Transformer 做基线，也是同样的思路。8 帧观测的序列长度太短，自注意力在这个长度上体现不出优势，反而对学习率和 warmup 更敏感，调参成本高。等你把基线跑通、指标心里有数了，再在注册表里换成transformer做对比实验，那才是有意义的迭代，而不是一上来就搭一个自己都说不清为什么这么设计的网络。
3. 数据管线拆解：8 帧观测、12 帧预测的窗口怎么切
轨迹预测翻车的案例里，一大半不是模型的问题，是数据管线的问题。窗口切错一帧、归一化用了全局统计量、邻居掩码写成反的，这几种错误有个共同特点：训练 loss 照降，指标也不难看，但你把模型搬到真实场景就完全不是那么回事。这一章把 Dataset、归一化、collate 三段拆开写。
3.1 滑动窗口采样与索引构建
先看切窗逻辑。一条目标轨迹长度可能是 100 帧，我们要的是“8 帧看、12 帧猜”的样本对，所以用滑动窗口切，步长stride控制样本密度。步长取 1 是样本最多但相邻样本高度重复，取 5 能明显降冗余，一般在 2 到 5 之间试。
# datasets/traj_dataset.py import numpy as np import torch from torch.utils.data import Dataset OBS_LEN = 8 # 观测帧，2.5Hz 采样下约 3.2 秒 PRED_LEN = 12 # 预测帧，约 4.8 秒 class TrajDataset(Dataset): def __init__(self, seq_path, obs_len=OBS_LEN, pred_len=PRED_LEN, stride=3): self.seqs = np.load(seq_path, allow_pickle=True) # list[ndarray[T,2]] self.obs_len, self.pred_len, self.stride = obs_len, pred_len, stride self.index = self._build_index() def _build_index(self): idx = [] total = self.obs_len + self.pred_len for si, seq in enumerate(self.seqs): if len(seq) < total: continue # 太短的轨迹直接丢掉，切不出完整窗口 for start in range(0, len(seq) - total + 1, self.stride): idx.append((si, start)) return idx这段的实质是把“第几条轨迹、从第几帧开始”预先算成一个二元组列表存起来，__len__返回它的长度，__getitem__按索引去取。好处是采样逻辑只跑一次，epoch 之间不重复计算；坏处是内存里多存一份索引，几十万条样本也就几 MB，可以忽略。
参数上唯一要提醒的是stride和样本量的关系：一条 100 帧的轨迹，步长 1 切出 81 个样本，步长 5 切出 17 个。训练集本来就只有几万条窗口的时候，别把步长调太大，否则一轮 epoch 走完模型还没热身就结束了。
3.2 归一化：以观测末帧为原点，别让未来信息漏进来
归一化是整条管线里最容易出隐蔽 bug 的地方。常见错误写法是先算出整条序列（含未来帧）的均值方差，再统一减掉。这么做在训练集上指标会很漂亮，因为模型在归一化那一步就已经“看到”了未来的分布——典型的标签泄露，玄学得很，你查一周都查不出来。
正确的做法只用观测帧的信息：以观测窗口最后一帧为原点做平移。这个点的物理含义很清晰，“从现在的位置出发，未来往哪走”。
def normalize(obs, pred=None): # obs: [8, 2]，pred: [12, 2]。只用观测末帧做原点，未来帧不参与任何统计 origin = obs[-1].copy() obs_n = obs - origin if pred is None: return obs_n, origin return obs_n, pred - origin, origin提示：原点选
obs[-1]还是obs.mean(axis=0)有区别。取均值对噪声更鲁棒，但会让输出偏移，“原地不动”的预测会落在负偏移上。我做行人场景时用末帧，做车辆高速场景时用均值，前者更看重“当前位置”，后者更看重“平均趋势”。
还有一层处理是缺失帧。真实数据里，遮挡、检测漏框会导致某些帧没有坐标。我的处理是把缺失的帧坐标填 0（即原点），同时生成一个mask，[8]的 0/1 向量，在编码器里通过pack_padded_sequence或加权的方式排除掉。绝对不要把缺失帧丢掉后把剩下的帧拼起来——那样时间间隔就乱了，速度特征全错。
valid = ~np.isnan(obs).any(axis=1) # [8] bool obs = np.nan_to_num(obs, nan=0.0) # 缺失填原点 mask = valid.astype(np.float32) # 1 有效，0 缺失3.3 邻域构建与 collate：变长邻居怎么对齐成张量
单目标的历史轨迹没什么难度，难度在邻居。同一个路口，目标周围可能站着 0 个人，也可能站着 15 个人，每条样本的邻居数量都不一样，torch.stack直接报形状不匹配。标准做法是定一个上限N（我一般取 8 到 16），不足补零，同时用nbr_mask标出哪些位置是真实邻居。
# datasets/collate.py import torch def collate_fn(batch, max_nbr=8): obs = torch.stack([b["obs"] for b in batch]) # [B, 8, 2] pred = torch.stack([b["pred"] for b in batch]) # [B, 12, 2] origin = torch.stack([b["origin"] for b in batch]) # [B, 2] nbrs, masks = [], [] for b in batch: n = b["nbrs"][:max_nbr] # 截断超出的邻居 m = torch.ones(len(n), dtype=torch.bool) if len(n) < max_nbr: # 不足则补零 pad = torch.zeros(max_nbr - len(n), n.shape[-2], 2) n = torch.cat([n, pad], dim=0) m = torch.cat([m, torch.zeros(max_nbr - len(m), dtype=torch.bool)]) nbrs.append(n) masks.append(m) return { "obs": obs, "pred": pred, "origin": origin, "nbrs": torch.stack(nbrs), # [B, N, 8, 2] "nbr_mask": torch.stack(masks), # [B, N] }逻辑说明：邻居按距离由近到远排序后截断，保证选中的是最相关的那几个；补零的邻居在nbr_mask里是 False，后面注意力层会把它屏蔽掉。参数max_nbr不是越大越好——邻居数量翻倍，注意力的计算量和显存占用跟着涨，而实际场景里超过 8 个近距离邻居的情况很少，收益递减。
邻居的筛选规则也值得写清楚：只在观测窗口内与该目标平均距离小于阈值（行人 2.5 米，车辆 10 米量级）的目标才算邻居，且不算已经离开场景的。这个规则放在转换脚本里做，Dataset 只负责读，避免把“距离判定”这种事塞到训练循环里，以后想换阈值还得改模型代码。
4. 模型核心拆解：编码器、社交池化与多模态解码头
模型这部分的架构按“自己 → 邻居 → 融合 → 多条未来”四步走。整套网络参数量很小，单卡跑起来很轻，但每一块都有值得说的地方，尤其是掩码注意力和多模态损失这两个模块，写的时候稍微不注意就会出问题。
4.1 历史编码器：GRU 加 pack_padded_sequence 处理缺失帧
编码器的任务是把[8, 2]的历史轨迹压成一个定长向量。用 GRU 是因为轨迹本质上是连续的时序信号，8 步的长度上循环网络足够，而且训练稳定。关键是要处理有效帧的长度不一致——有的目标前两帧被遮挡，只有 6 帧有效。
import torch import torch.nn as nn class GRUEncoder(nn.Module): def __init__(self, in_dim=2, hidden=64, layers=1): super().__init__() self.gru = nn.GRU(in_dim, hidden, layers, batch_first=True) def forward(self, obs, mask): # obs: [B, 8, 2]，mask: [B, 8]，1 表示该帧有效 lengths = mask.sum(dim=1).clamp(min=1).long().cpu() packed = nn.utils.rnn.pack_padded_sequence( obs, lengths, batch_first=True, enforce_sorted=False ) _, h = self.gru(packed) return h[-1] # [B, hidden]参数说明：hidden是隐藏维度，64 是我常用的起点，128 在小数据集上容易过拟合；layers取 1 就够，2 层带来的收益在这个序列长度下不明显。lengths必须.cpu()，这是pack_padded_sequence的历史遗留要求，忘了会报一个“expected scalar type Long but found Long”之类的诡异错误。
enforce_sorted=False这一项很重要。默认要求 batch 内按长度降序排，否则报错；设成 False 后内部自己排，代价是你要理解它排完后h的顺序会还原回来，不会乱。我第一次用的时候老老实实在 dataloader 里按长度排序，结果每个 epoch 数据顺序全变了，损失曲线抖得跟心电图一样。
4.2 邻域交互：掩码注意力里那个空集合的坑
邻居融合用的是多头注意力：目标当 Query，邻居当 Key/Value，算出来的加权特征加回目标自己的表示。这部分代码不长，但有个坑必须处理——当一条样本一个邻居都没有时，key_padding_mask全是 True，PyTorch 的注意力会输出 NaN，然后整个 batch 的 loss 变成 nan。
class SocialPool(nn.Module): def __init__(self, hidden=64, heads=4): super().__init__() self.attn = nn.MultiheadAttention(hidden, heads, batch_first=True) self.norm = nn.LayerNorm(hidden) def forward(self, ego, nbrs, nbr_mask): # ego: [B, H]，nbrs: [B, N, H]，nbr_mask: [B, N] True 表示有邻居 has_nbr = nbr_mask.any(dim=1, keepdim=True) # [B, 1] safe_mask = nbr_mask.clone() safe_mask[~has_nbr.squeeze(1), 0] = True # 全空时保留一个占位位 out, _ = self.attn( ego.unsqueeze(1), nbrs, nbrs, key_padding_mask=~safe_mask ) # [B, 1, H] out = out.squeeze(1) * has_nbr.float() # 真没邻居就关掉交互项 return self.norm(ego + out)逻辑分三步：先判断这条样本有没有邻居；没有的话把第 0 个位置伪造成有效，骗过注意力层不产生 NaN；再乘上has_nbr，让这个伪造出来的交互结果归零，等价于“没有邻居就不融合”。这一手叫空集合保护，写图网络和集合聚合的时候都绕不开。
nbr_mask的语义一定要在项目里统一。我这里约定 True 表示有效，所以传进去要取反成key_padding_mask（PyTorch 约定 True 表示要屏蔽）。这种反向语义是血泪经验：一旦拼接层和模型层约定不一致，模型会悄悄地把所有邻居屏蔽掉，训练照样收敛，只是社交模块形同虚设，指标和纯单目标模型一模一样。
4.3 多模态解码：锚点、残差与概率头
未来轨迹不是唯一的，解码器要输出 M 条候选（M 一般取 6），每条 12 帧。直接让一个全连接层输出M × 12 × 2个数也能跑，但收敛慢而且各条模式容易挤在一起。我的做法是给每条模式一个可学习的锚点轨迹，网络只回归相对锚点的残差。
class MultimodalDecoder(nn.Module): def __init__(self, hidden=64, pred_len=12, num_modes=6): super().__init__() self.pred_len, self.num_modes = pred_len, num_modes self.fc = nn.Linear(hidden, 256) self.mode_head = nn.Linear(256, num_modes * pred_len * 2) self.cls_head = nn.Linear(256, num_modes) # 锚点初始化成扇形：直行 + 左右各两个方向 self.anchors = nn.Parameter(self._init_anchors(), requires_grad=True) def _init_anchors(self): base = torch.zeros(self.num_modes, self.pred_len, 2) # 每条模式给一个末帧偏移，形成扇形初值 offset = torch.linspace(-4.0, 4.0, self.num_modes) for i in range(self.num_modes): base[i, :, 1] = offset[i] * torch.linspace(0, 1, self.pred_len) return base def forward(self, feat): x = torch.relu(self.fc(feat)) res = self.mode_head(x).view(-1, self.num_modes, self.pred_len, 2) traj = self.anchors.unsqueeze(0) + res # 锚点 + 残差 logits = self.cls_head(x) # [B, M] 每条模式的打分 return traj, logits锚点的初始化比较讲究。如果全部初始化为 0，6 条模式会从同一个点出发，梯度也几乎一样，最后塌缩成一条，这就是“多模态塌缩”。初始化成扇形，每条模式一上来就指向不同方向，梯度自然分化。offset和linspace的幅度按场景尺度调——行人 4 米、车辆 20 米量级，用之前先看一眼你数据的坐标单位是像素还是米。
logits输出的是未归一化的分数，训练时配交叉熵，推理时 softmax 拿到概率。概率这个东西在工程里很有用：下游做规划的时候可以按概率加权，概率低的多条轨迹直接丢掉，减少误触发。
4.4 损失函数：winner-takes-all 配分类交叉熵
多模态训练的经典写法是 winner-takes-all：只让离真值最近的那条模式回传回归梯度，同时分类头学会预测哪条最可能对。这样每条模式各管一片区域，不会互相打架。
import torch.nn.functional as F def wta_loss(traj_pred, logits, traj_gt): # traj_pred: [B, M, 12, 2]，logits: [B, M]，traj_gt: [B, 12, 2] gt = traj_gt.unsqueeze(1) err = torch.norm(traj_pred - gt, dim=-1) # [B, M, 12] ade = err.mean(dim=-1) # [B, M] best = ade.argmin(dim=1, keepdim=True) # [B, 1] reg = ade.gather(1, best).mean() # 只有最优模式回传梯度 cls = F.cross_entropy(logits, best.squeeze(1)) return reg + 0.5 * cls逻辑说明：argmin本身不可导，但gather会保留下标对应那条模式的梯度，其余模式这一批拿不到回归梯度——它们会在下一批里因为成为最优而获得更新。这就是“赢者通吃”的含义。
0.5这个分类权重需要调。设得太小，分类头学不动，推理时概率全是均匀的；设得太大，模型倾向于只优化“选哪条”而忽略“这条准不准”，ADE 会变差。我一般在 0.2 到 1.0 之间扫三四个值，看验证集上 minADE 和分类准确率两个指标哪个先撑不住。
5. 训练与评估跑通：三条命令把 ADE 和 FDE 跑出来
前面把数据和模型拆完了，这一章落到执行：环境怎么装、配置怎么改、训练日志怎么看、指标怎么算。目标很明确——你拿着这个包，在不改任何代码的前提下，能独立跑出一个能解释的数字。
5.1 配置文件：所有可调参数只在一处
配置用 yaml，结构分四块：数据、模型、训练、评估。改参数只动这个文件，代码里不允许出现魔法数字。
# configs/base.yaml data: train_path: data/processed/train.npy val_path: data/processed/val.npy obs_len: 8 pred_len: 12 stride: 3 max_nbr: 8 model: encoder: gru encoder_args: {hidden: 64, layers: 1} social: attn social_args: {hidden: 64, heads: 4} decoder: multi decoder_args: {hidden: 64, pred_len: 12, num_modes: 6} train: epochs: 60 batch_size: 64 lr: 0.001 weight_decay: 0.0001 amp: true grad_clip: 1.0 seed: 42 ckpt_dir: runs/exp01 eval: split: val topk: 1 miss_threshold: 2.0几个参数值得单独说：amp: true开混合精度，显存能省三成左右，速度提升明显，代价是偶尔出现梯度溢出，配合grad_clip一般能压住；miss_threshold: 2.0是 MR 指标的判定阈值，预测终点离真值超过这个距离算“漏检”，单位跟你数据一致，用米和像素完全是两个量级，别搞混；seed一定要写死在配置里，不然复现实验会变成玄学。
5.2 训练入口：混合精度、梯度裁剪和断点续训
命令就一行，重点是背后的训练循环要有几个保护措施：
python -m scripts.train --config configs/base.yaml --exp exp01# engine/trainer.py 核心片段 scaler = torch.cuda.amp.GradScaler(enabled=cfg.train.amp) for epoch in range(start_epoch, cfg.train.epochs): model.train() for batch in loader: obs = batch["obs"].to(device) nbrs = batch["nbrs"].to(device) nbr_mask = batch["nbr_mask"].to(device) gt = batch["pred"].to(device) with torch.cuda.amp.autocast(enabled=cfg.train.amp): traj, logits = model(obs, nbrs, nbr_mask) loss = wta_loss(traj, logits, gt) scaler.scale(loss).backward() scaler.unscale_(opt) torch.nn.utils.clip_grad_norm_(model.parameters(), cfg.train.grad_clip) scaler.step(opt) scaler.update() opt.zero_grad(set_to_none=True)三处保护各自的含义：autocast让前向用 fp16 算，省显存；unscale_必须在clip_grad_norm_之前调用，否则裁的是放大过的梯度，等于没裁；zero_grad(set_to_none=True)比默认的清零更快，而且能区分“梯度为 0”和“没有梯度”两种情况，排查梯度消失时有用。
断点续训别省。每个 epoch 结束存一次last.pt，验证指标创新高存一次best.pt，文件里带上epoch、optimizer.state_dict()、scaler.state_dict()。训练到第 40 轮机器重启、进度全丢，这种事故只要遇到一次，以后你写什么训练脚本都会先把续训加上。
5.3 评估与可视化：minADE、minFDE、MR 怎么算
评估用独立脚本，加载best.pt，跑验证集或测试集：
python -m scripts.eval --config configs/base.yaml --ckpt runs/exp01/best.pt --split test指标实现不复杂，但口径要写对：
@torch.no_grad() def compute_metrics(pred, gt, topk=1, miss_thr=2.0): # pred: [B, M, T, 2]，gt: [B, T, 2] err = torch.norm(pred - gt.unsqueeze(1), dim=-1) # [B, M, T] ade_modes = err.mean(dim=-1) # [B, M] fde_modes = err[..., -1] # [B, M] order = ade_modes.argsort(dim=1)[:, :topk] # 按 ADE 选前 k 条 ade = ade_modes.gather(1, order).mean().item() fde = fde_modes.gather(1, order).mean().item() mr = (fde_modes.min(dim=1).values > miss_thr).float().mean().item() return {"minADE": ade, "minFDE": fde, "MR": mr}参数说明：topk=1是取 ADE 最小的那条算指标，topk=6则是取的 6 条里最好的，数字会好看不少但含义不同，论文里报的一般是 k=1；miss_thr是漏检阈值。选前 k 条必须按同一个指标排序，有人用 ADE 排序却报 FDE，指标会偏乐观，对比实验时容易得出错误结论。
可视化脚本scripts/demo.py读一条序列，画三样东西：历史轨迹（实线）、真值未来（虚线）、6 条预测（按概率上色的扇形）。一张图看三件事——方向对不对、发散范围合不合理、高概率那条是不是真最近。模型“看起来还行但实际很差”的情况，很多时候能从图上直接看出来，比盯数字快。
6. 常见问题排查：五个让我返工的坑
这一章全是踩出来的。每一条都是“训练能跑、指标也能出、但结论是错的”那种问题，比直接报错难查十倍。
6.1 指标卡在常数不动，loss 却一路下降
现象：训练 loss 从 1.2 降到 0.3，验证集 minADE 一直在 0.85 附近抖，几乎不动。
原因：归一化用了整条序列（含未来帧）的统计量，模型在输入侧就获得了未来分布的信息，训练集上学到的是一个“作弊解”。到验证集上这个信息不存在，模型等于瞎猜。
解决：把归一化改成只用观测帧，原点固定在obs[-1]，未来帧只做同样的平移不做统计。改完训练 loss 会略微上升，但验证指标会开始动。判断方法很简单：检查 transform 里有没有任何一行代码的输入是pred。
6.2 六条预测轨迹几乎重叠，多模态退化
现象：可视化里 6 条线挤成一条，概率也是均匀的 1/6，模型退化成单模态。
原因有两种。一是锚点全初始化为 0，所有模式起点相同，梯度也相同，谁也没比谁好，就这么一起走到收敛；二是分类损失权重设得太低，分类头没被训练，概率学不出来。
解决：锚点初始化成扇形（见 4.3 的_init_anchors），给每条模式一个初始方向差异；把分类权重从 0.1 提到 0.5 到 1.0 再试；训练前几个 epoch 观察ade_modes各列的值，如果 6 列数字几乎一样就说明没分化。这个指标比看 loss 直观。
6.3 训练中途 loss 突然变成 nan
现象：前 20 个 epoch 都正常，某个 batch 之后 loss 直接 nan，之后再也降不下来。
原因：某条样本没有邻居，key_padding_mask全 True，注意力 softmax 分母为 0，输出 nan 并沿梯度污染全部参数。这种样本在数据集里占比很少，可能几百个 batch 才碰上一次，所以表现为“随机时刻崩掉”。
解决：加空集合保护（4.2 里的has_nbr处理）；同时在训练循环里加一句if not torch.isfinite(loss): break提前退出并打印当前 batch 索引，方便定位。追加排查手段是把nbr_mask.sum(dim=1) == 0的样本数统计出来，如果占比超过 20%，说明邻居阈值设得太严。
6.4 换 batch size 后结果全变，实验没法复现
现象：把batch_size从 64 调到 128，指标差了 0.1，调回去也对不上原数字。
原因：种子只在scripts/train.py里设了一次torch.manual_seed，dataloader 的 worker、numpy、cuda 三处的随机源没管住；另外 batch size 变了，学习率没跟着调，本身就不是等价实验。
解决：写一个set_seed统一处理这几处：
import random import numpy as np import torch def set_seed(seed): random.seed(seed) np.random.seed(seed) torch.manual_seed(seed) torch.cuda.manual_seed_all(seed) torch.backends.cudnn.deterministic = True torch.backends.cudnn.benchmark = Falsedeterministic=True会牺牲一点速度换来可复现；benchmark=False是配合它用的。另外给 dataloader 加worker_init_fn，把每个 worker 的种子也固定住。至于 batch size 变化，学习率按线性缩放规则同步调整，否则对比的就不是同一件事。
6.5 推理速度比训练还慢，一帧要几十毫秒
现象：单条推理耗时异常，实时场景（10Hz 以上）完全带不动。
原因：demo.py里忘了加torch.no_grad()，每次推理都在建计算图；另外模型没调eval()，BatchNorm 和 Dropout 还在训练模式，单条样本过 BN 时统计量抖动，结果不稳定。
解决：推理脚本统一用@torch.no_grad()装饰或with torch.no_grad():，前面加model.eval()；能导出就导成静态图，再上一层推理加速。这两个改动一般能把耗时压下来一大截。这类问题不会报错，只会让你觉得“模型好慢”，属于典型的黑匣子式错觉。
7. 二次开发：换数据、换解码头、加物理约束的三个入口
代码跑通之后，真正花时间的是改成自己的场景。这套工程我推荐从三个入口动，改动面小、验证也快。
第一个入口是数据集适配。别去改TrajDataset，写一个新脚本把原始标注转成list[ndarray[T, 2]]再存成npy就行。转换时把三件事定死：坐标单位统一成米、采样帧率统一重采样到 2.5Hz、过滤掉连续帧数少于 20 的碎片轨迹。判断转换是否正确，最快的办法是跑demo.py，看图里的历史轨迹和实际画面能不能对上。
第二个入口是解码头。如果你只关心单条最优轨迹，把num_modes设成 1、去掉分类头，损失退化成纯 L2 或 SmoothL1，收敛更快；如果下游规划要多样本，保留 6 条并按概率排序输出。改MultimodalDecoder的时候记得同步改wta_loss，两边模式数对不上会静默错位，不会报错。
第三个入口是加约束。行人轨迹有速度上限、车辆轨迹有曲率限制，这些先验直接写成损失项最省事：
def smooth_loss(traj, weight=0.05): # 二阶差分约束加速度，抑制锯齿状预测 acc = traj[:, :, 2:] - 2 * traj[:, :, 1:-1] + traj[:, :, :-2] return weight * acc.pow(2).mean()加进去之后总损失变成wta_loss(...) + smooth_loss(...)，weight从 0.01 起调。加太大会让轨迹过度平滑、转弯处滞后，指标反而变差。改完任何一处，验证流程固定走三步：先跑 5 个 epoch 看 loss 是否正常下降，再跑全量看验证集 minADE，最后跑 demo 看图上有没有明显反物理的路径。三步走完才敢说改动是有效的。
我早期改这类项目，总想着一步到位把结构换掉，结果往往是数据管线里的一个约定被新模型打破了，训练照跑、指标照出，等到接真机才发现全歪。从那以后我每次换模型或加损失项，都强制先只改一个变量、跑完那三步验证，再合并下一处改动。希望帮到你。
本文还有配套的精品资源，点击获取
