Supervision — 适合视觉 AI 标注与后处理的工具库

cultural · 2026-03-30 11:00:23 · 5 次点击 · 0 条评论

[notebooks](https://github.com/roboflow/notebooks) | [inference](https://github.com/roboflow/inference) | [autodistill](https://github.com/autodistill/autodistill) | [maestro](https://github.com/roboflow/multimodal-maestro)
[![version](https://badge.fury.io/py/supervision.svg)](https://badge.fury.io/py/supervision) [![downloads](https://img.shields.io/pypi/dm/supervision)](https://pypistats.org/packages/supervision) [![snyk](https://snyk.io/advisor/python/supervision/badge.svg)](https://snyk.io/advisor/python/supervision) [![license](https://img.shields.io/pypi/l/supervision)](https://github.com/roboflow/supervision/blob/main/LICENSE.md) [![python-version](https://img.shields.io/pypi/pyversions/supervision)](https://badge.fury.io/py/supervision) [![colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb) [![gradio](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/Roboflow/Annotators) [![discord](https://img.shields.io/discord/1159501506232451173?logo=discord&label=discord&labelColor=fff&color=5865f2&link=https%3A%2F%2Fdiscord.gg%2FGbfgXGJ8Bk)](https://discord.gg/GbfgXGJ8Bk) [![built-with-material-for-mkdocs](https://img.shields.io/badge/Material_for_MkDocs-526CFE?logo=MaterialForMkDocs&logoColor=white)](https://squidfunk.github.io/mkdocs-material/)

👋 你好

我们为你编写可复用的计算机视觉工具。 无论你需要从硬盘加载数据集、在图像或视频上绘制检测框，还是统计区域内检测目标的数量，你都可以信赖我们！🤝

💻 安装

在 Python>=3.9 环境中使用 Pip 安装 supervision 包。

pip install supervision

有关 conda、mamba 以及从源码安装的更多信息，请参阅我们的指南。

🔥 快速开始

模型

Supervision 被设计为模型无关。只需接入任何分类、检测或分割模型即可。为了方便使用，我们为最流行的库（如 Ultralytics、Transformers 或 MMDetection）创建了连接器。

import cv2
import supervision as sv
from ultralytics import YOLO

image = cv2.imread(...)
model = YOLO("yolov8s.pt")
result = model(image)[0]
detections = sv.Detections.from_ultralytics(result)

len(detections)
# 5

👉 更多模型连接器

- inference 使用 [Inference](https://github.com/roboflow/inference) 运行需要 [Roboflow API KEY](https://docs.roboflow.com/api-reference/authentication#retrieve-an-api-key)。 ```python import cv2 import supervision as sv from inference import get_model image = cv2.imread(...) model = get_model(model_id="yolov8s-640", api_key=) result = model.infer(image)[0] detections = sv.Detections.from_inference(result) len(detections) # 5 ```

标注器

Supervision 提供了一系列高度可定制的标注器，让你可以根据具体用例组合出完美的可视化效果。

import cv2
import supervision as sv

image = cv2.imread(...)
detections = sv.Detections(...)

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

https://github.com/roboflow/supervision/assets/26109316/691e219c-0565-4403-9218-ab5644f39bce

数据集

Supervision 提供了一套工具，允许你以支持的格式之一加载、分割、合并和保存数据集。

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:
    # 按需加载图像

👉 更多数据集工具

- 加载 ```python 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=... ) ``` - 分割 ```python 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) ``` - 合并 ```python 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'] ``` - 保存 ```python 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=... ) ``` - 转换 ```python sv.DetectionDataset.from_yolo( images_directory_path=..., annotations_directory_path=..., data_yaml_path=... ).as_pascal_voc( images_directory_path=..., annotations_directory_path=... ) ```