每个 CV 项目都在重写的那段管道
Supervision 出自 Roboflow,它不是一个模型。它是围在你模型外面的工具箱,负责一切非推理的事:把检测结果装进一个一致的结构、画框和掩膜、跨帧追踪目标、在区域里计数、切分和转换数据集、计算指标。任何做过两个计算机视觉 demo 的人,都把这段胶水写过两遍,每次还略有不同。Supervision 的主张就是:这段你只该写一次,然后复用。
唯一的核心想法:检测结果的通用货币
设计的支点是 sv.Detections,一种统一表示,任何模型的输出都被归一化进去。你跑 Ultralytics、Transformers 模型、MMDetection,或 Roboflow 自家的 inference,调对应的 from_* 连接器,下游一切都讲同一种对象。换模型,而你的标注、追踪、计数代码不用动。
import supervision as sv
from PIL import Image
from rfdetr import RFDETRSmall
image = Image.open(...)
model = RFDETRSmall()
detections = model.predict(image, threshold=0.5)
len(detections) # 5有些库直接返回 sv.Detections;另一些则用一个连接器包住原始输出,比如 sv.Detections.from_inference(...)。这层归一化就是它全部的价值主张,也是它为何自称「设计上与模型无关」。
检测对象之外你还拿到什么
- 标注器(Annotators):框、掩膜、标签、轨迹等等,可组合,所以你搭出的正是你要的可视化,而不是接受一套固定叠加层。
- 数据集工具:在 COCO、YOLO、Pascal VOC 之间加载、切分、合并、保存,含三者互转,消掉了一整类一次性脚本。
- 追踪与区域:跨视频帧跟踪目标,并在它们穿过区域时计数,这是停留时长和测速管线的基础。
- 指标(Metrics):评估检测和分割质量。
安装
pip install supervision它面向 Python 3.9 或更新版本。conda、mamba 和源码安装在项目文档里有。模型连接器会拉它们自己的依赖,所以跑示例时你还要装模型包,比如 pip install rfdetr。
快速标注
一旦你从任意来源拿到 detections,最小循环是:
import cv2
import supervision as sv
image = cv2.imread(...)
detections = sv.Detections(...)
box_annotator = sv.BoxAnnotator()
annotated = box_annotator.annotate(scene=image.copy(), detections=detections)「与模型无关」的设计在哪里会咬你
它的强项也是要盯着的接缝。因为 supervision 包的是别人模型的输出,from_* 连接器和那些上游 API 是耦合的。当某个模型库改了输出形状,连接器就得跟上,所以一条管线要保持可复现,就把你的模型包和 supervision 版本一起钉死。这个库为追新模型而跑得很快:2026 年 4 月的 0.28.0 加上了 SAM3 支持和一个 CompactMask 表示,当你想要最新模型时这是特性,当你想要稳定时它是一片变动面。
第二点要记牢:supervision 自己不做任何检测。它不会提升你模型的精度,只改善你拿预测结果做什么。如果你的框是错的,那是模型的问题,supervision 在它下游。
supervision 与功能上的邻居对比
| supervision | fiftyone | norfair | |
|---|---|---|---|
| Stars | 43,268 | 10,768 | 2,651 |
| 范围 | 标注、追踪、数据集、指标 | 数据集策展、评估、可视化 | 仅轻量追踪 |
| 许可 | MIT | Apache-2.0 | BSD-3-Clause |
| 最擅长 | 跨任意模型的检测后处理胶水 | 检视与调试数据集 | 给检测结果加追踪 |
计数取自 GitHub,截至 2026 年 6 月。FiftyOne 在数据集这一侧有重叠,但更偏策展、评估和一个可视化 UI,而非管线内标注。Norfair 是个专注的追踪库,大致是 supervision 覆盖范围的一个切片。Supervision 横跨标注、追踪、数据集、指标的广度,且全都挂在一种检测格式上,这让它成为一个默认起点,而非单一用途的依赖。
关于生态的一点说明
Supervision 是更大的 Roboflow 技术栈里那块开源、MIT 许可的拼图,这个栈还包括 inference、notebooks、autodistill 和 maestro。你完全可以单独用 supervision 配任意模型,没有任何东西逼你进 Roboflow 的托管产品。掂量厂商锁定时,这份独立性值得知道。
相关
Supervision 对你可能用 TensorFlow 这类框架训练出的检测模型的输出做后处理。想看生态里还有什么在往上爬,见每日趋势速报和周报。
FAQ
supervision 是检测模型吗? 不是。它是围着模型的工具箱:归一化、标注、追踪、计数检测结果,但自己不做推理。
它支持哪些模型? 任意分类、检测或分割模型。连接器覆盖 Ultralytics、Transformers、MMDetection、Roboflow Inference,有些库还直接返回它的 sv.Detections 格式。
我必须用 Roboflow 的付费平台吗? 不必。Supervision 是 MIT 许可,能独立配任意模型和你自己的数据使用。
升级后我的管线为什么崩了? 连接器跟着上游模型 API 走。需要可复现时,把你的模型包和 supervision 版本一起钉死。