Kornia 迁移指南：BoxMotTracker 移除与基于 boxmot + RTDETRDetectorBuilder 的替代方案-平芜编程栈

计算机视觉
深度学习
人工智能
图像处理

【免费下载链接】kornia

🐍 空间人工智能的几何计算机视觉库

本篇技术指南聚焦 Kornia 开源仓库中的一项破坏性变更（Migration 004）：kornia.contrib.BoxMotTracker及其配套的kornia.contrib.boxmot_tracker模块被正式移除。文中将剖析移除的根因（boxmot 10.x API 与 Kornia 支持的 PyTorch 版本栈不兼容）、完整的影响面（含kornia.core.external.boxmot的同步删除），并给出以 boxmot 原生 API + KorniaRTDETRDetectorBuilder检测器组合的迁移路径与可运行代码，帮助开发者平滑升级到最新版本。

变更概述：一次"无法实例化"的清理

迁移条目记录于 changelog.d/+migration-004.breaking.md，其核心内容只有一句话：kornia.contrib.BoxMotTracker被移除，连带kornia.contrib.boxmot_tracker模块一并删除。

这不是一次普通的 API 重构，而是一次针对"事实上已不可用"组件的清理。在 Kornia 0.7 系列中，BoxMotTracker被设计为一个薄封装层：它在内部调用 boxmot 跟踪器仓库（tracker zoo）的 10.x API，即：

boxmot.DeepOCSORT(model_weights=..., device=..., fp16=...)

并将该跟踪器与 Kornia 自身的检测器串联，形成"检测 + 跟踪"一条龙。然而问题在于：

boxmot 10.x 的这套 API 需要特定的 PyTorch 版本配套；
Kornia 当前支持的最低 PyTorch 版本为torch>=2.5.1；
没有任何一个 boxmot 发布版本能在torch>=2.5.1的安装环境下提供这套 10.x API（详见 issue #4320）。

结果是：无论用户选用 Kornia 官方支持栈中的哪一种组合，BoxMotTracker都无法被实例化——它成了一个"挂着但永远跑不起来"的占位组件。与其保留一个必然抛错的入口误导用户，Kornia 团队选择直接将其从 API 表面移除。

影响面：三类符号同步消失

通过仓库内的 API 表面追踪文件可以精确确认本次移除的完整范围。

tests/api_surface_removals.json 中登记了以下移除记录：

{ "kornia.contrib": [ "BoxMotTracker" ], "kornia.contrib.boxmot_tracker": [ "BoxMotTracker" ] }

结合迁移文档，实际受影响的有三处：

kornia.contrib.BoxMotTracker：顶层公开类，从kornia.contrib命名空间移除；
kornia.contrib.boxmot_tracker：承载该类的整个子模块被删除（而非仅删类保留模块）；
kornia.core.external.boxmot：Kornia 对外部 boxmot 库的桥接导入模块同步移除，kornia.core.external下不再暴露 boxmot 相关封装。

也就是说，任何from kornia.contrib import BoxMotTracker、from kornia.contrib.boxmot_tracker import ...或from kornia.core.external.boxmot import ...形式的导入在升级后都会直接失败。建议在升级后先全局搜索boxmot（忽略大小写）关键字，确认没有残留引用。

迁移路径：boxmot 直连 + Kornia 检测器

迁移文档给出的官方指引非常明确：放弃通过 Kornia 间接使用 boxmot 的方式，改为直接使用 boxmot，并给它喂入 Kornia 检测器的输出。

推荐的组合方式是：

Kornia RTDETRDetectorBuilder（检测） → boxmot（跟踪）

即：检测阶段完全交给 Kornia 的 RT-DETR 实现，跟踪阶段完全交给 boxmot 原生 API，二者通过标准的检测结果数据格式衔接，不再经由已移除的BoxMotTracker封装层。

这样做的好处是：每一层都使用各自生态中受官方支持、可正常安装运行的版本，不再受"Kornia 的 torch 版本要求"与"boxmot 的 torch 版本要求"互相冲突的困扰。

第 1 步：用 RTDETRDetectorBuilder 产出检测框

RTDETRDetectorBuilder定义于 kornia/contrib/object_detection.py，是本次迁移的官方推荐检测器。它的使用方式（来源：docs/source/models/rt_detr.rst）：

from kornia.io import load_image from kornia.contrib.object_detection import RTDETRDetectorBuilder image = load_image("delorean.png")[None] # (1, 3, H, W) float in [0, 1] # 下载 COCO 预训练权重，默认在 640px 分辨率下推理 detector = RTDETRDetectorBuilder.build("rtdetr_r18vd") # 输出：每张图一个 (D, 6) 的 tensor：class_id, score, x, y, w, h（原始像素坐标） detections = detector(image) for class_id, score, x, y, w, h in detections[0].tolist(): print(f"class {int(class_id)}: {score:.2f} at ({x:.0f}, {y:.0f}) size {w:.0f}x{h:.0f}")

