自动标注三件套：Grounded-SAM、autodistill、X-AnyLabeling 实战-平芜编程栈

标注工作最磨人的不是画框这个动作本身，而是“重复、量大、还得保证质量”。我去年把整套标注流程彻底重写了一遍，从原来靠人在 X-AnyLabeling 里一张张手工拉框，到后来引入 Grounded-SAM 自动出掩膜、再用 autodistill 做主动学习迭代，整个数据生产线才算真正转起来。这篇文章就把这条链路完整拆开来讲，包含环境搭建、提示词设计、批量跑图、人工校验、格式转换和各类翻车实录，适合正在做目标检测、实例分割数据集，或者被标注成本压得喘不过气的算法工程师、数据工程师参考。

1. 整体思路：三件套各管一段，组合成一条自动标注流水线

1.1 为什么是这三个工具

先理清一个认知：市面上没有任何单一工具能包办“自动标注”这件事。自动标注本质上是一条流水线，至少需要三个环节：自动生成粗标注、模型辅助迭代标注、人工精修兜底。我把这块拆成三件套，对应关系非常明确。

Grounded-SAM：负责“从零生成粗标注”。它把 GroundingDINO 的文本检测能力和 SAM 的分割能力串起来，只要输入一句“car. person. traffic light.”，就能输出相应的检测框和分割掩膜。它的价值在于零样本、开箱即用，不用先准备训练集。
autodistill：负责“用小模型跟上大模型的节奏”。Grounded-SAM 这种大模型推理速度慢，大批量跑图跑不起，而 autodistill 的核心思路是用大模型当 teacher，先自动标注一批数据，再训练一个小模型当 student，之后让小模型接手大部分推理工作，形成主动学习闭环。
X-AnyLabeling：负责“人工精修与格式落地”。自动标注出来的结果永远带瑕疵——漏检、误检、边缘毛糙、类别错位，必须有一个顺手的工具让人快速修正。X-AnyLabeling 内置了多种模型推理引擎，支持交互式分割、半自动标注、关键点标注，还能直接导入导出 YOLO、COCO、VOC 等格式，是流水线最后一道闸门。

这三个工具在职责上几乎没有重叠，刚好组成一个金字塔：Grounded-SAM 是地基，autodistill 是自动化的加速器，X-AnyLabeling 是质量控制的终结者。

1.2 整体标注流程长什么样

用一个实际项目的执行顺序来说明，更直观。假设我要做一个“街边小物体检测”数据集，类别包括“椅子、雨伞、自行车、垃圾桶”四类：

先用 Grounded-SAM 在原始图片上跑一轮文本提示词，自动生成包含 bbox 和 mask 的标注文件。
把 Grounded-SAM 的输出导成 COCO JSON 格式，喂给 autodistill，用它训练一个 lightweight student 模型（比如 YOLOv8n）。
再用 student 模型对另一批未标注图片做批量预测，把置信度低的样本挑出来，交给人工精修。
最后把所有这些结果放进 X-AnyLabeling，由标注员用快捷键逐张核验、删改、补漏，导出最终数据集。

这套流程的精髓是“把人的精力只放在疑难样本上”。高质量样本让模型自动过，低质量样本才需要人去处理，标注成本能压缩到原来的三分之一甚至更低。

2. X-AnyLabeling：安装、配置与快捷键体系

2.1 环境搭建与 Linux 注意事项

X-AnyLabeling 有两种常见装法：直接下 release 包，或者源码编译。Windows 用户直接去官方 GitHub release 下载编译好的压缩包，解压即用。但 Linux 下不能靠一个二进制包走天下，得手动处理依赖链。我是在 Ubuntu 22.04 上搭建的，踩了几个坑后总结出一套稳定的安装路径。

# 1. 先创建独立的 conda 环境，避免和系统 Python 打架 conda create -n anylabeling python=3.10 -y conda activate anylabeling # 2. 安装 PyQt5 基础依赖 sudo apt update sudo apt install libgl1 libglib2.0-0 libsm6 libxext6 libxrender1 \ libgomp1 libegl1 mesa-utils -y # 3. 克隆源码并安装 git clone https://github.com/vietanhdev/anylabeling.git cd anylabeling pip install -r requirements.txt python anylabeling/app.py

