企业官网建设流程全解析

1. 为什么要先读builder：注册器机制就是整个框架的“路由总表”

拿到mmdetection源码，很多人第一反应是直奔模型文件，看ResNet怎么搭、FPN怎么融合、两阶段检测头怎么算loss。这个方向没错，但我个人的建议是：先读mmdet/models/builder.py。这个文件只有几十行，却直接决定了你后面读所有模型代码的效率。

原因很简单——mmdetection里几乎每个可配置的组件，模型、骨干网络、颈部、检测头、损失函数，甚至优化器策略和训练钩子，都不是在代码里直接if-else按名字调的，而是通过一套“注册器”（Registry）机制管理的。你可以把注册器理解成一个全局路由表：配置文件里写type = 'ResNet'，builder负责去路由表里找到真正干活的ResNet类，然后用配置文件里剩下的参数把它实例化出来。

这套机制一旦看懂，三个问题会瞬间解开：

• 为什么配置文件里只要写dict(type='FPN', in_channels=256)就能自动构造出FPN实例，代码里却看不到一处显式的FPN()调用？
• 为什么自定义一个新网络，只需要写一个继承官方基类的类，加一行装饰器，再在某个地方import一下，配置文件就能直接用？
• 为什么明明代码里定义了FasterRCNN，配置文件写type='FasterRCNN'却报错“not in registry”？

所以这篇笔记先从builder讲起，把注册器机制、build_from_cfg的执行链路、各个注册表的职责划分讲透。读者对象是正在啃mmdetection源码、想自定义检测模型、或者被各种KeyError: xxx is not in the registry折磨到怀疑人生的同学。

1.1 从一个“不合常理”的导入机制说起

第一次看到mmdetection的models/__init__.py，很多人会觉得这文件怎么全是import，而且顺序还很讲究：

from .backbones import * # noqa: F401,F403 from .detectors import * # noqa: F401,F403 from .losses import * # noqa: F401,F403 from .necks import * # noqa: F401,F403 ...

有人会觉得这些import *只是方便from mmdet.models import ResNet用的，但实际干的活远不止这些。

每个模块文件里都藏着一堆注册动作，比如resnet.py的末尾通常是这样：

@BACKBONES.register_module() class ResNet(nn.Module): ...

BACKBONES就是一个Registry实例，@BACKBONES.register_module()这个装饰器，在文件被import时就会执行，把ResNet这个类本身放进注册表。所以__init__.py里那一堆import *，真正作用是触发注册，让所有模型类在框架启动时就进注册表。如果某个模块没被import，注册动作就永远不会发生，配置里引用它必然报错。

这个机制，就是整个mmdetection可扩展性的地基。

1.2 配置文件中的“type”是个钥匙，不是类名

理解注册器，先要理解配置文件的写法。mmdetection的配置几乎全是Python文件嵌套字典，例如一个典型的检测头配置：

bbox_head=dict( type='FCOSHead', num_classes=80, in_channels=256, stacked_convs=4, ... )

代码里build_head(cfg)要做的事情，就是拿到这个字典，看到type是FCOSHead，然后去HEADS这个Registry里查一下叫FCOSHead的东西在不在，在的话，用num_classes=80, in_channels=256, ...这些参数去构造这个类。

所有需要“可被配置”的模块，都走这条路。理解到这一层，你就会发现mmdetection的代码结构其实非常规整：设计模式上叫“工厂模式”加“注册表模式”，但落地实现很Pythonic——用一个字典做映射，用装饰器做登记，用build_from_cfg做统一入口。

2. Registry类的实现：装饰器背后到底发生了什么

Registry类的实现，在mmcv的mmcv/utils/registry.py里。老版本mmdetection直接依赖mmcv，所以读builder之前，必须把mmcv中的Registry类读明白。

2.1 从mmcv导入的Registry到底做了什么

老版本mmdetection的mmdet/models/builder.py开头一般是：

from mmcv.utils import Registry, build_from_cfg

Registry类的最核心数据结构，就是一个内部字典_module_dict，键是注册名，值是模块类。看简化版源码：

