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.
4.7 KiB
4.7 KiB
CSV 转 JSON
- 算子 ID:
operator-builtin-csv-to-json - 类别:
DATA - 类型:
builtin
作用
将真实 CSV/TSV 文件转换成结构化 JSON 行列表。
定位与职责边界
- 该算子属于
DATA类,当前登记类型是builtin。 - 平台会在
/api/operators中自动提供该算子元数据,运行时由 operator-runner 的既有 handler 接管。 - 它更偏向结构化中间层,用于整理、筛选、转换、路由或补充数据。
平台语义
读取 SOURCE_PATH 或上游 source manifest 指向的 csv/tsv 文件,输出完整 JSON 行数据。
运行时契约
- Worker 会先把上游 artifact 汇总到
INPUT_ARTIFACTS_PATH,再把节点配置通过NODE_DATA_JSON注入运行容器。 - 节点执行结果会写入
OUTPUT_DIR、RESULT_OUTPUT_PATH和STAGE_MANIFEST_PATH对应的文件,再由 worker 汇总进运行记录。 - 大文件和大 JSON 不应依赖 API 内联传输,应该通过
artifact.path、dataRef.payloadPath、共享 PVC 或对象存储引用传递。 - 当前实现入口通常可追到
backend/operator-runner/main.py中的builtin_csv_to_json(...)。
设计边界
- 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。
- 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。
数据流示意
flowchart LR
A[上游输入或运行时注入] --> B[CSV 转 JSON]
B --> C[artifact / stage manifest / 外部副作用]
输入端口详解
in-1/ input /json/bus:CSV/TSV 输入 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。
输出端口详解
out-1/ table /json/bus:JSON 行列表 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。
关键超参数
SOURCE_PATH:类型string,默认值 空字符串或由工作流显式填写。csv/tsv 文件路径 通常建议在工作流中显式配置。
执行前准备
- 先确认上下游端口类型兼容,特别是
json、file、video等端口不要混接。 - 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。
- 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。
数据通信与存储路径
- 标准输入来自
INPUT_ARTIFACTS_PATH指向的 artifact 列表文件,artifact 可同时包含data、path、metadata与dataRef。 - 标准输出写入
OUTPUT_DIR,并通过stage-manifest.json对外暴露产物路径、payload 引用和摘要元数据。
典型上下游编排
- 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。
节点配置示例
{
"label": "CSV 转 JSON",
"operatorId": "operator-builtin-csv-to-json",
"type": "builtin",
"category": "DATA",
"hyperparams": {
"SOURCE_PATH": "<按节点填写>"
}
}
输入输出示例
- 典型输入:worker 会把上游 artifact 序列化为
INPUT_ARTIFACTS_PATH文件供节点读取。 - 典型输出:节点会在
OUTPUT_DIR下写业务文件,并在stage-manifest.json里登记对外可消费的结果。
成功判定
- 节点 execution 状态为
completed,且日志中没有隐藏的回退错误或重试未果记录。 stage-manifest.json中能看到期望的 artifact 条目,且下游节点可以正常消费这些结果。
常见失败与排查
- 如果看不到预期结果,先检查
OUTPUT_DIR、RESULT_OUTPUT_PATH和STAGE_MANIFEST_PATH是否真实写出。 - 如果下游收不到数据,先检查当前节点输出 artifact 是否设置了正确的
portId、portName和type。 - 如果日志中只有摘要没有大 payload,优先排查
dataRef.payloadPath或外置文件是否存在,而不是误以为结果丢失。
验收检查清单
- 至少在一条真实工作流中跑通该算子,而不是只验证单元测试或空输入。
- 确认该节点输出被下游节点实际消费,避免出现“本节点成功但链路无效”的假阳性。
- 保留一次成功运行的示例日志、stage manifest 和关键产物路径,便于后续回归对照。