SAHI 快速开始：用切片推理在超大图像上检测小目标（Python 与 CLI 完整实战）-育师

计算机视觉
人工智能

【免费下载链接】sahi

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

项目地址：https://gitcode.com/gh_mirrors/sa/sahi

SAHI（Sliced Aided Hyper Inference）是一个框架无关的切片推理（sliced/tiled inference）工具库：它先把大图像切成相互重叠的小切片，在每个切片上独立运行目标检测器，再把各切片的检测结果合并回完整图像坐标系，从而让原本被下采样到只剩几个像素的小目标保持足够尺寸被可靠检测，且无需重新训练。本篇以 SAHI 官方中文快速入门文档 docs/zh/quick-start.md 为主线，带你从安装、Python API 预测、结果读取到 CLI 批处理完整跑通第一条切片推理管线，并结合仓库源码剖析每一步背后的实现细节。读完本文，你将能够在一台 CPU 机器上直接对航拍图、卫星图等大分辨率图像执行小目标检测，并导出可视化与 COCO 格式结果用于评估。

SAHI 的切片推理效果可以从仓库自带的示例数据直观感受：下面的 demo/demo_data/small-vehicles1.jpeg 是一张典型的航拍小目标车辆样例图，也是快速入门文档中演示代码所下载的测试图像；demo/demo_data/prediction_visual.png 则是调用result.export_visuals()后生成的预测可视化结果，可以看到切片合并后输出的检测框标注。

切片推理解决的核心问题

标准目标检测器在推理前会把输入图像缩放到固定分辨率（例如 640×640）。当原始图像是大尺寸航拍照片或卫星图时，小目标会被下采样到仅几个像素，从而彻底消失、无法检测。

SAHI 的思路分三步（详见 docs/guides/sliced-inference.md）：

切片：把大图按网格切成与模型输入尺寸匹配的小切片，切片之间设置重叠区域，确保落在切片边界上的目标在至少一个切片内完整可见；
推理：对每个切片独立执行检测器推理，并可选地对整图再做一次标准预测（perform_standard_pred=True，默认开启），以捕获被切片"切开"的大目标；
合并：将各切片上的预测框按偏移量映射回整图坐标系，再通过后处理（默认 GREEDYNMM）合并重复框、消除伪影。

在 sahi/predict.py 中，get_sliced_prediction函数完整实现了上述流程：先调用slice_image生成SliceImageResult（内部包含每个切片的图像数组、起始像素坐标与 COCO 元信息），再对每个切片执行推理并用shift_amount与full_shape把预测框搬回原图位置，最后统一做后处理合并。整个调用链清晰且可独立验证，相关行为在 tests/test_predict.py 中有完整覆盖。

1. 安装 SAHI 与检测框架

sahi本身不捆绑任何检测器，因此需要为所用框架选择对应的 extra 一起安装：

pip install "sahi[ultralytics]"

从 pyproject.toml 中的 optional-dependencies 可以确认，可用的 extra 包括：

extra	用途	说明
`ultralytics`	YOLOv8 / YOLO11 / YOLO26 等 Ultralytics 模型	`ultralytics>=8.0.0`
`transformers`	HuggingFace Transformers 检测/零样本检测模型	`transformers>=4.49.0`
`yolov5`	经典 YOLOv5	`yolov5>=6.0.0,<8.0.0`
`torchvision`	TorchVision 内置检测模型	依赖`sahi[torch]`与`torchvision`
`torch`	PyTorch 本体	按 Python 版本选择对应 wheel
`onnx`	ONNX / ONNXRuntime	用于导出与加速
`numba`	Numba 后端加速	`numba>=0.59.0`
`roboflow`	Roboflow RF-DETR 检测/分割模型	`inference`与`rfdetr`
`all`	一次性安装上述全部 extra	体积较大，按需选用

Conda 用户可以先执行conda install -c conda-forge sahi，再单独安装所选的深度学习框架。安装完成后可以通过sahi version查看版本、sahi env查看当前环境中 torch、ultralytics、transformers 等相关包的版本（参见 docs/cli.md）。

