SAHI：切片辅助超推理

一个用于大规模目标检测与实例分割的轻量级视觉库

概述

SAHI 通过支持在大图像中检测小物体的 切片推理，帮助开发者克服目标检测中的现实挑战。它支持多种流行的检测模型，并提供易于使用的 API。

社区认可

📜 引用 SAHI 的出版物列表（目前超过 600 篇）

🏆 使用过 SAHI 的竞赛获奖者列表

AI 工具认可

SAHI 的文档已被 indexed in Context7 MCP，为 AI 编码助手提供最新、特定于版本的代码示例和 API 参考。我们还提供一个遵循新兴 AI 可读文档标准的 llms.txt 文件。要将 SAHI 文档集成到您的 AI 开发工作流中，请查看 Context7 MCP 安装指南。

安装

基本安装

pip install sahi

pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu126

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

pip install ultralytics>=8.3.161

pip install transformers>=4.49.0 timm

pip install yolov5==7.0.14 sahi==0.11.21

pip install mim
mim install mmdet==3.3.0

pip install inference>=0.51.5 rfdetr>=1.6.2

快速入门

学习资源

笔记本与演示

框架	笔记本	演示
YOLO12		—
YOLO11		—
YOLO11-OBB		—
Roboflow / RF-DETR		—
RT-DETR v2		—
RT-DETR		—
HuggingFace		—
YOLOv5		—
MMDetection		—
TorchVision		—
YOLOX	—

框架无关的切片/标准预测

有关使用 sahi predict 命令的详细信息，请参阅 CLI 文档，并探索 预测 API 以获取高级用法。

有关视频推理的详细信息，请参阅 视频推理教程。

错误分析图表与评估

详细信息请参阅 错误分析图表与评估。

交互式可视化与检查

探索 FiftyOne 集成，以实现交互式可视化和检查。

其他工具

请查阅全面的 COCO 工具指南，了解 YOLO 转换、数据集切片、子采样、过滤、合并和拆分等操作。更多关于切片工具的信息，可帮助您对图像和数据集的切片参数进行精细控制。

引用

如果您在工作中使用本软件包，请按以下格式引用：

@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},
  title        = {{SAHI: 用于大规模目标检测和实例分割的轻量级视觉库}},
  month        = nov,
  year         = 2021,
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.5718950},
  url          = {https://doi.org/10.5281/zenodo.5718950}
}

贡献

我们欢迎各类贡献！请参阅我们的贡献指南以开始参与。感谢所有贡献者 🙏！

SAHI 快速上手指南

SAHI (Slicing Aided Hyper Inference) 是一个轻量级视觉库，专为解决大图像中小目标检测难题而设计。它通过切片推理技术，将大图切割成小块分别检测，再合并结果，显著提升小目标的检测精度。

1. 环境准备

• 操作系统: Linux, macOS, Windows
• Python: 3.8+
• 核心依赖: PyTorch, torchvision
• 可选检测框架: Ultralytics (YOLOv8/v10), MMDetection, Hugging Face Transformers, YOLOv5 等

注意：请确保已安装与你的 CUDA 版本匹配的 PyTorch。如果使用 mmdet，需特定版本的 PyTorch (如 2.1.2)。

2. 安装步骤

基础安装

直接通过 pip 安装核心库：

pip install sahi

完整环境配置（推荐）

根据你使用的检测模型框架，选择以下一种方案进行安装：

方案 A：使用 Ultralytics (YOLOv8/v10 等)

# 安装 PyTorch (示例为 CUDA 12.6，请根据实际情况调整)
pip install torch==2.7.0 torchvision==0.22.0 --index-url https://download.pytorch.org/whl/cu126

# 安装 Ultralytics
pip install ultralytics>=8.3.161

# 安装 SAHI
pip install sahi

方案 B：使用 Hugging Face Models

pip install torch torchvision
pip install transformers>=4.49.0 timm
pip install sahi

方案 C：使用 MMDetection

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

国内加速建议：如遇下载缓慢，可使用清华或阿里镜像源。 例如：pip install sahi -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 基本使用

SAHI 提供了简单的 Python API 和命令行工具。以下是两种最常用的方式。

方式一：Python API 调用（最灵活）

适用于在代码中集成切片推理功能。

from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction

# 1. 加载检测模型 (以 YOLOv8 为例)
detection_model = AutoDetectionModel.from_pretrained(
    model_path='yolov8n.pt',
    confidence_threshold=0.25,
    device="cuda", # 或 "cpu"
)

# 2. 执行切片推理
# source: 图片路径、视频路径或目录
# slice_height/width: 切片尺寸
# overlap_height_ratio/overlap_width_ratio: 重叠率
result = get_sliced_prediction(
    "large_image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2
)

# 3. 查看结果或导出
print(f"检测到 {len(result.object_prediction_list)} 个目标")
result.export_visuals(export_dir="./output")

方式二：命令行工具 (CLI)

适用于快速测试或对批量数据进行处理，无需编写代码。

对单张图片进行切片预测：

sahi predict \
    --source image.jpg \
    --model_path yolov8n.pt \
    --model_type yolov8 \
    --slice_height 512 \
    --slice_width 512 \
    --overlap_height_ratio 0.2 \
    --overlap_width_ratio 0.2 \
    --conf_th 0.25 \
    --device cuda

常用参数说明：

• --model_type: 支持 yolov8, mmdet, huggingface, torchvision 等。
• --slice_height / --slice_width: 切片的大小，小目标较多时可适当调小。
• --overlap_*_ratio: 切片间的重叠比例，防止目标被切断，通常设为 0.2。
• --novisual: 添加此参数可跳过可视化图片的生成，仅保存 JSON 结果。