1. CVAT到底是什么为什么标注工具这件事被严重低估了先说结论CVATComputer Vision Annotation Tool是英特尔开源的在线视频和图像标注工具也是一个真正意义上把“标注”这件事做成工业化流水线的平台。如果你做计算机视觉相关的工作不管是目标检测、图像分割、关键点检测还是视频跟踪类任务日常大概率逃不开标注这个环节。我最早接触CVAT是帮团队做一批行人重识别数据的标注当时用labelImg一张张拉框拉到怀疑人生后来换到CVAT才意识到标注工具之间的差距比我想象中大得多。CVAT解决的问题表面上看是“让人能画框”但往深处拆它解决的其实是三件事标注效率、标注质量、以及标注任务的协同管理。早期单人标注随便找个工具就能干但一旦标注人员有多个、标注标准需要统一、数据需要版本管理、任务需要分配和验收普通的桌面级标注软件就撑不住了。CVAT把标注任务拆成“任务—作业—标注—审核—导出”这样一个完整闭环配合RBAC权限模型可以直接按标注员、审核员、管理员三种角色划分权限。这一点在项目稍微正规一点之后价值会体现得特别明显。另一个被低估的地方是CVAT对“辅助标注”的支持。它不是让你从零开始对着空白图画框而是可以接深度学习模型的推理结果做预标注标注员只需要微调位置、修正类别。官方也提供了模型加载通道比如通过Intel OpenVINO或者自己写的推理API做自动标注。实测下来对于场景相对固定的数据辅助标注能把标注速度提升3到5倍这个提升不是体感上的是真实能算出来的。再说说CVAT的适用范围。它支持图像分类、目标检测矩形框、多边形分割、关键点、线段、以及视频帧序列的跟踪标注基本覆盖了主流视觉任务。数据格式方面支持COCO、Pascal VOC、YOLO、TFRecord等常见协议模型训练完之后的数据导出基本上不需要写额外的转换脚本。正是因为这个覆盖面足够广所以不管是做安防、工业质检、自动驾驶场景还是做学术研究CVAT都能作为标注侧的主力工具接入流程。2. 本地部署的真实动机和落地之前必须想清楚的几件事2.1 为什么很多团队选择本地部署而不是直接用云版本网上关于CVAT部署的教程不少但大部分是把Docker命令粘贴一遍就完事很少讲清楚“为什么要本地部署”这件事。我先把动机聊透因为这直接决定你要不要花几天时间去折腾它。官方其实提供了在线体验版app.cvat.ai注册个账号就能用。但对多数做实际项目的团队来说数据安全是绕不开的红线。训练数据一旦传到第三方平台上不管是保密协议还是公司内部合规都过不了。尤其是做工业、医疗、军工相关项目的朋友数据出内网这件事本身就是重大事故。本地部署的最核心动机就是数据完全在自己的服务器上流转训练数据不出内网。另一个动机是和内网已有的资源打通。很多团队的训练服务器上本来就挂着GPU资源、已经有自己训练的模型服务。把CVAT部署在同内网环境里它可以直接调用内网里的推理模型做预标注走内网带宽速度和安全性都有保障。这个优势在云端方案上是很难复制的。2.2 部署之前需要确认的硬件和软件条件先泼一盆冷水CVAT不是随便找个低配机器就能顺畅跑的。它的组件里有PostgreSQL、Redis、Django后端还带一套基于React的前端以及一个专门跑自动标注任务的worker进程。全部服务加起来对内存的消耗很可观我最早一次部署给了4G内存的机器结果光依赖服务就把内存吃满了页面直接卡成PPT。结合社区里的实践和我自己的试错硬件需求可以分两个档位使用场景CPU核心数内存存储是否需要GPU单机学习、小团队试用4核8G100G可用不需要中大型团队正式使用8核以上16G以上500G以上建议有需要说明的是GPU不是必选项。如果只做纯手工标注CPU跑核心服务就够了但如果要用模型辅助标注建议至少有一张支持CUDA的N卡。CVAT的自动标注worker可以通过OpenVINO在CPU上跑部分模型但速度不太理想用GPU才会有实用性。软件层面其实很省心因为CVAT本身是Docker容器化部署宿主机只需要装好Docker和Docker Compose插件。如果你用Linux系统我建议用Ubuntu 20.04以上版本。Windows环境也能跑但文件权限和路径挂载的坑比较多对于新手我强烈建议用Linux。2.3 版本选择推荐用docker-compose而不是手动搭组件CVAT官方提供了两种部署思路一是用现成的Docker Compose编排另一种是手动安装所有依赖组件然后跑源码。想都不用想直接用Docker Compose。手动部署意味着你要自己搞定PostgreSQL数据库初始化、Redis缓存配置、Django的migration、静态文件收集、HTTPS证书等一系列步骤光这些就能消耗掉一到两天时间而且几乎每次都会踩到不一样的坑。通过Docker Compose所有组件都由编排文件统一管理日志、网络、持久化存储都集中在一个命名空间里重装、升级、回滚都方便得多。后面我会把具体步骤写清楚。3. 使用Docker Compose部署CVAT的完整实操步骤3.1 第一步安装Docker和Compose插件如果你在Ubuntu上从零开始部署先把基础环境准备好。这一步不复杂但有两个细节容易踩坑。一是Docker的apt源如果用官方源国内服务器拉取会非常慢建议装完Docker之后立刻配置国内镜像加速器。二是Docker Compose v2是作为插件存在的命令是docker compose中间有空格和老的docker-compose命令不是同一个东西。CVAT官方的部署脚本在v2版本下运行更顺。基础安装命令如下# 更新系统包 sudo apt update sudo apt upgrade -y # 安装依赖 sudo apt install -y curl git # 安装Docker使用官方脚本国内建议配代理 curl -fsSL https://get.docker.com | sudo sh # 将当前用户加入docker组避免每次sudo sudo usermod -aG docker $USER # 安装Compose插件 sudo apt install -y docker-compose-plugin # 验证安装 docker --version docker compose version这里提醒一句usermod加组之后需要重新登录终端才生效别以为配完没反应就是出错了。用id命令看到docker组身份后就可以继续。3.2 第二步获取CVAT源码和配置环境变量CVAT的部署需要的是一整套配置仓库直接从GitHub拉取git clone https://github.com/cvat-ai/cvat.git cd cvat进入仓库目录后你会发现根目录下有几个关键文件docker-compose.yml是主编排文件docker-compose.dev.yml是开发环境用的.env文件存放环境变量配置。在前端是英文界面的问题上CVAT本身带i18n机制新版已经支持多语言。但默认配置下中文翻译并不完整想切中文界面的朋友可以在前端构建完成后查看语言设置。从我实际使用的经验来看标注界面英文影响不大因为关键操作就那几个按钮习惯之后效率反而更高。接下来创建一个.env文件配置核心参数cp .env .env.local nano .env.local.env.local里需要关注的几个配置项包括CVAT_PORT宿主机映射到前端的端口默认是8080可以改成别的端口避免冲突POSTGRES_DATA_DIRPostgreSQL数据持久化目录生产环境务必改到有足够磁盘空间的路径CVAT_REDIS_HOSTRedis地址保持默认即可CVAT_SERVERLESS是否启用无服务器辅助标注模式默认false需要接外部推理服务时开启3.3 第三步用Docker Compose启动所有服务在源码根目录下执行docker compose up -d第一次执行会拉取所有镜像。这一步极其依赖网络如果发现拉取速度极慢或者某个镜像老是拉不动比如ghcr.io下的镜像大概率是网络问题。最直接的解决方案是配置Docker的registry mirror或者给Docker配置HTTP代理。对国内服务器镜像加速地址网上有很多公开的选一个延迟低的填进去就行。docker compose up -d执行完成后用docker compose ps看看服务状态。正常情况下你应该看到下面这些服务在运行docker compose ps输出里会有cvat_server、cvat_worker_annotation、cvat_worker_export、cvat_worker_import、cvat_db、cvat_redis、cvat_traefik等容器。其中traefik是反向代理负责路由Web请求。如果某个容器状态显示Restarting或者Exited不要慌看日志定位问题docker compose logs cvat_server我遇到过的常见问题是端口被占用导致traefik起不来改一下.env里的CVAT_PORT就行。3.4 第四步执行数据库迁移和创建超级用户容器全部起来之后不能立刻访问因为数据库还没初始化。需要进入cvat_server容器执行Django的migrationdocker exec -it cvat_server bash进入容器后依次执行python3 manage.py migrate python3 manage.py collectstatic --noinputmigrate的作用是把Django模型映射成PostgreSQL里的表结构collectstatic会把前端静态文件收集到一个统一目录。这两步不执行或执行出错页面会出现接口404或者样式丢失的问题。然后创建管理员账号python3 manage.py createsuperuser按照提示输入用户名、邮箱、密码。这个账号是平台的管理员后续所有标注任务的创建、人员分配、模型配置都需要用它登录后台操作。退出容器后在浏览器里访问http://你的服务器IP:8080能看到登录页面用刚才创建的账号登录进去说明整套部署已经跑通了。3.5 初始化脚本官方actually提供了一个便捷入口如果你觉得手动进容器执行manage.py命令太繁琐CVAT仓库里其实带了个初始化脚本cvat/container_utils/init.sh它会自动帮你跑完migrate、createsuperuser、collectstatic这几步。具体用法是./cvat/container_utils/init.sh它会提示你输入用户名邮箱密码然后自动完成初始化。我在新环境部署时都是用它省去手动敲命令的麻烦。不过我还是把手动流程写出来因为了解每一步在干什么对以后排查问题很有帮助。4. 部署完成后的首次配置从创建用户到输出第一批标注数据4.1 用户、团队和权限模型怎么划分CVAT的权限模型分三个层级Admin、User、Worker。Admin是平台管理员负责系统配置、模型加载、用户管理User是标注项目的创建者可以创建任务、分配作业、审核结果Worker是执行标注的成员登录后只能看到分配给自己的标注任务。在多人团队里我建议至少建两个标注账号和一个审核账号让不同角色的人使用不同账号。这样做的好处是责任清晰后端审计日志能追踪到每个标注框是谁画的、什么时候改的。审核员账号发现标注质量问题可以直接打回重做整个流程有据可查。用户创建的位置在页面右上角菜单的Admin下拉里或者直接通过/admin路径进入Django后台在Users表里添加。如果你有批量创建用户的需求Django后台也支持CSV导入不过字段格式要对上实际操作比较少用。4.2 创建标注项目和任务的核心参数配置正常使用流程是登录后点击Create new task然后按顺序填写配置。这里有几个参数很容易让新手困惑我把它们的含义和选择逻辑捋一遍Name任务名称建议用“项目_数据集_版本”这样的命名规范比如carplate_val_v3后续导出和管理会清晰很多。Annotation mode选择Annotation表示标准标注模式Attribute模式则是需要额外打属性标签的模式。属性模式适合那种除了画框还得标记颜色、遮挡物等属性的场景。如果瞄一眼来看默认用Annotation就够了属性可以在标签配置里追加。Labels这一步极其关键它决定标注员能画哪些框、每种框有哪些属性。比如做一个交通标志检测任务labels可以设置traffic_light、stop_sign、speed_limit再加上color、occluded这样的属性字段。配置错误会导致后期改起来很麻烦所以开始前一定要和算法同学确认清楚。Dataset上传图片或视频。多张图片可以压缩成zip上传CVAT会自动解压并按文件名排序。视频上传后需要设置采样帧间隔比如每秒取一帧。Project可以选择已有项目进行关联项目相当于一系列任务的集合可以共享标签体系。任务创建完成后点进任务详情页把要做的具体标注作业分配给WorkerWorker登录后就能在Tasks列表里看到分配的任务进去开始标注。4.3 辅助标注与模型推理的接入方式任务配置页面里有一个Automatic annotation的区块这是整个CVAT的精髓所在也是很多人没搞明白的部分。它支持两种接入方式一是接官方提供的AI模型列表需要通过OpenVINO或外部服务二是自己写一个HTTP推理接口把图片发过去接口返回标注结果CVAT把结果自动绘制到图片上。自己写推理接口的协议并不复杂CVAT把图片以二进制POST到指定URL推理服务返回一组JSON数组包含框坐标、标签、置信度。坐标是相对于图像尺寸的归一化值格式定义在官方文档里有详细说明。对于用PyTorch训练过的检测模型写一个基于Flask的推理服务大概半小时能搞定。实际部署中我自己用OpenVINO加载了YOLOv5的模型做过一次装配体零件标注单片图的推理时间在GPU上是20毫秒左右标注员只需要把置信度低的检测框删掉、把漏检的补上。整个标注过程从“画框”变成了“看图验框”疲劳度下降非常明显。5. CVAT进阶玩法和本地大模型生态结合的几种思路5.1 把本地推理服务接入辅助标注一个完整的调用链路最近越来越多的团队在本地部署大语言模型比如通过Ollama或者vLLM跑对话模型。CVAT本身不会直接调用大模型但如果你有一个图像理解的API服务比如接一个本地部署的视觉模型可以通过CVAT的Serverless配置对接。具体的思路是在CVAT的服务器配置里增加一个无服务器函数指向你本地部署的模型推理地址。标注员在画布上点击“AI标注”按钮时CVAT将当前图像发送给推理服务推理服务解析后把结果传回来。整个链路对标注员来说是无感的。我之前在一个缺陷检测项目中在GPU服务器上部署了一个检测模型通过HTTP服务暴露端口CVAT同一个内网里把推理地址配置好。标注员处理的图像全部走内网传输一张1920×1080的图从发送到拿到结果大约300毫秒和刷网页的感觉差不多。这个体验在云端方案里很难做到因为网络延迟很难控制在个位数毫秒。5.2 标注数据的导出和训练闭环如何打通标注完成的最终目的当然是训练模型。CVAT支持在任务详情页直接导出标注结果格式选择里能找到COCO、YOLO等选项。导出后的文件结构是task_data/ ├── images/ │ ├── 0001.jpg │ ├── 0002.jpg └── annotations/ ├── instances_default.json # COCO格式标注 └── labels.txt拿到COCO JSON文件之后常规的MMDetection或Ultralytics YOLO训练流程都能对接。如果用的是YOLO格式直接拖进训练脚本里也能跑。实操中我推荐在CVAT里导出COCO格式然后用自己写的转换脚本转成训练框架需要的格式。原因有两个一是COCO格式的字段完整包含标签属性等信息二次转换不容易丢数据二是很多训练框架的评测脚本天然支持COCO格式后续做验证集评估会省很多事。5.3 多人协同标注时的并发控制和数据一致性CVAT对同一个标注任务默认是单人标注模式也就是一个任务同时只能有一个人操作避免多人同时在同一个图上画框造成冲突。但实际项目中一个任务往往包含上千张图单人标注效率太低。正确做法是把一个大任务拆成多个小任务每个小任务包含几百张图分给不同的人标注。批量创建任务可以调用CVAT的REST API。官方文档里有详细说明核心是往/api/tasks发POST请求携带任务名称、标签配置、文件列表等参数。我在团队里通常会写一个Python脚本把一批图片按比例分配到N个任务里脚本调用API批量创建然后分配给对应标注员。这样做有几个好处每人的任务量均衡、任务之间互不干扰、审核时可以针对单个任务单独验收打回。6. 实战中我最常遇到的部署问题和排查链路6.1 数据库连接池耗尽导致的页面卡顿项目跑了一段时间后有次标注员反馈页面偶尔白屏过几分钟自己恢复。查了cvat_server的日志看到大量connection refused和too many clients报错定位到是PostgreSQL的连接数被撑爆了。原因其实不复杂CVAT的多个worker进程都会创建数据库连接默认配置下PostgreSQL的最大连接数是100如果服务的并发请求多连接池很容易耗尽。排查链路是先看PostgreSQL的当前连接数docker exec -it cvat_db psql -U cvat -c SELECT count(*) FROM pg_stat_activity;确认是连接数过高之后再去docker-compose.yml里找数据库服务的配置给PostgreSQL添加max_connections参数或者调小Django侧连接池的keepalive时间。我最后的处理是给PostgreSQL配置了200个最大连接数同时把数据库服务器的内存加大到8G后面再没出现过这个问题。6.2 自动标注服务连不上模型的网络配置坑接本地推理服务的时候有一个容易忽略的问题是Docker容器网络和宿主机网络的隔离。CVAT容器内的localhost指向的是容器自己不是宿主机。如果推理服务跑在宿主机上CVAT容器里配置推理地址时不能用localhost:8000要写成host.docker.internal:8000Linux系统可能需要额外加extra_hosts配置。我第一次配置的时候忽略了这个问题标注员点自动标注总是提示模型服务不可用。查了worker日志才意识到是网络路由的问题。在docker-compose.yml的cvat_worker_annotation服务下添加extra_hosts: - host.docker.internal:host-gateway然后docker compose up -d重启服务问题就解决了。6.3 图片上传失败和磁盘空间不足的连锁反应CVAT上传图片默认存到服务器本地存储路径由CVAT_DATA_ROOT环境变量控制。如果你没改过这个配置默认在/data目录。服务器根分区不够大的话用一段时间后磁盘会被打满表现就是上传图片时长时间转圈最终报错。排查方式很简单直接看磁盘使用率df -h如果确认/data所在分区空间不足把整个/data目录挂载到更大容量的数据盘上或者迁移数据目录。迁移的时候需要注意把PostgreSQL的数据目录一起迁走因为CVAT的元数据和图片数据是分离存储的。我自己在正式环境里是把/data目录符号链接到一块独立的4T数据盘上这样即使图片数据快速增长也不会影响系统分区的稳定性。6.4 版本升级带来的数据库迁移问题CVAT社区更新频率很高几乎每个月都有新版本。升级通常是用最新的镜像重新启动容器但数据库结构变化时需要手动执行新的migration才能兼容。每次升级前我习惯先备份数据库docker exec cvat_db pg_dump -U cvat cvat cvat_backup_$(date %Y%m%d).sql然后拉新镜像、启容器、执行docker exec -it cvat_server python3 manage.py migrate。如果升级后页面报500错误大概率是migrate没有完整执行或者有字段冲突。这时候把备份文件恢复回去可以快速回到可用状态。6.5 关于Nginx或Traefik反代HTTPS的小建议CVAT默认使用Traefik作为入口代理通过HTTP访问。如果要在公网环境使用建议在Traefik配置里开启HTTPS。CVAT官方文档里有ACME证书自动申请的配置示例traefik目录下放一个dynamic_config.yaml即可。不过对绝大多数本地部署场景我建议在局域网内先以HTTP方式跑起来物理隔离内网环境下性能优先证书反而是次要的。等团队用了稳定了再考虑加网关层加密也不迟。7. 从标注工具到数据工厂CVAT在团队协作中的定位思考很多人把CVAT当成一个画框工具来用这是最浪费的用法。它真正的长期价值在于把标注从“个人手工活”升级成“团队流水线”。一个成熟的数据标注团队架构应该是算法工程师负责定义标签体系和预标注模型数据管理员负责建任务、拆图集、分配人员标注员专注执行审核通过的标注标准审核员负责抽检和回退。CVAT的权限模型和任务流在机制上就支持这一整套流程。如果你正在搭建自己的标注团队或者最近被重复标注搞得焦头烂额我建议先花一个下午把本地部署跑通再用一周时间把一个小型真实任务完整跑一遍建任务、分配、标注、审核、导出、训练、评估。走完这一轮你就知道CVAT能为你省下多少时间。最后再分享一个实操中的小技巧在多显卡服务器上可以把CVAT的自动标注worker绑定到指定GPU上通过--gpus参数控制避免和训练进程争抢显存。这个细节在团队共享服务器时特别有用否则训练到一半被标注任务抢了显存谁都难受。
CVAT本地部署指南：用Docker Compose搭建高效数据标注平台
1. CVAT到底是什么为什么标注工具这件事被严重低估了先说结论CVATComputer Vision Annotation Tool是英特尔开源的在线视频和图像标注工具也是一个真正意义上把“标注”这件事做成工业化流水线的平台。如果你做计算机视觉相关的工作不管是目标检测、图像分割、关键点检测还是视频跟踪类任务日常大概率逃不开标注这个环节。我最早接触CVAT是帮团队做一批行人重识别数据的标注当时用labelImg一张张拉框拉到怀疑人生后来换到CVAT才意识到标注工具之间的差距比我想象中大得多。CVAT解决的问题表面上看是“让人能画框”但往深处拆它解决的其实是三件事标注效率、标注质量、以及标注任务的协同管理。早期单人标注随便找个工具就能干但一旦标注人员有多个、标注标准需要统一、数据需要版本管理、任务需要分配和验收普通的桌面级标注软件就撑不住了。CVAT把标注任务拆成“任务—作业—标注—审核—导出”这样一个完整闭环配合RBAC权限模型可以直接按标注员、审核员、管理员三种角色划分权限。这一点在项目稍微正规一点之后价值会体现得特别明显。另一个被低估的地方是CVAT对“辅助标注”的支持。它不是让你从零开始对着空白图画框而是可以接深度学习模型的推理结果做预标注标注员只需要微调位置、修正类别。官方也提供了模型加载通道比如通过Intel OpenVINO或者自己写的推理API做自动标注。实测下来对于场景相对固定的数据辅助标注能把标注速度提升3到5倍这个提升不是体感上的是真实能算出来的。再说说CVAT的适用范围。它支持图像分类、目标检测矩形框、多边形分割、关键点、线段、以及视频帧序列的跟踪标注基本覆盖了主流视觉任务。数据格式方面支持COCO、Pascal VOC、YOLO、TFRecord等常见协议模型训练完之后的数据导出基本上不需要写额外的转换脚本。正是因为这个覆盖面足够广所以不管是做安防、工业质检、自动驾驶场景还是做学术研究CVAT都能作为标注侧的主力工具接入流程。2. 本地部署的真实动机和落地之前必须想清楚的几件事2.1 为什么很多团队选择本地部署而不是直接用云版本网上关于CVAT部署的教程不少但大部分是把Docker命令粘贴一遍就完事很少讲清楚“为什么要本地部署”这件事。我先把动机聊透因为这直接决定你要不要花几天时间去折腾它。官方其实提供了在线体验版app.cvat.ai注册个账号就能用。但对多数做实际项目的团队来说数据安全是绕不开的红线。训练数据一旦传到第三方平台上不管是保密协议还是公司内部合规都过不了。尤其是做工业、医疗、军工相关项目的朋友数据出内网这件事本身就是重大事故。本地部署的最核心动机就是数据完全在自己的服务器上流转训练数据不出内网。另一个动机是和内网已有的资源打通。很多团队的训练服务器上本来就挂着GPU资源、已经有自己训练的模型服务。把CVAT部署在同内网环境里它可以直接调用内网里的推理模型做预标注走内网带宽速度和安全性都有保障。这个优势在云端方案上是很难复制的。2.2 部署之前需要确认的硬件和软件条件先泼一盆冷水CVAT不是随便找个低配机器就能顺畅跑的。它的组件里有PostgreSQL、Redis、Django后端还带一套基于React的前端以及一个专门跑自动标注任务的worker进程。全部服务加起来对内存的消耗很可观我最早一次部署给了4G内存的机器结果光依赖服务就把内存吃满了页面直接卡成PPT。结合社区里的实践和我自己的试错硬件需求可以分两个档位使用场景CPU核心数内存存储是否需要GPU单机学习、小团队试用4核8G100G可用不需要中大型团队正式使用8核以上16G以上500G以上建议有需要说明的是GPU不是必选项。如果只做纯手工标注CPU跑核心服务就够了但如果要用模型辅助标注建议至少有一张支持CUDA的N卡。CVAT的自动标注worker可以通过OpenVINO在CPU上跑部分模型但速度不太理想用GPU才会有实用性。软件层面其实很省心因为CVAT本身是Docker容器化部署宿主机只需要装好Docker和Docker Compose插件。如果你用Linux系统我建议用Ubuntu 20.04以上版本。Windows环境也能跑但文件权限和路径挂载的坑比较多对于新手我强烈建议用Linux。2.3 版本选择推荐用docker-compose而不是手动搭组件CVAT官方提供了两种部署思路一是用现成的Docker Compose编排另一种是手动安装所有依赖组件然后跑源码。想都不用想直接用Docker Compose。手动部署意味着你要自己搞定PostgreSQL数据库初始化、Redis缓存配置、Django的migration、静态文件收集、HTTPS证书等一系列步骤光这些就能消耗掉一到两天时间而且几乎每次都会踩到不一样的坑。通过Docker Compose所有组件都由编排文件统一管理日志、网络、持久化存储都集中在一个命名空间里重装、升级、回滚都方便得多。后面我会把具体步骤写清楚。3. 使用Docker Compose部署CVAT的完整实操步骤3.1 第一步安装Docker和Compose插件如果你在Ubuntu上从零开始部署先把基础环境准备好。这一步不复杂但有两个细节容易踩坑。一是Docker的apt源如果用官方源国内服务器拉取会非常慢建议装完Docker之后立刻配置国内镜像加速器。二是Docker Compose v2是作为插件存在的命令是docker compose中间有空格和老的docker-compose命令不是同一个东西。CVAT官方的部署脚本在v2版本下运行更顺。基础安装命令如下# 更新系统包 sudo apt update sudo apt upgrade -y # 安装依赖 sudo apt install -y curl git # 安装Docker使用官方脚本国内建议配代理 curl -fsSL https://get.docker.com | sudo sh # 将当前用户加入docker组避免每次sudo sudo usermod -aG docker $USER # 安装Compose插件 sudo apt install -y docker-compose-plugin # 验证安装 docker --version docker compose version这里提醒一句usermod加组之后需要重新登录终端才生效别以为配完没反应就是出错了。用id命令看到docker组身份后就可以继续。3.2 第二步获取CVAT源码和配置环境变量CVAT的部署需要的是一整套配置仓库直接从GitHub拉取git clone https://github.com/cvat-ai/cvat.git cd cvat进入仓库目录后你会发现根目录下有几个关键文件docker-compose.yml是主编排文件docker-compose.dev.yml是开发环境用的.env文件存放环境变量配置。在前端是英文界面的问题上CVAT本身带i18n机制新版已经支持多语言。但默认配置下中文翻译并不完整想切中文界面的朋友可以在前端构建完成后查看语言设置。从我实际使用的经验来看标注界面英文影响不大因为关键操作就那几个按钮习惯之后效率反而更高。接下来创建一个.env文件配置核心参数cp .env .env.local nano .env.local.env.local里需要关注的几个配置项包括CVAT_PORT宿主机映射到前端的端口默认是8080可以改成别的端口避免冲突POSTGRES_DATA_DIRPostgreSQL数据持久化目录生产环境务必改到有足够磁盘空间的路径CVAT_REDIS_HOSTRedis地址保持默认即可CVAT_SERVERLESS是否启用无服务器辅助标注模式默认false需要接外部推理服务时开启3.3 第三步用Docker Compose启动所有服务在源码根目录下执行docker compose up -d第一次执行会拉取所有镜像。这一步极其依赖网络如果发现拉取速度极慢或者某个镜像老是拉不动比如ghcr.io下的镜像大概率是网络问题。最直接的解决方案是配置Docker的registry mirror或者给Docker配置HTTP代理。对国内服务器镜像加速地址网上有很多公开的选一个延迟低的填进去就行。docker compose up -d执行完成后用docker compose ps看看服务状态。正常情况下你应该看到下面这些服务在运行docker compose ps输出里会有cvat_server、cvat_worker_annotation、cvat_worker_export、cvat_worker_import、cvat_db、cvat_redis、cvat_traefik等容器。其中traefik是反向代理负责路由Web请求。如果某个容器状态显示Restarting或者Exited不要慌看日志定位问题docker compose logs cvat_server我遇到过的常见问题是端口被占用导致traefik起不来改一下.env里的CVAT_PORT就行。3.4 第四步执行数据库迁移和创建超级用户容器全部起来之后不能立刻访问因为数据库还没初始化。需要进入cvat_server容器执行Django的migrationdocker exec -it cvat_server bash进入容器后依次执行python3 manage.py migrate python3 manage.py collectstatic --noinputmigrate的作用是把Django模型映射成PostgreSQL里的表结构collectstatic会把前端静态文件收集到一个统一目录。这两步不执行或执行出错页面会出现接口404或者样式丢失的问题。然后创建管理员账号python3 manage.py createsuperuser按照提示输入用户名、邮箱、密码。这个账号是平台的管理员后续所有标注任务的创建、人员分配、模型配置都需要用它登录后台操作。退出容器后在浏览器里访问http://你的服务器IP:8080能看到登录页面用刚才创建的账号登录进去说明整套部署已经跑通了。3.5 初始化脚本官方actually提供了一个便捷入口如果你觉得手动进容器执行manage.py命令太繁琐CVAT仓库里其实带了个初始化脚本cvat/container_utils/init.sh它会自动帮你跑完migrate、createsuperuser、collectstatic这几步。具体用法是./cvat/container_utils/init.sh它会提示你输入用户名邮箱密码然后自动完成初始化。我在新环境部署时都是用它省去手动敲命令的麻烦。不过我还是把手动流程写出来因为了解每一步在干什么对以后排查问题很有帮助。4. 部署完成后的首次配置从创建用户到输出第一批标注数据4.1 用户、团队和权限模型怎么划分CVAT的权限模型分三个层级Admin、User、Worker。Admin是平台管理员负责系统配置、模型加载、用户管理User是标注项目的创建者可以创建任务、分配作业、审核结果Worker是执行标注的成员登录后只能看到分配给自己的标注任务。在多人团队里我建议至少建两个标注账号和一个审核账号让不同角色的人使用不同账号。这样做的好处是责任清晰后端审计日志能追踪到每个标注框是谁画的、什么时候改的。审核员账号发现标注质量问题可以直接打回重做整个流程有据可查。用户创建的位置在页面右上角菜单的Admin下拉里或者直接通过/admin路径进入Django后台在Users表里添加。如果你有批量创建用户的需求Django后台也支持CSV导入不过字段格式要对上实际操作比较少用。4.2 创建标注项目和任务的核心参数配置正常使用流程是登录后点击Create new task然后按顺序填写配置。这里有几个参数很容易让新手困惑我把它们的含义和选择逻辑捋一遍Name任务名称建议用“项目_数据集_版本”这样的命名规范比如carplate_val_v3后续导出和管理会清晰很多。Annotation mode选择Annotation表示标准标注模式Attribute模式则是需要额外打属性标签的模式。属性模式适合那种除了画框还得标记颜色、遮挡物等属性的场景。如果瞄一眼来看默认用Annotation就够了属性可以在标签配置里追加。Labels这一步极其关键它决定标注员能画哪些框、每种框有哪些属性。比如做一个交通标志检测任务labels可以设置traffic_light、stop_sign、speed_limit再加上color、occluded这样的属性字段。配置错误会导致后期改起来很麻烦所以开始前一定要和算法同学确认清楚。Dataset上传图片或视频。多张图片可以压缩成zip上传CVAT会自动解压并按文件名排序。视频上传后需要设置采样帧间隔比如每秒取一帧。Project可以选择已有项目进行关联项目相当于一系列任务的集合可以共享标签体系。任务创建完成后点进任务详情页把要做的具体标注作业分配给WorkerWorker登录后就能在Tasks列表里看到分配的任务进去开始标注。4.3 辅助标注与模型推理的接入方式任务配置页面里有一个Automatic annotation的区块这是整个CVAT的精髓所在也是很多人没搞明白的部分。它支持两种接入方式一是接官方提供的AI模型列表需要通过OpenVINO或外部服务二是自己写一个HTTP推理接口把图片发过去接口返回标注结果CVAT把结果自动绘制到图片上。自己写推理接口的协议并不复杂CVAT把图片以二进制POST到指定URL推理服务返回一组JSON数组包含框坐标、标签、置信度。坐标是相对于图像尺寸的归一化值格式定义在官方文档里有详细说明。对于用PyTorch训练过的检测模型写一个基于Flask的推理服务大概半小时能搞定。实际部署中我自己用OpenVINO加载了YOLOv5的模型做过一次装配体零件标注单片图的推理时间在GPU上是20毫秒左右标注员只需要把置信度低的检测框删掉、把漏检的补上。整个标注过程从“画框”变成了“看图验框”疲劳度下降非常明显。5. CVAT进阶玩法和本地大模型生态结合的几种思路5.1 把本地推理服务接入辅助标注一个完整的调用链路最近越来越多的团队在本地部署大语言模型比如通过Ollama或者vLLM跑对话模型。CVAT本身不会直接调用大模型但如果你有一个图像理解的API服务比如接一个本地部署的视觉模型可以通过CVAT的Serverless配置对接。具体的思路是在CVAT的服务器配置里增加一个无服务器函数指向你本地部署的模型推理地址。标注员在画布上点击“AI标注”按钮时CVAT将当前图像发送给推理服务推理服务解析后把结果传回来。整个链路对标注员来说是无感的。我之前在一个缺陷检测项目中在GPU服务器上部署了一个检测模型通过HTTP服务暴露端口CVAT同一个内网里把推理地址配置好。标注员处理的图像全部走内网传输一张1920×1080的图从发送到拿到结果大约300毫秒和刷网页的感觉差不多。这个体验在云端方案里很难做到因为网络延迟很难控制在个位数毫秒。5.2 标注数据的导出和训练闭环如何打通标注完成的最终目的当然是训练模型。CVAT支持在任务详情页直接导出标注结果格式选择里能找到COCO、YOLO等选项。导出后的文件结构是task_data/ ├── images/ │ ├── 0001.jpg │ ├── 0002.jpg └── annotations/ ├── instances_default.json # COCO格式标注 └── labels.txt拿到COCO JSON文件之后常规的MMDetection或Ultralytics YOLO训练流程都能对接。如果用的是YOLO格式直接拖进训练脚本里也能跑。实操中我推荐在CVAT里导出COCO格式然后用自己写的转换脚本转成训练框架需要的格式。原因有两个一是COCO格式的字段完整包含标签属性等信息二次转换不容易丢数据二是很多训练框架的评测脚本天然支持COCO格式后续做验证集评估会省很多事。5.3 多人协同标注时的并发控制和数据一致性CVAT对同一个标注任务默认是单人标注模式也就是一个任务同时只能有一个人操作避免多人同时在同一个图上画框造成冲突。但实际项目中一个任务往往包含上千张图单人标注效率太低。正确做法是把一个大任务拆成多个小任务每个小任务包含几百张图分给不同的人标注。批量创建任务可以调用CVAT的REST API。官方文档里有详细说明核心是往/api/tasks发POST请求携带任务名称、标签配置、文件列表等参数。我在团队里通常会写一个Python脚本把一批图片按比例分配到N个任务里脚本调用API批量创建然后分配给对应标注员。这样做有几个好处每人的任务量均衡、任务之间互不干扰、审核时可以针对单个任务单独验收打回。6. 实战中我最常遇到的部署问题和排查链路6.1 数据库连接池耗尽导致的页面卡顿项目跑了一段时间后有次标注员反馈页面偶尔白屏过几分钟自己恢复。查了cvat_server的日志看到大量connection refused和too many clients报错定位到是PostgreSQL的连接数被撑爆了。原因其实不复杂CVAT的多个worker进程都会创建数据库连接默认配置下PostgreSQL的最大连接数是100如果服务的并发请求多连接池很容易耗尽。排查链路是先看PostgreSQL的当前连接数docker exec -it cvat_db psql -U cvat -c SELECT count(*) FROM pg_stat_activity;确认是连接数过高之后再去docker-compose.yml里找数据库服务的配置给PostgreSQL添加max_connections参数或者调小Django侧连接池的keepalive时间。我最后的处理是给PostgreSQL配置了200个最大连接数同时把数据库服务器的内存加大到8G后面再没出现过这个问题。6.2 自动标注服务连不上模型的网络配置坑接本地推理服务的时候有一个容易忽略的问题是Docker容器网络和宿主机网络的隔离。CVAT容器内的localhost指向的是容器自己不是宿主机。如果推理服务跑在宿主机上CVAT容器里配置推理地址时不能用localhost:8000要写成host.docker.internal:8000Linux系统可能需要额外加extra_hosts配置。我第一次配置的时候忽略了这个问题标注员点自动标注总是提示模型服务不可用。查了worker日志才意识到是网络路由的问题。在docker-compose.yml的cvat_worker_annotation服务下添加extra_hosts: - host.docker.internal:host-gateway然后docker compose up -d重启服务问题就解决了。6.3 图片上传失败和磁盘空间不足的连锁反应CVAT上传图片默认存到服务器本地存储路径由CVAT_DATA_ROOT环境变量控制。如果你没改过这个配置默认在/data目录。服务器根分区不够大的话用一段时间后磁盘会被打满表现就是上传图片时长时间转圈最终报错。排查方式很简单直接看磁盘使用率df -h如果确认/data所在分区空间不足把整个/data目录挂载到更大容量的数据盘上或者迁移数据目录。迁移的时候需要注意把PostgreSQL的数据目录一起迁走因为CVAT的元数据和图片数据是分离存储的。我自己在正式环境里是把/data目录符号链接到一块独立的4T数据盘上这样即使图片数据快速增长也不会影响系统分区的稳定性。6.4 版本升级带来的数据库迁移问题CVAT社区更新频率很高几乎每个月都有新版本。升级通常是用最新的镜像重新启动容器但数据库结构变化时需要手动执行新的migration才能兼容。每次升级前我习惯先备份数据库docker exec cvat_db pg_dump -U cvat cvat cvat_backup_$(date %Y%m%d).sql然后拉新镜像、启容器、执行docker exec -it cvat_server python3 manage.py migrate。如果升级后页面报500错误大概率是migrate没有完整执行或者有字段冲突。这时候把备份文件恢复回去可以快速回到可用状态。6.5 关于Nginx或Traefik反代HTTPS的小建议CVAT默认使用Traefik作为入口代理通过HTTP访问。如果要在公网环境使用建议在Traefik配置里开启HTTPS。CVAT官方文档里有ACME证书自动申请的配置示例traefik目录下放一个dynamic_config.yaml即可。不过对绝大多数本地部署场景我建议在局域网内先以HTTP方式跑起来物理隔离内网环境下性能优先证书反而是次要的。等团队用了稳定了再考虑加网关层加密也不迟。7. 从标注工具到数据工厂CVAT在团队协作中的定位思考很多人把CVAT当成一个画框工具来用这是最浪费的用法。它真正的长期价值在于把标注从“个人手工活”升级成“团队流水线”。一个成熟的数据标注团队架构应该是算法工程师负责定义标签体系和预标注模型数据管理员负责建任务、拆图集、分配人员标注员专注执行审核通过的标注标准审核员负责抽检和回退。CVAT的权限模型和任务流在机制上就支持这一整套流程。如果你正在搭建自己的标注团队或者最近被重复标注搞得焦头烂额我建议先花一个下午把本地部署跑通再用一周时间把一个小型真实任务完整跑一遍建任务、分配、标注、审核、导出、训练、评估。走完这一轮你就知道CVAT能为你省下多少时间。最后再分享一个实操中的小技巧在多显卡服务器上可以把CVAT的自动标注worker绑定到指定GPU上通过--gpus参数控制避免和训练进程争抢显存。这个细节在团队共享服务器时特别有用否则训练到一半被标注任务抢了显存谁都难受。
