2026/9/14 14:26:37
FEATURED · 精选文章 
CVAT Docker Compose 部署 AI Agent 实战指南把自研模型跑成 CVAT 自动标注函数【免费下载链接】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/cvatCVAT 的 Agent 机制允许把用户自研的模型如 SAM2 分割跟踪模型注册为服务端函数再由一个轮询 CVAT 任务队列的 Agent 容器负责实际推理。本篇指南介绍如何用 Docker Compose 在一台普通 Linux 机器上完成 CVAT Agent 的完整生命周期管理——注册函数、拉起 Agent、验证跟踪效果、注销函数——并深入源码解释 Agent 的轮询与任务获取机制读完即可脱离 Kubernetes 环境独立部署自己的自动标注服务。方案总览三步走的工作流Docker Compose 方案适合不熟悉 Kubernetes、只想快速把 Agent 跑起来的用户熟悉 Kubernetes 的读者可参考 Helm 部署指南该方案由 Helm hooks 自动完成注册与注销。Compose 工作流整体只有三步注册函数在 CVAT 中把模型注册为一个 lambda functionCompose 文件内部通过cvat-cli完成运行 AgentAgent 容器启动后持续轮询 CVAT拉取新的标注请求annotation request并用你的模型处理清理注销Agent 不再需要时从 CVAT 注销deregister该函数。与 Helm 方案由 Chart 的 pre-install / pre-delete hook 自动化注册、注销不同Compose 方案通过独立的 compose 服务来完成同一件事手动控制粒度更细。环境准备在运行 Agent 的机器上需要安装Docker EngineDocker Compose 插件安装步骤以 Docker 官方文档为准参考仓库 ai-models/README.md 所在的仓库结构Agent 部署所需的镜像与 Compose 模板随 CVAT 生态仓库分发。此外还需要满足两个前提本机可以访问目标 CVAT 实例的网络持有一个 CVAT 访问令牌Access Token可在 CVAT 界面的 Profile → Security 页面生成。提示在当前仓库中ai-models/目录的 README 已声明该目录整体迁移到了独立的 cvat-models 仓库主仓库仅保留指引。因此获取 Agent 的 Docker Compose 文件与 Dockerfile 模板时应从 cvat-models 仓库的agents_deployment/sam2目录获取主仓库 ai-models/README.md 给出了迁移说明。配置 .env 文件Docker Compose 的全部配置通过 Agent 目录下的.env文件提供包含以下 8 个变量变量说明CVAT_BASE_URL目标 CVAT 实例地址默认为https://app.cvat.aiCVAT_ACCESS_TOKEN用于 cvat-cli 连接 CVAT 的访问令牌在 CVAT UI 的 Profile → Security 页获取FUNCTION_NAME要在 CVAT 中注册的函数名例如SAM2或MY_GREAT_MODELIMAGE_URLAgent 镜像地址。可自行基于提供的 Dockerfile 构建或使用 CVAT 官方 DockerHub 镜像AGENTS_COUNTAgent 副本数取决于模型负载ORG_SLUG组织 slug。若希望把函数共享给整个组织必须提供COMPOSE_PROFILES选择 CPU 或 GPU 运行。使用 GPU 时设为gpu要求 Linux NVIDIA GPU NVIDIA 驱动 NVIDIA Container Toolkit GPU 版镜像MODEL_CONFIG_PARAMS传给模型适配函数的参数每个模型不同具体格式参考对应模型文档原指南指出 transformers 目录下有解释性示例可参考以一个 SAM2 跟踪 Agent 的 CPU 部署为例.env可写成CVAT_BASE_URLhttps://app.cvat.ai CVAT_ACCESS_TOKENyour_access_token FUNCTION_NAMESAM2 IMAGE_URLcvat/sam2_agent:latest AGENTS_COUNT1 ORG_SLUG COMPOSE_PROFILEScpu MODEL_CONFIG_PARAMSmodel_specific_params其中FUNCTION_NAME对每个用户需保持唯一MODEL_CONFIG_PARAMS的取值因模型而异配置错误是部署失败的最常见原因之一见文末排障。启动 Agentdocker compose up进入 Agent 目录后执行docker compose upCompose 会依次完成拉取.env中指定的镜像本地已有则跳过→ 运行函数注册服务将模型注册为 CVAT 中的 lambda function → 启动AGENTS_COUNT个 Agent 副本。随后打开 CVAT UI 即可看到已注册的模型出现在函数列表中。Agent 是如何轮询任务的源码级机制Agent 容器内运行的是cvat-cli的 agent 子命令。从 命令定义文件 可以看到三个与 Compose 服务一一对应的核心命令create-nativeL20创建可被本地 Agent 驱动的 CVAT 函数即“注册”步骤run-agentL100启动 Agent 主循环即docker compose up后常驻的容器进程deleteL73删除函数即注销步骤。Agent 主循环实现在 agent.py 的_Agent类L240 起中其核心设计值得了解SSE 事件流 低频轮询的混合等待。Agent 启动一个后台线程通过/api/functions/queues/{queue_id}/watch端点连接服务器端的 Server-Sent Events 事件流源码。连接成功后轮询间隔从默认的 60 秒拉长到 10 分钟_POLLING_INTERVAL_MEAN_FREQUENT/_POLLING_INTERVAL_MEAN_RARE见 常量定义事件流中收到newrequest事件才立刻唤醒主循环去取任务——即有通知就立即响应没通知就低频兜底兼顾实时性与服务器压力。若事件流断开则以指数退避方式重连退避实现。请求分类与优先级。Agent 按优先级处理两类请求interactive交互式如用户在 UI 里点Run annotation function触发的跟踪请求优先于batch批处理请求处理批任务期间若来了交互请求会立即插队处理见 任务处理循环。任务生命周期 API。Agent 与 CVAT 后端之间的任务流转全部走 lambda 队列 APIacquire获取请求、update上报进度每 30 秒心跳一次、complete提交结果失败自动指数退避重试最多 3 次、fail上报异常。CVAT 服务端的 lambda 网关与路由定义可参考 lambda_manager/urls.py其 REST 契约包含函数列表/详情查询、函数调用与请求状态跟踪等端点。本地缓存自清理。Agent 会下载任务媒体数据到本地缓存_TaskCacheLimiter源码限制缓存最多保留 10 个任务超限时删除最久未使用的任务缓存防止 Agent 长期运行占满磁盘。进程崩溃自愈。模型推理运行在独立子进程中RecoverableExecutor源码在子进程崩溃BrokenExecutor时自动重建进程池保证 Agent 主循环不中断。验证 Agent 工作正常以 SAM2 跟踪模型为例验证步骤打开一个已有的 Job画一个新的多边形polygon点击Run annotation function运行 AI 跟踪观察终端日志可以看到 Agent 收到标注请求并开始处理的日志输出。逐帧向后移动观察多边形被逐帧跟踪、结果自动写回 CVAT即说明整条链路UI 触发 → CVAT 排队 → Agent 取任务 → 模型推理 → 结果回写工作正常。清理停止容器与注销函数在运行docker compose up的终端按CTRL C可以停止容器但这只是停止容器不会从 CVAT 注销函数——函数记录仍留在服务端。要完整清理执行docker compose run --rm cvat-function-deregister该服务在 Compose 内部调用cvat-cli functions delete完成注销。如果连本地数据卷也不想保留可以直接推倒重来docker compose down -v常见问题排查1..env配置错误最常见确认CVAT_BASE_URL、CVAT_ACCESS_TOKEN、FUNCTION_NAME、IMAGE_URL、MODEL_CONFIG_PARAMS均正确Base URL 必须是容器可达的地址Token 未过期函数名与期望一致镜像地址可拉取。2. 共享数据卷状态异常多副本 Agent 之间通过共享数据卷交换函数 ID 等状态注册服务写入FUNCTION_ID文件供 Agent 读取。可以用下面的命令检查卷内容是否正常docker run --rm -v sam2_shared-data:/mnt alpine cat /mnt/FUNCTION_ID若文件缺失或内容异常通常是上一次注册流程被中断导致的脏状态直接docker compose down -v清掉卷后重新docker compose up即可。3.MODEL_CONFIG_PARAMS参数不匹配参数格式因模型而异务必对照所用模型的文档逐项核对参数错误通常表现为注册成功但 Agent 处理请求时报错此时查看docker compose logs中 Agent 的异常堆栈定位具体问题。小结Docker Compose 方案把 CVAT Agent 的部署抽象为配置.env→docker compose up→cvat-function-deregister三个动作注册与注销分别由cvat-cli functions create-native/delete完成Agent 本体则依赖 SSE 事件通知加低频轮询的混合机制从 lambda 队列中获取并处理标注请求Agent 核心实现。理解这套机制后无论是排查 Agent收不到任务还是处理结果未回写的问题都可以沿着acquire → update → complete/fail这条 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），仅供参考
CVAT Docker Compose 部署 AI Agent 实战指南：把自研模型跑成 CVAT 自动标注函数
CVAT Docker Compose 部署 AI Agent 实战指南把自研模型跑成 CVAT 自动标注函数【免费下载链接】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/cvatCVAT 的 Agent 机制允许把用户自研的模型如 SAM2 分割跟踪模型注册为服务端函数再由一个轮询 CVAT 任务队列的 Agent 容器负责实际推理。本篇指南介绍如何用 Docker Compose 在一台普通 Linux 机器上完成 CVAT Agent 的完整生命周期管理——注册函数、拉起 Agent、验证跟踪效果、注销函数——并深入源码解释 Agent 的轮询与任务获取机制读完即可脱离 Kubernetes 环境独立部署自己的自动标注服务。方案总览三步走的工作流Docker Compose 方案适合不熟悉 Kubernetes、只想快速把 Agent 跑起来的用户熟悉 Kubernetes 的读者可参考 Helm 部署指南该方案由 Helm hooks 自动完成注册与注销。Compose 工作流整体只有三步注册函数在 CVAT 中把模型注册为一个 lambda functionCompose 文件内部通过cvat-cli完成运行 AgentAgent 容器启动后持续轮询 CVAT拉取新的标注请求annotation request并用你的模型处理清理注销Agent 不再需要时从 CVAT 注销deregister该函数。与 Helm 方案由 Chart 的 pre-install / pre-delete hook 自动化注册、注销不同Compose 方案通过独立的 compose 服务来完成同一件事手动控制粒度更细。环境准备在运行 Agent 的机器上需要安装Docker EngineDocker Compose 插件安装步骤以 Docker 官方文档为准参考仓库 ai-models/README.md 所在的仓库结构Agent 部署所需的镜像与 Compose 模板随 CVAT 生态仓库分发。此外还需要满足两个前提本机可以访问目标 CVAT 实例的网络持有一个 CVAT 访问令牌Access Token可在 CVAT 界面的 Profile → Security 页面生成。提示在当前仓库中ai-models/目录的 README 已声明该目录整体迁移到了独立的 cvat-models 仓库主仓库仅保留指引。因此获取 Agent 的 Docker Compose 文件与 Dockerfile 模板时应从 cvat-models 仓库的agents_deployment/sam2目录获取主仓库 ai-models/README.md 给出了迁移说明。配置 .env 文件Docker Compose 的全部配置通过 Agent 目录下的.env文件提供包含以下 8 个变量变量说明CVAT_BASE_URL目标 CVAT 实例地址默认为https://app.cvat.aiCVAT_ACCESS_TOKEN用于 cvat-cli 连接 CVAT 的访问令牌在 CVAT UI 的 Profile → Security 页获取FUNCTION_NAME要在 CVAT 中注册的函数名例如SAM2或MY_GREAT_MODELIMAGE_URLAgent 镜像地址。可自行基于提供的 Dockerfile 构建或使用 CVAT 官方 DockerHub 镜像AGENTS_COUNTAgent 副本数取决于模型负载ORG_SLUG组织 slug。若希望把函数共享给整个组织必须提供COMPOSE_PROFILES选择 CPU 或 GPU 运行。使用 GPU 时设为gpu要求 Linux NVIDIA GPU NVIDIA 驱动 NVIDIA Container Toolkit GPU 版镜像MODEL_CONFIG_PARAMS传给模型适配函数的参数每个模型不同具体格式参考对应模型文档原指南指出 transformers 目录下有解释性示例可参考以一个 SAM2 跟踪 Agent 的 CPU 部署为例.env可写成CVAT_BASE_URLhttps://app.cvat.ai CVAT_ACCESS_TOKENyour_access_token FUNCTION_NAMESAM2 IMAGE_URLcvat/sam2_agent:latest AGENTS_COUNT1 ORG_SLUG COMPOSE_PROFILEScpu MODEL_CONFIG_PARAMSmodel_specific_params其中FUNCTION_NAME对每个用户需保持唯一MODEL_CONFIG_PARAMS的取值因模型而异配置错误是部署失败的最常见原因之一见文末排障。启动 Agentdocker compose up进入 Agent 目录后执行docker compose upCompose 会依次完成拉取.env中指定的镜像本地已有则跳过→ 运行函数注册服务将模型注册为 CVAT 中的 lambda function → 启动AGENTS_COUNT个 Agent 副本。随后打开 CVAT UI 即可看到已注册的模型出现在函数列表中。Agent 是如何轮询任务的源码级机制Agent 容器内运行的是cvat-cli的 agent 子命令。从 命令定义文件 可以看到三个与 Compose 服务一一对应的核心命令create-nativeL20创建可被本地 Agent 驱动的 CVAT 函数即“注册”步骤run-agentL100启动 Agent 主循环即docker compose up后常驻的容器进程deleteL73删除函数即注销步骤。Agent 主循环实现在 agent.py 的_Agent类L240 起中其核心设计值得了解SSE 事件流 低频轮询的混合等待。Agent 启动一个后台线程通过/api/functions/queues/{queue_id}/watch端点连接服务器端的 Server-Sent Events 事件流源码。连接成功后轮询间隔从默认的 60 秒拉长到 10 分钟_POLLING_INTERVAL_MEAN_FREQUENT/_POLLING_INTERVAL_MEAN_RARE见 常量定义事件流中收到newrequest事件才立刻唤醒主循环去取任务——即有通知就立即响应没通知就低频兜底兼顾实时性与服务器压力。若事件流断开则以指数退避方式重连退避实现。请求分类与优先级。Agent 按优先级处理两类请求interactive交互式如用户在 UI 里点Run annotation function触发的跟踪请求优先于batch批处理请求处理批任务期间若来了交互请求会立即插队处理见 任务处理循环。任务生命周期 API。Agent 与 CVAT 后端之间的任务流转全部走 lambda 队列 APIacquire获取请求、update上报进度每 30 秒心跳一次、complete提交结果失败自动指数退避重试最多 3 次、fail上报异常。CVAT 服务端的 lambda 网关与路由定义可参考 lambda_manager/urls.py其 REST 契约包含函数列表/详情查询、函数调用与请求状态跟踪等端点。本地缓存自清理。Agent 会下载任务媒体数据到本地缓存_TaskCacheLimiter源码限制缓存最多保留 10 个任务超限时删除最久未使用的任务缓存防止 Agent 长期运行占满磁盘。进程崩溃自愈。模型推理运行在独立子进程中RecoverableExecutor源码在子进程崩溃BrokenExecutor时自动重建进程池保证 Agent 主循环不中断。验证 Agent 工作正常以 SAM2 跟踪模型为例验证步骤打开一个已有的 Job画一个新的多边形polygon点击Run annotation function运行 AI 跟踪观察终端日志可以看到 Agent 收到标注请求并开始处理的日志输出。逐帧向后移动观察多边形被逐帧跟踪、结果自动写回 CVAT即说明整条链路UI 触发 → CVAT 排队 → Agent 取任务 → 模型推理 → 结果回写工作正常。清理停止容器与注销函数在运行docker compose up的终端按CTRL C可以停止容器但这只是停止容器不会从 CVAT 注销函数——函数记录仍留在服务端。要完整清理执行docker compose run --rm cvat-function-deregister该服务在 Compose 内部调用cvat-cli functions delete完成注销。如果连本地数据卷也不想保留可以直接推倒重来docker compose down -v常见问题排查1..env配置错误最常见确认CVAT_BASE_URL、CVAT_ACCESS_TOKEN、FUNCTION_NAME、IMAGE_URL、MODEL_CONFIG_PARAMS均正确Base URL 必须是容器可达的地址Token 未过期函数名与期望一致镜像地址可拉取。2. 共享数据卷状态异常多副本 Agent 之间通过共享数据卷交换函数 ID 等状态注册服务写入FUNCTION_ID文件供 Agent 读取。可以用下面的命令检查卷内容是否正常docker run --rm -v sam2_shared-data:/mnt alpine cat /mnt/FUNCTION_ID若文件缺失或内容异常通常是上一次注册流程被中断导致的脏状态直接docker compose down -v清掉卷后重新docker compose up即可。3.MODEL_CONFIG_PARAMS参数不匹配参数格式因模型而异务必对照所用模型的文档逐项核对参数错误通常表现为注册成功但 Agent 处理请求时报错此时查看docker compose logs中 Agent 的异常堆栈定位具体问题。小结Docker Compose 方案把 CVAT Agent 的部署抽象为配置.env→docker compose up→cvat-function-deregister三个动作注册与注销分别由cvat-cli functions create-native/delete完成Agent 本体则依赖 SSE 事件通知加低频轮询的混合机制从 lambda 队列中获取并处理标注请求Agent 核心实现。理解这套机制后无论是排查 Agent收不到任务还是处理结果未回写的问题都可以沿着acquire → update → complete/fail这条 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），仅供参考 
