1. 为什么“部署训练”要放在一起讲做视觉检测这行的朋友大概都有体会模型训练和工程部署这两件事在教程里往往是分开讲的。训练教程教你跑通配置文件、调学习率、看loss曲线部署教程教你转模型、写推理脚本、接服务。可真到了项目里这两件事根本分不开——训练时用的输入尺寸、预处理方式、后处理参数直接决定了部署端能不能对上部署端对延迟和显存的约束又反过来限制了你训练时能选多大的backbone、能不能开多尺度训练。我见过太多团队训练那边跑出一个mAP挺好看的模型交给工程那边一转发现预处理对不上、NMS参数不一致、输出维度解析错位来回扯皮好几天。所以这篇东西我想把mmdetection的部署和训练串成一条线来讲从环境搭起来、数据准备好、配置改对、训练跑稳一直到模型导出、推理验证、服务封装尽量做到“一步到位”。这里说的“一步到位”不是指无脑复制粘贴就能成而是指整个链路的思路是连贯的你在训练阶段做的每一个决定都能预判到部署阶段会发生什么。适合谁看我觉得有三类人比较对口一是刚接触mmdetection、想系统搞明白这套框架怎么落地的新手二是有一定训练经验、但部署环节总是踩坑的算法同学三是做工程落地、需要理解模型侧约束的部署同学。不管你基础如何我会尽量把每个关键选择背后的“为什么”讲清楚而不是只丢一堆命令。需要先说明一点mmdetection这个框架版本迭代比较快配置文件的组织方式、注册机制、导出接口在不同大版本之间都有差异。我下面讲的内容基于常见的2.x系列实践如果你用的是更新的版本个别API名字可能要对一下官方文档但整体思路和踩坑点是相通的。另外文中涉及的具体项目、数据、环境我都用代称你替换成自己的即可。2. 整体方案设计与思路拆解2.1 为什么选mmdetection而不是自己搭轮子先聊选型。检测任务的开源框架不少有偏研究友好的有偏部署友好的也有大厂内部流出的。mmdetection能在这几年被大量项目采用核心原因我觉得有三个。第一是模块化彻底backbone、neck、head、loss、assigner、sampler全都是可注册可替换的组件你想换个注意力模块或者换个标签分配策略改配置文件加几行注册代码就行不用动框架主干。第二是配置驱动一个实验的所有超参都收敛在py文件里配合继承机制你可以写一个base配置然后派生出十几个变体做消融管理起来很清爽。第三是生态衔接顺它和同系列的工具链在数据格式、模型导出、推理封装上是打通的训练完转部署的路径相对短。当然它也有代价。配置继承层次深的时候找一个参数到底被谁覆盖了会让人抓狂版本升级偶尔有破坏性改动文档虽然全但偏“参考手册”风格新手照着跑容易卡在环境上。这些后面我都会讲到怎么绕。2.2 “训练即部署”的连贯设计思路我这套方案的核心思路是在训练阶段就把部署约束前置。具体体现在几个决定上。输入尺寸固定化训练时就确定一个固定的输入分辨率比如短边800、长边1333这种常见设置或者干脆固定成正方形而不是开多尺度训练。多尺度训练对精度有好处但导出后的模型如果带动态shape部署端要么得支持动态输入要么得额外做shape固定麻烦。除非你的业务场景对精度极其敏感且部署端明确支持动态否则我建议训练时就固定。预处理与后处理参数显式化mean/std、通道顺序、resize策略、NMS的iou阈值和score阈值这些在训练配置里是什么部署脚本里就必须一模一样。我会在训练阶段就把这些参数单独记一份部署时直接对照杜绝“训练用RGB部署用BGR”这种低级但致命的错。导出格式早验证不要等训练完全结束才第一次尝试导出。训练到第一个epoch有checkpoint了就顺手导一次、跑一次推理确认链路通。这样万一导出有问题你还有时间调整而不是最后一天才发现。这个思路说白了就是“别让训练和部署成为两个团队各自为战的黑盒”把接口在早期就对齐。2.3 环境与依赖的整体规划环境这块我踩过的坑最多值得单独说。mmdetection对底层库的版本比较敏感尤其是深度学习框架和编译工具链的匹配。我的建议是用虚拟环境隔离并且把版本号全部钉死。不要用“最新版”不要用“pip install 不指定版本”因为不同小版本之间API变动可能就让你的配置跑不起来。一个稳妥的做法是先确定深度学习框架的版本比如某个稳定的2.x版本然后去查mmdetection对应版本官方推荐的配套版本把框架、视觉库、编译工具链的版本一次性对齐。CUDA和驱动版本也要匹配这个在环境搭建那节我会给一个对照思路。另外编译型依赖比如某些算子库在安装时容易因为本地编译器版本不对而失败建议提前确认系统里的编译器版本必要时降级。3. 环境搭建与数据准备的关键细节3.1 虚拟环境与依赖安装的稳妥顺序安装顺序这件事顺序错了就是无尽的报错。我推荐的顺序是先建虚拟环境再装深度学习框架按官方命令走别自己拼wheel然后装视觉基础库接着装mmdetection依赖的底层CV工具包最后装mmdetection本体用可编辑模式装方便改源码。# 建环境以conda为例 conda create -n mmdet_train python3.8 -y conda activate mmdet_train # 装框架版本按你查到的配套版本填 # 这一步务必用官方给的命令包含对应的CUDA版本 # 装完立刻验证 python -c import torch; print(torch.__version__, torch.cuda.is_available())验证那行一定要跑输出里cuda.is_available()是True才算过关。我见过有人装完框架没验证后面训练报“CUDA error”查了半天结果是装了个CPU版本。接着装mmdetection本体时用pip install -v -e .这种可编辑模式好处是你改了源码里的注册组件能立刻生效不用重装。装完跑一下框架自带的环境检查脚本如果有的话它会告诉你哪些依赖版本不匹配。注意不要在base环境里装也不要在多个项目共用一个环境。检测框架的依赖比较重版本冲突一旦发生排查成本极高。3.2 数据集格式转换与目录组织mmdetection主流支持COCO格式和VOC格式我一般推荐统一转成COCO格式因为它的标注信息包括iscrowd、area这些字段更完整后续做评估和导出也更顺。转换脚本网上很多但有几个细节必须自己核对。第一是类别id的连续性。COCO格式里category的id不要求从0开始连续但很多训练配置和评估逻辑默认按连续id处理如果id跳号比如1、3、5可能出现类别映射错位。转换后一定打开json看一眼categories列表。第二是图片路径与实际文件的一致性。json里的file_name是相对路径训练时框架会拼上data_root如果拼出来的路径找不到图训练直接报错。建议转换完写个小脚本随机抽几十张图验证路径可读。第三是空标注和异常框。有些标注里存在宽高为0的框、超出图像边界的框这些在训练时可能引发除零或者越界错误。转换阶段就过滤掉别留到训练时炸。目录组织我习惯这样data/ my_dataset/ annotations/ train.json val.json train/ xxx.jpg val/ xxx.jpg配置里data_root指向data/my_dataset/ann_file写annotations/train.jsonimg_prefix写train/。这样结构清晰换数据集只改配置不改代码。3.3 配置文件继承体系怎么读才不迷路mmdetection的配置是继承式的一个训练配置往往继承自一个basebase又可能继承自更底层的base。新手最容易犯的错是改了一个参数发现没生效因为被上层或者更后面的定义覆盖了。我的读法是从叶子往根倒推。先打开你要用的那个配置文件看它_base_里继承了谁然后一层层往上翻把涉及你要改的模块比如model、train_pipeline、optimizer的定义都找出来理清覆盖顺序。配置里同一个key后定义的覆盖先定义的_base_列表里越靠后的优先级越高。改配置时我建议不改base只在自己的实验配置里覆盖。这样base保持干净实验配置一目了然出了问题也好回滚。比如你要改学习率就在自己的配置里写optimizer dict(lr0.01)而不是去动base里的optimizer。4. 训练配置的核心参数与实操要点4.1 模型结构选择从业务约束反推选backbone和head不是看哪个mAP高就选哪个得从部署约束反推。如果你的部署端是边缘设备、算力有限那就要优先考虑轻量backbone比如深度可分离卷积系列输入分辨率也不能太大。如果是服务器端、延迟要求不严那可以上重一点的backbone追求精度。检测头这块单阶段和两阶段的选择也影响部署复杂度。单阶段结构简单、导出后算子少部署友好两阶段精度往往更好但结构复杂导出和推理时的后处理逻辑要多写一些。我的经验是如果部署链路是第一次做优先选结构简单的单阶段方案跑通全流程再考虑换复杂结构。先把“能跑通”这件事拿下比一上来追求极致精度重要。配置里改模型结构主要动model字典下的backbone、neck、bbox_head。改完记得检查train_cfg和test_cfg里的相关参数是否还匹配比如anchor的尺寸、strides换了backbone的下采样倍数这些都要跟着调。4.2 学习率与batch size的配比计算学习率和batch size是绑定的。业界常用的经验法则是线性缩放batch size翻倍学习率也大致翻倍。但这个法则有前提不是无脑套。我一般这样定初始值先确定显存能撑住的最大batch size用二分法试从大往小调直到不OOM然后按每张卡每batch大概对应某个基准学习率来算。举个具体例子。假设基准是8卡、每卡2张图、学习率0.02这是很多检测配置的常见起点。如果你只有单卡、每卡能放4张图那总batch是4相比基准的16缩放系数是0.25学习率大致取0.005。当然这只是起点实际还要看loss曲线微调。# 配置里optimizer和lr_config的典型写法 optimizer dict(typeSGD, lr0.005, momentum0.9, weight_decay0.0001) lr_config dict( policystep, warmuplinear, warmup_iters500, warmup_ratio0.001, step[8, 11]) # 在第8、11个epoch降学习率warmup别省检测任务前期loss波动大warmup能让训练稳下来。warmup_iters按你的总迭代数比例给一般占总iter的很小一部分。4.3 数据增强的取舍训练收益与部署一致性数据增强能提精度但有些增强会改变图像的统计特性如果部署端不做同样的处理就会造成训练和推理的分布不一致。比如颜色抖动color jitter在训练时随机改亮度对比度部署时图像是原始的模型可能对原始图的响应偏弱。我的原则是几何类增强翻转、缩放、裁剪可以放心用因为部署端可以通过调整输入尺寸部分对齐颜色类增强要谨慎用了就要评估部署端的影响。另外增强的pipeline顺序也有讲究。resize、pad、normalize的顺序要和部署端预处理严格一致。我习惯在配置里把pipeline写清楚然后部署脚本照着这个pipeline一步步实现确保像素级对齐。train_pipeline [ dict(typeLoadImageFromFile), dict(typeLoadAnnotations, with_bboxTrue), dict(typeResize, img_scale(1333, 800), keep_ratioTrue), dict(typeRandomFlip, flip_ratio0.5), dict(typeNormalize, mean[123.675, 116.28, 103.53], std[58.395, 57.12, 57.375], to_rgbTrue), dict(typePad, size_divisor32), dict(typeDefaultFormatBundle), dict(typeCollect, keys[img, gt_bboxes, gt_labels]), ]注意to_rgbTrue和mean/std的对应关系部署端如果读图是BGR就得先转RGB再减均值顺序错了结果全错。4.4 训练启动与日志监控启动训练的命令不复杂单机多卡用分布式启动器指定卡数和配置文件即可。启动后重点盯几个东西loss是否正常下降分类loss、回归loss分开看、学习率是否按预期变化、显存占用是否稳定、有没有出现nan。# 单机多卡启动卡数按实际填 bash tools/dist_train.sh configs/my_exp/my_config.py 4 --work-dir work_dirs/my_exp日志里如果看到某个loss突然变成nan常见原因是学习率太大、数据里有异常标注、或者梯度爆炸。先降学习率试不行就检查数据。显存如果持续上涨最后OOM多半是数据加载的worker数开太多或者有内存泄漏把data.samples_per_gpu和data.workers_per_gpu调小试试。实操心得训练前先跑个几十iter的“冒烟测试”确认整个pipeline能走通、loss能算出来、checkpoint能存下来再开长训练。这个习惯帮我省过很多次“跑了半天才发现配置错”的时间。5. 模型导出与部署链路的打通5.1 导出前的检查清单导出不是点一下按钮就完事导出前有几项必须确认。第一配置文件里的test_cfg要和部署端一致尤其是NMS的iou_threshold、score_threshold、max_per_img这些导出时如果框架把后处理也固化进模型那这些参数就定死了部署端改不了。第二输入尺寸固定确认导出时指定的input_shape和训练时一致。第三类别数对齐导出的模型输出维度里的类别数必须和部署端解析逻辑匹配。我一般会写一个导出脚本把配置路径、checkpoint路径、输出路径、输入shape都作为参数传进去导出后立刻用同一份配置跑一次推理把结果和训练时验证集的结果对比确认数值一致。5.2 导出格式选择与算子兼容性导出格式的选择取决于部署端。如果部署端是通用推理引擎那要关注模型里的算子是否都被支持。检测模型里常见的“麻烦算子”包括一些自定义的NMS实现、动态shape相关的操作、以及某些特殊的插值方式。导出后如果发现某些算子不被支持有两个思路一是把后处理从模型里剥离出来模型只输出原始预测后处理用部署端的代码实现二是替换成等价的支持算子。我倾向于把后处理剥离因为这样模型更纯粹部署端对NMS参数的控制也更灵活。剥离后模型输出的是每个检测头的原始分类得分和框回归值部署端自己解码、自己NMS。代价是部署端要多写一些解码逻辑但换来的是参数可调和算子兼容性好。5.3 推理脚本编写与结果对齐验证推理脚本的核心是预处理、前向、后处理三段要和训练严格对齐。预处理按训练pipeline来前向就是喂数据拿输出后处理按test_cfg来。写完后拿几张训练集里的图跑一下把检测框画出来肉眼看再和训练时验证脚本的输出做数值对比框坐标、得分差异在容忍范围内才算对齐。# 推理脚本骨架示意 import numpy as np def preprocess(img, mean, std, input_shape): # resize保持比例、pad到固定尺寸、转RGB、减均值除标准差 ... def postprocess(preds, score_thr, iou_thr, max_per_img): # 解码、按得分过滤、NMS ... # 关键mean/std/score_thr/iou_thr 必须和训练配置一致对齐验证这一步千万别省。我见过预处理里少做了一次通道转换导致部署后精度掉了一大截查了两天才发现。6. 常见问题与排查技巧实录6.1 环境与训练阶段的典型故障现象可能原因排查与解决训练启动报CUDA相关错误框架装成了CPU版或CUDA版本不匹配验证cuda.is_available()重装对应版本编译依赖安装失败本地编译器版本与依赖要求不符查依赖要求的编译器版本降级或升级loss出现nan学习率过大、数据异常、梯度爆炸降学习率、过滤异常标注、加梯度裁剪显存持续上涨后OOMworker过多、内存泄漏调小worker数和batch检查数据加载代码找不到图片文件路径拼接错误、file_name不对打印实际拼接路径核对json里的file_name6.2 部署阶段的精度掉点排查部署后精度掉点是最让人头疼的问题因为原因可能藏在链路的任何一环。我的排查顺序是先查预处理再查后处理最后查模型本身。预处理查通道顺序、mean/std、resize策略是否和训练一致后处理查NMS阈值、得分阈值、解码方式模型本身查导出时有没有算子被错误替换、输入shape是否一致。一个高效的定位方法是拿同一张图分别在训练框架里和部署端跑把中间结果预处理后的张量、模型原始输出、NMS后的框逐层对比哪一层开始出现差异问题就在那一层。这个方法比盲猜快得多。6.3 独家避坑技巧汇总参数快照训练启动时把最终生效的完整配置dump一份存到work_dir部署时以这份为准而不是以你记忆中的配置为准。小样本回归测试部署链路搭好后固定几张图作为回归测试集每次改代码都跑一遍对比输出是否变化防止改一处崩一片。版本锁定文件把环境里所有包的版本导出成文件存档换机器复现时照着装避免“在我机器上是好的”。导出即验证每次导出模型后立刻跑推理验证不要攒着一起验问题越早发现越好定位。7. 我个人在实际操作中的几点体会这套“训练部署一步到位”的流程我前后在几个项目里打磨过最大的感受是真正花时间的往往不是模型本身而是链路的对齐。训练一个能出结果的模型可能几天就搞定但把训练和部署之间的每一个接口对齐、把每一个参数核对清楚可能要花同样甚至更多的时间。所以我现在做项目会在一开始就把部署端的约束列出来反过来指导训练配置而不是训练完再想部署。另外一个体会是别迷信“一步到位”的字面意思。没有任何一套流程能让你完全不做验证就上线所谓一步到位是指思路连贯、环节可预期、问题可定位而不是跳过验证。该跑的冒烟测试、该做的对齐验证、该留的参数快照一个都不能少。把这些基本功做扎实后面换模型、换数据、换部署端的时候你才有底气快速迭代。最后分享一个小习惯我会给每个项目维护一份“链路对照表”左边写训练配置里的关键参数右边写部署脚本里对应的实现位置中间标注是否已验证一致。这份表在交接和排查时特别好用比翻聊天记录和代码注释靠谱得多。