supervision 弃用与迁移全指南：ByteTrack、keypoint、LMM/VLM 等已废弃 API 的升级路径

在计算机视觉工具库 supervision（当前开发版本 0.31.0.dev0，见 pyproject.toml）中，官方采用"逐步退场"策略管理 API 演进：被弃用（Deprecated）的功能通常还会在后续多个版本中继续可用，给用户留出迁移时间。本文以仓库内的 docs/deprecated.md 为主线，系统梳理当前版本中所有已标记弃用、即将被移除的接口，以及历史上已经删除的 API，并给出每条迁移路径的可执行示例与源码级佐证。读完本文，你将能精准定位自己代码中正在使用的废弃接口，并一次性完成向新 API 的平滑升级，避免在 supervision 0.31.0 / 0.32.0 升级时遇到破坏性变更。

一、先理解 supervision 的弃用（Deprecation）机制

弃用不代表立即失效。官方策略是：被弃用的功能通常会在后续多个版本中继续被支持，为用户提供充足的迁移窗口，随后才在规划好的版本中彻底移除。从仓库源码看，弃用信息全部集中标注了"从哪个版本弃用（deprecated_in）、在哪个版本移除（remove_in）"两个时间点：

• supervision-0.31.0 将移除绝大多数在 0.27.0~0.28.0 弃用的接口；
• supervision-0.32.0 将移除 0.29.0 弃用的校验类接口与 KeyPoints.confidence。

由于当前仓库版本号已是 0.31.0.dev0，上述 0.31.0 移除项已经进入最后窗口期，升级代码刻不容缓。

弃用警告如何产生与如何控制

弃用提示由底层告警机制统一发出。在 src/supervision/utils/internal.py 中可以看到，supervision 定义了专属的 SupervisionWarnings 告警类别，并提供两种控制方式：

• 默认情况下（未设置环境变量或值不为 "0"）所有弃用警告都会显示（warnings.simplefilter("always", ...)）；
• 设置环境变量 SUPERVISION_DEPRECATION_WARNING=0 可以关闭全部弃用警告（历史拼写错误的变量名 SUPERVISON_DEPRECATION_WARNING 依然兼容）。

函数级/类级弃用装饰器则来自 deprecate 库，例如 ByteTrack 类上方的 @deprecated_class、create_tiles 等函数上的 @deprecated，它们会在运行时给出提示。参数级弃用（如 denormalize_boxes 的 normalized_xyxy）会触发 FutureWarning。因此，你在升级前可以先关闭噪音、逐条清理代码，也可以保留警告作为"待办清单"逐项排查。

二、目标追踪迁移：sv.ByteTrack → ByteTrackTracker

弃用状态与替代方案

sv.ByteTrack 在 supervision-0.28.0 被弃用，计划在 supervision-0.31.0 移除。官方指定的替代品是外部独立包 trackers 中的 ByteTrackTracker，安装方式：

pip install trackers

这一决策在源码的类 docstring 中写得很明确（见 src/supervision/tracker/byte_tracker/core.py），同时类定义上方由 @deprecated_class(deprecated_in="0.28.0", remove_in="0.31.0") 注解标记（同一文件第 26-31 行）。

迁移前后对照

迁移前（supervision 内置 ByteTrack）：

import supervision as sv

tracker = sv.ByteTrack(
    track_activation_threshold=0.25,
    lost_track_buffer=30,
    minimum_matching_threshold=0.8,
    frame_rate=30,
)
# 逐帧更新
tracked_detections = tracker.update_with_detections(detections)

迁移后（外部 trackers 包）：

from trackers import ByteTrackTracker
from trackers.byte_tracker.byte_tracker import Detection

tracker = ByteTrackTracker()
# 注意：方法名从 update_with_detections() 改名为 update()
tracked_detections = tracker.update(detections)

需要特别留意的两个差异：

1. 方法改名：update_with_detections() 重命名为 update()；
2. 参数体系已经历过一次重命名（历史变更，见下文 0.23.0 移除记录）：track_buffer/track_thresh/match_thresh 在 0.23.0 已删除，需使用 lost_track_buffer/track_activation_threshold/minimum_matching_threshold。当前 supervision 内置 ByteTrack 的构造参数即已采用新命名（src/supervision/tracker/byte_tracker/core.py），迁移到外部包后建议沿用一致的语义参数。

三、关键点（Keypoint）API 迁移

3.1 模块改名：supervision.keypoint → supervision.key_points

supervision.keypoint 模块在 supervision-0.27.0 弃用，将在 supervision-0.31.0 移除，应改用 supervision.key_points。源码中旧模块已变成一层"兼容转发层"：从 src/supervision/keypoint/init.py 可以看到，导入该模块时首先调用 warn_deprecated() 发出弃用警告，随后才从 supervision.key_points 重新导出 KeyPoints 及注解器（annotators.py、core.py 同理）。

