Skip to content

算子开发(内测) ​

本页面向研发工程师,说明如何编写可以上传到 NexCore 算子库并在管线处理中运行的算子。

权限

只有研发工程师可以上传算子与配置参数。算子库按项目隔离,不跨项目共享。

算子包结构 ​

算子以 .zip 包上传:

text
slam_orbslam3_v1.2.0.zip
├── operator.yaml        # 算子描述文件(必需)
├── main.py              # 入口脚本(必需,路径在 operator.yaml 中声明)
├── requirements.txt     # Python 依赖(可选)
├── assets/              # 模型权重、词表等静态资源(可选)
└── README.md            # 说明文档(推荐)

算子包不超过 2 GB。超过时,请把大文件放在对象存储中,在运行时按需下载。

描述文件 operator.yaml ​

yaml
name: slam_orbslam3              # 算子名,项目内唯一;仅小写字母、数字、下划线
version: 1.2.0                   # 语义化版本
type: slam                       # slam | vision | depth | tactile
description: 双目视觉 SLAM,输出相机轨迹
entry: main.py
runtime:
  python: "3.10"
  gpu: true                      # 是否需要 GPU
  timeout_minutes: 60            # 单条数据超时时间
inputs:
  - name: left_video
    type: video
  - name: right_video
    type: video
  - name: calib
    type: yaml
outputs:
  - name: trajectory
    type: table                  # 产出写入 output 目录
    file: trajectory.csv
params:
  - name: feature_count
    type: int
    default: 1500
    min: 500
    max: 5000
  - name: use_imu
    type: bool
    default: false
depends_on: []                   # 前置算子名列表,用于构建管线链路
字段说明
type决定算子出现在哪个导出算子类型下
params声明的参数会出现在弹窗的参数表单中,非研发角色只读
depends_on声明前置依赖,平台据此排出「前置依赖 → 算子执行 → 后置处理」链路

运行约定 ​

平台为每条数据启动一次算子进程,通过环境变量传入路径与参数:

环境变量说明
NEXCORE_INPUT_DIR输入目录,只读挂载
NEXCORE_OUTPUT_DIR输出目录,算子把产物写到这里
NEXCORE_PARAMSJSON 字符串,参数值
NEXCORE_DATA_ID当前数据 ID
NEXCORE_RUN_ID当前管线任务 ID

入口脚本示例:

python
import json
import os
from pathlib import Path


def main() -> int:
    input_dir = Path(os.environ["NEXCORE_INPUT_DIR"])
    output_dir = Path(os.environ["NEXCORE_OUTPUT_DIR"])
    params = json.loads(os.environ.get("NEXCORE_PARAMS", "{}"))

    left = input_dir / "video" / "left.mp4"
    right = input_dir / "video" / "right.mp4"
    if not left.exists() or not right.exists():
        print("missing stereo video", flush=True)
        return 2

    # ... 运行算法,生成轨迹 ...
    (output_dir / "trajectory.csv").write_text("timestamp,x,y,z,qx,qy,qz,qw\n")
    print(f"done, feature_count={params.get('feature_count')}", flush=True)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

退出码 ​

退出码含义平台行为
0成功收集产物,进入下一步
1一般错误标记该步骤失败,可重试
2输入不满足要求标记失败,不建议直接重试,需检查输入数据
超时超过 timeout_minutes终止进程,标记失败

标准输出与标准错误会被收集到管线日志中。

必须遵守的规则 ​

  • 不得修改输入目录:输入为只读挂载,源数据不可被改写。
  • 不得静默删除数据:算子只能产出结果、候选标签或处理步骤,不能删除或覆盖源数据。
  • 产物写入输出目录:写到其他位置的文件不会被收集。
  • 幂等:同一输入重复运行应得到相同产物,便于重试。

本地自测 ​

上传前建议在本地模拟运行:

bash
export NEXCORE_INPUT_DIR=./samples/session_001
export NEXCORE_OUTPUT_DIR=./out
export NEXCORE_PARAMS='{"feature_count": 1500, "use_imu": false}'
export NEXCORE_DATA_ID=local-test
export NEXCORE_RUN_ID=local-run
mkdir -p "$NEXCORE_OUTPUT_DIR"
python main.py; echo "exit code: $?"

上传与版本 ​

  • 上传后平台校验 operator.yaml 与入口文件,校验通过才进入算子库。
  • 同名算子上传时提示「覆盖」或「改名」。覆盖不影响已完成的历史运行记录。
  • 建议每次修改都提升 version,便于在运行日志中区分。

产品快速迭代中,表现效果以最新版本为准NexCore Docs · 鹿明机器人具身智能技能学习平台使用手册