Supervision 完全上手指南：模型无关的计算机视觉工具箱从安装到实战

Supervision（即 supervision 包）是 Roboflow 开源的可复用计算机视觉工具库，它把目标检测、实例分割模型的输出统一封装为标准化的 sv.Detections 对象，并提供从数据加载、标注可视化到实时区域计数、视频处理的全套可复用组件，让你把精力集中在构建业务应用而非重复造轮子。读完本文，你将掌握它的安装方式、三种模型接入路径（直接返回、from_inference 转换、数据集工具链），以及如何用标注器与数据工具完成从单张图片到视频流的完整视觉应用。

项目定位与核心哲学

README 开篇用一句话定义了项目使命："We are your essential toolkit for computer vision."（我们是你的计算机视觉必备工具箱），强调从数据加载到实时区域计数（real-time zone counting），Supervision 提供的是可以直接复用的"积木"（building blocks），开发者只需专注围绕模型构建自己的应用。

这一点在 源码包结构 中体现得非常清楚：库被拆分成 detection（检测核心与工具）、annotators（可视化标注器）、dataset（数据集读写）、classification（分类）、geometry（几何原语）、draw（绘制）、utils（视频/图像/文件等通用工具）、metrics（评估指标）、tracker（跟踪器）等相对独立又互相配合的模块。整个设计的关键在于：模型无关（model agnostic）。

安装与运行环境

在 Python >= 3.10 的环境中使用 pip 即可完成安装（该版本要求可在 pyproject.toml 的 requires-python = ">=3.10" 中确认）：

pip install supervision

当前仓库对应的开发版本为 0.31.0.dev0（见 pyproject.toml）。运行核心功能所需的运行时依赖包括 numpy>=1.21.2、opencv（通过内置的 supervision._cv2 子系统管理）、matplotlib>=3.6、pillow>=9.4、av>=14.2（视频读写）、pyyaml、tqdm、scipy 等。如果你想用额外的数据评估指标，可再安装可选依赖：pip install supervision[metrics]。

说明：README 还提到 conda、mamba 以及从源码安装的更多方式，可以进一步查阅项目官方文档。

Quickstart：先把一条端到端流程跑通

1. 接入模型：从 Detections 开始

Supervision 的设计目标是模型无关——你可以插入任意分类、检测或分割模型，由官方提供连接器（connectors）把主流库的输出统一转换。快速开始给出的最小示例选用 rfdetr，因为 RF-DETR 的 predict 结果本身就是 sv.Detections 对象，无需任何转换步骤（这是 源码 中 Detections 标准化设计的直接受益者）：

# 为该示例安装可选依赖
pip install pillow rfdetr

import supervision as sv
from PIL import Image
from rfdetr import RFDETRSmall

image = Image.open("path/to/image.jpg")
model = RFDETRSmall()
detections = model.predict(image, threshold=0.5)

len(detections)
# 5

如果使用 Roboflow Inference 平台托管的模型，则通过 sv.Detections.from_inference() 完成转换。这一步需要先在 Roboflow 平台申请一个 API KEY：

import supervision as sv
from PIL import Image
from inference import get_model

image = Image.open("path/to/image.jpg")
model = get_model(model_id="rfdetr-small", api_key="ROBOFLOW_API_KEY")
result = model.infer(image)[0]
detections = sv.Detections.from_inference(result)

len(detections)
# 5

Detections：标准化的检测结果容器

from_inference 只是入口之一。查看 Detections 源码 可以发现，模型无关是通过一整套 @classmethod 转换器实现的，覆盖了主流推理框架：

转换器	适用框架
Detections.from_ultralytics(...)	Ultralytics YOLOv8/YOLO11 检测、分割、OBB 结果
Detections.from_yolov5(...)	旧版 YOLOv5 推理结果
Detections.from_transformers(...)	HuggingFace Transformers（如 DETR 系列）
Detections.from_mmdetection(...)	OpenMMLab MMDetection
Detections.from_deepsparse(...)	DeepSparse 推理
Detections.from_detectron2(...)	Detectron2
Detections.from_inference(...)	Roboflow Inference / API
Detections.from_sam(...) / from_sam3(...)	Meta SAM 系列分割模型