class Registry: def __init__(self, name, build_func=None): self._name = name self._module_dict = dict() def __getitem__(self, key): return self.get(key) def register_module(self, name=None, force=False, module=None): def _register(module): self._register_module(module, name=name, force=force) return module return _register def _register_module(self, module, name=None, force=False): if name is None: name = module.__name__ if name in self._module_dict and not force: raise KeyError(f'{name} is already registered in {self.name}') self._module_dict[name] = module def get(self, key): if key not in self._module_dict: raise KeyError(f'{key} is not registered in {self.name}') return self._module_dict[key]

注意几个细节：

• register_module返回的是_register函数，所以用@BACKBONES.register_module()装饰类时，Python会把ResNet类作为module参数传给_register，进而传给_register_module。
• 如果name没传，默认用module.__name__，也就是类名。所以@BACKBONES.register_module()等价于注册时用类名作为键。
• 如果传了@BACKBONES.register_module(name='MyResNet50')，配置里type就得写MyResNet50，写ResNet会找不到。

这个类本身不看难，难在它和Python装饰器、import机制、继承关系的相互作用。很多自定义组件失败，不是类写错了，而是注册流程没走通。

2.2 register_module装饰器的执行时机

装饰器是理解注册器的一个门槛。很多人以为装饰器是“运行到某行才执行”，实际上Python在import模块时，解释器从上到下执行模块代码，遇到@BACKBONES.register_module()这行，会先执行BACKBONES.register_module()得到_register函数，然后把紧随其后的类作为参数调用_register。也就是说，注册动作发生在“import这个模块”的时刻，而不是“实例化这个类”的时刻。

举一个真实案例：A同学自定义了一个检测头MyHead，放在mmdet/models/heads/my_head.py，也在文件里写了@HEADS.register_module()，但配置文件一跑就报MyHead is not in HEADS registry。

排查后发现，他只是写了这个文件，却在mmdet/models/heads/__init__.py里忘了加from .my_head import MyHead。于是整个训练流程从头到尾没有人import过my_head.py，装饰器根本没执行，注册表中自然没有这个类。这是mmdetection二次开发里最经典的错误之一，几乎每周都有人踩。

2.3 从registry.get到类的完整链路

再看一个完整调用链。假设配置文件里写model = dict(type='FasterRCNN', backbone=..., neck=...)，训练脚本入口通常是：

from mmdet.models import build_detector model = build_detector(model_cfg)

build_detector的实现是：

def build_detector(cfg, train_cfg=None, test_cfg=None): return build_model(cfg, train_cfg=train_cfg, test_cfg=test_cfg)

而build_model在mmdet/models/builder.py里：

def build_model(cfg, train_cfg=None, test_cfg=None): return build_from_cfg(cfg, MODELS, default_args=dict(train_cfg=train_cfg, test_cfg=test_cfg))

于是控制权交给build_from_cfg，这一步才是真正“造对象”的地方，下一步单独拆。

2.4 一个容易被忽略的细节：类对象作为type

build_from_cfg有个不太起眼但很实用的特性：cfg['type']既可以是字符串，也可以直接是类对象。

如果是字符串，就去注册表里查；如果是类对象，直接使用，不再查注册表。这给调试带来很大方便：你可以不修改任何配置，在脚本里临时写：

from mmdet.models.backbones import ResNet cfg = dict(type=ResNet, depth=50, in_channels=3) backbone = build_backbone(cfg)

这样绕过了注册表，直接拿类构造。适用于快速验证某个新类的参数逻辑，不需要注册、不需要改配置。

3. build_from_cfg：一个配置如何变成可运行的模块

build_from_cfg是builder这个文件里最核心的函数，理解了它，等于理解了配置到对象的全部魔法。

3.1 type字段的解析规则与inspect.signature

老版本mmcv中build_from_cfg的签名和核心逻辑如下：

