企业官网建设流程全解析

BoxMOT 多目标跟踪部署完整指南：CPU、GPU 到 C++ 原生，11 种跟踪器如何选

【免费下载链接】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

BoxMOT是一个"检测器无关"的多目标跟踪（MOT）工具包：它把 YOLO 等任意模型的检测输出，交给可插拔的跟踪器，稳定地给出每个目标的持续 ID。它同时提供 Python 与 C++ 两条实现路径，支持水平框（AABB）和旋转框（OBB）两种几何，内置 11 种主流跟踪算法（ByteTrack、BoT-SORT、StrongSORT、DeepOCSort、OccluBoost 等），并覆盖从实时跟踪、数据集评测、参数调优到 ReID 模型训练的完整工作流。下面从安装、设备选择、算法挑选到生产部署，一步步带你把它用起来。

一、先看懂架构：为什么说 BoxMOT 是"可插拔"的跟踪框架

BoxMOT 的设计原则是组件独立、按需组合，依赖方向是单向的：

structures -> domain components -> pipelines -> engine

• 检测器（detectors）：任意模型都可以接入，内置 YOLO 系列、YOLOX、RT-DETR 等后端；
• 分割器（segmentors）：如 EdgeTAM，可为检测框生成实例掩码；
• 外观编码器（reid）：OSNet、LMBN 等 ReID 模型，为跟踪器提供外观特征；
• 跟踪器（trackers）：每个算法一个独立目录，互不干扰，可随时替换。

这种结构带来的直接好处是：你想换检测模型、换 ReID 权重、换跟踪算法，都只改一个参数，其他部分不用动。跟踪器源码位于 boxmot/trackers/，配置模板集中在 boxmot/configs/trackers/。

二、三步完成安装：从 pip 一行命令到 GPU 环境

BoxMOT 支持 Python3.10到3.13，最简安装只需要两行：

pip install boxmot # 安装 CLI、Python API、全部跟踪器和核心 ReID 组件 boxmot --help # 验证安装成功

如果你的项目要跑检测器，还可以追加对应的功能包，例如boxmot install --extra yolo会装上 Ultralytics 和 YOLOX。如果你需要锁定 CPU 或 CUDA 环境（源码方式），可以选择互斥的cpu或cu130两套 PyTorch profile。

部署上更省事的选择是官方 Docker 镜像，它一次给出了四种生产目标：

CPU 镜像不含任何 CUDA 运行时，可以直接跑在无显卡的服务器上；GPU 镜像内置锁定的 CUDA 13.0 Torch 轮子，需要宿主机有兼容的 NVIDIA 驱动。镜像细节和挂载方式见 docker/README.md 与安装文档。

三、一条命令开始跟踪：track 命令与 CPU/GPU 设备选择

装好之后，最常用的是track模式。以"用 YOLO 检测 + BoT-SORT 跟踪一个视频"为例：

boxmot track \ --source video.mp4 \ --detector yolov8n \ --reid osnet_x0_25_msmt17 \ --tracker botsort \ --save

这条命令的白话解释是：从video.mp4读帧，用 yolov8n 检测目标，用 osnet_x0_25_msmt17 提取外观特征，交给 botsort 分配 ID，最后把带框 ID 的视频存下来。

几个高频选项值得知道：

• --source：可以是视频文件、图片目录、摄像头编号（如0）或 URL 流；
• --device：指定执行设备。--device cpu跑 CPU，--device mps跑 Apple 芯片，--device cuda:0或0跑第一块 GPU。跟踪、物化、ReID 推理、导出共用这一套选择器，且会先校验设备可用性再加载模型；
• --show：实时预览，--save保存标注视频；
• --geometry aabb|obb：切换水平框/旋转框。做航拍等俯视场景时，配--geometry obb加一个 OBB 检测器（如yolo11n-obb.pt）即可，OBB 角度以弧度为单位且在时间上保持连续。

设备怎么选？经验法则是：ByteTrack、OcSort 这类纯运动跟踪器不消费图像像素，在 CPU 上就很轻松，适合低帧率流和成本敏感的边缘场景；而 StrongSORT（需要 ECC 像素特征）、BoT-SORT 等依赖 ReID 的算法，把检测、ReID 都放到 GPU 上收益最大。官方对每种工作负载的 extras 组合（yolo、evolve、service、onnx、openvino、tflite等）都有表格说明，见安装指南。

四、11 种跟踪器怎么挑：一张表定去留

BoxMOT 的跟踪器分三类：纯运动（只看框和运动模型）、运动+外观（可选 ReID 特征）、多模态（掩码或 3D 传感器是核心输入）。项目内置 11 个，能力矩阵如下：

选择建议非常直接：

