droboticflow/docs/custom-operator-manual.zh-CN.md
eust-w 43326d6a5e feat(platform): land workflow, data tooling, and docs updates
Include the accumulated workflow scheduling, run history, subtree rerun, operator UI, deployment, data asset, object storage, database browser, and documentation changes currently in the worktree.
2026-04-24 12:29:46 +08:00

13 KiB
Raw Blame History

Drobodata 自定义算子手册

本文档面向平台研发、算法工程师和工作流设计者,说明在当前架构下如何设计、实现、调试、文档化和验收自定义算子。

配套文档:

相关实现入口:

  • backend/operator-runner/main.py
  • internal/worker/executor.go
  • internal/worker/runtime.go
  • internal/k8s/launcher.go
  • internal/api/server.go
  • internal/domain/types.go
  • src/pages/Operators.tsx

1. 自定义算子的定位

自定义算子不是“代码随便跑一下”的兜底概念,而是平台用来承接非标准化逻辑的受控扩展点。

它适合:

  • 需求刚出现,逻辑尚未稳定
  • 需要快速验证一个新处理链路
  • 需要接一个内建算子暂时没有覆盖的业务逻辑
  • 需要独立镜像、独立依赖或项目级脚本

它不适合:

  • 已经被多个工作流复用的稳定公共能力
  • 明显属于平台核心语义的能力,例如增量扫描、统一上传、审核流、标准视频处理
  • 需要长期维护但没有人负责的临时脚本

如果一个自定义算子会长期存在,请从一开始就把它当成“将来可能要内建化的标准件”来设计,而不是当作一次性脚本。

2. 三种落地方式

2.1 命令型验证

最常见的起点是:

适合:

  • 快速验证
  • 小范围项目定制
  • 临时脚本或受控命令执行

优点:

  • 上手快
  • 无需改平台主逻辑

问题:

  • 约束弱
  • 复用差
  • 难统一回归

2.2 注册型自定义算子

通过平台算子管理页或 API 创建 type=custom 的算子元数据,补齐:

  • 名称
  • 类别
  • 描述
  • 输入端口
  • 输出端口
  • 超参数
  • 镜像
  • skillDefinition

适合:

  • 已经形成稳定的输入输出契约
  • 需要给 UI、工作流生成器、调用方提供统一入口
  • 需要把逻辑包装为更像“产品能力”的算子

2.3 内建化

当一个自定义算子满足下面任意条件时,应该考虑内建化:

  • 复用频率高
  • 失败模式明确且可以平台化治理
  • 需要和 BOS/PVC/审核流/回归体系深度集成
  • 需要严格的文档、测试和验收

3. 元数据字段该怎么设计

当前 OperatorRecord 关键字段包括:

  • id
  • name
  • type
  • category
  • description
  • inputs
  • outputs
  • hyperparams
  • image
  • skillDefinition

设计建议:

3.1 名称

  • 用业务动作命名,不要只写技术实现
  • 名称应该让工作流设计者一眼看出用途
  • 避免“脚本1”“临时处理”“新版聚合”这类无语义名字

3.2 分类

  • 选最贴近职责的类别
  • 不要为了“好找”滥用一个分类
  • 如果算子主要做数据清洗,就归 DATA
  • 如果主要做文件引入或导出,就归 IO

3.3 description

description 负责回答一个问题:

“这个算子到底做什么,不做什么。”

应该写清:

  • 主职责
  • 主要输入
  • 主要输出

3.4 image

image 字段表示“运行这个自定义算子时实际拉起的容器镜像”。

当前平台的责任边界很明确:

  • 平台不会帮你构建自定义镜像
  • 平台不会帮你推送镜像到仓库
  • 平台只会保存你填写的镜像地址,并在运行时直接用它启动 Kubernetes Job

因此,自定义镜像的标准流程是:

  1. 用户自己在外部容器仓库构建并推送镜像
  2. 用户把完整镜像地址填写到算子的 image 字段
  3. 工作流运行时,平台直接拉取这个地址执行

填写要求:

  • 必须填写完整镜像引用,格式建议为 <registry>/<namespace>/<image>:<tag>
  • 不要依赖 latest,应使用明确版本标签,方便回滚和排障
  • 镜像仓库必须能被当前集群拉取