def build_from_cfg(cfg, registry, default_args=None): if not isinstance(cfg, dict): raise TypeError('cfg must be a dict') if 'type' not in cfg: raise KeyError('cfg must contain the key type') if not isinstance(registry, Registry): raise TypeError('registry must be mmcv.Registry') args = cfg.copy() obj_type = args.pop('type') if isinstance(obj_type, str): obj_cls = registry.get(obj_type) if obj_cls is None: raise KeyError(f'{obj_type} is not in the {registry.name} registry') elif inspect.isclass(obj_type): obj_cls = obj_type else: raise TypeError('type must be a str or valid type') try: return obj_cls(**args) except Exception as e: raise type(e)(f'{obj_cls.__name__}: {e}')

三个细节值得画重点：

• args = cfg.copy()是浅拷贝，type被pop掉，剩下的所有键全部作为关键字参数传给构造函数。
• 普通写法ResNet(**args)意味着配置里的键名必须和类的__init__参数名对得上，比如depth、in_channels、num_stages等。多传一个不认识的参数，构造函数就会报TypeError。
• inspect.isclass(obj_type)判断type是不是一个类，是的话直接用，刚才说的调试技巧就是靠这个分支实现的。

3.2 参数透传的两种方式

默认情况下，build_from_cfg只处理cfg本身的参数。但很多模块的构造函数，还需要额外传入train_cfg、test_cfg这类由训练流程动态提供的配置。

于是default_args这个参数就起作用了。build_model里：

build_from_cfg(cfg, MODELS, default_args=dict(train_cfg=train_cfg, test_cfg=test_cfg))

build_from_cfg内部会把default_args合并到参数里。合并规则有一个坑：cfg里已有的键优先，default_args只做兜底。也就是说，如果cfg里传了train_cfg=dict(...)，就以cfg为准，default_args里的train_cfg被覆盖。

这个优先级设计很合理——配置文件显式指定的参数，永远比代码里的默认值更优先。

3.3 配置文件里的“影子参数”

还有一个常见用法可能让新手困惑：有些配置参数根本不会传给构造函数，比如：

model=dict( type='MaskRCNN', backbone=dict(...), neck=dict(...), rpn_head=dict(...), roi_head=dict(...), train_cfg=dict(...), test_cfg=dict(...), )

train_cfg和test_cfg对MaskRCNN的构造函数而言是可以接收的参数，但真正起作用的路径是：build_detector把这两个参数从default_args传进去，MaskRCNN的__init__把它们保存下来；在forward_train阶段再传给内部的rpn_head和roi_head用。

还有一些配置键，比如pretrained、init_cfg，它们会被模型的初始化逻辑消费，而不是网络前向直接使用。读者在阅读配置时，要区分“构造参数”和“运行时参数”，否则容易对着一个配置文件发呆，不知道某个键到底去哪了。

我把这个调用链画成文字流程就是：

配置文件type字符串 → registry.get查注册表 → 拿到类对象 → pop掉type → 剩余参数合并default_args → 类(**args)实例化 → 返回对象。

看透这条链，配置到对象这条路就没秘密了。

4. mmdetection的builder生态：每个注册表各司其职

mmdetection的builder.py不只是有一个Registry，而是一群Registry和配套的build函数。老版本大致长这样：

BACKBONES = Registry('backbone') NECKS = Registry('neck') ROI_EXTRACTORS = Registry('roi_extractor') SHARED_HEADS = Registry('shared_head') HEADS = Registry('head') LOSSES = Registry('loss') DETECTORS = Registry('detector') SEGMENTORS = Registry('segmentor')

然后为每个注册表写一个build函数，例如：

def build_backbone(cfg): return build_from_cfg(cfg, BACKBONES) def build_neck(cfg): return build_from_cfg(cfg, NECKS) def build_roi_extractor(cfg): return build_from_cfg(cfg, ROI_EXTRACTORS) def build_head(cfg): return build_from_cfg(cfg, HEADS) def build_loss(cfg): return build_from_cfg(cfg, LOSSES)

4.1 主干网络、颈部、检测头：MODELS的分层注册

这些Registry不是乱建的，每个都对应模型结构的一个语义层。

