obss/sahi

Framework agnostic sliced/tiled inference + interactive ui + error analysis plots

SAHI는 무엇인가요?

SAHI ( Slicing‑Aided Hyper Inference )는 매우 큰 이미지나 비디오에서 객체 탐지 및 인스턴스 세그멘테이션 모델을 쉽게 실행할 수 있도록 해주는 경량 Python 라이브러리입니다. 핵심 아이디어는 스라이싱 추론(sliced inference) 입니다: 입력 이미지는 자동으로 겹치는 타일로 나뉘며, 각 타일은 일반적인 탐지기로 처리되고 결과는 다시 통합됩니다. 이는 전체 이미지의 해상도가 낮을 때 작은 객체를 놓치는 일반적인 문제를 해결합니다.

주요 기능 (README에 설명된 내용)

기능	설명
스라이싱 추론	큰 이미지를 자동으로 타일로 나누고, 지원되는 모든 탐지기를 각 타일에 적용한 후 탐지 결과를 다시 통합합니다.
프레임워크 독립성	Ultralytics YOLO (v5, v8, YOLO‑X, YOLO‑E 등), MMDetection, Detectron2, HuggingFace 🤗 Transformers, TorchVision, Roboflow / RF‑DETR, GroundingDINO와 호환됩니다.
CLI 도구	`sahi predict`, `predict‑fiftyone`, `coco slice`, `coco evaluate`, `coco analyse`, `coco yolo` 등으로 빠르게 명령줄 사용 및 데이터셋 처리가 가능합니다.
FiftyOne 통합	FiftyOne 앱에서 예측 결과와 오류 분석을 시각화할 수 있습니다.
COCO 유틸리티	COCO 데이터셋을 슬라이스하고, 포맷 간 변환, AP/AR 평가, 오류 분석 플롯 생성이 가능합니다.
비디오 지원	동일한 슬라이싱 로직이 비디오 프레임에 적용되어 실시간 또는 배치 추론이 가능합니다.
사전 학습 모델 지원	추가 코드 없이, 지원되는 라이브러리의 모델 체크포인트를 지정하기만 하면 됩니다.
풍부한 문서 및 노트북	주요 탐지기마다 Colab 노트북, 완전한 문서 사이트, 그리고 방법을 설명하는 논문 (ICIP 2022)이 제공됩니다.

설치 (빠른 방법)

pip install sahi            # 핵심 라이브러리
# 선택 사항 – 사용할 탐지기 설치 예: 
# pip install ultralytics>=8.3   # YOLO 계열
# pip install torch torchvision  # TorchVision 모델용
# pip install transformers timm  # HuggingFace 모델용
# pip install yolov5==7.0.14    # YOLOv5
# pip install mim && mim install mmdet==3.3.0   # MMDetection

README에는 PyTorch, CUDA, 각 탐지 프레임워크에 대한 세부적인 버전 매칭 지침도 제공됩니다.

빠른 시작 예제 (문서에서)

from sahi import AutoDetectionModel, get_sliced_prediction

# 지원되는 모델 중 하나를 선택 – 여기서는 ultralytics의 YOLOv8 사용
model = AutoDetectionModel.from_pretrained(
    model_type="yolov8",
    model_path="yolov8n.pt",
    confidence_threshold=0.3,
    device="cuda:0",
)

result = get_sliced_prediction(
    "large_image.jpg",
    detection_model=model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
)

# 통합된 탐지 결과를 시각화하거나 내보내기
result.save("output.jpg")

동일한 워크플로우는 비디오 (각 프레임에서 get_sliced_prediction 사용) 및 다른 지원 백엔드에서도 동일하게 작동합니다.

언제 SAHI를 사용할까요?

위성 또는 항공 영상에서 이미지가 수만 픽셀 너비에 이르고, 차량, 선박, 동물과 같은 작은 객체를 놓치기 쉬운 경우.
의료 영상 (예: 전체 슬라이드 병리학)에서 고해상도 스캔을 다운샘플링 없이 처리해야 하는 경우.
감시 비디오에서 여러 프레임에 걸쳐 작은 객체를 효율적으로 탐지하고자 하는 경우.
벤치마킹 / 연구 – COCO 데이터셋을 슬라이스하고, AP/AR를 평가하며, 오류 분석 플롯을 생성하는 도구가 포함되어 있습니다.
빠른 프로토타이핑 – 기존 탐지기 코드를 다시 작성할 필요 없이, SAHI의 CLI 또는 Python API로 감싸기만 하면 됩니다.

리소스

논문: Slicing Aided Hyper Inference (ICIP 2022) – DOI 10.1109/ICIP46576.2022.9897990
문서: https://github.com/obss/sahi/tree/main/docs
Colab 노트북 – 주요 탐지기마다 제공 (README 내 링크 참조).
HuggingFace Space 데모 – https://huggingface.co/spaces/fcakyon/sahi-yolox
커뮤니티: 600건 이상의 인용, 경진대회 우승자, 오류 분석을 위한 토론 포럼.

결론: SAHI는 자동으로 슬라이싱, 예측, 통합을 수행함으로써, 어떤 주류 객체 탐지 모델도 거대한 이미지나 비디오 스트림에 적용할 수 있도록 해주는 실용적이고 지속적으로 유지 관리되는 오픈소스 라이브러리입니다. AI/ML(컴퓨터 비전) 분야에 특화되어 있으며, 개발자를 위한 CLI 편의성과 Python API를 모두 제공합니다.