CVAT图像标注工具安装与导出YOLO训练集实战指南

先说结论CVATComputer Vision Annotation Tool是一款开源的图像与视频标注工具前端基于React后端是Django PostgreSQL整套系统通过Docker Compose编排运行。我在自己工作站上先后帮团队搭过好几套版本从1.x一路折腾到现在的2.x踩过的坑基本能凑一篇长文。这篇文章就把从零安装、图片标注、再到导出成YOLO训练集的全过程写清楚包括那些报错和绕路的地方希望能帮你少走半天弯路。这篇文章适合正在准备计算机视觉训练数据集的算法工程师、数据标注团队负责人以及刚接触CVAT但不想看英文文档的开发者。无论你打算用它标目标检测框、分割多边形还是关键点整个流程都是通用的。如果你用的是VMware虚拟的Ubuntu环境同样适配但建议内存至少给8GB磁盘预留60GB以上否则后面跑容器会很吃力。1. CVAT到底是什么为什么值得折腾1.1 CVAT核心功能与适用场景CVAT本质上是一个围绕“标注”这件事打造的全流程平台。它不只是一个画框工具而是把任务管理、多人协作、数据存储、标注导出、模型预标注全链路打通。在一个团队里有人负责上传原始图片有人负责画框有人负责审核项目管理员可以实时看到每个人完成了多少任务这种协作模式比传统的“各自用LabelImg画完再合并”要高一个量级。功能上CVAT支持2D目标检测框bounding box、多边形分割、关键点、折线、3D点云标注还有视频跟踪标注。对做自动驾驶、安防、工业视觉场景的人来说3D点云和视频连续帧跟踪是刚需这也是为什么很多团队宁可多花点时间部署CVAT也不愿用轻量小工具。它还有自动标注功能可以接入自己训练的模型或者内置的深度学习方法先出一版粗标结果人工再做修正能把标注成本压缩到原来的三分之一。它的任务管理模型也很清晰项目Project下建任务Task任务下分多个作业Job标注员在作业里干活管理员实时审核。图片上传后系统会自动做切片一个任务几百张图不会卡前端页面用起来依然流畅。1.2 Docker Compose安装与原生安装的取舍安装CVAT目前主流有两种方式Docker Compose部署和原生Native安装。先说结论如果只是日常标注使用不是深度二次开发直接选Docker Compose省心程度完全不是一个量级。原生安装需要手动搞定Python环境、Node.js、PostgreSQL、Redis、RQLite、MinIO等一系列组件光是版本匹配就能折腾半天。CVAT后端是Django应用前端是React SPA构建时还得用Yarn处理一堆依赖任何一个组件版本不对就会出现诡异报错。我在1.x时代试过一次原生安装最后卡在RQLite迁移上拉了官方文档、翻了GitHub issue才解决前后花了两天。但Docker Compose方式也不是零成本它要求你懂基本的Docker操作知道镜像、容器、卷这些概念。如果你之前完全没接触过容器第一次看到十几个容器一起启动可能会懵。我建议你先花半小时跑一遍Docker官方快速入门再回来折腾CVAT会顺手很多。下面是两种方式的对比对比项Docker Compose原生安装环境隔离好组件互不干扰差依赖容易冲突安装速度快拉镜像即可慢需逐步编译安装升级维护改配置后一条命令重启容易升级失败二次开发需要额外配置挂载更方便直接改代码适合人群标注使用为主、运维小白准备改后端源码的开发者我个人的建议是第一套环境务必用Docker Compose即使后面要二次开发也可以在这个基础上加挂载目录改代码没必要一开始就挑战地狱模式。2. 从零开始的安装环境准备2.1 Linux环境与基础依赖CVAT官方推荐Ubuntu 20.04或22.04 LTS我用的是Ubuntu 22.04整体兼容性很好。其他Linux发行版也能跑但命令会有差异这篇文章以Ubuntu为准。装系统这一步不多说重点说一下装完系统后必须补齐的依赖。第一个是Git用于拉取CVAT源码直接执行sudo apt update sudo apt install -y git git --version第二个是Docker和Docker Compose插件。这里特别提醒CVAT新版本要求Docker Compose V2语法也就是docker compose命令旧版的docker-composeV1可能会在解析docker-compose.yml时直接报错。检查方法docker --version docker compose version如果Docker版本低于20.10建议直接卸载重装不要考虑升级系统源里的旧包。我踩过最大的坑就在这里当时工作站装的Docker 19.03CVAT的compose文件里用了新版语法启动时直接提示services.cvat_server.environment must be a mapping排查了半天才发现是Docker Compose版本太老。第三个是Python环境CVAT的迁移脚本、数据导出脚本很多需要Python 3.8以上。Ubuntu 22.04自带的Python 3.10够用不需要额外配置。但如果你后续要跑模型预标注最好装上Miniconda管理虚拟环境避免和系统Python打架。2.2 拉取CVAT源码与配置基础依赖准备好之后开始拉取源码git clone https://github.com/cvat-ai/cvat.git cd cvat进入目录后先复制一份环境变量配置cp .env.dev .env这里有个关键配置需要关注DJANGO_SECRET_KEY。CVAT用它来做Django签名和安全校验默认值是开发用的如果你部署在公网环境一定要改成随机字符串。生成方法很多可以用Pythonpython3 -c import secrets; print(secrets.token_urlsafe(64))然后把生成的值填到.env文件的DJANGO_SECRET_KEY后面。如果不改系统虽然能跑但存在安全风险尤其多人协作时别人拿到默认配置就能构造恶意会话。接着检查一下docker-compose.yml重点关注端口映射。默认服务跑在8080端口如果你想换端口找到services: cvat_server: ports: - 8080:8080把左边的8080改成你想要的端口比如9090:8080。如果你要用GPU跑深度学习预标注模型还要在cvat_server和cvat_worker_default服务下配置gpus: all否则容器内无法使用CUDA。2.3 踩坑记录镜像拉取慢、权限、容器启动失败这个环节是踩坑重灾区我把常见问题按顺序列一遍。第一类问题是镜像拉取超时或失败。CVAT的镜像比较大cvat_server单镜像就有好几个GB如果网络不稳定很容易拉到一半中断。解决思路是配置Docker可用的registry mirror。修改/etc/docker/daemon.json填入你所在网络环境下可用的镜像仓库地址然后重启Docker服务sudo systemctl restart docker配置好之后重新拉取速度会明显改善。还有个小技巧拉镜像时别傻等用docker compose pull按需拉取哪个失败了单独重试哪个比整体重来高效。第二类是Docker权限问题。如果你执行docker ps提示权限不足说明当前用户不在docker用户组里执行sudo usermod -aG docker $USER newgrp docker不解决这个问题后面所有compose命令都要加sudo很容易把文件权限搞乱。第三类是端口冲突。我遇到过8080端口被其他服务占用的情况启动时提示Bind for 0.0.0.0:8080 failed: port is already allocated。直接用sudo lsof -i:8080查占用进程杀完之后重新启动。如果你不想杀改端口映射更省事。第四类问题是启动后某个容器一直重启。用docker compose ps看到cvat_server显示Restarting立刻看日志docker compose logs -f cvat_server最常见的错误是cant open file manage.py或者ModuleNotFoundError这类多半是镜像没拉全或者版本不一致。先把旧容器清干净再重来docker compose down -v docker compose pull docker compose up -d注意-v会连数据卷一起删掉如果里面已经有标注数据不要随便加这个参数。3. 启动CVAT并完成初始配置3.1 一键启动与容器状态检查配置好之后在cvat目录下执行docker compose up -d第一次执行会拉取并创建所有容器包括cvat_server、cvat_worker_default、cvat_db、cvat_redis、cvat_minio等。整个过程看CPU和网速一般需要十到二十分钟。启动完成后检查容器状态docker compose ps看到所有服务状态都是Up并且没有持续重启的才算正常。然后打开浏览器访问http://localhost:8080如果页面能加载出CVAT的登录界面说明前后端服务都通了。这里要说一下CVAT的容器分工了解之后排查问题会快很多。cvat_server跑的是Django后端加API服务处理登录、任务管理、标注数据读写cvat_worker_default是后台任务队列负责图片预处理、自动标注模型推理这些异步任务cvat_db是PostgreSQL数据库存所有业务数据cvat_redis做缓存和消息队列cvat_minio是对象存储存原始图片和导出的数据集。这套架构和很多企业级应用类似理解了容器职责日志里报错你一眼就能定位到问题模块。3.2 创建管理员账号与登录CVAT登录界面有一个Create an account入口可以直接注册。但管理员账号建议用命令行创建因为后续管理标注员、查看全局任务都需要管理员角色。进入cvat_server容器执行docker exec -it cvat_server bash -c python3 manage.py createsuperuser按提示输入用户名、邮箱、密码。创建完成回到浏览器用管理员账号登录。登录进去之后右上角点你的用户名进入Admin页面可以在用户管理里添加标注员账号并分配角色。CVAT的角色分三层Admin管理员、User普通用户、Worker标注员。实际团队里项目负责人用Admin账号建项目建任务标注员用Worker账号干活普通User角色适合需要看数据但不能改任务的算法工程师。如果你给所有人都是Admin权限后期标注数据被误删、误改的风险会高很多。3.3 踩坑记录数据库迁移失败、账号无法创建、UI空白启动过程顺利的话到这里应该已经能登录了。但有几个问题很典型尤其多人同时部署时经常碰到。第一个是数据库迁移失败。执行up -d之后cvat_server日志里出现relation django_migrations does not exist之类的内容。这种一般是数据库还没初始化完而server容器已经尝试连接了。解决办法是等待cvat_db容器完全就绪后手动执行迁移docker exec -it cvat_server bash -c python3 manage.py migrate执行完重启server容器。注意CVAT部署时其实会自动跑迁移手动补跑只是兜底如果你自己再改过数据库配置迁移顺序更要对齐。第二个是账号创建后登录报错Invalid username or password。排查思路是先确认密码强度是否满足要求CVAT默认密码策略比较严格太短的密码会被Django直接拒绝。如果确认密码没问题再检查浏览器是不是自动填充了旧缓存清掉站点Cookie重新登录大部分问题能解决。第三个是前端UI加载出来但接口全部报错页面白屏。此时看浏览器F12控制台如果出现一堆401 Unauthorized大概率是管理员会话过期重新登录即可如果出现502 Bad Gateway说明cvat_server容器崩了或者还在启动中看docker compose logs -f cvat_server输出等容器完全起来再刷新页面。有几次我以为系统装坏了其实只是等待时间不够。4. 用CVAT完成一次图片标注任务4.1 创建任务上传图片登录进系统后左侧菜单有Projects、Tasks、Jobs三个模块。实际使用中我推荐先建Project再建Task这样不同任务可以共享同一套标签集合。在Projects页面点击Create a new project填写项目名称后在Label配置里加入你要用的标签比如person、car、bicycle。这里可以给每个标签设置颜色方便在标注时快速区分。标签配置是核心步骤后面任务里如果标签和项目对不上导出数据时类别会乱。建好项目之后进入Tasks页面创建任务。任务名称随意但建议包含数据批次信息比如20250115_road_camera_batch1方便后期管理。关联到之前建的项目后系统会自动继承项目的标签配置任务里不需要再重复添加。上传图片在任务详情页的Upload data区域。这里要注意文件大小限制CVAT默认限制单次上传文件总大小如果图片全是高清大图可能在服务端被拒。有两种解决办法一是把图片压缩或裁小二是调整docker-compose.yml里cvat_server的CLIENT_MAX_BODY_SIZE配置默认是15mb改成100mb再重启容器。上传完成后系统会自动创建若干Job每个Job包含一部分图片。标注员进入Jobs就能开始干活。4.2 标注界面与快捷键操作打开一个Job进入标注界面。左侧是工具栏有画框、画多边形、画关键点等工具中间是大画布右侧是标签列表和属性面板。新手最容易忽略的是快捷键但快捷键恰恰是提升标注效率的关键。我最常用的几个N新建标注目标按下后鼠标变成十字拖拽画框或画点CtrlS手动保存当前标注Esc取消当前正在绘制的目标CtrlZ撤销上一步Delete删除选中的目标Q隐藏/显示当前图片的所有标注操作流程是这样的选好标签类别在右侧标签列表里点击选中或者按数字键快速切换然后按N开始画框画完自动进入下一个目标的绘制状态。如果你连续标注同一类别不需要再切换标签直接N继续画就行。不同类别切换可以提前给标签绑定数字快捷键比如1对应person、2对应car这样全程键盘操作速度能翻一倍。CVAT默认每隔一段时间会自动保存标注结果但我在实际使用中还是养成了边画边按CtrlS的习惯。原因是有几次浏览器标签页崩溃重新打开后发现丢了最近几分钟的标注那种感觉真的很崩溃。自动保存不是万能的尤其在多人并发操作同一个任务时手动保存更稳妥。4.3 踩坑记录标签画错、属性面板消失、自动保存标注过程中有三个问题经常被问。第一个是画错标签怎么办。比如本来要标car结果标成了person。最简单的方法是选中这个标注框直接在右侧标签列表里点击正确标签类别就改了不需要删除重画。如果框的位置也不对用鼠标拖拽框的顶点调整比删除重画更快。如果整张图的标注都乱了可以按CtrlZ逐步撤销但撤销次数多了之后系统偶尔会卡顿我建议大范围错误时直接刷新页面CVAT会恢复到最近一次保存的状态。第二个是右侧属性面板突然消失。这通常是因为浏览器窗口宽度不够CVAT布局自动折叠了侧栏。把浏览器窗口拉大或者点击界面顶部的“属性”图标重新展开面板。如果还是没有按F5刷新页面属性面板会恢复默认布局。第三个是关于自动保存间隔的误解。很多用户以为CVAT像在线文档一样实时保存其实它是定时批量保存默认间隔大概几十秒到几分钟不等取决于后端配置和任务复杂度。如果你在自动保存的间隙关闭了浏览器这部分改动就丢了。所以工作流上我建议每标完一张图就按一次CtrlS养成肌肉记忆能避免绝大多数数据丢失问题。5. 导出标注结果并接入YOLO等模型训练5.1 导出格式选型COCO、YOLO、Segmentation mask标完数据之后进入任务详情页点击Export dataset按钮会弹出格式选择列表。列表很长比如COCO 1.0、Ultralytics YOLO、Pascal VOC、Segmentation mask等。初次接触的人很容易懵这里我给一个选型建议做目标检测YOLO系列用Ultralytics YOLO格式导出后直接是训练可用的图片加txt标注省去转码步骤做实例分割或关键点检测用COCO 1.0格式JSON结构完整适合用mmdetection或detectron2训练做语义分割用Segmentation mask格式会生成PNG掩码图COCO 1.0和Ultralytics YOLO对比YOLO格式每个图片对应一个同名txt文件每行内容依次是类别id x_center y_center width height坐标值都归一化到0到1之间。COCO格式则是一个超大JSON文件包含images、annotations、categories三大部分。两种格式各有优劣但如果你用的是Ultralytics的YOLO训练脚本直接导出YOLO格式最省事因为它连data.yaml文件都帮你生成好了训练时直接引用即可。5.2 从CVAT到YOLO训练集的实际流程导出Ultralytics YOLO格式后你会拿到一个zip压缩包。解压后目录结构大致如下dataset/ ├── data.yaml ├── images/ │ ├── frame_000001.jpg │ └── ... └── labels/ ├── frame_000001.txt └── ...data.yaml的内容类似这样train: images val: images nc: 2 names: [person, car]不过实际使用时train和val路径可能需要改成绝对路径或者在当前目录下运行训练脚本。另外你最好手动把图片划分一下训练集和验证集不要让train和val完全一样否则模型评估结果会虚高。我通常用Python脚本随机划分import os import random import shutil all_images os.listdir(images) os.makedirs(train/images, exist_okTrue) os.makedirs(train/labels, exist_okTrue) os.makedirs(val/images, exist_okTrue) os.makedirs(val/labels, exist_okTrue) random.shuffle(all_images) split_idx int(len(all_images) * 0.8) for img in all_images[:split_idx]: shutil.move(fimages/{img}, ftrain/images/{img}) label img.replace(.jpg, .txt) shutil.move(flabels/{label}, ftrain/labels/{label}) for img in all_images[split_idx:]: shutil.move(fimages/{img}, fval/images/{img}) label img.replace(.jpg, .txt) shutil.move(flabels/{label}, fval/labels/{label})然后修改data.yaml中的路径指向train/images和val/images接上Ultralytics YOLO训练命令就能开跑。5.3 踩坑记录坐标转换、类别顺序、空标签导出和训练阶段有几个细节特别容易翻车。第一个是类别顺序问题。CVAT的标签顺序取决于你在项目里添加标签的先后顺序导出YOLO格式后txt文件里的类别id就是这个顺序。如果你的训练脚本里model.names或data.yaml的names顺序与标签顺序不一致模型训练时会出现张冠李戴。所以在训练前一定先打开几个txt文件确认类别id对应的标签名再和data.yaml中的names对齐。第二个是坐标归一化问题。CVAT导出的YOLO格式坐标已经是归一化后的结果不需要你手工再除以图片宽高。但如果你导出的是COCO格式坐标是像素值转YOLO时才需要做归一化。有人拿COCO格式直接套YOLO训练脚本结果损失函数爆掉原因就是坐标范围完全不对。所以导出时选对格式比后期转换省事得多。第三个是空标签问题。有些图片可能没有任何目标导出的txt文件是0字节空文件。如果图片出现在验证集里某些检测框架会直接跳过它但有些框架会报错。检查方法是对比images和labels目录下的文件数量不一致就找到缺失的对应关系手动处理。我一般会在数据清洗阶段直接把空标签图片从训练集里剔除避免训练时报奇怪的错。6. 团队协作与日常维护的进阶建议6.1 多账号与权限管理当标注量变大一个人标不完就需要给团队分配账号。在Admin页面创建的用户默认是普通User你可以给标注员赋予Worker角色这样他们只能操作分配到的任务看不到项目全局设置也不能修改标签体系。项目管理员用Admin账号把任务通过Jobs页面分配给具体标注员不要让人自己去所有任务里挑活否则协作记录会乱。在多人同时标注同一批数据时协作规范很重要。我见过最典型的混乱两个人在同一张图片上做了不同版本的标注任务提交后管理员发现重复标注数据导出后类别数量翻倍。CVAT虽然支持任务锁定但默认没有强制限制所以我的建议是每个Job只分配给一个人管理员审核通过后再整理汇总。如果团队规模大还可以用CVAT的组织管理功能按业务线划分不同组织数据和标签完全隔离互不干扰。6.2 数据备份与容器日常运维CVAT用起来之后数据全在Docker卷里如果不做备份哪天磁盘坏了或者误删容器标注成果就全没了。数据库备份是核心CVAT的业务数据全部在PostgreSQL里。备份命令docker exec -it cvat_db pg_dump -U postgres cvat backup.sql还原时docker exec -i cvat_db psql -U postgres -d cvat backup.sql图片和导出的数据集默认存在MinIO对象存储里备份时可以连同cvat_minio的卷一起备份。最简单的做法是把整个/var/lib/docker/volumes目录定期复制到另一台机器但前提是容器处于停止状态或数据一致状态。日常运维最需要关注的是磁盘占用。CVAT运行时间长了日志文件、临时文件、缓存会越来越大尤其cvat_server容器日志如果长期不清理一个文件能膨胀到几十GB。建议给Docker配置日志轮转在/etc/docker/daemon.json里加{ log-driver: json-file, log-opts: { max-size: 50m, max-file: 5 } }重启Docker后生效。这个配置能省掉很多麻烦别等日志把磁盘塞满才开始处理。6.3 常见问题速查表按我这么多年实战经验把高频问题整理成速查表遇到直接对照着查现象可能原因解决方案启动后cvat_server不停重启数据库迁移未完成或Docker版本过旧看日志执行migrate再重启上传图片失败提示文件过大服务端body大小限制改CLIENT_MAX_BODY_SIZE后重启标注保存后刷新丢失自动保存间隔未到或浏览器崩溃养成手动CtrlS习惯导出YOLO格式后类别对不上项目标签顺序与训练脚本names不一致核对data.yaml与txt文件类别idUI白屏接口返回502cvat_server未完全启动或崩溃看server日志等待或重启多人同时标同一任务冲突同一Job分配给了多个人恢复单人单Job分配策略除了表格里的再补充一个我最近才处理的问题换了网络环境后cvat_minio容器一直报连接错误。查了半天发现是MinIO的访问密钥和.env里的配置不一致因为之前重置容器时数据卷保留了旧密钥而.env被重新生成过。解决办法是删掉MinIO的容器和卷重新初始化docker compose rm -sf cvat_minio docker volume rm cvat_cvat_minio_data docker compose up -d注意这个操作会把已上传的图片备份清掉所以操作前先确认MinIO里没有重要数据。还有一个经验分享CVAT版本更新比较频繁新版本修复边界情况和性能问题很积极。每次升级前先备份数据库和MinIO数据卷再执行git pull docker compose up -d如果升级后遇到奇怪问题回退版本比排查要快得多。我目前稳定使用的是2.x系列整体性能和稳定性比1.x时代提升了一个档次尤其大分辨率图片标注的流畅度改善明显。最后再说一个很多人问的点CVAT不只是能标图片视频标注同样支持。上传视频后系统会自动抽帧你可以用插值标注的方式标关键帧中间帧自动拟合。我们团队做视频目标跟踪数据集时就是这么干的效率比逐帧标注高出好几倍。如果你有视频标注需求CVAT确实是个值得花时间研究透彻的利器。