• BACKBONES管主干网络，ResNet、ResNeXt、MobileNetV2、SwinTransformer都在这里。
• NECKS管特征融合，FPN、PAFPN、NASFPN、BiFPN在这里。
• HEADS管的范围比较广，单阶段检测器的分类回归头、两阶段检测器里的RPN Head和RoI Head的基类都在这里。严格说mmdetection把RoI Head又细分了，有ROI_EXTRACTORS（RoI特征提取器）、SHARED_HEADS（共享头，常用于多任务）。这种分层注册的好处是，骨架和检测头可以自由排列组合，只要配置里的type能在对应注册表查到。
• LOSSES管所有损失函数，CrossEntropyLoss、GIoULoss、DiceLoss都注册在这里。
• DETECTORS是顶层，对应整个检测模型，比如FasterRCNN、MaskRCNN、RetinaNet、CascadeRCNN都注册在这。

为什么要拆这么细？因为模块化。假设你想把ResNet换成SwinTransformer，不需要动检测头，只需要改配置文件里的backbone=dict(type='SwinTransformer', ...)，并且确保代码里import了SwinTransformer。注册表就是模块间的接口契约，各层各管各的。

4.2 优化器、调度器、hooks的注册差异

值得注意的是，mmdet里的builder.py只管模型相关组件。优化器和学习率调度器，老版本用的是mmcv里的build_optimizer和build_scheduler，它们的实现同样基于Registry，只是注册表定义在mmcv内部，比如OPTIMIZERS、SCHEDULERS。

而HOOKS这类训练钩子，注册表在mmcv的mmcv/runner/hooks里，比如CheckpointHook、EvalHook。新版mmdetection里训练器相关的东西逐渐被mmengine统一管理，注册表也统一到了mmengine的Registry，但核心机制没变。

这块的阅读经验是：不要只盯着mmdet的builder看，mmcv和mmengine里还有一大半体系。他们都是同一个注册器模式在不同层的应用，真正要掌握的是原理，而不是一个个文件。

4.3 典型builder实例对照

这张表建议贴在手边，读配置的时候对着看。看到某个配置块，先判断它属于哪个注册表，再决定看哪部分源码。

4.4 为什么builder实例里没有DATASETS

这里有个很容易混淆的细节：mmdetection的数据集类用的是DATASETS注册表，定义在mmdet/datasets/builder.py里，不在mmdet/models/builder.py。同理，数据增强也有自己的PIPELINES注册表。也就是说，mmdetection里不止一个builder文件，而是“每个大的功能域各有一组Registry”。

这意味着：

• mmdet/models/builder.py里的Registry，构建的是模型组件。
• mmdet/datasets/builder.py里的Registry，构建的是数据集和数据流水线。
• mmcv里的Registry，构建的是优化器、hook、runner相关组件。

统一思想：任何一个可配置的组件，都会有一个对应的Registry和一个build函数。你在源码里看到build_xxx(cfg)，基本就能推断出xxx对应的注册表在哪里。

5. 自定义组件：把你的网络结构挂进配置文件

讲完原理，来看具体操作。这一节以一个自定义backbone为例，走一遍完整流程。

5.1 最小的自定义Backbone示例

假设你想实现一个简单的三层卷积网络作为backbone，文件放在my_models/my_backbone.py：

import torch.nn as nn from mmcv.runner import BaseModule from mmdet.models.builder import BACKBONES @BACKBONES.register_module() class MyBackbone(BaseModule): def __init__(self, in_channels=3, out_channels=64): super().__init__() self.conv1 = nn.Conv2d(in_channels, out_channels, kernel_size=3, stride=2, padding=1) self.conv2 = nn.Conv2d(out_channels, out_channels * 2, kernel_size=3, stride=2, padding=1) self.conv3 = nn.Conv2d(out_channels * 2, out_channels * 4, kernel_size=3, stride=2, padding=1) self.out_channels = out_channels * 4 def forward(self, x): x = self.conv1(x) x = self.conv2(x) x = self.conv3(x) return (x, )

然后配置文件写成：

model=dict( type='FasterRCNN', backbone=dict( type='MyBackbone', in_channels=3, out_channels=64, ), ... )

这样就能跑通配置解析了。注意两点：forward要返回tuple，因为下游neck是按多尺度特征图tuple来解的；backbone最终输出通道数要能对上后面neck的in_channels。

5.2 注册时机：为什么必须先import再build