从 RTDETRDetectorBuilder.build 的源码可以看到其关键装配逻辑：

支持传入model_name（如rtdetr_r18vd）或自定义config对象，二者不能同时提供（否则抛出ValueError）；
默认置信度阈值为0.3（可通过confidence_threshold参数调整，控制保留框的多少）；
内部将模型与 ResizePreProcessor（预处理）和DETRPostProcessor（后处理）打包进ObjectDetector，因此输入(B, 3, H, W)的[0, 1]浮点图，直接得到每图一个(D, 6)检测张量。

可选的模型变体按"速度优先 → 精度优先"排列为：rtdetr_r18vd、rtdetr_r34vd、rtdetr_r50vd_m、rtdetr_r50vd、rtdetr_r101vd。注意一个细节：当通过model_name构建时，模型会强制缩放到权重训练时的 640px，此时image_size参数不生效；image_size仅在配合config=对象时才有意义（官方建议取 32 的倍数，480～800 之间）。

第 2 步：把检测框喂给 boxmot

拿到(D, 6)检测张量后，将其转换为 boxmot 期望的输入格式，直接调用 boxmot 原生的跟踪 API（例如DeepOCSORT）：

import numpy as np from boxmot import DeepOCSORT tracker = DeepOCSORT( model_weights="path/to/weights.pt", # ReID 模型权重 device="cuda:0", fp16=True, ) # detections 来自 RTDETRDetectorBuilder 的输出，取其中一帧的 (D, 6) 结果 for det in detections[0].tolist(): class_id, score, x, y, w, h = map(float, det) # boxmot 通常接受 [x1, y1, x2, y2, score, class_id] 或 xywh 格式的 ndarray frame_boxes = np.array([[x, y, x + w, y + h, score, class_id]], dtype=np.float32) tracks = tracker.update(frame_boxes, img) # img 为当前帧图像

注意：上述 boxmot 调用片段用于示意数据衔接方式，具体参数（如检测框格式、update的签名）以你所安装的 boxmot 版本文档为准。迁移的核心原则是：检测结果由 Kornia 产生，跟踪状态机由 boxmot 自己管理，两者不再经由BoxMotTracker这个失效的中间层。

源码级佐证：为何该决策是合理的

从代码结构看，本次移除是一个低风险、高收益的清理：

无替代实现残留：迁移文档明确说明kornia.contrib.boxmot_tracker模块被整体移除，tests/api_surface_removals.json 与之一致，不存在"旧 API 换皮成新 API"的隐性兼容负担；
推荐替代品完整可用：RTDETRDetectorBuilder在 kornia/contrib/object_detection.py 中有完整实现，且具备visualize（画框可视化）、to_onnx（导出 ONNX）、compile（torch.compile加速）等配套能力，检测器本身的功能完备性不受影响；
边界清晰：Kornia 的定位是"几何计算机视觉库"，检测器作为其能力的一部分被保留并持续维护，而第三方跟踪器集成则交还给 boxmot 自己的生态，职责划分更干净。

升级检查清单

扫描导入：全局搜索boxmot、BoxMotTracker、boxmot_tracker，移除或改写所有相关import；
替换跟踪逻辑：将BoxMotTracker(...)的实例化改为"RTDETRDetectorBuilder.build(...)产检测框 + boxmot 原生DeepOCSORT等跟踪器"的两段式管线；
确认环境：确保 boxmot 与当前 torch（>=2.5.1）版本兼容——这正是旧封装失效的根因，迁移后应回到 boxmot 官方支持矩阵来锁定版本；
验证 API 表面：可通过运行 tests/test_api_surface.py 类测试或直接执行import kornia.contrib确认新 API 表面正常，BoxMotTracker不再出现在kornia.contrib中即迁移完成。

小结

Migration 004 是一次典型的"移除不可用组件"的破坏性变更：BoxMotTracker因依赖的 boxmot 10.x API 与 Kornia 支持的最低 torch 版本（>=2.5.1）不兼容而无法实例化，Kornia 选择果断删除该封装及kornia.core.external.boxmot桥接模块。开发者只需将"检测 + 跟踪"管线改写为KorniaRTDETRDetectorBuilder负责检测、boxmot 原生 API 负责跟踪的组合，即可在最新版本上获得完全可运行的等价能力，且每一层的依赖版本都处于各自官方支持的范围之内。