droboticflow/docs/operators/6DRepNet-Headpose.md

6.1 KiB
Raw Blame History

6DRepNet Headpose

  • 算子 ID:operator-builtin-head-pose
  • 类别:AI
  • 类型:builtin

作用

调用 digest 固定的 6DRepNet 服务,对图片或视频输出逐帧头部 yaw/pitch/roll、置信度和运行证据。

定位与职责边界

  • 该算子属于 AI 类,当前登记类型是 builtin。
  • 平台会在 /api/operators 中自动提供该算子元数据,运行时由 operator-runner 委派到独立算子入口。

平台语义

真实调用 6DRepNet 服务,输出逐帧 yaw/pitch/roll、置信度、标注媒体引用和服务镜像证据。

运行时契约

  • Worker 会先把上游 artifact 汇总到 INPUT_ARTIFACTS_PATH,再把节点配置通过 NODE_DATA_JSON 注入运行容器。
  • 节点执行结果会写入 OUTPUT_DIR、RESULT_OUTPUT_PATH 和 STAGE_MANIFEST_PATH 对应的文件,再由 worker 汇总进运行记录。
  • 大文件和大 JSON 不应依赖 API 内联传输,应该通过 artifact.path、dataRef.payloadPath、共享 PVC 或对象存储引用传递。
  • 当前独立实现入口是 operator-repos/builtin/head_pose/src/operator.py 中的 run(...),平台 runtimeHandler 为 builtin_head_pose。

设计边界

  • 该算子应该只承担单一职责,不应在一个节点里同时混合索引、筛选、上传、审核等多个阶段性行为。
  • 如果一个节点要消费多个语义不同的结果,优先通过多节点拆分,而不是把所有逻辑塞进一个超大脚本。

数据流示意

flowchart LR
  A[上游输入或运行时注入] --> B[6DRepNet Headpose]
  B --> C[artifact / stage manifest / 外部副作用]

输入端口详解

  • in-1 / media / json / bus:图片/视频 artifact 或媒体清单 作为输入端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。

输出端口详解

  • out-1 / headpose / json / bus:droboticflow.headpose/v1 manifest 作为输出端口时,适合结构化清单、规则结果、摘要对象等可直接序列化的数据。 通过统一 artifact 契约传递;大 payload 会外置到 stage manifest / payloadPath。

关键超参数

  • HEADPOSE_API_BASE_URL:类型 string,默认值 空字符串或由工作流显式填写。6DRepNet 服务地址 通常建议在工作流中显式配置。
  • HEADPOSE_MODEL:类型 string,默认值 6DRepNet。模型名称 可直接使用默认值,也可在节点级覆盖。
  • FRAME_STRIDE:类型 integer,默认值 3。视频抽帧间隔 可直接使用默认值,也可在节点级覆盖。
  • MAX_FRAMES:类型 integer,默认值 120。最多采样帧数 可直接使用默认值,也可在节点级覆盖。
  • REQUEST_TIMEOUT_SECONDS:类型 integer,默认值 300。请求超时秒数 可直接使用默认值,也可在节点级覆盖。
  • HEADPOSE_SERVICE_IMAGE_ID:类型 string,默认值 空字符串或由工作流显式填写。digest 固定的服务镜像 通常建议在工作流中显式配置。
  • HEADPOSE_MODEL_SHA256:类型 string,默认值 空字符串或由工作流显式填写。6DRepNet 权重 SHA-256 通常建议在工作流中显式配置。
  • HEADPOSE_LICENSE_ID:类型 string,默认值 空字符串或由工作流显式填写。模型与代码许可证标识 通常建议在工作流中显式配置。

执行前准备

  • 先确认上下游端口类型兼容,特别是 json、file、video 等端口不要混接。
  • 为每个关键超参数补齐明确值,避免依赖隐式默认值进入生产工作流。
  • 对需要跨节点长期保留的产物,提前规划对象存储前缀或外部落库集合,而不是只写临时目录。

数据通信与存储路径

  • 标准输入来自 INPUT_ARTIFACTS_PATH 指向的 artifact 列表文件,artifact 可同时包含 data、path、metadata 与 dataRef。
  • 标准输出写入 OUTPUT_DIR,并通过 stage-manifest.json 对外暴露产物路径、payload 引用和摘要元数据。

典型上下游编排

  • 该算子通常位于同类数据处理节点之间,承担结构化中间层职责。

节点配置示例

{
  "label": "6DRepNet Headpose",
  "operatorId": "operator-builtin-head-pose",
  "type": "builtin",
  "category": "AI",
  "hyperparams": {
    "HEADPOSE_API_BASE_URL": "<按节点填写>",
    "HEADPOSE_MODEL": "6DRepNet",
    "FRAME_STRIDE": "3",
    "MAX_FRAMES": "120",
    "REQUEST_TIMEOUT_SECONDS": "300",
    "HEADPOSE_SERVICE_IMAGE_ID": "<按节点填写>",
    "HEADPOSE_MODEL_SHA256": "<按节点填写>",
    "HEADPOSE_LICENSE_ID": "<按节点填写>"
  }
}

输入输出示例

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

相关文档