每个转换器把各自框架的预测结果映射成统一的字段。Detections 本质是一个 dataclass（源码 src/supervision/detection/core.py），核心字段包括：

• xyxy：形状 (n, 4) 的边界框数组，格式 [x1, y1, x2, y2]；
• mask：形状 (n, H, W) 的分割掩膜（布尔数组），无掩膜时为 None；
• confidence：形状 (n,) 的置信度数组；
• class_id：形状 (n,) 的类别编号数组；
• tracker_id：形状 (n,) 的跟踪器 ID 数组（无跟踪时为 None）；
• data：存放 class_name 等附加逐检测数据的字典；
• metadata：存放作用于整批检测的集合级元数据。

这一标准化是后续跟踪器、标注器和工具模块能无缝协作的前提。对检测结果还经常使用 detections.with_nms(...)（源码位于 core.py）做非极大值抑制、detections[boolean_mask] 做置信度过滤。分类任务则对应 sv.Classifications（见 src/supervision/classification/core.py），分割掩膜格式转换工具（RLE、多边形、xyxy 互相转换）集中在 src/supervision/detection/utils/converters.py。

多模型连接器（更多详情）

官方同时维护了 Ultralytics、Transformers、MMDetection、Inference 等连接器的完整文档。例如 Ultralytics 的接入方式与上面类似：

import supervision as sv
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
results = model(image)[0]
detections = sv.Detections.from_ultralytics(results)

from_ultralytics 同时兼容检测、分割与 OBB（有向边界框）三种任务类型（见 源码说明），这是 Ultralytics 生态用户的常用入口。

2. 标注器（Annotators）：让检测结果"看得见"

Supervision 提供大量高度可定制的标注器，用于把 Detections 绘制到图像上，帮助组合出适合自己场景的可视化效果。最基础的是边界框标注：

import cv2
import supervision as sv

image = cv2.imread("path/to/image.jpg")
# 假设 detections 来自某个模型
detections = sv.Detections(...)

box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(scene=image.copy(), detections=detections)

查看 BoxAnnotator 源码，其构造参数与默认值如下：

• color（默认 ColorPalette.DEFAULT）：单个 Color、ColorPalette 调色板或颜色字符串；
• thickness（默认 2）：边框线宽（像素）；
• color_lookup（默认 ColorLookup.CLASS）：颜色到标注的映射策略，可选 INDEX（按检测序号）、CLASS（按类别）、TRACK（按跟踪 ID）。

annotate 方法逐检测框遍历，将 xyxy 坐标转为整数后在场景上用 cv2.rectangle 绘制。值得注意的是，annotate 支持传入 custom_color_lookup 覆盖默认取色策略，且通过装饰器同时接受 numpy.ndarray 与 PIL.Image 两种图像输入。

除 BoxAnnotator 外，annotators/core.py 中还实现了 20 余种标注器。完整清单可直接从 顶层导出 看到，包括：

• 检测框类：BoxAnnotator、BoxCornerAnnotator、RoundBoxAnnotator、TriangleAnnotator、OrientedBoxAnnotator（OBB 专用）；
• 掩膜/区域类：MaskAnnotator、PolygonAnnotator、HaloAnnotator、BackgroundOverlayAnnotator；
• 目标形状类：EllipseAnnotator、CircleAnnotator、DotAnnotator；
• 标签/文字类：LabelAnnotator、RichLabelAnnotator、IconAnnotator、PercentageBarAnnotator、ColorAnnotator；
• 图像处理类：BlurAnnotator、PixelateAnnotator、HeatMapAnnotator（热力图）、CropAnnotator（裁剪导出）、TraceAnnotator（运动轨迹）。

配合 LabelAnnotator 源码 的 text_scale、text_thickness、text_padding 等参数，以及 draw/utils.py 中 calculate_optimal_text_scale、calculate_optimal_line_thickness 这类根据图像尺寸自适应计算文字/线宽的辅助函数，可以拼出非常精致的可视化。更完整的标注器参数文档见 docs/detection/annotators.md 与 docs/keypoint/annotators.md。

3. 数据集工具：加载 / 切分 / 合并 / 保存 / 格式转换

Supervision 在数据集处理上提供了一组实用工具，支持加载、切分、合并与保存多种主流标注格式。下面以 Roboflow 下载的 COCO 数据集为例：

