尧图网页设计 
Ultralytics YOLOE 训练器家族源码级解析train.py中五种训练范式与线性探测、视觉提示、Prompt-free 实战指南【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralyticsYOLOE 是 Ultralytics 仓库中面向开放词汇检测与实例分割的模型家族其训练体系并不是单一大而全的训练器而是由一套职责分明的 Trainer 类家族构成。ultralytics/models/yolo/yoloe/train.py定义了标准训练、线性探测Linear Probing、从零训练From Scratch、Prompt-free 训练与视觉提示Visual Prompt训练五类训练器。读完本文你将彻底理清每个 Trainer 的继承关系与职责边界掌握在自己数据集上微调 YOLOE、训练检测/分割模型以及复现官方从零训练流程的正确调用方式。参考文档定位与训练模块全景docs/en/reference/models/yolo/yoloe/train.md是 Ultralytics 自动生成的 API 参考页按标准训练、线性探测、视觉提示训练detection 与 segmentation的分类收录了train.py中五个顶层 Trainer 类的签名与文档字符串YOLOETrainer—— YOLOE 检测模型的标准训练器支持多模态数据YOLOEPETrainer—— 使用线性探测方式微调 YOLOE 的训练器YOLOETrainerFromScratch—— 从零训练无预训练权重、带文本嵌入与 grounding 数据YOLOEPEFreeTrainer—— 训练Prompt-free免提示YOLOE 模型YOLOEVPTrainer—— 带视觉提示Visual Prompt的训练器。与之配套同一模块还通过 train_seg.py 提供分割任务的变体并在init.py 中统一导出。整个 yoloe 子模块的文件布局如下文件职责train.py五类检测/通用训练器本文主体train_seg.pyYOLOESegTrainer等分割任务变体val.pyYOLOEDetectValidator/YOLOESegValidator支持文本提示与视觉提示验证predict.pyYOLOEVPDetectPredictor/YOLOEVPSegPredictor视觉提示推理器init.py包级导出同时导出检测与分割训练器训练器继承关系总览理解 YOLOE 训练体系的第一把钥匙是继承关系。从源码看YOLOE 训练器复用了 Ultralytics 两条经典训练链——检测任务链DetectionTrainer与分割任务链SegmentationTrainer并把 YOLO-World 的混合 grounding 数据集能力WorldTrainerFromScratch组合进来训练器类直接/主要基类用途YOLOETrainerDetectionTrainer检测任务标准训练文本/视觉提示评测由专用验证器负责YOLOEPETrainerDetectionTrainer线性探测微调类别被fuse进分类头后按普通检测流程训练YOLOETrainerFromScratchYOLOETrainerWorldTrainerFromScratch从零训练支持yolo_data与grounding_data混合数据集并缓存文本嵌入YOLOEPEFreeTrainerYOLOEPETrainerYOLOETrainerFromScratch训练免提示模型无需文本嵌入推理无需文本编码器YOLOEVPTrainerYOLOETrainerFromScratch视觉提示训练数据集变换末尾追加LoadVisualPromptPython 多继承按 MRO 决定方法解析顺序例如YOLOEPEFreeTrainer(YOLOEPETrainer, YOLOETrainerFromScratch)意味着它同时具备线性探测的模型构建能力和从零训练的混合数据集能力而YOLOESegVPTrainer(YOLOEVPTrainer, YOLOESegTrainerFromScratch)则表明视觉提示 分割 从零训练三者叠加见 train_seg.py。YOLOETrainer通用基类与两个硬性约束YOLOETrainer继承自DetectionTrainer是标准微调 / 从零训练链路的基类train.py。初始化compileFalse与overlap_maskFalse构造函数有两个容易被忽略的强制行为train.pydef __init__(self, cfgDEFAULT_CFG, overridesNone, _callbacksNone): if overrides is None: overrides {} assert not overrides.get(compile), fTraining with model{overrides[model]} requires compileFalse overrides[overlap_mask] False super().__init__(cfg, overrides, _callbacks)拒绝compileTrueYOLOE 的训练以及分割 mask 分支尚不支持 torch.compile任何继承自YOLOETrainer的训练器都会直接断言失败。默认的YOLOESegTrainer与全部 from-scratch 训练器都受此约束。强制overlap_maskFalse覆盖默认配置禁止训练数据集中出现重叠 mask同一像素被多个实例共享。get_modelnc的真实含义与 80 类硬上限get_model按任务选择模型类并按数据集通道数、类别数实例化train.pymodel (YOLOESegModel if self.args.task segment else YOLOEModel)( cfg[yaml_file] if isinstance(cfg, dict) else cfg, chself.data[channels], ncmin(self.data[nc], 80), verboseverbose and RANK -1, )源码注释对此做了明确说明这里的nc不是真正的类别数而是单张图片中不同文本样本的最大数量同时为遵循官方配置nc当前被硬编码上限为 80min(self.data[nc], 80)。YOLOE 是开放词汇模型推理时类别由set_classes()或视觉提示动态给出模型本身在训练期并不固定死类别集合——这是理解后续所有 Trainer 差异的前提。build_dataset训练模式的多模态开关return build_yolo_dataset( self.args, img_path, batch, self.data, modemode, rectmode val, stridegs, multi_modalmode train )当mode train时开启multi_modalTrue多模态图像 文本验证模式下rectTrue使用矩形推理。gs为模型最大 stride 与 32 的较大者max(int(unwrap_model(self.model).stride.max()...), 32)。get_validator提示感知的验证器YOLOETrainer.get_validator返回的是 YOLOE 专用验证器分割任务返回YOLOESegValidator否则返回YOLOEDetectValidator见 train.py。这两类验证器在评测时会调用模型的get_text_pe(names)用文本提示生成嵌入或用get_visual_pe从参考样本提取视觉提示嵌入val.py。也就是说默认训练器按 YOLOE 的开放词汇语义评测不会针对你数据集的固定类别名称训练——这正是微调自己数据集要换训练器的根源。YOLOEPETrainer把类别名熔接进分类头的线性探测对大多数在自有数据上微调的用户来说YOLOEPETrainer及其分割版YOLOEPESegTrainer才是最常用到的训练器。它做一件关键的事把你的类别名先编码、再熔接fuse进分类头从而在微调阶段真正对着你的类别名训练。源码级拆解get_modeldel model.model[-1].savpe # 删除视觉提示编码模块 SAVPE assert weights is not None, Pretrained weights must be provided for linear probing. model.load(weights) # 必须加载预训练权重 model.eval() names list(self.data[names].values()) # 取数据集的类别名 tpe model.get_text_pe(names) # 通过文本编码器RepRTA 计算文本提示嵌入 model.set_classes(names, tpe) # 把名称与嵌入写入模型 model.model[-1].fuse(model.pe) # 把文本嵌入熔接到分类头 model.model[-1].cv3[0][2] deepcopy(model.model[-1].cv3[0][2]).requires_grad_(True) model.model[-1].cv3[1][2] deepcopy(model.model[-1].cv3[1][2]).requires_grad_(True) model.model[-1].cv3[2][2] deepcopy(model.model[-1].cv3[2][2]).requires_grad_(True) if getattr(model.model[-1], one2one_cv3, None) is not None: model.model[-1].one2one_cv3[0][2] deepcopy(...).requires_grad_(True) model.model[-1].one2one_cv3[1][2] deepcopy(...).requires_grad_(True) model.model[-1].one2one_cv3[2][2] deepcopy(...).requires_grad_(True) model.train()完整实现见 train.py示例中的...为同结构语句的省略。要点解读删除savpe线性探测阶段不需要视觉提示分支get_text_pe(names)类别文本先过文本模型得到原始嵌入再经YOLOEDetect头部的reprta可重参数化的 Region-Text Alignment 模块见 head.py精炼得到与区域特征可比对的最终文本嵌入该辅助网络只需在每次调用时跑一次导出时会被折叠掉fuse(model.pe)把整份类别嵌入折叠进分类头的卷积权重此后推理不再需要文本编码器参与逐帧计算.cv3[i][2]/.one2one_cv3[i][2]解冻每个分类塔的末层卷积被深拷贝并设为requires_grad_(True)可训练其余层保持预训练冻结状态——cv3对应常规多塔分类分支one2one_cv3仅存在于 YOLOE-26 端到端end2end配置中YAML 里end2end: True参考 yoloe-26-seg.yaml。结合训练时传入的freeze列表就实现了只训练分类投影层的线性探测。因为类别已被熔接进固定头部get_validator就不再需要 YOLOE 专用验证器而是返回标准DetectionValidator/SegmentationValidatortrain.py评测走普通封闭集流程。实战微调你的自有数据以分割任务为例官方推荐直接用YOLOEPESegTrainer来自 docs/en/models/yoloe.md 的微调配方from ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOEPESegTrainer model YOLOE(yoloe-26s-seg.pt) results model.train( datacoco128-seg.yaml, epochs80, patience10, trainerYOLOEPESegTrainer, # - Important: the fine-tuning trainer, not the default )注意官方发布权重都是分割检查点。若你手头是检测需求可从匹配的 YAML 构建模型、加载同尺度分割权重、并改用检测版YOLOEPETrainerfrom ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOEPETrainer model YOLOE(yoloe-26s.yaml).load(yoloe-26s-seg.pt) results model.train(datacoco128.yaml, epochs80, patience10, trainerYOLOEPETrainer)实战小数据上的严格线性探测当数据量很小、完整微调容易过拟合时应冻结除分类投影外的全部参数。先冻结主干与颈部head 之前的所有层再把每个分类塔cv3端到端配置还有one2one_cv3前三层中除末层卷积外的部分冻结from ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOEPESegTrainer model YOLOE(yoloe-26s-seg.pt) # Freeze the backbone and neck, i.e. everything before the head head_index len(model.model.model) - 1 freeze [str(i) for i in range(head_index)] # Freeze the whole head except the terminal conv of every classification tower for name, _ in model.model.model[-1].named_children(): if cv3 in name: # cv3, plus one2one_cv3 on end-to-end YOLOE-26 configs freeze.extend(f{head_index}.{name}.{i}.{j} for i in range(3) for j in (0, 1)) else: freeze.append(f{head_index}.{name}) results model.train( datacoco128-seg.yaml, epochs80, patience10, trainerYOLOEPESegTrainer, freezefreeze, )该配方与YOLOEPETrainer.get_model中仅解冻分类塔末层卷积的逻辑一一对应共同实现特征全部复用、只让分类决策适应新类别的效果。YOLOETrainerFromScratch混合 grounding 数据的从零训练要复现官方发布的开源检查点需要在 Objects365、GQA、Flickr30k约 140 万训练样本上从零训练。YOLOETrainerFromScratch(YOLOETrainer, WorldTrainerFromScratch)train.py正是为此设计build_dataset委托给WorldTrainerFromScratch既能从标准 YOLO 数据yolo_data对应*.yaml构建也能从 grounding 数据grounding_data的img_pathjson_file构建多数据集用YOLOConcatDataset拼接参考 train_world.py。训练文本嵌入在此阶段被批量生成并缓存以加速后续每个 epoch 的数据装载generate_text_embeddings(texts, batch, cache_dir)以text_model名称形如mobileclip2:b见 yoloe-26-seg.yaml生成缓存文件名text_embeddings_model.pt命中且文本集合完全一致时直接读缓存否则调用模型的get_text_pe(texts, batch, without_reprtaTrue, cache_clip_modelFalse)生成并用torch.save落盘train.py。注意这里先不经过reprta、也不缓存 CLIP 模型——与最终评测用的嵌入存在差异。从零训练的数据结构与入口data 既可以是同构字典也可以是指向相同结构 YAML 文件的路径。官方配方YOLOESegTrainerFromScratch形如from ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOESegTrainerFromScratch data { train: { yolo_data: [Objects365.yaml], grounding_data: [ { img_path: flickr/full_images/, json_file: flickr/annotations/final_flickr_separateGT_train_segm.json, }, { img_path: mixed_grounding/gqa/images, json_file: mixed_grounding/annotations/final_mixed_train_no_coco_segm.json, }, ], }, val: {yolo_data: [lvis.yaml]}, } model YOLOE(yoloe-26l-seg.yaml) model.train( datadata, # or the path to a YAML file holding the same structure batch128, epochs30, close_mosaic2, optimizerAdamW, lr02e-3, warmup_bias_lr0.0, weight_decay0.025, momentum0.9, workers4, trainerYOLOESegTrainerFromScratch, device0,1,2,3,4,5,6,7, )几点说明该流程需要带分割标注的数据官方用 SAM 2.1 生成的 mask JSON验证集为 LVIS数据集配置见 lvis.yaml验证时WorldTrainerFromScratch.get_dataset会为 LVIS 自动选择minival切分。所有 from-scratch 训练器都继承YOLOETrainer因此compileTrue一律被拒绝。YOLOEVPTrainer在变换管线中追加视觉提示加载YOLOEVPTrainer(YOLOETrainerFromScratch)用于用一个示例框教会模型识别某类目标如特定部件、logo、缺陷的场景train.py。它不改模型结构而是改数据集——通过 augment.py 中的LoadVisualPrompt()变换为每个样本绑定visuals参考框区域特征def build_dataset(self, img_path, modetrain, batchNone): dataset super().build_dataset(img_path, mode, batch) if isinstance(dataset, YOLOConcatDataset): for d in dataset.datasets: d.transforms.append(LoadVisualPrompt()) else: dataset.transforms.append(LoadVisualPrompt()) return dataset同时它重写了_close_dataloader_mosaictrain.pyYOLO 训练在后期会关闭 Mosaic 增强VP 训练器在关闭后再次追加LoadVisualPrompt保证视觉提示加载在任何数据增强裁剪之后仍能正确对齐到最终图像。训练后的文本提示模型在此基础上只更新视觉提示编码模块SAVPE即可派生出视觉提示检查点。YOLOEPEFreeTrainerPrompt-free 免提示模型训练YOLOEPEFreeTrainer(YOLOEPETrainer, YOLOETrainerFromScratch)训练出的模型靠内置词表约 4585 类识别目标推理时既不需要文本提示也不需要文本编码器train.py。它的实现精髓是两个空操作覆盖def preprocess_batch(self, batch): Preprocess a batch of images for YOLOE training, adjusting formatting and dimensions as needed. return DetectionTrainer.preprocess_batch(self, batch) def set_text_embeddings(self, datasets, batch: int): No-op override for prompt-free training that does not require text embeddings. pass # 源码为 pass 体空实现preprocess_batch直接回到DetectionTrainer的标准实现不注入文本特征set_text_embeddings是空操作从零训练阶段本应为数据集批量生成文本嵌入Prompt-free 训练完全不需要。在 head.py 中prompt-free 推理走的是forward_lrpc路径lrpc Lazy Region-Prompt Contrast按内置词表匹配区域嵌入验证器也会据此判断见 val.py。训练结束后需用get_vocab/set_vocab把词表重参数化进检查点详细配方见下文。分割任务变体train_seg.py四件套分割场景并不重复实现逻辑而是通过组合与别名复用检测训练器train_seg.py分割训练器组成方式对应检测等价物YOLOESegTrainerYOLOETrainerSegmentationTrainerYOLOETrainerYOLOEPESegTrainerSegmentationTrainer单继承get_model直接借用YOLOEPETrainer.get_modelYOLOEPETrainerYOLOESegTrainerFromScratchYOLOETrainerFromScratchYOLOESegTrainerYOLOETrainerFromScratchYOLOESegVPTrainerYOLOEVPTrainerYOLOESegTrainerFromScratchYOLOEVPTrainer其中YOLOEPESegTrainer(SegmentationTrainer)是一个值得注意的设计它保持SegmentationTrainer为唯一直接基类避免与线性探测模型构建逻辑产生 MRO 冲突再用一行get_model YOLOEPETrainer.get_model复用线性探测的模型构建——这类共享方法 单一基类的写法在 train_seg.py 源码注释中有明确交代。视觉提示的分割训练变体YOLOESegVPTrainer对应官方配方中的 VP 阶段。训练器注册task_map与默认入口YOLOE模型类在 model.py 的task_map中注册了默认的 trainer / validator / predictordetect: { model: YOLOEModel, validator: yolo.yoloe.YOLOEDetectValidator, predictor: yolo.detect.DetectionPredictor, trainer: yolo.yoloe.YOLOETrainer, }, segment: { model: YOLOESegModel, validator: yolo.yoloe.YOLOESegValidator, predictor: yolo.segment.SegmentationPredictor, trainer: yolo.yoloe.YOLOESegTrainer, },即不显式传trainer时加载*-seg.pt走YOLOESegTrainer默认分割训练器评测需要文本/视觉提示加载 YAML 构建的检测模型走YOLOETrainer。两种默认训练器都继承YOLOETrainer因此都要求compileFalse。由于默认训练器不针对你的固定类别名训练需要按使用场景显式传入 trainer你的目标使用的训练器关键点微调自己的数据推荐官方权重为分割模型YOLOEPESegTrainer类别名熔接进头部后再训练训练一个检测模型YOLOEPETrainer从yoloe-*-*.yaml构建、加载同尺度 seg 权重严格线性探测小数据集YOLOEPESegTrainerfreeze列表仅解冻分类塔末层卷积复现官方文本提示检查点YOLOESegTrainerFromScratchyolo_datagrounding_data混合数据集、缓存文本嵌入视觉提示阶段VPYOLOESegVPTrainer由已训练的文本提示模型继续配freeze冻结除savpe外头部Prompt-free 阶段YOLOEPEFreeTrainer冻结所有分类塔另需single_clsTrue从官方流程看三种推理能力是递进派生关系先用YOLOESegTrainerFromScratch训练文本提示模型YOLOESegVPTrainer视觉提示与YOLOEPEFreeTrainerPrompt-free分别从该模型出发、各更新一个模块SAVPE 编码器 / LRPC 词表匹配分支。需要注意VP 与 PEFree 训练器本身不冻结任何参数——选择性训练完全由随 train 传入的freeze列表实现冻结除savpe外的全部头部子模块或冻结全部分类塔。Prompt-free 运行的权重在头部已被熔接用文本提示运行的权重头部未熔接二者配合可把自定义词表写入最终免提示检查点from ultralytics import YOLOE model YOLOE(runs/segment/train-2/weights/best.pt) # prompt-free 运行的权重 text_model YOLOE(runs/segment/train/weights/best.pt) # 同源文本提示运行的权重 names list(YOLOE(yoloe-26l-seg-pf.pt).model.names.values()) # 内置 4585 词表或自定义列表 vocab text_model.get_vocab(names) model.set_vocab(vocab, names) model.save(yoloe-26l-seg-pf-custom.pt) # 切勿覆盖官方发布权重get_vocab/set_vocab的 API 说明见 docs/en/reference/models/yolo/model.md。与训练器配套的验证体系YOLOE 训练离不开专用验证器val.py 与训练器一一呼应YOLOEDetectValidator与YOLOESegValidator后者同时继承DetectionValidator语义在验证时按需选择提示来源load_vpFalse时用get_text_pe(names)走文本提示load_vpTrue时用get_visual_pe从训练样本中逐类统计并 L2 归一化出视觉提示嵌入还可通过refer_data指定另一份同类别数据集提取val.py头部带lrpc的 Prompt-free 模型则直接进入forward_lrpc的免提示评测分支验证集名字会按name.split(/, 1)[0]取主类别名LVIS 长尾类别名含/层级结构。决策小结与使用注意事项综合全篇围绕train.py训练器家族可以得到几条直接可用的结论日常微调选 PE 家族YOLOEPESegTrainer分割/YOLOEPETrainer检测它们先把set_classes()后的文本嵌入经reprta精炼再fuse进分类头训练、验证都走普通封闭集流程默认训练器与 from-scratch 家族禁止compileTruePE 家族没有该限制nc在 YOLOE 训练里代表单图最多不同文本数上限 80不要把它当真实类别数VP 与 Prompt-free 是官方检查点的派生阶段依靠freeze列表 LoadVisualPrompt变换 / 空操作的set_text_embeddings实现无需各自从零训练。如果想继续深入可依次阅读 train.py五类训练器实现、train_seg.py分割变体组合、yoloe-26-seg.yaml端到端分割架构与尺度缩放、docs/en/models/yoloe.md完整的训练/微调/视觉提示/免提示配方与 LVIS 评测说明以及各.yaml中的模型定义与验证代码。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ultralytics YOLOE 训练器家族源码级解析：`train.py` 中五种训练范式与线性探测、视觉提示、Prompt-free 实战指南
Ultralytics YOLOE 训练器家族源码级解析train.py中五种训练范式与线性探测、视觉提示、Prompt-free 实战指南【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralyticsYOLOE 是 Ultralytics 仓库中面向开放词汇检测与实例分割的模型家族其训练体系并不是单一大而全的训练器而是由一套职责分明的 Trainer 类家族构成。ultralytics/models/yolo/yoloe/train.py定义了标准训练、线性探测Linear Probing、从零训练From Scratch、Prompt-free 训练与视觉提示Visual Prompt训练五类训练器。读完本文你将彻底理清每个 Trainer 的继承关系与职责边界掌握在自己数据集上微调 YOLOE、训练检测/分割模型以及复现官方从零训练流程的正确调用方式。参考文档定位与训练模块全景docs/en/reference/models/yolo/yoloe/train.md是 Ultralytics 自动生成的 API 参考页按标准训练、线性探测、视觉提示训练detection 与 segmentation的分类收录了train.py中五个顶层 Trainer 类的签名与文档字符串YOLOETrainer—— YOLOE 检测模型的标准训练器支持多模态数据YOLOEPETrainer—— 使用线性探测方式微调 YOLOE 的训练器YOLOETrainerFromScratch—— 从零训练无预训练权重、带文本嵌入与 grounding 数据YOLOEPEFreeTrainer—— 训练Prompt-free免提示YOLOE 模型YOLOEVPTrainer—— 带视觉提示Visual Prompt的训练器。与之配套同一模块还通过 train_seg.py 提供分割任务的变体并在init.py 中统一导出。整个 yoloe 子模块的文件布局如下文件职责train.py五类检测/通用训练器本文主体train_seg.pyYOLOESegTrainer等分割任务变体val.pyYOLOEDetectValidator/YOLOESegValidator支持文本提示与视觉提示验证predict.pyYOLOEVPDetectPredictor/YOLOEVPSegPredictor视觉提示推理器init.py包级导出同时导出检测与分割训练器训练器继承关系总览理解 YOLOE 训练体系的第一把钥匙是继承关系。从源码看YOLOE 训练器复用了 Ultralytics 两条经典训练链——检测任务链DetectionTrainer与分割任务链SegmentationTrainer并把 YOLO-World 的混合 grounding 数据集能力WorldTrainerFromScratch组合进来训练器类直接/主要基类用途YOLOETrainerDetectionTrainer检测任务标准训练文本/视觉提示评测由专用验证器负责YOLOEPETrainerDetectionTrainer线性探测微调类别被fuse进分类头后按普通检测流程训练YOLOETrainerFromScratchYOLOETrainerWorldTrainerFromScratch从零训练支持yolo_data与grounding_data混合数据集并缓存文本嵌入YOLOEPEFreeTrainerYOLOEPETrainerYOLOETrainerFromScratch训练免提示模型无需文本嵌入推理无需文本编码器YOLOEVPTrainerYOLOETrainerFromScratch视觉提示训练数据集变换末尾追加LoadVisualPromptPython 多继承按 MRO 决定方法解析顺序例如YOLOEPEFreeTrainer(YOLOEPETrainer, YOLOETrainerFromScratch)意味着它同时具备线性探测的模型构建能力和从零训练的混合数据集能力而YOLOESegVPTrainer(YOLOEVPTrainer, YOLOESegTrainerFromScratch)则表明视觉提示 分割 从零训练三者叠加见 train_seg.py。YOLOETrainer通用基类与两个硬性约束YOLOETrainer继承自DetectionTrainer是标准微调 / 从零训练链路的基类train.py。初始化compileFalse与overlap_maskFalse构造函数有两个容易被忽略的强制行为train.pydef __init__(self, cfgDEFAULT_CFG, overridesNone, _callbacksNone): if overrides is None: overrides {} assert not overrides.get(compile), fTraining with model{overrides[model]} requires compileFalse overrides[overlap_mask] False super().__init__(cfg, overrides, _callbacks)拒绝compileTrueYOLOE 的训练以及分割 mask 分支尚不支持 torch.compile任何继承自YOLOETrainer的训练器都会直接断言失败。默认的YOLOESegTrainer与全部 from-scratch 训练器都受此约束。强制overlap_maskFalse覆盖默认配置禁止训练数据集中出现重叠 mask同一像素被多个实例共享。get_modelnc的真实含义与 80 类硬上限get_model按任务选择模型类并按数据集通道数、类别数实例化train.pymodel (YOLOESegModel if self.args.task segment else YOLOEModel)( cfg[yaml_file] if isinstance(cfg, dict) else cfg, chself.data[channels], ncmin(self.data[nc], 80), verboseverbose and RANK -1, )源码注释对此做了明确说明这里的nc不是真正的类别数而是单张图片中不同文本样本的最大数量同时为遵循官方配置nc当前被硬编码上限为 80min(self.data[nc], 80)。YOLOE 是开放词汇模型推理时类别由set_classes()或视觉提示动态给出模型本身在训练期并不固定死类别集合——这是理解后续所有 Trainer 差异的前提。build_dataset训练模式的多模态开关return build_yolo_dataset( self.args, img_path, batch, self.data, modemode, rectmode val, stridegs, multi_modalmode train )当mode train时开启multi_modalTrue多模态图像 文本验证模式下rectTrue使用矩形推理。gs为模型最大 stride 与 32 的较大者max(int(unwrap_model(self.model).stride.max()...), 32)。get_validator提示感知的验证器YOLOETrainer.get_validator返回的是 YOLOE 专用验证器分割任务返回YOLOESegValidator否则返回YOLOEDetectValidator见 train.py。这两类验证器在评测时会调用模型的get_text_pe(names)用文本提示生成嵌入或用get_visual_pe从参考样本提取视觉提示嵌入val.py。也就是说默认训练器按 YOLOE 的开放词汇语义评测不会针对你数据集的固定类别名称训练——这正是微调自己数据集要换训练器的根源。YOLOEPETrainer把类别名熔接进分类头的线性探测对大多数在自有数据上微调的用户来说YOLOEPETrainer及其分割版YOLOEPESegTrainer才是最常用到的训练器。它做一件关键的事把你的类别名先编码、再熔接fuse进分类头从而在微调阶段真正对着你的类别名训练。源码级拆解get_modeldel model.model[-1].savpe # 删除视觉提示编码模块 SAVPE assert weights is not None, Pretrained weights must be provided for linear probing. model.load(weights) # 必须加载预训练权重 model.eval() names list(self.data[names].values()) # 取数据集的类别名 tpe model.get_text_pe(names) # 通过文本编码器RepRTA 计算文本提示嵌入 model.set_classes(names, tpe) # 把名称与嵌入写入模型 model.model[-1].fuse(model.pe) # 把文本嵌入熔接到分类头 model.model[-1].cv3[0][2] deepcopy(model.model[-1].cv3[0][2]).requires_grad_(True) model.model[-1].cv3[1][2] deepcopy(model.model[-1].cv3[1][2]).requires_grad_(True) model.model[-1].cv3[2][2] deepcopy(model.model[-1].cv3[2][2]).requires_grad_(True) if getattr(model.model[-1], one2one_cv3, None) is not None: model.model[-1].one2one_cv3[0][2] deepcopy(...).requires_grad_(True) model.model[-1].one2one_cv3[1][2] deepcopy(...).requires_grad_(True) model.model[-1].one2one_cv3[2][2] deepcopy(...).requires_grad_(True) model.train()完整实现见 train.py示例中的...为同结构语句的省略。要点解读删除savpe线性探测阶段不需要视觉提示分支get_text_pe(names)类别文本先过文本模型得到原始嵌入再经YOLOEDetect头部的reprta可重参数化的 Region-Text Alignment 模块见 head.py精炼得到与区域特征可比对的最终文本嵌入该辅助网络只需在每次调用时跑一次导出时会被折叠掉fuse(model.pe)把整份类别嵌入折叠进分类头的卷积权重此后推理不再需要文本编码器参与逐帧计算.cv3[i][2]/.one2one_cv3[i][2]解冻每个分类塔的末层卷积被深拷贝并设为requires_grad_(True)可训练其余层保持预训练冻结状态——cv3对应常规多塔分类分支one2one_cv3仅存在于 YOLOE-26 端到端end2end配置中YAML 里end2end: True参考 yoloe-26-seg.yaml。结合训练时传入的freeze列表就实现了只训练分类投影层的线性探测。因为类别已被熔接进固定头部get_validator就不再需要 YOLOE 专用验证器而是返回标准DetectionValidator/SegmentationValidatortrain.py评测走普通封闭集流程。实战微调你的自有数据以分割任务为例官方推荐直接用YOLOEPESegTrainer来自 docs/en/models/yoloe.md 的微调配方from ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOEPESegTrainer model YOLOE(yoloe-26s-seg.pt) results model.train( datacoco128-seg.yaml, epochs80, patience10, trainerYOLOEPESegTrainer, # - Important: the fine-tuning trainer, not the default )注意官方发布权重都是分割检查点。若你手头是检测需求可从匹配的 YAML 构建模型、加载同尺度分割权重、并改用检测版YOLOEPETrainerfrom ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOEPETrainer model YOLOE(yoloe-26s.yaml).load(yoloe-26s-seg.pt) results model.train(datacoco128.yaml, epochs80, patience10, trainerYOLOEPETrainer)实战小数据上的严格线性探测当数据量很小、完整微调容易过拟合时应冻结除分类投影外的全部参数。先冻结主干与颈部head 之前的所有层再把每个分类塔cv3端到端配置还有one2one_cv3前三层中除末层卷积外的部分冻结from ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOEPESegTrainer model YOLOE(yoloe-26s-seg.pt) # Freeze the backbone and neck, i.e. everything before the head head_index len(model.model.model) - 1 freeze [str(i) for i in range(head_index)] # Freeze the whole head except the terminal conv of every classification tower for name, _ in model.model.model[-1].named_children(): if cv3 in name: # cv3, plus one2one_cv3 on end-to-end YOLOE-26 configs freeze.extend(f{head_index}.{name}.{i}.{j} for i in range(3) for j in (0, 1)) else: freeze.append(f{head_index}.{name}) results model.train( datacoco128-seg.yaml, epochs80, patience10, trainerYOLOEPESegTrainer, freezefreeze, )该配方与YOLOEPETrainer.get_model中仅解冻分类塔末层卷积的逻辑一一对应共同实现特征全部复用、只让分类决策适应新类别的效果。YOLOETrainerFromScratch混合 grounding 数据的从零训练要复现官方发布的开源检查点需要在 Objects365、GQA、Flickr30k约 140 万训练样本上从零训练。YOLOETrainerFromScratch(YOLOETrainer, WorldTrainerFromScratch)train.py正是为此设计build_dataset委托给WorldTrainerFromScratch既能从标准 YOLO 数据yolo_data对应*.yaml构建也能从 grounding 数据grounding_data的img_pathjson_file构建多数据集用YOLOConcatDataset拼接参考 train_world.py。训练文本嵌入在此阶段被批量生成并缓存以加速后续每个 epoch 的数据装载generate_text_embeddings(texts, batch, cache_dir)以text_model名称形如mobileclip2:b见 yoloe-26-seg.yaml生成缓存文件名text_embeddings_model.pt命中且文本集合完全一致时直接读缓存否则调用模型的get_text_pe(texts, batch, without_reprtaTrue, cache_clip_modelFalse)生成并用torch.save落盘train.py。注意这里先不经过reprta、也不缓存 CLIP 模型——与最终评测用的嵌入存在差异。从零训练的数据结构与入口data 既可以是同构字典也可以是指向相同结构 YAML 文件的路径。官方配方YOLOESegTrainerFromScratch形如from ultralytics import YOLOE from ultralytics.models.yolo.yoloe import YOLOESegTrainerFromScratch data { train: { yolo_data: [Objects365.yaml], grounding_data: [ { img_path: flickr/full_images/, json_file: flickr/annotations/final_flickr_separateGT_train_segm.json, }, { img_path: mixed_grounding/gqa/images, json_file: mixed_grounding/annotations/final_mixed_train_no_coco_segm.json, }, ], }, val: {yolo_data: [lvis.yaml]}, } model YOLOE(yoloe-26l-seg.yaml) model.train( datadata, # or the path to a YAML file holding the same structure batch128, epochs30, close_mosaic2, optimizerAdamW, lr02e-3, warmup_bias_lr0.0, weight_decay0.025, momentum0.9, workers4, trainerYOLOESegTrainerFromScratch, device0,1,2,3,4,5,6,7, )几点说明该流程需要带分割标注的数据官方用 SAM 2.1 生成的 mask JSON验证集为 LVIS数据集配置见 lvis.yaml验证时WorldTrainerFromScratch.get_dataset会为 LVIS 自动选择minival切分。所有 from-scratch 训练器都继承YOLOETrainer因此compileTrue一律被拒绝。YOLOEVPTrainer在变换管线中追加视觉提示加载YOLOEVPTrainer(YOLOETrainerFromScratch)用于用一个示例框教会模型识别某类目标如特定部件、logo、缺陷的场景train.py。它不改模型结构而是改数据集——通过 augment.py 中的LoadVisualPrompt()变换为每个样本绑定visuals参考框区域特征def build_dataset(self, img_path, modetrain, batchNone): dataset super().build_dataset(img_path, mode, batch) if isinstance(dataset, YOLOConcatDataset): for d in dataset.datasets: d.transforms.append(LoadVisualPrompt()) else: dataset.transforms.append(LoadVisualPrompt()) return dataset同时它重写了_close_dataloader_mosaictrain.pyYOLO 训练在后期会关闭 Mosaic 增强VP 训练器在关闭后再次追加LoadVisualPrompt保证视觉提示加载在任何数据增强裁剪之后仍能正确对齐到最终图像。训练后的文本提示模型在此基础上只更新视觉提示编码模块SAVPE即可派生出视觉提示检查点。YOLOEPEFreeTrainerPrompt-free 免提示模型训练YOLOEPEFreeTrainer(YOLOEPETrainer, YOLOETrainerFromScratch)训练出的模型靠内置词表约 4585 类识别目标推理时既不需要文本提示也不需要文本编码器train.py。它的实现精髓是两个空操作覆盖def preprocess_batch(self, batch): Preprocess a batch of images for YOLOE training, adjusting formatting and dimensions as needed. return DetectionTrainer.preprocess_batch(self, batch) def set_text_embeddings(self, datasets, batch: int): No-op override for prompt-free training that does not require text embeddings. pass # 源码为 pass 体空实现preprocess_batch直接回到DetectionTrainer的标准实现不注入文本特征set_text_embeddings是空操作从零训练阶段本应为数据集批量生成文本嵌入Prompt-free 训练完全不需要。在 head.py 中prompt-free 推理走的是forward_lrpc路径lrpc Lazy Region-Prompt Contrast按内置词表匹配区域嵌入验证器也会据此判断见 val.py。训练结束后需用get_vocab/set_vocab把词表重参数化进检查点详细配方见下文。分割任务变体train_seg.py四件套分割场景并不重复实现逻辑而是通过组合与别名复用检测训练器train_seg.py分割训练器组成方式对应检测等价物YOLOESegTrainerYOLOETrainerSegmentationTrainerYOLOETrainerYOLOEPESegTrainerSegmentationTrainer单继承get_model直接借用YOLOEPETrainer.get_modelYOLOEPETrainerYOLOESegTrainerFromScratchYOLOETrainerFromScratchYOLOESegTrainerYOLOETrainerFromScratchYOLOESegVPTrainerYOLOEVPTrainerYOLOESegTrainerFromScratchYOLOEVPTrainer其中YOLOEPESegTrainer(SegmentationTrainer)是一个值得注意的设计它保持SegmentationTrainer为唯一直接基类避免与线性探测模型构建逻辑产生 MRO 冲突再用一行get_model YOLOEPETrainer.get_model复用线性探测的模型构建——这类共享方法 单一基类的写法在 train_seg.py 源码注释中有明确交代。视觉提示的分割训练变体YOLOESegVPTrainer对应官方配方中的 VP 阶段。训练器注册task_map与默认入口YOLOE模型类在 model.py 的task_map中注册了默认的 trainer / validator / predictordetect: { model: YOLOEModel, validator: yolo.yoloe.YOLOEDetectValidator, predictor: yolo.detect.DetectionPredictor, trainer: yolo.yoloe.YOLOETrainer, }, segment: { model: YOLOESegModel, validator: yolo.yoloe.YOLOESegValidator, predictor: yolo.segment.SegmentationPredictor, trainer: yolo.yoloe.YOLOESegTrainer, },即不显式传trainer时加载*-seg.pt走YOLOESegTrainer默认分割训练器评测需要文本/视觉提示加载 YAML 构建的检测模型走YOLOETrainer。两种默认训练器都继承YOLOETrainer因此都要求compileFalse。由于默认训练器不针对你的固定类别名训练需要按使用场景显式传入 trainer你的目标使用的训练器关键点微调自己的数据推荐官方权重为分割模型YOLOEPESegTrainer类别名熔接进头部后再训练训练一个检测模型YOLOEPETrainer从yoloe-*-*.yaml构建、加载同尺度 seg 权重严格线性探测小数据集YOLOEPESegTrainerfreeze列表仅解冻分类塔末层卷积复现官方文本提示检查点YOLOESegTrainerFromScratchyolo_datagrounding_data混合数据集、缓存文本嵌入视觉提示阶段VPYOLOESegVPTrainer由已训练的文本提示模型继续配freeze冻结除savpe外头部Prompt-free 阶段YOLOEPEFreeTrainer冻结所有分类塔另需single_clsTrue从官方流程看三种推理能力是递进派生关系先用YOLOESegTrainerFromScratch训练文本提示模型YOLOESegVPTrainer视觉提示与YOLOEPEFreeTrainerPrompt-free分别从该模型出发、各更新一个模块SAVPE 编码器 / LRPC 词表匹配分支。需要注意VP 与 PEFree 训练器本身不冻结任何参数——选择性训练完全由随 train 传入的freeze列表实现冻结除savpe外的全部头部子模块或冻结全部分类塔。Prompt-free 运行的权重在头部已被熔接用文本提示运行的权重头部未熔接二者配合可把自定义词表写入最终免提示检查点from ultralytics import YOLOE model YOLOE(runs/segment/train-2/weights/best.pt) # prompt-free 运行的权重 text_model YOLOE(runs/segment/train/weights/best.pt) # 同源文本提示运行的权重 names list(YOLOE(yoloe-26l-seg-pf.pt).model.names.values()) # 内置 4585 词表或自定义列表 vocab text_model.get_vocab(names) model.set_vocab(vocab, names) model.save(yoloe-26l-seg-pf-custom.pt) # 切勿覆盖官方发布权重get_vocab/set_vocab的 API 说明见 docs/en/reference/models/yolo/model.md。与训练器配套的验证体系YOLOE 训练离不开专用验证器val.py 与训练器一一呼应YOLOEDetectValidator与YOLOESegValidator后者同时继承DetectionValidator语义在验证时按需选择提示来源load_vpFalse时用get_text_pe(names)走文本提示load_vpTrue时用get_visual_pe从训练样本中逐类统计并 L2 归一化出视觉提示嵌入还可通过refer_data指定另一份同类别数据集提取val.py头部带lrpc的 Prompt-free 模型则直接进入forward_lrpc的免提示评测分支验证集名字会按name.split(/, 1)[0]取主类别名LVIS 长尾类别名含/层级结构。决策小结与使用注意事项综合全篇围绕train.py训练器家族可以得到几条直接可用的结论日常微调选 PE 家族YOLOEPESegTrainer分割/YOLOEPETrainer检测它们先把set_classes()后的文本嵌入经reprta精炼再fuse进分类头训练、验证都走普通封闭集流程默认训练器与 from-scratch 家族禁止compileTruePE 家族没有该限制nc在 YOLOE 训练里代表单图最多不同文本数上限 80不要把它当真实类别数VP 与 Prompt-free 是官方检查点的派生阶段依靠freeze列表 LoadVisualPrompt变换 / 空操作的set_text_embeddings实现无需各自从零训练。如果想继续深入可依次阅读 train.py五类训练器实现、train_seg.py分割变体组合、yoloe-26-seg.yaml端到端分割架构与尺度缩放、docs/en/models/yoloe.md完整的训练/微调/视觉提示/免提示配方与 LVIS 评测说明以及各.yaml中的模型定义与验证代码。【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考