Ultralytics auto_annotate 自动标注完全指南：用 YOLO 检测 + SAM 分割零手工生成高质量数据集

Ultralytics auto_annotate 自动标注完全指南：用 YOLO 检测 + SAM 分割零手工生成高质量数据集

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics

auto_annotate是 Ultralytics 提供的一条极简自动标注流水线：先用预训练 YOLO 检测模型圈出目标，再用 SAM 系列分割模型为每个框生成像素级轮廓，最终直接产出 YOLO 分割格式（txt）标注文件。本文以 annotator.py 的源码实现为主线，完整覆盖其全部参数、内部调用链、输出文件格式与最佳实践，帮助你在不写一行标注工具代码的情况下，把任意图片目录一键变成可直接用于训练的 segmentation 数据集。

核心函数速览与工作流程

auto_annotate定义在 ultralytics/data/annotator.py，是全仓库文档化引用页 docs/en/reference/data/annotator.md 的核心（也是唯一的）公开函数。它返回None，标注结果直接落盘。整条流水线只由三个环节构成：

1. 目标检测：用 YOLO 检测模型（默认yolo26x.pt）对每张图做目标框预测，得到候选boxes与类别cls；
2. 提示式分割：把检测框作为 SAM 的bboxes提示输入，SAM 针对每个框输出对应的实例分割 mask；
3. 格式落地：把每个 mask 的归一化轮廓坐标与类别 id 写成一个 YOLO 分割格式的.txt标签文件。

从源码结构看，auto_annotate只做"编排"，底层完全复用YOLO与SAM两个成熟的推理入口（分别定义在 ultralytics/models/yolo/model.py 与 ultralytics/models/sam/model.py），因此它不需要任何训练，开箱即用。

自动标注的流水线内部实现

先看源码整体（ultralytics/data/annotator.py）：

def auto_annotate( data: str | Path, det_model: str = "yolo26x.pt", sam_model: str = "sam_b.pt", device: str = "", conf: float = 0.25, iou: float = 0.45, imgsz: int = 640, max_det: int = 300, classes: list[int] | None = None, output_dir: str | Path | None = None, ) -> None:

函数体内按如下逻辑推进：

1. 加载两个模型：det_model = YOLO(det_model)、sam_model = SAM(sam_model)。权重文件不存在时会自动下载；也支持传入本地权重路径。

2. 确定输出目录：若未显式给出output_dir，则默认创建输入图片目录的同级姊妹目录<输入目录名>_auto_annotate_labels，例如对data="ultralytics/assets"会得到ultralytics/assets_auto_annotate_labels；随后Path(output_dir).mkdir(exist_ok=True, parents=True)确保目录存在。

3. 批量检测：调用det_model(data, stream=True, device=device, conf=conf, iou=iou, imgsz=imgsz, max_det=max_det, classes=classes)，以流式生成器逐个返回每张图的Results对象。

4. 逐图精修：

   • 通过result.boxes.cls.int().tolist()取出该图所有检测框的类别 id；若某张图没有检测到任何目标（空列表），则跳过该图、不生成标注文件；
   • 将result.boxes.xyxy（绝对像素坐标框）作为提示喂给sam_model(result.orig_img, bboxes=boxes, verbose=False, save=False, device=device)，orig_img保证 SAM 在原始分辨率上精修，不经过 YOLO 的imgsz缩放；
   • 取sam_results[0].masks.xyn获得归一化 mask 轮廓。

5. 写标签文件：每个图对应一个与图片同名的.txt（如image.jpg→image.txt），逐行写出。

关键实现细节：为何坐标是归一化小数

写文件时遍历每个 mask 轮廓，把(N, 2)的归一化坐标拉平为一行：

segments = sam_results[0].masks.xyn with open(f"{Path(output_dir) / Path(result.path).stem}.txt", "w", encoding="utf-8") as f: for i, s in enumerate(segments): if len(s) >= 3: # fewer than 3 points is not a polygon... segment = map(str, s.reshape(-1).tolist()) f.write(f"{class_ids[i]} " + " ".join(segment) + "\n")

需要理解的两个关键点：

• masks.xyn返回的是归一化多边形坐标。该属性定义于 ultralytics/engine/results.py，内部先经ops.masks2segments把二进制 mask 转成轮廓点集，再经ops.scale_coords(..., self.orig_shape, normalize=True)归一化到[0, 1]区间。这意味着 YOLO 训练约定里的x_center y_center w h式归一化在这里并不适用——本输出是逐点多边形归一化坐标，对应 YOLO 分割任务的标签格式：<class> <x1> <y1> <x2> <y2> ...。
• 少于 3 个点的轮廓会被静默丢弃。源码注释明确指出：不足 3 个点无法构成多边形，写出后也没有任何加载器能够解析，因此在写盘时直接跳过，从根源上避免产生脏标注行。

参数详解

下表完整继承自仓库共享宏 docs/macros/sam-auto-annotate.md，并与源码默认值一一对应：