import supervision as sv
from roboflow import Roboflow

project = Roboflow().workspace("WORKSPACE_ID").project("PROJECT_ID")
dataset = project.version("PROJECT_VERSION").download("coco")

ds = sv.DetectionDataset.from_coco(
    images_directory_path=f"{dataset.location}/train",
    annotations_path=f"{dataset.location}/train/_annotations.coco.json",
)

path, image, annotation = ds[0]
# 图像按需惰性加载

for path, image, annotation in ds:
    # 图像按需惰性加载
    pass

这段代码展示了一个重要设计：图像惰性加载。查看 DetectionDataset 源码，当以"图片路径列表"（list[str]）构造数据集时，_get_image 只在通过 __getitem__ / __iter__ 访问时才真正 imread 读取图片，内存友好；而旧式"路径 → 数组字典"的传参方式已在 0.30.0 起标记为弃用。

数据集工具集中封装了如下操作（源码与完整签名见 src/supervision/dataset/core.py）：

加载（load）——支持 YOLO、Pascal VOC、COCO 三种主流格式：

dataset = sv.DetectionDataset.from_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
)

dataset = sv.DetectionDataset.from_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)

dataset = sv.DetectionDataset.from_coco(
    images_directory_path=...,
    annotations_path=...,
)

切分（split）——split() 返回训练/测试两份数据集，不修改原对象；支持 split_ratio（训练集占比，默认 0.8）、random_state（随机种子，保证可复现）与 shuffle（是否打乱，默认 True）参数。README 展示了连续两次切分得到 7:1.5:1.5 三份数据的典型做法：

train_dataset, test_dataset = dataset.split(split_ratio=0.7)
test_dataset, valid_dataset = test_dataset.split(split_ratio=0.5)

len(train_dataset), len(test_dataset), len(valid_dataset)
# (700, 150, 150)

合并（merge）——DetectionDataset.merge([...]) 可以把多个数据集合并，类别列表自动并集排序：

ds_1 = sv.DetectionDataset(...)
len(ds_1)
# 100
ds_1.classes
# ['dog', 'person']

ds_2 = sv.DetectionDataset(...)
len(ds_2)
# 200
ds_2.classes
# ['cat']

ds_merged = sv.DetectionDataset.merge([ds_1, ds_2])
len(ds_merged)
# 300
ds_merged.classes
# ['cat', 'dog', 'person']

保存（save）：

dataset.as_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
)

dataset.as_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)

dataset.as_coco(
    images_directory_path=...,
    annotations_path=...,
)

格式转换（convert）——上述读/写方法可无缝链式组合，实现一行代码完成格式互转：

sv.DetectionDataset.from_yolo(
    images_directory_path=...,
    annotations_directory_path=...,
    data_yaml_path=...,
).as_pascal_voc(
    images_directory_path=...,
    annotations_directory_path=...,
)

底层各格式的注解解析与落盘逻辑分别实现在 src/supervision/dataset/formats/ 的 yolo.py、pascal_voc.py、coco.py、labelme.py、createml.py 中，由 formats/init.py 统一导出 from_* / as_* 各方法所用到的加载与保存函数。除检测数据集 DetectionDataset 外，还有分类数据集 ClassificationDataset 与通用基类 BaseDataset（分类任务用法见 docs/classification/core.md）。

视频处理与区域分析：从单帧走向真实场景

README 的示例代码聚焦单张图片，但 Supervision 的真实价值在视频与实时流场景。它提供了一套围绕 src/supervision/utils/video.py 的完整视频工具链：

• sv.VideoInfo.from_video_path(...)：读取视频的 width、height、fps、total_frames 元数据；
• sv.get_video_frames_generator(...)：逐帧读取的生成器（源码 video.py），配合 sv.FPSMonitor 可以监测处理帧率；
• sv.process_video(...)：把"单帧处理回调"应用到整个视频并写出结果，是批量离线处理的利器（video.py）；
• sv.VideoSink：带 tqdm 进度条的高效视频写出器（video.py）。

组合起来，一个"读取视频 → 逐帧推理 + 跟踪 → 标注 → 写出"的典型管线形如：

import supervision as sv

video_info = sv.VideoInfo.from_video_path(video_path="input.mp4")

