PETRV2-BEV训练步骤详解：create_petr_nus_infos.py数据预处理全解析

PETRV2-BEV训练步骤详解：create_petr_nus_infos.py数据预处理全解析

你是否在训练PETRV2-BEV模型时，卡在了create_petr_nus_infos.py这一步？明明脚本跑通了，但后续训练却报错“找不到annotation文件”或“sample token mismatch”，评估指标始终为0？别急——这不是代码bug，而是对这个关键预处理脚本的逻辑、输入结构和输出格式缺乏系统理解。

本文不堆砌参数说明，不照搬文档，而是以真实训练动线为线索，带你逐行拆解create_petr_nus_infos.py到底做了什么、为什么必须这样执行、哪些细节稍有偏差就会导致整个训练流程崩盘。所有操作均基于Paddle3D官方实现，在星图AI算力平台上完整验证，每一步都附带可直接复用的命令与避坑提示。

1. 环境准备：不是“激活环境”就完事了

很多同学执行完conda activate paddle3d_env就以为万事大吉，结果运行脚本时报错ModuleNotFoundError: No module named 'paddle3d'。问题出在哪？——Paddle3D未正确安装或路径未纳入Python环境。

1.1 确认Paddle3D已编译安装

进入环境后，先验证核心依赖是否就位：

conda activate paddle3d_env python -c "import paddle; print('PaddlePaddle version:', paddle.__version__)" python -c "import paddle3d; print('Paddle3D imported successfully')"

若第二条报错，请勿跳过此步。Paddle3D需从源码编译安装（非pip install）：

cd /usr/local/Paddle3D python setup.py develop

关键提示：setup.py develop会将当前目录软链接至Python site-packages，确保后续tools/下脚本能正确导入paddle3d.datasets等模块。跳过此步，create_petr_nus_infos.py将无法加载NuScenes数据接口。

1.2 检查CUDA与Paddle版本兼容性

PETRV2-BEV对CUDA版本敏感。星图平台默认提供CUDA 11.2环境，需匹配PaddlePaddle 2.4+（推荐2.4.4）：

nvidia-smi # 确认GPU可见 python -c "import paddle; print(paddle.is_compiled_with_cuda())" # 必须返回True

若返回False，请检查conda list | grep paddle，确认安装的是paddlepaddle-gpu而非paddlepaddle（CPU版）。

2. 数据依赖下载：两个文件，三种风险

预训练权重与数据集看似简单下载，实则暗藏三类高频失败点：路径错误、解压异常、权限不足。

2.1 预训练权重：别让model.pdparams“躺平”在错误位置

官方命令：

wget -O /root/workspace/model.pdparams https://paddle3d.bj.bcebos.com/models/petr/petrv2_vovnet_gridmask_p4_800x320/model.pdparams

风险点：

• /root/workspace/目录可能不存在 → 执行前加mkdir -p /root/workspace
• wget被限速或中断 → 建议加--no-check-certificate -t 3重试
• 文件下载后权限为只读 → 训练时无法覆盖保存 → 执行chmod 644 /root/workspace/model.pdparams

安全写法：

mkdir -p /root/workspace wget --no-check-certificate -t 3 -O /root/workspace/model.pdparams \ https://paddle3d.bj.bcebos.com/models/petr/petrv2_vovnet_gridmask_p4_800x320/model.pdparams chmod 644 /root/workspace/model.pdparams

2.2 NuScenes v1.0-mini数据集：解压路径必须精准匹配

命令中tar -xf ... -C /root/workspace/nuscenes是关键。注意：

• nuscenes目录名必须小写，且不能多级嵌套（如/root/workspace/dataset/nuscenes会失败）
• 解压后目录结构应为：
  /root/workspace/nuscenes/v1.0-mini/
/root/workspace/nuscenes/v1.0-mini/samples/
/root/workspace/nuscenes/v1.0-mini/sweeps/
/root/workspace/nuscenes/v1.0-mini/maps/
/root/workspace/nuscenes/v1.0-mini/panoptic/

常见错误：解压到/root/workspace/nuscenes/v1.0-mini/内层，导致实际路径变成/root/workspace/nuscenes/v1.0-mini/v1.0-mini/...，脚本将找不到samples目录。

验证命令：

ls -l /root/workspace/nuscenes/v1.0-mini/ | head -5 # 应看到 samples/ sweeps/ maps/ 等子目录，而非空或报错

