sahi

obssMIT活跃维护

把超大图像切成小块做切片推理，再拼回完整结果，兼容任意检测/分割模型，还带交互式界面和误差分析图。

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

0.14.0发布于 2026-11-01 01:43 UTC5,596star +5 / 7 天793fork同步于 2026-11-10 11:35 UTC

切片推理目标检测实例分割大图推理误差分析

对比 GitHub 官网 coco computer-vision deep-learning explainable-ai fiftyone

怎么上手

由 README 提炼，执行前请确认

原文

pip install sahi
pip install ultralytics>=8.3.161

硬件要求按 README 说明

README 未说明具体显存或 GPU 型号要求；推理依赖 PyTorch，实际硬件需求取决于所选检测框架与模型

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼

没人工点评？写下你的经验

框架无关的切片推理库，专治大图小目标漏检，附带交互式 UI 和误差分析图

把超大图像切成小块做切片推理，再拼回完整结果，兼容任意检测/分割模型，还带交互式界面和误差分析图。

核心能力

按切片方式做图像/视频推理，提升大图小目标检出
兼容 ultralytics、mmdet、huggingface、torchvision 等模型
提供 CLI 一键切片 COCO 数据集并转换 YOLO 格式
用 FiftyOne 交互式浏览预测结果并按误检数排序
导出 COCO 误差分析图表与逐类 AP/AR 评估

容易踩的坑

sahi 本身不含模型，需另装 ultralytics/mmdet/huggingface 等检测框架；mmdet 支持要求 torch 2.1.2 与 torchvision 0.16.2；yolov5 需锁定 yolov5==7.0.14 与 sahi==0.12.1 版本组合

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本0.14.0

全部 release

0.14.0最新正式版2026-11-01 · 2026-11-01 01:43 UTC

A minor release that moves the tests, docs and examples to YOLO26, defaults YOLOE to YOLOE-26, fixes bugs in the YOLOE, YOLO-World, torchvision, Hugging Face and mmdet wrappers, downloads and scripts, and makes COCO slicing and mask drawing faster with the same output.

💥 Breaking Changes

