---

name: model-configs description: "Select, inspect, customize, and debug SOLO-era MMDetection models, registries, configs, heads, post-processing, and optional compiled operators without relying on the source checkout." metadata: disco-role: operating disable-model-invocation: true license: NOASSERTION

Model configs

Use this skill when a Researcher must choose a SOLO/SOLOv2 model family, understand how a legacy MMDetection configuration becomes a PyTorch module, or safely plan a custom component. This is an operating guide for the pinned SOLO-era design, not a modern MMDetection API reference.

First classify the request

1. Instance segmentation: choose SOLO/SOLOv2 and read references/model-overview.md. SOLO is box-free and uses a category branch plus mask prediction; SOLOv2 adds a mask-feature head and dynamic mask kernels. The decoupled and light heads are head variants, not new detector registry families.
2. Bounding-box detection: choose a detector family from the representative table in references/api-reference.md: two-stage RPN/R-CNN variants, or single-stage RetinaNet/FCOS/Fovea/ATSS/RepPoints/SSD families.
3. Architecture modification: identify the component registry and its parent detector boundary before editing a config. Follow the custom-component recipe below; do not assume a Python class is discoverable merely because its file exists.
4. Inference/post-processing: check the model's test_cfg, result contract, NMS/matrix-NMS path, and compiled-op requirements before trying an API.

A config is executable Python in this vintage. It may define shared variables, expressions, range(...), and nested dictionaries. Use the safe read-only helper python scripts/inspect_config.py CONFIG.py to print model component types and selected keys without importing the config, importing MMDetection, loading weights, downloading data, or executing arbitrary config code. It is a summary probe, not a full config validator.

Build boundary: registry -> builder -> detector

• mmdet.models.registry exposes separate registries: BACKBONES, NECKS, HEADS, LOSSES, DETECTORS, ROI_EXTRACTORS, and SHARED_HEADS.
• mmdet.models.builder.build_* calls the legacy build_from_cfg: each config must be a dict with a string type (or an explicit class), and that name must already be registered. A list builds an nn.Sequential.
• Import side effects populate registries through package __init__ files. A custom class needs both a registry decorator and an import reachable from the corresponding package initializer; otherwise registry.get(type) is None.
• build_detector(model, train_cfg, test_cfg) injects the two configs as default constructor arguments. A component's constructor owns its accepted keys; extra keys fail at construction rather than being silently ignored.
• The ordinary graph is backbone -> optional neck -> head; two-stage graphs add RPN/ROI extractors/bbox or mask heads. SOLO uses SingleStageInsDetector; SOLOv2 additionally builds mask_feat_head. See the graph table in the API reference.

Before construction, confirm that num_classes, feature channels, number of feature levels, grid/stride lists, and any mask-head channel widths agree. The repository's representative config-construction pattern loads a config, sets model.pretrained = None, and calls build_detector. That check exercises Python imports and constructors, not forward correctness, compiled CUDA kernels, data availability, or checkpoint compatibility.

Select a model and config

Use the bundled model overview to map the goal to a family, then, from the generated skill root, inspect a user-supplied config with the bundled helper:

python sub-skills/model-configs/scripts/inspect_config.py <CONFIG.py>
python sub-skills/model-configs/scripts/inspect_config.py --json <CONFIG.py>

Selection rules:

• configs/solo/solo_* -> model.type='SOLO', normally SOLOHead.
• configs/solo/decoupled_solo_* -> model.type='SOLO', with DecoupledSOLOHead or its light variant; it separates x/y mask branches.
• configs/solov2/solov2_* -> model.type='SOLOv2', SOLOv2Head, and a MaskFeatHead; light variants alter backbone/head channels and input scale.
• Configs with dcn in the backbone or use_dcn_in_tower=True require the DCN extension. Do not use a DCN config as a CPU-only construction candidate.
• fp16/ configs opt into the old Fp16OptimizerHook; this is a training precision policy, not a guarantee that every custom op supports half tensors.
• 8gpu, 1x, and 3x in filenames describe the released schedule assumptions. The baseline learning rate is commonly for 8 GPUs x 2 images/GPU; rescaling or changing batch size requires an explicit optimization decision.

The config's data pipeline must match the model: SOLO/SOLOv2 training collects img, gt_bboxes, gt_labels, and gt_masks; detector-only pipelines need not collect masks. test_cfg controls filtering and final result limits. Dataset paths, checkpoint URLs, and work directories are environment inputs: replace them with local approved values and never bake source-checkout paths into a skill.

