<div align="center">
<img width="90" alt="SAHI logo" src="https://raw.githubusercontent.com/obss/sahi/main/docs/images/sahi-logo.svg">
<h1>
  SAHI: 切片辅助高效推理
</h1>

<h4>
  一个轻量级的计算机视觉库，可实现大规模的目标检测和实例分割
</h4>

<h4>
    <img width="700" alt="teaser" src="https://raw.githubusercontent.com/obss/sahi/main/resources/sahi-sliced-inference-overview.avif">
</h4>

<!-- 下载量 & 版本 -->
<div>
  <a href="https://pepy.tech/project/sahi"><img src="https://pepy.tech/badge/sahi" alt="总下载量"></a>
  <a href="https://pepy.tech/project/sahi"><img src="https://pepy.tech/badge/sahi/month" alt="月下载量"></a>
  <a href="https://badge.fury.io/py/sahi"><img src="https://badge.fury.io/py/sahi.svg" alt="PyPI 版本"></a>
  <a href="https://anaconda.org/conda-forge/sahi"><img src="https://anaconda.org/conda-forge/sahi/badges/version.svg" alt="Conda 版本"></a>
  <a href="https://github.com/obss/sahi/blob/main/LICENSE.md"><img src="https://img.shields.io/pypi/l/sahi" alt="许可证"></a>
</div>

<!-- CI & 质量 -->
<div>
  <a href="https://github.com/obss/sahi/actions/workflows/ci.yml"><img src="https://github.com/obss/sahi/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://snyk.io/test/github/obss/sahi"><img src="https://snyk.io/test/github/obss/sahi/badge.svg" alt="已知漏洞"></a>
  <a href="https://www.codefactor.io/repository/github/onuralpszr/sahi"><img src="https://www.codefactor.io/repository/github/onuralpszr/sahi/badge" alt="CodeFactor"></a>
  <a href="https://ieeexplore.ieee.org/document/9897990"><img src="https://img.shields.io/badge/DOI-10.1109%2FICIP46576.2022.9897990-orange.svg" alt="DOI"></a>
</div>

<!-- AI & 文档 -->
<div>
  <a href="https://context7.com/obss/sahi"><img src="https://img.shields.io/badge/Context7%20MCP-Indexed-blue" alt="Context7 MCP"></a>
  <a href="https://context7.com/obss/sahi/llms.txt"><img src="https://img.shields.io/badge/llms.txt-✓-brightgreen" alt="llms.txt"></a>
  <a href="https://deepwiki.com/obss/sahi"><img src="https://img.shields.io/badge/DeepWiki-obss%2Fsahi-blue.svg?logo=data:image/png;base64, " alt="DeepWiki"></a>
  <a href="https://huggingface.co/spaces/fcakyon/sahi-yolox"><img src="https://raw.githubusercontent.com/obss/sahi/main/resources/hf_spaces_badge.svg" alt="HuggingFace Spaces"></a>
</div>

</div>

## <div align="center">概览</div>

SAHI 通过启用**切片推理**来检测大图像中的小物体，从而帮助开发人员克服了对象检测中的实际挑战。它支持各种流行的检测模型并提供易于使用的 API。

<div align="center">

🌐 [English](../../README.md) | 🇨🇳 [简体中文](README.md) | 🇹🇷 [Türkçe](../tr/README.md)

</div>