Linux 上最容易踩的坑有两个。第一个是 libGL.so.1 缺失，PyQt5 和无头显卡环境经常遇到，启动时报ImportError: libGL.so.1: cannot open shared object file，执行sudo apt install libgl1就能解决。第二个坑是 OpenCV 版本冲突，如果系统里已经装了 opencv-python-headless，而 anylabeling 依赖的是完整版 opencv，两边的视频解码后端会互相干扰，典型的症状是导入图片正常、打开视频异常。处理方法很简单：先卸载 headless 版本，再重装普通版。

pip uninstall opencv-python-headless -y pip install opencv-python==4.8.1.78

注意：X-AnyLabeling 对 torch 的版本没有硬性要求，但如果你要用内置的 SAM 模型做交互式分割，建议单独装一个 torch 环境，不要把 torch 装进 anylabeling 的 conda 环境里，否则每次启动程序都要等 torch 加载，光是初始化就慢 20 秒。我习惯把 anylabeling 保持轻量，需要跑模型时直接调用命令行推理脚本，两边互不干扰。

2.2 快捷键体系：提效的核心武器

X-AnyLabeling 的快捷键设计，是我见过那么多标注工具里比较合理的。它不只是“画框快”，而是把“画框、切图、查漏、改错”整套动作都做成了单手操作。最常用的几组我列出来：

操作目的	快捷键	说明
画矩形标注	`W`	按一次进入画框状态，拖动即可
画多边形标注	`P`	适合精细轮廓标注，点一次加一个顶点
智能分割	`D`	激活内置 SAM / YOLOSAM，单击目标即可出掩膜
切换下一张图	`D`或`N`（按工具版本略有差异）	我常用`D`，确认当前图后立即切下一张
删除当前标注	`Ctrl+D`/`Delete`	删除当前选中的框或多边形
撤销上一步	`Ctrl+Z`	误操作兜底，画错顶点赶紧撤销
复制标注到下一张	`Ctrl+C`/`Ctrl+V`	视频帧或相似场景下能省一半时间
放大缩小画布	`+`/`-`	看细碎小目标时非常关键
自适应窗口	`F`	一键回到全局视图，方便对比前后帧

我实测下来，效率最高的操作组合是：W 画框 → D 切下一张 → W 画框，这个循环里右手完全不需要离开鼠标，左手配合快捷键切图，每小时处理的图片数量比纯手工画框高两到三倍。

还有一个被很多人忽略的功能：形状复制粘贴。在连续帧标注中（比如视频抽帧的数据集），物体往往只在原位置做轻微移动，我通常是第一帧画好框，第二帧直接 Ctrl+C / Ctrl+V 粘贴，再轻微拖拽调整位置。这种“先复制再微调”的打法，比每帧重新画效率高得多。

2.3 内置 AI 推理引擎的正确打开方式

X-AnyLabeling 最亮眼的设计是内置了一批推理引擎，包括 YOLOv8、YOLOv5、SAM、MobileSAM、RT-DETR 等，可以不写代码直接在软件里跑模型推理。但我不建议一上来就把所有模型都加载一遍。我的实际使用原则是：

日常画框场景：只加载一个小型模型（比如 yolov8n），用于“AI 辅助自动画框”。点击模型后，工具会先在后台对所有目标出框，标注员只需要核验是否有漏检和误检。
精细分割场景：才切换 SAM 系列模型。SAM 靠单击提示词就能分割出目标轮廓，适合做实例分割数据集，但推理速度慢，不能全程开着。

我的经验是：先让内置模型预标注，再人工逐张检查，而不是直接信任模型的全部输出。模型出的框有个规律：大类目标很准，小目标和遮挡严重的漏检率高。人工检查的节奏就是把漏检补上、把误检删掉，而不是从零开始画。

3. Grounded-SAM：从文本提示到自动掩膜

3.1 环境搭建与权重准备

Grounded-SAM 并不是一个独立模型，它是“GroundingDINO + SAM”的组合流水线，官方仓库也明确说明需要分别准备两个模型的权重。环境搭建我建议直接用官方给的environment.yml，或者自己用 conda 控制依赖版本。