刚才说过，注册发生在import时。因此训练脚本或者my_models/__init__.py里必须有一句：

import my_models.my_backbone # noqa: F401

或者更规范一点，在my_models/__init__.py里写：

from .my_backbone import MyBackbone

然后在mmdet/models/builder.py之后、build_detector之前，确保my_models被import。如果你用的是mmdetection官方训练脚本train.py，它启动时会importmmdet，但不会import你的自定义模块。最常见做法是：修改train.py，在import mmdet下面加一句import my_models；或者你把自定义模块放进mmdet/models/backbones/并在backbones/__init__.py里加import。

这里还有一个陷阱：即使你在train.py里写from my_models.my_backbone import MyBackbone，如果你在某个地方又用了force=True去重复注册同名模块，会报already registered。但如果你明明import了却还报找不到，几乎肯定是import路径没生效，或者文件里有语法错误导致整个import被吞掉。

5.3 模块覆盖的坑

注册器机制天然支持模块覆盖：同一个注册名，后注册的会顶掉先注册的，前提是注册时设置了force=True。但mmcv默认force=False，重复注册直接抛异常。

这个设计是为了防止用户无意间覆盖官方模块。但有的时候，你就是想“不动官方源码，替换掉某个类”。比如官方ResNet满足不了你的需求，你想写一个同名ResNet类替换它。

可以通过这样注册：

@BACKBONES.register_module(name='ResNet', force=True) class MyResNet(BaseModule): ...

这会强行把ResNet这个名字指向你的新类。这种操作适合快速实验，但我不建议在正式项目里这样搞，因为把所有官方代码里的ResNet都换掉会带来不可预期的影响，排查问题的时候非常痛苦。更稳妥的做法是换个名字注册，在配置里显式引入。

6. 继承注册与歧义消解：children的隐藏特性

6.1 继承时子类自动注册的机制

mmcv的Registry在较新版本中支持“children（子注册表）”这个概念，用于多项目共存时隔离命名空间。

但它的另一个隐藏能力，在新版mmcv的register_module实现里体现得很充分：

if module is not None: # 注册到当前注册表 ... for base_class in module.__mro__: if base_class in registry._module_dict: registry._module_dict[base_class.__name__] = module

这个逻辑通俗讲就是：当你注册一个子类时，如果它的某个基类已经在注册表里，那么子类会以“基类名”为键再次注册一次。什么意思？

比如官方ResNet注册在BACKBONES里。你写一个class CustomResNet(ResNet): ...注册成CustomResNet，注册器会检测到父类ResNet已经在注册表里，于是也把ResNet这个键指向CustomResNet。

带来的效果是：配置文件里写type='ResNet'，实际拿到的是CustomResNet。这在工程上很实用——你不需要改任何官方配置，只要在入口处import了你的模块，整个项目就跑在你的自定义实现上。

6.2 两次查找：先看主干再看扩展

新版Registry的get做了更复杂的查找逻辑，大概流程是：

1. 先用scope确认当前注册表归属的项目模块（比如mmdet还是mmseg）。
2. 先从当前注册表自己的_module_dict里查。
3. 没查到，就去父注册表或children链路上再查一次。
4. 都查不到才抛KeyError。

这就是为什么你在mmdetection里使用backbone时，有些类其实定义在mmcls里，也能直接被BACKBONES查到。因为mmcv的Registry支持把不同项目的注册表链接起来——例如mmdet.models.backbones里会从mmcls的backbone注册表做一次“借用注册”。

这个设计让OpenMMLab系列项目之间能互相复用模型。如果你是做分类任务的，在mmcls里写了一个超强的backbone，到了检测项目里，只要import一下，检测的注册表也能查到。这就是“两次查找”的意义，第一查找各项目自己的注册表，第二查找跨项目共享注册表。

6.3 踩到的实际问题：同名模块的冲突

有了上述机制，一个新的坑就出现了：如果mmcls和mmdet都有ResNet，且都注册了，那BACKBONES.get('ResNet')到底返回谁？

