13 KiB
Drobodata 自定义算子手册
本文档面向平台研发、算法工程师和工作流设计者,说明在当前架构下如何设计、实现、调试、文档化和验收自定义算子。
配套文档:
相关实现入口:
backend/operator-runner/main.pyinternal/worker/executor.gointernal/worker/runtime.gointernal/k8s/launcher.gointernal/api/server.gointernal/domain/types.gosrc/pages/Operators.tsx
1. 自定义算子的定位
自定义算子不是“代码随便跑一下”的兜底概念,而是平台用来承接非标准化逻辑的受控扩展点。
它适合:
- 需求刚出现,逻辑尚未稳定
- 需要快速验证一个新处理链路
- 需要接一个内建算子暂时没有覆盖的业务逻辑
- 需要独立镜像、独立依赖或项目级脚本
它不适合:
- 已经被多个工作流复用的稳定公共能力
- 明显属于平台核心语义的能力,例如增量扫描、统一上传、审核流、标准视频处理
- 需要长期维护但没有人负责的临时脚本
如果一个自定义算子会长期存在,请从一开始就把它当成“将来可能要内建化的标准件”来设计,而不是当作一次性脚本。
2. 三种落地方式
2.1 命令型验证
最常见的起点是:
适合:
- 快速验证
- 小范围项目定制
- 临时脚本或受控命令执行
优点:
- 上手快
- 无需改平台主逻辑
问题:
- 约束弱
- 复用差
- 难统一回归
2.2 注册型自定义算子
通过平台算子管理页或 API 创建 type=custom 的算子元数据,补齐:
- 名称
- 类别
- 描述
- 输入端口
- 输出端口
- 超参数
- 镜像
skillDefinition
适合:
- 已经形成稳定的输入输出契约
- 需要给 UI、工作流生成器、调用方提供统一入口
- 需要把逻辑包装为更像“产品能力”的算子
2.3 内建化
当一个自定义算子满足下面任意条件时,应该考虑内建化:
- 复用频率高
- 失败模式明确且可以平台化治理
- 需要和 BOS/PVC/审核流/回归体系深度集成
- 需要严格的文档、测试和验收
3. 元数据字段该怎么设计
当前 OperatorRecord 关键字段包括:
idnametypecategorydescriptioninputsoutputshyperparamsimageskillDefinition
设计建议:
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 引用
因此,自定义镜像的标准流程是:
- 用户自己在外部容器仓库构建并推送镜像
- 用户把完整镜像地址填写到算子的
image字段 - 工作流运行时,平台直接拉取这个地址执行
上传镜像归档的标准流程是:
- 用户用
docker save或 OCI 工具导出真实镜像归档 - 在算子管理页选择“上传归档”,填写目标仓库、tag 和版本
- 平台导入镜像后保存
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:上游附带的摘要信息
推荐读取顺序:
- 先看
artifact.data - 再看本地
artifact.path - 再判断是否需要物化
bos://... - 最后处理外置 payload
4.2 输出必须满足 artifact 契约
一个可靠的自定义算子应该明确产出:
nametypepathdatametadata- 多分支时补齐
portId/portName
推荐原则:
- 小 JSON:可以直接放
data - 大 JSON:外置为文件或 payload
- 大文件:写到
OUTPUT_DIR - 长期结果:上传到对象存储后再返回远程引用
4.3 多输出必须显式绑定端口
如果你的算子有多个输出分支:
- 每个输出 artifact 都要明确绑定
portId - 下游边必须接到对应输出端口
- 不要把不同语义的结果混在一个输出口里
5. 运行时环境
平台当前是 Kubernetes Job-only + 共享 PVC + BOS 的执行模型。
常见环境变量和文件:
RUN_IDWORKFLOW_IDNODE_IDNODE_LABELNODE_DATA_JSONINPUT_ARTIFACTS_PATHOUTPUT_DIRRESULT_OUTPUT_PATHSTAGE_MANIFEST_PATH
如果节点涉及存储,还可能注入:
SOURCE_PATHBOS_ENDPOINTBOS_ACCESS_KEY_IDBOS_SECRET_ACCESS_KEYSTORAGE_BUCKETSTORAGE_PREFIX
这意味着自定义算子要从一开始就接受一个事实:
- 你不是在写“本地脚本”
- 你是在写“平台节点执行逻辑”
6. 数据路径设计
6.1 什么时候只传引用
优先只传引用的场景:
- 视频
- 大图片集
- 大 JSON 清单
- 压缩包
- 成品目录
6.2 什么时候要物化到本地
必须物化的场景:
- ffmpeg / ffprobe 需要真实文件
- OpenCV 需要直接读本地路径
- 业务脚本只能消费本地文件
6.3 什么时候要上传 BOS
需要跨 Job 生命周期保留时,就不要只留在 OUTPUT_DIR:
- clip
- annotation
- package
- 报表
- 大型结果集
7. 自定义算子的文档体系
这次仓库把自定义算子文档拆成三层:
- 本手册:平台级规则
- 模板与示例:
docs/custom-operators/README.md - 实例级分册:
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 型
适合:
- 字段提取
- 聚合统计
- 路由判断
- 清洗和映射
基本流程:
- 读取
INPUT_ARTIFACTS_PATH - 优先从
artifact.data取 payload - 做纯结构化处理
- 输出 JSON artifact
9.2 文件处理型
适合:
- 视频
- 压缩包
- 大型报表
- 目录级产物
基本流程:
- 解析 artifact 引用
- 必要时物化到本地
- 在
OUTPUT_DIR写结果 - 生成 artifact 和 stage manifest
- 必要时上传对象存储
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. 验收要求
每个正式自定义算子上线前,至少满足:
- 有一篇独立 Markdown 文档
- 有明确输入输出契约
- 有最小测试或脚本级验证
- 有一次真实工作流回归
- 有外部副作用核验证据
- 版本号、镜像 tag、digest 和验收记录能对应起来
建议证据:
- 文档链接
- 节点配置示例
- 一次成功 run
- 一份 stage manifest
- 一组真实产物