git clone https://github.com/IDEA-Research/Grounded-SAM.git cd Grounded-SAM conda env create -f environment.yml conda activate grounded-sam python -m pip install -e .

权重文件方面需要准备两个：

GroundingDINO 权重：从官方仓库 release 下载，我使用的是groundingdino_swint_ogc，适合通用目标检测。如果你有特定场景，可以选用经过微调的 checkpoint。
SAM ViT-H 权重：从 SAM 官方仓库下载sam_vit_h_4b8939.pth。如果显卡显存不够，也可以用 ViT-B / ViT-L 版本，但分割精细度会略降。

启动推理可以用官方示例脚本，但官方脚本只处理单张图片。对大规模批量标注来说，我更建议写一个简单的 shell 循环，把图片一张张喂进去，并自动记录耗时和输出路径。

3.2 提示词模板设计：一句话决定标注质量

Grounded-SAM 的检测效果，很大程度取决于提示词的写法。我总结出的经验是：提示词不是越短越好，也不是越长越好，而是要覆盖“类别范围 + 排除歧义”。

以“车辆”这个大类为例，我的提示词写作方式对比：

提示词	效果	说明
`car`	只检出小轿车，卡车、公交车全部漏掉	过窄
`vehicle`	可能检出部分但不是全部	通用词在 GroundingDINO 上表现不稳定
`car. truck. bus. motorcycle. bicycle.`	各类别都能稳定检出	推荐
`a photo of a car, truck and bus`	部分类别丢失	句子结构可能干扰 DINO 的 grounding 能力

关键规律是：每个类别用单独的点号隔开，不要人为加复杂定状语句。GroundingDINO 的文本编码器对“名词短语”的响应最好，你用自然语言描述反而会稀释它的注意力。

提示词中尽量加入场景限定词。比如做街景标注时，提示词写成pedestrian on the crosswalk. chair on the sidewalk.比直接写person. chair.效果更好，因为 GroundingDINO 在复杂场景下容易把小的人影或远处的斑马线误判为目标。

3.3 批量跑图与输出解析

我设计了一套批量跑图的脚本模板，核心思路是每隔几张图自动保存一次结果，方便中断续跑。

#!/bin/bash # 批量跑 Grounded-SAM 标注脚本，图片放在 ./images 中，结果输出到 ./labels IMG_DIR="./images" OUT_DIR="./labels" mkdir -p "$OUT_DIR" for img in "$IMG_DIR"/*.jpg; do echo "Processing: $img" python grounding_dino_sam_inference.py \ --config GroundingDINO/groundingdino/config/GroundingDINO_SwinT_OGC.py \ --grounded_checkpoint ./weights/groundingdino_swint_ogc.pth \ --sam_h_checkpoint ./weights/sam_vit_h_4b8939.pth \ --input_image "$img" \ --output_json "$OUT_DIR/$(basename "$img" .jpg).json" \ --prompt "car. person. traffic light. bicycle. motorcycle." sleep 1 done

跑出来的 JSON 里，核心字段有两个：boxes和masks。boxes 是 xyxy 格式的检测框，masks 是 RLE 编码的分割掩膜。注意不要直接用这个 JSON 当数据集，还得转换一次。我的习惯是先把 RLE 掩膜解码成 PNG 透明图，再转成 COCO JSON，这样后道工序的校验工具和训练脚本都能通用。

批量跑图的节奏也有讲究。Grounded-SAM 跑单张 1024x1024 的图片，在 RTX 3090 上大约需要 2-3 秒，一张一张跑问题不大。但如果图很多，可以开多进程并行，每个进程指定不同的 GPU，速度几乎线性提升。跑任务前先随机挑 10 张测试一下推理结果，确认提示词没有大问题再全量跑，否则 2 万张图跑完才发现类别错位，就得全部重来。

4. autodistill：用主动学习让标注量持续下降

4.1 autodistill 的工作原理

autodistill 是一个很有意思的框架。它的核心机制是：用一个大模型当 teacher，自动标注未标记数据，然后训练一个小模型当 student。它的思想非常朴素：

