企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 深度学习
• 自动驾驶

MMDetection3D 在tools/目录下集成了覆盖"训练—评估—部署—转换"全流程的实用工具，包括训练日志曲线绘制与训练耗时统计、基于 TorchServe 的模型服务化部署、模型 FLOPs/参数量评估、预训练权重格式转换（RegNet、publish 模型）以及 nuImages 等数据集转换脚本。读完本文，你将能熟练使用这些工具完成 3D 检测模型日常实验中的效率分析、服务部署与模型发布工作，并结合 tools 目录下的源码理解每个命令的底层实现原理。

一、工具全景概览

tools/目录按用途划分为analysis_tools/、deployment/、model_converters/、dataset_converters/、misc/五个子目录，各自承担不同职责：

下文按原文档主线逐类展开，并在每一节结合仓库源码补充关键实现细节。

二、训练日志分析：曲线绘制与训练耗时统计

训练过程中 Runner 会输出.log.json格式的日志文件，analyze_logs.py 支持两种子任务：plot_curve绘制 loss/mAP 曲线，cal_train_time统计平均训练迭代耗时。使用前需要先安装绘图依赖pip install seaborn。

2.1 绘制训练曲线

python tools/analysis_tools/analyze_logs.py plot_curve [--keys ${KEYS}] [--title ${TITLE}] [--legend ${LEGEND}] [--backend ${BACKEND}] [--style ${STYLE}] [--out ${OUT_FILE}] [--mode ${MODE}] [--interval ${INTERVAL}]

各参数含义如下：

• --keys：要绘制的指标键，可传多个，默认值为mAP_0.25；
• --title：图像标题；
• --legend：每条曲线的图例名称，可传多个；不指定时自动使用{日志文件名}_{指标名}组合（见 analyze_logs.py 的实现）；
• --backend：matplotlib 后端；
• --style：seaborn 样式，默认dark；
• --out：输出图像文件路径（如.pdf、.png），不指定则直接弹出窗口显示；
• --mode/--interval：注意原文档中的--mode eval与--interval在源码中实际对应--eval与--eval-interval两个参数。若想绘制的是评估阶段（validation）计算的指标（如 KITTI 的Car_3D_moderate_strict），必须加--eval；且当训练时设置了每隔${INTERVAL}个 epoch 评估一次时，需要同步传--eval-interval ${INTERVAL}，否则脚本会在读取日志时抛出 KeyError（analyze_logs.py 会提示检查是否使用了--no-validate或eval_interval是否匹配）。

以下图为例，这是典型的分类/回归损失收敛曲线，横轴为训练迭代数（iter），纵轴为损失值：

常用示例：

• 绘制某个 run 的分类损失：

  python tools/analysis_tools/analyze_logs.py plot_curve log.json --keys loss_cls --legend loss_cls

• 同时绘制分类损失与回归损失，并保存为 PDF：

  python tools/analysis_tools/analyze_logs.py plot_curve log.json --keys loss_cls loss_bbox --out losses.pdf

• 在同一张图对比两个 run 的 KITTI 车类 3D 检测 mAP（评估指标需加--eval，且按实际评估间隔传--eval-interval）：

  # 对比 PartA2 与 second 在 KITTI 上按 Car_3D_moderate_strict 评估 python tools/analysis_tools/analyze_logs.py plot_curve tools/logs/PartA2.log.json tools/logs/second.log.json --keys KITTI/Car_3D_moderate_strict --legend PartA2 second --eval --eval-interval 1 # 对比 PointPillars 车类与 3 类模型 python tools/analysis_tools/analyze_logs.py plot_curve tools/logs/pp-3class.log.json tools/logs/pp.log.json --keys KITTI/Car_3D_moderate_strict --legend pp-3class pp --eval --eval-interval 2

