# 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 填写要求: - 必须填写完整镜像引用,格式建议为 `//:` - 不要依赖 `latest`,应使用明确版本标签,方便回滚和排障 - 镜像仓库必须能被当前集群拉取 当前部署环境里,推荐沿用与平台一致的百度云 CCR 命名方式,例如: ```text ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-: ``` 如果你当前接的是百度云 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)