553 lines
18 KiB
Markdown
553 lines
18 KiB
Markdown
# 算子开发文档
|
||
|
||
本文档基于当前仓库的真实实现,说明在 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=<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` 字段,格式建议为 `<registry>/<namespace>/<image>:<tag>`
|
||
- 不要使用 `latest` 作为长期运行版本标签
|
||
- 不要把 `droboticflow-operator-runner:*` 这类平台内建 runner 镜像当成自定义镜像填写
|
||
|
||
在当前部署环境中,推荐使用与平台一致的百度云 CCR,例如:
|
||
|
||
```text
|
||
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 时,建议按这个结构写:
|
||
|
||
```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)
|