BoxMOT Mode Defaults 全解析runtime.yaml 如何统一驱动 track / eval / tune / research 五大模式【免费下载链接】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导读本文以 docs/config/modes.md 为骨架系统讲解 BoxMOT 中央默认配置boxmot/configs/runtime.yaml它是 CLI 与高层BoxMOTPython 门面共同解析追踪工作流默认值的唯一事实来源。读完本文你将掌握shared/runtime/ 各模式段的字段语义与合并优先级理解n_threads: auto、tracker_backend等关键项在 boxmot/engine/config.py 中的归一化逻辑并能结合实际命令定制出可复现的 track、generate、eval、tune、research 工作流。一、什么是 Mode Defaults一份文件管住所有追踪模式BoxMOT 将「多目标追踪工作流」的默认值集中存放在单一 YAML 文件boxmot/configs/runtime.yaml中文档与仓库均将其称为Mode Defaults模式默认值。其核心职责包括三部分见 docs/config/modes.md共享的检测器与 ReID 选择shared段给出全库默认的detector与reid即「没有显式指定时用哪个模型」。跨模式通用运行时选项runtime段集中了imgsz、device、batch_size、postprocessing等与具体模式无关的选项。命令级专属默认值track、generate、eval、tune、research五个段分别给出各自工作流的专属默认如track.source、tune.n_trials、research.max_metric_calls。值得注意的是作用域边界ReID 训练默认值保留在boxmot/reid/training/configs/defaults.yamlReID 导出默认值保留在boxmot/reid/exporters/defaults.yaml二者刻意不放入 runtime.yaml——这正是「追踪运行时配置」与「训练/导出配置」的分层设计boxmot/configs/README.md 明确说明 ReID 训练 recipes 与导出 defaults 不属于追踪运行时配置范畴。谁在消费这份文件从源码看消费方有两条链路最终都收敛到 boxmot/engine/config.py 的_load_mode_defaults()CLI 链路boxmot/engine/cli.py顶部将BOXMOT_DEFAULTS拆分为RUNTIME_DEFAULTS、TRACK_DEFAULTS、TUNE_DEFAULTS、RESEARCH_DEFAULTS、SHARED_DEFAULTS等所有 Click 选项如--imgsz、--tracker的default都从这些对象取值cli.py。Python API 链路高层门面BoxMOT的每个方法track()、generate()、val()、tune()、research()的函数签名默认值同样直接引用BOXMOT_DEFAULTS.*pipeline.py最终经boxmot/api/_args.py的build_*_args()汇入build_mode_namespace()。也就是说无论你是敲boxmot track命令还是写BoxMOT().track(...)默认行为都由同一份 runtime.yaml 决定。二、当前默认值全量盘点对照源码逐一解读仓库中boxmot/configs/runtime.yaml的实际内容比文档展示的示例更完整下面按段完整列出并补充源码侧的含义shared: detector: yolov8n reid: osnet_x0_25_msmt17 runtime: imgsz: null fps: null conf: null iou: 0.7 device: cpu batch_size: 16 auto_batch: true resume: true n_threads: auto project: runs name: exp exist_ok: false half: false vid_stride: 1 ci: false tracker: bytetrack tracker_backend: python verbose: false show_timing: false agnostic_nms: false postprocessing: none show: false show_labels: true show_conf: true show_trajectories: false show_kf_preds: false save_txt: false save_crop: false save: false line_width: null per_class: false target_id: null track: source: 0 benchmark: split: generate: experiment: null source: null benchmark: split: eval: experiment: null dataset: null source: null benchmark: split: tune: experiment: null source: null benchmark: split: n_trials: 10 objectives: - HOTA maximize: [] minimize: [] research: experiment: null source: null benchmark: split: proposal_model: openai/gpt-5.4 proposal_api_key: null proposal_api_key_env: null max_metric_calls: 24 eval_timeout: 900.0 keep_workspace: false hota_penalty: 0.0 idf1_penalty: 1.0 mota_penalty: 1.0 hota_tolerance: 0.0 idf1_tolerance: 0.0 mota_tolerance: 0.0shared 段默认模型选择键默认值说明detectoryolov8n未显式指定时的检测权重名经ensure_model_extension()会解析为WEIGHTS/yolov8n.ptreidosnet_x0_25_msmt17未显式指定时的 ReID 权重名同样解析为.pt路径runtime 段跨模式通用运行时选项键默认值说明imgsznull为空时由所选检测器配置决定输入尺寸CLI 帮助文本说明「read from the selected detector config」fpsnull帧率覆盖保存的追踪视频 FPS 或评估目标 FPSconfnull最小置信度阈值为空时回退到检测器配置兜底 0.01iou0.7NMS 的 IoU 阈值devicecpu计算设备如0、0,1,2,3或cpubatch_size16检测/嵌入的 micro-batch 大小auto_batchtrue用一次空跑探测 GPU 显存以选取安全 batch 大小resumetrue从进度检查点续跑检测/嵌入生成n_threadsauto图像解码与缓存追踪的 CPU worker 上限auto在加载时解析为min(8, max(1, os.cpu_count() or 1))projectruns结果保存目录project/namenameexp结果保存子目录exist_okfalse为 true 时允许复用已存在的project/name不自动递增halffalse是否启用 FP16 半精度推理vid_stride1视频帧率步长隔帧采样cifalseCI 模式下复用已有 runs无 UItrackerbytetrack默认追踪器可选集合由TRACKER_MAPPING定义tracker_backendpython追踪器实现后端python或cpp原生 C 支持 botsort/bytetrack/occluboost/ocsort/sfsortverbosefalse打印详细日志show_timingfalse评估后打印运行时计时摘要agnostic_nmsfalse类无关 NMSpostprocessingnone追踪器输出后处理逗号分隔按序应用none \| gsi \| gbrc \| gta如gbrc,gtashowfalse窗口显示追踪结果show_labelstrue显示/隐藏检测标签show_conftrue显示/隐藏检测置信度show_trajectoriesfalse叠加历史轨迹show_kf_predsfalse显示卡尔曼滤波预测save_txtfalse结果保存为.txt文件save_cropfalse保存裁剪后的检测图savefalse保存标注视频line_widthnull边界框线宽per_classfalse是否按类别分别追踪target_idnull需要高亮为绿色的目标 ID源码佐证n_threads: auto的实际解析发生在_resolve_default_value()加载时即转换为具体整数config.pyget_mode_defaults()返回的都是归一化后的值因此tests/unit/configs/test_configs.py中断言isinstance(defaults[n_threads], int)且 1test_configs.py。命令级段track / generate / eval / tune / researchtrack默认source: 0摄像头benchmark与split默认空字符串供数据集追踪时填充。generateexperiment与source均默认null二者必须提供其一CLI 中_require_generate_input会校验「要么 experiment 要么 source不能都传」。eval除experiment/dataset/source外dataset默认为null允许模型无关的--dataset评估。tunen_trials: 10默认优化目标objectives: [HOTA]maximize/minimize为空时在TuneModeDefaults.from_mapping()中回退为objectives或(HOTA,)config.py。researchGEPA 驱动的追踪器代码研究默认值proposal_model默认openai/gpt-5.4max_metric_calls: 24单次研究最多 24 次基准评估eval_timeout: 900.0单次评估硬超时 900 秒。边界说明eval_timeout是「每次基准评估的硬超时」而非整个 research 任务的总时限二者不要混淆cli.py 帮助文本原文为 hard timeout in seconds for each benchmark evaluation。三、合并优先级shared → runtime → mode命令行/API 显式值最优先runtime.yaml之所以能同时服务五个模式靠的是 boxmot/engine/config.py 中_merged_mode_defaults()的逐层合并策略先取shared段作为基底若模式属于RUNTIME_MODES {track, generate, eval, tune, research}再用runtime段覆盖共享键例如tracker、device最后用模式专属段如tune覆盖该模式特有键如n_trials在build_mode_namespace()中调用方传入的 payload来自 CLI 显式参数或 Python API 关键字再覆盖一次。关键设计是显式值追踪_explicit_cli_keys()cli.py通过 Click 的ParameterSource判断哪些选项是用户真正在命令行写过的而 Python API 则通过_explicit_api_keys()与detector_explicit/reid_explicit/tracker_explicit等标记传递。这保证「用户显式传--device 0」与「默认恰好是cpu」被区别对待——前者会正确覆盖所有层级后者则正常回退。验证这一链路的最直接证据是测试 test_build_mode_namespace_uses_shared_runtime_defaults仅传入{experiment: mot17-mini}时命名空间自动获得detector [DEFAULT_DETECTOR]、reid [DEFAULT_REID]、tracker get_mode_default(eval, tracker)、tracker_backend python。另外两个容易忽略的归一化行为config.pydetector/reid在generate、eval、tune、research模式下被包装为列表可传多个模型而track模式保持单值tracker与tracker_backend会经过parse_tracker_spec()解析允许在tracker字符串中直接携带后端信息例如botsortcpp这类规格语法。四、五大模式的实战组合从默认值出发定制命令1. track直接用默认值或按需覆盖默认配置下bytetrackyolov8nosnet_x0_25_msmt17 摄像头boxmot track --source 0 --show显式指定模型与追踪器示例取自 CLI 内置帮助cli.pyboxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker deepocsort --source 0 --show boxmot track --detector yolov8n --reid osnet_x0_25_msmt17 --tracker botsort --source video.mp4 --savePython API 等价写法默认值来自BOXMOT_DEFAULTS.trackfrom boxmot.api import BoxMOT model BoxMOT() # detector/reid/tracker 均取 runtime.yaml 默认 result model.track(sourcevideo.mp4, saveTrue)一个 CLI 特化行为值得注意当source是实时输入纯数字或含://且用户没有显式指定show/save/save_txt时_apply_track_cli_defaults()会自动打开showTruecli.py。2. generate先准备检测与嵌入缓存generate只接受「experiment 或 source」二选一# 基于实验配置生成 boxmot generate --experiment mot17-ablation-yolox-lmbn # 直接基于数据集根目录生成 boxmot generate --source /path/to/mot17runtime段中的batch_size、auto_batch、resume、n_threads在这里直接生效——resume: true使得中途中断后可续跑auto_batch: true会先用一次空跑探测显存选择安全 batch。3. eval模型无关与实验驱动两种评估# 模型无关评估detector/ReID 由调用方决定 boxmot eval --dataset mot17 --split ablation --tracker boosttrack # 实验驱动评估检测器、ReID、数据集全部由实验配置锁定 boxmot eval --experiment mot17-ablation-yolox-lmbn --tracker boosttrackCLI 校验逻辑_require_eval_input()保证--experiment与--dataset恰好提供其一cli.py。Python 侧对应BoxMOT().val()其签名默认值同样逐项取自BOXMOT_DEFAULTS.evalpipeline.py。4. tune默认 10 次试验、HOTA 最大化boxmot tune --experiment mot17-ablation-yolox-lmbn --tracker deepocsort --n-trials 10tune段的objectives: [HOTA]决定默认优化目标maximize/minimize为空时Python API 的_split_objectives_by_direction()会按预定义方向表如IDSW_rate归入最小化api/_args.py自动拆分。可用的最大/最小化指标包括HOTA、MOTA、IDF1、AssA、AssRe、IDSW、IDs、IDSW_rate并支持大小写别名。5. researchGEPA 驱动的追踪器代码演化boxmot research --experiment mot17-ablation-yolox-lmbn --tracker bytetrack \ --proposal-model openai/gpt-5.4 --max-metric-calls 24research段是唯一包含「AI 提案」相关默认值的模式段proposal_model、proposal_api_key、proposal_api_key_envAPI Key 环境变量名、max_metric_calls、eval_timeout以及一组惩罚/容差参数hota_penalty、idf1_penalty、mota_penalty与对应*_tolerance用于约束与基线相比的指标回退幅度。五、超出本文范围的默认值train 与 exportruntime.yaml只管理追踪工作流。文档明确提示 ReID 训练与导出的默认值分别位于训练boxmot/reid/training/configs/defaults.yaml含epochs、lr、batch_size、损失权重等加载逻辑见load_training_defaults()同时训练还支持 recipes如lmbn_n逐项覆盖导出boxmot/reid/exporters/defaults.yaml含include、opset、workspace、CoreML/TFLite 量化参数等加载逻辑见load_export_defaults()。在_load_mode_defaults()中export与train两个模式会额外从各自 YAML 读取再合并进同一份BoxMOTDefaults对象config.py。因此BoxMOTDefaults是一个覆盖「追踪 训练 导出」的统一门面但每个模式的事实来源仍然彼此独立、职责分明。六、常见问题与排查建议Q1为什么我改runtime.yaml后boxmot eval行为没变get_mode_defaults()/BOXMOT_DEFAULTS在导入时读取 YAML。修改文件后需要重启 Python 进程CLI 每次运行都是新进程天然生效长时间运行的 Python API 会话需重新导入。Q2--tracker-backend cpp和--tracking-backend cpp有什么区别--tracker-backend选择追踪器实现python/cppcli.py--tracking-backend是 eval/tune/research 缓存回放执行器process/thread/cpp其cpp只是作为--tracker-backend cpp的兼容别名cli.py。Q3默认device: cpu会不会很慢会。runtime.yaml 刻意保持「开箱即用」的保守默认生产评估请显式指定--device 0或 Python API 传device0配合auto_batch: true会自动探测合适 batch。Q4如何验证默认值是否正确加载单测 tests/unit/configs/test_configs.py 是对runtime.yaml合并逻辑的权威验证它断言n_threads被归一化为整数、tracker_backend python、project被转为Path等。也可以直接运行python -c from boxmot.engine.config import BOXMOT_DEFAULTS; print(BOXMOT_DEFAULTS.track)查看归一化后的结果。总结runtime.yaml是 BoxMOT 追踪工作流的「单一默认事实源」shared定义模型runtime定义跨模式运行时行为五个模式段定义命令级专属参数经_merged_mode_defaults()三层合并与build_mode_namespace()归一化后同时供给 CLI 与BoxMOTPython 门面并通过显式参数追踪保证用户意图始终优先。理解这份文件的层级结构、合并顺序与关键项的归一化细节是精准定制 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），仅供参考