• 想要一个快的基线→bytetrack，不碰图像像素，CPU 友好；
• 遮挡多、要求 ID 一致→botsort、strongsort、deepocsort、hybridsort、boosttrack、occluboost任选，按基准成绩和算力预算挑；
• 有 3D 检测和标定→ 走 Python 的eagermot；
• 有全帧掩码→maf_hda。

完整的能力矩阵和每个跟踪器的输入要求（embedding、掩码、3D 框、标定等）在跟踪器总览里都有逐行说明。

五、性能基准：MOT17 官方消融组的真实成绩

项目 README 内置了统一的基准测试（MOT17 ablation、SportsMOT val、MMOT OBB test 三组），核心指标 HOTA 越高越好。摘选 MOT17 组的成绩：

可以看到：纯运动的 bytetrack/ocsort 靠速度取胜（无像素依赖），而引入外观特征的 occluboost、botsort 在 HOTA/IDF1 上明显领先——IDF1 衡量身份一致性，这正是"ID 不跳"的关键指标。括号内为对应 C++ 原生实现的同口径成绩，两条路径指标一致，方便你按性能需求切换实现语言。

六、嵌入自己的项目：Python API 最小示例

不想走 CLI，也可以把组件直接嵌进应用。最典型的用法是"NumPy 检测框直接进、跟踪 ID 直接出"：

import numpy as np from boxmot import OccluBoost tracker = OccluBoost() # 默认 CPU，构造即用 dets = np.array([[100, 200, 300, 400, 0.9, 0]]) # x1, y1, x2, y2, 置信度, 类别 frame = np.zeros((480, 640, 3), dtype=np.uint8) # BGR 图像 tracks = tracker.update(dets, frame) print(tracks[:, 4].astype(int)) # 输出的跟踪 ID 列

白话解释：update每帧调一次，传入检测框矩阵和当前帧图像，返回每个目标的跟踪 ID，第 5 列就是你要的 ID。要 OBB 则把is_obb=True，检测框换成(cx, cy, w, h, angle, 置信度, 类别)七元组即可。

更结构化的方式是create_tracker(TrackerSpec(...))工厂，可以显式指定后端（backend="cpp"）和几何（geometry="obb"），并随时查看tracker.capabilities与tracker.requirements确认它需要什么输入。完整 API 参考见 docs/python/high-level.md。

七、生产部署的两个进阶选项：C++ 原生后端与 HTTP 跟踪服务

1. C++ 原生后端（--tracker-backend cpp）

ByteTrack、BoT-SORT、OcSort、OccluBoost、SFSORT 五个跟踪器都有 C++ 实现，与 Python 路径指标一致。首次选择 cpp 后端时会按需编译（需要 C++17、CMake 3.16+、OpenCV 4.x、Eigen3），也可以提前用boxmot build统一编译。C++ 源码位于 boxmot/native/cpp/，如果你想把跟踪器直接嵌进独立的 C++ 工程，CMake 集成文档在 docs/native/index.md：

boxmot track --detector yolov8n --tracker bytetrack --tracker-backend cpp --source video.mp4

2. HTTP 跟踪服务（boxmot-service）

如果你的检测由另一个服务完成，只要把检测结果 POST 给 BoxMOT 服务即可。CPU 镜像支持无像素的 ByteTrack/OcSort/SFSORT；GPU 镜像默认 BoT-SORT，并支持 StrongSort、DeepOcSort、HybridSort、BoostTrack、OccluBoost 等 ReID 增强跟踪器，服务自带健康检查与 OpenAPI 文档页。请求协议与扩缩容模型见部署指南。

八、常用配置与文档导航

需要源码级改动或贡献时，可从 CONTRIBUTING.md 入手，仓库地址：https://gitcode.com/GitHub_Trending/bo/boxmot。

九、落地建议：按你的场景对号入座

• 预算有限 / 边缘设备 / 低帧率流→ CPU +bytetrack或ocsort，纯运动关联不吃像素，内存占用最低；
• 实时视频分析、要求 ID 稳定→ GPU（--device cuda:0）+botsort或occluboost，ReID 推理放 GPU 上收益最大；
• 追求极限吞吐或嵌入 C++ 产品→ 同算法切--tracker-backend cpp，指标不变、延迟更低；
• 检测结果已在别处产生→ 直接上boxmot-service的 Docker 镜像，HTTP 接入即可；
• 要发论文级对比→boxmot materialize物化一次感知结果，后续所有eval/tune复用同一个 build，保证公平可复现。

先跑通第二条命令（boxmot track），再根据画面里 ID 是否频繁跳变决定是否升级到 ReID 跟踪器，这是最省心的路径。

【免费下载链接】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