如果一个大模型已经能把任务解决得很好，那我何必用昂贵的人力去标注？直接让大模型生成标签，然后让一个小模型去学习大模型的泛化能力，最后在推理阶段用小模型替代大模型，速度和成本都能大幅下降。

这个框架支持把 Grounded-SAM、YOLO-World 等模型当作 teacher，也支持把 YOLOv8、YOLOv5 等模型当作 student。安装非常简单：

pip install autodistill autodistill-grounded-sam autodistill-yolov8

4.2 一个典型的主动学习迭代流程

我实际跑过的完整流程是这样的：

初始化：准备 5000 张无标注图片。
Teacher 标注：用 Grounded-SAM 把 5000 张图片全部自动标注，导出 COCO JSON。
Student 训练：用 autodistill 把标注结果转成 YOLOv8 格式，训练一个 yolov8n 模型。
Student 推理：用训练好的小模型对下一批 5000 张图做推理。
置信度过滤：小模型输出的检测框若置信度高于 0.9，直接视为可信标注；置信度在 0.5 到 0.9 之间，进入人工精修；低于 0.5 的，大概率是错检或漏检，要么删掉，要么进人工资重新标注。
重复训练：把人工修正过的数据合并到训练集，训练下一个版本的 student 模型。

到第二轮后，十之八九的图片已经可以直接用 student 模型的输出，不再需要经过 Grounded-SAM 或人工，标注成本直线下降。

这一步有个非常重要的量化衡指标：我建议每次迭代后记录“student 模型自动标注的可信率”。如果第一轮是 60%，第二轮升到 80%，说明主动学习生效了；如果提升很慢，大概率是类别体系设计有问题，或者标签噪声太大，需要回头检查 teacher 的标注质量。

4.3 autodistill 的实操经验与回灌机制

autodistill 的 API 设计简洁，但有个地方容易踩坑：默认只支持 maximal 的检测框输出，mask 信息会被丢弃。如果后续做实例分割任务，需要在 grounded-sam 的模块里额外保留 mask 数据，或改用直接调用 Grounded-SAM 底层接口。

autodistill 训练出来的标签怎么回灌进 X-AnyLabeling？我习惯的做法是：

autodistill 训练后，用 student 模型对未标注图片批量预测，输出为 YOLO txt 格式。
进入 X-AnyLabeling 前，先把 YOLO txt 转成 X-AnyLabeling 支持的标签文件。转换的原理很简单：X-AnyLabeling 的标准格式是一个图片对应一个同名.txt（YOLO 分割格式）或者在labels目录下的 JSON 文件，把类别编号和归一化坐标填对就行。
在 X-AnyLabeling 里对自动标注结果进行人工修改，保存后重新导出成 YOLO 格式，回到训练集。

我最开始的理解是 autodistill 能完全替代人工校验。但实测后我发现它替代的是“画标注”这个动作，替代不了“查缺补漏”这个动作。低置信度的样本永远需要人来看，而自动标注的价值是把人从 100% 的工作量压缩到 15%，而不是压缩到 0%。

5. 实战流程：从原始图片到最终可用数据集

5.1 设定标签体系

标签体系设计直接影响整个标注流程的体验。我在做自动标注项目时，总结出一条核心准则：类别尽量合并，避免过度拆分。比如做车辆检测，car和sedan不要拆成两类；做动物识别，dog和puppy也不要拆。因为 Grounded-SAM 对细粒度的类别区分能力有限，拆得太细，模型和人都容易混淆，标签噪声指数级上升。

标签体系设计完成后，我建议先在 X-AnyLabeling 里手动标注 50 张图作为“标准答案”。这个标准答案集有三个用途：一是验证标签体系是否合理；二是用来测试自动标注工具的输出质量；三是作为后续人工精修时的参照模板。

5.2 数据准备与目录组织

数据集目录结构我建议这样组织：

dataset/ ├── images/ # 原始图片 │ ├── train/ │ ├── val/ │ └── test/ ├── auto_labels/ # 自动标注结果（Grounded-SAM / autodistill 输出） │ ├── train/ │ ├── val/ │ └── test/ ├── human_labels/ # 人工精修后的最终标注 │ ├── train/ │ ├── val/ │ └── test/ └── scripts/ # 中间转换脚本

