droboticflow/docs/annotation-operations.md
2026-08-18 12:22:11 +08:00

3.8 KiB
Raw Blame History

标注生产闭环

/annotation-operations 提供项目级语义模板、供应商分组、逐段标注、质检、验收、返工和工时统计。平台全局角色仍负责系统权限,业务分工由项目成员关系单独表达:

  • annotator:提交首轮标注或返工 revision。
  • quality_reviewer:对当前 revision 做质检通过或打回。
  • acceptance_reviewer:对质检通过的 revision 做最终验收。

每个成员关系同时绑定 projectId、workgroupId 和 vendorId。除管理员、流程工程师和兼容管理员外,后端只返回当前用户所在分组的任务、模板、分组和工时事件;前端隐藏不是安全边界。

核心接口

  • GET/POST /api/annotation-workgroups
  • GET/POST /api/annotation-memberships
  • GET/POST /api/annotation-templates
  • POST /api/annotation-templates/{id}/publish
  • GET/POST /api/annotation-tasks
  • GET /api/annotation-tasks/{id}
  • POST /api/annotation-tasks/{id}/revisions
  • POST /api/annotation-tasks/{id}/reviews
  • GET /api/annotation-workload-summary

模板必须发布后才能创建任务。时间段必须位于 clip 范围内、不能重叠,置信度必须位于 [0, 1]。质检或验收拒绝会把任务转为 rework 并指向下一 revision,不在工作流 DAG 中建立环。

原生工作流 Annotation Gate

人工审核节点配置 REVIEW_MODE=annotation 后成为原生标注门,另外需要:

  • ANNOTATION_TEMPLATE_ID:当前项目中已发布的模板。
  • ANNOTATION_WORKGROUP_ID:目标供应商分组。
  • ANNOTATION_ASSIGNED_USER_ID:可选的首轮标注员。

Worker 到达该节点后不会启动 Kubernetes Job,也不会创建通用 AuditTask。它会从上游 clips-manifest.json、视频 artifact 和预标 JSON 自动按片段创建 AnnotationTask,并写入 projectId、dataTaskId、workflowId、runId、nodeId、artifactId。Run 保持 waiting_for_audit,直到该节点下所有任务完成首轮 revision、质检和最终验收。

最终验收通过后,Worker 生成 droboticflow.annotation.accepted/v1 的 annotations-manifest.json,记录模板版本、人工 revision、片段、artifact 和 Run lineage,然后从节点 approved 输出恢复同一个 Run。未选择的分支标记为跳过,不启动空上传 Job;质检或验收打回仅创建新 revision。

/annotation-operations 支持通过以下参数从项目或监控页深链进入:

projectId、dataTaskId、workflowId、runId、nodeId、artifactId、taskId。

时间轴交互

标注任务使用真实 artifact 视频预览,并提供:

  • 拖动整个语义片段;
  • 拖动左右把手调整起止时间;
  • 默认 0.1 秒吸附、方向键微调、Shift 加速;
  • 播放头与视频时间同步;
  • 1–8 倍横向缩放;
  • 选中后独立删除,避免点击片段即删除。

拖动和缩放在相邻片段及 clip 边界内自动限位,提交 revision 时仍由后端执行范围、重叠和置信度校验。

工作量口径

首次 revision 产生 outputDelta=1;返工 revision 记录工时和返工次数,但 outputDelta=0,因此不会重复增加正式产出。质检、验收及拒绝原因分别记录为不可变工作量事件,汇总可按用户、供应商、分组和模板版本查询。

泛宇算子

custom-operators/fanyu-annotation/operator-definitions.json 登记两个 draft 算子:

  • Orbbec Ego 数据标准化:将视频、PTS、IMU、音频和标定对象配对为 droboticflow.orbbec.normalized/v1。
  • 版本化语义预标:将视频动作分段映射为 droboticflow.semantic.prelabels/v1。

两者在独立镜像构建、digest 固定、真实工作流验收和 artifact/lineage 回读前保持 draft,不能借用其他镜像的 digest 标记为已发布。