参数语义都透传给底层推理：conf、iou、imgsz、max_det、classes在 YOLO 检测调用中被原样使用（见源码第 52-54 行），与 docs/en/modes/predict.md 中 Predict 模式的同名参数行为一致；device对检测与分割两阶段都生效，Slicing 时注意 SAM 对显存占用更高。

端到端运行示例

在仓库根目录下用自带的示例图片（ultralytics/assets）跑通最简流程：

from ultralytics.data.annotator import auto_annotate # 最简调用：默认 yolo26x 检测 + sam_b 分割 auto_annotate(data="ultralytics/assets") # 显式指定轻量模型与保存目录（适合 CPU / 快速验证） auto_annotate( data="ultralytics/assets", det_model="yolo26n.pt", sam_model="mobile_sam.pt", device="cuda", # 无 GPU 时改为 "cpu" output_dir="runs/auto_annotate_labels", )

运行结束后，output_dir（或默认生成的assets_auto_annotate_labels目录）内会出现与每张图片同名的.txt文件。一个标签文件的内容形如：

0 0.581 0.412 0.588 0.410 0.596 0.415 ... # 类别 0 的多边形轮廓（归一化坐标） 2 0.120 0.301 0.131 0.298 0.139 0.305 ... # 类别 2 的第二个实例

其中每行第一个数字是检测模型预测出的类别 id（注意：id 对应det_model自身的类别表，而非目标数据集新定义的类别），其后是偶数个浮点数、每两个一组构成一个归一化坐标点。

检测模型与分割模型的自由组合

auto_annotate对模型组合非常宽容，可自由搭配两类预训练权重：

• 检测模型：可选 yolo26、yolo11、YOLOv8 等任意 Ultralytics 检测权重。模型越强、置信度阈值越准，SAM 阶段拿到的提示框就越可靠；
• 分割模型：可选 SAM（如sam_b.pt）、SAM 2（如sam2_b.pt）、MobileSAM（如mobile_sam.pt，体积小、CPU 友好）、SAM 3 等。精度要求高用 SAM 2 / SAM 3，追求吞吐和轻量部署用 MobileSAM。

这些组合在仓库文档中均有现成示例，例如 docs/en/models/mobile-sam.md 展示sam_model="mobile_sam.pt"的用法，docs/en/models/sam-2.md 展示sam2_b.pt的用法，docs/en/models/sam.md 与 docs/en/datasets/segment/index.md 则给出默认组合的完整说明。

与其他工具链的衔接

补充生成检测框标注

自动标注产出的是分割轮廓，若你的下游任务同时需要检测框标签（YOLO detect 格式的cls x_center y_center w h），可以配合segments2boxes函数把轮廓转换回归一化框，具体见 docs/en/usage/simple-utilities.md。

数据集质量复核

自动标注并非 100% 可靠，训练前强烈建议抽样可视化校验。Ultralytics 提供visualize_image_annotations工具（同样记录在 docs/en/usage/simple-utilities.md），可把标注框与类别名称叠加回原图以人工检查错标、漏标：

from ultralytics.data.utils import visualize_image_annotations label_map = {0: "person", 1: "car"} visualize_image_annotations("path/to/image.jpg", "path/to/image.txt", label_map)

与测试用例的对应关系

仓库在 tests/test_python.py 中内置了test_data_annotator集成测试：以yolo26n.pt检测 +mobile_sam.pt分割对示例图片资产批量自动标注并写入临时目录，验证了"YOLO 检测 + SAM 分割 + 同名 txt 落盘"整条链路的正确性。你可以参照它组织自己的最小复现脚本。

使用建议与注意事项

• device决定能否跑通：SAM 阶段对单张原始分辨率图做框提示分割，显存/内存占用通常高于检测阶段。小显存环境优先sam_model="mobile_sam.pt"并把device="cpu"；大图建议预先压缩或分批处理。
• max_det与imgsz影响召回：拥挤场景下若目标众多，默认max_det=300一般够用，但若检测框被 NMS 截断可适当调高；imgsz只影响检测阶段，SAM 精修仍在原始分辨率上进行，因此不必担心因缩小输入而损失 mask 细节。
• classes用于定向标注：只需标注部分类别（如仅 person）时传入类别 id 列表，SAM 只对保留的框生成 mask，可显著节省计算量。
• 类别 id 归属检测模型：输出的class_id取自det_model的预测结果，因此不要用任意 COCO 类别编号与目标任务混淆；若目标数据集类别不同，应在后续数据集整理阶段重新映射。
• 空图自然跳过：未检测到任何目标的图片不会生成.txt，整理数据集时需自行决定是否保留这些图片作为背景样本。

综合来看，auto_annotate把"检测出框 → 分割成面 → 归一化落盘"压缩成了一个函数调用，是快速构建分割数据集的实用起点；再叠加segments2boxes与visualize_image_annotations，就能同时覆盖检测框标签生成和质量抽检，形成一条完整的半自动数据生产链路。

【免费下载链接】ultralyticsUltralytics YOLO26, YOLO11, YOLOv8 — object detection, instance segmentation, semantic segmentation, image classification, pose estimation, object tracking项目地址: https://gitcode.com/GitHub_Trending/ul/ultralytics