droboticflow-new/docs/custom-operator-manual.zh-CN.md
2026-06-25 12:38:29 +08:00

13 KiB
Raw Permalink 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 version / image / imageId

version 是平台侧展示给工作流作者和审计人员看的算子版本。它不是随便写的备注字段,应该和镜像构建、测试验收、上线记录对应起来。

推荐约束:

  • 新算子首次注册使用明确版本,例如 v1、1.0.0、2026.06.25
  • 每次镜像行为或输入输出契约发生变化,都应升级 version
  • 不要把不同实现复用同一个版本号
  • 版本号只能包含字母、数字、下划线、点和短横线,长度不超过 128

工作流节点会保存添加节点时的 operatorVersion 和 operatorImageId,用于后续排障和验收追踪。

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

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

  • 平台不会帮你构建自定义镜像
  • 如果你直接填写镜像地址,平台只会保存并在运行时直接用它启动 Kubernetes Job
  • 如果你上传 Docker/OCI 镜像归档,平台会把归档导入到 POC 配置的 CCR 仓库,并把算子运行镜像固定到 digest 引用

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

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

上传镜像归档的标准流程是:

  1. 用户用 docker save 或 OCI 工具导出真实镜像归档
  2. 在算子管理页选择“上传归档”,填写目标仓库、tag 和版本
  3. 平台导入镜像后保存 imageId=repo@sha256:...,工作流节点也会记录该 digest

填写要求:

  • 必须填写完整镜像引用,格式建议为 <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. 有外部副作用核验证据
  6. 版本号、镜像 tag、digest 和验收记录能对应起来

建议证据:

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

13. 相关资料