图片统一命名规则很重要。我踩过最大的坑是：从不同渠道收集的图片，文件名可能是中文、包含空格，甚至同一张图被重复命名。自动标注脚本基于文件名映射标签，一旦文件名搞混，后期合并数据时整个数据集直接报废。我的做法是进数据集之前统一改名为 8 位数字 + 短横线编号，比如00000001.jpg，彻底规避编码问题。

5.3 一次完整的端到端实操演示

以下是我这边跑通的一个“零样本标注 + 主动学习 + 人工校验”的完整流程记录：

任务：给 8000 张无人机航拍的工地图片，标注person. helmet. excavator. truck.四类。

第一步：Grounded-SAM 自动标注。我写的提示词是：

person. helmet. excavator. truck.

跑完后生成了 8000 个 JSON，耗时约 6 小时（单卡 RTX 3090）。

第二步：转换格式。写一个 Python 脚本把 JSON 转换成 YOLO 格式，过滤掉面积过小的框（比如小于 2% 图片面积的目标，基本都是误检），再输出为 COCO JSON 和 YOLO txt 双份格式。

第三步：autodistill 训练 student。这个环节我提前把 Grounded-SAM 标注结果转成了 autodistill 的输入格式，然后训练 yolov8n，大概 20 分钟一个 epoch，跑 50 个 epoch，得到一个 mAP 50 约 0.65 的小模型。

第四步：student 模型继续生产。用这个模型对新收集的 5000 张未标注图片推理，统计置信度分布。置信度 >0.9 的占比约 35%，0.5-0.9 占 45%，低置信度占 20%。

第五步：X-AnyLabeling 人工精修。把低置信度的 1000 张图、中置信度的 2250 张图抽样 10% 放进标注工具人工修改，再回灌到训练集。这一步用快捷键组合，两个人两天就完成了。

最终，这个 13000 张的数据集，人工实际参与精修的只有大概 2600 张图，有效人工工时压缩到原先的 20% 左右。

5.4 格式转换脚本要点

格式转换是数据链路里最容易翻车的环节。三种常见格式的转换关系如下：

Grounded-SAM 的 JSON：包含 xyxy 框与 RLE 掩膜，需要解码成 numpy 掩膜数组，才能转成其他格式。
COCO JSON：需要维护一个categories列表，并且支持一个目标多标签或遮挡的复杂度，适合做实例分割。
YOLO txt：每行一个目标，格式是类ID x_center y_center width height，值均为归一化到 0-1 的浮点数。

我提供一段我常用的转换脚本，能直接把 Grounded-SAM 的检测结果转成 YOLO 分割格式：

import json import numpy as np import pycocotools.mask as mask_util from pathlib import Path def grounded_sam_json_to_yolo(json_path, class_mapping, out_txt_path, img_w, img_h): with open(json_path, "r") as f: data = json.load(f) lines = [] for item in data["annotations"]: category = item["category"] if category not in class_mapping: continue class_id = class_mapping[category] # mask 是 RLE 编码，解码为多边形 mask = mask_util.decode(item["mask"]) ys, xs = np.where(mask > 0) if len(xs) == 0: continue # 计算掩膜的外接多边形，这里简化为外接矩形归一化 x1, x2 = xs.min(), xs.max() y1, y2 = ys.min(), ys.max() box_w, box_h = x2 - x1, y2 - y1 x_center = (x1 + x2) / 2 / img_w y_center = (y1 + y2) / 2 / img_h w, h = box_w / img_w, box_h / img_h lines.append(f"{class_id} {x_center:.6f} {y_center:.6f} {w:.6f} {h:.6f}") with open(out_txt_path, "w") as f: f.write("\n".join(lines))

这段脚本的简化处理是把掩膜变成外接矩形，这在大规模自动标注中完全可以接受。如果需要精细分割标签，则要输出多边形顶点序列，代码量会更大，但原理相同：先解码掩膜，再用cv2.findContours提取多边形轮廓。

6. 常见问题与避坑实录

6.1 内存爆掉与推理速度慢

自动标注流水线最容易崩的环节是 Grounded-SAM 批量推理。SAM 模型非常吃显存，ViT-H 在 8GB 显存下基本跑不了 1024 分辨率以上的图，会直接 OOM。我的解决思路是：