YOLOE loads yoloe-26s-seg.pt when no model_path is given (#1499) instead of yoloe-11s-seg.pt. Pass model_path to keep using YOLOE-11.
The hugging_face_universal_segmentation model type is removed (#1498). It had no module behind it and always failed with ModuleNotFoundError. Use huggingface_segmentation for those models.

🐛 Fixes

YOLOE and YOLO-World predictions use the class names set with set_classes (#1499) instead of '0', '1' and so on. A category_mapping you pass in is still kept.
model_type="yolo-world" loads (#1498). The registered class name was misspelled, so it always failed with AttributeError.
The torchvision wrapper keeps every image of a batch (#1502) with its own shift amount and full shape, instead of only the last image.
Hugging Face panoptic segmentation keeps batch outputs paired with their slices (#1502). An image with no segments was dropped, so the predictions after it got the wrong slice positions.
mmdet inference no longer has a path that raises NameError (#1502).
python -m sahi.scripts.slice_coco runs (#1501). It passed the builtin slice to Fire instead of slicer.
predict adds up the export time of every image (#1501) instead of keeping only the last one, and no longer raises KeyError with verbose=2 when there are no images.
predict_fiftyone counts the prediction time of sliced predictions (#1501).
sahi env shows pillow and every installed OpenCV distribution (#1501), and no longer lists tensorflow, which sahi does not use.
Downloads write to a temporary file first (#1495, #1504), so an interrupted download never leaves a broken model file that later runs would load. The YOLOv5 helpers used by the YOLOv5 notebook now go through the same download code.

⚡ Performance

All of these give the same output as before (#1503).

Benchmark	v0.13.1	v0.14.0
`slice_coco` on 50 VisDrone images, 6493 sliced annotations	1.48 s	0.92 s
Drawing 80 masks on a 4K image	2.09 s	0.15 s
Drawing masks on 100 frames of the OpenCV `vtest.avi` video	1.20 s	0.12 s

Slicing computes each annotation's bbox and area once per image instead of once per slice.
Mask drawing blends only the area each mask covers instead of the whole image.
Sliced prediction and SliceImageResult indexing no longer rebuild the slice lists on every access, and predict converts each image to an array once for all exports.

🧹 Maintenance & CI

Tests and CI commands use YOLO26 (#1496) for detection, segmentation, OBB and ONNX export.
CI installs CPU torch (#1494), which makes the CI caches about three times smaller.
from __future__ import annotations is removed (#1500) now that Python 3.10 is the minimum, and ruff stops it from coming back.

📚 Documentation

The README, docs and examples use YOLO26 (#1497

0.13.12026-10-31 · 2026-10-31 18:01 UTC
查看更新说明
A patch release that adds Python 3.15 support.

📦 Build
- Python 3.15 is supported and tested in CI (#1492). Core sahi installs and runs on 3.15. torch 2.15.0 and torchvision 0.29.2 are the first releases with Python 3.15 wheels, so installing the torch or torchvision extra on 3.15 picks those versions or newer.
- The onnx extra skips onnxruntime on Python 3.15 (#1492) until onnxruntime ships wheels for it.
0.13.02026-10-31 · 2026-10-31 15:18 UTC
查看更新说明
A minor release that drops Python 3.8 and 3.9, raises the torch floor to 2.13.0 on every supported Python, and fixes seven bugs in slicing, COCO handling, shapely annotations and image normalization.

💥 Breaking Changes
- Python 3.10 or newer is required (#1485). Python 3.8 and 3.9 are end of life and torch no longer ships wheels for them. Older Python versions keep installing sahi 0.12.8.
- The torch extra needs torch 2.13.0 or newer and the torchvision extra needs torchvision 0.28.0 or newer (#1485, #1488), which clears the torch security alerts that came from the old Python 3.8 and 3.9 pins.
🐛 Fixes
- shift_masks moves the mask pixels to their place in the full image (#1471). It read each row of a boolean mask as a polygon, so the shifted masks were wrong.
- COCO annotations keep their iscrowd flag (#1472) when loaded, clipped and exported, instead of always being written as 0.
- Slicing skips zero-area annotations (#1473) instead of stopping with ZeroDivisionError.
- get_subsampled_coco filters category 0 (#1479). category_id=0 was treated as no category, so every category was subsampled.
- YOLO export only replaces the image suffix in label paths (#1480), so folders or file names that contain the suffix, such as export.jpg/ or photo.jpg.backup.jpg, keep their names.
- Simplifying and buffering annotations made of several polygons works (#1481) instead of raising ValueError.
- normalize_numpy_image returns zeros for an all-black image (#1482) instead of NaN.
- Buffering annotations no longer warns about a deprecated shapely argument (#1489).
🧹 Maintenance & CI
- CI keeps testing the oldest supported torch and torchvision (#1491). Dependabot no longer bumps their CI pins, which move only when the floor is raised.
- CI tests Python 3.10 to 3.14 (#1485).
📚 Documentation
- The test guide matches the current test suite and CI (#1488), and the contributing guide recommends Python 3.12 for development in every language.
0.12.82026-09-30 · 2026-09-30 16:52 UTC
查看更新说明
A patch release that adds LibreYOLO as a detection backend, fixes seven bugs in COCO category remapping, slicing, mask conversion and box merging, and builds boolean masks faster.

✨ Features
- LibreYOLO detection backend (#1425). Install it with pip install libreyolo and load MIT-licensed LibreYOLO models with model_type="libreyolo". It reuses the Ultralytics wrapper, and the models guide covers it in every language (#1467).
🐛 Fixes
- Sliced annotations that touch the slice border are kept (#1462). When a polygon edge lay exactly on a slice border, the intersection came back as a mix of polygons and lines and the annotation was dropped with area 0. The polygon parts are now kept.
- NMM merges boxes whose overlap equals the match threshold (#1464). These boxes were claimed by the keeper but never merged, so they disappeared from the output and the keeper box did not grow.
- get_bool_mask_from_coco_segmentation returns a boolean array (#1463). It returned the float64 canvas, so Mask.bool_mask could not be used to index an image.
- Category remapping maps each id once (#1465). With remapping_dict={0: 1, 1: 2} both categories ended up with id 2 and loading failed with KeyError.
- Subsampled, upsampled, area filtered and bbox clipped Coco objects keep their categories (#1466). They applied remapping_dict a second time to ids that were already remapped, which also affected clip_bboxes_to_img_dims=True.
- Class-aware NMM and greedy NMM accept an image with no detections (#1470) instead of raising AttributeError.
- fix_shift_amount_list and fix_full_shape_list accept empty lists (#1459) instead of raising IndexError.
⚡ Performance
- Boolean masks from COCO polygons build about 8x faster (#1463). The mask is drawn on a uint8 canvas instead of float64, which takes a 1080p mask from 1.03 ms to 0.13 ms on an Intel Core i7-13850HX and uses 8x less memory.
📚 Documentation
- The Chinese and Turkish docs match the English docs again (#1461).
- The RT-DETR guide uses the Ultralytics weights the backend loads (#1467), and the coco slice CLI docs no longer list a --backend option it does not have (#1460).
0.12.72026-09-25 · 2026-09-25 02:55 UTC
查看更新说明
A patch release that adds an optional ultrafast-pycocotools backend to COCO evaluation, fixes four crashes and miscounts in COCO and video utilities, speeds up postprocessing and sliced prediction, and raises the torch floor to 2.13.0 on Python 3.10 and newer.

✨ Features
- sahi coco evaluate can run on ultrafast-pycocotools (https://github.com/obss/sahi/pull/1452). Install it with pip install "sahi[ultrafast]" and pass --backend ultrafast on the CLI or backend="ultrafast" to sahi.scripts.coco_evaluation.evaluate. pycocotools stays the default, and the tests check that both backends return the same bbox and segm results (https://github.com/obss/sahi/pull/1457).
🐛 Fixes
- COCO evaluation accepts a list of IoU thresholds (https://github.com/obss/sahi/pull/1452). Passing iou_thrs as a list stopped in the summary step with a NumPy "nonzero on 0d arrays" error. Thresholds are now always stored as an array.
- Video prediction counts skipped frames correctly (https://github.com/obss/sahi/pull/1449). The progress bar total only accounted for frame_skip_interval while a visual was shown, and the exported video used fps / frame_skip_interval instead of fps / (frame_skip_interval + 1), so it played back faster than the source.
- remove_invalid_coco_results skips bboxes that do not have four values (https://github.com/obss/sahi/pull/1455) instead of raising IndexError.
- get_coco_segmentation_from_obb_points returns an empty list for empty input (https://github.com/obss/sahi/pull/1456) instead of raising IndexError.
⚡ Performance
- NMS and greedy NMM choose the stored-pair path again when boxes are spread out (https://github.com/obss/sahi/pull/1443). Since 0.12.5 they always read rows from the STRtree on demand, which is slower than a stored pair list when boxes are spread out. They now pick the path by crowding the same way NMM does, and the output is unchanged.
- Streaming postprocessing drops boxes it has finished with (https://github.com/obss/sahi/pull/1426). Settled boxes are removed from later STRtree queries, so crowded inputs query a tree that shrinks as the loop runs.
- Sliced prediction decodes the source image once (https://github.com/obss/sahi/pull/1445). get_sliced_prediction used to decode the file four times. It now reuses the decode that slicing already holds.
- slice_image uses less peak memory (https://github.com/obss/sahi/pull/1421). Local files decode straight to a NumPy array with OpenCV instead of going through Pillow, and read_image_size reads the size from the file header without decoding the image. 16-bit files and anything else OpenCV declines use the Pillow path as before.
📦 Build
- The torch floor is 2.13.0 on Python 3.10 and newer (https://github.com/obss/sahi/pull/1440), 2.8.0 on Python 3.9 and 2.4.1 on Python 3.8, the newest release each of them still has wheels for.
- Development installs pick the torch build that matches the machine (https://github.com/obss/sahi/pull/1446), CUDA or CPU, instead of always CPU.
- CI tests Python 3.13 and 3.14 (https://github.com/obss/sahi/pull/1433).
📚 Documentation
- Documented commands, defaults and examples match the code (https://github.com/obss/sahi/pull/1427, https://github.com/obss/sahi/pull/1452). This includes the coco evaluate options, which now list --type segm, --max_detections and --backend.
- The quick start ends in a prediction, pages link to the next page, and API parameters are shown as tables (https://github.com/obss/sahi/pull/1428, https://github.com/obss/sahi/pull/1429).
- The docs point at the site they are published on and serve their markdown (https://github.com/obss/sahi/pull/1431), and demo links resolve outside GitHub (https://github.com/obss/sahi/pull/1435).
- A new notebook measures batched sliced inference speed (https://github.com/obss/sahi/pull/1447) on the machine it runs on and checks that batching does not chan

用户点评

登录用户的真实使用记录，可按版本和硬件筛选

共 0 条

还没有人点评。第一个说出真实体验的人最有价值。

README 原文

未翻译

在 GitHub 打开

Overview

SAHI helps developers overcome real-world challenges in object detection by enabling sliced inference for detecting small objects in large images. It supports various popular detection models and provides easy-to-use APIs.

🌐 English | 🇨🇳 简体中文 | 🇹🇷 Türkçe

Command	Description
predict	Perform sliced/standard video/image prediction using any ultralytics / mmdet / huggingface / torchvision model, see CLI guide
predict-fiftyone	Perform sliced/standard prediction using any supported model and explore results in fiftyone app, learn more
coco slice	Automatically slice COCO annotation and image files, see slicing utilities
coco fiftyone	Explore multiple prediction results on your COCO dataset with fiftyone ui ordered by number of misdetections
coco evaluate	Evaluate classwise COCO AP and AR for given predictions and ground truth, check COCO utilities
coco analyse	Calculate and export many error analysis plots, see the complete guide
coco yolo	Automatically convert any COCO dataset to ultralytics format

Approved by the Community

📜 List of publications that cite SAHI (currently 600+)

🏆 List of competition winners that used SAHI

Approved by AI Tools

SAHI's documentation is indexed in Context7 MCP, providing AI coding assistants with up-to-date, version-specific code examples and API references. We also provide an llms.txt file following the emerging standard for AI-readable documentation. To integrate SAHI docs with your AI development workflow, check out the Context7 MCP installation guide.

Installation

Basic Installation

pip install sahi

Install your desired version of pytorch and torchvision:

pip install torch==2.13.0 torchvision==0.28.0 --index-url https://download.pytorch.org/whl/cu130

(torch 2.1.2 is required for mmdet support):

pip install torch==2.1.2 torchvision==0.16.2 --index-url https://download.pytorch.org/whl/cu121

Install your desired detection framework (ultralytics):

pip install ultralytics>=8.3.161

Install your desired detection framework (huggingface):

pip install transformers>=4.49.0 timm

Install your desired detection framework (yolov5):

pip install yolov5==7.0.14 sahi==0.12.1

Install your desired detection framework (mmdet):

pip install mim
mim install mmdet==3.3.0

Install your desired detection framework (roboflow):

pip install inference>=0.51.5 rfdetr>=1.6.2

Quick Start

Learning Resources

Resource	Type
Introduction to SAHI	Blog Post
2025 Video Tutorial ⭐	Video
Official Paper (ICIP 2022 oral)	Paper
Pretrained Weights & ICIP 2022 Paper Files	Benchmark
Visualizing and Evaluating SAHI Predictions with FiftyOne	Blog Post
Exploring SAHI on learnopencv.com	Article
Slicing Aided Hyper Inference Explained by Encord	Article
Video Tutorial: SAHI for Small Object Detection	Video
Satellite Object Detection	Blog Post
COCO Dataset Conversion	Blog Post
Kaggle Notebook	Notebook
Error Analysis Plots & Evaluation ⭐	Discussion
Interactive Result Visualization and Inspection ⭐	Discussion
Video Inference Support	Discussion
Slicing Operation Notebook	Notebook
Complete Documentation	Docs

Notebooks & Demos

Framework	Notebook	Demo
YOLO26		-
YOLO26-SEG		-
YOLO26-OBB		-
YOLOE		-
Roboflow / RF-DETR		-
RT-DETR v2		-
RT-DETR		-
HuggingFace		-
GroundingDINO		-
YOLOv5		-
MMDetection		-
Detectron2		-
TorchVision		-
YOLOX	-

Framework Agnostic Sliced/Standard Prediction

Find detailed info on using sahi predict command in the CLI documentation and explore the prediction API for advanced usage.

Find detailed info on video inference at video inference tutorial.

Error Analysis Plots & Evaluation

Find detailed info at Error Analysis Plots & Evaluation.

Interactive Visualization & Inspection

Explore FiftyOne integration for interactive visualization and inspection.

Other Utilities

Check the comprehensive COCO utilities guide for YOLO conversion, dataset slicing, subsampling, filtering, merging, and splitting operations. Learn more about the slicing utilities for detailed control over image and dataset slicing parameters.

Citation

If you use this package in your work, please cite as:

@article{akyon2022sahi,
  title={Slicing Aided Hyper Inference and Fine-tuning for Small Object Detection},
  author={Akyon, Fatih Cagatay and Altinuc, Sinan Onur and Temizel, Alptekin},
  journal={2022 IEEE International Conference on Image Processing (ICIP)},
  doi={10.1109/ICIP46576.2022.9897990},
  pages={966-970},
  year={2022}
}

@software{obss2021sahi,
  author       = {Akyon, Fatih Cagatay and Cengiz, Cemil and Altinuc, Sinan Onur and Cavusoglu, Devrim and Sahin, Kadir and Eryuksel, Ogulcan and Sezer, Onuralp},
  title        = {{SAHI: A lightweight vision library for performing large scale object detection and instance segmentation}},
  month        = nov,
  year         = 2021,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.5718950},
  url          = {https://doi.org/10.5281/zenodo.5718950}
}

Contributing

We welcome contributions! Please see our Contributing Guide to get started. Thank you 🙏 to all our contributors!

怎么上手

项目说明

核心能力

容易踩的坑

最近发版

💥 Breaking Changes

🐛 Fixes

⚡ Performance

🧹 Maintenance & CI

📚 Documentation

📦 Build

💥 Breaking Changes

🐛 Fixes

🧹 Maintenance & CI

📚 Documentation

✨ Features

🐛 Fixes

⚡ Performance

📚 Documentation

✨ Features

🐛 Fixes

⚡ Performance

📦 Build

📚 Documentation

用户点评

README 原文

Overview

Approved by the Community

Approved by AI Tools

Installation

Basic Installation

Quick Start

Learning Resources

Notebooks & Demos

Framework Agnostic Sliced/Standard Prediction

Error Analysis Plots & Evaluation

Interactive Visualization & Inspection

Other Utilities

Citation

Contributing

相关项目