droboticflow/docs/operators/CSV-转-JSON.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

4.7 KiB
Raw Blame History

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 和关键产物路径,便于后续回归对照。

相关文档