降低输入分辨率。对标注任务来说，大部分目标在 640 分辨率下依然清晰，把图片 resize 到 640x640 后再喂给模型，显存占用能降一半以上。
开启半精度。fp16 推理在显存占用上提升明显，精度损失对于标注任务基本无感。
分批处理。不要一次性把几千张图塞进内存，而是每处理 100 张输出一次结果，中间清理显存缓存。

另一个容易忽略的内存问题是 X-AnyLabeling 自身。当一张图片分辨率特别大（比如 5000x3000 的航拍图），工具加载时会很卡。我的建议是先把大图切瓦片，分块标注，再合并回整图，或者先下采样到 2000 像素再标注。

6.2 漏检与误检：自动标注结果质量问题

漏检和误检永远是自动标注最核心的问题，我的处理经验分两层：

漏检的修正：漏检多发生在小目标、遮挡目标和远处目标。处理办法是加跑一遍针对小目标的提示词轮次，比如把图片放大 1.5 倍后再跑一次 Grounded-SAM，然后合并两次结果。如果还是漏，说明是类别本身与背景对比度太低，这类样本只能靠人工补。

误检的清理：误检的典型特征是置信度偏低、目标尺寸偏小或尺寸过大。我在转换脚本里加入了基于面积的过滤规则：目标面积占图片面积 0.5% 以下或 95% 以上，直接丢弃。这个规则能过滤掉大部分把纹理背景误判成目标的情况。

注意：过度的面积过滤会把真正的小目标一并删掉。实际项目里我会先跑一个统计脚本，输出所有检测框的面积分布，看一眼数据分布再设定过滤阈值，而不是拍脑袋定 0.5%。

6.3 标签管理混乱：类别ID与标签名错位

这是多人协作时最严重的坑。自动标注输出的类别顺序和 X-AnyLabeling 的类别顺序不一致，训练时类别 ID 就会错位，看起来模型训练正常，实际 ap 计算出来全是零。

我的解决办法是用一个统一的classes.txt，并且把它固定在数据集根目录，所有脚本和工具都从这个文件读类别列表。任何工具、任何脚本、任何中间层都不允许自己另写一份类别清单。这样即使标注过程跨多个平台，类别顺序也完全可控。

6.4 中文路径与文件编码问题

很多标注工具和深度学习框架对中文路径支持不友好，Windows 上尤其明显。如果数据集路径里包含中文或特殊字符，轻则程序报警告，重则直接无法读取图片或保存标注。我的铁律是：数据集根目录和所有子目录只用英文字母、数字、下划线。个人头像里那些稀奇古怪的字符就别拿来做数据集了。

还有一个我踩过的坑：某些自动标注脚本生成的 JSON 里包含 Unicode 转义字符，在 Linux 上看是\uXXXX，用 Python 读取没问题，但用记事本打开就是乱码。遇到这种情况不要手动改文件，直接在转换脚本里用ensure_ascii=False处理输出。

6.5 快捷操作反人类？重新绑定

X-AnyLabeling 允许自定义快捷键。默认的D键既是“智能分割”又是“下一张图”（取决于当前是否处于编辑状态），这经常让我刚画完一个框就误跳到下一张图。我的解决思路很直接：进入设置面板把智能分割改为S，把下一张图保留为D，这样手指分布的肌肉记忆更舒服。

还有一个高效技巧：开启“自动保存”后，切图时会自动保存当前标注，但手动Ctrl+S仍然保险。因为自动保存偶尔会遇到图片加载失败的情况，这时未保存的标注会丢失，手动保存能在关键时刻兜底。

这套三件套组合的强势之处不在于任何单一工具，而在于“大模型自动标注 + 小模型迭代 + 人工只处理难点”的循环结构。我在实际项目里最大的感受是：技术选型不难，难的是把每个环节的数据流打通，让标注结果能顺畅地从一个工具流向另一个工具，任何一个环节出现格式断层，整条流水线就卡死。如果你也想引入自动标注，我建议先拿几百张图小规模跑通全流程，确认标注质量、成本、工具稳定性都达标后，再放心铺开到全量数据。