BoxMOT Mode Defaults 全解析runtime.yaml 如何統(tǒng)一驅(qū)動 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導(dǎo)讀本文以 docs/config/modes.md 為骨架系統(tǒng)講解 BoxMOT 中央默認(rèn)配置boxmot/configs/runtime.yaml它是 CLI 與高層BoxMOTPython 門面共同解析追蹤工作流默認(rèn)值的唯一事實來源。讀完本文你將掌握shared/runtime/ 各模式段的字段語義與合并優(yōu)先級理解n_threads: auto、tracker_backend等關(guān)鍵項在 boxmot/engine/config.py 中的歸一化邏輯并能結(jié)合實際命令定制出可復(fù)現(xiàn)的 track、generate、eval、tune、research 工作流。一、什么是 Mode Defaults一份文件管住所有追蹤模式BoxMOT 將「多目標(biāo)追蹤工作流」的默認(rèn)值集中存放在單一 YAML 文件boxmot/configs/runtime.yaml中文檔與倉庫均將其稱為Mode Defaults模式默認(rèn)值。其核心職責(zé)包括三部分見 docs/config/modes.md共享的檢測器與 ReID 選擇shared段給出全庫默認(rèn)的detector與reid即「沒有顯式指定時用哪個模型」?？缒Ｊ酵ㄓ眠\行時選項runtime段集中了imgsz、device、batch_size、postprocessing等與具體模式無關(guān)的選項。命令級專屬默認(rèn)值track、generate、eval、tune、research五個段分別給出各自工作流的專屬默認(rèn)如track.source、tune.n_trials、research.max_metric_calls。值得注意的是作用域邊界ReID 訓(xùn)練默認(rèn)值保留在boxmot/reid/training/configs/defaults.yamlReID 導(dǎo)出默認(rèn)值保留在boxmot/reid/exporters/defaults.yaml二者刻意不放入 runtime.yaml——這正是「追蹤運行時配置」與「訓(xùn)練/導(dǎo)出配置」的分層設(shè)計boxmot/configs/README.md 明確說明 ReID 訓(xùn)練 recipes 與導(dǎo)出 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()的函數(shù)簽名默認(rèn)值同樣直接引用BOXMOT_DEFAULTS.*pipeline.py最終經(jīng)boxmot/api/_args.py的build_*_args()匯入build_mode_namespace()。也就是說無論你是敲boxmot track命令還是寫B(tài)oxMOT().track(...)默認(rèn)行為都由同一份 runtime.yaml 決定。二、當(dāng)前默認(rèn)值全量盤點對照源碼逐一解讀倉庫中boxmot/configs/runtime.yaml的實際內(nèi)容比文檔展示的示例更完整下面按段完整列出并補充源碼側(cè)的含義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 段默認(rèn)模型選擇鍵默認(rèn)值說明detectoryolov8n未顯式指定時的檢測權(quán)重名經(jīng)ensure_model_extension()會解析為WEIGHTS/yolov8n.ptreidosnet_x0_25_msmt17未顯式指定時的 ReID 權(quán)重名同樣解析為.pt路徑runtime 段跨模式通用運行時選項鍵默認(rèn)值說明imgsznull為空時由所選檢測器配置決定輸入尺寸CLI 幫助文本說明「read from the selected detector config」fpsnull幀率覆蓋保存的追蹤視頻 FPS 或評估目標(biāo) FPSconfnull最小置信度閾值為空時回退到檢測器配置兜底 0.01iou0.7NMS 的 IoU 閾值devicecpu計算設(shè)備如0、0,1,2,3或cpubatch_size16檢測/嵌入的 micro-batch 大小auto_batchtrue用一次空跑探測 GPU 顯存以選取安全 batch 大小resumetrue從進度檢查點續(xù)跑檢測/嵌入生成n_threadsauto圖像解碼與緩存追蹤的 CPU worker 上限auto在加載時解析為min(8, max(1, os.cpu_count() or 1))projectruns結(jié)果保存目錄project/namenameexp結(jié)果保存子目錄exist_okfalse為 true 時允許復(fù)用已存在的project/name不自動遞增halffalse是否啟用 FP16 半精度推理vid_stride1視頻幀率步長隔幀采樣cifalseCI 模式下復(fù)用已有 runs無 UItrackerbytetrack默認(rèn)追蹤器可選集合由TRACKER_MAPPING定義tracker_backendpython追蹤器實現(xiàn)后端python或cpp原生 C 支持 botsort/bytetrack/occluboost/ocsort/sfsortverbosefalse打印詳細(xì)日志show_timingfalse評估后打印運行時計時摘要agnostic_nmsfalse類無關(guān) NMSpostprocessingnone追蹤器輸出后處理逗號分隔按序應(yīng)用none \| gsi \| gbrc \| gta如gbrc,gtashowfalse窗口顯示追蹤結(jié)果show_labelstrue顯示/隱藏檢測標(biāo)簽show_conftrue顯示/隱藏檢測置信度show_trajectoriesfalse疊加歷史軌跡show_kf_predsfalse顯示卡爾曼濾波預(yù)測save_txtfalse結(jié)果保存為.txt文件save_cropfalse保存裁剪后的檢測圖savefalse保存標(biāo)注視頻line_widthnull邊界框線寬per_classfalse是否按類別分別追蹤target_idnull需要高亮為綠色的目標(biāo) ID源碼佐證n_threads: auto的實際解析發(fā)生在_resolve_default_value()加載時即轉(zhuǎn)換為具體整數(shù)config.pyget_mode_defaults()返回的都是歸一化后的值因此tests/unit/configs/test_configs.py中斷言isinstance(defaults[n_threads], int)且 1test_configs.py。命令級段track / generate / eval / tune / researchtrack默認(rèn)source: 0攝像頭benchmark與split默認(rèn)空字符串供數(shù)據(jù)集追蹤時填充。generateexperiment與source均默認(rèn)null二者必須提供其一CLI 中_require_generate_input會校驗「要么 experiment 要么 source不能都傳」。eval除experiment/dataset/source外dataset默認(rèn)為null允許模型無關(guān)的--dataset評估。tunen_trials: 10默認(rèn)優(yōu)化目標(biāo)objectives: [HOTA]maximize/minimize為空時在TuneModeDefaults.from_mapping()中回退為objectives或(HOTA,)config.py。researchGEPA 驅(qū)動的追蹤器代碼研究默認(rèn)值proposal_model默認(rèn)openai/gpt-5.4max_metric_calls: 24單次研究最多 24 次基準(zhǔn)評估eval_timeout: 900.0單次評估硬超時 900 秒。邊界說明eval_timeout是「每次基準(zhǔn)評估的硬超時」而非整個 research 任務(wù)的總時限二者不要混淆cli.py 幫助文本原文為 hard timeout in seconds for each benchmark evaluation。三、合并優(yōu)先級shared → runtime → mode命令行/API 顯式值最優(yōu)先runtime.yaml之所以能同時服務(wù)五個模式靠的是 boxmot/engine/config.py 中_merged_mode_defaults()的逐層合并策略先取shared段作為基底若模式屬于RUNTIME_MODES {track, generate, eval, tune, research}再用runtime段覆蓋共享鍵例如tracker、device最后用模式專屬段如tune覆蓋該模式特有鍵如n_trials在build_mode_namespace()中調(diào)用方傳入的 payload來自 CLI 顯式參數(shù)或 Python API 關(guān)鍵字再覆蓋一次。關(guān)鍵設(shè)計是顯式值追蹤_explicit_cli_keys()cli.py通過 Click 的ParameterSource判斷哪些選項是用戶真正在命令行寫過的而 Python API 則通過_explicit_api_keys()與detector_explicit/reid_explicit/tracker_explicit等標(biāo)記傳遞。這保證「用戶顯式傳--device 0」與「默認(rèn)恰好是cpu」被區(qū)別對待——前者會正確覆蓋所有層級后者則正常回退。驗證這一鏈路的最直接證據(jù)是測試 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會經(jīng)過parse_tracker_spec()解析允許在tracker字符串中直接攜帶后端信息例如botsortcpp這類規(guī)格語法。四、五大模式的實戰(zhàn)組合從默認(rèn)值出發(fā)定制命令1. track直接用默認(rèn)值或按需覆蓋默認(rèn)配置下bytetrackyolov8nosnet_x0_25_msmt17 攝像頭boxmot track --source 0 --show顯式指定模型與追蹤器示例取自 CLI 內(nèi)置幫助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 等價寫法默認(rèn)值來自BOXMOT_DEFAULTS.trackfrom boxmot.api import BoxMOT model BoxMOT() # detector/reid/tracker 均取 runtime.yaml 默認(rèn) result model.track(sourcevideo.mp4, saveTrue)一個 CLI 特化行為值得注意當(dāng)source是實時輸入純數(shù)字或含://且用戶沒有顯式指定show/save/save_txt時_apply_track_cli_defaults()會自動打開showTruecli.py。2. generate先準(zhǔn)備檢測與嵌入緩存generate只接受「experiment 或 source」二選一# 基于實驗配置生成 boxmot generate --experiment mot17-ablation-yolox-lmbn # 直接基于數(shù)據(jù)集根目錄生成 boxmot generate --source /path/to/mot17runtime段中的batch_size、auto_batch、resume、n_threads在這里直接生效——resume: true使得中途中斷后可續(xù)跑auto_batch: true會先用一次空跑探測顯存選擇安全 batch。3. eval模型無關(guān)與實驗驅(qū)動兩種評估# 模型無關(guān)評估detector/ReID 由調(diào)用方?jīng)Q定 boxmot eval --dataset mot17 --split ablation --tracker boosttrack # 實驗驅(qū)動評估檢測器、ReID、數(shù)據(jù)集全部由實驗配置鎖定 boxmot eval --experiment mot17-ablation-yolox-lmbn --tracker boosttrackCLI 校驗邏輯_require_eval_input()保證--experiment與--dataset恰好提供其一cli.py。Python 側(cè)對應(yīng)BoxMOT().val()其簽名默認(rèn)值同樣逐項取自BOXMOT_DEFAULTS.evalpipeline.py。4. tune默認(rèn) 10 次試驗、HOTA 最大化boxmot tune --experiment mot17-ablation-yolox-lmbn --tracker deepocsort --n-trials 10tune段的objectives: [HOTA]決定默認(rèn)優(yōu)化目標(biāo)maximize/minimize為空時Python API 的_split_objectives_by_direction()會按預(yù)定義方向表如IDSW_rate歸入最小化api/_args.py自動拆分。可用的最大/最小化指標(biāo)包括HOTA、MOTA、IDF1、AssA、AssRe、IDSW、IDs、IDSW_rate并支持大小寫別名。5. researchGEPA 驅(qū)動的追蹤器代碼演化boxmot research --experiment mot17-ablation-yolox-lmbn --tracker bytetrack \ --proposal-model openai/gpt-5.4 --max-metric-calls 24research段是唯一包含「AI 提案」相關(guān)默認(rèn)值的模式段proposal_model、proposal_api_key、proposal_api_key_envAPI Key 環(huán)境變量名、max_metric_calls、eval_timeout以及一組懲罰/容差參數(shù)hota_penalty、idf1_penalty、mota_penalty與對應(yīng)*_tolerance用于約束與基線相比的指標(biāo)回退幅度。五、超出本文范圍的默認(rèn)值train 與 exportruntime.yaml只管理追蹤工作流。文檔明確提示 ReID 訓(xùn)練與導(dǎo)出的默認(rèn)值分別位于訓(xùn)練boxmot/reid/training/configs/defaults.yaml含epochs、lr、batch_size、損失權(quán)重等加載邏輯見load_training_defaults()同時訓(xùn)練還支持 recipes如lmbn_n逐項覆蓋導(dǎo)出boxmot/reid/exporters/defaults.yaml含include、opset、workspace、CoreML/TFLite 量化參數(shù)等加載邏輯見load_export_defaults()。在_load_mode_defaults()中export與train兩個模式會額外從各自 YAML 讀取再合并進同一份BoxMOTDefaults對象config.py。因此BoxMOTDefaults是一個覆蓋「追蹤 訓(xùn)練 導(dǎo)出」的統(tǒng)一門面但每個模式的事實來源仍然彼此獨立、職責(zé)分明。六、常見問題與排查建議Q1為什么我改runtime.yaml后boxmot eval行為沒變get_mode_defaults()/BOXMOT_DEFAULTS在導(dǎo)入時讀取 YAML。修改文件后需要重啟 Python 進程CLI 每次運行都是新進程天然生效長時間運行的 Python API 會話需重新導(dǎo)入。Q2--tracker-backend cpp和--tracking-backend cpp有什么區(qū)別--tracker-backend選擇追蹤器實現(xiàn)python/cppcli.py--tracking-backend是 eval/tune/research 緩存回放執(zhí)行器process/thread/cpp其cpp只是作為--tracker-backend cpp的兼容別名cli.py。Q3默認(rèn)device: cpu會不會很慢會。runtime.yaml 刻意保持「開箱即用」的保守默認(rèn)生產(chǎn)評估請顯式指定--device 0或 Python API 傳device0配合auto_batch: true會自動探測合適 batch。Q4如何驗證默認(rèn)值是否正確加載單測 tests/unit/configs/test_configs.py 是對runtime.yaml合并邏輯的權(quán)威驗證它斷言n_threads被歸一化為整數(shù)、tracker_backend python、project被轉(zhuǎn)為Path等。也可以直接運行python -c from boxmot.engine.config import BOXMOT_DEFAULTS; print(BOXMOT_DEFAULTS.track)查看歸一化后的結(jié)果?？偨Y(jié)runtime.yaml是 BoxMOT 追蹤工作流的「單一默認(rèn)事實源」shared定義模型runtime定義跨模式運行時行為五個模式段定義命令級專屬參數(shù)經(jīng)_merged_mode_defaults()三層合并與build_mode_namespace()歸一化后同時供給 CLI 與BoxMOTPython 門面并通過顯式參數(shù)追蹤保證用戶意圖始終優(yōu)先。理解這份文件的層級結(jié)構(gòu)、合并順序與關(guān)鍵項的歸一化細(xì)節(jié)是精準(zhǔn)定制 BoxMOT 各模式行為、寫出可復(fù)現(xiàn)實驗的第一步?！久赓M下載鏈接】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創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考