Detectron2 LazyConfig 教程用 Python 与递归实例化构建灵活的非侵入式配置系统【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2LazyConfig 是 Detectron2 提供的一套与经典 yacs 配置系统并行的新型配置方案它用纯 Python 语法定义配置字典并通过_target_键递归实例化任意函数与类从而把配置与代码执行解耦。本文完整讲解 LazyConfig 的加载/保存/覆盖 API、递归实例化模式与LazyCall用法并结合仓库源码与模型仓库配置演示如何用它对 Mask R-CNN 等模型做零侵入式的构造、修改与命令行覆盖甚至让 Detectron2 训练与自身无关的 ImageNet 分类模型。读完本文你将掌握一套可迁移到任意深度学习项目的配置管理范式。为什么需要 LazyConfigyacs 之外的选择传统的 yacs 配置系统即CfgNode与get_cfg()见 detectron2/config/defaults.py提供了基础而标准的功能定义默认值、从 YAML 文件合并、用KEY.VALUE点号语法访问与覆盖。但对于很多新项目而言它存在明显的灵活性瓶颈配置结构是预定义的字段必须在defaults.py中预先声明新增一个字段需要改源码值类型受限YAML 只能表达基础数据类型难以放入类对象、lambda 或需要计算的表达式组合困难想复用另一个配置只能手工复制粘贴或借助_BASE_机制逻辑不够直观。LazyConfig 正是为解决这些痛点而生。它是一个非侵入式non-intrusive的替代方案不要求被配置的对象感知配置系统的存在可以被用在 Detectron2 之外的任何复杂项目中。其核心思想只有两条用 Python 语法写配置以及用递归实例化描述对象的创建。二者相互正交可以单独使用也可以组合使用详见 docs/tutorials/lazyconfigs.md。Python 语法配置即字典LazyConfig 的配置对象本质上仍然是字典只不过不再用 YAML 书写而是直接以 Python 代码创建。这让配置获得了原生 Python 的全部能力用 Python 轻松增删字典键值而 YAML 很难表达删除在配置里写简单算术或调用简单函数使用更丰富的数据类型与任意对象用熟悉的 Python import 语法导入 / 组合其他配置文件。一个最简示例文档原文# config.py: a dict(x1, y2, zdict(xx1)) b dict(x3, y4) # my_code.py: from detectron2.config import LazyConfig cfg LazyConfig.load(path/to/config.py) # an omegaconf dictionary assert cfg.a.z.xx 1加载后cfg是一个包含配置文件中全局作用域所有字典的 omegaconf 字典对象。需要注意几点与源码 detectron2/config/lazy.py 中的LazyConfig.load实现一一对应自动转为 omegaconf所有字典在加载时被转换为 omegaconf 配置对象DictConfig/ListConfig从而获得 omegaconf 的访问语法与变量插值${...}能力绝对导入照常工作config.py内的绝对 import 与普通 Python 完全一致相对导入只能导入其他配置文件中的字典它本质上是LazyConfig.load_rel的语法糖可以加载相对路径的 Python 文件而不需要__init__.py只收集配置对象从源码可见load在无keys参数时会过滤掉所有非DictConfig/ListConfig/dict的值以及下划线开头的变量not name.startswith(_)因此import进来的模块不会污染配置。此外load的实现还会先调用_validate_py_syntax用ast.parse预检语法并通过_patch_import()上下文管理器增强相对导入它基于文件相对位置解析导入目标、不缓存模块全局状态、支持通过PathManager加载云端配置。测试用例 tests/config/test_lazy_config.py 中的test_load也验证了每次加载都是全新状态这一点修改cfg.lazyobj.x后重新load值会恢复为原始值说明配置模块不会被全局缓存。保存LazyConfig.saveLazyConfig.save(cfg, filename)可以把配置对象保存为 YAML。但文档明确指出当配置中包含不可序列化的对象如 lambda时保存不一定成功——是否牺牲可保存性来换取灵活性由用户自己权衡。源码中save的降级策略很值得了解detectron2/config/lazy.py先深度拷贝配置并把可调用对象形式的_target_转成字符串以让 YAML 更美观若序列化失败则打印错误并尝试用cloudpickle保存为filename.pkl。对应测试test_failed_save验证了这一行为配置{x: lambda: 3}保存后会同时存在test_config.yaml与test_config.yaml.pkl两个文件。递归实例化用字典描述一次函数调用LazyConfig 系统大量依赖**递归实例化recursive instantiation**这一模式用一个字典描述对某个函数/类的调用。字典由两部分组成_target_键可调用对象的路径形如module.submodule.class_name其余键传给该可调用对象的参数参数本身也可以继续用递归实例化定义。仓库提供了辅助函数LazyCall源码位于 detectron2/config/lazy.py__all__同时导出LazyCall与LazyConfig来生成这类字典。下面这段文档中的代码from detectron2.config import LazyCall as L from my_app import Trainer, Optimizer cfg L(Trainer)( optimizerL(Optimizer)( lr0.01, algoSGD ) )等价于手工写出如下字典cfg { _target_: my_app.Trainer, optimizer: { _target_: my_app.Optimizer, lr: 0.01, algo: SGD } }LazyCall的实现有两点值得注意见 detectron2/config/lazy.py它要求只能以关键字参数调用位置参数暂不支持若_target_是 dataclass 类型会先转换为字符串形式因为 omegaconf 无法持有 dataclass 类型。返回的是带allow_objectsTrue标志的DictConfig因此调用本身并未发生只是记录了一次待执行的调用。instantiate把字典变成真正的对象既然对象被表示成了字典一个通用的instantiate函数就能把它们还原为真实对象实现在 detectron2/config/instantiate.pyfrom detectron2.config import instantiate trainer instantiate(cfg) # equivalent to: # from my_app import Trainer, Optimizer # trainer Trainer(optimizerOptimizer(lr0.01, algoSGD))instantiate会递归处理对ListConfig/list 逐个实例化元素对含_target_的映射先递归实例化所有参数再取出_target_若其为字符串则通过locate解析为可调用对象最后执行cls(**cfg)完成构造。当某个字典不含_target_时它会被原样返回这让纯数据字典与调用描述字典可以自然共存。一个完整的 Mask R-CNN 递归实例化示例该模式强大到足以描述非常复杂的对象。文档中给出了一个完整 Mask R-CNN 的递归实例化定义可展开查看其源码对应 configs/common/models/mask_rcnn_fpn.py。摘录核心片段from detectron2.config import LazyCall as L from detectron2.layers import ShapeSpec from detectron2.modeling.meta_arch import GeneralizedRCNN from detectron2.modeling.backbone.fpn import LastLevelMaxPool from detectron2.modeling.backbone import BasicStem, FPN, ResNet from detectron2.modeling.proposal_generator import RPN, StandardRPNHead from detectron2.modeling.roi_heads import ( StandardROIHeads, FastRCNNOutputLayers, MaskRCNNConvUpsampleHead, FastRCNNConvFCHead, ) model L(GeneralizedRCNN)( backboneL(FPN)( bottom_upL(ResNet)( stemL(BasicStem)(in_channels3, out_channels64, normFrozenBN), stagesL(ResNet.make_default_stages)( depth50, stride_in_1x1True, normFrozenBN, ), out_features[res2, res3, res4, res5], ), in_features${.bottom_up.out_features}, out_channels256, top_blockL(LastLevelMaxPool)(), ), proposal_generatorL(RPN)( in_features[p2, p3, p4, p5, p6], headL(StandardRPNHead)(in_channels256, num_anchors3), anchor_generatorL(DefaultAnchorGenerator)( sizes[[32], [64], [128], [256], [512]], aspect_ratios[0.5, 1.0, 2.0], strides[4, 8, 16, 32, 64], offset0.0, ), batch_size_per_image256, positive_fraction0.5, pre_nms_topk(2000, 1000), post_nms_topk(1000, 1000), nms_thresh0.7, ), roi_headsL(StandardROIHeads)( num_classes80, batch_size_per_image512, positive_fraction0.25, box_in_features[p2, p3, p4, p5], box_poolerL(ROIPooler)( output_size7, scales(1.0 / 4, 1.0 / 8, 1.0 / 16, 1.0 / 32), sampling_ratio0, pooler_typeROIAlignV2, ), box_headL(FastRCNNConvFCHead)( input_shapeShapeSpec(channels256, height7, width7), conv_dims[], fc_dims[1024, 1024], ), mask_in_features[p2, p3, p4, p5], mask_poolerL(ROIPooler)( output_size14, scales(1.0 / 4, 1.0 / 8, 1.0 / 16, 1.0 / 32), sampling_ratio0, pooler_typeROIAlignV2, ), mask_headL(MaskRCNNConvUpsampleHead)( input_shapeShapeSpec(channels256, width14, height14), num_classes${..num_classes}, conv_dims[256, 256, 256, 256, 256], ), ), pixel_meanconstants.imagenet_bgr256_mean, pixel_stdconstants.imagenet_bgr256_std, input_formatBGR, )这个例子展示了递归实例化的几个关键特性层级嵌套GeneralizedRCNN→FPN/RPN/StandardROIHeads→ResNet/Matcher/ROIPooler每一层都是L(Class)(...)形式的调用描述插值引用in_features${.bottom_up.out_features}引用兄弟节点FPN 复用 ResNet 输出的特征层num_classes${..num_classes}引用父节点ROIHeads 的num_classes这正是 omegaconf 插值能力在配置中的直接应用计算表达式scales(1.0 / 4, ...)直接书写算术复用自定义对象constants来自 configs/common/data/constants.py其中imagenet_bgr256_mean[103.530, 116.280, 123.675]、imagenet_bgr256_std[1.0, 1.0, 1.0]注意官方预训练模型已将 std 吸收进 conv1 权重因此 std 置 1。当然并非所有逻辑都能用字典描述。文档也提醒被复用的对象、方法调用等无法简单地用字典表达可能需要一些重构才能适配递归实例化。使用模型仓库的 LazyConfig仓库的模型仓库model zoo中提供了一批基于 LazyConfig 系统编写的配置典型代表configs/common/通用基础配置包括模型models/mask_rcnn_fpn.py、数据data/coco.py、优化器optim.py、学习率调度coco_schedule.py、训练选项train.pyconfigs/new_baselines/使用 Large-Scale JitterLSJ与更长训练计划的新 Mask R-CNN 基线50ep/100ep/200ep/400ep。安装 Detectron2 后可以通过模型仓库 APImodel_zoo.get_config加载它们实现见 detectron2/model_zoo/model_zoo.pyfrom detectron2.model_zoo import get_config from detectron2.config import LazyConfig cfg get_config(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.py)以 configs/COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.py 为例它把常见部件拆解到了common目录并通过相对导入组合再就地覆盖少量差异项from ..common.optim import SGD as optimizer from ..common.coco_schedule import lr_multiplier_1x as lr_multiplier from ..common.data.coco import dataloader from ..common.models.mask_rcnn_fpn import model from ..common.train import train model.backbone.bottom_up.freeze_at 2 train.init_checkpoint detectron2://ImageNetPretrained/MSRA/R-50.pkl这正体现了 LazyConfig 的组合哲学用 Python import 语法复用配置用赋值语句做细粒度覆盖——freeze_at 2冻结 ResNet 前两层init_checkpoint指向 ImageNet 预训练权重整份配置只有 8 行。约定俗成的字段结构虽然你可以为自己的项目自由定义配置结构与字段只要训练脚本能读懂但模型仓库的配置仍遵循一些简单约定以保持一致性cfg.model定义一个模型对象cfg.dataloader.{train,test}定义训练/测试数据加载器对象cfg.train以键值对形式存放训练选项。cfg.train的默认字段定义在 configs/common/train.py训练脚本 tools/lazyconfig_train_net.py 正是按这些字段工作的train dict( output_dir./output, init_checkpoint, max_iter90000, ampdict(enabledFalse), # options for Automatic Mixed Precision ddpdict( # options for DistributedDataParallel broadcast_buffersFalse, find_unused_parametersFalse, fp16_compressionFalse, ), checkpointerdict(period5000, max_to_keep100), # options for PeriodicCheckpointer eval_period5000, log_period20, devicecuda, )对照 tools/lazyconfig_train_net.py 的do_train实现可以看到这些字段的消费方式instantiate(cfg.model)构建模型并model.to(cfg.train.device)cfg.optimizer.params.model model先把模型挂到优化器参数上再实例化随后依次实例化cfg.dataloader.train、cfg.lr_multiplierfvcore 调度器并根据cfg.train.amp.enabled选择AMPTrainer或SimpleTrainer最终注册PeriodicCheckpointer、EvalHook等 hooks 后按cfg.train.max_iter训练。查看配置结构LazyConfig.to_py除print()之外更推荐用LazyConfig.to_py查看配置结构from detectron2.model_zoo import get_config from detectron2.config import LazyConfig print(LazyConfig.to_py(get_config(COCO-InstanceSegmentation/mask_rcnn_R_50_FPN_1x.py)))从输出中更容易找到需要修改的选项例如dataloader.train.total_batch_size对应批量大小optimizer.lr对应基础学习率。源码中to_py会先把配置resolve成容器再通过black格式化成类似cfg.xxx ...的伪 Python 代码不可直接执行主要供人阅读测试 tests/config/test_lazy_config.py 的test_to_py给出了精确的输出格式预期。命令行覆盖与参考训练脚本官方提供了参考训练脚本 tools/lazyconfig_train_net.py既能训练也能评估模型仓库的配置同时演示了如何支持命令行值覆盖。其main流程为cfg LazyConfig.load(args.config_file) cfg LazyConfig.apply_overrides(cfg, args.opts) default_setup(cfg, args) if args.eval_only: model instantiate(cfg.model) ... else: do_train(args, cfg)命令行覆盖由LazyConfig.apply_overrides实现源码见 detectron2/config/lazy.py。它以ab形式的字符串列表就地修改配置语法遵循 Hydra 的 override grammar若安装了hydra-core会使用其OverridesParser做完整解析与类型处理否则退化为简单的keyvalue拆分并用ast.literal_eval推断值类型。覆盖过程中会对路径上的每个前缀做检查一旦前缀不是配置对象就抛出KeyError对应测试test_invalid_overrideslazyobj.x.xxx123会报错。一个真实的训练命令示例来自 configs/Misc/torchvision_imagenet_R_50.py 的头部注释python tools/lazyconfig_train_net.py --config-file configs/Misc/torchvision_imagenet_R_50.py \ --num-gpus 8 dataloader.train.dataset.root/path/to/imagenet/其中--config-file指定 Python 配置--num-gpus 8设置 GPU 数量末尾的dataloader.train.dataset.root...即为键路径覆盖无需修改任何配置文件。扩展案例用 Detectron2 训练 ImageNet 分类模型为展示新系统的威力与灵活性文档引用了 configs/Misc/torchvision_imagenet_R_50.py一份简单的配置文件就能让 Detectron2 训练一个来自 torchvision 的 ImageNet 分类模型——尽管 Detectron2 本身不包含任何 ImageNet 分类功能。这可以作为把 Detectron2 用作通用深度学习引擎的参考范例。其结构完全符合上述约定model是一个包装了 torchvisionResNet(Bottleneck, layers[3,4,6,3])的ClassificationNetdataloader.{train,test}用L(torchvision.datasets.ImageNet)配合T.Compose变换训练用RandomResizedCropRandomHorizontalFlip测试用ResizeCenterCrop并在 test 数据集上通过插值root${...train.dataset.root}复用训练集根路径dataloader.evaluator是自定义的ClassificationAcc计算 top-1 accuracy并经comm.all_gather做分布式聚合optimizer与lr_multiplier同样以递归实例化定义。配置末尾还注释提醒把可复用代码写进配置文件只是为了演示工程实践上更推荐放到自己的项目里再 import。总结为什么是LazyConfig通过递归实例化来创建对象cfg只在instantiate一处被消费从而避免了把巨型配置到处传递。这带来以下好处文档原文归纳非侵入式non-intrusive被构造的对象是配置无关的普通 Python 函数/类甚至可以来自其他库。例如{_target_: torch.nn.Conv2d, in_channels: 10, out_channels: 10, kernel_size: 1}就定义了一个卷积层——完全不需要 Detectron2 参与清晰clarity一眼就能看出将调用哪些函数/类、使用哪些参数灵活flexibilitycfg不需要预定义键与结构只要最终能翻译成合法代码即为有效配置兼容仍然可以像旧方式那样把大字典作为参数整体传递。递归实例化与 Python 语法是正交的可以只使用其中一种。但二者结合后配置文件看起来几乎就是将要执行的代码区别在于配置文件只定义字典可以随时通过组合或覆盖继续修改对应代码要到instantiate被调用时才会真正执行。某种意义上我们是在配置文件中书写可编辑的代码并在需要时延迟执行——这正是 LazyConfig 名字的由来。【免费下载链接】detectron2Detectron2 is a platform for object detection, segmentation and other visual recognition tasks.项目地址: https://gitcode.com/GitHub_Trending/de/detectron2创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考