forked from longtao.wu/droboticflow
535 lines
13 KiB
Markdown
535 lines
13 KiB
Markdown
# Drobodata 自定义算子手册
|
||
|
||
本文档面向平台研发、算法工程师和工作流设计者,说明在当前架构下如何设计、实现、调试、文档化和验收自定义算子。
|
||
|
||
配套文档:
|
||
|
||
- [内建算子手册](./builtin-operators-manual.zh-CN.md)
|
||
- [内建算子分册索引](./operators/README.md)
|
||
- [自定义算子分册体系](./custom-operators/README.md)
|
||
- [算子开发文档](./operator-authoring.md)
|
||
|
||
相关实现入口:
|
||
|
||
- `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 命令型验证
|
||
|
||
最常见的起点是:
|
||
|
||
- [Shell 命令执行](./operators/Shell-命令执行.md)
|
||
- [模型推理](./operators/模型推理.md)
|
||
|
||
适合:
|
||
|
||
- 快速验证
|
||
- 小范围项目定制
|
||
- 临时脚本或受控命令执行
|
||
|
||
优点:
|
||
|
||
- 上手快
|
||
- 无需改平台主逻辑
|
||
|
||
问题:
|
||
|
||
- 约束弱
|
||
- 复用差
|
||
- 难统一回归
|
||
|
||
### 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 命名方式,例如:
|
||
|
||
```text
|
||
ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-<operator-name>:<tag>
|
||
```
|
||
|
||
如果你当前接的是百度云 CCR `xspark` 命名空间,并希望让用户自己推镜像再在算子里填写 `image`,请直接参考:
|
||
|
||
- [百度云 CCR `xspark` 自定义算子接入指南](./custom-operators/百度云-CCR-xspark-自定义算子接入指南.md)
|
||
|
||
这份分册包含:
|
||
|
||
- `xspark` 私有镜像的真实验收结论
|
||
- 登录、推送、填写 `image` 的标准流程
|
||
- 自定义镜像最小运行协议
|
||
- 一个可直接复制的最小 Dockerfile / `run.sh` 示例
|
||
- 常见失败模式与排障方式
|
||
|
||
特别注意:
|
||
|
||
- 不要把 `droboticflow-operator-runner:*` 当成自定义镜像名填写
|
||
- 这类平台内建 runner 镜像在运行时可能被系统镜像覆盖,不适合作为自定义算子的独立镜像地址
|
||
|
||
### 3.5 skillDefinition
|
||
|
||
`skillDefinition` 不应该只写一句简介。
|
||
|
||
它应该是给未来工作流生成器、平台维护者和文档脚本看的高密度说明,至少覆盖:
|
||
|
||
- 输入需要什么结构
|
||
- 输出会产生什么结果
|
||
- 超参数分别控制什么
|
||
- 哪些场景适合用
|
||
- 哪些场景不该用
|
||
- 失败时怎么理解
|
||
|
||
如果你愿意,`skillDefinition` 可以直接按 Markdown 写,这也是本仓库现在推荐的方向。
|
||
|
||
## 4. 输入输出契约
|
||
|
||
### 4.1 输入不是“只有 path”
|
||
|
||
自定义算子最常见的错误,是假设输入永远长这样:
|
||
|
||
```python
|
||
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`](./custom-operators/README.md)
|
||
3. 实例级分册:[`docs/custom-operators/instances/README.md`](./custom-operators/instances/README.md)
|
||
|
||
你应该为每个长期存在的自定义算子单独维护一篇 Markdown,至少包括:
|
||
|
||
- 作用与边界
|
||
- 输入输出契约
|
||
- 端口语义
|
||
- 超参数
|
||
- 运行时依赖
|
||
- 配置示例
|
||
- 失败模式
|
||
- 验收口径
|
||
|
||
## 8. 推荐开发流程
|
||
|
||
### 8.1 第一步:先写文档,再写实现
|
||
|
||
在动手之前,先用 [`自定义算子设计模板`](./custom-operators/templates/自定义算子设计模板.md) 写清楚:
|
||
|
||
- 它解决什么问题
|
||
- 它的输入是什么
|
||
- 它的输出是什么
|
||
- 为什么现有内建算子不够
|
||
- 它未来是否可能内建化
|
||
|
||
### 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. 相关资料
|
||
|
||
- [内建算子手册](./builtin-operators-manual.zh-CN.md)
|
||
- [自定义算子分册体系](./custom-operators/README.md)
|
||
- [算子开发文档](./operator-authoring.md)
|
||
- [平台使用手册](./platform-usage-manual.zh-CN.md)
|