算子开发(内测)
本页面向研发工程师,说明如何编写可以上传到 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_PARAMS | JSON 字符串,参数值 |
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,便于在运行日志中区分。

