CVAT CLI 命令行工具完全指南安装、认证、任务/项目/函数管理与自动标注实战【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat导读CVATComputer Vision Annotation Tool提供了一个名为cvat-cli的命令行客户端用于在终端中直接管理 CVAT 服务器上的项目、任务和Enterprise/Cloud 版AI 函数资源。本文以官方 CLI 文档为主线结合仓库中 cvat-cli 源码 与 cvat-sdk 认证实现系统讲解安装方式、通用命令结构、两种认证方案与持久化 profile 机制并逐一演示任务、项目、函数的完整实操命令。读完本文你将掌握用一行命令完成建任务→传数据→自动标注→导出数据集→备份恢复全流程的能力。OverviewCLI 能做什么CVAT CLI 是一个简单但可扩展的命令行界面目前实现了基础功能集未来可以发展为更全面的 CVAT 管理工具。它围绕三类资源组织子命令Projects项目backup、create、create-from-backup、delete、export-dataset、import-dataset、lsTasks任务create、create-from-backup、delete、ls、frames、export-dataset、import-dataset、backup、auto-annotateFunctions函数仅 Enterprise/Cloudcreate-native、delete、run-agent在源码中这些命令分别定义于 commands_tasks.py、commands_projects.py 与 commands_functions.py统一由 command_base.py 中的CommandGroup机制注册每个命令是一个实现了description/configure_parser/execute协议的类通过COMMANDS.command_class(name)装饰器挂载到 argparse 子命令树上command_base.py。安装CVAT CLI 作为独立 Python 包发布一条命令即可安装pip install cvat-cliPython 版本要求3.10 及以上见 pyproject.toml 中requires-python 3.10。安装后提供cvat-cli可执行入口由 pyproject.toml 中cvat-cli cvat_cli.__main__:main指定最终调用main.py 中的main()完成参数解析、客户端构建与执行。依赖项cvat-sdk固定版本、attrs、json-with-comments用于解析 profile token 信封文件、Pillow见 pyproject.toml。通用用法与命令结构所有命令遵循统一形态$ cvat-cli common options resource action options其中common options所有子命令共享的全局选项认证、服务器地址、组织等resourceCVAT 资源类型如task、project、functionaction对资源执行的动作如create、ls、deleteoptions特定资源与动作专属的参数。三个层级的--help由浅入深$ cvat-cli --help # 查看公共选项与可用资源 $ cvat-cli resource --help # 查看某资源的可用动作 $ cvat-cli resource action --help # 查看动作专属参数公共选项在 auth.py 的configure_client_auth_arguments中定义主要包括选项说明--auth USER[:PASS]用户名/密码认证支持PASS环境变量或交互输入密码--server-host HOST服务器地址默认取 profile、default-server 或http://localhost--server-port PORT服务器端口HTTP 默认 80HTTPS 默认 443--organization/--org SLUG组织短名slug传空字符串使用个人工作区--profile NAME使用已保存的 profile与--server-host/--server-port/--auth互斥--insecure关闭 SSL 证书校验--debug输出调试日志同时开启 HTTP 层 debug见 common.py另外部分任务动作提供了别名子命令用于向后兼容例如cvat-cli ls等价于cvat-cli task ls。这些别名已被标记为弃用deprecated执行时会输出警告建议始终使用task action形式command_base.py。认证CLI 支持两种认证方式Personal Access TokenPAT认证使用访问令牌令牌可在 CVAT UI 的用户设置中创建是推荐的首选认证方式参见 访问令牌文档。密码认证使用用户名 密码组合为安全起见如可能建议优先使用 PAT。PAT 认证PAT 只能通过CVAT_ACCESS_TOKEN环境变量使用且该变量优先级高于其他认证环境变量export CVAT_ACCESS_TOKENtoken value cvat-cli task ls在源码层面default_auth_factory()会优先读取CVAT_ACCESS_TOKEN环境变量构造令牌凭据未设置时才回退到系统用户名 密码询问流程auth.py。密码认证凭据通过全局参数--auth指定密码可以跟在冒号:分隔符后也可通过PASS环境变量提供cvat-cli --auth username:password task lsexport PASSpassword cvat-cli --auth username task ls--auth也可以省略此时 CLI 尝试使用当前 OS 用户作为用户名若配置了PASS环境变量则作为密码否则交互式请求输入密码cvat-cli task lsget_auth_factory()的实现正是这个逻辑解析USER[:PASS]缺密码时先查PASS环境变量再不行就getpass交互提示auth.py。持久化认证Profiles为避免每天重复输入--server-host/--auth或让凭据泄漏进 shell 历史CLI 可以把服务器地址与 PAT 保存在本地profile中。每个 profile 自包含一个服务器 一个 PAT。存储位置与权限Profiles 以 JSON 文件形式存储位于0700权限目录下、文件本身为0600模式仅属主可读写。CLI 会拒绝读写文件或其父目录可被组/他人访问的情况Windows 上为尽力检查。位置遵循平台惯例平台路径Linux${XDG_CONFIG_HOME:-$HOME/.config}/cvat-sdk/auth.jsonmacOS~/Library/Application Support/cvat-sdk/auth.jsonWindows%LOCALAPPDATA%\CVAT.ai\cvat-sdk\auth.json该路径由get_auth_store_path()基于platformdirs.user_config_path计算auth.py读写由AuthStore类强制执行0600/0700权限检查auth.py。注意本地 profile 仅支持 PAT 认证方式用户名/密码无法以这种方式记忆。管理 Profiles使用cvat-cli profile与cvat-cli config创建和管理 profile。这些命令只操作本地文件、不与服务器通信唯一的例外是当未提供令牌名称时profile create会向服务器查询令牌的name。# 保存一个 profile省略令牌时交互式输入不回显 cvat-cli --server-host https://app.cvat.ai profile create --name mycvat --set-default # 直接粘贴令牌保存并指定昵称 cvat-cli --server-host https://app.cvat.ai profile create --name mycvat paste-token-here # 从纯文本文件导入令牌 cvat-cli --server-host https://app.cvat.ai profile create --name mycvat --file ~/Downloads/cvat-token.txt # JSONC 信封文件含令牌、服务器、profile 名无需额外参数 cvat-cli profile create --file ~/Downloads/cvat-token-my-laptop.json # 查看与管理存储 cvat-cli profile list # 列出名称、服务器与默认标记 cvat-cli profile list --names-only # 仅名称一行一个脚本友好 cvat-cli profile default # 打印当前默认 profile cvat-cli profile default staging # 将 staging 设为默认 cvat-cli profile default --unset # 取消默认 cvat-cli profile delete staging # 删除 profile不会吊销令牌 # 设置默认服务器当既无 --server-host 也无 --profile 时作为后备 cvat-cli config default-server https://app.cvat.ai cvat-cli config default-server # 打印当前默认服务器 cvat-cli config default-server --unset令牌信封文件支持 JSONC 语法含注释、尾随逗号。如果下载信封后服务器地址有变更可用--server-host覆盖信封内嵌的服务器 URLcvat-cli --server-host https://new.example.com profile create \ --file ~/Downloads/cvat-token-my-laptop.json删除 profile 不会吊销服务器端令牌如需吊销请到 CVAT UI 或通过 API 操作。源码中ProfileCreate.execute完整实现了上述逻辑支持--name、--set-default、--force覆盖、--file导入、交互式getpass输入令牌等commands_profile.py。单条命令选择 Profile全局--profile name标志为单条命令选择已保存的 profile它与--server-host、--server-port、--auth互斥cvat-cli --profile mycvat task ls cvat-cli --profile staging task create task 1 --labels labels.json local file.jpg解析顺序CLI 首先尝试选择 profile显式指定--profile NAME同时提供服务器与 PAT不能与--server-host、--server-port、--auth组合使用。否则若配置了默认 profile 且未显式提供服务器或凭据则使用默认 profileCVAT_ACCESS_TOKEN被视为显式凭据。若选中 profile则服务器与凭据都由它提供、解析终止。否则凭据与服务器各自独立解析凭据解析顺序--auth USER[:PASS]省略 PASS 时用PASS环境变量或交互询问CVAT_ACCESS_TOKEN若已设置当前 OS 用户名 PASS环境变量或密码询问。服务器解析顺序--server-host--server-port作用于选定的主机若只给--server-port主机来自下面的来源cvat-cli config default-server配置的服务器若已设置内置默认值http://localhost源码常量DEFAULT_SERVER见 auth.py。提供显式凭据或服务器会阻止 CLI 从默认 profile 借用另一项值。任务Task实战示例创建任务创建任务需要一份 JSON 格式的标签labels文件可以借助 UI 中的标签构造器生成。示例 labels.json[ { name: cat, attributes: [] }, { name: dog, attributes: [] } ]在源码中--labels参数由parse_label_arg()解析如果传的是已存在路径则按 JSON 文件读取否则按 JSON 字符串解析parsers.py因此两种写法均可。基础示例在默认服务器http://localhost上创建名为 new task 的任务标签来自 labels.json数据为本地图片 file1.jpg、file2.jpg任务以当前用户创建cvat-cli task create new task --labels labels.json local file1.jpg file2.jpg指定服务器与用户在https://example.com上创建 task 1标签来自 labels.json本地图片 image1.jpg以用户 user-1 创建cvat-cli --server-host https://example.com --auth user-1 task create task 1 \ --labels labels.json local image1.jpg指定组织在默认服务器创建 task 1标签来自 labels.json本地图片 file1.jpg当前用户身份组织 myorgcvat-cli --org myorg task create task 1 --labels labels.json local file1.jpg继承项目标签 远程视频标签来自 id 为 1 的项目数据为远程视频文件以用户 user-1 创建cvat-cli --auth user-1:password task create task 1 --project_id 1 \ remote https://github.com/opencv/opencv/blob/master/samples/data/vtest.avi?rawtrue高级参数组合标签 cat、dogchunk 大小 8随机排序帧步长 10复制数据到 CVAT 服务器使用 zip chunks视频来自共享资源cvat-cli task create task 1 sort random --labels [{name: cat},{name: dog}] --chunk_size 8 \ --sorting-method random --frame_step 10 --copy_data --use_zip_chunks share //share/dataset_1/video.avi带标注导入与质量设置标签来自 labels.json链接 bug tracker图片质量降至 75从 annotation.xml 导入 CVAT 1.1 格式标注数据来自 dataset_1/images/以 user-2 创建密码需另行输入cvat-cli --auth user-2 task create task from dataset_1 --labels labels.json \ --bug_tracker https://bug-tracker.com/0001 --image_quality 75 --annotation_path annotation.xml \ --annotation_format CVAT 1.1 local dataset_1/images/分段segment参数overlay 大小 5segment 大小 100第 5 到 705 帧使用缓存远程视频cvat-cli task create segmented task 1 --labels labels.json --overlap 5 --segment_size 100 \ --start_frame 5 --stop_frame 705 --use_cache \ remote https://github.com/opencv/opencv/blob/master/samples/data/vtest.avi?rawtrue云存储数据过滤使用test_images/*.jpeg过滤 manifest.jsonl 中描述的云存储数据cvat-cli task create task with filtered cloud storage data --labels [{name: car}]\ --use_cache --cloud_storage_id 1 --filename_pattern test_images/*.jpeg share manifest.jsonl使用全部云存储数据filename_pattern为*cvat-cli task create task with filtered cloud storage data --labels [{name: car}]\ --use_cache --cloud_storage_id 1 --filename_pattern * share manifest.jsonltask create支持的全部参数含默认值可在 commands_tasks.py 中查看常用参数包括参数默认值说明--labels[]JSON 字符串或文件路径的标签规格--project_id-关联已有项目替代 labels--annotation_path/--annotation_format/CVAT 1.1创建时导入标注--image_quality70图片质量0-100--chunk_size-每 chunk 的帧数--sorting-methodlexicographicallexicographical/natural/predefined/random--frame_step-视频/图像序列抽帧步长--start_frame/--stop_frame-视频起止帧--overlap/--segment_size-分段重叠帧数 / 每段帧数--use_cacheFalse使用缓存--use_zip_chunksFalse上传前压缩 chunk--copy_dataFalse仅 share 类型复制数据到服务器--cloud_storage_id/--filename_pattern-从云存储按模式过滤取数据--completion_verification_period2检查数据压缩完成的间隔秒从实现上看TaskCreate.execute会把 kwargs 按models.DataRequest.attribute_map拆分为data_params与task_params随后调用client.tasks.create_from_data(...)一次性完成建任务 传数据 可选导入标注成功后打印新任务 IDcommands_tasks.py。删除任务删除 ID 为 100、101、102 的任务以拥有删除权限的 user-1 执行cvat-cli --auth user-1:password task delete 100 101 102底层由GenericDeleteCommand的remove_by_ids实现会忽略不存在的 IDcommand_base.py。列出任务cvat-cli task ls # 列出全部任务 cvat-cli --org myorg task ls # 列出组织 myorg 的全部任务 cvat-cli task ls --json list_of_tasks.json # 以 JSON 格式保存到文件--json输出使用缩进美化后的 JSON不加--json时默认只打印任务 ID 列表command_base.py。下载帧将任务 119 的第 12、15、22 帧以压缩质量保存到 images 文件夹cvat-cli task frames --outdir images --quality compressed 119 12 15 22--quality可选original默认或compressed默认输出到当前目录--outdir为空时保存的文件名模式为task_ID_frame_FRAME.jpgcommands_tasks.py。导出数据集cvat-cli task export-dataset --format CVAT for images 1.1 103 output.zip # 导出任务 103 为 CVAT 格式 cvat-cli task export-dataset --format COCO 1.0 104 output.zip # 导出任务 104 为 COCO 格式导出的默认格式为CVAT for images 1.1--with-images控制是否包含图片默认False项目导出示例中会用到省略输出文件名时保存到当前目录并使用服务器生成的名称command_base.py。从数据集导入标注将任务 105 以CVAT 1.1格式从 annotation.xml 导入标注cvat-cli task import-dataset --format CVAT 1.1 105 annotation.xml备份任务将任务 136 备份到 task_136.zipcvat-cli task backup 136 task_136.zip从备份创建任务从备份文件 task_backup.zip 创建任务cvat-cli task create-from-backup task_backup.zip自动标注Auto-annotatetask auto-annotate是自动标注 API 的命令行入口它在本机运行 AA 函数对指定任务进行自动标注。AA 函数可通过以下两种方式实现方式一模块级直接实现 AA 函数协议。模块顶层必须定义所需属性import cvat_sdk.auto_annotation as cvataa spec cvataa.DetectionFunctionSpec(...) def detect(context, image): ...方式二实现名为create的工厂函数。该函数返回一个实现 AA 函数协议的对象命令行中用-p指定的参数会传给createimport cvat_sdk.auto_annotation as cvataa class _MyFunction: def __init__(...): ... spec cvataa.DetectionFunctionSpec(...) def detect(context, image): ... def create(...) - cvataa.DetectionFunction: return _MyFunction(...)示例一用预置的 torchvision 检测函数带参数标注任务 137cvat-cli task auto-annotate 137 --function-module cvat_sdk.auto_annotation.functions.torchvision_detection \ -p model_namestr:fasterrcnn_resnet50_fpn_v2 -p box_score_threshfloat:0.5示例二用my_func.py中定义的 AA 函数标注任务 138cvat-cli task auto-annotate 138 --function-file path/to/my_func.py注意该命令不会修改 Python 模块搜索路径。如果函数模块需要导入其他本地模块必须确保其目录已在搜索路径中。示例三函数定义在my-project目录的my_func模块中允许它从该目录导入其他模块PYTHONPATHpath/to/my-project cvat-cli task auto-annotate 139 --function-module my_func参数格式-p的格式为NAMETYPE:VALUE支持int、float、str、bool四种类型由parse_function_parameter()解析parsers.py。--function-module与--function-file二选一必填二者由configure_function_implementation_arguments构造互斥组common.py。函数加载由FunctionLoader.load()完成模块方式用importlib.import_module文件方式用spec_from_file_location动态加载若函数对象有create属性则视为工厂并传入参数调用且要求最终对象必须带spec属性common.py。task auto-annotate还支持以下选项commands_tasks.py选项说明--clear-existing先清除任务已有标注--allow-unmatched-labels允许函数声明任务中未配置的标签/子标签/属性--conf-threshold过滤检测结果的置信度阈值0-1--conv-mask-to-poly将 mask 形状转换为多边形仓库自带的预置函数位于 auto_annotation/functions 目录包括torchvision_detection、torchvision_classification、torchvision_instance_segmentation、torchvision_keypoint_detection等。以torchvision_detection为例其detect方法会读取context.conf_threshold过滤低置信度框并生成矩形标注torchvision_detection.py。项目Project实战示例创建项目创建项目时可选定义标签project create的--labels与task create格式相同参见上文任务示例。基础示例在默认服务器http://localhost创建 new project标签来自 labels.jsoncvat-cli project create new project --labels labels.json从数据集创建COCO 格式cvat-cli project create new project --dataset_path coco.zip --dataset_format COCO 1.0从数据集创建并每秒检查导入状态cvat-cli project create new project --dataset_path coco.zip --dataset_format COCO 1.0 \ --completion_verification_period 1实现上ProjectCreate.execute调用client.projects.create_from_dataset(...)其中--dataset_path与--dataset_format默认CVAT 1.1仅在指定数据集路径时生效commands_projects.py。删除项目cvat-cli project delete 100 101 102列出项目cvat-cli project ls # 列出全部项目 cvat-cli project ls --json list_of_projects.json # 保存为 JSON备份项目cvat-cli project backup 25 project_25.zip从备份创建项目cvat-cli project create-from-backup project_backup.zip导出数据集cvat-cli project export-dataset --format CVAT for images 1.1 103 project.zip # 导出项目 103 cvat-cli project export-dataset --format COCO 1.0 --with-images yes 104 project.zip # COCO 格式并包含图片 cvat-cli project export-dataset --format CVAT for images 1.1 105 # 保存到当前目录使用服务器生成文件名--with-images接受布尔值如yes/no由to_bool转换command_base.py。从数据集创建任务为项目 106 从 coco.zipCOCO 1.0格式创建任务cvat-cli project import-dataset --format COCO 1.0 106 coco.zip前提条件项目必须拥有与导入数据集兼容的标签上传的数据集必须包含图像数据因为该命令会创建带图像和标注的新任务与task import-dataset仅导入标注不同project import-dataset同时创建任务并导入图像与标注见 commands_projects.py。函数Function实战示例仅 Enterprise/Cloud注意本节功能只能在 CVAT Enterprise 或 CVAT Cloud 中使用。函数相关命令接受与task auto-annotate相同的 AA 函数即实现 SDK 的自动标注函数接口因此实现方式与--function-module/--function-file/-p的用法与上文一致。创建并使用 torchvision 检测函数创建使用 torchvision 检测模型的函数并为其运行 agentcvat-cli function create-native Faster R-CNN \ --function-module cvat_sdk.auto_annotation.functions.torchvision_detection \ -p model_namestr:fasterrcnn_resnet50_fpn_v2 cvat-cli function run-agent ID printed by previous command \ --function-module cvat_sdk.auto_annotation.functions.torchvision_detection \ -p model_namestr:fasterrcnn_resnet50_fpn_v2其中第一条命令会打印新函数的 IDrun-agent需要用到它。create-native支持--visibility private|public默认private并在服务端/api/functions端点注册providernative的函数commands_functions.py。创建并运行 SAM2 追踪函数cvat-cli function create-native SAM2 \ --function-fileCVAT_DIR/ai-models/tracker/sam2/func.py \ -p model_idstr:facebook/sam2.1-hiera-tiny cvat-cli function run-agent ID printed by previous command \ --function-fileCVAT_DIR/ai-models/tracker/sam2/func.py \ -p model_idstr:facebook/sam2.1-hiera-tiny这里的CVAT_DIR指 CVAT 源码仓库目录ai-models/tracker/sam2/func.py即仓库中的 SAM2 追踪 AA 函数实现。关于 SAM2 的详细部署与使用说明参见 SAM2 Tracker 文档AI Agent 变体可通过 AA 函数在用户侧运行为 CVAT Online 与 Enterprise 带来 SAM2 追踪能力且推荐使用 GPU 以获得性能。删除函数cvat-cli function delete 100 101function delete会逐个删除函数404 时给出警告其他失败打印错误commands_functions.py。小结命令模型统一cvat-cli common resource action options三级--help可随时查阅全部参数。认证首选 PAT通过CVAT_ACCESS_TOKEN环境变量注入或使用profile/config持久化服务器与令牌避免凭据进入 shell 历史--profile提供单命令级的快速切换。全生命周期覆盖任务与项目均支持创建、列表、删除、备份/恢复、数据集导入导出任务还支持帧下载与本地 AA 函数自动标注。自动标注体系task auto-annotate即时模式与function create-nativerun-agentagent 模式Enterprise/Cloud共用同一套 AA 函数协议仓库预置了多个 torchvision 函数并支持通过-p NAMETYPE:VALUE参数化。如需继续深入可阅读仓库中的 cvat-cli 源码、cvat-cli 包说明、自动标注 API 文档 与访问令牌文档。【免费下载链接】cvatComputer Vision Annotation Tool (CVAT) is a leading platform for building high-quality visual datasets for vision AI. It offers open-source, cloud, and enterprise products, as well as labeling services, for image, video, and 3D annotation with AI-assisted labeling, quality assurance, team collaboration, analytics, and developer APIs.项目地址: https://gitcode.com/GitHub_Trending/cvat/cvat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考