droboticflow-new/docs/human-loop-plugin.md

86 lines
3.9 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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:
```text
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`
项目卡片、编辑器和运行监控显示对应标签,分别进入:
```text
/plugins/annotation-qa/workflows/:workflowId/annotate
/plugins/annotation-qa/workflows/:workflowId/quality
/plugins/annotation-qa/workflows/:workflowId/acceptance
/plugins/annotation-qa/items/:itemId
```
## API
核心接口:
```text
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 不可用或文件无效时回退到原始视频、文件信息和下载入口,标注与审核状态不受影响。