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

原创2026-10-11 23:26:261,986 阅读
文章标签:人工智能计算机视觉深度学习图像处理

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

YOLO-World 是 Ultralytics 推出的开放词汇(open-vocabulary)目标检测模型,能够在推理阶段仅凭文本描述检测未见过的类别,无需重新训练。本文围绕 SAHI 提供的 YOLOWorldDetectionModel 封装(对应文档 docs/models/yolo-world.md),讲解如何通过 AutoDetectionModel 统一加载 YOLO-World 权重、配置推理参数,并借助 SAHI 的切片推理(sliced inference)流程检测大图中的小目标。读完本文,你将掌握在 SAHI 中完整使用 YOLO-World 的配置方法、底层加载与预测转换原理,以及文本提示(text prompt)的设置方式。

YOLO-World 在 SAHI 中的定位

SAHI(Slicing Aided Hyper Inference)是一个框架无关的目标检测推理工具库,通过统一的 DetectionModel 接口把 Detectron2、MMDetection、HuggingFace、Ultralytics YOLO 等不同框架的模型"包装"成同一种调用方式。YOLO-World 正是这类集成中的一员:

  • 从源码结构看,SAHI 为其单独提供了封装文件 sahi/models/yolo-world.py,并在 sahi/auto_model.py 的 MODEL_TYPE_TO_MODEL_CLASS_NAME 注册表中注册了 "yolo-world": "YOLOWORLDDetectionModel";
  • 该封装类 YOLOWorldDetectionModel 直接继承自 sahi/models/ultralytics.py 中的 UltralyticsDetectionModel,因此天然复用 Ultralytics 模型的批推理、类别映射、OBB/分割预测转换等全部能力;
  • 在官方模型集成指南 docs/guides/models.md 中,YOLO-World 与 YOLOE 并列归入"零样本 / 开放词汇检测"章节,作为 SAHI 支持开放词汇检测的两条路径之一。

环境准备

使用 YOLO-World 需要安装 Ultralytics 框架,SAHI 会在初始化模型时通过依赖检查(check_dependencies)自动确认 ultralytics 包是否存在,相关逻辑见 sahi/models/ultralytics.py 与 sahi/models/base.py。

pip install ultralytics

若尚未安装 SAHI 本体,还需先安装本仓库:

pip install sahi

快速开始:加载 YOLO-World 模型

与加载其他框架模型一样,使用 AutoDetectionModel.from_pretrained() 统一入口,只需把 model_type 指定为 "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",                    # 或 "cpu"
)

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)

AutoDetectionModel 会根据 model_type 从注册表查找类名,再通过 sahi/utils/file.py 的 import_model_class 动态导入 sahi.models.yolo-world.YOLOWorldDetectionModel 并实例化,传入 model_path、confidence_threshold、device 等公共参数(注册表见 sahi/auto_model.py)。

底层加载过程

YOLOWorldDetectionModel.load_model() 的实现非常简洁,完整逻辑见 sahi/models/yolo-world.py:

def load_model(self) -> None:
    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. 默认权重:当不传 model_path 时,自动回退到 yolov8s-worldv2.pt(YOLO-World v2 的 Small 版本),首次使用会由 Ultralytics 自动下载;
  2. 设备迁移:加载后立即调用 model.to(self.device),device 支持 "cpu"、"cuda:0"、"mps" 等取值;
  3. 错误语义:任何加载失败都会被包装为 TypeError("model_path is not a valid yolo world model path: ..."),便于用户排查权重路径问题。

加载成功后,set_model() 还会把类别映射写入 category_mapping(当未显式提供时,以 {索引: 类别名} 的形式生成),该逻辑来自父类 sahi/models/ultralytics.py。

设置文本提示:开放词汇检测的关键一步

YOLO-World 的核心能力是"文本提示检测":在推理时通过 set_classes() 指定要检测的类别文本,模型即可输出这些类别的检测框。SAHI 的封装只负责加载与推理,不会替你设定类别,因此加载模型后需要主动调用 Ultralytics 原生的 set_classes() 接口:

# 在 SAHI 中获取底层 YOLOWorld 模型实例
detection_model = AutoDetectionModel.from_pretrained(
    model_type="yolo-world",
    model_path="yolov8s-worldv2.pt",
    confidence_threshold=0.1,
    device="cuda:0",
)

# 调用 Ultralytics YOLO-World 原生 API 设置要检测的文本类别
detection_model.model.set_classes(
    ["person", "car", "traffic light", "bicycle"],
    detection_model.model.get_text_pe(["person", "car", "traffic light", "bicycle"]),
)

# 之后即可进行切片推理
from sahi.predict import get_sliced_prediction
result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=512,
    slice_width=512,
)

其中 get_text_pe() 用于把类别文本转换为模型可用的文本提示嵌入(text prompt embeddings),set_classes() 会把类别名称写入模型,SAHI 在结果转换阶段会依据该名称生成 ObjectPrediction 的 category_name(见 sahi/models/ultralytics.py 的类别解析逻辑)。

