droboticflow/docs/operator-authoring.md
2026-06-17 13:35:21 +08:00

17 KiB
Raw Blame History

算子开发文档

本文档基于当前仓库的真实实现,说明在 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

注意:算子之间传输的不是共享内存,也不是直接传文件句柄,而是 artifact。

执行链路如下:

  1. 上游节点执行完成
  2. 上游节点产出 ExecutionArtifact[]
  3. worker 把这些 artifact 持久化到当前 run 的执行记录中
  4. 下游节点启动前,worker 按 DAG 边关系筛选对应的 artifact
  5. worker 把这些 artifact 写入共享工作区的 input-artifacts.json
  6. worker 通过 INPUT_ARTIFACTS_PATH 把输入文件路径传给下游算子

也就是说,跨算子的数据传输核心仍然是 artifact 契约,但主链路已经改成“共享 PVC 上的文件化 manifest + 轻量环境变量指针”,不再依赖大体积 env 直传。

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
  • 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=<path>

worker 再通过结果文件读取日志、artifact、资源采样,并回写到 run 记录。

3. Artifact 契约

artifact 是算子之间的统一数据交换格式。一个 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 字段,格式建议为 <registry>/<namespace>/<image>:<tag>
  • 不要使用 latest 作为长期运行版本标签
  • 不要把 droboticflow-operator-runner:* 这类平台内建 runner 镜像当成自定义镜像填写

在当前部署环境中,推荐使用与平台一致的百度云 CCR,例如:

ccr-29eug8s3-pub.cnc.bj.baidubce.com/dataflow/custom-<operator-name>:<tag>

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 时,建议按这个结构写:

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. 相关文件