絡(luò)架構(gòu)配置詳解：從Backbone、Neck到Head的組裝邏輯)
很多同學(xué)第一次打開 mmDetection 的倉庫都有一種“從入門到放棄”的沖動mmdet/models目錄下躺著backbones、necks、dense_heads、roi_heads一堆文件夾點進configs發(fā)現(xiàn)每份配置文件長得像一棵樹尤其model字段嵌套七八層里面全是dict。我當年第一次看 Faster R-CNN 的配置時腦子里只有一個念頭這玩意兒到底是怎么變成一個能跑的網(wǎng)絡(luò)的這篇筆記想解決的就是這個問題。我會沿著 mmDetection 的網(wǎng)絡(luò)架構(gòu)這條線把model配置里的每個字段掰開揉碎告訴你 backbone、neck、head 各自扮演什么角色它們怎么組合成一個完整的檢測器以及如果你想把某一層換掉、加一個模塊應(yīng)該改哪里、怎么改。適合誰看剛接觸 mmDetection、跑通了官方 demo 但對配置一臉懵的科研小白以及在框架里做過小改動、卻始終沒弄清“為什么這樣寫”的開發(fā)者。1. 先建立整體印象mmDetection 的網(wǎng)絡(luò)分層思想1.1 檢測器不是一個黑盒而是一條流水線目標檢測和圖像分類最大的區(qū)別在于它要同時回答兩個問題物體在哪里定位和物體是什么分類。分類任務(wù)可以干脆利落地拿一個網(wǎng)絡(luò)把圖像映射成類別概率但檢測任務(wù)不行——你既要提取特征又要在特征上做密集的候選框預(yù)測還要對候選框做精修這么多事不可能靠一個單一的“黑盒網(wǎng)絡(luò)”完成。mmDetection 的做法是把這條鏈路拆成幾個職責(zé)清晰的模塊典型結(jié)構(gòu)是Backbone主干網(wǎng)絡(luò)負責(zé)從原始圖像中提取多層次特征。Neck頸部模塊在 backbone 輸出的多尺度特征上做融合或增強最典型的就是 FPN。Head檢測頭在融合后的特征上做最終的分類和回歸預(yù)測。雙階段檢測器還會拆成 RPN Head 和 RoI Head。Detector檢測器外殼把上面這些模塊拼裝起來同時負責(zé)訓(xùn)練和推理流程的編排。這個設(shè)計思路很像工廠里的流水線原料圖像先進第一道工序backbone粗加工再進第二道工序neck做精細處理最后由檢測頭head完成質(zhì)檢和打包。生產(chǎn)線上的每個環(huán)節(jié)都可以獨立替換這也是 mmDetection 能支持幾十種檢測器的根本原因。1.2 你一定會見到的幾個“角色”字段翻看任意一份 mmDetection 配置model字段下常見的關(guān)鍵字就那么幾個model dict( typeFasterRCNN, backbonedict(...), neckdict(...), rpn_headdict(...), roi_headdict(...), )單階段檢測器比如 RetinaNet、YOLO 系列通常只有backbone、neck、bbox_head沒有rpn_head和roi_head因為單階段不需要“先提候選框再精修”這兩步直接在特征圖上做密集預(yù)測。多階段檢測器Faster R-CNN、Mask R-CNN、Cascade R-CNN則多出rpn_head和roi_headRPN 先快速篩出一批可能包含物體的候選框RoI Head 再對這些候選框?qū)?yīng)的特征區(qū)域做精細分類和回歸。這個“粗篩 精修”的思路是雙階段方法在精度上長期優(yōu)于單階段方法的關(guān)鍵原因之一?？吹竭@里你就明白了mmDetection 的model配置不是一個“模型的形狀描述”而是一份組件清單。每個組件都是一個dict里面寫著“我要用什么模塊、參數(shù)是多少”。搞清楚每個組件的參數(shù)含義是理解這份清單的前提。2. 主干網(wǎng)絡(luò) Backbone特征的底層來源2.1 ResNet 配置字段逐項解讀幾乎九成以上的 mmDetection 模型都基于 ResNet。打開一份 Faster R-CNN 配置backbone常常長這樣backbonedict( typeResNet, depth50, num_stages4, out_indices(0, 1, 2, 3), frozen_stages1, norm_cfgdict(typeBN, requires_gradTrue), norm_evalTrue, stylepytorch),這些字段看著簡單但每一個都可能影響你的實驗成敗。depth很好理解50 代表 ResNet-50。很多人會隨手改成 101然后發(fā)現(xiàn)訓(xùn)練速度慢了一大截、顯存爆掉這很正常畢竟更深的主干意味著更大的計算量。改depth之前先掂量一下自己的 GPU。num_stages是 ResNet 的 stage 數(shù)量。ResNet 默認 4 個 stage每個 stage 對應(yīng)一個下采樣倍率stage1 輸出 1/4 分辨率特征stage2 是 1/8stage3 是 1/16stage4 是 1/32。這也是out_indices的可選范圍為什么是 0 到 3。out_indices決定 backbone 向外輸出哪些 stage 的特征。(0, 1, 2, 3)表示把四個 stage 的特征全部輸出。如果你是做語義分割或者輕量檢測可能只需要(2, 3)甚至(3,)這樣可以省掉前面階段的輸出計算但對檢測來說多尺度特征很重要一般會全部輸出或者至少輸出后三個。frozen_stages是很多人容易忽略的字段。它表示凍結(jié)前幾個 stage 的參數(shù)不參與訓(xùn)練。默認值是 1也就是 stage1 之前的 stem 和 stage1 整個被凍住。這么做的原因是主干網(wǎng)絡(luò)通常使用在 ImageNet 上預(yù)訓(xùn)練的權(quán)重淺層特征邊緣、紋理比較通用不需要在目標任務(wù)上重新學(xué)凍結(jié)它們可以省顯存、加快收斂。如果你在任務(wù)上與 ImageNet 差異很大或者數(shù)據(jù)量很少也可以把frozen_stages設(shè)為 0 讓全部參數(shù)都參與訓(xùn)練但這會顯著增加顯存占用和訓(xùn)練時間需要自己權(quán)衡。norm_cfg和norm_eval是一對需要一起理解的概念。norm_cfgdict(typeBN, requires_gradTrue)表示使用 BatchNorm且 BN 層的weight和bias是允許梯度更新的。但注意norm_evalTrue會強制所有 BN 層在訓(xùn)練時也切換到 eval 模式意思是 BN 的均值/方差不更新只更新縮放和平移參數(shù)。這個組合在遷移學(xué)習(xí)里非常常見預(yù)訓(xùn)練 BN 的統(tǒng)計量已經(jīng)足夠好微調(diào)時不更新它們可以有效避免小 batch size 帶來的統(tǒng)計量抖動。如果你自己改網(wǎng)絡(luò)時把 BN 換成了 GroupNorm 之類的記得相應(yīng)調(diào)整這套配置。stylepytorch和stylecaffe的區(qū)別在于 stem 結(jié)構(gòu)。PyTorch 官方實現(xiàn)里 ResNet 的 stem 是一個 7x7 卷積加一個 3x3 的 max poolingCaffe 版本則沒有 pooling或者在第一層卷積上直接 stride2。這個字段影響了 backbone 實際搭出來的結(jié)構(gòu)也決定了加載預(yù)訓(xùn)練權(quán)重的方式通常保持默認的pytorch不需要管。2.2 更換主干網(wǎng)絡(luò)時的三個注意點我在實際項目里換過不少 backbone踩過的坑基本集中在三個地方。第一注意out_indices與后面 neck 的in_channels要對齊。比如 ResNet-50 四個 stage 的輸出通道數(shù)是[256, 512, 1024, 2048]如果你換了一個輸出通道數(shù)不同的主干比如某些輕量網(wǎng)絡(luò)輸出[24, 56, 120, 248]那 FPN 的in_channels必須同步修改否則 1x1 卷積的輸入維度直接 mismatch跑起來就是 TypeError。第二預(yù)訓(xùn)練權(quán)重的鍵名匹配問題。mmDetection 加載預(yù)訓(xùn)練權(quán)重時是拿 state dict 的 key 做嚴格匹配的如果你換了一個結(jié)構(gòu)稍微不同的 backbone比如 ResNet 的 stem 換了那么預(yù)訓(xùn)練權(quán)重里對應(yīng)層的 key 就對不上。這時候你需要在訓(xùn)練腳本里加--cfg-options model.backbone.pretrained...或者用load_from配合strictFalse來忽略不匹配的層。有一次我改了 stem 的結(jié)構(gòu)忘了處理權(quán)重加載結(jié)果訓(xùn)練了 20 個 epoch 后 mAP 一直在 0 附近排查了半天才意識到是預(yù)訓(xùn)練權(quán)重根本沒加載上。這個問題很隱蔽因為訓(xùn)練不會報錯只是精度起不來。第三frozen_stages和norm_eval需要根據(jù)你的 backbone 類型調(diào)整。如果你換了一個沒有 BN 層的 backbone或者用的 BN 在微調(diào)時會產(chǎn)生很大問題保持默認配置反而會拖慢收斂。適合初學(xué)者的建議是先保持默認配置跑通確認架構(gòu)沒問題再去調(diào)這些“精細化”參數(shù)。3. 特征金字塔 Neck讓不同尺度的目標都被看見3.1 FPN 的配置與機制FPNFeature Pyramid Network是當前檢測框架里最常見、也最重要的 neck。它在配置里長這樣neckdict( typeFPN, in_channels[256, 512, 1024, 2048], out_channels256, num_outs5),這份配置的意思是FPN 接收來自 backbone 的四個不同尺度的特征通道數(shù)分別是 256、512、1024、2048經(jīng)過處理后統(tǒng)一輸出 256 通道的特征圖最終向外輸出 5 個尺度的特征。FPN 的核心操作分兩條路徑。自底向上的路徑就是 backbone 本身——分辨率越來越低但語義越來越豐富。FPN 額外加了一條自頂向下的路徑從分辨率最低但語義最強的 stage4 特征開始通過 1x1 卷積統(tǒng)一通道數(shù)然后逐級上采樣與自底向上的特征做逐元素相加。這樣做的效果是高層特征獲得了高分辨率的細節(jié)信息低層特征獲得了豐富的語義信息每一層都同時擁有“是什么”和“在哪里”兩種能力。目標檢測中尺度變化很常見——一張圖里大象可能占半個畫面遠處的貓只有 20 個像素。沒有 FPN 之前老方法要么只在單一特征圖上檢測對不同尺度很不友好要么在多個尺度上分別跑一遍網(wǎng)絡(luò)計算量爆炸。FPN 用很小的額外計算量就拿到了多尺度的能力這也是它成為標配的原因。3.2 配置中的幾個隱蔽細節(jié)num_outs表示 FPN 輸出的特征金字塔層數(shù)。它通常比in_channels的列表長度多 1比如這里in_channels有 4 個num_outs5意味著除了 backbone 的 4 層特征FPN 還會在最高層1/32 分辨率之上再做一次 stride2 的下采樣額外產(chǎn)生一個 1/64 分辨率的特征層通常叫 P6。P6 對檢測超大目標有幫助但如果你處理的任務(wù)里目標普遍偏小反而沒必要保留這一層——小目標天然在高分辨率特征層上更容易被檢測到。我曾經(jīng)在一個小目標數(shù)據(jù)集上測試過把num_outs從 5 改成 4精度反而略有提升因為 P6 層貢獻的全是誤檢。out_channels是 FPN 所有輸出層的統(tǒng)一通道數(shù)。它在后續(xù) head 的in_channels里必須保持一致。很多人改網(wǎng)絡(luò)時只調(diào)了 backbone 的深度忘了 FPN 的out_channels也要匹配 head 的輸入通道結(jié)果又是一堆維度報錯。如果你用的是PAFPNPath Aggregation FPN它會在 FPN 的基礎(chǔ)上再加一條自底向上的增強路徑讓底層細節(jié)信息也能向上傳遞對小目標更友好。配置上的差別是把typeFPN換成typePAFPN同時多了num_outs之外的一些下采樣配置。YOLO 系列檢測器里常用的就是這種結(jié)構(gòu)。經(jīng)驗之談如果項目里目標尺寸跨度很大優(yōu)先考慮保留完整的 5 層 FPN如果目標普遍偏小可以試試去掉最深層或者在neck后面接一個尺寸較大的特征層做檢測。這類小改動往往比更換 backbone 收益來得更快。4. 檢測頭 Head分類和回歸真正發(fā)生的地方4.1 單階段 dense head 的配置邏輯單階段檢測器的 head 直接在 neck 輸出的特征圖上做密集預(yù)測。以 RetinaNet 為例bbox_head大概是bbox_headdict( typeRetinaHead, num_classes80, in_channels256, stacked_convs4, feat_channels256, anchor_generatordict( typeAnchorGenerator, octave_base_scale4, scales_per_octave3, ratios[0.5, 1.0, 2.0], strides[8, 8, 16, 32, 64]), bbox_coderdict( typeDeltaXYWHBBoxCoder, target_means[0.0, 0.0, 0.0, 0.0], target_stds[1.0, 1.0, 1.0, 1.0]), loss_clsdict( typeFocalLoss, use_sigmoidTrue, loss_weight1.0), loss_bboxdict(typeL1Loss, loss_weight1.0)),核心概念有兩個anchor 的生成和bbox 的編解碼。anchor_generator里的strides指的是特征圖下采樣倍數(shù)也就是該層特征圖上每個像素對應(yīng)原圖上的步長。特征圖的每個像素都會鋪上若干 anchor。octave_base_scale4表示基礎(chǔ)尺寸為 4 像素scales_per_octave3表示在每個“倍頻程”內(nèi)取 3 種尺度ratios[0.5, 1.0, 2.0]表示 3 種長寬比。所以每個像素上RetinaNet 默認生成3 (scales) x 3 (ratios) 9個 anchor這些 anchor 覆蓋了不同尺度、不同形狀的目標候選。bbox_coder負責(zé)的是“框的表示方式”。檢測器一般不會直接回歸框的四個坐標絕對值而是回歸“相對 anchor 的偏移量”因為直接回歸絕對值太難學(xué)。DeltaXYWHBBoxCoder把真實框轉(zhuǎn)換成相對于 anchor 的(dx, dy, dw, dh)訓(xùn)練時讓網(wǎng)絡(luò)去預(yù)測這四個值。target_stds是歸一化用的標準差RPN 里通常是[1.0, 1.0, 1.0, 1.0]RCNN 精修頭里通常是[0.1, 0.1, 0.2, 0.2]因為精修階段框的偏移量更小用更小的標準差可以讓回歸目標放大一些訓(xùn)練更好收斂。這里要提醒一個非常容易踩的坑num_classes一定不要隨便寫。它應(yīng)該等于“目標類別數(shù)“不含背景類別。比如你的數(shù)據(jù)集有 10 類物體num_classes就是 10。如果你從別人那里復(fù)制了一份 COCO 的配置里面是 80忘了改訓(xùn)練時 loss 計算、精度評估都會錯得離譜而且往往表現(xiàn)出一種“l(fā)oss 降了但 mAP 極低”的詭異狀態(tài)。4.2 雙階段 RPN Head RoI Head 的配合雙階段檢測器把檢測頭分成兩個階段這是它在精度上更“講究”的地方。RPNRegion Proposal Network的作用是快速生成候選框。它在每個特征層上做一次二分類有沒有物體和一次粗回歸挑出幾千個候選框再通過 NMS 篩到幾百個。RPN 本身并不知道框里是什么類別它只負責(zé)“這里可能有東西”。這個設(shè)計來自人類視覺的一個直覺先快速掃一遍場景鎖定可疑區(qū)域再仔細看清每個區(qū)域里到底是什么。RoI Head 則是真正的“精修專家”。它對 RPN 給出的每個候選框用RoI Align從特征圖上摳出對應(yīng)的區(qū)域特征然后統(tǒng)一縮放到固定尺寸比如 7x7送到全連接層里做分類和精細回歸。RoI Align 是雙階段方法里特別重要的組件。在它之前RoI Pooling 用的是兩次量化取整會引入像素級的偏差對小目標尤其不友好。RoI Align 用雙線性插值避免了量化誤差這也是 Mask R-CNN 之后幾乎所有雙階段方法都默認使用 RoI Align 的原因。配置里對應(yīng)的字段是roi_headdict( typeStandardRoIHead, bbox_roi_extractordict( typeSingleRoIExtractor, roi_layerdict(typeRoIAlign, output_size7, sampling_ratio0), out_channels256, featmap_strides[4, 8, 16, 32]), bbox_headdict( typeShared2FCBBoxHead, in_channels256, fc_out_channels1024, roi_feat_size7, num_classes80, ... ), )這里有個細節(jié)roi_layer里的output_size7和bbox_head里的roi_feat_size7必須一致。output_size決定 RoI Align 輸出特征圖的高寬roi_feat_size決定后面全連接層的輸入尺寸。如果你把output_size改成了 14roi_feat_size還留著 7那全連接的輸入維度就會對不上。這種錯誤在改網(wǎng)絡(luò)時特別容易出現(xiàn)因為報錯信息往往發(fā)生在網(wǎng)絡(luò)前向的最后階段定位起來比較費時間。雙階段方法還有一個隱含的好處RPN 已經(jīng)把絕大多數(shù)背景框篩掉了RoI Head 處理的候選框數(shù)量遠少于單階段密集檢測的 anchor 數(shù)量所以分類器學(xué)起來更容易精度自然更高。代價就是推理速度慢不少畢竟多跑了一輪網(wǎng)絡(luò)。到這一步你應(yīng)該也理解了為什么單階段與雙階段的配置結(jié)構(gòu)有那么大差異——本質(zhì)上就是“一次到位”和“由粗到精”兩種思路的區(qū)別。5. 一個最小但完整的檢測器配置逐行拆解5.1 用 Faster R-CNN 走一遍完整配置我不會讓你去對著論文看結(jié)構(gòu)直接拆一份實際的 Faster R-CNN 配置把它當成一張“JSON 地圖”逐段翻譯。完整的model配置長這樣model dict( typeFasterRCNN, backbonedict( typeResNet, depth50, num_stages4, out_indices(0, 1, 2, 3), frozen_stages1, norm_cfgdict(typeBN, requires_gradTrue), norm_evalTrue, stylepytorch), neckdict( typeFPN, in_channels[256, 512, 1024, 2048], out_channels256, num_outs5), rpn_headdict( typeRPNHead, in_channels256, feat_channels256, anchor_generatordict( typeAnchorGenerator, scales[8], ratios[0.5, 1.0, 2.0], strides[4, 8, 16, 32, 64]), bbox_coderdict( typeDeltaXYWHBBoxCoder, target_means[0.0, 0.0, 0.0, 0.0], target_stds[1.0, 1.0, 1.0, 1.0]), loss_clsdict( typeCrossEntropyLoss, use_sigmoidTrue, loss_weight1.0), loss_bboxdict(typeL1Loss, loss_weight1.0)), roi_headdict( typeStandardRoIHead, bbox_roi_extractordict( typeSingleRoIExtractor, roi_layerdict(typeRoIAlign, output_size7, sampling_ratio0), out_channels256, featmap_strides[4, 8, 16, 32]), bbox_headdict( typeShared2FCBBoxHead, in_channels256, fc_out_channels1024, roi_feat_size7, num_classes80, bbox_coderdict( typeDeltaXYWHBBoxCoder, target_means[0.0, 0.0, 0.0, 0.0], target_stds[0.1, 0.1, 0.2, 0.2]), reg_class_agnosticFalse, loss_clsdict( typeCrossEntropyLoss, use_sigmoidFalse, loss_weight1.0), loss_bboxdict(typeL1Loss, loss_weight1.0))) )我們來一步一步地看。typeFasterRCNN是檢測器外殼的類型它決定了訓(xùn)練流程怎么編排、前向推理走哪條路。backbone是 ResNet-50輸出四層特征neck是 FPN把四層特征統(tǒng)一成 256 通道的 5 層金字塔rpn_head在每層特征上生成scales[8]和 3 種寬高比組合出的 3 個 anchor實際 RPN 一般是 3 個因為scales只有 1 個值、ratios有 3 個roi_head用 RoI Align 提取候選框特征然后通過兩層全連接做分類和邊界框精回歸。一個需要注意的對應(yīng)關(guān)系rpn_head的anchor_generator.strides[4, 8, 16, 32, 64]有 5 個值和neck的num_outs5一一對應(yīng)。如果 FPN 輸出層的數(shù)量或者這些層對應(yīng)的 stride 變了這里必須同步修改。這個對應(yīng)關(guān)系在改num_outs時很容易漏掉出錯的表現(xiàn)是 RPN 在某個特征層上找不到匹配的 anchor 配置直接報錯。bbox_head里的reg_class_agnosticFalse是一個值得理解的字段。False意味著回歸分支為每個類別各預(yù)測一組邊界框偏移量框修正得更精細但參數(shù)量也更大最后的全連接層輸出維度從 4 變成4 * num_classes。True則表示所有類別共用一組回歸參數(shù)參數(shù)量小、速度更快但精度有輕微損失。實際小數(shù)據(jù)集項目里我一般會保持默認False這也是官方配置的選擇。5.2 從配置到模型的實例化流程配置里的dict最終是怎么變成可執(zhí)行的網(wǎng)絡(luò)模塊的mmDetection 的答案是讀取type字段去對應(yīng)的注冊表里找到這個類的定義把剩下的參數(shù)作為關(guān)鍵字參數(shù)傳進去完成實例化。這條鏈路的起點是from mmdet.models import build_detector model build_detector(cfg.model, test_cfgcfg.get(test_cfg))build_detector展開之后實際就是調(diào)用了build_from_cfg先根據(jù)model.type拿到FasterRCNN這個類然后創(chuàng)建backbone、neck、rpn_head、roi_head這些子模塊再全部作為參數(shù)塞進FasterRCNN的構(gòu)造函數(shù)。子模塊的構(gòu)建方式也是一樣的——讀各自的type找注冊表實例化。這套機制的好處是你不需要寫一堆if backbone resnet50: return ResNet()之類的分支代碼。所有模塊都把自己注冊到一個全局字典里配置里寫什么type框架就找什么類。這也是為什么你需要看mmdet/models/backbones/resnet.py源碼時在文件末尾總會看到一句BACKBONES.register_module() class ResNet(nn.Module): ...如果你調(diào)試網(wǎng)絡(luò)結(jié)構(gòu)時想知道某個中間結(jié)果的 shape最簡單的辦法是在對應(yīng)模塊的forward里打印x.shape。因為模塊都是直接通過配置構(gòu)建的打斷點也好、加打印也好都和你自己寫的一個普通 PyTorch 模型沒有區(qū)別這也是 mmDetection 對新手比較友好的地方。6. 網(wǎng)絡(luò)的可定制性注冊器機制與自定義組件6.1 注冊器機制到底做了什么這一節(jié)可能是 mmDetection 全網(wǎng)架構(gòu)里最“勸退”也最有價值的部分。注冊器Registry本質(zhì)就是一個“類名到類的映射表”但它的巧妙之處在于把“注冊”這件事做成了裝飾器。當你新建一個自定義 backbone代碼大概是這樣的from mmdet.models.builder import BACKBONES BACKBONES.register_module() class MyBackbone(nn.Module): def __init__(self, arg1, arg2): super().__init__() self.arg1 arg1 self.arg2 arg2 ... def forward(self, x): ... return outs只要這個文件被 import 過MyBackbone就會被自動寫進BACKBONES這個注冊表。之后你在配置里寫backbonedict( typeMyBackbone, arg1..., arg2...)框架構(gòu)建時就會執(zhí)行BACKBONES.get(MyBackbone)找到這個類然后用arg1和arg2作為參數(shù)實例化。我強烈建議你搞清楚mmdet/models/builder.py里那幾十行代碼里面定義了BACKBONES、NECKS、ROI_EXTRACTORS、HEADS、DETECTORS等注冊表。搞清楚這些注冊表的名字你就知道自己的模塊應(yīng)該注冊到哪里新主干網(wǎng)絡(luò) →BACKBONES.register_module()新特征融合模塊 →NECKS.register_module()新檢測頭 →HEADS.register_module()新檢測器外殼 →DETECTORS.register_module()這個機制是 mmDetection 支持復(fù)用的核心。也正是因為注冊器的存在你會發(fā)現(xiàn)很多模塊的內(nèi)部實現(xiàn)可能不一樣但只要它們注冊到同一個表里、接口一致就能無縫替換。這就是“配置驅(qū)動”的真正含義。6.2 自定義組件時最常見的三個坑我見過太多人卡在自定義這一步基本都是三類問題。第一類配置里寫了typeMyModule運行時報KeyError: MyModule is not in the ... registry。原因幾乎總是你雖然寫好了類和裝飾器但這個文件沒有被導(dǎo)入。mmDetection 默認只會導(dǎo)入mmdet/models/__init__.py里的東西你自己新建的.py文件如果不被任何__init__.pyimport注冊表里就沒有它。解決辦法是在對應(yīng)的__init__.py里加一行from .my_module import MyBackbone。這行代碼不直接做事但它觸發(fā)文件執(zhí)行裝飾器才算生效。第二類build_from_cfg報類型不匹配。這通常是因為你的模塊__init__里聲明的參數(shù)名和配置 dict 里的 key 不一致或者__init__的參數(shù)沒有給默認值導(dǎo)致cfg里的參數(shù)匹配不上。調(diào)試方法很簡單在模塊的__init__里打一個斷點看實際收到的 kwargs 是什么。第三類改了網(wǎng)絡(luò)結(jié)構(gòu)后加載預(yù)訓(xùn)練權(quán)重報錯。這與注冊器沒關(guān)系但最容易讓人心態(tài)爆炸。報錯信息一般是size mismatch for ...。原因很簡單預(yù)訓(xùn)練權(quán)重的層和你的新網(wǎng)絡(luò)層不完全對應(yīng)。規(guī)范做法是在配置的load_from里指定預(yù)訓(xùn)練權(quán)重然后訓(xùn)練腳本里用--cfg-options把model.train_cfg相關(guān)的嚴格加載關(guān)掉或者在代碼里調(diào)用load_state_dict時設(shè)置strictFalse。不過要注意strictFalse是一個有風(fēng)險的操作它會靜默忽略缺失的層有時候反而掩蓋了真正的維度錯誤。我的建議是加載報錯后先明確搞清楚哪些層不匹配確認是預(yù)期的結(jié)構(gòu)差異再關(guān)掉嚴格模式。7. 自主修改網(wǎng)絡(luò)架構(gòu)的實操經(jīng)驗7.1 一次“換主干加檢測頭”的完整過程假設(shè)你想把默認的 ResNet-50 backbone 換成一個新的輕量網(wǎng)絡(luò)再在 FPN 后面加一個小模塊具體可以怎么做我會分步驟介紹這套流程我自己反復(fù)用過很多次是通用的。第一步新建一個文件mmdet/models/backbones/my_backbone.py或者放在你自己的插件目錄里實現(xiàn)網(wǎng)絡(luò)結(jié)構(gòu)。不需要從頭寫卷積層復(fù)用torchvision或timm里的現(xiàn)成模型也行只要保證forward返回一個 tuple 或者 list里面是不同 stage 的特征圖。然后在文件末尾加上BACKBONES.register_module()。第二步注冊。在mmdet/models/backbones/__init__.py里導(dǎo)入這個文件。注意__init__.py的順序不影響執(zhí)行結(jié)果只要有 import 語句就夠了。第三步改配置。把backbone里的type改成你的類名并根據(jù)你的網(wǎng)絡(luò)實際輸出通道數(shù)調(diào)整out_indices和后面neck.in_channels。一個常見做法是先在骨干網(wǎng)絡(luò)內(nèi)部做一次print(outs.shape)跑一次單 batch 的前向確認輸出維度和預(yù)期一致再改配置。這一步能幫你省大量排查時間。第四步改neck和head的通道數(shù)使其與 backbone 輸出對齊。如果你只是換了depth而沒有換結(jié)構(gòu)這一步甚至可以不動如果你換了完全不同的網(wǎng)絡(luò)那么in_channels必須改。同時檢查一下rpn_head的strides和roi_head里featmap_strides是否和你的 FPN 輸出層級 match。第五步處理預(yù)訓(xùn)練權(quán)重。如果新 backbone 有預(yù)訓(xùn)練權(quán)重用load_from指定如果結(jié)構(gòu)差異很大用轉(zhuǎn)換腳本先對齊狀態(tài)字典里的 key實在對齊不了的才考慮strictFalse。整個過程聽起來繁瑣但這就是科研里最常見的“改配置迭代”流程。跑通一次之后你會覺得靈活度很高所有組件的替換邏輯其實都是一樣的。7.2 常見問題排查速查表我把實際項目里高頻出現(xiàn)的報錯和解決辦法整理如下現(xiàn)象原因解決辦法KeyError: xxx is not in the ... registry模塊沒有注冊確認xxx.register_module()存在且文件被 import前向時報size mismatch某個模塊的輸入輸出通道數(shù)不一致檢查 backbone 輸出通道、neckin_channels、headin_channelsRoI Align相關(guān) shape 錯誤roi_layer.output_size和roi_feat_size不一致保持兩個值一致并檢查 head 里 fc 層的輸入維度加載權(quán)重時報size mismatch新網(wǎng)絡(luò)和預(yù)訓(xùn)練權(quán)重結(jié)構(gòu)不同調(diào)整 key 對齊必要時設(shè)置strictFalse訓(xùn)練 loss 為 NaN學(xué)習(xí)率太大或正則化設(shè)置不當降低學(xué)習(xí)率檢查norm_cfg設(shè)置排查數(shù)據(jù)是否存在異常值改了num_classes但評估結(jié)果異常類別數(shù)不匹配確認num_classes等于數(shù)據(jù)集的類別數(shù)量不含背景類顯存溢出batch size 過大或 backbone 過深減小 batch size降低輸入分辨率考慮使用更淺的 backbone還有一個容易被忽略的問題很多人會直接修改官方配置里的model字段但配置繼承時沒有處理好。如果一份配置用了_base_繼承另一個配置你在子配置里寫了新的model那么整體 model dict 會替換掉 base 里的 model而不是做深層的逐 key 合并。如果你只是想覆蓋某一項比如只改num_classes正確的寫法是寫一個modeldict里面只放需要覆蓋的字段嗎不對——mmDetection 的配置繼承只做頂層 dict 的合并所以你要改model.roi_head.bbox_head.num_classes最安全的做法是把整條鏈路都寫全modeldict(roi_headdict(bbox_headdict(num_classes10)))。從頂層開始每一級都給出 dict避免合并時悄悄丟了其他字段。我在早期因為這個機制吃過虧只寫了modeldict(roi_headdict(bbox_headdict(num_classes2)))結(jié)果整個roi_head被替換成了只有bbox_head的 dict跑起來一堆配置缺失。搞清楚配置繼承規(guī)則能幫你少折騰很多個晚上。最后聊幾句我在實際使用這個框架的過程中體會到mmDetection 的網(wǎng)絡(luò)架構(gòu)設(shè)計最值得學(xué)習(xí)的反而不是某個檢測算法本身而是它這套模塊拆分 注冊機制 配置驅(qū)動的組裝理念。剛開始學(xué)的時候別急著追求理解每個算法的數(shù)學(xué)細節(jié)先學(xué)會“看配置猜結(jié)構(gòu)”拿到一份配置在腦子里過一遍 backbone 的輸出是什么形狀、neck 怎么融合、head 在哪一層做分類和回歸基本上網(wǎng)絡(luò)就活了。等你改過幾次 backbone、加過幾次自定義模塊之后再回頭看那些論文里的檢測器會發(fā)現(xiàn)它們之間的距離其實沒有想象中那么大。最后再分享一個小技巧如果你想快速驗證某個 backbone 改動到底效果如何不需要把整個訓(xùn)練流程跑完。先拿一個很小的數(shù)據(jù)集、只訓(xùn)練幾個 epoch觀察 loss 的下降趨勢和大致精度心里有數(shù)了再上全量數(shù)據(jù)。這個階段跑得快迭代才會快。祝你的實驗早日跑通指標早日漂亮起來。 mmDetection網(wǎng)絡(luò)架構(gòu)配置詳解：從Backbone、Neck到Head的組裝邏輯
很多同學(xué)第一次打開 mmDetection 的倉庫都有一種“從入門到放棄”的沖動mmdet/models目錄下躺著backbones、necks、dense_heads、roi_heads一堆文件夾點進configs發(fā)現(xiàn)每份配置文件長得像一棵樹尤其model字段嵌套七八層里面全是dict。我當年第一次看 Faster R-CNN 的配置時腦子里只有一個念頭這玩意兒到底是怎么變成一個能跑的網(wǎng)絡(luò)的這篇筆記想解決的就是這個問題。我會沿著 mmDetection 的網(wǎng)絡(luò)架構(gòu)這條線把model配置里的每個字段掰開揉碎告訴你 backbone、neck、head 各自扮演什么角色它們怎么組合成一個完整的檢測器以及如果你想把某一層換掉、加一個模塊應(yīng)該改哪里、怎么改。適合誰看剛接觸 mmDetection、跑通了官方 demo 但對配置一臉懵的科研小白以及在框架里做過小改動、卻始終沒弄清“為什么這樣寫”的開發(fā)者。1. 先建立整體印象mmDetection 的網(wǎng)絡(luò)分層思想1.1 檢測器不是一個黑盒而是一條流水線目標檢測和圖像分類最大的區(qū)別在于它要同時回答兩個問題物體在哪里定位和物體是什么分類。分類任務(wù)可以干脆利落地拿一個網(wǎng)絡(luò)把圖像映射成類別概率但檢測任務(wù)不行——你既要提取特征又要在特征上做密集的候選框預(yù)測還要對候選框做精修這么多事不可能靠一個單一的“黑盒網(wǎng)絡(luò)”完成。mmDetection 的做法是把這條鏈路拆成幾個職責(zé)清晰的模塊典型結(jié)構(gòu)是Backbone主干網(wǎng)絡(luò)負責(zé)從原始圖像中提取多層次特征。Neck頸部模塊在 backbone 輸出的多尺度特征上做融合或增強最典型的就是 FPN。Head檢測頭在融合后的特征上做最終的分類和回歸預(yù)測。雙階段檢測器還會拆成 RPN Head 和 RoI Head。Detector檢測器外殼把上面這些模塊拼裝起來同時負責(zé)訓(xùn)練和推理流程的編排。這個設(shè)計思路很像工廠里的流水線原料圖像先進第一道工序backbone粗加工再進第二道工序neck做精細處理最后由檢測頭head完成質(zhì)檢和打包。生產(chǎn)線上的每個環(huán)節(jié)都可以獨立替換這也是 mmDetection 能支持幾十種檢測器的根本原因。1.2 你一定會見到的幾個“角色”字段翻看任意一份 mmDetection 配置model字段下常見的關(guān)鍵字就那么幾個model dict( typeFasterRCNN, backbonedict(...), neckdict(...), rpn_headdict(...), roi_headdict(...), )單階段檢測器比如 RetinaNet、YOLO 系列通常只有backbone、neck、bbox_head沒有rpn_head和roi_head因為單階段不需要“先提候選框再精修”這兩步直接在特征圖上做密集預(yù)測。多階段檢測器Faster R-CNN、Mask R-CNN、Cascade R-CNN則多出rpn_head和roi_headRPN 先快速篩出一批可能包含物體的候選框RoI Head 再對這些候選框?qū)?yīng)的特征區(qū)域做精細分類和回歸。這個“粗篩 精修”的思路是雙階段方法在精度上長期優(yōu)于單階段方法的關(guān)鍵原因之一?？吹竭@里你就明白了mmDetection 的model配置不是一個“模型的形狀描述”而是一份組件清單。每個組件都是一個dict里面寫著“我要用什么模塊、參數(shù)是多少”。搞清楚每個組件的參數(shù)含義是理解這份清單的前提。2. 主干網(wǎng)絡(luò) Backbone特征的底層來源2.1 ResNet 配置字段逐項解讀幾乎九成以上的 mmDetection 模型都基于 ResNet。打開一份 Faster R-CNN 配置backbone常常長這樣backbonedict( typeResNet, depth50, num_stages4, out_indices(0, 1, 2, 3), frozen_stages1, norm_cfgdict(typeBN, requires_gradTrue), norm_evalTrue, stylepytorch),這些字段看著簡單但每一個都可能影響你的實驗成敗。depth很好理解50 代表 ResNet-50。很多人會隨手改成 101然后發(fā)現(xiàn)訓(xùn)練速度慢了一大截、顯存爆掉這很正常畢竟更深的主干意味著更大的計算量。改depth之前先掂量一下自己的 GPU。num_stages是 ResNet 的 stage 數(shù)量。ResNet 默認 4 個 stage每個 stage 對應(yīng)一個下采樣倍率stage1 輸出 1/4 分辨率特征stage2 是 1/8stage3 是 1/16stage4 是 1/32。這也是out_indices的可選范圍為什么是 0 到 3。out_indices決定 backbone 向外輸出哪些 stage 的特征。(0, 1, 2, 3)表示把四個 stage 的特征全部輸出。如果你是做語義分割或者輕量檢測可能只需要(2, 3)甚至(3,)這樣可以省掉前面階段的輸出計算但對檢測來說多尺度特征很重要一般會全部輸出或者至少輸出后三個。frozen_stages是很多人容易忽略的字段。它表示凍結(jié)前幾個 stage 的參數(shù)不參與訓(xùn)練。默認值是 1也就是 stage1 之前的 stem 和 stage1 整個被凍住。這么做的原因是主干網(wǎng)絡(luò)通常使用在 ImageNet 上預(yù)訓(xùn)練的權(quán)重淺層特征邊緣、紋理比較通用不需要在目標任務(wù)上重新學(xué)凍結(jié)它們可以省顯存、加快收斂。如果你在任務(wù)上與 ImageNet 差異很大或者數(shù)據(jù)量很少也可以把frozen_stages設(shè)為 0 讓全部參數(shù)都參與訓(xùn)練但這會顯著增加顯存占用和訓(xùn)練時間需要自己權(quán)衡。norm_cfg和norm_eval是一對需要一起理解的概念。norm_cfgdict(typeBN, requires_gradTrue)表示使用 BatchNorm且 BN 層的weight和bias是允許梯度更新的。但注意norm_evalTrue會強制所有 BN 層在訓(xùn)練時也切換到 eval 模式意思是 BN 的均值/方差不更新只更新縮放和平移參數(shù)。這個組合在遷移學(xué)習(xí)里非常常見預(yù)訓(xùn)練 BN 的統(tǒng)計量已經(jīng)足夠好微調(diào)時不更新它們可以有效避免小 batch size 帶來的統(tǒng)計量抖動。如果你自己改網(wǎng)絡(luò)時把 BN 換成了 GroupNorm 之類的記得相應(yīng)調(diào)整這套配置。stylepytorch和stylecaffe的區(qū)別在于 stem 結(jié)構(gòu)。PyTorch 官方實現(xiàn)里 ResNet 的 stem 是一個 7x7 卷積加一個 3x3 的 max poolingCaffe 版本則沒有 pooling或者在第一層卷積上直接 stride2。這個字段影響了 backbone 實際搭出來的結(jié)構(gòu)也決定了加載預(yù)訓(xùn)練權(quán)重的方式通常保持默認的pytorch不需要管。2.2 更換主干網(wǎng)絡(luò)時的三個注意點我在實際項目里換過不少 backbone踩過的坑基本集中在三個地方。第一注意out_indices與后面 neck 的in_channels要對齊。比如 ResNet-50 四個 stage 的輸出通道數(shù)是[256, 512, 1024, 2048]如果你換了一個輸出通道數(shù)不同的主干比如某些輕量網(wǎng)絡(luò)輸出[24, 56, 120, 248]那 FPN 的in_channels必須同步修改否則 1x1 卷積的輸入維度直接 mismatch跑起來就是 TypeError。第二預(yù)訓(xùn)練權(quán)重的鍵名匹配問題。mmDetection 加載預(yù)訓(xùn)練權(quán)重時是拿 state dict 的 key 做嚴格匹配的如果你換了一個結(jié)構(gòu)稍微不同的 backbone比如 ResNet 的 stem 換了那么預(yù)訓(xùn)練權(quán)重里對應(yīng)層的 key 就對不上。這時候你需要在訓(xùn)練腳本里加--cfg-options model.backbone.pretrained...或者用load_from配合strictFalse來忽略不匹配的層。有一次我改了 stem 的結(jié)構(gòu)忘了處理權(quán)重加載結(jié)果訓(xùn)練了 20 個 epoch 后 mAP 一直在 0 附近排查了半天才意識到是預(yù)訓(xùn)練權(quán)重根本沒加載上。這個問題很隱蔽因為訓(xùn)練不會報錯只是精度起不來。第三frozen_stages和norm_eval需要根據(jù)你的 backbone 類型調(diào)整。如果你換了一個沒有 BN 層的 backbone或者用的 BN 在微調(diào)時會產(chǎn)生很大問題保持默認配置反而會拖慢收斂。適合初學(xué)者的建議是先保持默認配置跑通確認架構(gòu)沒問題再去調(diào)這些“精細化”參數(shù)。3. 特征金字塔 Neck讓不同尺度的目標都被看見3.1 FPN 的配置與機制FPNFeature Pyramid Network是當前檢測框架里最常見、也最重要的 neck。它在配置里長這樣neckdict( typeFPN, in_channels[256, 512, 1024, 2048], out_channels256, num_outs5),這份配置的意思是FPN 接收來自 backbone 的四個不同尺度的特征通道數(shù)分別是 256、512、1024、2048經(jīng)過處理后統(tǒng)一輸出 256 通道的特征圖最終向外輸出 5 個尺度的特征。FPN 的核心操作分兩條路徑。自底向上的路徑就是 backbone 本身——分辨率越來越低但語義越來越豐富。FPN 額外加了一條自頂向下的路徑從分辨率最低但語義最強的 stage4 特征開始通過 1x1 卷積統(tǒng)一通道數(shù)然后逐級上采樣與自底向上的特征做逐元素相加。這樣做的效果是高層特征獲得了高分辨率的細節(jié)信息低層特征獲得了豐富的語義信息每一層都同時擁有“是什么”和“在哪里”兩種能力。目標檢測中尺度變化很常見——一張圖里大象可能占半個畫面遠處的貓只有 20 個像素。沒有 FPN 之前老方法要么只在單一特征圖上檢測對不同尺度很不友好要么在多個尺度上分別跑一遍網(wǎng)絡(luò)計算量爆炸。FPN 用很小的額外計算量就拿到了多尺度的能力這也是它成為標配的原因。3.2 配置中的幾個隱蔽細節(jié)num_outs表示 FPN 輸出的特征金字塔層數(shù)。它通常比in_channels的列表長度多 1比如這里in_channels有 4 個num_outs5意味著除了 backbone 的 4 層特征FPN 還會在最高層1/32 分辨率之上再做一次 stride2 的下采樣額外產(chǎn)生一個 1/64 分辨率的特征層通常叫 P6。P6 對檢測超大目標有幫助但如果你處理的任務(wù)里目標普遍偏小反而沒必要保留這一層——小目標天然在高分辨率特征層上更容易被檢測到。我曾經(jīng)在一個小目標數(shù)據(jù)集上測試過把num_outs從 5 改成 4精度反而略有提升因為 P6 層貢獻的全是誤檢。out_channels是 FPN 所有輸出層的統(tǒng)一通道數(shù)。它在后續(xù) head 的in_channels里必須保持一致。很多人改網(wǎng)絡(luò)時只調(diào)了 backbone 的深度忘了 FPN 的out_channels也要匹配 head 的輸入通道結(jié)果又是一堆維度報錯。如果你用的是PAFPNPath Aggregation FPN它會在 FPN 的基礎(chǔ)上再加一條自底向上的增強路徑讓底層細節(jié)信息也能向上傳遞對小目標更友好。配置上的差別是把typeFPN換成typePAFPN同時多了num_outs之外的一些下采樣配置。YOLO 系列檢測器里常用的就是這種結(jié)構(gòu)。經(jīng)驗之談如果項目里目標尺寸跨度很大優(yōu)先考慮保留完整的 5 層 FPN如果目標普遍偏小可以試試去掉最深層或者在neck后面接一個尺寸較大的特征層做檢測。這類小改動往往比更換 backbone 收益來得更快。4. 檢測頭 Head分類和回歸真正發(fā)生的地方4.1 單階段 dense head 的配置邏輯單階段檢測器的 head 直接在 neck 輸出的特征圖上做密集預(yù)測。以 RetinaNet 為例bbox_head大概是bbox_headdict( typeRetinaHead, num_classes80, in_channels256, stacked_convs4, feat_channels256, anchor_generatordict( typeAnchorGenerator, octave_base_scale4, scales_per_octave3, ratios[0.5, 1.0, 2.0], strides[8, 8, 16, 32, 64]), bbox_coderdict( typeDeltaXYWHBBoxCoder, target_means[0.0, 0.0, 0.0, 0.0], target_stds[1.0, 1.0, 1.0, 1.0]), loss_clsdict( typeFocalLoss, use_sigmoidTrue, loss_weight1.0), loss_bboxdict(typeL1Loss, loss_weight1.0)),核心概念有兩個anchor 的生成和bbox 的編解碼。anchor_generator里的strides指的是特征圖下采樣倍數(shù)也就是該層特征圖上每個像素對應(yīng)原圖上的步長。特征圖的每個像素都會鋪上若干 anchor。octave_base_scale4表示基礎(chǔ)尺寸為 4 像素scales_per_octave3表示在每個“倍頻程”內(nèi)取 3 種尺度ratios[0.5, 1.0, 2.0]表示 3 種長寬比。所以每個像素上RetinaNet 默認生成3 (scales) x 3 (ratios) 9個 anchor這些 anchor 覆蓋了不同尺度、不同形狀的目標候選。bbox_coder負責(zé)的是“框的表示方式”。檢測器一般不會直接回歸框的四個坐標絕對值而是回歸“相對 anchor 的偏移量”因為直接回歸絕對值太難學(xué)。DeltaXYWHBBoxCoder把真實框轉(zhuǎn)換成相對于 anchor 的(dx, dy, dw, dh)訓(xùn)練時讓網(wǎng)絡(luò)去預(yù)測這四個值。target_stds是歸一化用的標準差RPN 里通常是[1.0, 1.0, 1.0, 1.0]RCNN 精修頭里通常是[0.1, 0.1, 0.2, 0.2]因為精修階段框的偏移量更小用更小的標準差可以讓回歸目標放大一些訓(xùn)練更好收斂。這里要提醒一個非常容易踩的坑num_classes一定不要隨便寫。它應(yīng)該等于“目標類別數(shù)“不含背景類別。比如你的數(shù)據(jù)集有 10 類物體num_classes就是 10。如果你從別人那里復(fù)制了一份 COCO 的配置里面是 80忘了改訓(xùn)練時 loss 計算、精度評估都會錯得離譜而且往往表現(xiàn)出一種“l(fā)oss 降了但 mAP 極低”的詭異狀態(tài)。4.2 雙階段 RPN Head RoI Head 的配合雙階段檢測器把檢測頭分成兩個階段這是它在精度上更“講究”的地方。RPNRegion Proposal Network的作用是快速生成候選框。它在每個特征層上做一次二分類有沒有物體和一次粗回歸挑出幾千個候選框再通過 NMS 篩到幾百個。RPN 本身并不知道框里是什么類別它只負責(zé)“這里可能有東西”。這個設(shè)計來自人類視覺的一個直覺先快速掃一遍場景鎖定可疑區(qū)域再仔細看清每個區(qū)域里到底是什么。RoI Head 則是真正的“精修專家”。它對 RPN 給出的每個候選框用RoI Align從特征圖上摳出對應(yīng)的區(qū)域特征然后統(tǒng)一縮放到固定尺寸比如 7x7送到全連接層里做分類和精細回歸。RoI Align 是雙階段方法里特別重要的組件。在它之前RoI Pooling 用的是兩次量化取整會引入像素級的偏差對小目標尤其不友好。RoI Align 用雙線性插值避免了量化誤差這也是 Mask R-CNN 之后幾乎所有雙階段方法都默認使用 RoI Align 的原因。配置里對應(yīng)的字段是roi_headdict( typeStandardRoIHead, bbox_roi_extractordict( typeSingleRoIExtractor, roi_layerdict(typeRoIAlign, output_size7, sampling_ratio0), out_channels256, featmap_strides[4, 8, 16, 32]), bbox_headdict( typeShared2FCBBoxHead, in_channels256, fc_out_channels1024, roi_feat_size7, num_classes80, ... ), )這里有個細節(jié)roi_layer里的output_size7和bbox_head里的roi_feat_size7必須一致。output_size決定 RoI Align 輸出特征圖的高寬roi_feat_size決定后面全連接層的輸入尺寸。如果你把output_size改成了 14roi_feat_size還留著 7那全連接的輸入維度就會對不上。這種錯誤在改網(wǎng)絡(luò)時特別容易出現(xiàn)因為報錯信息往往發(fā)生在網(wǎng)絡(luò)前向的最后階段定位起來比較費時間。雙階段方法還有一個隱含的好處RPN 已經(jīng)把絕大多數(shù)背景框篩掉了RoI Head 處理的候選框數(shù)量遠少于單階段密集檢測的 anchor 數(shù)量所以分類器學(xué)起來更容易精度自然更高。代價就是推理速度慢不少畢竟多跑了一輪網(wǎng)絡(luò)。到這一步你應(yīng)該也理解了為什么單階段與雙階段的配置結(jié)構(gòu)有那么大差異——本質(zhì)上就是“一次到位”和“由粗到精”兩種思路的區(qū)別。5. 一個最小但完整的檢測器配置逐行拆解5.1 用 Faster R-CNN 走一遍完整配置我不會讓你去對著論文看結(jié)構(gòu)直接拆一份實際的 Faster R-CNN 配置把它當成一張“JSON 地圖”逐段翻譯。完整的model配置長這樣model dict( typeFasterRCNN, backbonedict( typeResNet, depth50, num_stages4, out_indices(0, 1, 2, 3), frozen_stages1, norm_cfgdict(typeBN, requires_gradTrue), norm_evalTrue, stylepytorch), neckdict( typeFPN, in_channels[256, 512, 1024, 2048], out_channels256, num_outs5), rpn_headdict( typeRPNHead, in_channels256, feat_channels256, anchor_generatordict( typeAnchorGenerator, scales[8], ratios[0.5, 1.0, 2.0], strides[4, 8, 16, 32, 64]), bbox_coderdict( typeDeltaXYWHBBoxCoder, target_means[0.0, 0.0, 0.0, 0.0], target_stds[1.0, 1.0, 1.0, 1.0]), loss_clsdict( typeCrossEntropyLoss, use_sigmoidTrue, loss_weight1.0), loss_bboxdict(typeL1Loss, loss_weight1.0)), roi_headdict( typeStandardRoIHead, bbox_roi_extractordict( typeSingleRoIExtractor, roi_layerdict(typeRoIAlign, output_size7, sampling_ratio0), out_channels256, featmap_strides[4, 8, 16, 32]), bbox_headdict( typeShared2FCBBoxHead, in_channels256, fc_out_channels1024, roi_feat_size7, num_classes80, bbox_coderdict( typeDeltaXYWHBBoxCoder, target_means[0.0, 0.0, 0.0, 0.0], target_stds[0.1, 0.1, 0.2, 0.2]), reg_class_agnosticFalse, loss_clsdict( typeCrossEntropyLoss, use_sigmoidFalse, loss_weight1.0), loss_bboxdict(typeL1Loss, loss_weight1.0))) )我們來一步一步地看。typeFasterRCNN是檢測器外殼的類型它決定了訓(xùn)練流程怎么編排、前向推理走哪條路。backbone是 ResNet-50輸出四層特征neck是 FPN把四層特征統(tǒng)一成 256 通道的 5 層金字塔rpn_head在每層特征上生成scales[8]和 3 種寬高比組合出的 3 個 anchor實際 RPN 一般是 3 個因為scales只有 1 個值、ratios有 3 個roi_head用 RoI Align 提取候選框特征然后通過兩層全連接做分類和邊界框精回歸。一個需要注意的對應(yīng)關(guān)系rpn_head的anchor_generator.strides[4, 8, 16, 32, 64]有 5 個值和neck的num_outs5一一對應(yīng)。如果 FPN 輸出層的數(shù)量或者這些層對應(yīng)的 stride 變了這里必須同步修改。這個對應(yīng)關(guān)系在改num_outs時很容易漏掉出錯的表現(xiàn)是 RPN 在某個特征層上找不到匹配的 anchor 配置直接報錯。bbox_head里的reg_class_agnosticFalse是一個值得理解的字段。False意味著回歸分支為每個類別各預(yù)測一組邊界框偏移量框修正得更精細但參數(shù)量也更大最后的全連接層輸出維度從 4 變成4 * num_classes。True則表示所有類別共用一組回歸參數(shù)參數(shù)量小、速度更快但精度有輕微損失。實際小數(shù)據(jù)集項目里我一般會保持默認False這也是官方配置的選擇。5.2 從配置到模型的實例化流程配置里的dict最終是怎么變成可執(zhí)行的網(wǎng)絡(luò)模塊的mmDetection 的答案是讀取type字段去對應(yīng)的注冊表里找到這個類的定義把剩下的參數(shù)作為關(guān)鍵字參數(shù)傳進去完成實例化。這條鏈路的起點是from mmdet.models import build_detector model build_detector(cfg.model, test_cfgcfg.get(test_cfg))build_detector展開之后實際就是調(diào)用了build_from_cfg先根據(jù)model.type拿到FasterRCNN這個類然后創(chuàng)建backbone、neck、rpn_head、roi_head這些子模塊再全部作為參數(shù)塞進FasterRCNN的構(gòu)造函數(shù)。子模塊的構(gòu)建方式也是一樣的——讀各自的type找注冊表實例化。這套機制的好處是你不需要寫一堆if backbone resnet50: return ResNet()之類的分支代碼。所有模塊都把自己注冊到一個全局字典里配置里寫什么type框架就找什么類。這也是為什么你需要看mmdet/models/backbones/resnet.py源碼時在文件末尾總會看到一句BACKBONES.register_module() class ResNet(nn.Module): ...如果你調(diào)試網(wǎng)絡(luò)結(jié)構(gòu)時想知道某個中間結(jié)果的 shape最簡單的辦法是在對應(yīng)模塊的forward里打印x.shape。因為模塊都是直接通過配置構(gòu)建的打斷點也好、加打印也好都和你自己寫的一個普通 PyTorch 模型沒有區(qū)別這也是 mmDetection 對新手比較友好的地方。6. 網(wǎng)絡(luò)的可定制性注冊器機制與自定義組件6.1 注冊器機制到底做了什么這一節(jié)可能是 mmDetection 全網(wǎng)架構(gòu)里最“勸退”也最有價值的部分。注冊器Registry本質(zhì)就是一個“類名到類的映射表”但它的巧妙之處在于把“注冊”這件事做成了裝飾器。當你新建一個自定義 backbone代碼大概是這樣的from mmdet.models.builder import BACKBONES BACKBONES.register_module() class MyBackbone(nn.Module): def __init__(self, arg1, arg2): super().__init__() self.arg1 arg1 self.arg2 arg2 ... def forward(self, x): ... return outs只要這個文件被 import 過MyBackbone就會被自動寫進BACKBONES這個注冊表。之后你在配置里寫backbonedict( typeMyBackbone, arg1..., arg2...)框架構(gòu)建時就會執(zhí)行BACKBONES.get(MyBackbone)找到這個類然后用arg1和arg2作為參數(shù)實例化。我強烈建議你搞清楚mmdet/models/builder.py里那幾十行代碼里面定義了BACKBONES、NECKS、ROI_EXTRACTORS、HEADS、DETECTORS等注冊表。搞清楚這些注冊表的名字你就知道自己的模塊應(yīng)該注冊到哪里新主干網(wǎng)絡(luò) →BACKBONES.register_module()新特征融合模塊 →NECKS.register_module()新檢測頭 →HEADS.register_module()新檢測器外殼 →DETECTORS.register_module()這個機制是 mmDetection 支持復(fù)用的核心。也正是因為注冊器的存在你會發(fā)現(xiàn)很多模塊的內(nèi)部實現(xiàn)可能不一樣但只要它們注冊到同一個表里、接口一致就能無縫替換。這就是“配置驅(qū)動”的真正含義。6.2 自定義組件時最常見的三個坑我見過太多人卡在自定義這一步基本都是三類問題。第一類配置里寫了typeMyModule運行時報KeyError: MyModule is not in the ... registry。原因幾乎總是你雖然寫好了類和裝飾器但這個文件沒有被導(dǎo)入。mmDetection 默認只會導(dǎo)入mmdet/models/__init__.py里的東西你自己新建的.py文件如果不被任何__init__.pyimport注冊表里就沒有它。解決辦法是在對應(yīng)的__init__.py里加一行from .my_module import MyBackbone。這行代碼不直接做事但它觸發(fā)文件執(zhí)行裝飾器才算生效。第二類build_from_cfg報類型不匹配。這通常是因為你的模塊__init__里聲明的參數(shù)名和配置 dict 里的 key 不一致或者__init__的參數(shù)沒有給默認值導(dǎo)致cfg里的參數(shù)匹配不上。調(diào)試方法很簡單在模塊的__init__里打一個斷點看實際收到的 kwargs 是什么。第三類改了網(wǎng)絡(luò)結(jié)構(gòu)后加載預(yù)訓(xùn)練權(quán)重報錯。這與注冊器沒關(guān)系但最容易讓人心態(tài)爆炸。報錯信息一般是size mismatch for ...。原因很簡單預(yù)訓(xùn)練權(quán)重的層和你的新網(wǎng)絡(luò)層不完全對應(yīng)。規(guī)范做法是在配置的load_from里指定預(yù)訓(xùn)練權(quán)重然后訓(xùn)練腳本里用--cfg-options把model.train_cfg相關(guān)的嚴格加載關(guān)掉或者在代碼里調(diào)用load_state_dict時設(shè)置strictFalse。不過要注意strictFalse是一個有風(fēng)險的操作它會靜默忽略缺失的層有時候反而掩蓋了真正的維度錯誤。我的建議是加載報錯后先明確搞清楚哪些層不匹配確認是預(yù)期的結(jié)構(gòu)差異再關(guān)掉嚴格模式。7. 自主修改網(wǎng)絡(luò)架構(gòu)的實操經(jīng)驗7.1 一次“換主干加檢測頭”的完整過程假設(shè)你想把默認的 ResNet-50 backbone 換成一個新的輕量網(wǎng)絡(luò)再在 FPN 后面加一個小模塊具體可以怎么做我會分步驟介紹這套流程我自己反復(fù)用過很多次是通用的。第一步新建一個文件mmdet/models/backbones/my_backbone.py或者放在你自己的插件目錄里實現(xiàn)網(wǎng)絡(luò)結(jié)構(gòu)。不需要從頭寫卷積層復(fù)用torchvision或timm里的現(xiàn)成模型也行只要保證forward返回一個 tuple 或者 list里面是不同 stage 的特征圖。然后在文件末尾加上BACKBONES.register_module()。第二步注冊。在mmdet/models/backbones/__init__.py里導(dǎo)入這個文件。注意__init__.py的順序不影響執(zhí)行結(jié)果只要有 import 語句就夠了。第三步改配置。把backbone里的type改成你的類名并根據(jù)你的網(wǎng)絡(luò)實際輸出通道數(shù)調(diào)整out_indices和后面neck.in_channels。一個常見做法是先在骨干網(wǎng)絡(luò)內(nèi)部做一次print(outs.shape)跑一次單 batch 的前向確認輸出維度和預(yù)期一致再改配置。這一步能幫你省大量排查時間。第四步改neck和head的通道數(shù)使其與 backbone 輸出對齊。如果你只是換了depth而沒有換結(jié)構(gòu)這一步甚至可以不動如果你換了完全不同的網(wǎng)絡(luò)那么in_channels必須改。同時檢查一下rpn_head的strides和roi_head里featmap_strides是否和你的 FPN 輸出層級 match。第五步處理預(yù)訓(xùn)練權(quán)重。如果新 backbone 有預(yù)訓(xùn)練權(quán)重用load_from指定如果結(jié)構(gòu)差異很大用轉(zhuǎn)換腳本先對齊狀態(tài)字典里的 key實在對齊不了的才考慮strictFalse。整個過程聽起來繁瑣但這就是科研里最常見的“改配置迭代”流程。跑通一次之后你會覺得靈活度很高所有組件的替換邏輯其實都是一樣的。7.2 常見問題排查速查表我把實際項目里高頻出現(xiàn)的報錯和解決辦法整理如下現(xiàn)象原因解決辦法KeyError: xxx is not in the ... registry模塊沒有注冊確認xxx.register_module()存在且文件被 import前向時報size mismatch某個模塊的輸入輸出通道數(shù)不一致檢查 backbone 輸出通道、neckin_channels、headin_channelsRoI Align相關(guān) shape 錯誤roi_layer.output_size和roi_feat_size不一致保持兩個值一致并檢查 head 里 fc 層的輸入維度加載權(quán)重時報size mismatch新網(wǎng)絡(luò)和預(yù)訓(xùn)練權(quán)重結(jié)構(gòu)不同調(diào)整 key 對齊必要時設(shè)置strictFalse訓(xùn)練 loss 為 NaN學(xué)習(xí)率太大或正則化設(shè)置不當降低學(xué)習(xí)率檢查norm_cfg設(shè)置排查數(shù)據(jù)是否存在異常值改了num_classes但評估結(jié)果異常類別數(shù)不匹配確認num_classes等于數(shù)據(jù)集的類別數(shù)量不含背景類顯存溢出batch size 過大或 backbone 過深減小 batch size降低輸入分辨率考慮使用更淺的 backbone還有一個容易被忽略的問題很多人會直接修改官方配置里的model字段但配置繼承時沒有處理好。如果一份配置用了_base_繼承另一個配置你在子配置里寫了新的model那么整體 model dict 會替換掉 base 里的 model而不是做深層的逐 key 合并。如果你只是想覆蓋某一項比如只改num_classes正確的寫法是寫一個modeldict里面只放需要覆蓋的字段嗎不對——mmDetection 的配置繼承只做頂層 dict 的合并所以你要改model.roi_head.bbox_head.num_classes最安全的做法是把整條鏈路都寫全modeldict(roi_headdict(bbox_headdict(num_classes10)))。從頂層開始每一級都給出 dict避免合并時悄悄丟了其他字段。我在早期因為這個機制吃過虧只寫了modeldict(roi_headdict(bbox_headdict(num_classes2)))結(jié)果整個roi_head被替換成了只有bbox_head的 dict跑起來一堆配置缺失。搞清楚配置繼承規(guī)則能幫你少折騰很多個晚上。最后聊幾句我在實際使用這個框架的過程中體會到mmDetection 的網(wǎng)絡(luò)架構(gòu)設(shè)計最值得學(xué)習(xí)的反而不是某個檢測算法本身而是它這套模塊拆分 注冊機制 配置驅(qū)動的組裝理念。剛開始學(xué)的時候別急著追求理解每個算法的數(shù)學(xué)細節(jié)先學(xué)會“看配置猜結(jié)構(gòu)”拿到一份配置在腦子里過一遍 backbone 的輸出是什么形狀、neck 怎么融合、head 在哪一層做分類和回歸基本上網(wǎng)絡(luò)就活了。等你改過幾次 backbone、加過幾次自定義模塊之后再回頭看那些論文里的檢測器會發(fā)現(xiàn)它們之間的距離其實沒有想象中那么大。最后再分享一個小技巧如果你想快速驗證某個 backbone 改動到底效果如何不需要把整個訓(xùn)練流程跑完。先拿一個很小的數(shù)據(jù)集、只訓(xùn)練幾個 epoch觀察 loss 的下降趨勢和大致精度心里有數(shù)了再上全量數(shù)據(jù)。這個階段跑得快迭代才會快。祝你的實驗早日跑通指標早日漂亮起來。