说明：示例中的tools/logs/*.log.json路径来自原文档，实际使用时应替换为你本地训练输出的日志文件。这里--eval-interval对应原文档的--interval，二者是同一参数在不同版本命令行界面下的写法，以当前仓库 analyze_logs.py 定义的参数名为准。

源码级实现细节：脚本通过load_json_logs逐行解析 JSON 日志并按键聚合——含/的键（如KITTI/Car_3D_moderate_strict）只取/后最后一段作为指标名；日志中记录epoch字段时切换当前 epoch 分组（analyze_logs.py）。非 eval 模式下横轴为迭代数（iter），eval 模式下横轴为 epoch 且用圆形 marker 标记每个评估点（analyze_logs.py）。该实现也解释了为什么日志的记录间隔必须小于一个 epoch 的迭代数，否则无法按 epoch 正确分组统计。

2.2 统计平均训练耗时

python tools/analysis_tools/analyze_logs.py cal_train_time log.json [--include-outliers]

--include-outliers表示是否把每个 epoch 的第一条耗时记录（通常含数据加载等冷启动开销，可视为离群点）纳入平均计算；默认剔除（源码中对应all_times.append(log_dict[epoch]['time'][1:])，见 analyze_logs.py）。

输出格式如下：

-----Analyze train time of work_dirs/some_exp/20190611_192040.log.json----- slowest epoch 11, average time is 1.2024 fastest epoch 1, average time is 1.1909 time std over epochs is 0.0028 average iter time: 1.1959 s/iter

报告包含最慢/最快 epoch、跨 epoch 的耗时标准差与整体平均迭代耗时，可用来快速判断训练速度是否稳定、是否存在资源抖动。

三、基于 TorchServe 的模型服务化部署

仓库提供了把 MMDetection3D 模型部署为 TorchServe 推理服务的完整链路。需要特别说明：该工具目前仍处于实验阶段，仅支持 SECOND 系列模型服务化（相关限制与演进计划见原文档说明），未来会支持更多模型。

部署流程共四步：

3.1 将 MMDetection3D 模型转换为 TorchServe 存档

python tools/deployment/mmdet3d2torchserve.py ${CONFIG_FILE} ${CHECKPOINT_FILE} \ --output-folder ${MODEL_STORE} \ --model-name ${MODEL_NAME}

• ${CONFIG_FILE}：MMDetection3D 格式的模型配置；
• ${CHECKPOINT_FILE}：训练得到的 checkpoint 权重；
• --output-folder：必须是绝对路径，生成的{model_name}.mar将写入该目录；
• --model-name：模型名，缺省时以 checkpoint 文件名去除后缀命名。

从源码看，该脚本在临时目录中展开配置后，调用torch-model-archiver的package_model将 config、checkpoint 与 mmdet3d_handler.py 一起打包，并支持--model-version（默认1.0）与-f/--force覆盖已存在的.mar文件（mmdet3d2torchserve.py）。如果环境缺少torch-model-archiver，脚本会直接提示pip install torch-model-archiver。

3.2 构建mmdet3d-serveDocker 镜像

docker build -t mmdet3d-serve:latest docker/serve/

镜像由 docker/serve/Dockerfile 定义，其基于pytorch/pytorch官方镜像，安装了 Java 运行时（TorchServe 依赖）、torchserve、torch-model-archiver，并通过mim install方式安装 mmengine、mmcv、mmdet 与 mmdet3d，最后以model-server用户启动，默认暴露 8080（Inference）、8081（Management）、8082（Metrics）三个端口。镜像内的服务启动逻辑见 docker/serve/entrypoint.sh，服务配置见 docker/serve/config.properties。

3.3 运行mmdet3d-serve

docker run --rm \ --cpus 8 \ --gpus device=0 \ -p8080:8080 -p8081:8081 -p8082:8082 \ --mount type=bind,source=$MODEL_STORE,target=/home/model-server/model-store \ mmdet3d-serve:latest

• --gpus device=0指定使用 GPU 0 运行（需预先安装 nvidia-docker / NVIDIA Container Toolkit）；去掉--gpus参数可回退到 CPU 推理；
• --mount将上一步生成的模型仓库目录（$MODEL_STORE，即--output-folder）绑定挂载到容器内/home/model-server/model-store；
• 8080/8081/8082 分别对应 TorchServe 的推理、管理与指标 REST API。

3.4 验证服务部署结果

使用 test_torchserver.py 对比 TorchServe 服务端与本地 PyTorch 的推理结果是否一致：

python tools/deployment/test_torchserver.py ${IMAGE_FILE} ${CONFIG_FILE} ${CHECKPOINT_FILE} ${MODEL_NAME} [--inference-addr ${INFERENCE_ADDR}] [--device ${DEVICE}] [--score-thr ${SCORE_THR}]

参数说明：

• ${IMAGE_FILE}：用于测试的点云文件（注意原文档示例中的demo/data/kitti/kitti_000008.bin为历史版本示例路径，当前仓库demo/下未附带该数据文件，实际使用时请替换为本地已下载的 KITTI bin 文件路径）；
• ${CONFIG_FILE}/${CHECKPOINT_FILE}：与服务端一致的配置与权重；原文档示例中使用的旧命名配置configs/second/hv_second_secfpn_6x8_80e_kitti-3d-car.py已更新，当前仓库中对应配置为 second_hv_secfpn_8xb6-80e_kitti-3d-car.py；
• ${MODEL_NAME}：服务端注册的模型名；
• --inference-addr：默认127.0.0.1:8080；
• --device：本地 PyTorch 推理设备，默认cuda:0；
• --score-thr：3D bbox 置信度阈值，默认0.5。

脚本先通过 inference_detector 在本地跑一遍点云推理并按阈值过滤 bbox，再向服务端POST /predictions/{model_name}发送同一文件，最后用np.allclose断言两端结果一致（test_torchserver.py）。注意该脚本当前按单模态点云输入处理，与上文"仅 SECOND 可服务化"的限制一致。

四、模型复杂度评估：FLOPs 与参数量

get_flops.py 基于mmcv.cnn.get_model_complexity_info()（源自 flops-counter 思路）统计模型的浮点运算量与参数量：

python tools/analysis_tools/get_flops.py ${CONFIG_FILE} [--shape ${INPUT_SHAPE}]

输出形如：

============================== Input shape: (40000, 4) Flops: 5.78 GFLOPs Params: 953.83 k ==============================

从源码可进一步确认以下事实：

• --shape默认[40000, 4]，即 40000 个点、每点 4 维特征（x, y, z, intensity）的点云输入；--modality可选point/image/multi，其中multi多模态输入在源码中直接raise NotImplementedError（get_flops.py）；
• image 模态下传单个数值N会自动补全为(3, N, N)输入形状，传两个数值则得到(3, H, W)；
• 脚本从配置构建模型后model.eval()，在 GPU 可用时搬移到 CUDA，再计算复杂度（get_flops.py）。

使用时有三个需要注意的限制（原文档明确说明，源码亦印证）：

1. FLOPs 与输入形状强相关，参数量与输入形状无关；默认点云输入形状为(1, 40000, 4)；
2. 部分算子（如 GroupNorm、自定义算子）不计入 FLOPs 统计；
3. 目前仅支持单阶段、单模态输入（点云或图像）模型的 FLOPs 计算，双阶段与多模态模型尚未支持。

工具本身仍属实验性质，统计值可能存在偏差，适合做模型间粗略对比；若要在技术报告或论文中引用，务必先人工复核数值。

五、模型权重转换与发布

5.1 RegNet 预训练权重转 MMDetection 风格

regnet2mmdet.py 将 pycls 预训练的 RegNet 权重 key 名转换为 MMDetection 风格：

python tools/model_converters/regnet2mmdet.py ${SRC} ${DST} [-h]

从源码看，转换逻辑分为三类：stem.conv/stem.bn映射为conv1/bn1；head.fc映射为fc；残差层s*按 block 位置重排为layer{...}.{block}.{conv/bn 1/2/3}，其中首个 block 的bn/proj映射为downsample.1/downsample.0（regnet2mmdet.py）。转换后以checkpoint['state_dict']形式保存，并打印未被转换的 key 以便核对。转换后的权重可直接用于 configs/regnet 下 RegNet 主干模型（如 PointPillars + RegNet）的预训练初始化。

5.2 Detectron ResNet 权重转 PyTorch

原文档指出tools/detectron2pytorch.py用于把 Detectron 预训练 ResNet 的 key 名转换为 PyTorch 风格：

python tools/detectron2pytorch.py ${SRC} ${DST} ${DEPTH} [-h]

需要说明：该脚本属于 MMDetection 姊妹仓库的工具，并不包含在当前 mmdetection3d 仓库的tools/目录下，使用前请确认你的环境中已安装 MMDetection 或其源码目录，再在其项目根目录执行上述命令。

5.3 发布前处理 checkpoint

publish_model.py 用于把训练产物整理成可公开发布的 checkpoint，自动完成三件事：

1. 将权重加载到 CPU 张量（map_location='cpu'）；
2. 删除 optimizer 状态（减小文件体积）；
3. 计算文件 SHA256 哈希，并把前 8 位哈希追加到文件名中。

python tools/model_converters/publish_model.py ${INPUT_FILENAME} ${OUTPUT_FILENAME}

例如：

python tools/model_converters/publish_model.py work_dirs/faster_rcnn/latest.pth faster_rcnn_r50_fpn_1x_20190801.pth

最终输出文件名形如faster_rcnn_r50_fpn_1x_20190801-{hash id}.pth。从源码看，重命名通过子进程的mv异步完成，输出的.pth文件即带有哈希后缀（publish_model.py）。

六、数据集转换工具

tools/dataset_converters 目录集中了各数据集的转换脚本，目标是把原始数据整理为训练可直接消费的格式：

• KITTI、nuScenes、Lyft 等转换脚本负责生成基于 pickle 的 info 文件（如 kitti_converter.py、nuscenes_converter.py、lyft_converter.py）；
• waymo_converter.py 则把 Waymo 原始数据重排为 KITTI 风格目录；
• nuimage_converter.py 等脚本的写法也便于改造复用到其他格式的数据。

以 nuImages 数据集转换为例（转为 COCO 格式，用于 configs/nuimages 下的 2D 检测/实例分割配置）：

python -u tools/dataset_converters/nuimage_converter.py --data-root ${DATA_ROOT} --version ${VERSIONS} \ --out-dir ${OUT_DIR} --nproc ${NUM_WORKERS} --extra-tag ${TAG}

核心参数一览（默认值均与 nuimage_converter.py 中 argparse 定义一致）：

从源码看，脚本内部先把 nuImages 的 14 种原始细分类别（如vehicle.bus.bendy、human.pedestrian.adult）通过NAME_MAPPING归并为 10 个 COCO 类别（car、truck、trailer、bus、construction_vehicle、bicycle、motorcycle、pedestrian、traffic_cone、barrier），并为每张关键帧生成语义分割 mask（类别索引从 1 开始，0 保留给背景），最后输出{extra_tag}_{version}.json的 COCO 格式标注文件（nuimage_converter.py、nuimage_converter.py）。-u参数用于关闭 Python 输出缓冲，便于在长耗时转换过程中实时观察进度。

七、其他实用工具：打印完整配置

misc/print_config.py 会把指定配置展开全部_base_继承并逐字打印：

python tools/misc/print_config.py ${CONFIG} [-h] [--options ${OPTIONS [OPTIONS...]}]

• ${CONFIG}：任意配置文件的路径，例如 configs/pointpillars/pointpillars_hv_secfpn_8xb6-160e_kitti-3d-car.py；
• --options：以xxx=yyy键值对形式临时覆盖配置项，支持列表/嵌套列表写法（如key="[a,b]"），无需修改原文件。

源码实现是Config.fromfile加载后经merge_from_dict合并覆盖项，再输出cfg.pretty_text（print_config.py）。该工具非常适合排查多层_base_继承后的最终生效配置，或在提交 issue/复现实验时导出完整配置快照。

八、小结与使用建议

本文系统梳理了 MMDetection3Dtools/下的六大类实用工具：日志曲线绘制与训练耗时统计（analyze_logs.py）、TorchServe 服务化部署全流程（mmdet3d2torchserve.py 与 docker/serve/Dockerfile）、模型复杂度评估（get_flops.py）、权重转换与发布（regnet2mmdet.py、publish_model.py）、数据集转换（nuimage_converter.py）以及配置打印（print_config.py）。日常使用中有几点值得注意：绘制评估指标曲线务必确认--eval与训练时eval_interval对齐；FLOPs 统计仅支持单阶段单模态模型且数值仅供对比参考；TorchServe 服务化目前仅支持 SECOND 模型。结合仓库 tests/test_apis 等测试目录，还可以进一步验证这些工具在自动化测试中的使用方式。

• 人工智能
• 计算机视觉
• 深度学习
• 自动驾驶