SAHI 集成 YOLO-World:零样本开放词汇检测的切片推理实战指南

原创2026-10-12 11:02:031,820 阅读
文章标签:人工智能计算机视觉深度学习图像处理

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 后端。整个调用链可以概括为:

  1. AutoDetectionModel.from_pretrained(model_type="yolo-world", ...) 依据 sahi/auto_model.py 中的 MODEL_TYPE_TO_MODEL_CLASS_NAME 映射,实例化 YOLOWORLDDetectionModel;
  2. YOLOWorldDetectionModel.load_model() 内部调用 ultralytics.YOLOWorld 完成权重加载;
  3. 之后即可直接调用 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)

关键点有三:

  1. 延迟导入:ultralytics.YOLOWorld 在 load_model 内才被导入,避免未安装 ultralytics 时影响 SAHI 其他模块的导入;
  2. 默认权重:model_path 为空时自动使用 "yolov8s-worldv2.pt";
  3. 异常包装:加载失败统一抛出 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):

  1. 用 sahi/slicing.py 的 slice_image 将原图切成带重叠的切片;
  2. 对每个切片调用模型的 perform_inference / perform_batch_inference 推理;
  3. 将切片上的预测框按 shift_amount(切片相对原图的偏移量)映射回整图坐标(实现于 sahi/models/ultralytics.py 的 _create_object_prediction_list_from_original_predictions,其中会对坐标做 max(0, coord) 截断与整图边界钳制,并丢弃无效框);
  4. 通过后处理合并跨切片的重复检测,默认使用 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。

登录后查看全文
sahi