3. 核心解析：create_petr_nus_infos.py到底在做什么？

这是全文最硬核的部分。create_petr_nus_infos.py不是简单的“生成json”，而是构建PETRV2-BEV专用的数据索引体系。它解决三个根本问题：

1. 如何将NuScenes原始样本（sample + sample_data + ego_pose）映射为BEV视角下的多相机联合观测？
2. 如何为每个样本生成精确的3D标注（box）及其在6个相机图像上的2D投影？
3. 如何组织训练所需的“帧序列”（frame sequence），满足PETR的时序建模需求？

3.1 脚本执行逻辑全景图

python3 tools/create_petr_nus_infos.py \ --dataset_root /root/workspace/nuscenes/ \ --save_dir /root/workspace/nuscenes/ \ --mode mini_val

参数含义：

• --dataset_root：指向/root/workspace/nuscenes/（含v1.0-mini子目录）
• --save_dir：生成的.pkl文件将存于此目录（不是子目录！）
• --mode：可选mini_train、mini_val、train、val，决定处理哪个split

执行后，将在/root/workspace/nuscenes/下生成：

• petr_nuscenes_annotation_mini_val.pkl（核心标注索引）
• petr_nuscenes_infos_mini_val.pkl（样本元信息索引）

3.2 深度拆解：一个sample的完整处理链

以v1.0-mini/samples/中某个sample_token为例，脚本内部执行：

1. 加载sample→ 获取其timestamp、scene_token、next/prev指针
2. 遍历6个CAM_FRONT/BACK/LEFT/RIGHT→ 通过sample_data获取各相机ego_pose、calibrated_sensor、filename
3. 加载3D标注→ 从sample_annotation中提取所有instance_token对应的bbox（x,y,z,l,w,h,rot_y）
4. 坐标系转换→ 将3D box从global→ego→camera坐标系，计算其在图像上的2D投影（含遮挡判断）
5. 构建BEV锚点→ 根据grid_config（如range=[-51.2, 51.2, 0.8]）生成BEV网格，并将3D box中心映射到BEV格点
6. 序列组装→ 若--mode=mini_train，则按sample['next']链式组装4帧（当前帧+前3帧），供时序建模

关键洞察：petr_nuscenes_annotation_*.pkl本质是一个list[dict]，每个dict包含：

• 'token': sample_token
• 'cams': dict of 6 cameras, each with'data_path','lidar2img','cam_intrinsic'
• 'gt_boxes': (N, 9) array: x,y,z,l,w,h,rot_y,velocity_x,velocity_y
• 'gt_labels': (N,) class ids
• 'bev_pos': (N, 2) BEV grid coordinates for each box center

3.3 为什么必须删除旧annotation文件？

命令中明确写了：

rm /root/workspace/nuscenes/petr_nuscenes_annotation_* -f

原因在于：create_petr_nus_infos.py不会覆盖同名文件，而是追加写入。若之前运行失败留下残缺.pkl，后续训练会因EOFError或维度不匹配直接崩溃。

正确操作：每次修改--mode或数据路径后，务必手动清理旧文件。

4. 训练全流程实操：从预处理到可视化，一气呵成

完成预处理后，训练流程水到渠成。但以下四点仍需特别注意：

4.1 评估脚本：看清mAP背后的“有效样本”

首次运行评估：

python tools/evaluate.py \ --config configs/petr/petrv2_vovnet_gridmask_p4_800x320_nuscene.yml \ --model /root/workspace/model.pdparams \ --dataset_root /root/workspace/nuscenes/

输出中mAP: 0.2669看似不高，但请重点看：

• Eval time: 5.8s→ 表明成功加载了petr_nuscenes_annotation_mini_val.pkl（若报错，此处会卡住或报KeyError）
• Per-class results中car/truck/bus/pedestrian均有>0.3的AP → 证明标注转换正确
• trailer/construction_vehicle等类别AP=0 → 这是v1.0-mini数据集本身缺失这些类别的标注，属正常现象

判断预处理成功的黄金标准：非零类别AP > 0.2 且 Eval time < 10s

4.2 训练命令：batch_size=2是显存妥协，不是最优解

星图平台单卡V100（32G）下，batch_size=2是安全值。但请注意：

