1. RT-DETR环境搭建避坑指南第一次接触RT-DETR时我在环境配置上踩了不少坑。这个基于Transformer的目标检测模型对PyTorch版本要求非常严格稍有不慎就会遇到各种兼容性问题。建议使用conda创建独立环境避免与其他项目冲突conda create -n rtdetr python3.8 conda activate rtdetr最关键的是PyTorch版本必须精确匹配。我试过用最新版PyTorch结果训练时直接报错AttributeError: module torchvision has no attribute disable_beta_transforms_warning。正确的安装命令应该是conda install pytorch2.0.1 torchvision0.15.2 torchaudio2.0.2 pytorch-cuda11.7 -c pytorch -c nvidia安装完基础环境后进入项目目录安装依赖。这里有个细节要注意如果直接从GitHub克隆RT-DETR项目建议先检查requirement.txt里的版本号。我遇到过pip自动安装最新版依赖导致兼容性问题的情况后来锁定版本才解决cd /path/to/RT-DETR pip install -r requirement.txt2. 训练流程详解与常见问题2.1 数据集准备技巧RT-DETR默认使用COCO格式数据集配置文件路径在configs/dataset/coco_detection.yml。新手最容易犯的错误是直接修改数据加载器的类别数这会导致训练时出现维度不匹配。正确的做法是通过修改配置文件中的num_classes参数记得要包括背景类别。比如我做车牌检测时虽然只有一个目标类别但num_classes需要设置为2背景车牌。有次训练时mAP始终为0排查半天才发现是这个参数设错了。2.2 训练参数调优训练启动命令很简单python tools/train.py -c configs/rtdetr/rtdetr_r50vd_6x_coco.yml但有几个关键参数需要关注学习率配置在configs/rtdetr/include/optimizer.yml训练轮数在配置文件的max_epochs参数如果显存不足可以减小batch_size实测发现RT-DETR对学习率比较敏感建议先用默认参数训练等loss曲线平稳后再调整。我在2080Ti上训练时将batch_size从16降到8才解决OOM问题。3. 模型导出与预测实战3.1 ONNX导出注意事项导出ONNX模型时需要修改tools/export_onnx.py中的模型路径。这里有个坑如果直接运行可能会报shape不匹配错误。解决办法是在导出前先加载模型并做一次前向推理model build_rtdetr(cfg) load_weight(model, path/to/checkpoint.pth) model.eval() dummy_input torch.randn(1,3,640,640) # 与输入尺寸一致 torch.onnx.export(model, dummy_input, model.onnx)3.2 预测代码解析用ONNXRuntime做预测时输入尺寸需要与训练时一致。这是我调试通过的预测脚本核心部分sess ort.InferenceSession(model.onnx) output sess.run( output_namesNone, input_feed{ images: im_data.data.numpy(), orig_target_sizes: size.data.numpy() } )特别注意输出顺序是labels、boxes、scores。有次我把输出名写错了导致检测框和类别对应不上。建议先用print(output.shape)确认输出维度。4. 高频报错解决方案4.1 导入路径问题最常见的报错是ImportError: attempted relative import with no known parent package。这是因为Python找不到模块路径。解决方法有两种在PyCharm中正确设置项目根目录将相对导入改为绝对导入例如# 错误写法 from .utils import get_activation # 正确写法 from src.zoo.rtdetr.utils import get_activation4.2 图像尺寸限制报错当处理大图时会遇到Image size exceeds limit错误。在以下两个文件添加配置即可解决# 在solver.py和det_solver.py开头添加 from PIL import ImageFile ImageFile.LOAD_TRUNCATED_IMAGES True Image.MAX_IMAGE_PIXELS None4.3 多边形标注处理如果标注是非矩形框如文字检测可能会遇到坐标校验错误。我的解决方案是将多边形转为外接矩形确保每个标注都有唯一ID检查标注文件中的width/height是否为实际值有次标注工具生成的JSON里width写成了0导致训练时直接崩溃。后来写了个校验脚本提前检查数据才避免这类问题。