SAHI 集成 YOLO-World:零样本开放词汇检测的切片推理实战指南
SAHI 集成 YOLO-World:零样本开放词汇检测的切片推理实战指南
YOLO-World 是 Ultralytics 推出的开放词汇(open-vocabulary)目标检测模型,能够在推理阶段直接通过文本描述检测任意类别,而无需针对新类别重新训练。SAHI(Slicing Aided Hyper Inference)为这类模型提供了完整的 YOLOWorldDetectionModel 封装(sahi/models/yolo-world.py),让 YOLO-World 可以无缝接入切片推理、批量推理、CLI 命令行和结果可视化导出流程。读完本文,你将掌握如何在 SAHI 中加载 YOLO-World 权重、通过 AutoDetectionModel.from_pretrained() 一行初始化模型、对超大图像执行切片预测,并通过文本提示自定义检测类别。
YOLO-World 与 SAHI 集成概览
YOLO-World 的核心能力在于"以文本为提示"的零样本检测:模型在训练阶段学习文本与视觉特征的对齐关系,因此部署时只要给出类别描述(例如 "person"、"car"、"traffic light"),模型就能直接输出对应目标的边界框,无需微调。Ultralytics 官方提供 yolov8s-worldv2.pt、yolov8m-worldv2.pt、yolov8l-worldv2.pt 等 World v2 系列权重。
SAHI 将 YOLO-World 归入模型集成体系中的 "YOLO-World (Zero-Shot)" 一类(见 docs/guides/models.md 中 ## YOLO-World (Zero-Shot) 小节),其集成方式继承自 Ultralytics 后端。整个调用链可以概括为:
AutoDetectionModel.from_pretrained(model_type="yolo-world", ...)依据 sahi/auto_model.py 中的MODEL_TYPE_TO_MODEL_CLASS_NAME映射,实例化YOLOWORLDDetectionModel;YOLOWorldDetectionModel.load_model()内部调用ultralytics.YOLOWorld完成权重加载;- 之后即可直接调用 SAHI 的
get_prediction/get_sliced_prediction/predict等高层 API,或通过 CLI 的sahi predict命令执行推理。
从源码结构看,sahi/models/yolo-world.py 中的 YOLOWorldDetectionModel 直接继承 UltralyticsDetectionModel(sahi/models/ultralytics.py),因此它天然获得 YOLO 家族统一的推理、批量推理、预测结果转换等全部能力,仅覆写了 load_model 用于初始化 YOLOWorld 实例。
环境准备与依赖安装
YOLO-World 的 SAHI 集成依赖 ultralytics 包,加载模型时 sahi/models/ultralytics.py 会向 required_packages 追加 "ultralytics",并在 DetectionModel.__init__ 中自动检查依赖(见 sahi/models/base.py 的 check_dependencies 调用)。安装命令:
pip install sahi ultralytics
此外,SAHI 的切片与可视化流程依赖 opencv-python、Pillow、numpy 等基础库,建议一并安装:
pip install opencv-python pillow numpy
加载 YOLO-World 模型:核心参数详解
SAHI 推荐通过 AutoDetectionModel.from_pretrained() 加载模型,它会根据 model_type 自动选择对应的模型封装类。针对 YOLO-World,model_type 固定为 "yolo-world"(映射关系见 sahi/auto_model.py 中的 MODEL_TYPE_TO_MODEL_CLASS_NAME 字典)。
最简用法如下(取自 docs/guides/models.md 的 YOLO-World 示例):
from sahi import AutoDetectionModel
detection_model = AutoDetectionModel.from_pretrained(
model_type="yolo-world",
model_path="yolov8s-worldv2.pt",
confidence_threshold=0.1,
device="cuda:0", # 或 "cpu"
)
这段代码等价于直接实例化封装类。若走底层 API,也可以显式使用:
from sahi.models.yolo_world import YOLOWorldDetectionModel
detection_model = YOLOWorldDetectionModel(
model_path="yolov8s-worldv2.pt",
confidence_threshold=0.1,
device="cuda:0",
)
参数说明
AutoDetectionModel.from_pretrained() 与 DetectionModel 构造函数共享一套参数(完整定义见 sahi/models/base.py 与 sahi/auto_model.py):
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
model_type |
str | — | 框架名,YOLO-World 传 "yolo-world" |
model_path |
str | "yolov8s-worldv2.pt" |
权重文件路径或模型名;不传时 sahi/models/yolo-world.py 会自动回退到默认的 yolov8s-worldv2.pt |
config_path |
str | None | 配置文件路径(YOLO-World 一般不需要) |
confidence_threshold |
float | 0.3 | 置信度阈值,低于该分数的预测会被丢弃 |
device |
str | None | "cpu"、"cuda:0"、"mps" 等 Torch 设备;通过 sahi/utils/torch_utils.py 的 select_device 解析 |
category_mapping |
dict | None | 类别 ID(字符串键)到类别名的映射,如 {"0": "car"} |
category_remapping |
dict | None | 推理后按类别名重映射类别 ID |
load_at_init |
bool | True | 初始化时立即加载权重 |
image_size |
int | None | 覆盖模型输入分辨率 |
mask_threshold |
float | 0.5 | 分割掩码像素阈值(YOLO-World 检测任务通常不涉及) |
针对零样本场景,官方示例将 confidence_threshold 设为 0.1,这是因为开放词汇检测的文本-视觉匹配分数通常偏低,使用更低的阈值可以避免漏检,再配合 SAHI 的后处理完成跨切片合并。
底层加载逻辑
YOLOWorldDetectionModel.load_model() 的实现非常精简(sahi/models/yolo-world.py):
def load_model(self) -> None:
"""Detection model is initialized and set to self.model."""
from ultralytics import YOLOWorld
try:
model_source = self.model_path or "yolov8s-worldv2.pt"
model = YOLOWorld(model_source)
model.to(self.device)
self.set_model(model)
except Exception as e:
raise TypeError("model_path is not a valid yolo world model path: ", e)
关键点有三:
- 延迟导入:
ultralytics.YOLOWorld在load_model内才被导入,避免未安装 ultralytics 时影响 SAHI 其他模块的导入; - 默认权重:
model_path为空时自动使用"yolov8s-worldv2.pt"; - 异常包装:加载失败统一抛出
TypeError,提示路径不是合法的 YOLO-World 模型路径。
set_model 由父类 UltralyticsDetectionModel 实现(sahi/models/ultralytics.py),会在未提供 category_mapping 时根据模型的 names 元数据自动生成 {类别ID: 类别名} 映射,供后续预测结果转换使用。
零样本提示:自定义检测类别
YOLO-World 是开放词汇模型,权重自带的类别往往只是训练时的基础类别。要在推理时检测自定义类别,需要使用 Ultralytics 的 set_classes() API 指定文本提示:
# 加载模型
detection_model = AutoDetectionModel.from_pretrained(
model_type="yolo-world",
model_path="yolov8s-worldv2.pt",
confidence_threshold=0.1,
device="cuda:0",
)
# 通过文本提示设置自定义类别
detection_model.model.set_classes(
["person", "car", "traffic light"],
detection_model.model.get_text_pe(["person", "car", "traffic light"]),
)
set_classes 会修改模型内部可检测的类别列表;get_text_pe 负责将类别文本编码为文本提示嵌入(text prompt embeddings)。设置后模型只对这三类目标输出检测框,预测结果的 category_id 也按照该列表顺序编号,SAHI 会依据 sahi/models/ultralytics.py 中的 category_names 属性自动同步类别名称,保证可视化与导出的标签正确。
切片推理实战:对小目标与大图的增强检测
SAHI 的核心价值在于切片辅助推理(sliced inference):把大图切成多个带重叠的切片分别推理,再合并去重,从而显著提升小目标检测精度。YOLO-World 与切片推理配合的完整用法:
from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction
detection_model = AutoDetectionModel.from_pretrained(
model_type="yolo-world",
model_path="yolov8s-worldv2.pt",
confidence_threshold=0.1,
device="cuda:0",
)
result = get_sliced_prediction(
"image.jpg", # 图像路径或 numpy 数组
detection_model,
slice_height=512, # 切片高度
slice_width=512, # 切片宽度
overlap_height_ratio=0.2, # 高度方向重叠比例
overlap_width_ratio=0.2, # 宽度方向重叠比例
)
get_sliced_prediction 的执行流程(对应 sahi/predict.py):
- 用 sahi/slicing.py 的
slice_image将原图切成带重叠的切片; - 对每个切片调用模型的
perform_inference/perform_batch_inference推理; - 将切片上的预测框按
shift_amount(切片相对原图的偏移量)映射回整图坐标(实现于 sahi/models/ultralytics.py 的_create_object_prediction_list_from_original_predictions,其中会对坐标做max(0, coord)截断与整图边界钳制,并丢弃无效框); - 通过后处理合并跨切片的重复检测,默认使用
GREEDYNMM(贪心非极大值合并)。
关键切片参数:
| 参数 | 默认值 | 说明 |
|---|---|---|
slice_height / slice_width |
512 / 512 | 切片尺寸,越小对小目标越友好,但切片数量增多 |
overlap_height_ratio / overlap_width_ratio |
0.2 / 0.2 | 重叠比例,避免目标恰好被切片边界切开导致漏检 |
postprocess_type |
"GREEDYNMM" |
合并策略,可选 NMM、GREEDYNMM、NMS、LSNMS |
postprocess_match_metric |
"IOS" |
匹配度量,IOU 或 IOS(交小面积比) |
postprocess_match_threshold |
0.5 | 超过该 IoU/IOS 的跨切片预测将被合并 |
batch_size |
1 | 切片批量推理的批大小 |
progress_bar |
False | 是否显示 tqdm 进度条 |
exclude_classes_by_name / exclude_classes_by_id |
None | 推理时排除指定类别 |
若图像尺寸不大、无需切片,可以直接使用标准推理:
from sahi.predict import get_prediction
result = get_prediction("image.jpg", detection_model)
批量推理与低层 API
SAHI 高层 predict 函数支持对整个文件夹或视频做批量切片推理,并自动导出结果(函数签名见 sahi/predict.py):
from sahi.predict import predict
predict(
model_type="yolo-world",
model_path="yolov8s-worldv2.pt",
model_confidence_threshold=0.1,
model_device="cuda:0", # 或 "cpu"
source="path/to/images/", # 图像文件夹、单张图像或视频
no_standard_prediction=True, # 只做切片推理
no_sliced_prediction=False,
slice_height=512,
slice_width=512,
overlap_height_ratio=0.2,
overlap_width_ratio=0.2,
export_pickle=False, # 导出 pickle 预测结果
export_crop=False, # 导出裁剪的目标图像
progress_bar=False,
)
由于 YOLOWorldDetectionModel 继承自 UltralyticsDetectionModel,它还具备原生 GPU 批量推理能力:perform_batch_inference 会把整批图像统一转换为 BGR 后一次性交给 YOLO 推理(sahi/models/ultralytics.py),比逐图推理更快。底层用法:
import cv2
from sahi import AutoDetectionModel
detection_model = AutoDetectionModel.from_pretrained(
model_type="yolo-world",
model_path="yolov8s-worldv2.pt",
confidence_threshold=0.1,
device="cuda:0",
)
# 读取一批图像(RGB 顺序)
images = [cv2.cvtColor(cv2.imread(p), cv2.COLOR_BGR2RGB) for p in image_paths]
# 原生批量推理
detection_model.perform_batch_inference(images)
# 非切片场景偏移为 0,full_shape 为各图原始尺寸
detection_model.convert_original_predictions(
shift_amount=[[0, 0]] * len(images),
full_shape=[[img.shape[0], img.shape[1]] for img in images],
)
# 逐图访问预测
for i, preds in enumerate(detection_model.object_prediction_list_per_image):
print(f"Image {i}: {len(preds)} detections")
for pred in preds:
print(pred.category.name, pred.score.value, pred.bbox.to_xyxy())
CLI 命令行使用
SAHI 提供 sahi predict 命令行入口(见 docs/cli.md 与 sahi/scripts/predict.py,基于 fire 实现)。YOLO-World 的 CLI 调用方式:
sahi predict \
--model_type yolo-world \
--model_path yolov8s-worldv2.pt \
--model_confidence_threshold 0.1 \
--model_device cuda:0 \
--source path/to/images/ \
--slice_width 512 --slice_height 512 \
--overlap_width_ratio 0.2 --overlap_height_ratio 0.2 \
--project runs/predict --name yolo_world_exp
常用 CLI 参数与 Python API 一一对应:--model_type、--model_path、--model_config_path、--model_confidence_threshold、--model_device、--source、--slice_height、--slice_width、--overlap_height_ratio、--overlap_width_ratio、--postprocess_type、--export_pickle、--export_crop、--novisual 等。运行结果默认保存在 project/name/ 目录下,其中 visuals/ 存放可视化图片。
预测结果可视化与导出
get_prediction / get_sliced_prediction 返回的 PredictionResult 支持多种导出格式(用法详见 docs/predict.md 的"Visualization parameters and export formats"小节):
# 自定义可视化导出
result.export_visuals(
export_dir="outputs/",
text_size=1.0, # 标签文字大小
rect_th=2, # 边界框线宽
hide_labels=False, # 是否隐藏类别标签
hide_conf=False, # 是否隐藏置信度
file_name="yolo_world_result",
)
# 导出 COCO 格式标注(无置信度)
coco_annotations = result.to_coco_annotations()
# 导出 COCO 格式预测(含置信度)
coco_predictions = result.to_coco_predictions(image_id=1)
# 导出 FiftyOne 检测结果
fiftyone_detections = result.to_fiftyone_detections()
这些导出函数位于 sahi/prediction.py 的 PredictionResult 中,可无缝对接 COCO 评估、FiftyOne 可视化等下游工具。
与其他开放词汇模型的关系
在 SAHI 的模型生态中,YOLO-World 与 YOLOE(sahi/models/yoloe.py)都属于开放词汇检测方案,二者加载方式高度相似:YOLOEDetectionModel 同样继承 UltralyticsDetectionModel,通过 model.set_classes(["person", "car"], model.get_text_pe(...)) 设置提示词。区别在于:
- YOLO-World 需要显式文本提示才能检测指定类别;
- YOLOE 额外支持视觉提示(参考图 one-shot)与免提示模式(内置 1200+ 类别内部词表)。
选用哪种取决于任务:类别稳定、追求轻量时选 YOLO-World v2 系列(如 yolov8s-worldv2.pt);需要更强开放集能力或内置分割时选 YOLOE。两者都可以无缝套用本文的切片推理与批量推理流程。
小结
通过 SAHI 的 yolo-world 集成(核心实现位于 sahi/models/yolo-world.py,继承自 sahi/models/ultralytics.py),YOLO-World 的零样本检测能力与切片推理、批量推理、CLI 与多格式导出被统一到一套标准 API 中。只需三步即可投入实战:pip install sahi ultralytics 安装依赖 → AutoDetectionModel.from_pretrained(model_type="yolo-world", ...) 加载权重 → get_sliced_prediction() 或 sahi predict 执行推理;再用 model.set_classes(...) 定制检测类别,即完成一个可处理任意大图、任意文本类别的开放词汇检测方案。更多模型集成示例与 Notebook 参考 docs/guides/models.md 与 docs/notebooks.md,切片算法细节可进一步阅读 docs/slicing.md。