• --learning_rate 1e-4是针对batch_size=2微调后的值，若增大batch_size，需线性缩放LR（如batch_size=4→1e-4 * 2 = 2e-4）
• --save_interval 5表示每5个epoch保存一次，output/best_model/仅在--do_eval开启时，根据NDS指标自动更新

4.3 VisualDL可视化：端口转发必须精准对应

命令：

visualdl --logdir ./output/ --host 0.0.0.0 ssh -p 31264 -L 0.0.0.0:8888:localhost:8040 root@gpu-09rxs0pcu2.ssh.gpu.csdn.net

注意：

• VisualDL默认启动端口是8040（非8080），--host 0.0.0.0使其可被远程访问
• SSH端口转发中localhost:8040指远程主机（gpu-09rxs0pcu2）上VisualDL监听的端口，不是本地端口
• 浏览器访问http://localhost:8888，看到Loss下降、mAP上升曲线，即训练健康

4.4 模型导出与DEMO：路径一致性是生命线

导出命令：

python tools/export.py \ --config configs/petr/petrv2_vovnet_gridmask_p4_800x320_nuscene.yml \ --model output/best_model/model.pdparams \ --save_dir /root/workspace/nuscenes_release_model

DEMO运行：

python tools/demo.py /root/workspace/nuscenes/ /root/workspace/nuscenes_release_model nuscenes

关键校验点：

• --save_dir路径必须与demo.py第三个参数（nuscenes）匹配，否则demo.py会尝试加载/root/workspace/nuscenes_release_model/nuscenes/inference.yml，而该文件由export.py自动生成
• demo.py输出的可视化结果保存在./demo_output/，打开图片可直观验证BEV检测框是否合理覆盖车辆

5. 进阶实践：xtreme1数据集适配要点

xtreme1是NuScenes的扩展数据集，但其目录结构与标注格式与官方v1.0-mini不同，因此需专用脚本：

python3 tools/create_petr_nus_infos_from_xtreme1.py /root/workspace/xtreme1_nuscenes_data/

5.1 结构差异：xtreme1没有标准v1.0-mini目录树

xtreme1_nuscenes_data/目录下应包含：

• samples/,sweeps/,maps/（与NuScenes同名，但内容为xtreme1采集）
• xtreme1_annotations.json（自定义标注文件，非NuScenes的sample_annotation.json）

create_petr_nus_infos_from_xtreme1.py会：

• 读取xtreme1_annotations.json，解析为sample_token→box_list映射
• 复用NuScenes的get_sample_data逻辑加载图像，但跳过panoptic等xtreme1不支持的字段
• 生成petr_nuscenes_annotation_xtreme1.pkl，结构与mini版一致

5.2 评估结果为0？先检查这个

你看到mAP: 0.0000不要慌。运行：

python -c " import pickle with open('/root/workspace/xtreme1_nuscenes_data/petr_nuscenes_annotation_xtreme1.pkl', 'rb') as f: data = pickle.load(f) print('Total samples:', len(data)) print('First sample keys:', list(data[0].keys())) "

若len(data) == 0，说明脚本未找到有效标注；若报错FileNotFoundError，则路径错误。xtreme1脚本不接受--dataset_root参数，路径必须作为唯一位置参数传入。

6. 总结：掌握预处理，就是掌握PETRV2-BEV训练的命门

回顾整个流程，create_petr_nus_infos.py绝非“一键生成”的黑盒，而是连接原始数据与模型训练的精密桥梁。它的健壮性直接决定了：

• 训练能否启动（路径/文件存在性）
• 损失函数是否收敛（3D→2D投影精度）
• BEV检测框是否准确定位（BEV网格映射正确性）
• 时序建模是否有意义（帧序列组装逻辑）

你真正需要记住的只有三点：

1. 路径即契约：--dataset_root必须直指含v1.0-mini/的父目录，--save_dir必须与之同级
2. 清理即保障：每次运行前rm petr_nuscenes_annotation_*，避免残留文件污染
3. 验证即调试：用python -c "import pickle; print(len(pickle.load(open(...))))"快速确认pkl文件有效性

当你的petr_nuscenes_annotation_mini_val.pkl中样本数与v1.0-mini/中sample数量一致（约7000），且demo.py能稳定输出带BEV框的可视化结果时，你就已经站在了PETRV2-BEV工程落地的坚实地基之上。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。