迁移方式：

# 旧写法（自 0.27.0 起触发弃用警告）
from supervision.keypoint import KeyPoints

# 新写法
from supervision.key_points import KeyPoints

新模块对应的完整源码位于 src/supervision/key_points/，注解器部分见 src/supervision/key_points/annotators.py。

3.2 属性改名：KeyPoints.confidence → KeyPoints.keypoint_confidence

KeyPoints.confidence 在 supervision-0.29.0 弃用，计划在 supervision-0.32.0 移除。改用 keypoint_confidence 表示每个关键点的置信度数组（形状 (n, m)），以消除它与"检测级置信度 detection_confidence（形状 (n,)）"之间的语义混淆。

源码层面，新构造函数以 keypoint_confidence 为正式参数，并保留了兼容入口：当同时传入 confidence 与 keypoint_confidence 时会直接抛出 ValueError（见 src/supervision/key_points/core.py），否则会发出弃用警告并把值映射过去。迁移示例：

import supervision as sv

# 新 API：明确使用 keypoint_confidence
key_points = sv.KeyPoints(
    xy=xy,
    class_id=class_id,
    keypoint_confidence=confidence_array,   # shape (n, m)
)

3.3 校验函数迁移

supervision.validators 中的关键点校验工具也在 supervision-0.27.0 弃用并计划于 0.31.0 移除，例如 validate_keypoint_confidence 与 validate_keypoints_fields。它们已在 src/supervision/validators/init.py 中被标记为 @deprecated(deprecated_in="0.27.0", remove_in="0.31.0")。普通用户通常无需直接调用这些校验函数（它们由 Detections/KeyPoints 内部触发）；如果确实引用了，请迁移到下文"校验函数统一迁移"一节说明的私有 _validate_* 语义（内部使用）或干脆移除显式调用。

四、视觉语言模型 API 迁移：sv.LMM → sv.VLM

4.1 枚举迁移：sv.LMM 弃用

sv.LMM（Large Multimodal Model 枚举）在 supervision-0.27.0 弃用，将在 supervision-0.31.0 移除，应替换为 sv.VLM（Vision Language Model）。虽然 src/supervision/init.py 仍同时导出二者，但 src/supervision/detection/vlm.py 中 LMM 的 docstring 与 from_value() 均已标注弃用提醒。

迁移方式：

# 旧写法
sv.LMM.PALIGEMMA
sv.LMM.QWEN_2_5_VL

# 新写法
sv.VLM.PALIGEMMA
sv.VLM.QWEN_2_5_VL

需要说明的是，源码注释表明 LMM 与 VLM 是值完全一致的镜像枚举（见 src/supervision/detection/core.py），因此仅替换枚举名即可，字符串值不发生变化，from_lmm/from_vlm 甚至可以通过 VLM(lmm.value) 直接互相转换。

4.2 构造方法迁移：Detections.from_lmm → Detections.from_vlm

sv.Detections.from_lmm 类方法在 supervision-0.26.0 弃用，将在 supervision-0.31.0 移除。其 docstring 中已明确要求改用 Detections.from_vlm（见 src/supervision/detection/core.py）。实现上 from_lmm 也只是先做类型归一化，最终完全委托给 from_vlm 完成解析（同一文件）。

迁移前：

detections = sv.Detections.from_lmm(
    sv.LMM.PALIGEMMA,
    result=paligemma_result,
    resolution_wh=image.size,
)

迁移后：

detections = sv.Detections.from_vlm(
    sv.VLM.PALIGEMMA,
    result=paligemma_result,
    resolution_wh=image.size,
)

from_vlm 目前支持 Paligemma、Qwen2.5-VL、Qwen3-VL、Florence-2、Google Gemini 2.0/2.5、Moondream、DeepSeek-VL2 等多个模型，且按模型区分 str/dict 结果类型（见 src/supervision/detection/vlm.py 及 core.py）。可继续参考 docs/detection/core.md 获取各模型所需参数。

五、图像与坐标转换工具迁移

5.1 create_tiles（utils.image）

supervision.utils.image.create_tiles 在 supervision-0.27.0 弃用，将在 supervision-0.31.0 移除。源码中该函数已挂上 @deprecated(deprecated_in="0.27.0", remove_in="0.31.0")（见 src/supervision/utils/image.py）。该函数用于将多张图像拼成网格马赛克（支持自动网格布局、单格缩放策略 tile_scaling、标题渲染等，参数定义见同文件 第 782-809 行）。

