droboticflow/docs/human-loop-plugin.md

3.9 KiB
Raw Permalink Blame History

Human Loop Core 与 Annotation QA 插件

定位

平台通过两个编译期可信模块提供人工闭环能力:

  • human-loop-core 是系统插件,提供 HumanBatch、HumanItem、阶段 Attempt、追加事件、乐观锁和工作流挂起/恢复。
  • annotation-qa 是组织级可选插件,提供切分标注、语义标注、人工质检、验收、供应商隔离、模板和 Viewer Adapter。

普通训练、自动驾驶、扫描等工作流在不包含人工节点时不会获得标注标签,也不会加载 Annotation QA 页面代码。

为什么工作流保持 DAG

工作流画布禁止有向环并返回 workflow_graph_cycle。人工驳回不是重新执行已经完成的 DAG 节点,而是让一条 HumanItem 创建新的 StageAttempt 和 Revision:

split_annotation -> semantic_annotation -> quality_review
        ^                    ^                    |
        +------- reject target / rework --------+

DeliveryPackage -> acceptance HumanItem -> approved final export / rejected area

驳回必须携带原因码、说明和目标阶段。默认最多返工 5 轮,超限进入 escalated,不会静默交付。

数据处理粒度

  • 数据集或 Run 形成 HumanBatch。
  • 每个 Clip、Episode 或 Artifact 形成独立 HumanItem。
  • 每个阶段进入 ready 时清空领取人;人工逐条领取、保存、提交和审核,阶段切换后重新进入待领取池。
  • 已验收条目最多 32 条或等待 60 秒形成一个 ReleasePartition。
  • ReleasePartition 通过带唯一键的 Outbox 创建 human_release 子 Run,从 Gate 下游继续执行。

all_accepted 兼容旧 Gate;新配置默认使用 accepted_partition,避免一个返工条目阻塞全部已通过数据。

插件与深链

组织管理员在系统配置中启用 Annotation QA。服务端根据工作流节点派生以下 capability,客户端不能手工伪造:

  • human_annotation
  • human_quality_review
  • human_acceptance

项目卡片、编辑器和运行监控显示对应标签,分别进入:

/plugins/annotation-qa/workflows/:workflowId/annotate
/plugins/annotation-qa/workflows/:workflowId/quality
/plugins/annotation-qa/workflows/:workflowId/acceptance
/plugins/annotation-qa/items/:itemId

API

核心接口:

GET  /api/plugins
GET  /api/organizations/:id/plugins/:pluginId
PUT  /api/organizations/:id/plugins/:pluginId
GET  /api/human-batches
GET  /api/human-items
GET  /api/human-items?pool=available|mine|all
GET  /api/human-items/:id
GET  /api/human-items/:id/subject-content
POST /api/human-items/:id/claim
POST /api/human-items/:id/release
POST /api/human-items/:id/submissions
POST /api/human-items/:id/decisions
GET  /api/human-items/:id/events

Annotation QA 新接口位于 /api/plugins/annotation-qa/*。原 /api/annotation-* 在一个兼容周期内保留,并返回 Deprecation、Sunset 和 successor Link 响应头。

历史数据与审计

插件首次启用时幂等迁移既有 AnnotationTask。HumanItem 保留 legacyTaskId,并继承 Revision、作者、工作组、供应商和当前状态;历史 assignedUserId 会转换为已领取状态,新任务不预分配。所有后续 created、claimed、released、submitted、approved、rejected、escalated 事件只追加不覆盖。

普通成员只能读取 available 和 mine;all 仅管理员可用。领取使用 version 乐观锁,竞争失败返回 409 version_conflict。领取者可在提交前释放,管理员可强制释放,不设置自动超时。

返工 Revision 的 CountsAsOutput=false,因此修改被打回数据不会重复计入正式产出。

Rerun 边界

Rerun 是可选 Viewer Adapter。.rrd Artifact 使用统一鉴权 Content 路由,前端先校验 RRF2 文件头;SDK 不可用或文件无效时回退到原始视频、文件信息和下载入口,标注与审核状态不受影响。