CVAT Helm 部署 AI Agent 完全指南values.yaml 配置、注册生命周期与排障实操【免费下载链接】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 的 AI Agent 机制允许你将任意模型以独立进程的形式接入 CVAT由 Agent 轮询平台任务并执行自动标注。本文以 CVAT 官方 Helm 部署指南为主体完整覆盖 Helm Chart 的注册/注销生命周期、集群准备、values.yaml全部配置项、部署验证与升级回滚操作并结合 CVAT 仓库中cvat-cli的 Agent 实现源码说明注册 Job 和轮询机制的底层原理帮助你在 Kubernetes 上可控、可观测地运行自己的 CVAT Agent。Helm 部署方式的生命周期总览相比 Docker Compose 部署可参考 compose-agents-userguide.md 中的 Compose 方式Helm 适合熟悉 Kubernetes、需要更强部署控制力和灵活性的用户。CVAT 的 Helm Chart 自动化管理 Agent 的完整生命周期Pre-install / pre-upgrade hook—— 一个 Kubernetes Job 使用cvat-cli将你的模型注册为 CVAT 中的一个 function注册产生的 function ID 被写入 ConfigMap供 Agent Deployment 读取使用Deployment—— Agent Pod 启动后开始轮询 CVAT 获取新任务并用你的模型处理这些任务Pre-delete hook—— 当你helm uninstall时另一个 Job 自动从 CVAT 注销该 function。这意味着你无需手动执行任何cvat-cli命令Chart 会自动完成注册与注销。这一机制可以从 CVAT 仓库的 CLI 源码中得到印证。注册对应的就是cvat-cli的functions create-native命令它读取本地函数定义以native为 provider 构造远程函数描述并向 CVAT 的POST /api/functions接口发起请求成功后把新 function 的 ID 打印到标准输出——commands_functions.py 中的FunctionCreateNative类实现了这一流程注销则对应FunctionDelete类对DELETE /api/functions/{function_id}的调用。Helm 的 pre-install/pre-delete hook Job 本质上就是在容器内自动执行这两类操作。Agent 侧的运行逻辑由 agent.py 实现。从源码结构看Agent 内置了带指数退避的轮询调度频繁/低频两类轮询间隔均值加抖动并通过RecoverableExecutor包装ProcessPoolExecutor在 worker 崩溃时自动重建进程池——这解释了为什么 Agent Pod 长时间运行也具备一定容错性。检测、交互如 SAM 系列和追踪三类函数分别由 agent_driver_detection.py、agent_driver_interaction.py、agent_driver_tracking.py 三个驱动实现。集群准备部署前需要满足的条件要使用 Helm 部署 CVAT Agent需要准备条件说明运行中的 Kubernetes 集群v1.23 及以上kubectl已配置好与集群的通信Helm 3客户端工具网络连通集群内到 CVAT 实例的网络可达CVAT 访问令牌用于认证的 access token如果使用 GPU还需确认集群已安装 NVIDIA device plugin且节点.status.allocatable中暴露了nvidia.com/gpu资源。Chart 位置说明原指南给出的操作是克隆 CVAT 仓库后进入ai-models/agents_deployment/helm目录。需要注意在当前仓库中ai-models/README.md 明确说明ai-models文件夹已迁移到独立的cvat-models仓库因此 Helm Chartagents_deployment/helm目录应到cvat-models仓库中获取Chart 内容与下文配置说明一致。配置 values.yaml打开 Chart 中的values.yaml需要配置以下各部分。ImageAgent 镜像指定包含 Agent 实现的 Docker 镜像image: repository: cvat/sam2_agent tag: latest pullPolicy: IfNotPresent你可以自己构建镜像也可以直接使用 CVAT 官方镜像仓库中提供的镜像。Agent 通用配置agent: function_name: myfunction # 函数的唯一名称按用户维度唯一 replicaCount: 1 # Agent 副本数 org_slug: # 组织 slug留空表示个人作用域 use_cuda: false # 镜像支持 GPU 时设为 true cvat_base_url: https://app.cvat.ai # 你的 CVAT 实例地址 cvat_access_token: # 访问令牌不推荐明文——请用 secret_env安全地存放访问令牌不要明文写入令牌而是创建一个 Kubernetes Secret 并引用它kubectl -n cvat-agents create secret generic cvat-agent --from-literaltokenYOUR_TOKEN_HERE然后在values.yaml中引用agent: cvat_access_token: # 留空使 secret 生效 secret_env: - name: CVAT_ACCESS_TOKEN secretName: cvat-agent secretKey: token注意如果直接设置cvat_access_token它会覆盖secret_env且令牌会出现在 Helm release 历史和 Pod spec 中。模型配置preset 与参数覆盖Chart 内置了常用模型的预设。选择一个 preset并可选地在其基础上覆盖或追加参数agent: preset: sam2 # 可选值: yolo, sam2, transformers-detr, custom # 在 preset 之上覆盖或追加参数: modelParamsOverride: {} # model_id: # type: str # value: facebook/sam2.1-hiera-large资源配额agent: resources: limits: cpu: 1 gpu: 1 # 仅在 use_cuda 为 true 时生效 requests: cpu: 200m gpu: 1 # 仅在 use_cuda 为 true 时生效 memory: 256Mi当use_cuda: true时gpu值会被翻译为nvidia.com/gpu资源请求/限制。节点调度可选通过nodeSelector、affinity和tolerations控制 Agent Pod 的调度位置agent: nodeSelector: {} # nodetype: gpu affinity: {} tolerations: [] # - key: nvidia.com/gpu # operator: Exists # effect: NoSchedule额外卷挂载可选如果模型需要额外数据目录可将附加卷挂载进 Agent 容器agent: extraVolumeMounts: [] # - name: model-cache # mountPath: /models extraVolumes: [] # - name: model-cache # persistentVolumeClaim: # claimName: model-cache-pvc部署与验证values.yaml配置完成后执行安装helm install my-agent . -n cvat-agents --create-namespaceHelm 会依次为注册 Job 创建 ServiceAccount、Role 和 RoleBinding运行 function 注册 Jobpre-install hook部署 Agent Pod。验证注册 Job 已完成kubectl get jobs -n cvat-agents -l app.kubernetes.io/instancemy-agent验证 Agent Pod 处于运行状态kubectl get pods -n cvat-agents -l app.kubernetes.io/instancemy-agent,app.kubernetes.io/component!job查看 Agent 日志kubectl logs -n cvat-agents -l app.kubernetes.io/instancemy-agent,app.kubernetes.io/component!job -fAgent 正常运行时的轮询/心跳日志示例最后到 CVAT UI 中确认模型已注册并可被选择。实际运行 Agent 驱动的模型追踪以 SAM2 tracker 为例在标注界面对目标画一个框然后点击 Run annotation function选择需要追踪的帧数例如 14 帧。触发后 CVAT 会向 Agent 派发追踪任务Agent Pod 侧的日志可以看到逐帧处理过程追踪完成后CVAT 中的标注会随追踪结果自动更新。升级 release修改配置例如调整副本数或模型参数后执行helm upgrade my-agent . -n cvat-agentspre-upgrade hook 会以新参数重新运行注册 Job。清理卸载 release 即可完成全部清理helm uninstall my-agent -n cvat-agentspre-delete hook 会在删除所有 Kubernetes 资源之前自动运行注销 Job 把 function 从 CVAT 中移除无需手动执行任何cvat-cli命令。常见问题排查注册 Job 失败查看 Job 日志kubectl logs -n cvat-agents -l app.kubernetes.io/componentjob常见原因cvat_base_url配置错误——集群必须能访问该地址cvat_access_token无效或已过期——在 CVAT UI 中重新生成function_name错误——该名称必须按用户维度唯一。Agent Pod 处于 Pending 状态kubectl describe pod -n cvat-agents -l app.kubernetes.io/nameagent常见原因集群 CPU/内存资源不足use_cuda: true但没有可用 GPU 节点或 NVIDIA device plugin 未安装nodeSelector/tolerations与任何节点都不匹配。Agent 能运行但模型不工作检查preset与modelParamsOverride确认参数与镜像内的模型匹配确认镜像中确实包含预期的模型文件查看 Agent 日志中模型加载相关的报错。ConfigMap 异常注册 Job 会创建名为release-config的 ConfigMap 保存 function ID。出问题时可以直接检查kubectl get configmap -n cvat-agents -l app.kubernetes.io/instancemy-agent -o yaml如需彻底重来卸载后重新安装helm uninstall my-agent -n cvat-agents helm install my-agent ./chart -n cvat-agents小结CVAT 的 Helm Agent 方案把“注册 function → 部署 Agent → 注销 function”收敛为一次helm install/uninstall操作注册与注销由 pre-install / pre-delete hook Job 借助cvat-cli自动完成Agent 本身由带副本数和 GPU 配额的 Deployment 承载。理解 Chart 生命周期与values.yaml各配置项的对应关系后你可以把任意自研模型快速接入 CVAT 的自动标注工作流并通过 K8s 原生的标签选择器、日志和 describe 命令完成全链路可观测运维。【免费下载链接】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），仅供参考