说明:如果你加载的是已经设定好类别的自定义 YOLO-World 权重(fine-tuned 模型),则无需再次调用 set_classes(),模型自带类别名会直接生效。同类开放词汇模型 YOLOE 也采用相同的 set_classes() 模式,示例可参考 sahi/models/yoloe.py。

公共参数详解

AutoDetectionModel.from_pretrained() 对 "yolo-world" 与对所有模型一样接受以下公共参数(与 docs/guides/models.md 中的 Common Parameters 表格一致,参数解析入口见 sahi/auto_model.py):

参数 类型 说明
model_type str 框架名,此处固定为 "yolo-world"
model_path str 权重文件路径或模型名,缺省时使用 yolov8s-worldv2.pt
config_path str 配置文件路径(Ultralytics 系可选)
confidence_threshold float 分数低于该值的检测结果被丢弃(默认 0.3;开放词汇场景官方示例常用 0.1)
device str "cpu"、"cuda:0"、"mps" 等设备标识
category_mapping dict 类别 ID 到名称的映射,键为字符串,如 {"0": "car", "1": "person"}
category_remapping dict 推理后按类别名重映射类别 ID
image_size int 覆盖模型输入分辨率
load_at_init bool 是否在初始化时立即加载权重(默认 True)

其中 image_size 会被传入底层 perform_batch_inference(),以 imgsz 的形式覆盖 YOLO 的输入尺寸(见 sahi/models/ultralytics.py)。confidence_threshold 同理作为 conf 传入模型调用(同文件第 L142 行)。

切片推理与批推理

YOLO-World 通过 SAHI 的切片推理可有效检测大尺寸图片中的小目标。切片推理的核心参数(slice_height、slice_width、overlap_height_ratio、overlap_width_ratio 等)及其背后的"切块—检测—合并"流程,可参阅 docs/guides/sliced-inference.md。

result = get_sliced_prediction(
    "image.jpg",
    detection_model,
    slice_height=640,
    slice_width=640,
    overlap_height_ratio=0.2,
    overlap_width_ratio=0.2,
    batch_size=8,          # 每批处理 8 个切片,利用 GPU 原生批推理加速
)

由于 YOLOWorldDetectionModel 继承自 UltralyticsDetectionModel,它自动获得了原生 GPU 批推理能力:perform_batch_inference() 会把图片列表整体传给 Ultralytics 模型(内部先把 RGB 转为 BGR,因为 YOLO 系列期望 BGR 输入),并从 Result 对象中提取 boxes.data 作为原始预测,见 sahi/models/ultralytics.py。这使得切片推理可按 batch_size 批量喂入模型,显著提升吞吐。

对于非切片场景,get_prediction() 同样可用;完整的低层批推理 API 与 convert_original_predictions() 用法参见 docs/predict.md。

通过命令行使用

SAHI 的 CLI 命令 sahi predict 同样支持 YOLO-World(model_type 传 yolo-world),语法与其他模型一致:

sahi predict \
  --model_type yolo-world \
  --model_path yolov8s-worldv2.pt \
  --source image/file/or/folder \
  --model_confidence_threshold 0.1 \
  --slice_width 512 \
  --slice_height 512 \
  --overlap_height_ratio 0.2 \
  --overlap_width_ratio 0.2

CLI 参数说明与 sahi predict-fiftyone 等其他子命令可参考 docs/cli.md。

预测结果转换与后处理

推理完成后,SAHI 会把 YOLO 原生输出转换为统一的 ObjectPrediction 列表,此过程在 _create_object_prediction_list_from_original_predictions() 中完成(sahi/models/ultralytics.py),要点包括:

  • 从每个检测行提取 bbox(前 4 个值)、score(第 5 个值)与 category_id(第 6 个值),并依据 category_mapping 解析类别名;
  • 对切片推理场景,根据 shift_amount 与 full_shape 把切片坐标平移回原图、并裁剪到图片边界内;
  • 过滤掉 x1 >= x2 或 y1 >= y2 的非法框(日志会输出 ignoring invalid prediction with bbox 警告);
  • 若模型输出分割掩码或 OBB 点,也会一并转换为 COCO 格式分割或多边形点序列。

之后可对合并结果使用 GreedyNMM、NMS、LSNMS 等后处理策略去重(合并机制详见 docs/guides/sliced-inference.md),并导出可视化图片、COCO 标注或 FiftyOne 检测结果(导出 API 见 docs/predict.md)。

使用注意事项

  1. 文本提示是开放词汇检测的前提:SAHI 封装不会自动注入文本类别,请务必在推理前调用 detection_model.model.set_classes(...),否则模型可能无法按预期输出特定类别;
  2. 置信度阈值:开放词汇检测的得分分布与闭集检测不同,官方集成示例采用 confidence_threshold=0.1 的较低阈值,可结合验证集调参;
  3. 版本依赖:YOLOWorld 类由 ultralytics 包提供,需要安装包含 YOLO-World 支持的 Ultralytics 版本;模型加载失败时抛出的 TypeError 会提示权重路径无效;
  4. 权重自动下载:首次使用 yolov8s-worldv2.pt 等内置模型名时,Ultralytics 会联网下载权重,离线环境请预先准备好本地 .pt 文件。

延伸阅读

登录后查看全文
sahi