CVAT 接入第三方模型：4 步在标注画布上跑出检测框-平芜编程栈

CVAT 接入第三方模型：4 步在标注画布上跑出检测框

【免费下载链接】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

想让自研检测模型接入 CVAT，在标注画布上直接产出检测框？整套流程就是 CVAT 算法集成的最小闭环，交付物共 4 个：serverless 容器一组、模型函数一个、推理请求一次、可被画布渲染的检测结果一批。终点验收很简单：在标注页的 Automatic annotation 对话框里选中 YOLO v7、确认标签映射、点 Annotate，检测框出现在画布上。

验收目标倒推：跑通需要哪四样东西

这一步不敲命令，先把"完成"的样子钉死，再倒推出依赖。

验收动作就是下面这张图里的操作：模型出现在下拉框、标签映射确认无误、点 Annotate 出框。

要支撑这个动作，四样东西缺一不可：

serverless 容器在跑：Nuclio 控制平面 + 开启CVAT_SERVERLESS的 CVAT 后端；
至少一个模型函数已部署，且function.yaml里声明了名称、类型和标签；
前端LambdaManager能跑通 list → run → listen → call 四个方法；
模型标签与任务标签可建立映射。

启动 serverless 容器的一条命令

这一步把 Nuclio 容器拉起来，让 CVAT 后端能连上算法网关，做完得到"模型服务注册可用"的状态。前提是你的基础 CVAT 栈已经docker compose up -d跑着。

# 项目根目录执行，叠加 serverless 配置 docker compose -f docker-compose.yml -f components/serverless/docker-compose.serverless.yml up -d

这条命令把 docker-compose.serverless.yml 叠加到基础栈上：新增nucliodashboard 容器（Nuclio 1.16 控制平面），并给cvat_server注入CVAT_SERVERLESS: 1，后端由此启用算法网关逻辑。

验证：用同样的两个-f参数把末尾的up -d换成ps，看到 nuclio 容器处于 running 状态即成功。

部署 YOLO v7 示例，让模型出现在下拉框

这一步把仓库自带的 YOLO v7 示例推到 Nuclio，做完得到"模型列表里多出 YOLO v7"。

deploy_cpu.sh 会扫描指定目录下所有function.yaml，逐个构建镜像并nuctl deploy；GPU 版 deploy_gpu.sh 逻辑相同，只是匹配function-gpu.yaml。只部署 yolov7 一个模型时把目录传进去：

./serverless/deploy_cpu.sh serverless/onnx/WongKinYiu/yolov7

每个模型函数目录就三类文件，以 yolov7 示例为准：

function.yaml：声明名称、类型、标签——CVAT 发现模型全靠它；
main.py：init_context加载模型，handler处理每次推理请求；
model_handler.py：具体 ONNX 推理实现。

function.yaml头部长这样，spec里的标签列表就是下拉框里那个映射的来源：

metadata: name: onnx-wongkinyiu-yolov7 annotations: name: YOLO v7 # 下拉框中显示的名称 type: detector # 模型种类：detector / interactor / tracker / reid spec: | [ { "id": 0, "name": "person", "type": "rectangle" }, ... ] # 标签列表

验证：脚本最后一步会执行nuctl get function --platform local，列表里出现 onnx-wongkinyiu-yolov7 且状态 READY，就说明函数上线了。

推理接口怎么调：LambdaManager 的四个方法

这一步看清前端如何把一次"点 Annotate"变成模型调用，核心都在 lambda-manager.ts 里。

run是发起推理的入口，把任务 ID 和模型 ID 一起 POST 给后端：

async run(taskID: number, model: MLModel, args: any) { const body = { ...args, task: taskID, function: model.id }; return serverProxy.lambda.run(body); // 提交到后端 api/lambda }

它返回一张请求单：id（请求号）、status（排队/运行/完成）、progress（进度）。之后listen(requestID, callback)注册状态回调，内部按排队 30 秒、运行 10 秒的间隔轮询直到终态；call(taskID, model, args)在终态后拉取检测结果。后端路由挂在api/lambda/下，见 cvat/apps/lambda_manager/urls.py。

验证：在对话框点 Annotate，进度条能从 0 走到 100，说明 run + listen 这条链路完全通了。

结果格式对不上怎么办：检测形状与标签映射

这一步弄清推理结果长什么样、标签在哪里对齐——两者都满足，框才会落上画布。

yolov7 函数每一帧返回的是一段这样的数组（仓库里前端对应MinimalShape、InteractorShape等类型）：

[ { "confidence": "0.87", "label": "person", "points": [x1, y1, x2, y2], "type": "rectangle" } ]

points是左上、右下两个角点，左上角为原点，这正是 CVAT 的标准图像坐标系。验证：推理成功后在浏览器 Network 面板里看call对应的响应，数组结构与函数返回一致。

⚠️ 一个容易踩的坑：模型标签来自function.yaml的spec，CVAT 要求它能与任务标签建立映射——对话框里 "Setup mapping between labels and attributes" 就是干这个的，后端会在 views.py 里做兼容性校验。"状态成功但画布没框"，十有八九是这步映射没配。

现象 → 方向 → 文件：排错速查表

卡住时按表定位，比从头读源码快。

现象	排查方向	对应文件
模型不在下拉框	函数未部署或未就绪	先`nuctl get function --platform local`；docker-compose.serverless.yml
函数构建失败	基础镜像或依赖缺失	函数目录的 Dockerfile、function.yaml 的 build 段
推理排队久、速度慢	未启用 GPU 部署	deploy_gpu.sh 与函数目录的 function-gpu.yaml
画布没有框	标签映射未配置或不匹配	function.yaml 的 spec、views.py
框位置偏移	ROI 裁剪或坐标变换问题	views.py 的`_get_roi`、model_handler.py 的 letterbox

下一步可以做什么

跑通之后，三个方向任选：

写自己的函数：复制 yolov7 目录，替换模型文件与spec标签，重新部署即可；
换模型种类：facebookresearch/sam 是 interactor 交互模型，openvino/omz 有现成 OpenVINO 示例，pytorch/ 下还有 MMPose 姿态估计；
深入服务端：标签校验、ROI 裁剪、结果转换的完整逻辑都在 cvat/apps/lambda_manager/views.py，值得通读一遍。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考