戰(zhàn)指南：從配置驅(qū)動(dòng)到模型部署的完整流程)
1. 為什么值得花時(shí)間搞懂 detectron2如果你正在做計(jì)算機(jī)視覺(jué)相關(guān)的項(xiàng)目尤其是目標(biāo)檢測(cè)、實(shí)例分割、關(guān)鍵點(diǎn)檢測(cè)這類(lèi)任務(wù)大概率會(huì)碰到detectron2這個(gè)名字。它是某知名AI研究機(jī)構(gòu)開(kāi)源的一個(gè)目標(biāo)檢測(cè)與分割框架基于PyTorch構(gòu)建把大量經(jīng)典和前沿的檢測(cè)、分割模型整合到了一套統(tǒng)一的代碼體系里。簡(jiǎn)單說(shuō)它解決的核心問(wèn)題是讓你不用從零實(shí)現(xiàn)Faster R-CNN、Mask R-CNN、RetinaNet這些模型的訓(xùn)練和推理流程直接調(diào)用現(xiàn)成的、經(jīng)過(guò)驗(yàn)證的實(shí)現(xiàn)就能跑起來(lái)。我第一次接觸它是因?yàn)橐粋€(gè)工業(yè)質(zhì)檢的項(xiàng)目需要在產(chǎn)線圖片里定位缺陷區(qū)域并做像素級(jí)分割。當(dāng)時(shí)試過(guò)自己搭Mask R-CNN光是把ROI Align、RPN、多尺度訓(xùn)練這些環(huán)節(jié)調(diào)通就花了兩周效果還不穩(wěn)定。后來(lái)?yè)Q到detectron2同樣的數(shù)據(jù)集配置改一改兩天就跑出了可用的baseline。這個(gè)效率差距就是它最大的價(jià)值。這篇文章適合誰(shuí)看如果你是剛?cè)腴T(mén)目標(biāo)檢測(cè)的學(xué)生、需要快速驗(yàn)證算法的工程師、或者想找一個(gè)穩(wěn)定訓(xùn)練框架的研究者那這篇內(nèi)容能幫你少走很多彎路。我會(huì)從整體設(shè)計(jì)思路講起然后拆解核心配置項(xiàng)再給出一套完整的實(shí)操流程最后把我在實(shí)際項(xiàng)目中踩過(guò)的坑整理成排查清單。全程不堆術(shù)語(yǔ)盡量用“人話”把每個(gè)選擇背后的原因講清楚。2. 整體設(shè)計(jì)思路與方案選型考量2.1 為什么是“配置驅(qū)動(dòng)”而不是“代碼驅(qū)動(dòng)”detectron2最核心的設(shè)計(jì)哲學(xué)是配置驅(qū)動(dòng)config-driven。你幾乎不需要改Python代碼只需要寫(xiě)一個(gè)YAML配置文件就能定義模型結(jié)構(gòu)、數(shù)據(jù)集路徑、訓(xùn)練超參數(shù)、數(shù)據(jù)增強(qiáng)策略等所有內(nèi)容。這個(gè)選擇背后有很實(shí)際的考量。傳統(tǒng)做法是每個(gè)項(xiàng)目復(fù)制一份訓(xùn)練腳本然后在代碼里改參數(shù)。問(wèn)題是當(dāng)你同時(shí)跑十幾個(gè)實(shí)驗(yàn)對(duì)比不同backbone、不同學(xué)習(xí)率、不同增強(qiáng)策略時(shí)代碼分支會(huì)變得極其混亂。detectron2把配置抽出來(lái)之后實(shí)驗(yàn)管理變得非常清晰一個(gè)實(shí)驗(yàn)一個(gè)YAML文件配合命令行覆蓋參數(shù)可以快速做消融研究。它的配置系統(tǒng)基于一個(gè)叫LazyConfig和CfgNode的機(jī)制。早期版本主要用CfgNode類(lèi)似字典的層級(jí)結(jié)構(gòu)支持從文件加載和命令行覆蓋。新版本引入了LazyConfig用Python文件做配置靈活性更高但對(duì)新手來(lái)說(shuō)門(mén)檻也稍高一些。我的建議是新手從CfgNode的YAML配置入手熟悉之后再考慮LazyConfig。注意detectron2的配置項(xiàng)非常多但真正需要你手動(dòng)調(diào)的其實(shí)就那么十幾個(gè)。不要被配置文件里密密麻麻的鍵值嚇到大部分保持默認(rèn)就行。2.2 模型 zoo 的設(shè)計(jì)邏輯detectron2內(nèi)置了一個(gè)Model Zoo提供了大量預(yù)訓(xùn)練模型。這些模型按照任務(wù)類(lèi)型和backbone結(jié)構(gòu)組織比如COCO-Detection下面是目標(biāo)檢測(cè)模型COCO-InstanceSegmentation下面是實(shí)例分割模型COCO-Keypoints是關(guān)鍵點(diǎn)檢測(cè)。這個(gè)設(shè)計(jì)的好處是你可以直接加載預(yù)訓(xùn)練權(quán)重做微調(diào)而不需要從頭訓(xùn)練。對(duì)于小數(shù)據(jù)集項(xiàng)目微調(diào)預(yù)訓(xùn)練模型通常比從頭訓(xùn)練效果好得多收斂也快得多。我做過(guò)對(duì)比同樣一個(gè)5000張圖的缺陷檢測(cè)數(shù)據(jù)集從頭訓(xùn)練mAP只能到0.45左右加載COCO預(yù)訓(xùn)練權(quán)重微調(diào)能到0.72。選擇哪個(gè)預(yù)訓(xùn)練模型主要看三個(gè)因素任務(wù)類(lèi)型、精度要求、推理速度要求。R50ResNet-50 backbone是速度和精度的平衡點(diǎn)R101精度更高但慢一些X101是更深的網(wǎng)絡(luò)適合精度優(yōu)先的場(chǎng)景。如果部署在邊緣設(shè)備上可以考慮MobileNet backbone的輕量模型。2.3 數(shù)據(jù)加載與增強(qiáng)的流水線設(shè)計(jì)detectron2的數(shù)據(jù)加載用了DatasetCatalog和MetadataCatalog兩個(gè)注冊(cè)表。你需要把數(shù)據(jù)集注冊(cè)進(jìn)去框架才能識(shí)別。這個(gè)設(shè)計(jì)看起來(lái)多了一步但實(shí)際上很合理它把數(shù)據(jù)集的“物理位置”和“邏輯名稱(chēng)”解耦了方便切換不同數(shù)據(jù)集做實(shí)驗(yàn)。數(shù)據(jù)增強(qiáng)方面detectron2內(nèi)置了一套基于AugmentationList的增強(qiáng)流水線。常用的增強(qiáng)包括隨機(jī)翻轉(zhuǎn)、隨機(jī)裁剪、顏色抖動(dòng)、亮度對(duì)比度調(diào)整等。它的增強(qiáng)是在線進(jìn)行的每個(gè)epoch的增強(qiáng)結(jié)果都不同能有效提升模型泛化能力。這里有個(gè)容易忽略的點(diǎn)增強(qiáng)策略要和任務(wù)匹配。比如做文本檢測(cè)時(shí)隨機(jī)旋轉(zhuǎn)可能會(huì)破壞文字的可讀性做工業(yè)缺陷檢測(cè)時(shí)顏色抖動(dòng)可能改變?nèi)毕莸囊曈X(jué)特征。我見(jiàn)過(guò)有人直接套用COCO的增強(qiáng)配置做工業(yè)項(xiàng)目結(jié)果模型把顏色變化當(dāng)成了缺陷特征換一批光照條件就完全失效。3. 核心配置項(xiàng)深度拆解與實(shí)操要點(diǎn)3.1 環(huán)境搭建從零到能跑通第一個(gè)Demo環(huán)境搭建是第一步也是最容易卡住的地方。detectron2對(duì)PyTorch版本、CUDA版本、編譯器版本都有要求版本不匹配會(huì)報(bào)各種奇怪的錯(cuò)誤。我的建議是用conda創(chuàng)建獨(dú)立環(huán)境不要污染系統(tǒng)Python。步驟如下conda create -n detectron2 python3.9 conda activate detectron2然后安裝PyTorch。這里要注意detectron2需要PyTorch 1.8以上但不同版本對(duì)CUDA的支持不同。如果你用的是CUDA 11.3可以這樣裝pip install torch1.10.0cu113 torchvision0.11.0cu113 -f https://download.pytorch.org/whl/torch_stable.html接下來(lái)安裝detectron2本體。有兩種方式pip安裝和源碼編譯。pip安裝簡(jiǎn)單但可能遇到版本兼容問(wèn)題源碼編譯更可控但需要gcc和g支持。# 方式一pip安裝 pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu113/torch1.10/index.html # 方式二源碼編譯 git clone https://github.com/facebookresearch/detectron2.git cd detectron2 pip install -e .提示源碼編譯時(shí)如果報(bào)“nvcc not found”說(shuō)明CUDA編譯器沒(méi)裝好需要先安裝對(duì)應(yīng)版本的CUDA Toolkit。如果報(bào)“gcc version too old”需要升級(jí)gcc到7.5以上。驗(yàn)證安裝是否成功import detectron2 print(detectron2.__version__)能打印出版本號(hào)就說(shuō)明基礎(chǔ)環(huán)境OK了。如果報(bào)“ImportError: libcudart.so.11.0: cannot open shared object file”說(shuō)明CUDA路徑?jīng)]配好需要把CUDA的lib目錄加到LD_LIBRARY_PATH里。3.2 配置文件的核心結(jié)構(gòu)一個(gè)典型的detectron2配置文件包含以下幾個(gè)大塊MODEL: META_ARCHITECTURE: GeneralizedRCNN BACKBONE: NAME: build_resnet_fpn_backbone RESNETS: DEPTH: 50 FPN: IN_FEATURES: [res2, res3, res4, res5] ROI_HEADS: NUM_CLASSES: 3 WEIGHTS: detectron2://COCO-Detection/faster_rcnn_R_50_FPN_3x/137849458/model_final_280758.pkl DATASETS: TRAIN: (my_dataset_train,) TEST: (my_dataset_val,) SOLVER: BASE_LR: 0.001 MAX_ITER: 10000 BATCH_SIZE_PER_IMAGE: 64 STEPS: (7000, 9000) INPUT: MIN_SIZE_TRAIN: (640, 800) MAX_SIZE_TRAIN: 1333 MIN_SIZE_TEST: 800 MAX_SIZE_TEST: 1333MODEL.META_ARCHITECTURE決定用哪個(gè)模型架構(gòu)。目標(biāo)檢測(cè)用GeneralizedRCNN實(shí)例分割也用這個(gè)但需要加mask head關(guān)鍵點(diǎn)檢測(cè)用GeneralizedRCNN加keypoint head。MODEL.WEIGHTS指定預(yù)訓(xùn)練權(quán)重路徑。可以是本地文件路徑也可以是Model Zoo的URL。加載預(yù)訓(xùn)練權(quán)重時(shí)如果類(lèi)別數(shù)不匹配比如COCO是80類(lèi)你的數(shù)據(jù)集是3類(lèi)框架會(huì)自動(dòng)跳過(guò)分類(lèi)層的權(quán)重只加載backbone和RPN的權(quán)重。SOLVER.BASE_LR是基礎(chǔ)學(xué)習(xí)率。這個(gè)值很關(guān)鍵太大容易震蕩太小收斂慢。經(jīng)驗(yàn)值是batch size為2時(shí)用0.001batch size為8時(shí)用0.005batch size為16時(shí)用0.01。如果你不確定從0.001開(kāi)始試。SOLVER.STEPS是學(xué)習(xí)率衰減的迭代次數(shù)。比如(7000, 9000)表示在第7000次和第9000次迭代時(shí)把學(xué)習(xí)率乘以0.1。通常設(shè)置在總迭代次數(shù)的70%和90%位置。INPUT.MIN_SIZE_TRAIN是訓(xùn)練時(shí)的圖像短邊縮放范圍。多尺度訓(xùn)練能提升模型對(duì)不同尺寸目標(biāo)的適應(yīng)能力但會(huì)增加顯存占用。如果顯存不夠可以固定一個(gè)值比如(800,)。3.3 數(shù)據(jù)集注冊(cè)的完整流程detectron2不能直接讀文件夾里的圖片必須先把數(shù)據(jù)集注冊(cè)到DatasetCatalog。注冊(cè)的核心是提供一個(gè)函數(shù)返回一個(gè)列表每個(gè)元素是一個(gè)字典包含file_name、image_id、annotations等字段。以COCO格式的數(shù)據(jù)集為例from detectron2.data.datasets import register_coco_instances register_coco_instances( my_dataset_train, {}, annotations/train.json, images/train ) register_coco_instances( my_dataset_val, {}, annotations/val.json, images/val )如果是自定義格式比如每張圖對(duì)應(yīng)一個(gè)XML標(biāo)注文件就需要自己寫(xiě)注冊(cè)函數(shù)from detectron2.data import DatasetCatalog, MetadataCatalog import os import xml.etree.ElementTree as ET def get_my_dataset_dicts(img_dir, anno_dir): dataset_dicts [] for idx, img_name in enumerate(os.listdir(img_dir)): record {} record[file_name] os.path.join(img_dir, img_name) record[image_id] idx record[height] 640 record[width] 640 anno_path os.path.join(anno_dir, img_name.replace(.jpg, .xml)) tree ET.parse(anno_path) objs [] for obj in tree.findall(object): bbox obj.find(bndbox) objs.append({ bbox: [ float(bbox.find(xmin).text), float(bbox.find(ymin).text), float(bbox.find(xmax).text), float(bbox.find(ymax).text) ], bbox_mode: BoxMode.XYXY_ABS, category_id: class_names.index(obj.find(name).text) }) record[annotations] objs dataset_dicts.append(record) return dataset_dicts DatasetCatalog.register(my_dataset_train, lambda: get_my_dataset_dicts(images/train, annotations/train)) MetadataCatalog.get(my_dataset_train).set(thing_classes[defect_a, defect_b, defect_c])注意image_id必須是唯一的整數(shù)。如果重復(fù)評(píng)估時(shí)會(huì)出錯(cuò)。bbox_mode要和標(biāo)注格式匹配COCO格式用XYXY_ABSYOLO格式用XYWH_ABS并做歸一化轉(zhuǎn)換。3.4 訓(xùn)練啟動(dòng)與參數(shù)覆蓋配置文件和數(shù)據(jù)集都準(zhǔn)備好之后就可以啟動(dòng)訓(xùn)練了。detectron2提供了tools/train_net.py腳本但更靈活的方式是自己寫(xiě)一個(gè)訓(xùn)練入口from detectron2.engine import DefaultTrainer from detectron2.config import get_cfg from detectron2 import model_zoo cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file(COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml)) cfg.DATASETS.TRAIN (my_dataset_train,) cfg.DATASETS.TEST (my_dataset_val,) cfg.DATALOADER.NUM_WORKERS 4 cfg.MODEL.WEIGHTS model_zoo.get_checkpoint_url(COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml) cfg.SOLVER.IMS_PER_BATCH 4 cfg.SOLVER.BASE_LR 0.001 cfg.SOLVER.MAX_ITER 10000 cfg.SOLVER.STEPS (7000, 9000) cfg.MODEL.ROI_HEADS.NUM_CLASSES 3 cfg.OUTPUT_DIR ./output os.makedirs(cfg.OUTPUT_DIR, exist_okTrue) trainer DefaultTrainer(cfg) trainer.resume_or_load(resumeFalse) trainer.train()命令行覆蓋參數(shù)的方式python train.py SOLVER.BASE_LR 0.002 SOLVER.MAX_ITER 20000這種覆蓋機(jī)制在做超參數(shù)搜索時(shí)特別方便不需要改文件就能跑不同配置。4. 完整實(shí)操流程與關(guān)鍵環(huán)節(jié)實(shí)現(xiàn)4.1 從原始數(shù)據(jù)到COCO格式的轉(zhuǎn)換大部分標(biāo)注工具LabelImg、CVAT、Labelme導(dǎo)出的格式都不是COCO。以LabelImg的XML為例轉(zhuǎn)換腳本如下import os import json import xml.etree.ElementTree as ET from PIL import Image def xml_to_coco(anno_dir, img_dir, output_json): coco { images: [], annotations: [], categories: [] } class_names [defect_a, defect_b, defect_c] for i, name in enumerate(class_names): coco[categories].append({id: i, name: name}) anno_id 0 for img_id, xml_file in enumerate(os.listdir(anno_dir)): if not xml_file.endswith(.xml): continue tree ET.parse(os.path.join(anno_dir, xml_file)) root tree.getroot() img_name xml_file.replace(.xml, .jpg) img_path os.path.join(img_dir, img_name) img Image.open(img_path) width, height img.size coco[images].append({ id: img_id, file_name: img_name, width: width, height: height }) for obj in root.findall(object): cls_name obj.find(name).text if cls_name not in class_names: continue bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) coco[annotations].append({ id: anno_id, image_id: img_id, category_id: class_names.index(cls_name), bbox: [xmin, ymin, xmax - xmin, ymax - ymin], area: (xmax - xmin) * (ymax - ymin), iscrowd: 0 }) anno_id 1 with open(output_json, w) as f: json.dump(coco, f)提示COCO的bbox格式是[x, y, width, height]不是[xmin, ymin, xmax, ymax]。這個(gè)轉(zhuǎn)換很容易搞錯(cuò)搞錯(cuò)了訓(xùn)練時(shí)loss會(huì)異常大或者直接不收斂。4.2 訓(xùn)練過(guò)程中的監(jiān)控與日志解讀detectron2默認(rèn)用TensorBoard記錄訓(xùn)練日志。啟動(dòng)TensorBoardtensorboard --logdir output/重點(diǎn)看幾個(gè)指標(biāo)total_loss總體損失應(yīng)該穩(wěn)步下降。如果震蕩劇烈可能是學(xué)習(xí)率太大。loss_cls分類(lèi)損失。如果一直不降可能是類(lèi)別不平衡或者標(biāo)注有問(wèn)題。loss_box_reg邊界框回歸損失。如果突然飆升可能是某些標(biāo)注框坐標(biāo)異常。lr學(xué)習(xí)率。確認(rèn)衰減策略是否按預(yù)期執(zhí)行。日志里還會(huì)定期打印評(píng)估結(jié)果包括AP、AP50、AP75等指標(biāo)。AP50是IoU閾值為0.5時(shí)的平均精度通常是最先看到明顯提升的指標(biāo)。AP是IoU從0.5到0.95的平均值更能反映模型在不同定位精度下的綜合表現(xiàn)。我一般會(huì)關(guān)注AP50和APs小目標(biāo)AP。如果AP50高但APs很低說(shuō)明模型對(duì)小目標(biāo)檢測(cè)能力不足可能需要調(diào)整FPN層或者增加高分辨率特征圖。4.3 推理與可視化訓(xùn)練完成后用DefaultPredictor做推理from detectron2.engine import DefaultPredictor from detectron2.config import get_cfg from detectron2 import model_zoo import cv2 cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file(COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml)) cfg.MODEL.WEIGHTS ./output/model_final.pth cfg.MODEL.ROI_HEADS.NUM_CLASSES 3 cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5 cfg.MODEL.DEVICE cuda predictor DefaultPredictor(cfg) img cv2.imread(test.jpg) outputs predictor(img) instances outputs[instances] boxes instances.pred_boxes.tensor.cpu().numpy() scores instances.scores.cpu().numpy() classes instances.pred_classes.cpu().numpy() for box, score, cls in zip(boxes, scores, classes): print(f類(lèi)別: {cls}, 置信度: {score:.3f}, 框: {box})可視化可以用Visualizerfrom detectron2.utils.visualizer import Visualizer from detectron2.data import MetadataCatalog v Visualizer(img[:, :, ::-1], MetadataCatalog.get(my_dataset_train), scale1.2) v v.draw_instance_predictions(outputs[instances].to(cpu)) cv2.imwrite(result.jpg, v.get_image()[:, :, ::-1])注意SCORE_THRESH_TEST是推理時(shí)的置信度閾值。設(shè)太低會(huì)出很多誤檢設(shè)太高會(huì)漏檢。工業(yè)質(zhì)檢場(chǎng)景通常設(shè)0.7以上通用檢測(cè)場(chǎng)景0.5左右比較合適。4.4 模型導(dǎo)出與部署準(zhǔn)備訓(xùn)練好的模型如果要部署到生產(chǎn)環(huán)境通常需要導(dǎo)出成TorchScript格式from detectron2.export import export_torchscript model predictor.model model.eval() torchscript_model export_torchscript(model, (img_tensor,)) torch.jit.save(torchscript_model, model.ts)導(dǎo)出時(shí)要注意輸入尺寸固定。如果訓(xùn)練時(shí)用了多尺度導(dǎo)出時(shí)需要指定一個(gè)固定尺寸比如(800, 1333)。另外TorchScript對(duì)某些自定義算子支持不好如果模型里用了非標(biāo)準(zhǔn)操作導(dǎo)出可能會(huì)失敗。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 訓(xùn)練不收斂的典型原因訓(xùn)練不收斂是最常見(jiàn)的問(wèn)題表現(xiàn)是loss震蕩或者一直很高。根據(jù)我的經(jīng)驗(yàn)原因通常集中在以下幾個(gè)方面現(xiàn)象可能原因排查方法解決方案loss劇烈震蕩學(xué)習(xí)率太大看lr曲線和loss曲線的關(guān)系降低BASE_LR從0.001降到0.0005loss一直不降標(biāo)注格式錯(cuò)誤可視化幾個(gè)batch的標(biāo)注框檢查bbox_mode和坐標(biāo)范圍loss先降后升過(guò)擬合對(duì)比訓(xùn)練集和驗(yàn)證集AP增加數(shù)據(jù)增強(qiáng)加weight decayloss為NaN梯度爆炸看是否有異常大的loss值加梯度裁剪降低學(xué)習(xí)率分類(lèi)loss不降類(lèi)別不平衡統(tǒng)計(jì)各類(lèi)別樣本數(shù)用focal loss或重采樣我遇到過(guò)一次特別隱蔽的問(wèn)題標(biāo)注文件里有個(gè)框的坐標(biāo)是負(fù)數(shù)導(dǎo)致ROI Align計(jì)算出錯(cuò)loss直接變NaN。排查了半天才發(fā)現(xiàn)是標(biāo)注工具導(dǎo)出的問(wèn)題。所以訓(xùn)練前一定要做數(shù)據(jù)清洗檢查所有框的坐標(biāo)是否在圖像范圍內(nèi)寬高是否大于0。5.2 顯存不足的優(yōu)化策略顯存不足是另一個(gè)高頻問(wèn)題。detectron2的顯存占用主要來(lái)自三個(gè)方面模型參數(shù)、特征圖、ROI特征。優(yōu)化手段按優(yōu)先級(jí)排列減小batch sizeSOLVER.IMS_PER_BATCH從4降到2顯存占用幾乎減半。減小輸入尺寸INPUT.MIN_SIZE_TRAIN從800降到640特征圖面積減少36%。減少ROI數(shù)量MODEL.ROI_HEADS.BATCH_SIZE_PER_IMAGE從512降到256。用混合精度訓(xùn)練SOLVER.AMP.ENABLED True顯存占用減少約30%。凍結(jié)backboneMODEL.BACKBONE.FREEZE_AT 2只訓(xùn)練后面的層。提示混合精度訓(xùn)練在PyTorch 1.6以上支持較好但某些自定義算子可能不兼容。開(kāi)啟后如果loss出現(xiàn)NaN先關(guān)掉試試。5.3 評(píng)估指標(biāo)異常的排查思路評(píng)估時(shí)如果AP異常低不要急著改模型先檢查評(píng)估流程本身類(lèi)別ID是否從0開(kāi)始COCO的類(lèi)別ID從1開(kāi)始但detectron2內(nèi)部從0開(kāi)始。如果注冊(cè)時(shí)沒(méi)做轉(zhuǎn)換評(píng)估時(shí)所有預(yù)測(cè)都會(huì)被當(dāng)成背景。驗(yàn)證集是否注冊(cè)正確DATASETS.TEST里的名稱(chēng)必須和注冊(cè)時(shí)的名稱(chēng)完全一致。標(biāo)注框是否被正確加載用DatasetCatalog.get(my_dataset_val)打印幾條數(shù)據(jù)確認(rèn)annotations字段不為空。NMS閾值是否合理MODEL.ROI_HEADS.NMS_THRESH_TEST默認(rèn)0.5如果設(shè)得太低重疊目標(biāo)會(huì)被誤刪。我踩過(guò)的一個(gè)坑是驗(yàn)證集的圖片路徑寫(xiě)錯(cuò)了導(dǎo)致加載不到圖片評(píng)估時(shí)所有預(yù)測(cè)都是空的AP直接為0。后來(lái)加了一個(gè)檢查在注冊(cè)數(shù)據(jù)集后打印前幾條數(shù)據(jù)的file_name確認(rèn)路徑存在。5.4 推理速度優(yōu)化的實(shí)戰(zhàn)技巧如果模型要部署到實(shí)時(shí)場(chǎng)景推理速度很關(guān)鍵。除了換輕量backbone還有幾個(gè)實(shí)用技巧降低輸入分辨率從1333降到800推理速度提升約2倍精度損失通常在2-3個(gè)點(diǎn)以?xún)?nèi)。減少ROI數(shù)量推理時(shí)MODEL.ROI_HEADS.DETECTIONS_PER_IMAGE從100降到30后處理時(shí)間大幅減少。用TensorRT加速把模型轉(zhuǎn)成TensorRT引擎推理速度能再提升2-3倍但轉(zhuǎn)換過(guò)程比較折騰。批處理推理如果有多路視頻流攢幾幀一起推理GPU利用率更高。實(shí)測(cè)數(shù)據(jù)Faster R-CNN R50在V100上輸入800x1333單張推理約45ms輸入640x1067約28ms轉(zhuǎn)TensorRT后約15ms。精度方面AP50從0.82降到0.79再降到0.77。這個(gè)精度換速度的取舍要根據(jù)實(shí)際業(yè)務(wù)需求來(lái)定。5.5 微調(diào)預(yù)訓(xùn)練模型的注意事項(xiàng)微調(diào)預(yù)訓(xùn)練模型時(shí)有幾個(gè)細(xì)節(jié)容易忽略學(xué)習(xí)率要調(diào)小從頭訓(xùn)練用0.01微調(diào)通常用0.001甚至0.0001。因?yàn)轭A(yù)訓(xùn)練權(quán)重已經(jīng)在一個(gè)大分布上收斂了大學(xué)習(xí)率會(huì)破壞已有的特征。凍結(jié)底層MODEL.BACKBONE.FREEZE_AT 2表示凍結(jié)前兩個(gè)stage只訓(xùn)練后面的。小數(shù)據(jù)集微調(diào)時(shí)特別有用能防止過(guò)擬合。類(lèi)別數(shù)要匹配MODEL.ROI_HEADS.NUM_CLASSES必須改成你的類(lèi)別數(shù)。如果忘了改加載權(quán)重時(shí)會(huì)報(bào)維度不匹配。權(quán)重加載策略trainer.resume_or_load(resumeFalse)會(huì)加載MODEL.WEIGHTS指定的權(quán)重。如果OUTPUT_DIR里有上次訓(xùn)練的checkpointresumeTrue會(huì)接著上次訓(xùn)練。我個(gè)人的習(xí)慣是先用小學(xué)習(xí)率微調(diào)全部層跑2000次迭代看效果如果過(guò)擬合明顯再凍結(jié)底層重新跑。這個(gè)策略在多個(gè)項(xiàng)目里都比較穩(wěn)。6. 從項(xiàng)目實(shí)戰(zhàn)中沉淀的經(jīng)驗(yàn)6.1 數(shù)據(jù)質(zhì)量比模型選擇更重要做了這么多檢測(cè)項(xiàng)目我最大的體會(huì)是數(shù)據(jù)質(zhì)量決定上限模型選擇只是逼近上限。一個(gè)標(biāo)注干凈、覆蓋全面的數(shù)據(jù)集用R50就能跑出很好的效果標(biāo)注混亂、漏標(biāo)嚴(yán)重的數(shù)據(jù)集換再大的模型也救不回來(lái)。具體來(lái)說(shuō)標(biāo)注要保證三點(diǎn)框要貼緊目標(biāo)邊緣不要留太多背景、類(lèi)別定義要清晰避免模棱兩可的標(biāo)注、難例要覆蓋遮擋、截?cái)?、小目?biāo)都要有樣本。我通常會(huì)在訓(xùn)練前隨機(jī)抽100張圖人工檢查標(biāo)注質(zhì)量發(fā)現(xiàn)問(wèn)題就返工。這個(gè)時(shí)間投入絕對(duì)值得。6.2 配置文件版本管理detectron2的配置文件是實(shí)驗(yàn)的核心資產(chǎn)。我的做法是每個(gè)實(shí)驗(yàn)一個(gè)獨(dú)立的YAML文件命名規(guī)則是日期_模型_數(shù)據(jù)集_關(guān)鍵參數(shù).yaml比如20240115_r50_mydata_lr001.yaml。所有配置文件用git管理每次訓(xùn)練前commit一次。這樣半年后回頭看能清楚知道每個(gè)結(jié)果是怎么來(lái)的。另外訓(xùn)練腳本里把關(guān)鍵配置打印到日志里包括學(xué)習(xí)率、batch size、迭代次數(shù)、數(shù)據(jù)集路徑。這樣即使配置文件丟了從日志里也能恢復(fù)出當(dāng)時(shí)的配置。6.3 小數(shù)據(jù)集上的實(shí)用技巧如果數(shù)據(jù)集只有幾百?gòu)垐D直接微調(diào)可能會(huì)過(guò)擬合。幾個(gè)實(shí)用技巧強(qiáng)增強(qiáng)隨機(jī)裁剪、旋轉(zhuǎn)、顏色抖動(dòng)全開(kāi)甚至可以用CutMix、Mosaic。多尺度訓(xùn)練INPUT.MIN_SIZE_TRAIN設(shè)一個(gè)范圍比如(640, 800, 1000)讓模型見(jiàn)到不同尺度的目標(biāo)。早停驗(yàn)證集AP連續(xù)幾次不提升就停不要死磕MAX_ITER。交叉驗(yàn)證如果數(shù)據(jù)量實(shí)在少用5折交叉驗(yàn)證取平均結(jié)果更可靠。我在一個(gè)只有300張圖的缺陷檢測(cè)項(xiàng)目里用R50微調(diào)加強(qiáng)增強(qiáng)最終AP50到了0.78。如果從頭訓(xùn)練AP50只有0.52。預(yù)訓(xùn)練權(quán)重的價(jià)值在小數(shù)據(jù)集上體現(xiàn)得淋漓盡致。6.4 后續(xù)擴(kuò)展方向detectron2的生態(tài)還在持續(xù)演進(jìn)。如果你已經(jīng)跑通了基礎(chǔ)流程可以考慮幾個(gè)擴(kuò)展方向自定義backbone比如換成EfficientNet或Swin Transformer、自定義數(shù)據(jù)增強(qiáng)針對(duì)特定場(chǎng)景設(shè)計(jì)增強(qiáng)策略、模型蒸餾用大模型教小模型兼顧精度和速度、半監(jiān)督訓(xùn)練利用未標(biāo)注數(shù)據(jù)提升效果。這些方向每一個(gè)都?jí)驅(qū)懸黄L(zhǎng)文但核心思路是一致的理解框架的擴(kuò)展點(diǎn)在合適的位置插入自己的邏輯。detectron2的模塊化設(shè)計(jì)讓這些擴(kuò)展變得相對(duì)容易這也是它比很多“一體化”框架更值得深入的原因。 Detectron2實(shí)戰(zhàn)指南：從配置驅(qū)動(dòng)到模型部署的完整流程
1. 為什么值得花時(shí)間搞懂 detectron2如果你正在做計(jì)算機(jī)視覺(jué)相關(guān)的項(xiàng)目尤其是目標(biāo)檢測(cè)、實(shí)例分割、關(guān)鍵點(diǎn)檢測(cè)這類(lèi)任務(wù)大概率會(huì)碰到detectron2這個(gè)名字。它是某知名AI研究機(jī)構(gòu)開(kāi)源的一個(gè)目標(biāo)檢測(cè)與分割框架基于PyTorch構(gòu)建把大量經(jīng)典和前沿的檢測(cè)、分割模型整合到了一套統(tǒng)一的代碼體系里。簡(jiǎn)單說(shuō)它解決的核心問(wèn)題是讓你不用從零實(shí)現(xiàn)Faster R-CNN、Mask R-CNN、RetinaNet這些模型的訓(xùn)練和推理流程直接調(diào)用現(xiàn)成的、經(jīng)過(guò)驗(yàn)證的實(shí)現(xiàn)就能跑起來(lái)。我第一次接觸它是因?yàn)橐粋€(gè)工業(yè)質(zhì)檢的項(xiàng)目需要在產(chǎn)線圖片里定位缺陷區(qū)域并做像素級(jí)分割。當(dāng)時(shí)試過(guò)自己搭Mask R-CNN光是把ROI Align、RPN、多尺度訓(xùn)練這些環(huán)節(jié)調(diào)通就花了兩周效果還不穩(wěn)定。后來(lái)?yè)Q到detectron2同樣的數(shù)據(jù)集配置改一改兩天就跑出了可用的baseline。這個(gè)效率差距就是它最大的價(jià)值。這篇文章適合誰(shuí)看如果你是剛?cè)腴T(mén)目標(biāo)檢測(cè)的學(xué)生、需要快速驗(yàn)證算法的工程師、或者想找一個(gè)穩(wěn)定訓(xùn)練框架的研究者那這篇內(nèi)容能幫你少走很多彎路。我會(huì)從整體設(shè)計(jì)思路講起然后拆解核心配置項(xiàng)再給出一套完整的實(shí)操流程最后把我在實(shí)際項(xiàng)目中踩過(guò)的坑整理成排查清單。全程不堆術(shù)語(yǔ)盡量用“人話”把每個(gè)選擇背后的原因講清楚。2. 整體設(shè)計(jì)思路與方案選型考量2.1 為什么是“配置驅(qū)動(dòng)”而不是“代碼驅(qū)動(dòng)”detectron2最核心的設(shè)計(jì)哲學(xué)是配置驅(qū)動(dòng)config-driven。你幾乎不需要改Python代碼只需要寫(xiě)一個(gè)YAML配置文件就能定義模型結(jié)構(gòu)、數(shù)據(jù)集路徑、訓(xùn)練超參數(shù)、數(shù)據(jù)增強(qiáng)策略等所有內(nèi)容。這個(gè)選擇背后有很實(shí)際的考量。傳統(tǒng)做法是每個(gè)項(xiàng)目復(fù)制一份訓(xùn)練腳本然后在代碼里改參數(shù)。問(wèn)題是當(dāng)你同時(shí)跑十幾個(gè)實(shí)驗(yàn)對(duì)比不同backbone、不同學(xué)習(xí)率、不同增強(qiáng)策略時(shí)代碼分支會(huì)變得極其混亂。detectron2把配置抽出來(lái)之后實(shí)驗(yàn)管理變得非常清晰一個(gè)實(shí)驗(yàn)一個(gè)YAML文件配合命令行覆蓋參數(shù)可以快速做消融研究。它的配置系統(tǒng)基于一個(gè)叫LazyConfig和CfgNode的機(jī)制。早期版本主要用CfgNode類(lèi)似字典的層級(jí)結(jié)構(gòu)支持從文件加載和命令行覆蓋。新版本引入了LazyConfig用Python文件做配置靈活性更高但對(duì)新手來(lái)說(shuō)門(mén)檻也稍高一些。我的建議是新手從CfgNode的YAML配置入手熟悉之后再考慮LazyConfig。注意detectron2的配置項(xiàng)非常多但真正需要你手動(dòng)調(diào)的其實(shí)就那么十幾個(gè)。不要被配置文件里密密麻麻的鍵值嚇到大部分保持默認(rèn)就行。2.2 模型 zoo 的設(shè)計(jì)邏輯detectron2內(nèi)置了一個(gè)Model Zoo提供了大量預(yù)訓(xùn)練模型。這些模型按照任務(wù)類(lèi)型和backbone結(jié)構(gòu)組織比如COCO-Detection下面是目標(biāo)檢測(cè)模型COCO-InstanceSegmentation下面是實(shí)例分割模型COCO-Keypoints是關(guān)鍵點(diǎn)檢測(cè)。這個(gè)設(shè)計(jì)的好處是你可以直接加載預(yù)訓(xùn)練權(quán)重做微調(diào)而不需要從頭訓(xùn)練。對(duì)于小數(shù)據(jù)集項(xiàng)目微調(diào)預(yù)訓(xùn)練模型通常比從頭訓(xùn)練效果好得多收斂也快得多。我做過(guò)對(duì)比同樣一個(gè)5000張圖的缺陷檢測(cè)數(shù)據(jù)集從頭訓(xùn)練mAP只能到0.45左右加載COCO預(yù)訓(xùn)練權(quán)重微調(diào)能到0.72。選擇哪個(gè)預(yù)訓(xùn)練模型主要看三個(gè)因素任務(wù)類(lèi)型、精度要求、推理速度要求。R50ResNet-50 backbone是速度和精度的平衡點(diǎn)R101精度更高但慢一些X101是更深的網(wǎng)絡(luò)適合精度優(yōu)先的場(chǎng)景。如果部署在邊緣設(shè)備上可以考慮MobileNet backbone的輕量模型。2.3 數(shù)據(jù)加載與增強(qiáng)的流水線設(shè)計(jì)detectron2的數(shù)據(jù)加載用了DatasetCatalog和MetadataCatalog兩個(gè)注冊(cè)表。你需要把數(shù)據(jù)集注冊(cè)進(jìn)去框架才能識(shí)別。這個(gè)設(shè)計(jì)看起來(lái)多了一步但實(shí)際上很合理它把數(shù)據(jù)集的“物理位置”和“邏輯名稱(chēng)”解耦了方便切換不同數(shù)據(jù)集做實(shí)驗(yàn)。數(shù)據(jù)增強(qiáng)方面detectron2內(nèi)置了一套基于AugmentationList的增強(qiáng)流水線。常用的增強(qiáng)包括隨機(jī)翻轉(zhuǎn)、隨機(jī)裁剪、顏色抖動(dòng)、亮度對(duì)比度調(diào)整等。它的增強(qiáng)是在線進(jìn)行的每個(gè)epoch的增強(qiáng)結(jié)果都不同能有效提升模型泛化能力。這里有個(gè)容易忽略的點(diǎn)增強(qiáng)策略要和任務(wù)匹配。比如做文本檢測(cè)時(shí)隨機(jī)旋轉(zhuǎn)可能會(huì)破壞文字的可讀性做工業(yè)缺陷檢測(cè)時(shí)顏色抖動(dòng)可能改變?nèi)毕莸囊曈X(jué)特征。我見(jiàn)過(guò)有人直接套用COCO的增強(qiáng)配置做工業(yè)項(xiàng)目結(jié)果模型把顏色變化當(dāng)成了缺陷特征換一批光照條件就完全失效。3. 核心配置項(xiàng)深度拆解與實(shí)操要點(diǎn)3.1 環(huán)境搭建從零到能跑通第一個(gè)Demo環(huán)境搭建是第一步也是最容易卡住的地方。detectron2對(duì)PyTorch版本、CUDA版本、編譯器版本都有要求版本不匹配會(huì)報(bào)各種奇怪的錯(cuò)誤。我的建議是用conda創(chuàng)建獨(dú)立環(huán)境不要污染系統(tǒng)Python。步驟如下conda create -n detectron2 python3.9 conda activate detectron2然后安裝PyTorch。這里要注意detectron2需要PyTorch 1.8以上但不同版本對(duì)CUDA的支持不同。如果你用的是CUDA 11.3可以這樣裝pip install torch1.10.0cu113 torchvision0.11.0cu113 -f https://download.pytorch.org/whl/torch_stable.html接下來(lái)安裝detectron2本體。有兩種方式pip安裝和源碼編譯。pip安裝簡(jiǎn)單但可能遇到版本兼容問(wèn)題源碼編譯更可控但需要gcc和g支持。# 方式一pip安裝 pip install detectron2 -f https://dl.fbaipublicfiles.com/detectron2/wheels/cu113/torch1.10/index.html # 方式二源碼編譯 git clone https://github.com/facebookresearch/detectron2.git cd detectron2 pip install -e .提示源碼編譯時(shí)如果報(bào)“nvcc not found”說(shuō)明CUDA編譯器沒(méi)裝好需要先安裝對(duì)應(yīng)版本的CUDA Toolkit。如果報(bào)“gcc version too old”需要升級(jí)gcc到7.5以上。驗(yàn)證安裝是否成功import detectron2 print(detectron2.__version__)能打印出版本號(hào)就說(shuō)明基礎(chǔ)環(huán)境OK了。如果報(bào)“ImportError: libcudart.so.11.0: cannot open shared object file”說(shuō)明CUDA路徑?jīng)]配好需要把CUDA的lib目錄加到LD_LIBRARY_PATH里。3.2 配置文件的核心結(jié)構(gòu)一個(gè)典型的detectron2配置文件包含以下幾個(gè)大塊MODEL: META_ARCHITECTURE: GeneralizedRCNN BACKBONE: NAME: build_resnet_fpn_backbone RESNETS: DEPTH: 50 FPN: IN_FEATURES: [res2, res3, res4, res5] ROI_HEADS: NUM_CLASSES: 3 WEIGHTS: detectron2://COCO-Detection/faster_rcnn_R_50_FPN_3x/137849458/model_final_280758.pkl DATASETS: TRAIN: (my_dataset_train,) TEST: (my_dataset_val,) SOLVER: BASE_LR: 0.001 MAX_ITER: 10000 BATCH_SIZE_PER_IMAGE: 64 STEPS: (7000, 9000) INPUT: MIN_SIZE_TRAIN: (640, 800) MAX_SIZE_TRAIN: 1333 MIN_SIZE_TEST: 800 MAX_SIZE_TEST: 1333MODEL.META_ARCHITECTURE決定用哪個(gè)模型架構(gòu)。目標(biāo)檢測(cè)用GeneralizedRCNN實(shí)例分割也用這個(gè)但需要加mask head關(guān)鍵點(diǎn)檢測(cè)用GeneralizedRCNN加keypoint head。MODEL.WEIGHTS指定預(yù)訓(xùn)練權(quán)重路徑。可以是本地文件路徑也可以是Model Zoo的URL。加載預(yù)訓(xùn)練權(quán)重時(shí)如果類(lèi)別數(shù)不匹配比如COCO是80類(lèi)你的數(shù)據(jù)集是3類(lèi)框架會(huì)自動(dòng)跳過(guò)分類(lèi)層的權(quán)重只加載backbone和RPN的權(quán)重。SOLVER.BASE_LR是基礎(chǔ)學(xué)習(xí)率。這個(gè)值很關(guān)鍵太大容易震蕩太小收斂慢。經(jīng)驗(yàn)值是batch size為2時(shí)用0.001batch size為8時(shí)用0.005batch size為16時(shí)用0.01。如果你不確定從0.001開(kāi)始試。SOLVER.STEPS是學(xué)習(xí)率衰減的迭代次數(shù)。比如(7000, 9000)表示在第7000次和第9000次迭代時(shí)把學(xué)習(xí)率乘以0.1。通常設(shè)置在總迭代次數(shù)的70%和90%位置。INPUT.MIN_SIZE_TRAIN是訓(xùn)練時(shí)的圖像短邊縮放范圍。多尺度訓(xùn)練能提升模型對(duì)不同尺寸目標(biāo)的適應(yīng)能力但會(huì)增加顯存占用。如果顯存不夠可以固定一個(gè)值比如(800,)。3.3 數(shù)據(jù)集注冊(cè)的完整流程detectron2不能直接讀文件夾里的圖片必須先把數(shù)據(jù)集注冊(cè)到DatasetCatalog。注冊(cè)的核心是提供一個(gè)函數(shù)返回一個(gè)列表每個(gè)元素是一個(gè)字典包含file_name、image_id、annotations等字段。以COCO格式的數(shù)據(jù)集為例from detectron2.data.datasets import register_coco_instances register_coco_instances( my_dataset_train, {}, annotations/train.json, images/train ) register_coco_instances( my_dataset_val, {}, annotations/val.json, images/val )如果是自定義格式比如每張圖對(duì)應(yīng)一個(gè)XML標(biāo)注文件就需要自己寫(xiě)注冊(cè)函數(shù)from detectron2.data import DatasetCatalog, MetadataCatalog import os import xml.etree.ElementTree as ET def get_my_dataset_dicts(img_dir, anno_dir): dataset_dicts [] for idx, img_name in enumerate(os.listdir(img_dir)): record {} record[file_name] os.path.join(img_dir, img_name) record[image_id] idx record[height] 640 record[width] 640 anno_path os.path.join(anno_dir, img_name.replace(.jpg, .xml)) tree ET.parse(anno_path) objs [] for obj in tree.findall(object): bbox obj.find(bndbox) objs.append({ bbox: [ float(bbox.find(xmin).text), float(bbox.find(ymin).text), float(bbox.find(xmax).text), float(bbox.find(ymax).text) ], bbox_mode: BoxMode.XYXY_ABS, category_id: class_names.index(obj.find(name).text) }) record[annotations] objs dataset_dicts.append(record) return dataset_dicts DatasetCatalog.register(my_dataset_train, lambda: get_my_dataset_dicts(images/train, annotations/train)) MetadataCatalog.get(my_dataset_train).set(thing_classes[defect_a, defect_b, defect_c])注意image_id必須是唯一的整數(shù)。如果重復(fù)評(píng)估時(shí)會(huì)出錯(cuò)。bbox_mode要和標(biāo)注格式匹配COCO格式用XYXY_ABSYOLO格式用XYWH_ABS并做歸一化轉(zhuǎn)換。3.4 訓(xùn)練啟動(dòng)與參數(shù)覆蓋配置文件和數(shù)據(jù)集都準(zhǔn)備好之后就可以啟動(dòng)訓(xùn)練了。detectron2提供了tools/train_net.py腳本但更靈活的方式是自己寫(xiě)一個(gè)訓(xùn)練入口from detectron2.engine import DefaultTrainer from detectron2.config import get_cfg from detectron2 import model_zoo cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file(COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml)) cfg.DATASETS.TRAIN (my_dataset_train,) cfg.DATASETS.TEST (my_dataset_val,) cfg.DATALOADER.NUM_WORKERS 4 cfg.MODEL.WEIGHTS model_zoo.get_checkpoint_url(COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml) cfg.SOLVER.IMS_PER_BATCH 4 cfg.SOLVER.BASE_LR 0.001 cfg.SOLVER.MAX_ITER 10000 cfg.SOLVER.STEPS (7000, 9000) cfg.MODEL.ROI_HEADS.NUM_CLASSES 3 cfg.OUTPUT_DIR ./output os.makedirs(cfg.OUTPUT_DIR, exist_okTrue) trainer DefaultTrainer(cfg) trainer.resume_or_load(resumeFalse) trainer.train()命令行覆蓋參數(shù)的方式python train.py SOLVER.BASE_LR 0.002 SOLVER.MAX_ITER 20000這種覆蓋機(jī)制在做超參數(shù)搜索時(shí)特別方便不需要改文件就能跑不同配置。4. 完整實(shí)操流程與關(guān)鍵環(huán)節(jié)實(shí)現(xiàn)4.1 從原始數(shù)據(jù)到COCO格式的轉(zhuǎn)換大部分標(biāo)注工具LabelImg、CVAT、Labelme導(dǎo)出的格式都不是COCO。以LabelImg的XML為例轉(zhuǎn)換腳本如下import os import json import xml.etree.ElementTree as ET from PIL import Image def xml_to_coco(anno_dir, img_dir, output_json): coco { images: [], annotations: [], categories: [] } class_names [defect_a, defect_b, defect_c] for i, name in enumerate(class_names): coco[categories].append({id: i, name: name}) anno_id 0 for img_id, xml_file in enumerate(os.listdir(anno_dir)): if not xml_file.endswith(.xml): continue tree ET.parse(os.path.join(anno_dir, xml_file)) root tree.getroot() img_name xml_file.replace(.xml, .jpg) img_path os.path.join(img_dir, img_name) img Image.open(img_path) width, height img.size coco[images].append({ id: img_id, file_name: img_name, width: width, height: height }) for obj in root.findall(object): cls_name obj.find(name).text if cls_name not in class_names: continue bbox obj.find(bndbox) xmin float(bbox.find(xmin).text) ymin float(bbox.find(ymin).text) xmax float(bbox.find(xmax).text) ymax float(bbox.find(ymax).text) coco[annotations].append({ id: anno_id, image_id: img_id, category_id: class_names.index(cls_name), bbox: [xmin, ymin, xmax - xmin, ymax - ymin], area: (xmax - xmin) * (ymax - ymin), iscrowd: 0 }) anno_id 1 with open(output_json, w) as f: json.dump(coco, f)提示COCO的bbox格式是[x, y, width, height]不是[xmin, ymin, xmax, ymax]。這個(gè)轉(zhuǎn)換很容易搞錯(cuò)搞錯(cuò)了訓(xùn)練時(shí)loss會(huì)異常大或者直接不收斂。4.2 訓(xùn)練過(guò)程中的監(jiān)控與日志解讀detectron2默認(rèn)用TensorBoard記錄訓(xùn)練日志。啟動(dòng)TensorBoardtensorboard --logdir output/重點(diǎn)看幾個(gè)指標(biāo)total_loss總體損失應(yīng)該穩(wěn)步下降。如果震蕩劇烈可能是學(xué)習(xí)率太大。loss_cls分類(lèi)損失。如果一直不降可能是類(lèi)別不平衡或者標(biāo)注有問(wèn)題。loss_box_reg邊界框回歸損失。如果突然飆升可能是某些標(biāo)注框坐標(biāo)異常。lr學(xué)習(xí)率。確認(rèn)衰減策略是否按預(yù)期執(zhí)行。日志里還會(huì)定期打印評(píng)估結(jié)果包括AP、AP50、AP75等指標(biāo)。AP50是IoU閾值為0.5時(shí)的平均精度通常是最先看到明顯提升的指標(biāo)。AP是IoU從0.5到0.95的平均值更能反映模型在不同定位精度下的綜合表現(xiàn)。我一般會(huì)關(guān)注AP50和APs小目標(biāo)AP。如果AP50高但APs很低說(shuō)明模型對(duì)小目標(biāo)檢測(cè)能力不足可能需要調(diào)整FPN層或者增加高分辨率特征圖。4.3 推理與可視化訓(xùn)練完成后用DefaultPredictor做推理from detectron2.engine import DefaultPredictor from detectron2.config import get_cfg from detectron2 import model_zoo import cv2 cfg get_cfg() cfg.merge_from_file(model_zoo.get_config_file(COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml)) cfg.MODEL.WEIGHTS ./output/model_final.pth cfg.MODEL.ROI_HEADS.NUM_CLASSES 3 cfg.MODEL.ROI_HEADS.SCORE_THRESH_TEST 0.5 cfg.MODEL.DEVICE cuda predictor DefaultPredictor(cfg) img cv2.imread(test.jpg) outputs predictor(img) instances outputs[instances] boxes instances.pred_boxes.tensor.cpu().numpy() scores instances.scores.cpu().numpy() classes instances.pred_classes.cpu().numpy() for box, score, cls in zip(boxes, scores, classes): print(f類(lèi)別: {cls}, 置信度: {score:.3f}, 框: {box})可視化可以用Visualizerfrom detectron2.utils.visualizer import Visualizer from detectron2.data import MetadataCatalog v Visualizer(img[:, :, ::-1], MetadataCatalog.get(my_dataset_train), scale1.2) v v.draw_instance_predictions(outputs[instances].to(cpu)) cv2.imwrite(result.jpg, v.get_image()[:, :, ::-1])注意SCORE_THRESH_TEST是推理時(shí)的置信度閾值。設(shè)太低會(huì)出很多誤檢設(shè)太高會(huì)漏檢。工業(yè)質(zhì)檢場(chǎng)景通常設(shè)0.7以上通用檢測(cè)場(chǎng)景0.5左右比較合適。4.4 模型導(dǎo)出與部署準(zhǔn)備訓(xùn)練好的模型如果要部署到生產(chǎn)環(huán)境通常需要導(dǎo)出成TorchScript格式from detectron2.export import export_torchscript model predictor.model model.eval() torchscript_model export_torchscript(model, (img_tensor,)) torch.jit.save(torchscript_model, model.ts)導(dǎo)出時(shí)要注意輸入尺寸固定。如果訓(xùn)練時(shí)用了多尺度導(dǎo)出時(shí)需要指定一個(gè)固定尺寸比如(800, 1333)。另外TorchScript對(duì)某些自定義算子支持不好如果模型里用了非標(biāo)準(zhǔn)操作導(dǎo)出可能會(huì)失敗。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 訓(xùn)練不收斂的典型原因訓(xùn)練不收斂是最常見(jiàn)的問(wèn)題表現(xiàn)是loss震蕩或者一直很高。根據(jù)我的經(jīng)驗(yàn)原因通常集中在以下幾個(gè)方面現(xiàn)象可能原因排查方法解決方案loss劇烈震蕩學(xué)習(xí)率太大看lr曲線和loss曲線的關(guān)系降低BASE_LR從0.001降到0.0005loss一直不降標(biāo)注格式錯(cuò)誤可視化幾個(gè)batch的標(biāo)注框檢查bbox_mode和坐標(biāo)范圍loss先降后升過(guò)擬合對(duì)比訓(xùn)練集和驗(yàn)證集AP增加數(shù)據(jù)增強(qiáng)加weight decayloss為NaN梯度爆炸看是否有異常大的loss值加梯度裁剪降低學(xué)習(xí)率分類(lèi)loss不降類(lèi)別不平衡統(tǒng)計(jì)各類(lèi)別樣本數(shù)用focal loss或重采樣我遇到過(guò)一次特別隱蔽的問(wèn)題標(biāo)注文件里有個(gè)框的坐標(biāo)是負(fù)數(shù)導(dǎo)致ROI Align計(jì)算出錯(cuò)loss直接變NaN。排查了半天才發(fā)現(xiàn)是標(biāo)注工具導(dǎo)出的問(wèn)題。所以訓(xùn)練前一定要做數(shù)據(jù)清洗檢查所有框的坐標(biāo)是否在圖像范圍內(nèi)寬高是否大于0。5.2 顯存不足的優(yōu)化策略顯存不足是另一個(gè)高頻問(wèn)題。detectron2的顯存占用主要來(lái)自三個(gè)方面模型參數(shù)、特征圖、ROI特征。優(yōu)化手段按優(yōu)先級(jí)排列減小batch sizeSOLVER.IMS_PER_BATCH從4降到2顯存占用幾乎減半。減小輸入尺寸INPUT.MIN_SIZE_TRAIN從800降到640特征圖面積減少36%。減少ROI數(shù)量MODEL.ROI_HEADS.BATCH_SIZE_PER_IMAGE從512降到256。用混合精度訓(xùn)練SOLVER.AMP.ENABLED True顯存占用減少約30%。凍結(jié)backboneMODEL.BACKBONE.FREEZE_AT 2只訓(xùn)練后面的層。提示混合精度訓(xùn)練在PyTorch 1.6以上支持較好但某些自定義算子可能不兼容。開(kāi)啟后如果loss出現(xiàn)NaN先關(guān)掉試試。5.3 評(píng)估指標(biāo)異常的排查思路評(píng)估時(shí)如果AP異常低不要急著改模型先檢查評(píng)估流程本身類(lèi)別ID是否從0開(kāi)始COCO的類(lèi)別ID從1開(kāi)始但detectron2內(nèi)部從0開(kāi)始。如果注冊(cè)時(shí)沒(méi)做轉(zhuǎn)換評(píng)估時(shí)所有預(yù)測(cè)都會(huì)被當(dāng)成背景。驗(yàn)證集是否注冊(cè)正確DATASETS.TEST里的名稱(chēng)必須和注冊(cè)時(shí)的名稱(chēng)完全一致。標(biāo)注框是否被正確加載用DatasetCatalog.get(my_dataset_val)打印幾條數(shù)據(jù)確認(rèn)annotations字段不為空。NMS閾值是否合理MODEL.ROI_HEADS.NMS_THRESH_TEST默認(rèn)0.5如果設(shè)得太低重疊目標(biāo)會(huì)被誤刪。我踩過(guò)的一個(gè)坑是驗(yàn)證集的圖片路徑寫(xiě)錯(cuò)了導(dǎo)致加載不到圖片評(píng)估時(shí)所有預(yù)測(cè)都是空的AP直接為0。后來(lái)加了一個(gè)檢查在注冊(cè)數(shù)據(jù)集后打印前幾條數(shù)據(jù)的file_name確認(rèn)路徑存在。5.4 推理速度優(yōu)化的實(shí)戰(zhàn)技巧如果模型要部署到實(shí)時(shí)場(chǎng)景推理速度很關(guān)鍵。除了換輕量backbone還有幾個(gè)實(shí)用技巧降低輸入分辨率從1333降到800推理速度提升約2倍精度損失通常在2-3個(gè)點(diǎn)以?xún)?nèi)。減少ROI數(shù)量推理時(shí)MODEL.ROI_HEADS.DETECTIONS_PER_IMAGE從100降到30后處理時(shí)間大幅減少。用TensorRT加速把模型轉(zhuǎn)成TensorRT引擎推理速度能再提升2-3倍但轉(zhuǎn)換過(guò)程比較折騰。批處理推理如果有多路視頻流攢幾幀一起推理GPU利用率更高。實(shí)測(cè)數(shù)據(jù)Faster R-CNN R50在V100上輸入800x1333單張推理約45ms輸入640x1067約28ms轉(zhuǎn)TensorRT后約15ms。精度方面AP50從0.82降到0.79再降到0.77。這個(gè)精度換速度的取舍要根據(jù)實(shí)際業(yè)務(wù)需求來(lái)定。5.5 微調(diào)預(yù)訓(xùn)練模型的注意事項(xiàng)微調(diào)預(yù)訓(xùn)練模型時(shí)有幾個(gè)細(xì)節(jié)容易忽略學(xué)習(xí)率要調(diào)小從頭訓(xùn)練用0.01微調(diào)通常用0.001甚至0.0001。因?yàn)轭A(yù)訓(xùn)練權(quán)重已經(jīng)在一個(gè)大分布上收斂了大學(xué)習(xí)率會(huì)破壞已有的特征。凍結(jié)底層MODEL.BACKBONE.FREEZE_AT 2表示凍結(jié)前兩個(gè)stage只訓(xùn)練后面的。小數(shù)據(jù)集微調(diào)時(shí)特別有用能防止過(guò)擬合。類(lèi)別數(shù)要匹配MODEL.ROI_HEADS.NUM_CLASSES必須改成你的類(lèi)別數(shù)。如果忘了改加載權(quán)重時(shí)會(huì)報(bào)維度不匹配。權(quán)重加載策略trainer.resume_or_load(resumeFalse)會(huì)加載MODEL.WEIGHTS指定的權(quán)重。如果OUTPUT_DIR里有上次訓(xùn)練的checkpointresumeTrue會(huì)接著上次訓(xùn)練。我個(gè)人的習(xí)慣是先用小學(xué)習(xí)率微調(diào)全部層跑2000次迭代看效果如果過(guò)擬合明顯再凍結(jié)底層重新跑。這個(gè)策略在多個(gè)項(xiàng)目里都比較穩(wěn)。6. 從項(xiàng)目實(shí)戰(zhàn)中沉淀的經(jīng)驗(yàn)6.1 數(shù)據(jù)質(zhì)量比模型選擇更重要做了這么多檢測(cè)項(xiàng)目我最大的體會(huì)是數(shù)據(jù)質(zhì)量決定上限模型選擇只是逼近上限。一個(gè)標(biāo)注干凈、覆蓋全面的數(shù)據(jù)集用R50就能跑出很好的效果標(biāo)注混亂、漏標(biāo)嚴(yán)重的數(shù)據(jù)集換再大的模型也救不回來(lái)。具體來(lái)說(shuō)標(biāo)注要保證三點(diǎn)框要貼緊目標(biāo)邊緣不要留太多背景、類(lèi)別定義要清晰避免模棱兩可的標(biāo)注、難例要覆蓋遮擋、截?cái)?、小目?biāo)都要有樣本。我通常會(huì)在訓(xùn)練前隨機(jī)抽100張圖人工檢查標(biāo)注質(zhì)量發(fā)現(xiàn)問(wèn)題就返工。這個(gè)時(shí)間投入絕對(duì)值得。6.2 配置文件版本管理detectron2的配置文件是實(shí)驗(yàn)的核心資產(chǎn)。我的做法是每個(gè)實(shí)驗(yàn)一個(gè)獨(dú)立的YAML文件命名規(guī)則是日期_模型_數(shù)據(jù)集_關(guān)鍵參數(shù).yaml比如20240115_r50_mydata_lr001.yaml。所有配置文件用git管理每次訓(xùn)練前commit一次。這樣半年后回頭看能清楚知道每個(gè)結(jié)果是怎么來(lái)的。另外訓(xùn)練腳本里把關(guān)鍵配置打印到日志里包括學(xué)習(xí)率、batch size、迭代次數(shù)、數(shù)據(jù)集路徑。這樣即使配置文件丟了從日志里也能恢復(fù)出當(dāng)時(shí)的配置。6.3 小數(shù)據(jù)集上的實(shí)用技巧如果數(shù)據(jù)集只有幾百?gòu)垐D直接微調(diào)可能會(huì)過(guò)擬合。幾個(gè)實(shí)用技巧強(qiáng)增強(qiáng)隨機(jī)裁剪、旋轉(zhuǎn)、顏色抖動(dòng)全開(kāi)甚至可以用CutMix、Mosaic。多尺度訓(xùn)練INPUT.MIN_SIZE_TRAIN設(shè)一個(gè)范圍比如(640, 800, 1000)讓模型見(jiàn)到不同尺度的目標(biāo)。早停驗(yàn)證集AP連續(xù)幾次不提升就停不要死磕MAX_ITER。交叉驗(yàn)證如果數(shù)據(jù)量實(shí)在少用5折交叉驗(yàn)證取平均結(jié)果更可靠。我在一個(gè)只有300張圖的缺陷檢測(cè)項(xiàng)目里用R50微調(diào)加強(qiáng)增強(qiáng)最終AP50到了0.78。如果從頭訓(xùn)練AP50只有0.52。預(yù)訓(xùn)練權(quán)重的價(jià)值在小數(shù)據(jù)集上體現(xiàn)得淋漓盡致。6.4 后續(xù)擴(kuò)展方向detectron2的生態(tài)還在持續(xù)演進(jìn)。如果你已經(jīng)跑通了基礎(chǔ)流程可以考慮幾個(gè)擴(kuò)展方向自定義backbone比如換成EfficientNet或Swin Transformer、自定義數(shù)據(jù)增強(qiáng)針對(duì)特定場(chǎng)景設(shè)計(jì)增強(qiáng)策略、模型蒸餾用大模型教小模型兼顧精度和速度、半監(jiān)督訓(xùn)練利用未標(biāo)注數(shù)據(jù)提升效果。這些方向每一個(gè)都?jí)驅(qū)懸黄L(zhǎng)文但核心思路是一致的理解框架的擴(kuò)展點(diǎn)在合適的位置插入自己的邏輯。detectron2的模塊化設(shè)計(jì)讓這些擴(kuò)展變得相對(duì)容易這也是它比很多“一體化”框架更值得深入的原因。