CVAT Guide 功能实战指南：为标注员编写与配置标注规范（Specification）

CVAT Guide 功能实战指南为标注员编写与配置标注规范Specification【免费下载链接】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 的Guide标注规范功能展开讲解如何利用内置的 Markdown 编辑器为项目Project和任务Task编写标注规范并让标注员在标注界面中随时查看。读完本文你将掌握规范的创建、编辑权限配置、自动弹出与手动查看机制以及底层的数据模型与权限策略实现。Guide 功能概览用 Markdown 承载标注规范Guide是 CVAT 提供的内置 Markdown 编辑器功能用于为标注员编写标注规范Specification。规范一旦创建并提交就会与项目或任务绑定标注员打开对应作业Job时即可从标注界面访问。其核心使用模型如下规范可以挂载到Projects项目或Tasks任务上挂载流程对个人用户和组织Organization完全一致规范以 Markdown 文本存储支持富文本、代码块、图片、待办清单等多种元素。从后端源码看规范对应AnnotationGuide数据模型定义在 cvat/apps/engine/models.py通过OneToOneField分别与Task、Project关联二者必填其一target属性负责取回所挂载的对象markdown字段以TextField存储规范正文默认为空字符串get_asset_ids_from_markdown()静态方法通过正则\(/api/assets/(uuid)\)从 Markdown 中提取引用的图片资源 ID用于资源生命周期管理。对应的 REST API 由 cvat/apps/engine/views.py 与 cvat/apps/engine/serializers.py 提供路由为/guides创建、查询与/guides/{id}读取、更新、删除序列化器会在写入时校验 Markdown 中引用的资源数量与合法性。为 Project 添加标注规范将规范添加到Projects的步骤如下进入Projects页面点击目标项目在Project description项目描述区域下方点击Edit编辑在 Markdown 编辑器 中输入规范内容然后点击Submit提交。规范保存后即与项目绑定项目下所有作业的标注员都能看到它。编辑权限Projects个人用户只有项目所有者owner和项目负责人assignee可以编辑规范组织Organization除上述两者外组织所有者organization owner和维护者maintainer也可以编辑。为 Task 添加标注规范将规范添加到Task的步骤如下进入Tasks页面点击目标任务在Task description任务描述区域下方点击Edit编辑在 Markdown 编辑器中输入规范内容然后点击Submit提交。编辑权限Tasks个人用户只有任务所有者owner和任务负责人assignee可以编辑规范组织Organization只有任务所有者、维护者maintainer和任务负责人assignee可以编辑规范。权限背后的源码实现上述编辑权限并非简单的界面控制而是由 OPAOpen Policy Agent策略引擎强制执行的。权限规则定义在 cvat/apps/engine/rules/annotationguides.rego核心逻辑包括管理员admin默认拥有全部权限沙箱非组织环境下view权限仅授予目标 owner/assignee 或作业负责人job staffcreate/update/delete在沙箱环境要求操作者是目标 owner/assignee组织环境下维护者及以上角色可管理所有规范普通成员则需同时满足是目标 owner/assignee 或 job staff的条件。该策略还配有完整的测试矩阵 cvat/apps/engine/rules/tests/configs/annotationguides.csv覆盖view/create/update/delete四种 scope 在沙箱、组织、管理员三种上下文下的预期行为例如沙箱环境下仅Target:owner, Target:assignee可GET /guides/{id}组织环境下 Maintainer 或目标 owner/assignee 可执行写操作。标注员如何访问标注规范规范的展示时机遵循以下规则当作业处于new annotation新标注状态时规范会自动打开即被分配的用户开始处理某个Project或Task内的第一个作业时规范会自动弹出用户在同一 Project/Task 内切换到其他作业时规范不会再次自动打开如果 Project/Task 被重新分配给另一位标注员新标注员打开第一个作业时规范会自动显示但后续作业同样不会重复弹出。强制每次自动打开?openGuide参数如果你希望规范每次都自动打开可以在分享给标注员的作业 URL 末尾追加?openGuide参数/tasks/task_id/jobs/job_id?openGuide例如https://app.cvat.ai/tasks/taskID/jobs/jobID?openGuide该参数的解析逻辑可以在前端容器组件 cvat-ui/src/containers/annotation-page/annotation-page.tsx 中找到页面初始化时通过searchParams.has(openGuide)读取标记随后将其从 URL 中移除并替换地址避免刷新或二次进入时重复触发。手动打开规范标注员也可以随时手动打开规范打开作业进入标注界面点击右上角的Guide 按钮图标见 guide_icon.jpg。手动打开与自动弹出的实现在 cvat-ui/src/components/annotation-page/top-bar/right-group.tsx 中点击按钮会通过jobInstance.guide()拉取规范并以模态框modal形式展示 Markdown 内容同时前端用localStorage中的seenGuides数组记录已看过的 guideId——只有尚未看过该规范或 URL 携带openGuide标记时才自动打开这正是同一任务后续作业不再重复弹出这一交互规则的来源。Markdown 编辑器指南Guide 的 Markdown 编辑器采用双栏布局左侧为编辑区右侧为实时预览区。在左栏输入内容右栏会立即显示格式化后的结果。你可以直接书写原始 Markdown也可以使用编辑器顶部的工具栏序号功能说明1文本格式加粗、斜体、删除线。2水平分割线插入一条水平线。3标题添加标题/小标题提供下拉列表选择 1 至 6 级标题。4链接添加链接。注意左键点击链接会在当前窗口打开。5引用添加引用块。6行内代码添加单行代码。7代码块添加多行代码块。8注释添加注释。注释仅对 Guide 编辑者可见标注员不可见适合放置内部说明。9图片有两种用法先将图片上传到外部资源再把链接粘贴进编辑器或者直接把图片拖拽进编辑器图片会上传到 CVAT 服务器并自动插入到规范中。10列表添加无序列表、有序列表和任务清单checklist。11面板切换隐藏编辑器面板可只显示右栏、双栏同显或只显示左栏。12全屏启用全屏模式。图片资源与注释仅编辑器可见的实现拖拽上传图片前端在 cvat-ui/src/components/md-guide/annotation-guide-page.tsx 中实现图片上传上传后图片以/api/assets/{uuid}形式写入 Markdown后端通过AnnotationGuide.get_asset_ids_from_markdown()提取这些 ID用于校验与清理相关迁移见 0071_annotationguide_asset.py。注释隔离工具栏第 8 项的注释在渲染时会被过滤标注员看到的预览不含注释内容而编辑者编辑时仍可见属于典型的编辑侧元信息用法。从源码理解 Guide 的完整链路综合前后端实现Guide 功能的一条完整数据链路为编辑入口在项目/任务详情页点击 Edit前端 md-guide-control.tsx 通过history.push(/{projects|tasks}/{id}/guide)跳转到规范编辑页编辑与保存编辑页调用/guidesREST API 创建或更新AnnotationGuide记录标注端读取标注员打开作业时前端通过jobInstance.guide()获取markdown文本并按是否携带openGuide参数 / 是否已看过决定是否自动弹出或点击右上角 Guide 按钮手动打开权限兜底整个流程的读写操作最终都经过 OPA 的 annotationguides.rego 策略校验保证谁编辑、谁查看的边界不会被绕过。视频教程CVAT 官方文档附带了一段介绍 Guide 功能用法的视频教程可在原始文档 specification.md 中查看建议结合上文步骤与源码分析一同实践先在项目上挂一份规范体验自动弹出再尝试?openGuide参数与手动按钮最后在组织环境下验证不同角色的编辑权限差异。【免费下载链接】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），仅供参考