Registry / ai-ml / sahi
library0.12.1pypypi✓ verified 85d ago

SAHI (Slicing Aided Hyper Inference) is a lightweight Python library designed to improve object detection and instance segmentation performance, especially for small objects in large or high-resolution images. It achieves this by dividing images into smaller overlapping slices, running inference on each slice, and then intelligently merging the predictions. Currently at version 0.11.36, SAHI has a frequent release cadence, often issuing patch releases to address bugs and introduce minor enhancements.

pip install sahi
INSTALL
IMPORT
SIG · SAHI
S
sahi
ai-mlpythonv0.12.1
Install
59.3s avg
Import
Disk
4501MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.12.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✓ 65.54s
py 3.11
✕ timeout
✓ 62.49s
py 3.12
✕ build_error
✓ 56.26s
py 3.13
✕ build_error
✓ 53.03s
py 3.9
✕ build_error
8/28 runs
4501MB installed
● package 4501MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AutoDetectionModel
from sahi import AutoDetectionModel
from sahi.models import AutoDetectionModel
`AutoDetectionModel` is directly available under the `sahi` package namespace.
get_sliced_prediction
from sahi.predict import get_sliced_prediction
read_image_as_pil
from sahi.utils.cv import read_image_as_pil
download_from_url
from sahi.utils.file import download_from_url

This quickstart demonstrates how to load a pre-trained model (e.g., YOLOv8s) using `AutoDetectionModel` and perform sliced inference on an image using `get_sliced_prediction`. It includes steps to download a sample image and print/visualize the detection results. Ensure you have the necessary backend (e.g., `ultralytics`) installed for the chosen `model_type`.

import os import torch from sahi import AutoDetectionModel from sahi.predict import get_sliced_prediction from sahi.utils.cv import read_image from sahi.utils.file import download_from_url # Download a sample image image_url = 'https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/small-vehicles1.jpeg' image_path = 'small-vehicles1.jpeg' download_from_url(image_url, image_path) # Download a YOLOv8s model (requires ultralytics installed: pip install ultralytics) model_path = 'yolov8s.pt' # This utility helps download; in a real scenario, you might have your own model. if not os.path.exists(model_path): # You would typically download a model or use an existing path # For this example, we'll try to use a common Ultralytics model. # For a real quickstart, ensure 'ultralytics' is installed and `yolov8s.pt` is available. print(f"Please ensure '{model_path}' is available or install 'ultralytics' and download it.") # Placeholder for actual download if ultralytics is installed # from ultralytics import YOLO # model = YOLO('yolov8s.pt') # This would download it if not present # Then you would pass model.model.pt for model_path or the YOLO object directly to AutoDetectionModel # Fallback or specific model path if `yolov8s.pt` is not handled by AutoDetectionModel without explicit ultralytics import # For simplicity, assuming a yolov8s.pt is present or can be loaded by AutoDetectionModel # Initialize the detection model device = 'cuda:0' if torch.cuda.is_available() else 'cpu' detection_model = AutoDetectionModel.from_pretrained( model_type='ultralytics', # Or 'yolov5', 'mmdet', 'huggingface', 'torchvision', etc. model_path=model_path, # Path to your pretrained model weights confidence_threshold=0.3, device=device ) # Perform sliced inference result = get_sliced_prediction( read_image(image_path), detection_model, slice_height=256, slice_width=256, overlap_height_ratio=0.2, overlap_width_ratio=0.2 ) # Print detection results print(f"Detected {len(result.object_prediction_list)} objects.") for i, prediction in enumerate(result.object_prediction_list): print(f" Detection {i+1}: Class={prediction.category.name}, Confidence={prediction.score.value:.3f}") # Export visuals (optional, requires opencv-python-headless or opencv-python) output_dir = './sahi_output' os.makedirs(output_dir, exist_ok=True) result.export_visuals(export_dir=output_dir, file_name='prediction_visual.png') print(f"Visualizations saved to {output_dir}/prediction_visual.png")
Debug
Known issues
breakingThe `confidence_threshold` parameter in `AutoDetectionModel.from_pretrained` changed its behavior or effect. Previously, it might have only filtered detections. Newer versions (around 0.11.27 and later discussions) suggest it can also influence the bounding box size or shape, not just filter by score. Always verify expected behavior for a given SAHI version.
fix
Thoroughly test model outputs, especially bounding box coordinates, after upgrading or changing `confidence_threshold` values. If issues arise, convert `PredictionResult` to COCO annotations for manual plotting or analysis to verify results.
affects: >=0.11.27
gotchaThe `BoundingBox` and `Category` objects were made immutable in versions 0.11.29 and 0.11.31 respectively. Direct modification of their attributes will now raise an error.
fix
Instead of modifying `BoundingBox` or `Category` objects directly, create new instances with desired values. For example, use methods like `get_shifted_box()` or create a new `BoundingBox` object.
affects: >=0.11.31
gotchaWhen working in multi-GPU environments, especially with subprocesses or certain frameworks (like Detectron2), models might default to loading on 'cuda:0' causing imbalanced GPU utilization. This was specifically addressed in 0.11.34 for subprocesses.
fix
Explicitly set the `device` parameter (e.g., 'cuda:1') when initializing `AutoDetectionModel` to distribute load. For versions prior to 0.11.34, custom scripts might be needed to manage GPU assignments across processes.
affects: <0.11.34
gotchaSAHI significantly increases inference time due to processing multiple slices. It is generally not recommended for real-time applications where latency is critical.
fix
Evaluate performance needs carefully. If real-time inference is critical, consider optimizing the base object detection model or using different techniques. If accuracy on small objects outweighs speed, SAHI is appropriate.
affects: *
gotchaSome users have reported degraded performance (fewer detections, lower confidence) when applying SAHI to models that already perform well on an original dataset without slicing.
fix
Experiment with SAHI's slicing hyperparameters (slice_height, slice_width, overlap_ratios) and post-processing techniques (e.g., NMS thresholds) to optimize for your specific dataset and model. Slicing hyperparameters should align with the model's training input sizes.
affects: *
Upgrade
Version history
0.12.1latest on PyPI · released Jun 8, 2026
Audit
Dependencies
torchrequiredUnderlying deep learning framework for most model backends.
torchvisionrequiredOften used with PyTorch models, especially for computer vision tasks.
opencv-pythonrequiredUsed for image processing utilities.
ultralyticsoptionalRequired for YOLOv8/YOLOv5 model support.
mmdetoptionalRequired for MMDetection framework support.
detectron2optionalRequired for Detectron2 framework support.
transformersoptionalRequired for HuggingFace object detector support.
shapelyoptionalRequired for geometric operations, especially on Windows with certain installations.
Agent activity
15 hits · last 30 days
node
14
OpenAI (training)
1
Resources
sahi — pip install sahi · libregistry