개요
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
FAQ (5)
문제 해결객체 탐지에서 Average Precision (AP)이 단일 IoU 임계값에서의 Precision과 다른 이유는 무엇인가요?
평균 정밀도(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와 일치하는지 확인하십시오.
문제 해결동일한 클래스에 대해 여러 segmentation masks가 있는 COCO dataset을 로드할 때 supervision에서 'ValueError: setting an array element with a sequence'를 수정하는 방법?
이 오류는 supervision 0.20.0에서 COCO 주석에 단일 객체에 대한 여러 분할 항목이 있을 때 발생합니다. 임시 해결 방법으로 Ultralytics의 general_json2yolo.py에 있는 merge_multi_segment() 함수를 수정하여 로드하기 전에 여러 분할 마스크를 병합하세요. 영구적인 수정을 위해 이슈 #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 broadcast 오류를 발생시킵니다. 마스크는 박스에 맞게 리사이즈된 후 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를 사용합니다. 범위를 벗어난 박스를 모두 false인 마스크로 저하시켜(마스크를 xyxy와 인덱스 정렬 상태로 유지하면서) 처리하는 PR이 보고자에 의해 계획되어 있습니다.
문제 해결YOLO 데이터셋을 supervision의 as_coco로 COCO로 변환할 때 주석에 중복 ID가 생기는 이유는 무엇인가요?
이는 각 분할(train, valid, test)이 고유한 주석 ID 시퀀스를 생성하여 충돌을 일으키는 알려진 문제입니다. 해결 방법: 모든 분할을 하나의 YOLO 데이터셋으로 병합하고, as_coco를 사용하여 병합된 데이터셋을 COCO로 변환한 후, 연속적인 주석 ID를 유지하면서 COCO 데이터셋을 하위 집합으로 다시 분할합니다.