# 算子开发文档 本文档基于当前仓库的真实实现,说明在 Drobodata 中如何创建新算子、算子运行时能拿到什么、如何接入 BOS、如何正确产出 artifact,以及在 Kubernetes 模式下需要注意哪些持久化问题。 相关实现入口: - `internal/worker/executor.go` - `internal/worker/runtime.go` - `internal/k8s/launcher.go` - `backend/operator-runner/main.py` - `internal/domain/types.go` ## 1. 总体执行模型 Drobodata 的算子执行分为三层: 1. 前端保存工作流 DAG,也就是 `nodes + edges` 2. Go worker 负责调度 DAG、收集上游 artifact、启动节点执行 3. Python operator-runner 真正执行算子逻辑,并把结果回传给 worker 注意:算子之间传输的不是跨 Job 共享内存或直接文件句柄,而是带端口语义的 artifact。新协议支持小 JSON 的值传递(`payload.mode=inline`)以及对象、目录、大 JSON 和二进制的引用传递(`payload.mode=ref`)。 执行链路如下: 1. 上游节点执行完成 2. 上游节点产出 `ExecutionArtifact[]` 3. worker 把这些 artifact 持久化到当前 run 的执行记录中 4. 下游节点启动前,worker 按 DAG 边关系筛选对应的 artifact 5. worker 把这些 artifact 写入共享工作区的 `input-artifacts.json`,并把按 `targetPortId` 分组后的绑定写入 `input-bindings.json` 6. worker 通过 `INPUT_ARTIFACTS_PATH` 把输入文件路径传给下游算子 算子可通过 `INPUT_BINDINGS_PATH` 获得端口到 payload/artifact 的准确映射;为兼容历史算子,`INPUT_ARTIFACTS_PATH` 仍保留扁平列表。小清单会另外提供 `INPUT_BINDINGS_JSON` / `INPUT_ARTIFACTS_JSON`,超过 64 KiB 时只传文件路径。 ## 2. 算子运行时会收到什么 worker 在执行节点前,会构造一组环境变量注入到算子进程或算子容器中。 基础环境变量包括: - `RUN_ID` - `WORKFLOW_ID` - `NODE_ID` - `NODE_LABEL` - `NODE_TYPE` - `NODE_CATEGORY` - `NODE_DESCRIPTION` - `NODE_DATA_JSON` - `INPUT_ARTIFACTS_PATH` - `RESULT_OUTPUT_PATH` - `STAGE_MANIFEST_PATH` - `OUTPUT_DIR` - `WORKFLOW_PREVIOUS_RUN_TIMESTAMP` - `WORKFLOW_CURRENT_RUN_TIMESTAMP` 还可能注入额外变量: - `STORAGE_BUCKET` - `STORAGE_PREFIX` - `STORAGE_PATTERN` - `CPU_LIMIT` - `MEMORY_LIMIT` - `NODE_IMAGE` - `PLATFORM_MONGO_URI` - `PLATFORM_MONGO_DB` - `OPERATOR_ALLOW_SHELL_COMMANDS` - `OPERATOR_COMMAND_ALLOWLIST_REGEX` - `OPERATOR_COMMAND_DENYLIST_REGEX` - 由 hyperparams 展开的变量,例如 `BOS_ENDPOINT`、`BOS_ACCESS_KEY_ID`、`COMMAND`、`MONGO_URI` 其中两个工作流级时间变量需要特别注意: - `WORKFLOW_PREVIOUS_RUN_TIMESTAMP` - 仅对 `scheduled` run 注入 - 上一轮 workflow trigger 的真实时间字符串 - 格式固定为 `Asia/Shanghai` 时区下的 RFC3339,例如 `2026-04-22T14:37:53+08:00` - 首次周期运行时固定为空字符串 - `WORKFLOW_CURRENT_RUN_TIMESTAMP` - 本轮 workflow trigger 的真实时间字符串 - 格式固定为 `Asia/Shanghai` 时区下的 RFC3339,例如 `2026-04-22T14:37:53+08:00` - 在 run 创建时固化,对该 run 内所有节点保持一致 - `CPU_LIMIT` / `MEMORY_LIMIT` / `GPU_LIMIT` - 节点资源配置的运行时提示值 - CPU/MEM 会同时写入 Kubernetes Job resources,显式值必须是合法且大于 0 的 Kubernetes resource quantity;GPU 正整数会写入 `nvidia.com/gpu` request/limit - GPU 算子镜像需要自行包含 CUDA/NVIDIA 运行依赖,集群也必须已安装 NVIDIA device plugin/runtime - 平台级 GPU nodeSelector、tolerations、runtimeClass 只会注入到 `GPU_LIMIT` 为正数的 Job - Worker 会在创建 GPU Job 前检查 Kubernetes Node allocatable `nvidia.com/gpu`;当前集群无可调度 GPU 时会直接失败并返回 `gpu request cannot be scheduled`,不会创建长时间 Pending 的 Job - `sharedMemorySize` / `/dev/shm` - 可在算子默认资源和工作流节点资源中配置,例如 `8Gi` 或 `16Gi` - 生效优先级为“节点覆盖值 > 算子默认值 > 平台 `DROBOTICFLOW_SHARED_MEMORY_SIZE`”,空值表示继承 - Kubernetes Job 使用可读写的内存型 `emptyDir` 挂载到 `/dev/shm`;容量是上限,实际使用仍会占用 Pod/节点内存 - `OPERATOR_ALLOW_SHELL_COMMANDS` / `OPERATOR_COMMAND_ALLOWLIST_REGEX` / `OPERATOR_COMMAND_DENYLIST_REGEX` - 平台级 `COMMAND/SCRIPT` 执行策略,由 worker 注入到 operator-runner Job - workflow 或节点 hyperparams 不能覆盖这些值 - 默认禁止 shell 执行;确需兼容旧工作流时由部署显式设置 `OPERATOR_ALLOW_SHELL_COMMANDS=true`,并建议配合正则名单限制 Python 侧的 operator-runner 会: 1. 读取 `NODE_DATA_JSON` 2. 优先读取 `INPUT_ARTIFACTS_PATH` 3. 根据节点 label 选择内置 handler,或者执行 `COMMAND/SCRIPT` 4. 在 `OUTPUT_DIR` 下产出文件 5. 把完整执行结果写到 `RESULT_OUTPUT_PATH` 6. 把阶段摘要写到 `STAGE_MANIFEST_PATH` 7. 最后向 stdout 打印一行 `DROBOTICFLOW_RESULT_PATH=` worker 再通过结果文件读取日志、artifact、资源采样,并回写到 run 记录。 ## 3. Artifact 契约 artifact 是算子之间的统一数据交换格式。一个 artifact 可能包含以下字段: - `payload.mode=inline`:仅用于不超过 64 KiB 的 JSON 值,并随 run 记录持久化 - `payload.mode=ref`:保存 `connectionId/bucket/key|prefix/manifestKey/versionId/etag/sha256` - `ref.kind=object|directory`:区分单对象和整个目录;目录 manifest 最后写入,作为完整提交标记 Worker 在节点完成后统一规范化输出:有 artifact 存储策略时,大 JSON 和二进制上传 BOS;目录先上传文件再写 manifest;已返回合法 ref 的算子不会被重复上传。发布后的工作流必须能解析平台默认或工作流覆盖的 artifact 存储。 - `id` - `runId` - `nodeId` - `portId` - `portName` - `name` - `type` - `size` - `path` - `metadata` - `data` ### 3.1 常见 `type` 当前常用类型有: - `json` - `image` - `video` - `file` - `tensor` 建议: - 结构化输出优先用 `json` - 图像、视频尽量标准确切类型 - 其他通用文件用 `file` ### 3.2 `metadata` 的用途 `metadata` 主要用于保存文件属性与预览相关信息,常见字段有: - `mimeType` - `sha256` - `duration` - `resolution` - `codec` - `thumbnail` 如果输出文件可预览,尽量补齐 `mimeType`。 ### 3.3 `data` 的用途 `data` 在当前系统里非常重要: - JSON artifact 通常把完整结构化内容直接放在 `data` - 非 JSON artifact 往往把预览信息放在 `data.preview` - 远程对象 artifact 往往把来源信息放在 `data.source` - 上传到 BOS 后的 artifact 常带 `data.relativePath` 很多前端和 API 页面会优先读 `data` 来展示结果,而不是总去读取 `path` 对应文件。 ## 4. DAG 边如何路由数据 worker 不会把一个节点的所有输出无脑传给所有下游节点,而是按边来筛选。 筛选规则如下: 1. 找到当前节点所有入边 2. 对每条入边,找到对应的 source 节点执行结果 3. 查看 source 节点的 artifact 列表 4. 如果这条边带 `sourceHandle`,并且 source artifact 带 `portId`,则只传 `artifact.portId == edge.sourceHandle` 的 artifact 5. 如果没有端口级信息,则退化成传 source 节点的全部 artifact 因此,多输出算子必须把输出 artifact 绑定到正确的 output port,否则下游会拿到混合数据。 ## 5. 两种输出模式 新算子输出一般有两种模式。 ### 5.1 临时文件 artifact 适用于: - 在 `OUTPUT_DIR` 下真实生成了文件 - 输出内容较小,或者后续不要求强持久化 常用 helper: - `write_json_artifact(...)` - `write_text_artifact(...)` - `write_csv_artifact(...)` - `collect_output_artifacts(...)` - `build_artifact(...)` 特点: - `path` 指向共享 PVC 上当前节点的输出文件 - `metadata.sha256` 可计算 - `data` 可放完整 JSON 或预览摘要 ### 5.2 虚拟远程 artifact 适用于: - 结果主要存放在 BOS - 输出文件较大 - 结果需要跨 Kubernetes Job 生命周期持久存在 常用 helper: - `build_virtual_artifact(...)` 特点: - `path` 可以是 `bos://bucket/key` - `data.source.path` 也可以指向远程对象 - `data.preview.url` 或 `data.source.previewURL` 可放预签名 URL - 文件不一定真的存在于 `OUTPUT_DIR` 在 K8s 模式下,大文件结果更推荐这种方式。 ## 6. BOS 的接入方式 当前系统里,BOS 不是以卷挂载的方式给算子使用,而是通过 SDK 直接访问。 ### 6.1 BOS 凭据如何传到算子里 工作流节点上通常不会直接保存裸的 endpoint/AK/SK,而是可能保存一个 `connectionId`。 worker 在执行前会把它解析成实际连接参数,并写进节点 hyperparams: - `DATA_SOURCE=BOS` - `SOURCE_PATH` - `BOS_ENDPOINT` - `BOS_ACCESS_KEY_ID` - `BOS_SECRET_ACCESS_KEY` 然后这些值会随着环境变量进入 operator-runner。 ### 6.2 内置 source 算子如何使用 BOS `builtin_source(...)` 的逻辑是: 1. 判断数据源是不是 BOS 2. 如果是,则构造 `BosClient` 3. 列 BOS 对象,形成 entries 4. 产出一个 `source-manifest.json` 5. 为每个远程对象产出一个“虚拟 artifact” 这些 artifact 往往不会把对象本体下载到 Job 容器临时目录,而是保留: - `path = bos://bucket/key` - `data.source.path = bos://...` - `data.source.previewURL = 预签名 URL` 因此下游算子拿到的可能是“远程对象描述符”,不是 Job 临时文件。 ### 6.3 内置 upload 算子如何使用 BOS `builtin_upload(...)` 的逻辑是: 1. 确定上传目标 bucket/prefix 2. 必要时先把输入 artifact 物化到临时 staging 目录 3. 调用 `put_object_from_file(...)` 上传到 BOS 4. 为每个上传结果生成新的“远程 artifact” 5. 对视频等可预览媒体,生成预签名 URL 这意味着 upload 类算子除了做上传,还负责把远程落点重新包装成工作流中可继续流转的 artifact。 ## 7. 新算子应该怎么设计 新增算子前,先明确它属于哪一类。 ### 7.1 结构化处理算子 适用于: - JSON 提取 - JSON 过滤 - manifest 聚合 - 路由判断 - 规则映射 推荐方式: 1. 优先从 `artifact.data` 读取结构化输入 2. 尽量不依赖 Job 临时文件 3. 输出使用 `write_json_artifact(...)` 这是最稳妥的算子类型。 ### 7.2 文件处理算子 适用于: - 视频切片 - 图像转换 - OCR - 媒体推理 - 解压缩 推荐方式: 1. 先把输入标准化成可处理的临时文件 2. 在 Job 容器的临时工作目录处理 3. 输出写入 `OUTPUT_DIR` 4. 用 `build_artifact(...)` 或 `collect_output_artifacts(...)` 产出 artifact 5. 如果结果需要长期保留,再上传 BOS 并产出远程 artifact ### 7.3 Source 算子 适用于: - BOS 前缀扫描 - BOS 前缀扫描 - 外部数据集发现 推荐方式: 1. 收集外部数据条目 2. 产出一个 manifest JSON 3. 按需为每个条目生成 artifact 4. 如果支持增量语义,再输出 checkpoint artifact ### 7.4 Sink 算子 适用于: - 上传到 BOS - 写入 MongoDB - 推送到外部业务系统 推荐方式: 1. 接受上游 artifact 2. 解析出结构化内容或临时文件 3. 写入目标系统 4. 输出一份 summary JSON 5. 如果目标系统里有远程对象,再顺便产出虚拟远程 artifact ## 8. 新算子的输入处理规范 不要直接假设 `artifact["path"]` 一定可读。 建议按下面顺序处理输入: 1. 如果算子可以直接消费结构化内容,优先读 `artifact.data` 2. 如果 `artifact.path` 是 Job 容器内的临时路径且文件存在,直接读取该文件 3. 如果 `artifact.path` 是 `bos://...`,要么下载到临时目录,要么按远程模式处理 4. 如果 `artifact.data.source.path` 是 `bos://...`,可把它当真实远程源 5. 如果只有 `data.preview.url` 或 `data.source.previewURL`,只能把它当预览信息,不能默认等价于原始文件 6. 上述都不满足时,明确报错 如果你的算子需要“真实文件”,建议统一在 `OUTPUT_DIR/work` 或类似 staging 目录里做输入物化。这里的 `OUTPUT_DIR` 已经位于共享 PVC 的节点工作目录下。 ## 9. 新算子的输出处理规范 每次实现输出时,先问自己几个问题: 1. 这是结构化 JSON 吗? 2. 这是 Job 临时文件吗? 3. 这是应该长期保存的远程对象吗? 4. 这个算子有多个输出口吗? 5. 前端是否需要预览? 推荐映射: - 结构化 JSON:`write_json_artifact(...)` - 临时文件:`build_artifact(...)` - 整个输出目录:`collect_output_artifacts(...)` - 远程 BOS 输出:上传后 `build_virtual_artifact(...)` 如果算子有多个输出口,必须把 artifact 绑定到对应的 output。 ## 10. 多输出算子必须做的事 如果一个算子定义了多个 output port,生成 artifact 时必须传入对应的 output binding。 否则: - `artifact.portId` 不会被设置 - worker 就无法按 `edge.sourceHandle` 路由 - 下游节点会错误地接收到全部输出 结论很直接:多输出算子如果不写 `portId/portName`,基本等于没实现好多输出。 ## 11. Kubernetes 模式下最重要的注意事项 这是当前实现中最容易踩坑的地方。 在 Kubernetes 模式下: - worker 会创建一个 Job - worker、API 和 Job 会共享同一个工作 PVC - 节点目录下至少会出现: - `input-artifacts.json` - `result.json` - `stage-manifest.json` - `outputs/` 因此: - `OUTPUT_DIR` 下的文件可以在后续 Job 中继续读取 - 但它们仍然属于运行期热数据,不应替代长期归档存储 所以开发新算子时必须遵守一个原则: - 如果输出是关键结果、体积较大、后续还要访问,就不要只写临时文件 - 应优先上传到 BOS 或其他持久化后端,并返回远程 artifact 当前系统只支持 Kubernetes Job 执行,因此不要把这类临时路径当成跨 Job 生命周期可复用的稳定存储。 当前系统只支持 Kubernetes Job 执行,因此共享 PVC 适合作为热数据与中间结果层,长期结果仍应优先上传到 BOS。 ## 12. 创建新算子时除了代码还要做什么 只写 handler 还不够,还需要把算子注册进系统目录。 一个完整的算子定义至少应包含: - `name` - `type` - `category` - `description` - `inputs` - `outputs` - 可选 `image` - 可选 `hyperparams` 特别要注意: - Python 内置 handler 的选择目前与节点 label 强相关 - 所以算子目录中的 `name/label` 要和 handler 路由保持一致 - 算子定义里的输入输出端口,要和实际 artifact 的输出绑定一致 如果这是一个依赖自定义容器镜像的算子,还要额外遵守下面的镜像登记规则: - 镜像由用户自己构建并推送到外部容器仓库 - 平台不会代替用户构建、推送或托管自定义镜像 - 用户需要把完整镜像地址填写到 `image` 字段,格式建议为 `//:` - 不要使用 `latest` 作为长期运行版本标签 - 不要把 `droboticflow-operator-runner:*` 这类平台内建 runner 镜像当成自定义镜像填写 在当前部署环境中,推荐使用与平台一致的百度云 CCR,例如: ```text ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-: ``` ## 13. 新算子开发检查清单 在提交前,至少检查下面这些点: - 算子在空输入、坏路径、非法 BOS 参数下能明确报错 - 算子不假设所有输入都有可持续存在的临时文件 - 算子支持 BOS artifact 或能清晰拒绝不支持的输入 - 临时文件全部写在 `OUTPUT_DIR` 下 - 最终一定返回合法 artifact,而不是只打印日志 - 结构化结果优先用 `write_json_artifact(...)` - 需要长期保存的大文件输出会上传 BOS 或其他持久化后端 - 多输出 artifact 正确带 `portId/portName` - 预览友好的输出带 `metadata.mimeType` - UI 需要预览时,尽量补 `data.preview` - 即使临时文件未来消失,artifact 的 `data` 依然尽可能保留有用摘要 ## 14. 新内置算子的推荐代码模板 在 `backend/operator-runner/main.py` 中新增 handler 时,建议按这个结构写: ```python def builtin_my_operator( run_id: str, node_id: str, output_dir: pathlib.Path, node_data: dict[str, Any], inputs: list[dict[str, Any]], ) -> list[dict[str, Any]]: params = hyperparams(node_data) work_dir = output_dir / "work" work_dir.mkdir(parents=True, exist_ok=True) # 1. 解析 inputs # 2. 必要时把 bos:// 或远程对象下载到 work_dir # 3. 执行业务逻辑 # 4. 写临时输出或上传远程输出 # 5. 返回 artifact 列表 payload = { "ok": True, "inputCount": len(inputs), } return [ write_json_artifact( run_id, node_id, output_dir, "result.json", payload, output=output_binding(node_data), ) ] ``` 然后把它接入 `BUILTIN_HANDLERS`,如果需要根据节点 label 自动匹配,再把关键词接入 `BUILTIN_HANDLER_RULES`。 ## 15. 常见错误 以下是新增算子时最常见的实现错误: - 直接读取 `artifact.path`,却没有判断它是不是 `bos://...` - 只打印日志,没有输出 `DROBOTICFLOW_RESULT_PATH=...` - 生成了文件,但没有包装成 artifact - 多输出算子没写 `portId` - 把 `previewURL` 当成原文件长期来源 - 在 K8s 模式下把共享 PVC 当成长期归档存储 - 漏掉 `mimeType`,导致预览和 API 内容服务退化 - 对大文件直接把完整内容塞进 `data.preview` ## 16. 什么时候应该在算子内部直接上传 BOS 以下情况建议在算子内部直接上传 BOS,而不是只写临时文件: - 输出文件很大 - 输出必须跨 Job 生命周期保留 - API 或前端后续需要稳定的远程路径 - 需要为媒体生成可访问的预签名预览 URL 以下情况临时输出也可以接受: - 输出很小 - 主要价值已经体现在 `data` 里 - 只作为单个 Job 内部的中间产物使用 - 后续节点只关心结构化摘要,不关心原始文件 ## 17. 相关文件 - [backend/operator-runner/main.py](../backend/operator-runner/main.py) - [internal/worker/executor.go](../internal/worker/executor.go) - [internal/worker/runtime.go](../internal/worker/runtime.go) - [internal/k8s/launcher.go](../internal/k8s/launcher.go) - [internal/domain/types.go](../internal/domain/types.go) - [docs/api.md](./api.md) - [docs/operations.md](./operations.md)