forked from longtao.wu/droboticflow
8.4 KiB
8.4 KiB
Drobodata 内建算子手册
本文档不是“把每个算子再抄一遍”的长列表,而是当前内建算子体系的总览、使用方法和验收规则。单算子细节请进入分册目录 docs/operators/README.md。
截至 2026-04-21,当前线上算子目录中可见 25 个 builtin 算子、0 个 custom 实例。
1. 文档结构
- 总手册:说明平台级规则、编排方式、通用坑点和验收口径
- 分册目录:
docs/operators/README.md - 自定义算子:
docs/custom-operator-manual.zh-CN.md - 算子开发参考:
docs/operator-authoring.md
建议阅读顺序:
- 先读本手册,理解平台约束
- 再按类别进入单算子分册
- 最后回到工作流设计和回归验证
2. 平台级规则
内建算子的价值不在于“名字固定”,而在于它们遵循统一运行时契约:
- worker 会先把上游 artifact 汇总到
INPUT_ARTIFACTS_PATH - 节点配置通过
NODE_DATA_JSON注入 runner - 算子在
OUTPUT_DIR中产出业务文件 - worker 再收集
RESULT_OUTPUT_PATH和STAGE_MANIFEST_PATH - 大文件和大 JSON 默认不会走 API 内联,而是走
artifact.path、dataRef.payloadPath、共享 PVC 或对象存储引用
你在设计 DAG 时,应该优先想清楚这五件事:
- 这个节点的输入到底是结构化 JSON,还是远程对象引用,还是本地文件路径
- 这个节点的输出是否需要被下游继续消费
- 这个节点是否有真实外部副作用,例如上传或写库
- 这个节点失败后如何重试,是否幂等
- 这个节点验收时应该看平台运行记录,还是必须去外部系统核对
3. 运行时模型
sequenceDiagram
participant UI as Workflow UI
participant Worker as Go Worker
participant Job as Kubernetes Job
participant Runner as operator-runner
participant Storage as PVC / BOS / DB
UI->>Worker: 保存工作流 DAG
Worker->>Worker: 汇总上游 artifact 与节点超参数
Worker->>Job: 创建节点 Job
Job->>Runner: 注入 NODE_DATA_JSON / INPUT_ARTIFACTS_PATH / OUTPUT_DIR
Runner->>Storage: 读取源文件、处理业务、写结果
Runner-->>Worker: result.json / stage-manifest.json
Worker->>Worker: 持久化 execution / run
你在理解内建算子时,不要把它想成“函数调用”,而应该把它想成“受平台约束的一次节点执行”。这会直接影响你对下列问题的判断:
- 是否允许把大视频、大包体结果直接塞进日志或 Mongo
- 是否应该用路径引用代替内联内容
- 为什么一个输入端口不能接多条上游边
- 为什么上传和写库必须把外部副作用单独验收
4. 什么时候优先用内建算子
优先选择内建算子的情形:
- 逻辑已经稳定,且会被多条工作流重复使用
- 输入输出契约已经清晰,可被 UI 和 AI 工作流生成器复用
- 需要受控地处理 BOS、PVC、Mongo、审核流、视频链路等平台强约束逻辑
- 需要长期维护、回归、上线和扩展
不应该勉强塞进内建算子的情形:
- 只是临时调试脚本
- 逻辑尚未稳定
- 接口和产物结构还在频繁变化
- 需要快速验证单次项目需求
这类场景更适合先走 docs/custom-operator-manual.zh-CN.md 里的自定义路径。
5. 当前算子分类地图
5.1 IO / 源与汇
适合解决:
- 外部数据引入
- 增量发现
- 目录级概览
- 最终结果落盘和上传
5.2 DATASET / 数据集整理
适合解决:
- 原始数据集结构解包
- 采集目录合法性验证
- 为视频链路提供标准化 manifest
5.3 DATA / 结构化处理中间层
适合解决:
- 数据转换
- 条件筛选
- 字段清洗
- 报表/外部库落地
5.4 VIDEO / 视频主链路
适合解决:
- 质检
- 筛选
- clip 切分
- 标注
- 成品组装
5.5 QA / HUMAN / LOGIC / UTIL / AI / ROBOTICS
这几类算子承担的是:
- 人工决策
- 路由控制
- 模板渲染
- 受控命令执行
- 模型/脚本推理
- 机器人数据集概览
6. 常见编排模式
6.1 增量扫描链路
flowchart LR
A["BOS 增量扫描"] --> B["X 平台数据集索引"]
B --> C["采集目录校验"]
C --> D["视频质检 / 数据过滤"]
适合持续发现新增目录或新增对象,并只处理本轮增量。
6.2 视频生产链路
flowchart LR
A["视频质检"] --> B["数据过滤"]
B --> C["视频切片"]
C --> D["视频标注"]
D --> E["成品打包"]
E --> F["结果上传"]
适合把原始视频逐步转成可交付 clip、annotation 和 package。
6.3 审核链路
flowchart LR
A["候选数据"] --> B["人工审核"]
B -->|"approved"| C["结果上传 / 写库"]
B -->|"rejected"| D["拒绝支路归档"]
审核节点后一定要显式拆分分支,不要让通过和拒绝结果流入同一后继节点。
7. 最容易踩的坑
7.1 把内建算子当成“内存函数”
错误理解:
- 认为上游输出会直接以内存对象传给下游
- 认为大 JSON 一定能在运行记录里完整看到
正确理解:
- 节点之间靠 artifact、manifest、PVC、BOS 引用通信
- 大结果很可能已经外置
7.2 一个上传节点同时接多条线
当前平台明确限制:
- 一个输入端口只能有一条上游边
- 想上传多个不同结果,就拆多个上传节点
7.3 只看平台状态,不看真实外部副作用
这在以下算子上最危险:
- 结果上传
- MongoDB 写入
- 人工审核
验收时必须去目标 BOS、目标库或审核流里核对真实结果。
7.4 在视频链路里传大对象而不是传引用
视频类算子的正确姿势是:
- 传 manifest
- 传本地路径
- 传
bos://...引用 - 让 runner 在必要时物化文件
而不是把大量媒体信息硬塞进内联 payload。
8. 验收标准
每个内建算子至少应该满足下面四层验收:
- 节点执行层:execution 状态为
completed - 产物层:
stage-manifest.json和OUTPUT_DIR中存在期望结果 - 链路层:下游节点能真实消费结果
- 外部副作用层:上传、写库、审核等副作用在外部系统中真实可见
推荐证据:
- 一次成功 run 的 execution 日志
- 一份 stage manifest
- 一组代表性输出文件路径
- 外部系统侧的核验截图或查询结果
9. 文档使用方式
当你要修改工作流或给 AI 生成工作流时,建议这样使用这些文档:
- 先在本手册中确认平台级约束
- 到
docs/operators/README.md选中目标算子 - 阅读该算子的单册,确认端口、超参数、排障和验收
- 再回到工作流设计和回归
这样做的好处是:
- 不会因为只看名字误判算子职责
- 不会遗漏端口语义和外部副作用
- 能更快定位失败点
