droboticflow/docs/builtin-operators-manual.zh-CN.md
eust-w 5d20029c57
Some checks are pending
CI / verify (push) Waiting to run
CI / docker-build (push) Waiting to run
🔐 Support authenticated data reconciliation
2026-06-16 17:44:22 +08:00

8.4 KiB
Raw Permalink Blame History

Drobodata 内建算子手册

本文档不是“把每个算子再抄一遍”的长列表,而是当前内建算子体系的总览、使用方法和验收规则。单算子细节请进入分册目录 docs/operators/README.md。

截至 2026-04-21,当前线上算子目录中可见 25 个 builtin 算子、0 个 custom 实例。

算子列表

1. 文档结构

建议阅读顺序:

  1. 先读本手册,理解平台约束
  2. 再按类别进入单算子分册
  3. 最后回到工作流设计和回归验证

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 时,应该优先想清楚这五件事:

  1. 这个节点的输入到底是结构化 JSON,还是远程对象引用,还是本地文件路径
  2. 这个节点的输出是否需要被下游继续消费
  3. 这个节点是否有真实外部副作用,例如上传或写库
  4. 这个节点失败后如何重试,是否幂等
  5. 这个节点验收时应该看平台运行记录,还是必须去外部系统核对

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. 验收标准

每个内建算子至少应该满足下面四层验收:

  1. 节点执行层:execution 状态为 completed
  2. 产物层:stage-manifest.json 和 OUTPUT_DIR 中存在期望结果
  3. 链路层:下游节点能真实消费结果
  4. 外部副作用层:上传、写库、审核等副作用在外部系统中真实可见

推荐证据:

  • 一次成功 run 的 execution 日志
  • 一份 stage manifest
  • 一组代表性输出文件路径
  • 外部系统侧的核验截图或查询结果

9. 文档使用方式

当你要修改工作流或给 AI 生成工作流时,建议这样使用这些文档:

  1. 先在本手册中确认平台级约束
  2. 到 docs/operators/README.md 选中目标算子
  3. 阅读该算子的单册,确认端口、超参数、排障和验收
  4. 再回到工作流设计和回归

这样做的好处是:

  • 不会因为只看名字误判算子职责
  • 不会遗漏端口语义和外部副作用
  • 能更快定位失败点

10. 相关文档