当前部署环境里,推荐沿用与平台一致的百度云 CCR 命名方式,例如:

ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-<operator-name>:<tag>

如果你当前接的是百度云 CCR xspark 命名空间,并希望让用户自己推镜像再在算子里填写 image,请直接参考:

这份分册包含:

  • xspark 私有镜像的真实验收结论
  • 登录、推送、填写 image 的标准流程
  • 自定义镜像最小运行协议
  • 一个可直接复制的最小 Dockerfile / run.sh 示例
  • 常见失败模式与排障方式

特别注意:

  • 不要把 droboticflow-operator-runner:* 当成自定义镜像名填写
  • 这类平台内建 runner 镜像在运行时可能被系统镜像覆盖,不适合作为自定义算子的独立镜像地址

3.5 skillDefinition

skillDefinition 不应该只写一句简介。

它应该是给未来工作流生成器、平台维护者和文档脚本看的高密度说明,至少覆盖:

  • 输入需要什么结构
  • 输出会产生什么结果
  • 超参数分别控制什么
  • 哪些场景适合用
  • 哪些场景不该用
  • 失败时怎么理解

如果你愿意,skillDefinition 可以直接按 Markdown 写,这也是本仓库现在推荐的方向。

4. 输入输出契约

4.1 输入不是“只有 path”

自定义算子最常见的错误,是假设输入永远长这样:

path = artifact["path"]

这是不够的。你必须同时考虑以下几类输入:

  • artifact.data:结构化 JSON 已经在内存可用
  • artifact.path:本地文件路径
  • artifact.path = bos://bucket/key:远程对象引用
  • dataRef.payloadPath:外置 payload 文件
  • metadata:上游附带的摘要信息

推荐读取顺序:

  1. 先看 artifact.data
  2. 再看本地 artifact.path
  3. 再判断是否需要物化 bos://...
  4. 最后处理外置 payload

4.2 输出必须满足 artifact 契约

一个可靠的自定义算子应该明确产出:

  • name
  • type
  • path
  • data
  • metadata
  • 多分支时补齐 portId / portName

推荐原则:

  • 小 JSON:可以直接放 data
  • 大 JSON:外置为文件或 payload
  • 大文件:写到 OUTPUT_DIR
  • 长期结果:上传到对象存储后再返回远程引用

4.3 多输出必须显式绑定端口

如果你的算子有多个输出分支:

  • 每个输出 artifact 都要明确绑定 portId
  • 下游边必须接到对应输出端口
  • 不要把不同语义的结果混在一个输出口里

5. 运行时环境

平台当前是 Kubernetes Job-only + 共享 PVC + BOS 的执行模型。

常见环境变量和文件:

  • RUN_ID
  • WORKFLOW_ID
  • NODE_ID
  • NODE_LABEL
  • NODE_DATA_JSON
  • INPUT_ARTIFACTS_PATH
  • OUTPUT_DIR
  • RESULT_OUTPUT_PATH
  • STAGE_MANIFEST_PATH

如果节点涉及存储,还可能注入:

  • SOURCE_PATH
  • BOS_ENDPOINT
  • BOS_ACCESS_KEY_ID
  • BOS_SECRET_ACCESS_KEY
  • STORAGE_BUCKET
  • STORAGE_PREFIX

这意味着自定义算子要从一开始就接受一个事实:

  • 你不是在写“本地脚本”
  • 你是在写“平台节点执行逻辑”

6. 数据路径设计

6.1 什么时候只传引用

优先只传引用的场景:

  • 视频
  • 大图片集
  • 大 JSON 清单
  • 压缩包
  • 成品目录

6.2 什么时候要物化到本地

必须物化的场景:

  • ffmpeg / ffprobe 需要真实文件
  • OpenCV 需要直接读本地路径
  • 业务脚本只能消费本地文件

6.3 什么时候要上传 BOS

需要跨 Job 生命周期保留时,就不要只留在 OUTPUT_DIR:

  • clip
  • annotation
  • package
  • 报表
  • 大型结果集

7. 自定义算子的文档体系

这次仓库把自定义算子文档拆成三层:

  1. 本手册:平台级规则
  2. 模板与示例:docs/custom-operators/README.md
  3. 实例级分册:docs/custom-operators/instances/README.md