被弃用后官方并未在仓库内提供同等的直接替代函数，弃用主因是为避免维护两套图像处理入口。迁移建议：如需保留拼图能力，将相关代码封装为自己的工具函数，或改用更现代的 sv.ImageTile（若存在）/自行实现；至少在 0.31.0 前停止从 supervision.utils.image 导入该名字。

5.2 ensure_cv2_image_for_processing（utils.conversion）

supervision.utils.conversion.ensure_cv2_image_for_processing 在 supervision-0.27.0 弃用，0.31.0 移除，源码位于 src/supervision/utils/conversion.py。它用于把 PIL/其他格式统一成 OpenCV BGR 图像后再送入处理流程；弃用后应使用标准做法：

import numpy as np
import supervision as sv

# 统一转 BGR ndarray
image_bgr = sv.utils.image_to_bgr(image)  # 或等价工具
# 然后用 numpy 数组调用图像类 API

5.3 denormalize_boxes 的 normalized_xyxy 参数

sv.denormalize_boxes 的首个位置参数在 supervision-0.27.0 由 normalized_xyxy 重命名为 xyxy。以 normalized_xyxy= 关键字传入会触发 FutureWarning，支持将在 supervision-0.31.0 移除。实现采用参数自动重映射装饰器 @deprecated(target=TargetMode.ARGS_REMAP, deprecated_in="0.27.0", remove_in="0.31.0", args_mapping={"normalized_xyxy": "xyxy"})（见 src/supervision/detection/utils/boxes.py），因此旧写法仍能工作，但应尽快迁移：

# 旧写法（触发 FutureWarning）
sv.denormalize_boxes(normalized_xyxy=xyxy_norm, resolution_wh=(1280, 720))

# 新写法
sv.denormalize_boxes(xyxy=xyxy_norm, resolution_wh=(1280, 720))
# 也可直接用位置参数：sv.denormalize_boxes(xyxy_norm, (1280, 720))

该函数其余参数不变：resolution_wh 为目标分辨率 (width, height)，normalization_factor 默认 1.0，用于支持 [0, 1024] 这类非 0~1 归一化坐标（示例见 同一文件）。

5.4 RLE 掩码函数改址：supervision.dataset.utils → supervision.detection.utils.converters

supervision.dataset.utils.rle_to_mask 与 supervision.dataset.utils.mask_to_rle 的导入路径在 supervision-0.28.0 弃用，计划于 supervision-0.31.0 从 supervision.dataset.utils 移除。这两个函数的真实实现位于 src/supervision/detection/utils/converters.py（rle_to_mask 见第 662 行、mask_to_rle 见第 736 行）；旧路径 src/supervision/dataset/utils.py 目前只是通过 @deprecated 装饰器做"转发占位"，调用时发出弃用提示并委托给新实现。

迁移方式：

# 旧写法（supervision-0.28.0 起弃用，0.31.0 起不可用）
from supervision.dataset.utils import rle_to_mask, mask_to_rle

# 新写法
from supervision.detection.utils.converters import rle_to_mask, mask_to_rle

注意新实现中 mask_to_rle 支持 compressed 参数返回压缩字符串形式，rle_to_mask 需要 resolution_wh 还原分辨率，功能与调用方式一致，只是换了个导入路径。

六、校验函数统一迁移：公开 validate_* → 内部 _validate_*

supervision.validators 中公开的 validate_* 辅助函数在 supervision-0.29.0 集体弃用，将在 supervision-0.32.0 移除。原因是 supervision 内部已改用私有 _validate_* 辅助函数做校验，公开函数仅作为兼容外壳存在。

以 src/supervision/validators/init.py 为例：

公开函数（弃用）	内部实现（新）	校验内容
validate_xyxy	_validate_xyxy	二维 (N, 4)、有限数值的坐标数组（第 10-49 行）
validate_mask	_validate_mask	形状 (n, H, W)、bool dtype 的掩码（第 52-96 行）
validate_class_id	_validate_class_id	形状 (n,) 的类别数组
validate_confidence	_validate_confidence	形状 (n,) 的检测置信度
validate_tracker_id	_validate_tracker_id	形状 (n,) 的追踪 ID
validate_data	_validate_data	dict 中各字段长度与类型
validate_resolution	_validate_resolution	二元正整数分辨率元组（第 349-378 行）

validate_xyxy、validate_detections_fields、validate_key_points_fields 等公开包装器均以 @deprecated(target=_validate_*, deprecated_in="0.29.0", remove_in="0.32.0") 形式指向对应私有实现（如 第 291-304 行）。

迁移建议：公开 validate_* 属于内部工具 API，绝大多数业务代码不应直接调用。若你的代码（尤其自定义数据结构封装）引用了它们，请将这些调用移除或改由 Detections/KeyPoints 构造函数内置校验替代；0.32.0 之后这些名字将彻底消失。

