droboticflow/docs/operator-authoring.md
eust-w 43326d6a5e feat(platform): land workflow, data tooling, and docs updates
Include the accumulated workflow scheduling, run history, subtree rerun, operator UI, deployment, data asset, object storage, database browser, and documentation changes currently in the worktree.
2026-04-24 12:29:46 +08:00

16 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
  • 由 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 内所有节点保持一致

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),
        )
    ]

然后再把它接入 main() 的 handler 分发逻辑。

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