PaddleX 3D 多模态融合检测（3D BEV Detection）模块使用教程：从 BEVFusion 快速集成到二次开发

人工智能大模型低代码计算机视觉深度学习NLP模型推理服务RAG【免费下载链接】PaddleXAll-in-One Development Tool based on PaddlePaddle项目地址https://gitcode.com/paddlepaddle/PaddleX点击查看免费下载导读3D 多模态融合检测是自动驾驶与机器人感知系统的核心技术之一它负责在激光雷达点云与多视角相机图像中定位目标的三维空间位置并输出带有类别与置信度的 3D 边界框。本文以飞桨 PaddlePaddle 生态的全流程开发工具 PaddleX 中的3d_bev_detection模块为主线完整讲解 BEVFusion 模型的快速集成、预测结果解析、3D 可视化以及基于命令行完成数据校验、模型训练、模型评估、模型推理与产线集成的整套二次开发流程。读完本文你将能够使用几行 Python 代码调用 3D 检测模型完成推理也能在 nuscenes 数据集上独立完成 BEVFusion 从数据准备到部署的完整开发闭环。一、模块概述3D 多模态融合检测在感知系统中的作用3D 多模态融合检测模块是计算机视觉和自动驾驶领域的关键组成部分负责在图像或点云中定位并标记出包含特定目标区域的 3D 坐标和检测框信息。该模块的性能直接影响到整个视觉或自动驾驶感知系统的准确性和效率。模块通常会输出目标区域的 3D 边界框Bounding Boxes这些 3D 边界框将作为输入传递给目标识别等后续模块进行进一步处理。与传统的 2D 目标检测不同3D 检测不仅需要给出目标的平面位置还需要同时回归目标的深度中心点 z 坐标、三维尺寸与航向角并在动态场景下估计目标速度因此其输出是长度固定的 9 维向量详见本文预测结果解析一节。在 PaddleX 中该能力由3d_bev_detection模块承载涉及仓库中的以下几部分实现模块配置paddlex/configs/modules/3d_bev_detection/BEVFusion.yaml产线配置paddlex/configs/pipelines/3d_bev_detection.yaml推理实现paddlex/inference/models/m_3d_bev_detection/predictor.py结果与可视化paddlex/inference/models/m_3d_bev_detection/result.py、paddlex/inference/models/m_3d_bev_detection/visualizer_3d.py训练/评估/导出paddlex/modules/m_3d_bev_detection/trainer.py、paddlex/modules/m_3d_bev_detection/evaluator.py、paddlex/modules/m_3d_bev_detection/exportor.py。二、支持模型列表与测试环境说明PaddleX 的 3D 多模态融合检测模块当前支持的模型为BEVFusion官方提供的推理模型与训练模型可通过模型下载链接获取模型模型下载链接mAP(%)NDS介绍BEVFusion推理模型 / 训练模型53.960.9BEVFusion 是一种在 BEV鸟瞰图视角下的多模态融合模型采用两个分支处理不同模态的数据得到 lidar 和 camera 在 BEV 视角下的特征。camera 分支采用 LSSLift, Splat, and Scatter这种自底向上的方式来显式地生成图像 BEV 特征lidar 分支采用经典的点云检测网络最后对两种模态的 BEV 特征进行对齐和融合应用于检测 head 或分割 head从仓库源码看模块的模型注册表位于 paddlex/modules/m_3d_bev_detection/model_list.py当前MODELS列表仅包含BEVFusion与文档中的支持模型列表一致训练器 trainer.py 与导出器 exportor.py 均以该列表作为实体集合。性能测试环境说明测试数据集上述精度基于 nuscenes 验证集指标为 mAP(0.5:0.95) 与 NDS 60.9精度类型为 FP32硬件配置GPUNVIDIA Tesla T4CPUIntel Xeon Gold 6271C 2.60GHz其他环境Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6。推理模式说明模式GPU 配置CPU 配置加速技术组合常规模式FP32 精度 / 无 TRT 加速FP32 精度 / 8 线程PaddleInference高性能模式选择先验精度类型和加速策略的最优组合FP32 精度 / 8 线程选择先验最优后端Paddle/OpenVINO/TRT 等需要说明的是3D BEVFusion 的推理依赖 GPU 平台的自定义算子。从 predictor.py 的_build()方法可以看到当 Paddle 编译支持 CUDA 且非 ROCm 平台时会导入paddlex/ops/iou3d_nms中的nms_gpu与paddlex/ops/voxelize中的hard_voxelize其实现位于 paddlex/ops/iou3d_nms/、paddlex/ops/voxel/否则会输出3D BEVFusion custom ops only support GPU platform!的错误提示。因此该模块的推理与训练均应以 GPU 环境为前提。三、快速集成几行代码完成 3D 检测推理❗ 在快速集成前请先安装 PaddleX 的 wheel 包详细请参考 PaddleX 本地安装教程。完成 wheel 包安装后几行代码即可完成 3D 多模态融合检测模块的推理可以任意切换该模块下的模型也可以将模块中的模型推理集成到自己的项目中。运行以下代码前请先下载示例输入到本地。from paddlex import create_pipeline pipeline create_pipeline(pipeline3d_bev_detection) output pipeline.predict(nuscenes_demo_infer.tar) for res in output: res.print() ## 打印预测的结构化输出 res.save_to_json(./output/) ## 保存结果到json文件 res.visualize(save_path./output/, showTrue) ## 3d结果可视化如果运行环境有图形界面设置showTrue否则设置为False这段示例与仓库中的 API 示例 api_examples/pipelines/test_3d_bev_detection.py 保持一致。在产线侧create_pipeline(pipeline3d_bev_detection)会读取 paddlex/configs/pipelines/3d_bev_detection.yaml该配置默认将3DBEVDetection子模块的model_name指定为BEVFusion、batch_size为 1其推理入口在 paddlex/inference/pipelines/m_3d_bev_detection/pipeline.py 的BEVDet3DPipeline中直接透传给 3D 检测模型完成预测。注3D 检测结果可视化需要先安装 open3d 包安装命令如下pip install open3d如果运行环境没有图形界面则无法可视化但不影响结果的保存可以在支持图形界面的环境下运行脚本对保存的结果进行可视化python paddlex/inference/models/3d_bev_detection/visualizer_3d.py --save_path./output/关于可视化机制的补充说明从 result.py 可以看到BEV3DDetResult.visualize()会读取输入点云路径input_path将原始点云 reshape 后仅保留前 4 维x, y, z, intensity并组合boxes_3d、scores_3d、labels_3d得到检测结果字典当save_path非空时会把results.npy与points.npy保存到指定目录当showTrue时再调用Visualizer3D.draw_results(points, result, score_threshold)其中默认置信度阈值score_threshold 0.25低于该阈值的框不会被绘制。3.1 预测结果示例与字段含义运行上述代码后得到的结果为{ res: { input_path: samples/LIDAR_TOP/n015-2018-10-08-15-36-500800__LIDAR_TOP__1538984253447765.pcd.bin, sample_id: b4ff30109dd14c89b24789dc5713cf8c, input_img_paths: [ samples/CAM_FRONT_LEFT/n015-2018-10-08-15-36-500800__CAM_FRONT_LEFT__1538984253404844.jpg, samples/CAM_FRONT/n015-2018-10-08-15-36-500800__CAM_FRONT__1538984253412460.jpg, samples/CAM_FRONT_RIGHT/n015-2018-10-08-15-36-500800__CAM_FRONT_RIGHT__1538984253420339.jpg, samples/CAM_BACK_RIGHT/n015-2018-10-08-15-36-500800__CAM_BACK_RIGHT__1538984253427893.jpg, samples/CAM_BACK/n015-2018-10-08-15-36-500800__CAM_BACK__1538984253437525.jpg, samples/CAM_BACK_LEFT/n015-2018-10-08-15-36-500800__CAM_BACK_LEFT__1538984253447423.jpg ], boxes_3d: [ [14.5425386428833, 22.142045974731445, -1.2903141975402832, 1.8441576957702637, 4.433370113372803, 1.7367216348648071, 6.367165565490723, 0.0036598597653210163, -0.013568558730185032] ], labels_3d: [0], scores_3d: [0.9920279383659363] } }运行结果参数含义如下input_path表示输入待预测样本的输入点云数据路径sample_id表示输入待预测样本的唯一标识符input_img_paths表示输入待预测样本的输入图像数据路径nuscenes 中每帧包含 6 个相机视角boxes_3d表示该 3D 样本的所有预测框信息每个预测框为一个长度为 9 的列表各元素分别表示0中心点 x 坐标1中心点 y 坐标2中心点 z 坐标3检测框宽度4检测框长度5检测框高度6旋转角度航向角 yaw7坐标系 x 方向速度8坐标系 y 方向速度labels_3d表示该 3D 样本的所有预测框对应的预测类别scores_3d表示该 3D 样本的所有预测框对应的置信度。从源码角度印证上述字段的组装发生在 predictor.py 的_format_output()方法中推理网络依次输出bboxes、scores、labels同时从img_metas中取出input_lidar_path、input_img_paths与sample_id最终汇总为包含input_path / input_img_paths / sample_id / boxes_3d / labels_3d / scores_3d六个键的结果字典。3.2 create_model 参数说明create_model用于实例化 3D 检测模型此处以BEVFusion为例具体说明如下参数参数说明参数类型可选项默认值model_name模型名称str无BEVFusionmodel_dir模型存储路径str无无device模型推理设备str支持指定 GPU 具体卡号如gpu:0其他硬件具体卡号如npu:0CPU 如cpugpu:0use_hpip是否启用高性能推理插件bool无Falsehpi_config高性能推理配置dict|None无None其中model_name必须指定。指定model_name后默认使用 PaddleX 内置的模型参数在此基础上指定model_dir时则使用用户自定义的模型。3.3 predict() 方法参数说明调用 3D 检测模型的predict()方法进行推理预测其参数有input和batch_size具体说明如下参数参数说明参数类型可选项默认值input待预测数据支持多种输入类型str/list文件路径如 3D 标注文件的本地路径/root/data/anno_file.pkl列表列表元素需为上述类型数据如[/root/data/anno_file1.pkl, /root/data/anno_file2.pkl]无batch_size批大小int任意整数1补充说明3D 检测的输入实际为 nuscenes 风格的标注文件pickle/.pkl或包含标注信息的.tar归档其中记录了每帧点云路径、6 路相机图像路径与内外参等元数据。推理时由Det3DBatchSamplerpaddlex/inference/common/batch_sampler/与ReadNuscenesData读取器paddlex/inference/common/reader/负责解析并将数据暂存于临时目录predictor.py中通过tempfile.mkdtemp()创建推理结束后自动清理。3.4 预测结果处理方法与属性说明对预测结果进行处理每个样本的预测结果均为对应的 Result 对象且支持打印、保存为json文件等操作方法方法说明参数参数类型参数说明默认值print()打印结果到终端format_jsonbool是否对输出内容使用JSON缩进格式化Trueindentint指定缩进级别以美化输出的JSON数据使其更具可读性仅当format_json为True时有效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。设置为True时所有非ASCII字符将被转义False则保留原始字符仅当format_json为True时有效Falsesave_to_json()将结果保存为 json 格式的文件save_pathstr保存的文件路径当为目录时保存文件命名与输入文件类型命名一致无indentint指定缩进级别以美化输出的JSON数据使其更具可读性仅当format_json为True时有效4ensure_asciibool控制是否将非ASCII字符转义为Unicode。设置为True时所有非ASCII字符将被转义False则保留原始字符仅当format_json为True时有效False此外也支持通过属性获取带结果的可视化图像和预测结果属性属性说明json获取预测的json格式的结果关于更多 PaddleX 单模型推理 API 的使用方法可以参考 PaddleX 单模型 Python 脚本使用说明。四、二次开发从数据准备到模型部署如果你追求更高精度的现有模型可以使用 PaddleX 的二次开发能力开发更好的 3D 检测模型。在使用 PaddleX 开发 3D 检测模型之前请务必安装 PaddleX 的 3D 检测相关模型训练插件安装过程可以参考 PaddleX 本地安装教程。二次开发的核心入口是仓库根目录下的main.py与模块配置文件 paddlex/configs/modules/3d_bev_detection/BEVFusion.yaml。该配置文件中Global段默认设置了model: BEVFusion、device: gpu:0,1,2,3并从官方地址加载相机分支预训练权重load_cam_from与激光雷达分支预训练权重load_lidar_from供训练时初始化使用。4.1 数据准备在进行模型训练前需要准备相应任务模块的数据集。PaddleX 针对每一个模块提供了数据校验功能只有通过数据校验的数据才可以进行模型训练。此外PaddleX 为每一个模块都提供了 Demo 数据集可以基于官方提供的 Demo 数据完成后续开发。4.1.1 Demo 数据下载可以参考下面的命令将 Demo 数据集下载到指定文件夹wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/nuscenes_demo.tar -P ./dataset tar -xf ./dataset/nuscenes_demo.tar -C ./dataset/4.1.2 数据校验一行命令即可完成数据校验python main.py -c paddlex/configs/modules/3d_bev_detection/BEVFusion.yaml \ -o Global.modecheck_dataset \ -o Global.dataset_dir./dataset/nuscenes_demo执行上述命令后PaddleX 会对数据集进行校验。命令运行成功后会在 log 中打印出Check dataset passed !信息同时相关产出会保存在当前目录的./output/check_dataset目录下。校验结果文件保存在./output/check_dataset_result.json校验结果文件具体内容为{ done_flag: true, check_pass: true, attributes: { num_classes: 11, train_mate: [ { sample_idx: f9878012c3f6412184c294c13ba4bac3, lidar_path: ./data/nuscenes/samples/LIDAR_TOP/n008-2018-05-21-11-06-59-0400__LIDAR_TOP__1526915243047392.pcd.bin, image_paths: [ ./data/nuscenes/samples/CAM_FRONT_LEFT/n008-2018-05-21-11-06-59-0400__CAM_FRONT_LEFT__1526915243004917.jpg, ./data/nuscenes/samples/CAM_FRONT/n008-2018-05-21-11-06-59-0400__CAM_FRONT__1526915243012465.jpg, ./data/nuscenes/samples/CAM_FRONT_RIGHT/n008-2018-05-21-11-06-59-0400__CAM_FRONT_RIGHT__1526915243019956.jpg, ./data/nuscenes/samples/CAM_BACK_RIGHT/n008-2018-05-21-11-06-59-0400__CAM_BACK_RIGHT__1526915243027813.jpg, ./data/nuscenes/samples/CAM_BACK/n008-2018-05-21-11-06-59-0400__CAM_BACK__1526915243037570.jpg, ./data/nuscenes/samples/CAM_BACK_LEFT/n008-2018-05-21-11-06-59-0400__CAM_BACK_LEFT__1526915243047295.jpg ] } ], val_mate: [ { sample_idx: 30e55a3ec6184d8cb1944b39ba19d622, lidar_path: ./data/nuscenes/samples/LIDAR_TOP/n015-2018-07-11-11-54-160800__LIDAR_TOP__1531281439800013.pcd.bin, image_paths: [ ./data/nuscenes/samples/CAM_FRONT_LEFT/n015-2018-07-11-11-54-160800__CAM_FRONT_LEFT__1531281439754844.jpg, ./data/nuscenes/samples/CAM_FRONT/n015-2018-07-11-11-54-160800__CAM_FRONT__1531281439762460.jpg, ./data/nuscenes/samples/CAM_FRONT_RIGHT/n015-2018-07-11-11-54-160800__CAM_FRONT_RIGHT__1531281439770339.jpg, ./data/nuscenes/samples/CAM_BACK_RIGHT/n015-2018-07-11-11-54-160800__CAM_BACK_RIGHT__1531281439777893.jpg, ./data/nuscenes/samples/CAM_BACK/n015-2018-07-11-11-54-160800__CAM_BACK__1531281439787525.jpg, ./data/nuscenes/samples/CAM_BACK_LEFT/n015-2018-07-11-11-54-160800__CAM_BACK_LEFT__1531281439797423.jpg ] } ] }, analysis: { histogram: check_dataset/histogram.png }, dataset_path: /workspace/bevfusion/Paddle3D/data/nuscenes, show_type: txt, dataset_type: NuscenesMMDataset }上述校验结果中check_pass为true表示数据集格式符合要求。可以看到该校验以 nuscenes 数据集规范为基准num_classes为 11dataset_type为NuscenesMMDataset每条样本包含一个lidar_path与 6 路image_paths。4.1.3 数据集格式转换/数据集划分可选在完成数据校验之后可以通过修改配置文件或是追加超参数的方式对数据集的格式进行转换也可以对数据集的训练/验证比例进行重新划分。3D 多模态融合检测模块不支持数据格式转换与数据集划分。这与配置文件 BEVFusion.yaml 中CheckDataset段默认设置一致convert.enable: False、split.enable: False即该模块不提供格式转换与划分能力。4.2 模型训练一条命令即可完成模型的训练以 3D 多模态融合检测模型BEVFusion的训练为例python main.py -c paddlex/configs/modules/3d_bev_detection/BEVFusion.yaml \ -o Global.modetrain \ -o Global.dataset_dir./dataset/nuscenes_demo需要如下几步指定模型的.yaml配置文件路径此处为BEVFusion.yaml训练其他模型时需指定相应的配置文件模型和配置文件的对应关系可查阅 PaddleX 模型列表CPU/GPU指定模式为模型训练-o Global.modetrain指定训练数据集路径-o Global.dataset_dir其他相关参数均可通过修改.yaml配置文件中的Global和Train字段进行设置也可以通过命令行追加参数来调整。例如指定前 2 卡 GPU 训练-o Global.devicegpu:0,1设置训练轮次数为 10-o Train.epochs_iters10。更多可修改参数及其详细解释可查阅 PaddleX 通用模型配置文件参数说明新特性Paddle 3.0 版本支持了 CINN 神经网络编译器在使用 GPU 设备训练时不同模型有不同程度的训练加速效果。在 PaddleX 中训练模型时可通过指定参数-o Train.dy2stTrue开启。该开关在源码中的体现位于 trainer.py 的get_train_kwargs()train_args[dy2st] self.train_config.get(dy2st, False)同时支持amp参数可选O1、O2、OFF默认OFF。更多说明模型训练过程中PaddleX 会自动保存模型权重文件默认为output如需指定保存路径可通过配置文件中-o Global.output字段进行设置PaddleX 对用户屏蔽了动态图权重和静态图权重的概念。在模型训练过程中会同时产出动态图和静态图的权重在模型推理时默认选择静态图权重推理在完成模型训练后所有产出保存在指定的输出目录默认为./output/下通常有以下产出train_result.json训练结果记录文件记录了训练任务是否正常完成以及产出的权重指标、相关文件路径等train.log训练日志文件记录了训练过程中的模型指标变化、loss 变化等config.yaml训练配置文件记录了本次训练的超参数配置.pdparams、.pdopt、.pdiparams、.json模型权重相关文件包括网络参数、优化器、静态图网络参数、静态图网络结构等注意Paddle 3.0.0 对于静态图网络结构信息的存储格式由 protobuf原.pdmodel后缀文件升级为 json现.json后缀文件以兼容 PIR 体系并获得更好的灵活性与扩展性。4.3 模型评估在完成模型训练后可以对指定的模型权重文件在验证集上进行评估验证模型精度。使用 PaddleX 进行模型评估一条命令即可完成python main.py -c paddlex/configs/modules/3d_bev_detection/BEVFusion.yaml \ -o Global.modeevaluate \ -o Global.dataset_dir./dataset/nuscenes_demo与模型训练类似需要如下几步指定模型的.yaml配置文件路径此处为BEVFusion.yaml指定模式为模型评估-o Global.modeevaluate指定验证数据集路径-o Global.dataset_dir其他相关参数均可通过修改.yaml配置文件中的Global和Evaluate字段进行设置详细请参考 PaddleX 通用模型配置文件参数说明。更多说明在模型评估时需要指定模型权重文件路径每个配置文件中都内置了默认的权重保存路径如 BEVFusion.yaml 中Evaluate.weight_path默认为output/best_model/model.pdparams如需改变只需通过追加命令行参数的形式进行设置如-o Evaluate.weight_path./output/best_model/best_model.pdparams在完成模型评估后会产出evaluate_result.json其记录了评估的结果具体来说记录了评估任务是否正常完成以及模型的评估指标包含 mAP、NDS。4.4 模型推理与模型集成在完成模型的训练和评估后即可使用训练好的模型权重进行推理预测或者进行 Python 集成。4.4.1 模型推理通过命令行的方式进行推理预测只需如下一条命令。运行以下代码前请先下载示例数据到本地。python main.py -c paddlex/configs/modules/3d_bev_detection/BEVFusion.yaml \ -o Global.modepredict \ -o Predict.model_dir./output/best_model/inference \ -o Predict.inputnuscenes_demo_infer.tar与模型训练和评估类似需要如下几步指定模型的.yaml配置文件路径此处为BEVFusion.yaml指定模式为模型推理预测-o Global.modepredict指定模型权重路径-o Predict.model_dir./output/best_model/inference指定输入数据路径-o Predict.input...其他相关参数均可通过修改.yaml配置文件中的Global和Predict字段进行设置详细请参考 PaddleX 通用模型配置文件参数说明。4.4.2 模型集成模型可以直接集成到 PaddleX 产线中也可以直接集成到自己的项目中。1. 产线集成3D 多模态融合检测模块可以集成的 PaddleX 产线是 3D 检测产线只需要替换模型路径即可完成相关产线中目标检测模块的模型更新。在产线集成中可以使用高性能部署和服务化部署来部署得到的模型。产线配置为 paddlex/configs/pipelines/3d_bev_detection.yaml其中的3DBEVDetection子模块支持通过model_dir字段直接指向自训练导出的模型目录。2. 模块集成产出的权重可以直接集成到 3D 多模态融合检测模块中可以参考上文快速集成一节的 Python 示例代码只需要将model_dir替换为训练得到的模型路径即可如create_model(BEVFusion, model_dir/path/to/your/inference)。五、总结本文以 PaddleX 的3d_bev_detection模块为主线系统梳理了 3D 多模态融合检测的完整使用路径快速集成通过create_pipeline(3d_bev_detection)一行代码创建产线对 nuscenes 格式的输入完成推理并对boxes_3d9 维向量中心点、尺寸、航向角与速度、labels_3d、scores_3d等输出进行解析、保存与 open3d 可视化二次开发基于main.py与 BEVFusion.yaml 完成check_dataset → train → evaluate → predict的完整闭环训练产物可直接用于产线或模块集成源码佐证推理预处理链点云加载、多帧点云聚合、多视角图像加载、Resize/Normalize/Pad、GPU 自定义算子依赖、结果组装与可视化阈值等实现细节均可在 paddlex/inference/models/m_3d_bev_detection/ 与 paddlex/modules/m_3d_bev_detection/ 中找到对应实现。对于自动驾驶感知、智能交通与机器人等需要三维空间感知能力的场景这套流程可以帮助你快速构建从数据校验、模型训练到高性能部署的端到端 3D 检测能力。赞分享人工智能大模型低代码计算机视觉深度学习NLP模型推理服务RAG【免费下载链接】PaddleXAll-in-One Development Tool based on PaddlePaddle项目地址https://gitcode.com/paddlepaddle/PaddleX点击查看免费下载相关推荐PaddleX 3D BEV多模态融合检测技术详解与实践指南PaddleX 3D BEV多模态融合检测技术详解与实践指南 引言自动驾驶感知的技术革命 在自动驾驶技术飞速发展的今天3D目标检测已成为感知系统的核心技术瓶人工智能大模型低代码计算机视觉深度学习模型推理服务.NET 覆盖率分析实战指南基于 Cobertura 证据解读、目标算术与 CRAP 风险排名dotnet-test coverage-analysis Skill.NET 覆盖率分析实战指南基于 Cobertura 证据解读、目标算术与 CRAP 风险排名dotnet test coverage analysis S人工智能大模型低代码计算机视觉深度学习NLP模型推理服务RAG微调语音PaddleX 3D多模态融合检测技术详解与实战指南PaddleX 3D多模态融合检测技术详解与实战指南 前言 在自动驾驶、机器人导航等前沿领域3D目标检测技术扮演着至关重要的角色。PaddleX作为飞桨生态下人工智能大模型低代码计算机视觉深度学习模型推理服务上一篇Haystack AmazonTextractConverter 实战指南用 AWS Textract 为 RAG 管道接入图像与单页 PDF 文本提取下一篇在 TanStack Router 项目中集成 Shadcn/ui完整配置、动画修复与类型安全导航实战创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考