2. 获取切片预测结果

以下代码可以在纯 CPU 环境下端到端运行：它会先下载一张示例航拍图，Ultralytics 会在首次使用时自动下载yolo26n.pt权重：

from sahi import AutoDetectionModel from sahi.predict import get_sliced_prediction from sahi.utils.file import download_from_url download_from_url( "https://raw.githubusercontent.com/obss/sahi/main/demo/demo_data/small-vehicles1.jpeg", "demo_data/small-vehicles1.jpeg", ) detection_model = AutoDetectionModel.from_pretrained( model_type="ultralytics", model_path="yolo26n.pt", confidence_threshold=0.25, device="cpu", # 或 "cuda:0" ) result = get_sliced_prediction( "demo_data/small-vehicles1.jpeg", detection_model, slice_height=512, slice_width=512, overlap_height_ratio=0.2, overlap_width_ratio=0.2, )

download_from_url位于 sahi/utils/file.py，若目标路径已存在则不会重复下载，父目录会自动创建。

AutoDetectionModel.from_pretrained：统一模型加载入口

AutoDetectionModel.from_pretrained（实现在 sahi/auto_model.py）是 SAHI 与所有检测框架交互的统一入口。它根据model_type查表（sahi/auto_model.py）选择对应的模型类，再以相同的关键字参数构造模型实例，之后该模型即可无缝用于切片推理、批量推理或 CLI。

常用参数说明：

参数	默认值	含义
`model_type`	必填	框架名：`ultralytics`、`mmdet`、`detectron2`、`huggingface`、`huggingface_segmentation`、`torchvision`、`rtdetr`、`libreyolo`、`yolov5`、`yoloe`、`yolo-world`、`roboflow`等；同时兼容`yolov8`、`yolov11`、`yolo11`、`yolo26`等 Ultralytics 别名（见 sahi/auto_model.py）
`model_path`	None	权重文件路径或模型名，如`yolo26n.pt`
`confidence_threshold`	0.3	置信度阈值，低于该值的预测被丢弃
`device`	None	推理设备，如`"cpu"`、`"cuda:0"`、`"mps"`
`config_path`	None	配置文件路径（MMDetection、Detectron2 等需要）
`category_mapping`	None	类别 ID 到名称的映射，如`{"0": "car"}`（键为字符串）
`category_remapping`	None	推理后按类别名重新映射类别 ID
`image_size`	None	覆盖模型输入分辨率
`mask_threshold`	0.5	掩码像素阈值（分割模型）
`load_at_init`	True	是否在初始化时立即加载权重

device="cpu"让示例在没有 GPU 的环境也能运行；如果有 NVIDIA GPU，改成"cuda:0"即可显著提速。

get_sliced_prediction：切片推理核心参数

get_sliced_prediction的完整签名与默认值定义在 sahi/predict.py，关键参数如下：

参数	默认值	含义
`image`	必填	图像路径、numpy 数组或 PIL Image
`detection_model`	必填	由`AutoDetectionModel.from_pretrained`构造的模型
`slice_height`/`slice_width`	None	每个切片的像素尺寸。若未提供且`auto_slice_resolution=True`，则根据图像分辨率与横竖方向自动计算（见 sahi/slicing.py 的分档逻辑：低/中/高/超高分辨率）
`overlap_height_ratio`/`overlap_width_ratio`	0.2	相邻切片的重叠比例，取值须小于 1.0。例如 512 的切片配 0.2 的重叠率意味着 102 像素的重叠带（见 sahi/slicing.py）
`perform_standard_pred`	True	是否在切片推理之外再对整图做一次标准预测，以提升大目标召回
`postprocess_type`	`"GREEDYNMM"`	合并策略：`GREEDYNMM`（默认，贪心合并取平均）、`NMM`、`NMS`（严格抑制）、`LSNMS`（位置敏感 NMS）
`postprocess_match_metric`	`"IOS"`	重叠度量：`IOS`（交与较小面积之比，合并更激进）或`IOU`（交并比，更保守）
`postprocess_match_threshold`	0.5	判定两个框为同一目标的匹配阈值，越低合并越多
`postprocess_class_agnostic`	False	True 时合并忽略类别 ID
`verbose`	1	0 不输出；1 打印切片数量；2 额外打印切片/推理/后处理耗时
`batch_size`	1	每批处理的切片数，增大可提升 GPU 利用率；Ultralytics 模型支持原生 GPU 批处理，其余框架回退为串行（见 sahi/predict.py）
`progress_bar`	False	是否显示 tqdm 进度条
`progress_callback`	None	每个切片处理完后回调`(current_slice, total_slices)`，便于接入自定义进度上报
`confidence_threshold`	None	仅本次调用生效的置信度阈值覆盖，调用结束后自动恢复模型原阈值（tests/test_predict.py 验证了即使推理抛异常阈值也会被恢复）

两个值得注意的自动行为（sahi/predict.py）：

当模型置信度阈值低于LOW_MODEL_CONFIDENCE（0.1）时，后处理会自动切换为NMS+IOU，避免低阈值下合并操作把边界框放大；可通过force_postprocess_type=True关闭该自动切换；
当检测模型是 Ultralytics 的 OBB（旋转框）输出时，后处理强制使用NMS。

3. 读取结果

get_sliced_prediction返回一个PredictionResult对象（定义于 sahi/prediction.py）。所有检测结果存放在result.object_prediction_list中，每一项是一个ObjectPrediction，包含category.name（类别名）、score.value（置信度）与bbox（边界框）：

for pred in result.object_prediction_list: print(pred.category.name, pred.score.value, pred.bbox.to_xyxy()) # 写入 demo_data/prediction_visual.png result.export_visuals(export_dir="demo_data/") # COCO 格式的字典，可直接保存为 JSON coco_predictions = result.to_coco_predictions(image_id=1)

各 API 的语义与实现位置：

pred.bbox.to_xyxy()：返回[x1, y1, x2, y2]形式的整图坐标框（实现在 sahi/annotation.py），另有to_xywh()可转换为[x, y, w, h]（sahi/annotation.py）。切片上的框在合并阶段已通过shift_amount平移到整图坐标，因此这里拿到的就是最终坐标。
pred.score.value：PredictionScore包装的置信度数值（sahi/prediction.py），支持与阈值直接比较。
result.export_visuals(export_dir=..., file_name=..., text_size=..., rect_th=..., hide_labels=..., hide_conf=...)：把预测框绘制到原图上，默认输出prediction_visual.png（sahi/prediction.py）。
result.to_coco_predictions(image_id=1)：导出包含image_id、bbox、score、category_id的 COCO 预测字典列表，可直接json.dump保存供 sahi coco evaluate 等工具评估。
同类导出还有to_coco_annotations()（不含 score）、to_fiftyone_detections()（FiftyOne 可视化）。

另外，PredictionResult.image_width/image_height记录原始图尺寸，durations_in_seconds记录切片、推理、后处理各阶段耗时，可用于性能剖析。

图像尺寸接近模型输入时：改用 get_prediction

如果图像尺寸已经接近模型输入尺寸，直接调用get_prediction完全跳过切片（实现在 sahi/predict.py）：

from sahi.predict import get_prediction result = get_prediction( "demo_data/small-vehicles1.jpeg", detection_model, )

get_prediction额外支持shift_amount、full_shape、exclude_classes_by_name/exclude_classes_by_id（按名称或 ID 排除类别）、confidence_threshold（单次覆盖）等参数，其中排除类别功能同样适用于切片推理。

4. 使用 CLI 执行同样的操作

SAHI 的 CLI 由 sahi/cli.py 中的fire.Fire应用暴露，sahi命令入口注册在 pyproject.toml（sahi = "sahi.cli:app"）。下面的命令与上面的 Python 示例等价，对demo_data/目录下的所有图像执行切片推理：

sahi predict --model_type ultralytics --model_path yolo26n.pt --source demo_data/ --slice_height 512 --slice_width 512

运行结束后，预测可视化写入runs/predict/exp目录（project默认runs/predict、name默认exp，重复运行会自动递增目录名，参见 sahi/utils/file.py 的increment_path与 sahi/predict.py）。

更多常用 CLI 参数（详见 docs/cli.md）：

推理模式：--no_sliced_prediction（仅整图标准推理）、--no_standard_prediction（仅切片推理）；默认两者都执行。
后处理：--postprocess_type GREEDYNMM|NMS、--postprocess_match_metric IOS|IOU、--postprocess_match_threshold 0.5、--postprocess_class_agnostic。
导出控制：--novisual（不导出可视化）、--visual_export_format JPG、--export_pickle、--export_crop（导出每个检测目标裁剪图）。
进度条：--progress_bar（CLI 不暴露progress_callback，该参数仅存在于 Python API）。
视频输入：--source video.mp4支持视频推理，配合--view_video实时预览与--frame_skip_interval跳帧加速。

配合 COCO 数据集导出评估结果

添加--dataset_json_path dataset.json后，predict会按 COCO 标注的顺序遍历--source目录下的图像，并把预测结果导出为 COCO 格式的result.json到运行目录runs/predict/exp/result.json（见 sahi/predict.py），同时还会在visuals_with_gt子目录中生成叠加了真实标注（绿色）与模型预测（红色）的对比可视化。得到result.json后即可继续使用 CLI 生态工具做闭环评估：

sahi coco evaluate --dataset_json_path dataset.json --result_json_path result.json sahi coco analyse --dataset_json_path dataset.json --result_json_path result.json --out_dir output/directory

coco evaluate计算 mAP/mAR 等 COCO 指标，coco analyse生成误差分析图；此外还有sahi coco slice（对 COCO 数据集切片并导出新的 COCO 标注）、sahi coco yolo（COCO 转 YOLO 格式用于训练）等实用命令（docs/cli.md）。

5. 底层原理：切片、推理、合并的源码级调用链

从源码可以看清get_sliced_prediction的完整工作流（sahi/predict.py）：

切片：调用slice_image（sahi/slicing.py）。它先把图像读成 numpy 数组，由get_slice_bboxes（sahi/slicing.py）按网格生成每个切片的[x_min, y_min, x_max, y_max]坐标，边界切片会被裁剪到图像范围内；每个切片记录其左上角starting_pixel，供后续坐标回移使用。重叠量按overlap_ratio × slice_size取整计算。
推理：切片按batch_size分组，调用detection_model.perform_batch_inference批量推理，再以shift_amount=batch_shifts、full_shape=[h, w]调用convert_original_predictions，把每个切片上的预测框平移回整图坐标（sahi/predict.py）。
合并：当启用perform_standard_pred且切片数大于 1 时，先对整图再做一次标准预测（sahi/predict.py），随后把所有预测统一交给所选后处理器（默认GreedyNMMPostprocess，postprocess_type映射表见 sahi/predict.py）合并重复框。若设置了merge_buffer_length，还会在切片推理过程中分批后处理，以降低内存占用。

在测试侧，tests/test_predict.py 用small-vehicles1.jpeg验证了切片推理输出的类别分布（应检测到car且没有person/truck误检）；tests/test_predict.py 则验证了batch_size=1与batch_size=4产生完全一致的预测结果，说明批处理不会改变检测质量，只影响吞吐。

下一步

切片推理工作原理：如何选择切片大小、重叠率和合并策略，以及何时不需要切片推理。
模型集成：HuggingFace、MMDetection、Detectron2、TorchVision、RT-DETR、RF-DETR 等各框架的接入示例与特有参数。
预测工具：批量推理、进度条、类别排除与可视化导出选项。
CLI 命令：所有命令与参数（含视频推理、COCO 评估、FiftyOne 可视化）。
交互式 Notebooks：可在 Colab 直接运行的示例。