86 lines
3.9 KiB
Markdown
86 lines
3.9 KiB
Markdown
# 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 不可用或文件无效时回退到原始视频、文件信息和下载入口,标注与审核状态不受影响。
|