def callback(scene, index):
    detections = model.predict(scene)          # 换成你的模型
    annotated = box_annotator.annotate(scene, detections)
    return annotated

sv.process_video(source_path="input.mp4", target_path="output.mp4", callback=callback)

而在区域分析方向，Supervision 提供了可直接用于计数场景的高层工具：

• sv.LineZone / sv.LineZoneAnnotator：划线计数（越线统计），多类别版本为 LineZoneAnnotatorMulticlass（src/supervision/detection/line_zone.py）；
• sv.PolygonZone / sv.PolygonZoneAnnotator：多边形区域人数/目标计数（src/supervision/detection/tools/polygon_zone.py）；
• sv.ByteTrack：多目标跟踪（源码位于 src/supervision/tracker/byte_tracker/，包含卡尔曼滤波与匈牙利匹配实现）；
• sv.DetectionsSmoother：检测结果时序平滑（tools/smoother.py）；
• sv.InferenceSlicer：大图切片推理（tools/inference_slicer.py），配合窗口化光栅数据集 WindowedRasterDataset 可用于遥感 GeoTIFF 等超大影像；
• sv.CSVSink / sv.JSONSink：把带跟踪 ID 的检测结果按帧序列化到 CSV / JSON，便于下游分析（tools/csv_sink.py、tools/json_sink.py）。

在模型评估层面，src/supervision/metrics/ 目录提供了 ConfusionMatrix、MeanAveragePrecision 等指标实现，可对检测结果进行量化评估。

教程与可运行示例：跟着仓库直接上手

除了本文讲解的快速开始，仓库还提供了多层次的进阶学习材料：

端到端可运行示例（examples），每个子目录都自带 README.md、requirements.txt 与针对不同推理框架（Ultralytics / RF-DETR / Roboflow Inference / YOLO-NAS）的脚本：

• examples/tracking：目标跟踪完整管线；
• examples/count_people_in_zone：区域人数统计，含多区域、象限等多种 zone 配置 JSON；
• examples/heatmap_and_track：停留热力图与跟踪叠加；
• examples/traffic_analysis：交通流量分析；
• examples/speed_estimation：结合透视变换的车速估计；
• examples/time_in_zone：含文件/流式处理两种模式，覆盖 Naive Stream 与多线程 Stream 的实时在场时长（dwell time）分析；
• examples/compact_mask：紧致掩膜（CompactMask）的推理 API 与性能基准测试，用于高分辨率掩膜场景的显存优化。

交互式 Notebook（demo.ipynb：位于仓库根目录，可在 Colab 等环境中直接运行，用于快速感受完整交互流程。

How-to 操作指南（docs/how_to）：针对具体任务给出短小精悍的配方式教程，包括 检测与标注、目标跟踪、区域计数、检测结果过滤、小目标检测、使用紧致掩膜、从 OpenCV 迁移 等。

Cookbook 与 Cheatsheet：官方站点提供了按场景组织的 cookbook（对应本仓库 docs/cookbooks.md）与速查表，方便随手翻阅 API 用法。

进一步了解与参与

• 官方文档：模块级 API 参考（含每个类/方法的完整参数与源码示例）可查阅文档站点，其中检测核心见 docs/detection/core.md、标注器见 docs/detection/annotators.md、数据集见 docs/datasets/core.md，关键点任务见 docs/keypoint/core.md。
• 测试保障：仓库在 tests/ 目录下为检测、标注器、数据集、跟踪器等模块提供了完整的自动化测试（例如 tests/test_public_api.py 校验公共 API 面），可作为理解组件行为边界的参考。
• 贡献指南：社区贡献规范见 docs/contributing.md，代码行为准则见 docs/code_of_conduct.md。

总结

Supervision 的价值在于把"模型预测之后"的繁杂工程——结果标准化、可视化标注、数据集清洗与格式转换、跟踪、区域计数、视频流处理——收敛为一套 API 统一、可组合、覆盖常用格式与主流推理框架的工具箱。从本文的快速开始出发，你可以先用 rfdetr 或 Detections.from_* 转换器把任何模型输出变成标准 sv.Detections，再叠加标注器与数据工具快速落地第一版应用；当需要进阶能力时，LineZone、PolygonZone、ByteTrack、InferenceSlicer 与视频工具链会随项目复杂度增长持续派上用场。