| 命令                                                                                                  | 描述                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [predict](https://github.com/obss/sahi/blob/main/docs/cli.md#predict-command-usage)                   | 使用任意 [ultralytics](https://github.com/ultralytics/ultralytics) / [mmdet](https://github.com/open-mmlab/mmdetection) / [huggingface](https://huggingface.co/models?pipeline_tag=object-detection&sort=downloads) / [torchvision](https://pytorch.org/vision/stable/models.html#object-detection) 模型进行切片或标准视频/图像预测 -- 参见 [CLI 指南](cli.md#predict-command-usage) |
| [predict-fiftyone](https://github.com/obss/sahi/blob/main/docs/cli.md#predict-fiftyone-command-usage) | 使用任意支持的模型进行切片或标准预测，并在 [fiftyone 应用](https://github.com/voxel51/fiftyone) 中探索结果 -- [了解更多](fiftyone.md)                                                                                                                                                                                                                                                |
| [coco slice](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-slice-command-usage)             | 自动切片 COCO 标注和图像文件 -- 参见 [切片工具](slicing.md)                                                                                                                                                                                                                                                                                                                          |
| [coco fiftyone](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-fiftyone-command-usage)       | 在 [fiftyone ui](https://github.com/voxel51/fiftyone) 中探索 COCO 数据集的多个预测结果，按错误检测数量排序                                                                                                                                                                                                                                                                           |
| [coco evaluate](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-evaluate-command-usage)       | 针对给定的预测和真实数据评估 COCO 的类级别 AP 和 AR -- 查看 [COCO 工具](coco.md)                                                                                                                                                                                                                                                                                                     |
| [coco analyse](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-analyse-command-usage)         | 计算并导出多种错误分析图表 -- 参见 [完整指南](index.md)                                                                                                                                                                                                                                                                                                                              |
| [coco yolo](https://github.com/obss/sahi/blob/main/docs/cli.md#coco-yolo-command-usage)               | 将任意 COCO 数据集自动转换为 [ultralytics](https://github.com/ultralytics/ultralytics) 格式                                                                                                                                                                                                                                                                                          |

### 社区认可

[📜 引用 SAHI 的出版物列表（当前超过 600 篇）](https://scholar.google.com/scholar?hl=en&as_sdt=2005&sciodt=0,5&cites=14065474760484865747&scipsc=&q=&scisbd=1)

[🏆 使用 SAHI 的竞赛获奖者列表](https://github.com/obss/sahi/discussions/688)

### AI 工具认可

SAHI 的文档已在 [Context7 MCP](https://context7.com/obss/sahi)
中建立索引，为 AI 编码助手提供最新的，版本特定的代码示例和 API 参考。我们还提供了一个遵循 AI 可读文档新兴标准的
[llms.txt](https://context7.com/obss/sahi/llms.txt)
文件。要将 SAHI 文档集成到您的 AI 开发工作流程中，请查看
[Context7 MCP 安装指南](https://github.com/upstash/context7#%EF%B8%8F-installation).

## <div align="center">安装</div>

### 基本安装

```bash
pip install sahi
```

<details closed>
<summary>
<big><b>详细安装说明（点击展开）</b></big>
</summary>

- 安装您所需的 PyTorch 和 torchvision 版本：

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

（为了获得 mmdet 框架的支持，您需要安装 torch 2.1.2 版本）：

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

- 安装您所需的检测框架 (ultralytics):

```console
pip install ultralytics>=8.3.161
```

- 安装您所需的检测框架 (huggingface):

```console
pip install transformers>=4.49.0 timm
```

- 安装您所需的检测框架 (yolov5):

```console
pip install yolov5==7.0.14 sahi==0.11.21
```

- 安装您所需的检测框架 (mmdet):

```console
pip install mim
mim install mmdet==3.3.0
```

- 安装您所需的检测框架 (roboflow):

```console
pip install inference>=0.51.5 rfdetr>=1.6.2
```

</details>

## <div align="center">快速开始</div>

### 学习资源

| 资源                                                                                                                                     | 类型     |
| ---------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| [SAHI 简介](https://medium.com/codable/sahi-a-vision-library-for-performing-sliced-inference-on-large-images-small-objects-c8b086af3b80) | 博客文章 |
| [视频教程（2025年）](https://www.youtube.com/watch?v=ILqMBah5ZvI) ⭐                                                                     | 视频     |
| [官方论文](https://ieeexplore.ieee.org/document/9897990) (ICIP 2022 oral)                                                                | 论文     |
| [预训练权重 和 ICIP 2022 论文文件](https://github.com/fcakyon/small-object-detection-benchmark)                                          | 基准测试 |
| [使用 FiftyOne 可视化并评估 SAHI 的预测结果](https://voxel51.com/blog/how-to-detect-small-objects/)                                      | 博客文章 |
| [《探索 SAHI》-- learnopencv.com](https://learnopencv.com/slicing-aided-hyper-inference/)                                                | 文章     |
| [Encord 对 Slicing Aided Hyper Inference（SAHI）的解读](https://encord.com/blog/slicing-aided-hyper-inference-explained/)                | 文章     |
| [视频教程：SAHI 在小目标检测中的应用](https://www.youtube.com/watch?v=UuOJKxn-M8&t=270s)                                                 | 视频     |
| [卫星图像目标检测](https://blog.ml6.eu/how-to-detect-small-objects-in-very-large-images-70234bab0f98)                                    | 博客文章 |
| [COCO 数据集转换](https://medium.com/codable/convert-any-dataset-to-coco-object-detection-format-with-sahi-95349e1fe2b7)                 | 博客文章 |
| [Kaggle notebook](https://www.kaggle.com/remekkinas/sahi-slicing-aided-hyper-inference-yv5-and-yx)                                       | Notebook |
| [误差分析绘图 & 评估](https://github.com/obss/sahi/discussions/622) ⭐                                                                   | 讨论     |
| [交互式结果可视化与检查](https://github.com/obss/sahi/discussions/624) ⭐                                                                | 讨论     |
| [视频推理支持](https://github.com/obss/sahi/discussions/626)                                                                             | 讨论     |
| [切片操作 Notebook](../../demo/slicing.ipynb)                                                                                            | Notebook |
| [完整文档](index.md)                                                                                                                     | 文档     |

### Notebooks & 示例

| 框架               | Notebook                                                                                                                                                                        | 示例                                                                                                                                                      |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| YOLO26             | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | —                                                                                                                                                         |
| YOLO12             | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | —                                                                                                                                                         |
| YOLO11             | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | —                                                                                                                                                         |
| YOLO11-OBB         | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_ultralytics.ipynb) | —                                                                                                                                                         |
| Roboflow / RF-DETR | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_roboflow.ipynb)    | —                                                                                                                                                         |
| RT-DETR v2         | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_huggingface.ipynb) | —                                                                                                                                                         |
| RT-DETR            | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_rtdetr.ipynb)      | —                                                                                                                                                         |
| HuggingFace        | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_huggingface.ipynb) | —                                                                                                                                                         |
| YOLOv5             | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_yolov5.ipynb)      | —                                                                                                                                                         |
| MMDetection        | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_mmdetection.ipynb) | —                                                                                                                                                         |
| TorchVision        | [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/obss/sahi/blob/main/demo/inference_for_torchvision.ipynb) | —                                                                                                                                                         |
| YOLOX              | —                                                                                                                                                                               | [![HuggingFace Spaces](https://raw.githubusercontent.com/obss/sahi/main/resources/hf_spaces_badge.svg)](https://huggingface.co/spaces/fcakyon/sahi-yolox) |

<a href="https://huggingface.co/spaces/fcakyon/sahi-yolox"><img width="600" src="https://user-images.githubusercontent.com/34196005/144092739-c1d9bade-a128-4346-947f-424ce00e5c4f.gif" alt="sahi-yolox"></a>

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

<img width="700" alt="sahi-predict" src="https://user-images.githubusercontent.com/34196005/149310540-e32f504c-6c9e-4691-8afd-59f3a1a457f0.gif">

请在 [CLI 文档](cli.md#predict-command-usage) 中查找关于使用 `sahi predict`
命令的详细信息，并查阅 [预测 API](predict.md) 以了解高级用法。

请在 [视频推理教程](https://github.com/obss/sahi/discussions/626)
中查找关于视频推理的详细信息。

### 误差分析绘图 & 评估

<img width="700" alt="sahi-analyse" src="https://user-images.githubusercontent.com/34196005/149537858-22b2e274-04e8-4e10-8139-6bdcea32feab.gif">

请在 [误差分析绘图 & 评估](https://github.com/obss/sahi/discussions/622)
中查找相关的详细信息。

### 交互式结果可视化与检查

<img width="700" alt="sahi-fiftyone" src="https://user-images.githubusercontent.com/34196005/149321540-e6dd5f3-36dc-4267-8574-a985dd0c6578.gif">

探索 [FiftyOne 集成](fiftyone.md) 以实现交互式可视化与检查。

### 其他实用工具

请查阅 [完整的 COCO 工具指南](coco.md)
了解 YOLO 格式转换、数据集切片、子采样、筛选、合并与分割等操作。了解更多关于
[切片工具](slicing.md) ，以实现对图像和数据集切片参数的精细控制。

## <div align="center">引用</div>

如果您在您的工作中使用了这个包，请如下文引用：

```bibtex
@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}
}
```

```bibtex
@software{obss2021sahi,
  author       = {Akyon, Fatih Cagatay and Cengiz, Cemil and Altinuc, Sinan Onur and Cavusoglu, Devrim and Sahin, Kadir and Eryuksel, Ogulcan},
  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}
}
```

## <div align="center">贡献者</div>

欢迎贡献！请参阅我们的 [贡献指南](contributing.md)
来开始使用。感谢所有贡献者！

<p align="center">
    <a href="https://github.com/obss/sahi/graphs/contributors">
      <img src="https://contrib.rocks/image?repo=obss/sahi" />
    </a>
</p>