老版本里，这取决于import顺序和注册表内的覆盖逻辑。新版本里，通过scope机制解决了——每个注册表定义时指定scope，查找时优先当前scope。如果你想让检测项目用mmcls的ResNet，需要用带scope的key，例如mmcls.ResNet。

因为源码持续演进，不同版本写法有差异。我不建议死记某个版本的细节，而是建议理解思路：注册器已经从一个“简单的dict映射”，进化成了“带命名空间和父子关系的模块路由系统”。你只要记住——遇到找不到模块，先想scope；遇到注册冲突，先想force；遇到继承覆盖，先想__mro__。

7. 阅读builder时最容易踩的坑

这一节专门盘点我在实际阅读和二次开发中反复遇到的几个问题，供你对照排查。

7.1 报错信息里说的不是类名，而是注册名

KeyError: 'MyHead is not in the HEADS registry'这句话，很多人以为是说MyHead这个类不存在，其实是在说HEADS注册表里没有名为MyHead的键。

这意味着三种可能：

1. 你没import包含MyHead的模块，注册动作没执行。
2. 你注册时用了别的名字（比如@HEADS.register_module(name='MySuperHead')），配置里却写type='MyHead'。
3. 模块import失败被吞掉了异常，Python解释器报的是别的问题，但错误信息被上层包装成了not in registry。

排查顺序：先确认文件能被import，再确认装饰器写法，再确认注册名和配置type一致。

7.2 import顺序影响注册冲突

如果你同时注册了几个“同名不同类”的模块，后注册的默认会抛异常。解决方式要么换名字，要么用force=True。但force=True会掩盖问题，上线前建议全局搜一下重复的注册名，确认是不是有意覆盖。

7.3 配置文件里的小写type与Python模块的区别

很多刚接触的人，会下意识把type='ResNet'和from mmdet.models.backbones import ResNet对应起来。绝大多数情况下确实如此，但记住：注册名只是一个字符串键，你完全可以把类名和注册名解耦。

比如官方有很多类是这么做的：

@BACKBONES.register_module() class ResNet(BaseModule): ...

注册名就是类名。但如果你看到一个模块文件里：

@HEADS.register_module(name='RetinaHead') class RetinaHeadModule(BaseModule): ...

配置里写type='RetinaHead'，但实际类名却是RetinaHeadModule。源码搜索时如果只搜RetinaHead类名，会找不到定义。这种解耦在大型项目里是常态，务必警惕。

7.4 多版本mmcv导致的Registry差异

mmdetection 2.x依赖mmcv，mmdetection 3.x则切换到mmengine。两个版本的Registry实现有不少差别：新版增加了scope、parent参数，装饰器还支持实例注册，查找链路也更复杂。

如果你看的解析博客是基于2.x的，但自己跑的是3.x，大概率会在自定义模块注册时报各种奇怪的错。我的建议是：先明确自己用的mmdet版本和配套的mmcv/mmengine版本，再看对应版本的builder源码，主流解析笔记的代码细节不一定适配你的版本。

8. 一份个人的阅读路径建议

最后分享我自己的源码阅读路径，算是一个可复用的方法论。

先读builder.py，建立注册表的概念框架，知道每个组件层有对应的Registry和build函数。

再挑一个最简单的检测器配置，比如Faster R-CNN的config，手动在ipython里“人肉build”一遍：

from mmdet.models import build_detector cfg = dict( type='FasterRCNN', backbone=dict(type='ResNet', depth=50, in_channels=3), neck=dict(type='FPN', in_channels=[256, 512, 1024, 2048], out_channels=256), ... ) model = build_detector(cfg)

把整个构建链路亲手跑出来，比看十遍注释都管用。

然后进入具体类源码阅读时，时刻带着两个问题：这个类是从哪个注册表被build出来的？它的父类是谁？一旦能把“配置键名-注册表-类定义”这条链路在脑子里快速串起来，mmdetection的学习曲线就会陡降。

我第一次读builder花了一个下午，但接下来读backbone、neck、head的源码，速度至少快了一倍。因为所有模型文件都在用同一种模式组织，入口都是那个几十行的builder，真正的复杂逻辑其实都在类内部，而类内部的组织规律已经被注册表规定好了。这就是先读这个小文件的真正价值。