Customize without breaking contracts

For a custom backbone, neck, head, loss, detector, ROI extractor, or shared head:

1. Define an nn.Module with a constructor whose keyword names match the config.
2. Implement the expected tensor/list-of-feature-map interface. A backbone emits feature maps selected by out_indices; FPN-like necks consume those maps and emit a list; heads consume the list and expose forward, loss, and inference methods expected by their detector.
3. Register with the correct registry (@BACKBONES.register_module, etc.).
4. Import the class from the package __init__.py that is imported by mmdet.models; registration is import-time, not filesystem discovery.
5. Replace only the relevant nested type and shape parameters in a config.
6. Start with pretrained=None, instantiate the model, and run a tiny tensor forward or a focused native test only after dependencies are proven.

BaseDetector requires extract_feat, forward_train, simple_test, and aug_test. SingleStageDetector passes backbone/neck features to one bbox head; TwoStageDetector performs proposal assignment/sampling and ROI heads; SingleStageInsDetector passes masks and metadata to the instance head and raises NotImplementedError for augmentation testing in this snapshot. Do not silently substitute a bbox head for a SOLO instance head: the data and result contracts differ.

Loss configs are also registry configs. Common registered choices include FocalLoss, CrossEntropyLoss, SmoothL1Loss, BalancedL1Loss, IoULoss, GIoULoss, and GHMC/GHMR; the SOLO heads additionally define a local dice_loss helper while their historical configs still spell the nested loss as type='DiceLoss'. Verify the exact target head before reusing that key outside SOLO. Preserve the expected label encoding, use_sigmoid, reduction/avg_factor, and loss_weight; changing these can produce a numerically valid but semantically wrong model. See references/api-reference.md for the compact contract table.

Post-processing and precision

For bbox heads, multiclass_nms skips score column 0 as background, filters by score_thr, dispatches the configured nms/soft_nms, and caps max_num. NMS accepts NumPy arrays or tensors and preserves the input type; GPU tensors use nms_cuda, CPU tensors use nms_cpu. CPU NMS tests cover float32/float64, while GPU tests cover float32 and skip float64. SOLO/SOLOv2 use category scores and mask-specific post-processing; SOLOv2 applies points_nms to category heatmaps and matrix_nms to same-class masks before max_per_img.

For legacy FP16, set fp16 in the config only when the installed MMCV runner and model support it. The hook keeps FP32 optimizer weights, converts the model to half, patches BatchNorm/GroupNorm to FP32, scales loss, and copies gradients and parameters. Custom modules should use @auto_fp16 and @force_fp32 only on nn.Module methods and only after verifying tensor dtypes. FP16 does not repair a missing extension or make an unsupported CUDA kernel safe.

Verification ladder

Use the smallest sufficient check and record what it does not prove:

1. Static config summary: run scripts/inspect_config.py; verify types, keys, stage widths, mask collections, and test thresholds.
2. Registry/build smoke: in a compatible environment, import mmdet.models, load a config through the legacy mmcv.Config, remove pretrained, and call build_detector. This may require all package imports and compiled ops.
3. CPU utility candidate: run the focused CPU NMS or pure-PyTorch matrix-NMS checks if the extension imports successfully. A CPU check does not validate custom CUDA kernels.
4. Forward candidate: use a tiny input only for a model without required DCN or other blocked extensions. CUDA forward and training are environment- and memory-dependent; full training is out of scope for this sub-skill.

Native acceptance candidates are therefore: representative config construction; CPU NMS or pure-PyTorch matrix-NMS utility checks when imports permit; and CUDA operator/forward checks only when the selected model requires them and a compatible GPU build is available. Do not call a blocked CUDA candidate successful, and do not run full training as a native check.

If an import fails with ModuleNotFoundError or a missing .so such as nms_cpu, nms_cuda, deform_conv_cuda, roi_align_cuda, or sigmoid_focal_loss_cuda, classify it as an expected build/environment failure, not as a model-config semantic failure. Read references/troubleshooting.md.

Safety and boundaries

Do not copy compiled extensions, checkpoints, datasets, generated logs, or source scripts into this skill. The bundled inspector is deliberately AST-based and read-only. Training, distributed launchers, visualization, publishing, model weight downloads, dataset conversion, and source-mutation helpers remain reference-only because they are long-running, environment-mutating, networked, or write artifacts. Use approved project tooling outside this runtime subtree when those actions are explicitly authorized.