SAHI 集成 YOLO-World:基于开放词汇检测的切片推理实战指南
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)
可以从中确认三个关键行为:
- 默认权重:当不传
model_path时,自动回退到yolov8s-worldv2.pt(YOLO-World v2 的 Small 版本),首次使用会由 Ultralytics 自动下载; - 设备迁移:加载后立即调用
model.to(self.device),device支持"cpu"、"cuda:0"、"mps"等取值; - 错误语义:任何加载失败都会被包装为
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)。
使用注意事项
- 文本提示是开放词汇检测的前提:SAHI 封装不会自动注入文本类别,请务必在推理前调用
detection_model.model.set_classes(...),否则模型可能无法按预期输出特定类别; - 置信度阈值:开放词汇检测的得分分布与闭集检测不同,官方集成示例采用
confidence_threshold=0.1的较低阈值,可结合验证集调参; - 版本依赖:
YOLOWorld类由ultralytics包提供,需要安装包含 YOLO-World 支持的 Ultralytics 版本;模型加载失败时抛出的TypeError会提示权重路径无效; - 权重自动下载:首次使用
yolov8s-worldv2.pt等内置模型名时,Ultralytics 会联网下载权重,离线环境请预先准备好本地.pt文件。
延伸阅读
- 模型集成总览(含 YOLO-World 官方示例代码):docs/guides/models.md
- YOLO-World 封装源码:sahi/models/yolo-world.py
- 父类 Ultralytics 封装源码(批推理、预测转换):sahi/models/ultralytics.py
- 模型自动加载注册表:sahi/auto_model.py
- 切片推理原理与参数:docs/guides/sliced-inference.md
- 预测与导出工具:docs/predict.md
- CLI 使用说明:docs/cli.md