你应该为每个长期存在的自定义算子单独维护一篇 Markdown,至少包括:

  • 作用与边界
  • 输入输出契约
  • 端口语义
  • 超参数
  • 运行时依赖
  • 配置示例
  • 失败模式
  • 验收口径

8. 推荐开发流程

8.1 第一步:先写文档,再写实现

在动手之前,先用 自定义算子设计模板 写清楚:

  • 它解决什么问题
  • 它的输入是什么
  • 它的输出是什么
  • 为什么现有内建算子不够
  • 它未来是否可能内建化

8.2 第二步:先走命令型验证

如果逻辑还在探索期,优先使用:

  • Shell 命令执行
  • 模型推理

目标不是“马上做成正式算子”,而是先确认:

  • 输入输出契约跑得通
  • 依赖准备齐全
  • 产物结构合理

8.3 第三步:收敛成注册型自定义算子

当输入输出已经稳定,就进入平台注册并补齐:

  • 端口
  • 超参数
  • 镜像
  • 详细 skillDefinition
  • 单算子 Markdown 文档

8.4 第四步:补测试和回归

至少覆盖:

  • 输入解析
  • 关键超参数
  • 输出 artifact 结构
  • 失败分支
  • 一条真实工作流回归

8.5 第五步:决定是否内建化

如果该算子开始被多个项目或多个流程复用,就不应长期停留在“项目级脚本”状态。

9. 代码模板建议

9.1 结构化 JSON 型

适合:

  • 字段提取
  • 聚合统计
  • 路由判断
  • 清洗和映射

基本流程:

  1. 读取 INPUT_ARTIFACTS_PATH
  2. 优先从 artifact.data 取 payload
  3. 做纯结构化处理
  4. 输出 JSON artifact

9.2 文件处理型

适合:

  • 视频
  • 压缩包
  • 大型报表
  • 目录级产物

基本流程:

  1. 解析 artifact 引用
  2. 必要时物化到本地
  3. 在 OUTPUT_DIR 写结果
  4. 生成 artifact 和 stage manifest
  5. 必要时上传对象存储

9.3 双分支或多分支型

适合:

  • 审核
  • 条件路由
  • 成功/失败分流

要求:

  • 每个分支都有明确输出端口
  • 每个 artifact 都绑定端口
  • 每个分支都能单独验收

10. 安全、幂等和资源约束

10.1 安全

  • 不要把密钥硬编码进脚本或文档
  • 优先使用环境变量和平台连接配置
  • 对外部命令和路径输入做校验
  • 不要让脚本任意扫描工作目录之外的敏感路径

10.2 幂等

自定义算子要尽量回答清楚:

  • 重跑同一个 run 会不会重复写入
  • 上传重试会不会覆盖
  • 写库失败重试会不会插入重复数据

10.3 资源

要明确:

  • 这个算子是 CPU 型还是 IO 型
  • 是否依赖 GPU
  • 是否会占大量磁盘
  • 是否会生成大量中间文件

11. 常见问题

11.1 只在 OUTPUT_DIR 写结果,不做长期保存

问题:

  • Job 结束后临时文件不等于长期结果

做法:

  • 需要保留的结果显式上传 BOS 或写入目标系统

11.2 误把 preview URL 当业务输入

问题:

  • preview 链接不等于生产消费路径

做法:

  • 真正处理时优先使用 bos://... 或本地物化路径

11.3 文档只写“干什么”,不写“怎么验收”

问题:

  • 后续维护者无法判断节点是否真的工作

做法:

  • 每篇自定义算子 Markdown 都必须包含验收章节

11.4 skillDefinition 太短

问题:

  • AI 和维护者都无法从元数据中理解正确使用方式

做法:

  • 至少写清输入、输出、超参数、使用边界和失败语义

12. 验收要求

每个正式自定义算子上线前,至少满足:

  1. 有一篇独立 Markdown 文档
  2. 有明确输入输出契约
  3. 有最小测试或脚本级验证
  4. 有一次真实工作流回归
  5. 有外部副作用核验证据

建议证据:

  • 文档链接
  • 节点配置示例
  • 一次成功 run
  • 一份 stage manifest
  • 一组真实产物

13. 相关资料