13 KiB
标注生产闭环
插件化重构后的通用状态机、API、分区释放和深链约定见 Human Loop Core 与 Annotation QA 插件。本页保留 Annotation QA 领域对象和兼容接口说明。
/annotation-operations 提供项目级语义模板、供应商、真实切分、逐段标注、审核、验收、返工和工时统计。平台账号角色负责组织级管理边界,ProjectMember 进一步限定项目、供应商和人工阶段。v5.8 生产角色固定为三类:
annotator(标注员):先编辑、命名并确认连续切片;系统物化双目/PTS/IMU 后,再逐片填写可预览的 JSON 描述。quality_reviewer(审核员):独立审核切分边界、左右目对应关系和语义标注,拒绝时把整条源任务退回标注员。acceptance_reviewer(最终验收员):对抽中的 Capture 独立执行整包全量验收;拒绝时整包退回审核员,不得参与该 Capture 的标注审核。cutter:只保留历史 v5.7 任务兼容,新建 v5.8 项目不再分配该角色。supplier_manager:只查看所属供应商成员、任务和原始工作事件,不能修改其他供应商或组织配置。
每个成员关系绑定 projectId、可选 supplierId 和三类项目角色。除组织管理员外,后端只返回当前用户所属项目和供应商范围内的任务、模板和工时事件;前端隐藏不是安全边界。
每个工作台均有“可领取”“我的任务”池;管理员额外拥有“全部任务”,并可通过带乐观锁版本的 PATCH /api/human-items/{id}/assignment 将任务改派给同项目、同供应商且符合当前阶段角色的用户,或退回共享池。所有领取、释放、改派、提交、审核和打回都会追加 HumanEvent/StageAttempt 审计记录。
核心接口
账号与编辑操作
生产前端以 /api/auth/me 返回的账号作为唯一身份,读取失败不得降级为本地缓存账号。账号的默认项目角色只是添加成员时的预选;管理员需在项目“成员与角色”中显式添加成员。打开添加成员表单会刷新账号目录,也可使用“刷新账号列表”。
逐片标注使用“新增动作描述”创建当前未描述区间的编辑草案;可在播放头处分割已有动作,直接输入时间或用 ±1 帧调整并立即预览。只有“确认保存描述”成功后才计入已保存内容;失败显示具体原因并保留编辑内容。空白区域拖动不再创建极短描述。送检后,标注员的处理按钮禁用,但仍可从任务卡查看只读结果。
GET/POST /api/suppliersGET/POST /api/projects/{id}/membersPATCH/DELETE /api/projects/{id}/members/{memberId}POST /api/projects/{id}/members/bulk:批量添加、批量改角色或批量移除。GET/POST /api/plugins/annotation-qa/templatesPOST /api/plugins/annotation-qa/templates/{id}/publishGET/POST /api/plugins/annotation-qa/tasksGET /api/plugins/annotation-qa/tasks/{id}POST /api/plugins/annotation-qa/tasks/{id}/slice-confirmations:确认边界并异步生成真实切片,不推进质检阶段。POST /api/plugins/annotation-qa/tasks/{id}/slice-reset:清空当前 JSON 描述并返回切片编辑阶段,旧 Revision 仅保留审计。POST /api/plugins/annotation-qa/tasks/{id}/combined-submissionsPOST /api/plugins/annotation-qa/tasks/{id}/reviewsGET /api/plugins/annotation-qa/workload-summaryGET /api/human-items?pool=available|mine|allPOST /api/human-items/{id}/claimPOST /api/human-items/{id}/releasePATCH /api/human-items/{id}/assignment:仅管理员,可改派或退回池。GET /api/dashboard?from=<RFC3339>&to=<RFC3339>:管理员平台范围、供应商管理员团队范围、其他成员本人范围;只返回原始计数和时长,派生评分暂为空。GET/POST/PATCH /api/annotation-labels:组织级语义标签字典。GET/PUT /api/projects/{id}/annotation-labels:项目启用的标签集合。GET/PATCH /api/workflows/{id}/runtime-policy:Capture 并发与最终验收抽样概率。
模板必须发布后才能创建任务。v5.8 当前修订把项目字典作为“描述模板”:选择后会填充描述草稿,用户可以继续修改;切片和 JSON 描述不再要求手别或切片任务标签。时间段必须位于切片范围内且不能重叠。质检拒绝后由标注员返工并提交新的 revision;最终验收打回质检时,仅增加 HumanItem 的 reviewRound,不伪造标注修订或重新切片。合并质检按任务、revision、stage 和 reviewRound 区分审核记录:同一轮不允许重复提交,新轮允许复审同一份数据,旧决定永久保留。历史未记录轮次的审核默认为第 0 轮。不在工作流 DAG 中建立环。
人工数据采用“只有一份当前有效数据”的使用方式,无需员工选择或管理版本。内部 revision 仅作为异步生成标识及防止旧请求覆盖的校验值:新切片生成并成功发布后,删除同一 Capture 较早的切片、描述记录和 API 生成的切片目录,同时移除 Run 中旧产物引用;生成失败或发布冲突不清理当前数据。新提交清空之前的通过状态并重新进入质检。审核意见、操作日志、原始采集文件、其他 Capture 与模型产物保留。数据详情只返回已发布的当前切片与描述,不再提供历史数据选择。
新增动作描述使用整数微秒比较时间边界。吸附后的播放点与切片起点相差不超过 1 微秒时,新草稿归位到该切片的真实起点;不改动已存切片、描述或 PTS。超过容差的越界、切片末尾及已有描述覆盖仍拒绝,且分别提示原因。不能把容差扩大到毫秒或一帧来规避错误。
已打回的最终验收记录只作为审核留痕。其列表、详情及证据读取通过原始批次关联到当前 Capture 产物,按组织、项目、工作流和 Run 校验范围;只读投影不会覆盖原审核记录,也不会把记录变回待验收。当前数据未重新通过质检时,旧记录禁止领取和提交验收决定。页面显示“已打回/等待重新质检”,读取失败显示“切片加载失败”,不把失败当作零切片。
部署时 API 和 Worker 的索引初始化会把审核唯一约束迁移为 organizationId + taskId + revision + stage + reviewRound:先将旧记录缺失的轮次补为 0,再建立新唯一索引,最后移除 organizationId_taskId_revision_stage_unique。不能只修改接口校验而保留旧数据库约束;同轮并发重复提交仍由数据库拦截。真实 Mongo 回归使用 MONGO_INDEX_TEST_URI、MONGO_INDEX_TEST_DB 运行 TestAnnotationReviewIndexMigrationMongo,在独立临时集合中验证迁移,结束后删除该测试集合,不提交业务任务。
原生工作流 Annotation Gate
人工审核节点配置 REVIEW_MODE=annotation 后成为原生标注门,另外需要:
ANNOTATION_TEMPLATE_ID:当前项目中已发布的模板。ANNOTATION_SUPPLIER_ID:v5.8 公共 Capture 池保持为空;标注员领取时原子绑定其项目供应商。旧工作流可继续显式绑定供应商。- 新任务不接受
ANNOTATION_ASSIGNED_USER_ID预分配;成员从 HumanItem 待领取池主动领取。
Worker 到达该节点后不会启动 Kubernetes Job,也不会创建通用 AuditTask。它会为整个 Capture 创建一个 AnnotationTask。Run 保持 waiting_for_human,直到标注与同供应商审核完成;随后按工作流固定概率抽样,抽中才创建匿名最终验收任务,未抽中直接释放 Package child Run。
v5.8 不预先把长视频拆成多个人工 Task;同一个源任务可提交多个最终切片。无法局部调整的丢帧、流缺失或时间轴异常必须整条任务退回自动重处理,不允许用 FFmpeg 拼接近似修复。
v5.8 打包以绝对 timestamp_us 为权威时钟,按同一个半开窗口同步裁切左右视频、左右 PTS CSV 和 IMU accel/gyro;输出侧车统一为毫秒并保留 clip-relative 时间。Audio 与 audio PTS 不处理、不交付,camera/IMU calibration 原文件在批次根目录保留且不做内参差异管理。
标注审核通过后执行一次不可变 Capture 抽样。抽样证据记录概率、策略版本、随机值和决定时间;最终验收拒绝时保留该决定并整包退回审核阶段。打包 manifest 同时记录抽样和 Pose 决策。
/annotation-operations 支持通过以下参数从项目或监控页深链进入:
projectId、dataTaskId、workflowId、runId、nodeId、artifactId、taskId。
两阶段切片与 JSON 描述交互
标注任务使用真实 artifact 视频预览,固定执行:
- 切片阶段:按 PTS 帧拖动公共边界、直接输入、逐帧微调、在播放头新增切片、删除/合并切片并编辑切片名称。
- 确认阶段:点击“确认切片并开始生成”,页面显示正在生成;后端实际裁切左右视频、左右 PTS 与 IMU,阶段仍停留在标注员。
- JSON 标注阶段:点击任一切片单独播放;从描述字典选择草稿后可修改描述,并设置描述起止时间。每片可添加多条描述或确认无动作。
- 完成阶段:所有切片均有描述或已确认无动作后,点击“完成任务并交给质检”。
- 重新切片:标注阶段点击“重新切片”必须确认警告;确认后清空当前 JSON 描述和完成状态,返回切片编辑,旧切片/标注只读留在审计历史。
切片始终首尾相连、无空洞无重叠;描述时间范围必须完全属于一个切片且互不重叠。服务端草稿与阶段状态支持刷新恢复。
切片工作台自适应
仅标注队列的切片阶段采用剩余空间布局,其他标注、质检、验收与媒体预览布局不变。页面填满现有应用容器,按筛选栏和操作区真实高度分配视频空间;视频完整等比显示,不改变媒体节点、播放头或 PTS 边界。
工作区宽度不足 900 CSS 像素时,任务池上置,列表限高 150px 并独立滚动;控件按容器宽度换行。正文不足时可滚动,底部确认栏独立占位,不覆盖输入;极矮窗口可通过外层滚动到工作台。切片字典在滚动布局中使用浮层避免被裁切,选择和快捷键含义保持不变。
播放器倍速
切片与标注工作台提供 0.5×、1×、1.5×、2×、4×、6×、8×,左右视频使用相同的所选倍速。快捷键含义不变:数字 1 为 0.5×,数字 2 为 1×。暂停后的上一帧/下一帧仍按原始帧时间轴移动,不随倍速扩大步长;选择倍速本身不移动播放头、不修改切片或描述边界。
原始工作记录
首次 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 标记为已发布。
切片中断恢复
确认切片后,API 每 15 秒续约持久化心跳,租约有效期 2 分钟。Worker 后台巡检与任务详情读取都会将过期的处理状态转为可重试失败,不要求用户保持页面打开;旧版本无租约的记录按开始时间判断。已保存的切片边界和领取人不变,用户可返回调整后重新确认,不会无限自动重试 OOM。
每次重新确认使用递增的物化版本;返回编辑保留版本序号。旧请求不能发布新请求的完成状态。正常处理中的重复确认返回 409。切片处理最长 24 小时,超时取消 ffmpeg 并记录失败。
项目供应商自动带入成员
创建项目并引用人工流程模板时,选择处理供应商会重新读取账号列表,自动带入该供应商全部启用的生产账号,并以默认项目角色(为空时使用账号角色)预填。供应商管理员保留管理权限,不自动分配生产角色。加载期间不可提交,切换供应商或关闭弹框后旧请求不会覆盖新选择。
DROBOTICFLOW_PROJECT_SUPPLIER_IDS 可在部署环境中指定新项目候选供应商 ID(逗号分隔)。仅影响 /api/suppliers?forProject=true 的创建选项,不删除历史供应商、不改变已有项目或任务权限;未配置时显示全部启用供应商。Fanyu 当前按运营要求只选择既有正式工作组。