项目简介
Supervision 是一个模型无关的计算机视觉工具库，支持数据加载、图像注释和对象跟踪。兼容 COCO、Pascal VOC 和 YOLO 等格式，并与 Ultralytics、Transformers 等库集成。适用于快速原型开发与部署。
README 预览
\n \n \n \n \n \n\n\n\n[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)\n\n\n\n[](https://badge.fury.io/py/supervision)\n[](https://pypistats.org/packages/supervision)\n[](LICENSE.md)\n[](https://badge.fury.io/py/supervision)\n[](https://codecov.io/gh/roboflow/supervision)\n\n[](https://snyk.io/advisor/python/supervision)\n[](https://colab.research.google.com/github/roboflow/supervision/blob/main/demo.ipynb)\n[](https://huggingface.co/spaces/Roboflow/Annotators)\n[](https://discord.gg/GbfgXGJ8Bk)\n\n\n \n \n\n\n\n## 👋 hello\n\n**We are your essential toolkit for computer vision.** From data loading to real-time zone counting, we provide the building blocks so you can focus on building applications around your models. 🤝\n\n## 💻 install\n\nPip install the supervision package in a\n[**Python>=3.9**](https://www.python.org/) environment.\n\n```bash\npip install supervision\n```\n\nRead more about conda, mamba, and installing from source in our [guide](https://roboflow.github.io/supervision/).\n\n## 🔥 quickstart\n\n### models\n\nSupervision was designed to be model agnostic. Just plug in any classification, detection, or segmentation model. For your convenience, we have created [connectors](https://supervision.roboflow.com/latest/detection/core/#detections) for the most popular libraries like Ultralytics, Transformers, MMDetection, or Inference. Other integrations, like `rfdetr`, already return `sv.Detections` directly.\n\nInstall the optional dependencies for this example with `pip install pillow rfdetr`.\n\n```python\nimport supervision as sv\nfrom PIL import Image\nfrom rfdetr import RFDETRSmall\n\nimage = Image.open(...)\nmodel = RFDETRSmall()\ndetections = model.predict(image, threshold=0.5)\n\nlen(detections)\n# 5\n```\n\n\n👉 more model connectors\n\n- inference\n\n Ru
常见问题 (5)
故障排除在目标检测中，为什么平均精度（AP）与单个IoU阈值下的精度不同？
平均精度（AP）和固定IoU阈值下的精准率是不同的，因为AP是精确率-召回率曲线下的面积，通过固定IoU阈值（如IoU=0.5）并变化置信度阈值计算得到。单一IoU阈值下的精准率是该曲线上的一点（在选定置信度和IoU下的TP/(TP+FP)）。AP聚合了所有召回率水平下的精确率，提供了检测器性能的总体概况，而单阈值精准率仅反映一个工作点的性能。这就是即使在单类问题中它们也可能存在差异的原因。
故障排除为什么我的 ultralytics 模型在完整图像上进行推理，而不是在 Supervision InferenceSlicer 中定义的 512x512 切片上？
Ultralytics会将输入调整到训练时使用的imgsz大小。如果您的模型使用imgsz=2048训练，它会在推理前将512x512的切片放大到2048x2048。要解决此问题，请将所需的切片大小传递给模型：result = model(image, device='cuda', imgsz=512)[0]。确保imgsz与InferenceSlicer中设置的slice_wh一致。
故障排除在加载具有相同类别的多个分割掩码的COCO数据集时，如何修复supervision中的'ValueError: setting an array element with a sequence'错误？
此错误出现在 supervision 0.20.0 中，当 COCO 注释中单个对象包含多个分割条目时。临时解决方案：在加载前，使用 Ultralytics 的 general_json2yolo.py 中的 merge_multi_segment() 函数合并多个分割掩码。关注 issue #1209 以获取永久修复。
故障排除如何修复在 supervision 中解析带掩码的 Gemini 2.5 检测结果时出现的 "ValueError: could not broadcast input array" 错误？
sv.Detections.from_vlm(sv.VLM.GOOGLE_GEMINI_2_5, ...)（以及 GOOGLE_GEMINI_3_5）在任一项目的 box_2d 坐标超出归一化的 0-1000 范围（即使是 1001 或 -1）且该项包含 mask 时，会抛出此 NumPy 广播错误。掩码会被缩放至边界框大小，并通过 src/supervision/detection/vlm.py 中的 np_mask[y_min:y_max, x_min:x_max] = ... 放置；超出范围的边界框会使目标切片比缩放后的掩码更小（或因负索引环绕而变为空切片），该异常会丢弃响应中的所有检测结果。在修复发布前的变通方法：(1) 在调用 from_vlm 之前，将模型 JSON 输出中的每个 box_2d 值钳制到 [0, 1000]。(2) 移除 mask 键，仅解析边界框——超出范围的边界框在没有掩码的情况下可以正常解析（mask 将为 None）。(3) 使用 sv.VLM.GOOGLE_GEMINI_3_6，其多边形掩码解析器可以容忍同样的超出范围的边界框。报告者计划提交一个 PR，将超出范围的边界框降级为全 false 掩码（保持掩码与 xyxy 索引对齐）。
故障排除为什么在使用 supervision 的 as_coco 转换 YOLO 数据集时会出现重复的注释 ID？
这是一个已知问题：每个子集（train、valid、test）都会生成自己的标注ID序列，导致冲突。解决办法：将所有子集合并成一个YOLO数据集，使用as_coco将合并后的数据集转换为COCO格式，然后重新将COCO数据集拆分为子集，同时保持连续的标注ID。