简介：面向计算机视觉开发者与目标检测研究者的YOLO-World学习资料包，聚焦开放词汇检测与视觉定位任务，提供PyTorch实现、预训练权重以及预训练/微调代码，便于复现“先提示后检测”的推理范式，并理解大规模检测、定位与图文数据上的训练流程。压缩包共161个文件，约2.35MB，以110个Python源码和20个Markdown文档为主，辅以少量txt、json配置与png/jpg示例图，另含Dockerfile、Shell脚本和Notebook，兼顾代码阅读、环境搭建与快速试跑。已有883人学习下载，适合需要从源码层面掌握YOLO-World结构、开放词表推理和微调方法的中高级读者，也可作为课程项目或算法原型的参考底稿。
1. 换个品类就要重训一轮？这份资料省下的是「改词表」的时间
上周一个做仓储视觉的朋友接了个临时活，客户在验收前一天要求加两类目标：「破损纸箱」和「缠绕膜」。原来的模型是标准闭集检测器，类别写死在分类头里，加类等于重标数据、重训、重调阈值，两天工期直接崩。换成 YOLO-World 这条路子，改的是推理时的一份词表，不是网络权重，十几分钟就能出结果。这份资料给的是源码加文档，覆盖模型结构、开放词表设置、自定义词表落盘、重参数化导出到 ONNX 这一整条链路，不是一份只会跑 demo 的脚本。它适合两类人：手上已经有 YOLO 系检测流水线、需要一个「临时加类不掉链子」的方案；以及想搞清楚开放词表检测内部到底在算什么、为什么能零样本出框的人。下面是拆解顺序：结构、跑通、速度、排坑、验证。
2. 开放词表是怎么跑通的：文本嵌入、RepVL-PAN 与两条推理路径
2.1 从闭集分类头到文本-视觉对齐：被替换的是哪一层
先看 YOLOv8 的检测头。解耦头里分类分支最后一层是 1×1 卷积，权重形状(num_classes, C, 1, 1)，num_classes在训练时就被烧死了，推理阶段改不了。YOLO-World 做的事很直接：把这个 1×1 卷积的权重矩阵，替换成文本编码器输出的类别嵌入矩阵W ∈ R^(N×D)，N是当前词表里的类别数，D是嵌入维度（ViT-B/32 量级是 512）。前向传播时，特征图上每个位置的特征向量和W做点积，得到的就是「这块区域像不像这个词」的相似度分数。
这样一换，类别就不再是网络的固有属性，而是一个运行时输入。你给["person", "forklift"]，它输出两个通道；给["crack", "stain", "dent", "oil leak"]，它输出四个通道。分类头的结构没变，只是权重来源变了。资料里的源码在这一点上写得很清楚，txt_feats这个张量是贯穿整个前向过程的核心，模型对象上挂着它，改词表就是改它。
理解这一层很关键，因为后面所有坑都从这里派生。词表存在模型对象上、不在权重文件里的说法不准确——它会跟着save()一起落盘，但你如果只做了set_classes()没保存，进程一退就没了。另一个派生问题是：文本嵌入的质量直接决定分类质量，所以用什么 prompt 模板、用中文还是英文，都会实打实影响 mAP，这不是玄学。
2.2 RepVL-PAN 与 T-CSPLayer：文本信息怎么注入多尺度特征
光换最后一层卷积，效果是不够的。纯点积意味着文本只在最末端参与，浅层特征完全靠视觉先验，遇到训练集里没有的类别，特征响应很弱。YOLO-World 在 neck 上做了文章，就是名字里的 RepVL-PAN（可重参数化的视觉-语言路径聚合网络）。它做了两件事。
第一件是 T-CSPLayer。在 PAN 的每个融合阶段（对应 P3、P4、P5 三个尺度），原本的 CSP 层被改造：文本嵌入先沿空间维度广播，和图像特征在通道维拼接，再走卷积融合。用代码的眼光看就是：
# 概念示意，非官方源码，帮助理解 T-CSPLayer 的张量流向 # x: (B, C, H, W) 图像特征 # txt: (B, N, D) 文本嵌入 # 广播后: (B, D, H, W) -> 与 x 在通道维 cat # 融合后: (B, C, H, W) 回到原通道数，继续往下走拼接带来的代价是通道数临时翻倍，所以后面的卷积要把它压回去。这个设计让文本信号在多个尺度上都参与，浅层的小目标也能被词表激活。文档里对这段结构的描述比较简略，实际读源码时重点盯住txt_feats在哪些层被repeat或expand、拼接位置在残差之前还是之后，这两点搞明白了，改结构才有下手的地方。
第二件是 I-Pooling Attention，图像感知的文本嵌入。它拿图像特征做多尺度池化，得到一组视觉 token，反过来去更新文本嵌入。效果是同一个词在不同场景下的嵌入会微调，比如「box」在堆叠场景和散放场景下语义侧重不同。这一路是可选的增强项，推理时如果追求极致速度可以关掉，但精度会掉一些，具体掉多少取决于词表的抽象程度。
2.3 离线词表与在线词表：两条路径的取舍
这是决定工程方案的分水岭，很多人在这一步选错，然后抱怨「速度慢得没法用」。
| 对比项 | 离线词表（offline vocabulary） | 在线词表（online vocabulary） |
|---|---|---|
| 文本编码次数 | 每个词表只编一次 | 每帧图像都编一次 |
| 能否重参数化 | 能，融成普通 1×1 卷积 | 不能 |
| 单帧延迟 | 与同规模 YOLOv8 基本持平 | 额外增加文本编码开销 |
| 运行中换词 | 需要重新 set_classes + 重新导出 | 可以逐帧换 prompt |
| 导出 ONNX / TensorRT | 支持 | 基本不支持 |
| 典型场景 | 产线固定几类、边缘设备部署 | 交互式检索、词表随用户输入变 |
离线模式的做法是：先set_classes，文本嵌入算出来之后，把分类头的点积操作「折叠」成普通的卷积权重，之后模型就退化成一个标准的、类别数为 N 的 YOLOv8。这也是「重参数化」三个字在项目名之外的第二层含义。在线模式则保留文本编码器，每帧都跑一遍 CLIP 文本分支。
我的建议很明确：只要类别集合在部署期内是确定的，一律走离线 + 重参数化。在线模式看着灵活，但文本编码器跑一次就是几十毫秒级别，视频流场景下完全吃不消。只有在做「用户输入一句话、立刻出框」这种交互式 demo 时，在线模式才有存在价值。
3. 把源码跑起来：从权重加载到自定义词表的完整链路
3.1 环境和依赖：pytorch 与 ultralytics 的版本约束
这套东西依赖链很短，但版本对不上会以很隐蔽的方式报错。核心就两个包：torch和ultralytics。YOLO-World 的权重是.pt格式，加载走的是 ultralytics 的YOLOWorld类，不是YOLO类，别混着用。
# 建议单独建环境，版本以资料文档里给出的为准 python -m venv yworld && source yworld/bin/activate # torch 按你的 CUDA 版本装，CPU 版也能跑，只是慢 pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121 # ultralytics 版本要支持 YOLOWorld，太老的版本没有这个类 pip install ultralytics装完之后先验证一下类能不能导入：
python -c "from ultralytics import YOLOWorld; print('ok')"报ImportError就说明版本太低，升级ultralytics即可。第二个要注意的是torch和torchvision版本必须配套，单独升一个会出现operator torchvision::nms does not exist这种看着像模型问题的报错，实际是依赖问题。资料里如果给了 requirements 文件，直接照装，别自己配。
提示：CPU 上跑开放词表模型可以出结果，但 640 输入下单帧几百毫秒到一秒，做功能验证没问题，做视频流验证会很痛苦。有条件先用一块入门级显卡把链路跑通。
3.2 加载权重与设置自定义词表
下面这段是整份资料里最核心的一段代码，涵盖加载、设词、推理、结果解析。
from ultralytics import YOLOWorld # 1) 加载开放词表权重，s 是速度优先，m/l/x 精度递增、速度递减 model = YOLOWorld("yolov8s-worldv2.pt") # 2) 设置本次任务的词表，必须是英文短语，用逗号拆开的自然语言描述也可以 classes = [ "person", "cardboard box", "damaged cardboard box", "pallet", "forklift", ] model.set_classes(classes) # 3) 推理：imgsz 取 32 的整数倍，conf 对开放词表要比闭集模型抬一点 results = model.predict( source="demo.jpg", imgsz=640, conf=0.30, iou=0.50, device=0, verbose=False, ) # 4) 解析结果：boxes.cls 是词表下标，要映射回 classes 里的字符串 r = results[0] for xyxy, cid, score in zip( r.boxes.xyxy.tolist(), r.boxes.cls.tolist(), r.boxes.conf.tolist(), ): label = classes[int(cid)] x1, y1, x2, y2 = [round(v, 1) for v in xyxy] print(f"{label:>24s} {score:.3f} ({x1},{y1})-({x2},{y2})")逐段说清楚逻辑。第一步的权重选择上，s和m是最常用的两个档位，s在 640 输入、单卡上能跑到实时，m精度明显好一截但速度掉一半左右。别一上来就用x，除非你的场景对精度极其敏感且不计成本。
第二步set_classes是改词表的唯一入口。这里的classes是有序的，因为后面boxes.cls出来的就是下标，顺序错了标签就全错。实测下来，词表里写具体短语比写抽象名词效果好，「damaged cardboard box」比「damage」检出率高不少，因为 CLIP 文本编码器对完整名词短语的语义更稳。中文词条能跑通，但精度下降明显，这是文本编码器训练语料的问题，不是代码 bug。
第三步的conf是个需要反复调的量。闭集模型上 0.25 往往合适，开放词表因为相似度分布更平，阈值给低了会冒出大量「像但不对」的框，给到 0.30 到 0.35 起步更稳。iou保持 0.5 一般够用，密集小目标可以压到 0.45。
第四步的解析逻辑容易被忽略。r.boxes.cls返回的是浮点数张量，直接拿去索引classes会报TypeError，必须先int()。另外r.names在set_classes之后会变成list而不是默认的dict，有些老代码里写r.names[i]的地方会静默出错，改成直接索引classes更省事。
3.3 批量推理与结果落盘
单图跑通之后，实际项目基本都是批量或视频流。批量推理的关键是把模型实例复用起来，别在循环里反复构造模型。
from pathlib import Path from ultralytics import YOLOWorld model = YOLOWorld("yolov8s-worldv2.pt") model.set_classes(["person", "helmet", "safety vest"]) img_dir = Path("./images") out_dir = Path("./outputs") out_dir.mkdir(exist_ok=True) # stream=True 时返回生成器，逐张吐结果，内存占用可控 for res in model.predict( source=str(img_dir), imgsz=640, conf=0.30, batch=8, stream=True, save=True, project=str(out_dir), name="run", exist_ok=True, ): src = Path(res.path).name counts = {} for cid in res.boxes.cls.tolist(): label = model.model.names[int(cid)] counts[label] = counts.get(label, 0) + 1 print(src, counts)batch=8是显存和吞吐的平衡点，8G 显存的卡上跑s模型、640 输入，8 到 16 都可以试。stream=True在大目录场景下必须开，否则 ultralytics 会先把所有结果攒在内存里再返回，几千张图能把内存打满。save=True配合project和name指定输出目录，exist_ok=True避免重复运行时目录冲突报错，这个小参数在批量脚本里很值得加。
读结果的另一个常见需求是统计每类数量，上面用model.model.names拿标签名，比外部再维护一份classes更不容易错位。注意这里是model.model.names，两层.model，第一层是YOLOWorld包装类，第二层才是内部的检测模型，写一层会拿到外层对象、没有names属性。
4. 固定词表与重参数化：把推理速度拉回 YOLOv8 档位
4.1 set_classes 之后必须 save，否则下次加载白干
这是整份资料里最容易踩、也最容易被忽视的一点。set_classes()只改了内存里模型对象的txt_feats和names，如果你在同一个进程里接着推理，一切正常；一旦进程退出、重新加载原始.pt，词表就回到默认的 80 类（COCO 词表）。表现就是「昨天还能检出叉车，今天全是 person」。
正确顺序是设词表、立刻保存、之后统一用保存后的权重。
from ultralytics import YOLOWorld model = YOLOWorld("yolov8s-worldv2.pt") classes = ["pallet", "forklift", "cardboard box", "damaged cardboard box"] model.set_classes(classes) # 把词表和文本嵌入一起写进新的权重文件 model.save("pallet_world_fixed.pt")保存后的文件里带着txt_feats和对应的names，重新加载就能直接推理：
from ultralytics import YOLOWorld m = YOLOWorld("pallet_world_fixed.pt") print(m.model.names) # 检查词表是不是你要的那几类 print(m.model.txt_feats.shape) # (1, N, D)，N 是类别数，D 是嵌入维度txt_feats的形状值得看一眼。如果N和你设的类别数对不上，说明某一步被覆盖了，大概率是保存之后再调了一次set_classes但没重新save。这个检查我一般写在部署脚本的启动自检里，几行代码能省掉半小时的排查。
4.2 导出 ONNX / TensorRT：哪些设置是硬约束
离线词表模式下，模型已经退化成固定类别的检测器，导出这条路是通的。但有几个约束必须满足，否则导出的图在推理端结果对不上。
from ultralytics import YOLOWorld # 一定要先固定词表再导出，顺序反了导出的就是默认 80 类 model = YOLOWorld("pallet_world_fixed.pt") model.export( format="onnx", opset=12, imgsz=640, simplify=True, dynamic=False, half=False, )opset=12是个稳妥选择，太低不支持某些算子，太高部分推理引擎跟不上。dynamic=False建议先用固定尺寸验证通链路，动态 shape 会引入额外的对齐工作，而且部分算子对动态维支持不好。half=False在导出阶段先关掉，FP16 放到推理引擎那边做，出问题时更容易定位是哪一层的问题。
TensorRT 这条路类似，把format换成engine，前提是本机装了 TensorRT 并且版本和 CUDA 匹配。导出后第一件事是拿同一张图分别用 PyTorch 权重和引擎跑一遍，比对框的数量和坐标偏差。偏差在 1 到 2 个像素内属正常，框数差很多就说明导出时类别没固定住，或者后处理参数不一致。
| 导出格式 | 适用场景 | 注意点 |
|---|---|---|
| ONNX | 跨平台、跨推理引擎 | 先固定词表；opset 选 12 左右 |
| TensorRT engine | 固定显卡的边缘部署 | 引擎与显卡型号绑定，不能跨卡拷 |
| OpenVINO | CPU 侧加速 | 输入尺寸固定，动态 shape 支持有限 |
| TorchScript | 保留 PyTorch 生态 | 文本分支未剥离时容易失败 |
最后一行要重点说。如果模型还保留在线词表能力（没走重参数化），导出 TorchScript 或 ONNX 时大概率会失败或丢掉文本分支，导出成功也只是一个固定了当时那次文本嵌入的静态图。所以导出的前置条件永远只有一个：词表已固定、已保存、已重参数化。
4.3 视频流场景的参数取舍
视频流和批量图片的差别在于，延迟和吞吐是两套指标，参数调法完全不同。做实时预览，imgsz降到 480 甚至 416，conf相应抬到 0.35 补精度，帧间复用模型实例，别每帧set_classes。做离线批处理，imgsz拉到 800 或 960，batch尽量吃满显存，conf可以降到 0.25 换召回。
一个实测经验：词表规模对速度的影响是非线性的。10 类以内，离线模式下和同规模 YOLOv8 几乎没差；到 100 类，分类头那层 1×1 卷积的输出通道从 80 涨到 100，开销开始可见；到 1000 类，即便重参数化之后，那层卷积的 FLOPs 也不容忽视，建议按实际需求裁剪词表，别把整个标签体系一股脑塞进去。
注意：改词表之后已经导出的 ONNX / engine 全部作废，必须重导。版本管理上把「权重文件 + 词表文件 + 引擎文件」绑成一个版本号，别只改其中一个。
5. 避坑与排查：五类高频翻车现场
5.1 现象：换进程后类别全变回 COCO 80 类
原因基本只有一个：set_classes()之后没有save()，或者save()之后又在同一进程里调了一次set_classes但没重新保存，导致落盘的是前一份词表。还有一种更隐蔽的情况：导出脚本里重新YOLOWorld(原始权重)加载，忘了这次加载是原始的，词表已经丢了。
解决方式是把「设词表 → 保存 → 校验」写成一个固定函数，部署流程里只允许通过这个函数产出权重：
def build_fixed_weights(base_ckpt: str, classes: list[str], out_ckpt: str): from ultralytics import YOLOWorld m = YOLOWorld(base_ckpt) m.set_classes(classes) m.save(out_ckpt) # 立刻回读校验，避免带着错误配置往下走 chk = YOLOWorld(out_ckpt) assert list(chk.model.names) == classes, f"词表写入失败: {chk.model.names}" return out_ckptassert那一行是关键。少了它，错误会一直飘到推理结果里才暴露，那时候你已经在怀疑模型精度了。
5.2 现象：模型什么框都不出，或者框一大堆但标签全错
前者通常是词表用了中文，或者类别名过于抽象（比如单个词「defect」）。文本编码器对完整英文名词短语的响应最稳，抽象词和中文都会让相似度分布整体偏低，conf=0.3直接把它们全过滤掉。后者则相反，是词表里几个类别语义太近，比如同时放「box」和「cardboard box」，短词会到处抢框。
解决上，先把conf降到 0.05 看原始分布，如果连低阈值都没框，问题在文本侧，换英文短语重试；如果低阈值下框很多但高阈值全乱，问题在词表区分度，把语义相近的项合并或改写得更具体。我一般的习惯是词表里每两项之间至少有一个明确的修饰词差异，比如「worker with helmet」对「worker without helmet」。
5.3 现象：imgsz设成任意值，报错或者结果明显偏移
YOLO 系列的骨干是下采样 32 倍的，输入尺寸必须是 32 的整数倍，否则内部 padding 的对齐方式会让特征图和原图坐标映射出偏差。表现是框整体偏移几十像素，或者小目标直接漏检。
解决很直接，imgsz只取 416、480、512、640、800、960 这几个值。如果你确实需要非标准尺寸，先在原图上做 letterbox 到最近的 32 倍数，再推理，最后把框坐标反算回原图。ultralytics 内部对标准尺寸做了 letterbox，但自定义预处理如果和它对不上，就会出现「训练时好好的，推理全偏」这种血泪情况。
5.4 现象：微调之后精度不升反降，甚至比零样本还差
这个坑在于数据集配置里的names顺序和set_classes的顺序不一致。YOLO 训练时标签是按索引读的，索引 0 在数据集里是「crack」，在词表里是「stain」，模型学到的就是错位的映射，越训越偏。
解决方式是让custom.yaml的names和代码里的classes从同一份配置生成，别手工维护两份：
import yaml classes = ["crack", "stain", "dent"] with open("custom.yaml", "w", encoding="utf-8") as f: yaml.safe_dump( {"path": "./dataset", "train": "images/train", "val": "images/val", "names": {i: n for i, n in enumerate(classes)}}, f, allow_unicode=True, )顺手把这份classes也写进权重保存流程，三处同源，错位问题从根上消掉。
5.5 现象：视频流跑几分钟后显存爆掉
model.predict每帧调用一次，如果每次都传save=True或者保留Results对象引用，显存会缓慢累积。另外在循环里反复set_classes也会不断新建文本嵌入张量，旧的不释放。
解决是把推理循环写干净：模型实例在循环外构造一次，循环内只调predict，不保存Results引用，stream=True只在批量图片场景开、视频流逐帧传入更可控。需要可视化的帧立刻转成 numpy 或写入视频流，别让它挂在 Python 对象上等 GC。这类问题排查起来没有明确报错，只能靠nvidia-smi看曲线，涨了就是泄漏。
6. 在自己的数据上微调：一套能对上数的验证流程
零样本能出框，但对特定工业缺陷的精度往往不够，微调是绕不开的一步。资料里给了训练入口，实际跑之前有几个参数值得先说清楚。
from ultralytics import YOLOWorld model = YOLOWorld("yolov8s-worldv2.pt") model.set_classes(["crack", "stain", "dent"]) # 必须与 custom.yaml 的 names 同源 model.train( data="custom.yaml", epochs=80, imgsz=640, batch=8, patience=20, # 20 轮无提升就早停，微调场景很有效 lr0=0.001, # 比从头训低一个量级，避免破坏预训练的视觉特征 freeze=10, # 冻结骨干前 10 层，小数据集上明显更稳 cache="ram", # 数据集不大时直接进内存，省掉 IO 瓶颈 )lr0和freeze是微调的两个关键旋钮。学习率按从头训练的十分之一起步，样本量小于两千张时再往下压；freeze冻结骨干前若干层，让模型只调整 neck 和检测头，收敛快也更不容易过拟合。patience一定要设，微调场景下验证集指标往往在第 30 到 50 轮就见顶，后面纯属浪费卡时。
训完别只看 loss 曲线，跑一次带低阈值的val看真实分布：
metrics = model.val(data="custom.yaml", split="val", conf=0.001, iou=0.6) print("mAP50:", round(metrics.box.map50, 4)) print("mAP50-95:", round(metrics.box.map, 4))conf=0.001是为了让 PR 曲线从最左端开始算，得到的 mAP 才准；iou=0.6在工业缺陷这类框偏紧的任务上比默认 0.5 更严格一点，能提前暴露定位不准的问题。把微调后的 mAP50 和零样本基线放在一张表里对比，才知道这轮训练到底值不值。
| 指标 | 零样本基线 | 微调后 | 判读 |
|---|---|---|---|
| mAP50 | 0.42 | 0.71 | 有实质提升，微调值得 |
| mAP50-95 | 0.23 | 0.44 | 定位质量同步改善 |
| 单帧延迟 | 21ms | 21ms | 离线模式下不变 |
| 误检数（每图） | 3.6 | 0.9 | 词表歧义被训练消掉 |
最后一句是踩出来的教训：拿到一份开放词表模型的资料，别急着把它当万能检测器铺到所有场景。我现在的习惯是，任何一次词表变更都强制走一遍「设词表 → 保存 → 回读校验 → 用同一张图对比前后结果」，四步一步不落，因为翻车从来不是发生在模型结构上，而是发生在「我以为保存过了」的那一刻。希望帮到你。
本文还有配套的精品资源，点击获取