七、历史已移除 API 清单（按版本回顾）

若你的代码基线较旧，以下"已移除"项需要特别警惕——它们不再有警告期，升级后直接报错。以下内容均记录于 docs/deprecated.md。

7.1 supervision-0.27.0

• sv.InferenceSlicer 的 overlap_ratio_wh 参数已移除，改用基于像素的 overlap_wh（当前实现见 src/supervision/detection/tools/inference_slicer.py，接受 int | tuple[int, int]）；
• sv.InferenceSlicer 的 overlap_filter_strategy 参数已移除，改用 overlap_strategy。

7.2 supervision-0.26.0

• sv.DetectionDataset.images 属性已移除。原因：不再要求把所有图像一次性加载进内存。正确做法是直接迭代数据集：for path, image, annotation in dataset:；
• 用 images: Dict[str, np.ndarray] 构造 sv.DetectionDataset 的方式已移除，请改为传入路径列表 List[str]；
• sv.BoundingBoxAnnotator 这个类名已删除并被重命名为 sv.BoxAnnotator。

7.3 supervision-0.24.0

• sv.PolygonZone 的 frame_resolution_wh 参数已移除；
• 安装方式 "headless" 与 "desktop" 两个 extra 已移除。执行 pip install supervision[headless] 会正常安装基础库，并对不存在的 extra 给出无害警告。

7.4 supervision-0.23.0

• ByteTrack 的 track_buffer、track_thresh、match_thresh 参数已移除，分别改用 lost_track_buffer、track_activation_threshold、minimum_matching_threshold（新参数默认值及语义见 src/supervision/tracker/byte_tracker/core.py）；
• sv.PolygonZone 的 triggering_position 参数已移除，改用 triggering_anchors。

7.5 supervision-0.22.0

• sv.Detections.from_roboflow 已移除，改用 Detections.from_inference；
• sv.Color.white() / black() / red() / green() / blue() 方法已移除，改用类常量 sv.Color.WHITE / BLACK / RED / GREEN / BLUE（色彩定义见 src/supervision/draw/color.py）；
• sv.ColorPalette.default() 方法已移除，改用常量 sv.ColorPalette.DEFAULT；
• 旧版 sv.BoxAnnotator 已移除，随后 sv.BoundingBoxAnnotator 立即重命名为 sv.BoxAnnotator。如今请使用 BoxAnnotator 与 LabelAnnotator（分别对应 src/supervision/annotators/core.py 与 第 1332 行，用法可查 docs/detection/annotators.md）；
• sv.FPSMonitor.__call__ 方法已移除，改用属性 sv.FPSMonitor.fps（帧率监控器完整定义见 同一文件）。

八、快速自查：你的代码踩中哪些雷区？

弃用项	弃用于	移除于	迁移动作
sv.ByteTrack	0.28.0	0.31.0	换用 trackers 包的 ByteTrackTracker；update_with_detections() → update()
supervision.keypoint 模块	0.27.0	0.31.0	改导入 supervision.key_points
KeyPoints.confidence	0.29.0	0.32.0	改用 keypoint_confidence
sv.LMM 枚举	0.27.0	0.31.0	改用 sv.VLM
Detections.from_lmm	0.26.0	0.31.0	改用 Detections.from_vlm
utils.image.create_tiles	0.27.0	0.31.0	迁移到自有封装或现代替代方案
utils.conversion.ensure_cv2_image_for_processing	0.27.0	0.31.0	显式做格式转换
denormalize_boxes(normalized_xyxy=...)	0.27.0	0.31.0	关键字改为 xyxy=（触发 FutureWarning）
dataset.utils.rle_to_mask / mask_to_rle	0.28.0	0.31.0	从 detection.utils.converters 导入
公开 validate_* 系列	0.29.0	0.32.0	移除显式调用，依赖对象内置校验

建议升级流程：

1. 全仓库检索以下高危符号，作为改造清单：ByteTrack、keypoint\.、keypoint_confidence（排查旧名 confidence）、from_lmm、sv.LMM、normalized_xyxy、from supervision.dataset.utils import、validate_；
2. 优先处理 0.31.0 移除项（当前仓库开发版本 pyproject.toml 已是 0.31.0.dev0），再处理 0.32.0 移除项；
3. 逐条按上表"迁移动作"列替换，并保持测试运行（仓库在 tests/ 下有 test_validate_deprecations.py 等用例，可参考其断言语义验证新接口行为）。

按上述清单完成迁移后，你的代码即可与 supervision 后续大版本保持兼容；若需进一步了解每个替代接口的完整参数与示例，可在仓库 docs/ 目录下按主题查阅对应指南（如 docs/detection/tools/inference_slicer.md、docs/detection/core.md、docs/utils/draw.md、docs/utils/video.md）。