forked from longtao.wu/droboticflow
146 lines
16 KiB
Markdown
146 lines
16 KiB
Markdown
# 标注生产闭环
|
||
|
||
> 插件化重构后的通用状态机、API、分区释放和深链约定见 [Human Loop Core 与 Annotation QA 插件](./human-loop-plugin.md)。本页保留 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/suppliers`
|
||
- `GET/POST /api/projects/{id}/members`
|
||
- `PATCH/DELETE /api/projects/{id}/members/{memberId}`
|
||
- `POST /api/projects/{id}/members/bulk`:批量添加、批量改角色或批量移除。
|
||
- `GET/POST /api/plugins/annotation-qa/templates`
|
||
- `POST /api/plugins/annotation-qa/templates/{id}/publish`
|
||
- `GET/POST /api/plugins/annotation-qa/tasks`
|
||
- `GET /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-submissions`
|
||
- `POST /api/plugins/annotation-qa/tasks/{id}/reviews`
|
||
- `GET /api/plugins/annotation-qa/workload-summary`
|
||
- `GET /api/human-items?pool=available|mine|all`
|
||
- `POST /api/human-items/{id}/claim`
|
||
- `POST /api/human-items/{id}/release`
|
||
- `PATCH /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 标注阶段:点击任一切片单独播放;从描述字典选择草稿后可修改描述,并设置描述起止时间。每片可添加多条描述或确认无动作。
|
||
- 完成阶段:所有切片均有描述或已确认无动作后,点击“完成任务并交给质检”。
|
||
- 重新切片已停用:描述阶段可**原地**调整切片结构(拖边界、合并、拆分、新增分界、舍弃切片,或 `E` 进入切片编辑模式逐帧挪边界;边界穿过/贴着动作时当场弹处置卡,不选则边界不动)。历史"重新切片"入口已删除,写端点返回 409 `slice_reset_disabled` 并指引改用原地编辑;既有重切历史只读保留。详见 [ADR 0007](adr/0007-inplace-slice-editing-replaces-reslice.md)。
|
||
|
||
切片始终首尾相连、无空洞无重叠;描述时间范围必须完全属于一个切片且互不重叠。服务端草稿与阶段状态支持刷新恢复。
|
||
|
||
## 切片工作台自适应
|
||
|
||
仅标注队列的切片阶段采用剩余空间布局,其他标注、质检、验收与媒体预览布局不变。页面填满现有应用容器,按筛选栏和操作区真实高度分配视频空间;视频完整等比显示,不改变媒体节点、播放头或 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 当前按运营要求只选择既有正式工作组。
|
||
|
||
### 质检领取与本人标注隔离
|
||
|
||
质检领取资格与正式审核保持职责隔离:任务的最近标注作者为当前用户时,后端返回不可领取,直接调用领取接口也被拒绝。账号从标注员调整为质检员不豁免此规则。连续审查与审核提交沿用现有本人隔离检查。历史已经领取的本人任务不在此次改动中自动释放,仍不能提交自审决定;不修改已有标注、历史审核或客户记录。
|
||
|
||
### 退回历史按需分页
|
||
|
||
工作台首屏不再请求退回历史;只有打开拒绝区才请求,每页读取最多 30 条候选记录,随后沿用服务端权限过滤。页面可能不足 30 条或为空但仍有下一页,此时继续翻页,不代表历史结束。本页待处置数量不是全部历史总量。筛选变化清空旧页,失败可重试。
|
||
|
||
`GET /api/human-rejects` 新增可选 `limit=1..100`、`cursor`,返回 `items` 和 `nextCursor`。按创建时间、ID 倒序游标分页,权限过滤不改变游标推进,不漏掉后续有权限的记录;本页关联任务批量查询,项目权限按请求复用。未传 limit 的旧调用及内部按任务读取仍保持全量行为,无数据迁移。此优化降低首屏和历史列表查询压力,不宣称已消除所有数据库超时。
|
||
|
||
### Poll response compatibility
|
||
|
||
Review continuation accepts `compact: true` for `renew` only. It returns
|
||
`generation`, `status`, `itemId`, `expiresAt`, `bound`, and `pending`, without
|
||
`item`. Missing tasks return an empty `itemId` and `waiting`; identity reads
|
||
remain organization-scoped. Other actions and clients omitting `compact` retain
|
||
the original response. New clients accept legacy full-item renew responses.
|
||
|
||
The annotation work-buffer GET accepts `view=summary`. Its response uses
|
||
`summaries` instead of `items`, retaining capacity, occupancy and processing
|
||
state. Each summary includes task identity, ownership, stage, version, review
|
||
round, claimed time, pending submission, slice status/phase and display labels.
|
||
Disabled buffers return an empty summary array. PUT and default GET retain their
|
||
old contracts. Summaries must never replace editor details or drafts. The frontend polls this summary endpoint and converts legacy full responses when paired with an older server. It loads full records when entering work, keeping summaries separate from editor data. Mongo reads use an inclusion projection; name-cache misses still load the original item to preserve historical nested capture-name precedence. Stable summary polls retain the existing no-ledger-write behavior.
|