17 KiB
算子开发文档
本文档基于当前仓库的真实实现,说明在 Drobodata 中如何创建新算子、算子运行时能拿到什么、如何接入 BOS、如何正确产出 artifact,以及在 Kubernetes 模式下需要注意哪些持久化问题。
相关实现入口:
internal/worker/executor.gointernal/worker/runtime.gointernal/k8s/launcher.gobackend/operator-runner/main.pyinternal/domain/types.go
1. 总体执行模型
Drobodata 的算子执行分为三层:
- 前端保存工作流 DAG,也就是
nodes + edges - Go worker 负责调度 DAG、收集上游 artifact、启动节点执行
- Python operator-runner 真正执行算子逻辑,并把结果回传给 worker
注意:算子之间传输的不是共享内存,也不是直接传文件句柄,而是 artifact。
执行链路如下:
- 上游节点执行完成
- 上游节点产出
ExecutionArtifact[] - worker 把这些 artifact 持久化到当前 run 的执行记录中
- 下游节点启动前,worker 按 DAG 边关系筛选对应的 artifact
- worker 把这些 artifact 写入共享工作区的
input-artifacts.json - worker 通过
INPUT_ARTIFACTS_PATH把输入文件路径传给下游算子
也就是说,跨算子的数据传输核心仍然是 artifact 契约,但主链路已经改成“共享 PVC 上的文件化 manifest + 轻量环境变量指针”,不再依赖大体积 env 直传。
2. 算子运行时会收到什么
worker 在执行节点前,会构造一组环境变量注入到算子进程或算子容器中。
基础环境变量包括:
RUN_IDWORKFLOW_IDNODE_IDNODE_LABELNODE_TYPENODE_CATEGORYNODE_DESCRIPTIONNODE_DATA_JSONINPUT_ARTIFACTS_PATHRESULT_OUTPUT_PATHSTAGE_MANIFEST_PATHOUTPUT_DIRWORKFLOW_PREVIOUS_RUN_TIMESTAMPWORKFLOW_CURRENT_RUN_TIMESTAMP
还可能注入额外变量:
STORAGE_BUCKETSTORAGE_PREFIXSTORAGE_PATTERNCPU_LIMITMEMORY_LIMITNODE_IMAGEPLATFORM_MONGO_URIPLATFORM_MONGO_DBOPERATOR_ALLOW_SHELL_COMMANDSOPERATOR_COMMAND_ALLOWLIST_REGEXOPERATOR_COMMAND_DENYLIST_REGEX- 由 hyperparams 展开的变量,例如
BOS_ENDPOINT、BOS_ACCESS_KEY_ID、COMMAND、MONGO_URI
其中两个工作流级时间变量需要特别注意:
WORKFLOW_PREVIOUS_RUN_TIMESTAMP- 仅对
scheduledrun 注入 - 上一轮 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/gpurequest/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
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 会:
- 读取
NODE_DATA_JSON - 优先读取
INPUT_ARTIFACTS_PATH - 根据节点 label 选择内置 handler,或者执行
COMMAND/SCRIPT - 在
OUTPUT_DIR下产出文件 - 把完整执行结果写到
RESULT_OUTPUT_PATH - 把阶段摘要写到
STAGE_MANIFEST_PATH - 最后向 stdout 打印一行
DROBOTICFLOW_RESULT_PATH=<path>
worker 再通过结果文件读取日志、artifact、资源采样,并回写到 run 记录。
3. Artifact 契约
artifact 是算子之间的统一数据交换格式。一个 artifact 可能包含以下字段:
idrunIdnodeIdportIdportNamenametypesizepathmetadatadata
3.1 常见 type
当前常用类型有:
jsonimagevideofiletensor
建议:
- 结构化输出优先用
json - 图像、视频尽量标准确切类型
- 其他通用文件用
file
3.2 metadata 的用途
metadata 主要用于保存文件属性与预览相关信息,常见字段有:
mimeTypesha256durationresolutioncodecthumbnail
如果输出文件可预览,尽量补齐 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 不会把一个节点的所有输出无脑传给所有下游节点,而是按边来筛选。
筛选规则如下:
- 找到当前节点所有入边
- 对每条入边,找到对应的 source 节点执行结果
- 查看 source 节点的 artifact 列表
- 如果这条边带
sourceHandle,并且 source artifact 带portId,则只传artifact.portId == edge.sourceHandle的 artifact - 如果没有端口级信息,则退化成传 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/keydata.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=BOSSOURCE_PATHBOS_ENDPOINTBOS_ACCESS_KEY_IDBOS_SECRET_ACCESS_KEY
然后这些值会随着环境变量进入 operator-runner。
6.2 内置 source 算子如何使用 BOS
builtin_source(...) 的逻辑是:
- 判断数据源是不是 BOS
- 如果是,则构造
BosClient - 列 BOS 对象,形成 entries
- 产出一个
source-manifest.json - 为每个远程对象产出一个“虚拟 artifact”
这些 artifact 往往不会把对象本体下载到 Job 容器临时目录,而是保留:
path = bos://bucket/keydata.source.path = bos://...data.source.previewURL = 预签名 URL
因此下游算子拿到的可能是“远程对象描述符”,不是 Job 临时文件。
6.3 内置 upload 算子如何使用 BOS
builtin_upload(...) 的逻辑是:
- 确定上传目标 bucket/prefix
- 必要时先把输入 artifact 物化到临时 staging 目录
- 调用
put_object_from_file(...)上传到 BOS - 为每个上传结果生成新的“远程 artifact”
- 对视频等可预览媒体,生成预签名 URL
这意味着 upload 类算子除了做上传,还负责把远程落点重新包装成工作流中可继续流转的 artifact。
7. 新算子应该怎么设计
新增算子前,先明确它属于哪一类。
7.1 结构化处理算子
适用于:
- JSON 提取
- JSON 过滤
- manifest 聚合
- 路由判断
- 规则映射
推荐方式:
- 优先从
artifact.data读取结构化输入 - 尽量不依赖 Job 临时文件
- 输出使用
write_json_artifact(...)
这是最稳妥的算子类型。
7.2 文件处理算子
适用于:
- 视频切片
- 图像转换
- OCR
- 媒体推理
- 解压缩
推荐方式:
- 先把输入标准化成可处理的临时文件
- 在 Job 容器的临时工作目录处理
- 输出写入
OUTPUT_DIR - 用
build_artifact(...)或collect_output_artifacts(...)产出 artifact - 如果结果需要长期保留,再上传 BOS 并产出远程 artifact
7.3 Source 算子
适用于:
- BOS 前缀扫描
- BOS 前缀扫描
- 外部数据集发现
推荐方式:
- 收集外部数据条目
- 产出一个 manifest JSON
- 按需为每个条目生成 artifact
- 如果支持增量语义,再输出 checkpoint artifact
7.4 Sink 算子
适用于:
- 上传到 BOS
- 写入 MongoDB
- 推送到外部业务系统
推荐方式:
- 接受上游 artifact
- 解析出结构化内容或临时文件
- 写入目标系统
- 输出一份 summary JSON
- 如果目标系统里有远程对象,再顺便产出虚拟远程 artifact
8. 新算子的输入处理规范
不要直接假设 artifact["path"] 一定可读。
建议按下面顺序处理输入:
- 如果算子可以直接消费结构化内容,优先读
artifact.data - 如果
artifact.path是 Job 容器内的临时路径且文件存在,直接读取该文件 - 如果
artifact.path是bos://...,要么下载到临时目录,要么按远程模式处理 - 如果
artifact.data.source.path是bos://...,可把它当真实远程源 - 如果只有
data.preview.url或data.source.previewURL,只能把它当预览信息,不能默认等价于原始文件 - 上述都不满足时,明确报错
如果你的算子需要“真实文件”,建议统一在 OUTPUT_DIR/work 或类似 staging 目录里做输入物化。这里的 OUTPUT_DIR 已经位于共享 PVC 的节点工作目录下。
9. 新算子的输出处理规范
每次实现输出时,先问自己几个问题:
- 这是结构化 JSON 吗?
- 这是 Job 临时文件吗?
- 这是应该长期保存的远程对象吗?
- 这个算子有多个输出口吗?
- 前端是否需要预览?
推荐映射:
- 结构化 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.jsonresult.jsonstage-manifest.jsonoutputs/
因此:
OUTPUT_DIR下的文件可以在后续 Job 中继续读取- 但它们仍然属于运行期热数据,不应替代长期归档存储
所以开发新算子时必须遵守一个原则:
- 如果输出是关键结果、体积较大、后续还要访问,就不要只写临时文件
- 应优先上传到 BOS 或其他持久化后端,并返回远程 artifact
当前系统只支持 Kubernetes Job 执行,因此不要把这类临时路径当成跨 Job 生命周期可复用的稳定存储。 当前系统只支持 Kubernetes Job 执行,因此共享 PVC 适合作为热数据与中间结果层,长期结果仍应优先上传到 BOS。
12. 创建新算子时除了代码还要做什么
只写 handler 还不够,还需要把算子注册进系统目录。
一个完整的算子定义至少应包含:
nametypecategorydescriptioninputsoutputs- 可选
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 内部的中间产物使用
- 后续节点只关心结构化摘要,不关心原始文件