📌 项目地址：roboflow/supervision | ⭐ 42,215 颗星 | 🔧 Python | 📜 未标注
别重复造轮子了：计算机视觉中那些通用工具
做目标检测、分割项目时，你是否总在重复写这几类代码：
- 从模型输出里解析框、置信度、类别
- 把检测结果画到图片上，调整颜色、线宽、标签
- 对视频逐帧处理，叠加标注后保存
- 把数据集从某种格式（如 COCO、YOLO）加载、合并、拆分
Supervision 就是把这些“无聊但必须”的部件封装好，让你可以直接对接主流模型（Ultralytics、Transformers、MMDetection、Roboflow Inference 等），然后把精力放在业务逻辑上。
根据 README，它被设计成 model agnostic，即模型无关。官方描述是：“We write your reusable computer vision tools.”
5 分钟上手：从检测到可视化
安装
环境要求 Python ≥ 3.9，直接 pip：
pip install supervision
其他安装方式（conda、mamba、源码）请参考官方安装指南。
加载模型 & 获取检测结果
以 Ultralytics YOLOv8 为例（官方 quickstart 代码）：
import cv2
import supervision as sv
from ultralytics import YOLO
image = cv2.imread("your_image.jpg")
model = YOLO("yolov8s.pt")
result = model(image)[0]
detections = sv.Detections.from_ultralytics(result)
print(len(detections)) # 输出检测到的目标数量，如 5
sv.Detections 是 Supervision 的核心数据结构，统一了不同模型输出的格式。如果你的模型来自 Hugging Face Transformers、MMDetection、或者 Roboflow Inference，只需换成对应的 .from_xxx() 方法。例如使用 Inference 库时需要 API Key：
from inference import get_model
model = get_model(model_id="yolov8s-640", api_key="YOUR_API_KEY")
result = model.infer(image)[0]
detections = sv.Detections.from_inference(result)
标注：画出框和标签
Supervision 提供了多种可高度自定义的 annotators（标注器）。最简单的使用方式：
box_annotator = sv.BoxAnnotator()
annotated_frame = box_annotator.annotate(
scene=image.copy(),
detections=detections
)
你还能组合多个 annotator（比如同时画框、标签、遮罩），调整颜色、文本样式等，详情见官方文档。
数据集处理
README 提到 Supervision 包含了加载、拆分、合并、保存数据集的工具，支持常见格式。这部分的具体 API 在数据集文档中。例如可以轻松地将 COCO 格式的标注转为 YOLO 格式，或者按比例划分训练/验证集。
为什么它比你自己写更值得用
| 维度 | 自己动手 | Supervision |
|---|---|---|
| 模型兼容 | 每个模型输出格式不同，需手写解析 | 提供统一 Detections，一行转换 |
| 可视化 | 重复编写 cv2.rectangle、cv2.putText |
预置多种 annotator，自定义方便 |
| 视频/流处理 | 需要手动管理帧循环和写入 | 有 sv.VideoSink、sv.VideoSource 等工具 |
| 数据集操作 | 写 COCO/YOLO 格式解析器 | 内置 load/save/merge/split |
| 集成 | 需要分别学不同库 | 连接器支持 Ultralytics、Transformers、Inference 等主流库 |
与类似工具（如 cvlib、imageai）相比，Supervision 的特点在于生态兼容性：它主动为最流行的模型库编写连接器，而不是强迫用户只用它自己的模型。同时，这个项目本身不依赖特定深度学习框架，轻量且能随时配合最新的模型。
需要注意的事
- Python 版本：要求 ≥ 3.9，如果你的项目仍用 3.8 及以下，需要先升级。
- 依赖 OpenCV：底层基于 OpenCV 进行图像操作，安装时会自动拉取相应版本。
- Roboflow 生态：虽然模型无关，但项目由 Roboflow 维护，部分高级功能（如 Inference API）需要 API Key，且有一些云服务的使用条款。
- 学习成本：虽然 API 简洁，但想用好 annotation 的定制、视频处理、数据集转换等特性，建议完整阅读官方文档。尤其是 annotator 的
customize参数和Detections的 mask 处理。
一句话总结
如果你正在做目标检测/分割/分类的工程化落地，无论你用什么模型，Supervision 能把最繁琐的“检测后处理”和“数据集管理”变成一行调用，是你工具箱中值得加入的万能转接器。