BoxMOT 检测器接入指南后端路由机制与自定义检测器扩展实战【免费下载链接】boxmotBoxMOT: Pluggable Python and C SOTA multi-object tracking modules with support for axis-aligned and oriented bounding boxes项目地址: https://gitcode.com/GitHub_Trending/bo/boxmotBoxMOT 的检测器运行时层位于 boxmot/detectors它将权重文件 → 推理后端 → 统一Detections输出抽象成一条可插拔流水线。本文以此目录为骨架讲解 BoxMOT 如何在 Ultralytics YOLO、YOLOX、RT-DETR 三个内置家族之间自动路由并分别给出复用现有家族权重与新增一个完整后端家族两条实战路径。读完本文你将掌握检测器配置文件的完整契约、BaseDetectorBackend三阶段接口的实现要求以及如何用最小改动把自有检测器接入 BoxMOT 的 track / eval 工作流。检测器运行时层概览boxmot/detectors/是 BoxMOT 的检测器运行时层目录职责划分非常清晰boxmot/detectors/ README.md # 本文档 __init__.py # 公开检测器导出 base.py # Detections 数据类与 BaseDetectorBackend 契约 config.py # 检测器 profile 校验与运行时适配 detector.py # 供工作流与 API 使用的公共 Detector 包装器 registry.py # 后端路由与检测器配置查找 ultralytics.py # Ultralytics 后端 yolox.py # YOLOX 后端 rtdetr.py # RT-DETR 后端围绕该目录的关联资源包括boxmot/configs/detectors —— 集中存放检测器运行时 profileYAMLmodels/—— 仓库约定的检测器权重默认存放位置也可使用该目录之外的显式路径tests/unit/detectors —— 检测器后端契约测试tests/unit/engine/tracking/test_inference.py —— 推理工作流测试docs/config/detectors.md —— 检测器 profile 的完整契约说明。BoxMOT 如何选择检测器后端公共包装器Detector定义在 detector.py在初始化时调用get_detector_class(path)定义在 registry.py由注册表决定实例化哪一个后端类。路由规则只有一条核心逻辑只检查权重文件的文件名大小写不敏感不检查父目录。registry.py中的_model_name会取Path(name).name.lower()然后用_check_model判断文件名中是否包含某个家族标记# boxmot/detectors/registry.py ULTRALYTICS_MODELS (yolov8, yolov9, yolov10, yolo11, yolo12, yolo26, sam) RTDETR_MODELS (rtdetr_v2_r50vd, rtdetr_v2_r18vd, rtdetr_v2_r101vd) YOLOX_MODELS (yolox_n, yolox_s, yolox_m, yolox_l, yolox_x)三个内置家族的匹配标记为家族文件名需包含对应后端类Ultralyticsyolov8/yolov9/yolov10/yolo11/yolo12/yolo26/samUltralyticsDetectorYOLOXyolox_n/yolox_s/yolox_m/yolox_l/yolox_xYoloXDetectorRT-DETRrtdetr_v2_r50vd/rtdetr_v2_r18vd/rtdetr_v2_r101vdRTDetrDetector因此受支持家族的自定义权重文件必须把家族标记保留在文件名中否则 BoxMOT 无法判断该加载哪个后端。DETECTOR_BACKENDS元组按序存放DetectorBackendSpec每个 spec 声明了匹配函数、模块路径、类名以及可选的自动安装依赖例如 YOLOX 家族声明了(yolox, tabulate, thop)RT-DETR 声明了(transformers[torch], timm)。当权重缺失时get_detector_class会借助RequirementsChecker尝试自动补齐可选依赖若完全无法匹配任何家族则记录错误并SystemExit(1)。从源码结构还可以看到registry.py同时提供了一组默认参数回退逻辑default_imgsz在无配置时对 YOLOX 回退为[1080, 1920]、其他家族回退为[640, 640]default_conf回退为0.01Detector包装器在构造时即用它们填充imgsz与conf见 detector.py。Option 1为受支持家族接入自有权重如果检测器属于三个内置家族之一通常不需要新增任何 Python 代码只需四个步骤。1. 把权重放到可访问的位置仓库约定权重放在models/下models/my_detector_weights.pt任何显式路径都可用但放在models/下与仓库其余部分保持一致也便于 profile 中的 checkpointpath直接引用。2. 在文件名中保留家族标记例如models/yolo11_custom_people.ptmodels/yolox_x_my_benchmark.ptmodels/rtdetr_v2_r50vd_traffic.pt这正是registry.py选择正确后端的依据。3.可选添加检测器配置检测器配置存放在 boxmot/configs/detectors 下。仓库内置的真实示例 yolox-x-mot17.yaml 与 yolo11l-mmot-obb.yaml 展示了两种典型形态AABB 检测与 OBB 检测。一份完整的 profile 骨架如下id: yolo11-custom-people box_type: aabb classes: 0: person inference: image_size: [800, 1440] confidence_threshold: 0.20 checkpoints: default: path: models/yolo11_custom_people.pt uri: https://example.com/yolo11_custom_people.pt # 占位示例请替换为真实下载地址各字段的作用idprofile 的唯一标识实验与 CLI 通过它引用该检测器box_typeaabb或obb告诉 BoxMOT 检测器输出的是轴对齐框还是旋转框定向框检测器与数据集的 box 类型必须匹配classes类别编号到名称的映射供后续跟踪与渲染使用inference.image_size推理默认输入尺寸以高度-宽度顺序给出两个正整数inference.confidence_threshold置信度阈值取值范围[0, 1]checkpoints命名 checkpoint 列表每个 checkpoint 含path权重路径与uri文件缺失时自动下载的地址。为什么这些字段有价值命名 checkpoint 支持对权重文件进行精确匹配查找uri允许权重文件缺失时自动下载image_size与confidence_threshold提供检测器专属的默认值无需在命令行重复指定box_type决定 BoxMOT 以 AABB 还是 OBB 语义消费检测结果。配置文件在 config.py 中经过严格校验load_detector_config要求必须定义id、box_type仅限aabb/obb、至少一个类别、inference映射image_size必须恰好是两个正整数confidence_threshold必须在[0,1]以及至少一个 checkpoint类别表还会检查重复名称与重复 id。detector_config_to_runtime把校验后的 profile 适配为运行时映射imgsz、conf、classes、model_url等供Detector与实验系统消费。直接检测器查找会把请求的模型名去扩展名、去连字符与 catalog 中所有 checkpoint 的path做归一化匹配见registry.py的_detector_name_key与_matching_detector_configs实验则通过 profile ID checkpoint 名称显式引用。4. 用你的权重运行 BoxMOTboxmot track --source path/to/video.mp4 --detector models/yolo11_custom_people.pt boxmot eval --experiment mot17-ablation-yolox-lmbn --detector models/yolo11_custom_people.pt--detector接受权重路径或模型标识如yolov8neval场景下实验显式引用 profile ID 与 checkpoint 名。注意 docs/config/detectors.md 中的约定在直接源与无模型的--dataset工作流里CLI 的--detector是权重路径或模型标识符不是profile 选择器。Option 2添加一个全新的检测器后端家族如果检测器不属于任何现有家族需要在boxmot/detectors/下新增后端模块并在registry.py中注册。1. 创建后端模块新增文件例如boxmot/detectors/mydetector.py实现一个遵循BaseDetectorBackend契约的类。该基类定义在 base.py核心是三阶段接口 一个组合入口preprocess(images, **kwargs)—— 输入预处理letterbox、归一化、张量上载process(preprocessed, **kwargs)—— 纯模型前向postprocess(predictions, **kwargs)—— 解码、置信度过滤、类别过滤、NMS、坐标还原__call__—— 依次组装三阶段并校验输出类型与批次数目。最小后端骨架如下取自 README 并对照基类契约from __future__ import annotations import numpy as np from boxmot.detectors.base import BaseDetectorBackend, Detections class MyDetector(BaseDetectorBackend): def __init__(self, model, device, imgszNone): self.device device self.imgsz imgsz self.model self._load_model(model) self.names {0: person} self._images [] def _load_model(self, model): return model def preprocess(self, images: list[np.ndarray]): self._images images return images def process(self, preprocessed): return self.model(preprocessed) def postprocess(self, predictions, conf, iou, classes, agnostic_nms): return [ Detections.empty(image, namesself.names) for image in self._images ]2. 返回 BoxMOT schema 下的Detections对象BoxMOT 期望每张输入图像恰好得到一个Detections结果。该数据类base.py在构造时完成三类校验验证检测矩阵的宽度只能为 AABB 的 6 列或 OBB 的 7 列、把数值归一化为float32、并保证 masks 与检测行数一一对齐否则抛ValueError。支持的检测布局AABB(N, 6)列为[x1, y1, x2, y2, conf, cls]OBB(N, 7)列为[cx, cy, w, h, angle, conf, cls]角度以弧度表示。Detections还提供了一系列便捷访问器boxes返回原生几何AABB 的xyxy或 OBB 的xywha、xyxy在 OBB 场景下自动计算外接轴对齐框、conf/classes分别取置信度与类别列。__call__会检查postprocess返回的是否为Detections列表且数量与输入批次数一致。解码、置信度过滤、类别过滤与 NMS 应全部放在postprocess中这样各后端的耗时统计才可横向比较tests/unit/detectors/test_base_contract.py 对此有专门的契约测试包括列数校验、AABB/OBB 空张量保持、masks 行对齐等场景。3. 在registry.py中注册后端在DETECTOR_BACKENDS中添加一个家族匹配函数与一条DetectorBackendSpec。最少需要一个用于识别模型文件名的匹配函数可选的可自动安装包要求模块路径类名。参考内置 spec 的结构DetectorBackendSpec( matchesis_yolox_model, moduleboxmot.detectors.yolox, class_nameYoloXDetector, requirements(yolox, tabulate, thop), requirement_args{yolox: (--no-deps,)}, )4.可选添加检测器配置以支持配置驱动的默认值如果希望后端支持按模型的默认参数或自动下载在 boxmot/configs/detectors 下添加 YAML 即可。这对用户只需给一个模型名就能用合理默认值运行的场景是可选的但推荐的做法。5. 保持公共包装器不变Detector类detector.py已经替你处理了数据源迭代与批处理setup_source/stream_inference单帧/多帧/流式三种调用语义_is_single_inference_source判定预热warmup用一张虚拟帧跑一次前向生命周期回调on_predict_start/on_predict_batch_start/on_predict_postprocess_end/on_predict_end返回原始数组或Detectionsas_detections参数切换。新后端通常不需要重新实现这一层工作流只需专注模型加载与批量推理。包装器还会在postprocess阶段回填orig_img与源路径等元数据。三个内置后端的实现要点从源码看三个后端都以三阶段 Detections输出的方式落地但适配细节各不相同Ultralytics 后端ultralytics.py包装 Ultralytics 的BasePredictor把preprocessletterbox 张量上载、process纯前向、postprocessNMS 坐标还原逐一映射到 predictor 的三个阶段使计时仪表可以独立统计各阶段耗时。它按result.obb/result.boxes分支提取 AABB 或 OBB 输出并支持分割模型-seg的 masks 提取与去 letterbox 缩放权重缺失时优先走 profile 的uri否则用 Ultralytics 的attempt_download_asset。YOLOX 后端yolox.py基于yolox包的get_exp构建实验配置preprocess实现 ByteTrack 同款 letterbox均值 0.485/0.456/0.406、方差 0.229/0.224/0.225process在torch.no_grad()下前向postprocess通过yolox.utils.postprocess解码并做obj_conf * class_conf合并与坐标还原它还带有一个面向 MPS 设备的decode_outputs猴子补丁。RT-DETR 后端rtdetr.py使用 Hugging Face Transformers 的RTDetrImageProcessor/RTDetrV2ForObjectDetectionpreprocess将 BGR 数组转 RGB PIL 图像并构建 processor 输入postprocess调用post_process_object_detection解码后经filter_detections做置信度/类别过滤。模型引用会被规范化为PekingU/name形式的 HF 模型 ID。推荐冒烟检查新增检测器或配置后建议按以下顺序验证uv run python -m boxmot.engine.cli track --source path/to/image_or_video --detector path/to/weights.pt uv run python -m boxmot.engine.cli eval --experiment mot17-ablation-yolox-lmbn --detector path/to/weights.pt uv run pytest tests/unit/detectors tests/unit/engine/tracking/test_inference.py第一条命令验证单帧/视频上的实时跟踪路径第二条验证实验评估路径第三条运行后端契约与推理工作流的单元测试。实用总结为现有家族换新权重通常只需放好权重推荐models/下、在文件名中保留家族标记、可选地补充一份 detector YAML然后通过--detector直接运行。新增检测器家族在boxmot/detectors/下新增后端模块并遵循BaseDetectorBackend三阶段契约在registry.py中注册匹配函数与DetectorBackendSpec工作流层的Detector包装器无需改动。检测器 profile统一存放在 boxmot/configs/detectors负责 box 类型、类别、推理默认值与命名 checkpoint 的声明式管理。权重按约定放在models/但 BoxMOT 也支持使用目录之外的显式路径。这套文件名路由 三阶段契约 YAML profile的架构让 BoxMOT 既能低成本复用主流检测器权重也能以标准化的方式扩展任意新检测器且不会侵入跟踪、评估与可视化等上层工作流。【免费下载链接】boxmotBoxMOT: Pluggable Python and C SOTA multi-object tracking modules with support for axis-aligned and oriented bounding boxes项目地址: https://gitcode.com/GitHub_Trending/bo/boxmot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考