参数化创建任务

通过命令行 flag（如 --image、--args、资源参数）创建任务，无需手写完整 TrainingJob 配置。实例规格相同时用 --pod-count 与 --framework 自动生成实例；各实例不同时，用 --workload-file 按实例填写需覆盖的字段，未写字段继承 CLI flag。本方式与 --config 互斥。

创建方式总览见创建任务。使用配置文件创建时，见配置文件创建。

名称

sco ssp jobs create - 参数化创建任务。

说明

sco ssp jobs create <job_name> [flags]

描述

位置参数为任务名（须以 job- 开头）。
工作空间与队列可由 -w / --queue-id 提供，也可在 profile 中配置默认值（见下）。
实例规格：默认用 --pod-count + --framework 自动推导；各实例不同时用 --workload-file 按实例填写需覆盖的字段，未写字段继承 CLI flag。
提交前可用 --dry-run 预览合并后的完整配置；可用 --dry-run --workload-file-out 导出合并后的 instances[]，可作为后续 --workload-file 的起点再编辑。

前置：Profile 默认（建议配置一次）

Profile 属性	配置命令	说明
`ssp.workspace_name`	`sco config set ssp.workspace_name <name>`	默认工作空间
`ssp.queue_id`	`sco config set ssp.queue_id <id>`	默认队列完整资源 ID（写入 `spec.queue.id`）

解析优先级（各字段独立）：命令行 flag > profile ssp.* > 报错。

获取 ssp.queue_id（取 JSON 输出中的 id 字段）：

sco ssp workspaces list-queues <workspace_name> -f json
# 或
sco ssp queues get <cluster_name> <queue_name> -f json

sco config set ssp.workspace_name team-a
sco config set ssp.queue_id /subscriptions/.../resourceGroups/.../regions/.../clusters/prod-cluster/queues/gpu-pool

配置后日常 create 可省略 -w 与 --queue-id。

命令行标志

位置参数

参数	说明
`job_name`	训练任务名，须 `job-` 开头；小写字母、数字、连字符；以字母开头、以字母或数字结尾；全长不超过 32 字符

基本信息

Flag	必填	默认值	说明
`-w` / `--workspace-name`	条件	profile `ssp.workspace_name`	工作空间名称；flag 与 profile 皆空则报错
`--display-name`	否	—	展示名；中文/字母/数字/`_`/`-`，以中文/字母/数字开头；1–256 字符

队列与优先级

Flag	必填	默认值	说明
`--queue-id`	条件	profile `ssp.queue_id`	队列完整资源 ID；flag 与 profile 皆空则报错
`--priority`	否	`NORMAL`	`NORMAL` / `HIGH` / `HIGHEST`
`--logic-node-count`	条件	—	仅 910C 机型：必填；非 910C 不得指定。逻辑超节点个数。取值 `1`～总副本数（各实例 `replicas` 之和）；分布式时总副本数须能被该值整除；仅 1 个副本时须为 `1`

训练框架

Flag	必填	默认值	说明
`--framework`	否	`PYTORCH_DDP`	`PYTORCH_DDP` / `MPI` / `RAY_JOB` / `TENSORFLOW_PS` / `FRAMEWORK_CUSTOM`

实例配置来源（二选一）

方式	触发	结构	资源规格	详见
自动	无 `--workload-file`	`--pod-count` + `--framework` 推导	CLI 资源 flag，各实例相同	自动实例配置
显式	有 `--workload-file`	文件中的 `instances[]`	文件已写用文件值，未写继承 CLI flag	显式实例配置

--pod-count 与 --workload-file 互斥。

资源默认与实例配置

Flag	必填	默认值	说明
`--pod-count`	否	`1`	pod 总数；与 `--workload-file` 互斥
`--cpu-count`	条件	—	默认 CPU 核数。`gpu_count = 0` 时必填；`gpu_count > 0` 时可选（未填则按机型自动填充）。详见资源规格规则
`--memory-gib`	条件	—	默认内存（GiB）。必填条件同 `--cpu-count`。详见资源规格规则
`--gpu-count`	否	`0`	默认 GPU 卡数
`--machine-type`	条件	—	队列 workload 机型编码（`spec_code`）；可逗号分隔多个（弱异构）。`gpu_count > 0` 时必填；`gpu_count = 0` 时可选，不填则不限制机型（也可填 GPU 机型）。仅 `gpu_count > 0` 且未填 CPU/内存时从 workload spec 自动填充。详见资源规格规则
`--rdma-name`	否	—	默认 RDMA；不填不限制
`--workload-file`	否	—	显式 `instances[]` YAML 文件路径
`--workload-file-out`	否	—	仅与 `--dry-run` 合用；将 merge 后 `instances[]` 写入 YAML 文件；`-` 表示打印到标准输出。使用本 flag 时不能再显式传 `-f`（此时不再输出完整 `TrainingJob`）

资源规格规则

合并后按实例校验：

合并后 `gpu_count`	`--machine-type`	`--cpu-count` / `--memory-gib`
`0`	可选（可填 CPU 或 GPU 机型）	必填（不自动填充）
`> 0`	必填	可选；未填时按所选机型自动填充（多机型取各机型可用最小值）

指定 --machine-type 时，所填 CPU 与内存须被该机型的同一档规格同时满足（均不超过该档上限）。若逗号指定多个机型，则每个机型都须各自满足上述要求。

共享内存

Flag	必填	默认值	说明
`--shm-size-gib`	否	min(memory)×25%，且 ≤128	各 pod 的 `/dev/shm`（GiB）；指定时 ≥ 0 且严格小于各参与 pod 的最小 `memory_gib`。仅可通过本 CLI flag 设置

环境

Flag	必填	默认值	说明
`--image`	条件	—	默认容器镜像；合并后每个实例均须有镜像
`--image-type`	否	—	`OFFICIAL` / `PRIVATE` / `THIRD_PARTY`；仅配合 CLI `--image`；实例在 workload-file 写了 `image` 时忽略
`--args`	是	—	启动命令（同控制台「启动命令」）；VcJob 与 `RAY_JOB` 均使用
`--command`	否	VcJob：`bash -c`；`RAY_JOB`：不适用	仅 VcJob：取值 `bash -c` 或 `sh -c`。`RAY_JOB` 下不得指定（入口命令用 `--args`）
`--env`	否	—	`KEY=VALUE`；可多次，或单次逗号分隔（如 `--env K1=V1,K2=V2`）

存储挂载

Flag	必填	说明
`--volume-mount`	否	见下方格式；可多次，或单次逗号分隔
`--aoss-access-key`	否	有 `PV_AOSS` 且需凭证时填写；各条 `PV_AOSS` 共用
`--aoss-secret-key`	否	与 `--aoss-access-key` 成对

<type>：PV_AFS（文件存储）/ PV_AOSS（对象存储）。

类型	格式
`PV_AFS`	`PV_AFS:<卷UUID>:<挂载路径>[:<卷内子目录>]`
`PV_AOSS`	`PV_AOSS:<桶名>:<挂载路径>:<endpoint>[:<桶内前缀>]`

要点：

<挂载路径>：容器内绝对路径（以 / 开头）；不可为系统目录（如 /proc、/etc）。
PV_AFS 的 <subdir>：省略或 / 表示卷根；若填须以 / 开头且仅单层（如 /train）。
PV_AOSS 的 <endpoint> 为 http(s)://...；<subdir> 规则同 PV_AFS。

PV_AFS:00000000-0000-7000-8000-000000000001:/data
PV_AFS:00000000-0000-7000-8000-000000000001:/data:/train
PV_AOSS:my-bucket:/data:https://aoss.example.com:/datasets

容错与生命周期

Flag	必填	说明
`--max-attempts`	否	仅 VcJob；任务失败后最大重试次数；传入即启用容错
`--active-deadline`	否	仅 `RAY_JOB`；最大运行时长（分钟）；`0` 表示不限制
`--ttl-after-finished`	否	仅 `RAY_JOB`；结束后保留时长（秒）；`0` 表示立即可回收

TensorBoard（仅 VcJob）

Flag	必填	默认值	说明
`--tensorboard-log-path`	否	—	设置后启用；须为已挂载文件存储（`PV_AFS`）某条 `mount_path` 下的路径
`--tensorboard-port`	否	`6006`	端口 6000–65000

节点亲和

Flag	必填	说明
`--specified-nodes`	否	默认指定节点 hostname，逗号分隔；实例未写时继承本 flag
`--excluded-nodes`	否	默认排除节点 hostname，逗号分隔；实例未写时继承本 flag

hostname 格式：host-x-x-x-x（将 IP 中 . 换为 -），如 host-10-201-2-10。
workload-file 可按实例覆盖；SPOT 队列下不可用。
910C 且填写指定节点时，hostname 个数须 ≥ 该实例 replicas。

其他

Flag	必填	默认值	说明
`--enable-queuing`	否	`false`	配额不足时排队
`--dry-run`	否	`false`	校验并预览，不创建任务；与 `-f` 的关系见 `--dry-run` 与导出模板

自动实例配置（无 `--workload-file`）

--pod-count = N 时，按框架生成实例：

Framework	生成的实例（`name` / `role` 或 `kind` / `replicas`）
`PYTORCH_DDP`（N=1）	`worker` / `PYTORCH_WORKER` / 1
`PYTORCH_DDP`（N>1）	`master`×1 + `worker`×(N−1)
`MPI`（N=1）	`worker` / `MPI_WORKER` / 1
`MPI`（N>1）	`launcher`×1 + `worker`×(N−1)
`TENSORFLOW_PS`（N=1）	仅 `TENSORFLOW_WORKER`×1
`TENSORFLOW_PS`（N≥2）	PS = floor(N/5)+1，Worker = N−PS
`RAY_JOB`（N=1）	`head` / `HEAD` / 1
`RAY_JOB`（N>1）	`head`×1 + `worker`×(N−1)
`FRAMEWORK_CUSTOM`（N=1）	`worker` / `CUSTOM` / 1
`FRAMEWORK_CUSTOM`（N>1）	`master`×1 + `worker`×(N−1)

head 与 worker 规格不同、多 worker group 等场景，请使用 --workload-file。

显式实例配置（`--workload-file`）

instances:
  - name: <string>                    # 必填；1–20 字符；同任务内不可重复
    replicas: <int>                   # 必填
    role: <enum>                      # VcJob 必填；须与 --framework 匹配，见下「role 取值」
    kind: HEAD | WORKER               # RAY_JOB 必填；VcJob 不写
    image: <string>                   # 可选；未写继承 CLI --image
    specified_nodes: <string>         # 可选；未写继承 CLI --specified-nodes
    excluded_nodes: <string>          # 可选；未写继承 CLI --excluded-nodes
    resource_spec:                    # 可选；未写字段继承对应 CLI flag
      cpu_count: <int>
      memory_gib: <int>
      gpu_count: <int>
      machine_type: <string>          # 可逗号分隔多个
      rdma_name: <string>

合并原则：实例已写用实例值，未写继承对应 CLI flag。

role 取值

VcJob（非 RAY_JOB）每项须填 role，且须与 --framework 匹配：

`--framework`	可用 `role`
`PYTORCH_DDP`	`PYTORCH_MASTER`、`PYTORCH_WORKER`（`PYTORCH_MASTER` 的 `replicas` 须为 1）
`MPI`	`MPI_LAUNCHER`、`MPI_WORKER`（`MPI_LAUNCHER` 的 `replicas` 须为 1）
`TENSORFLOW_PS`	`TENSORFLOW_PARAMETER_SERVER`、`TENSORFLOW_WORKER`
`FRAMEWORK_CUSTOM`	可为上表任一已定义 `role`（含 `CUSTOM`）

RAY_JOB 不写 role，改填 kind（HEAD / WORKER）。

各 role 含义亦可参见配置文件创建 · 枚举 role。

约束摘要：

VcJob：每项必填 role（不写 kind），1–10 项。
RAY_JOB：每项必填 kind（不写 role）；恰 1 项 kind: HEAD 且 replicas = 1。

workload-file 示例

仅写实例结构，资源走 CLI：

instances:
  - name: master
    role: PYTORCH_MASTER
    replicas: 1
  - name: worker
    role: PYTORCH_WORKER
    replicas: 4

配合例如：--cpu-count 4 --memory-gib 64 --gpu-count 0。

只覆盖 worker GPU：

instances:
  - name: master
    role: PYTORCH_MASTER
    replicas: 1
  - name: worker
    role: PYTORCH_WORKER
    replicas: 4
    resource_spec:
      gpu_count: 8

Ray：

instances:
  - name: coordinator
    kind: HEAD
    replicas: 1
  - name: gpu-workers
    kind: WORKER
    replicas: 4
    resource_spec:
      gpu_count: 1
      machine_type: h1ls.rp.k60a

`--dry-run` 与导出模板

项	行为
Create API	不调用；校验与组装与正式提交相同
未显式传 `-f`	预览完整 `TrainingJob`，强制输出 JSON
显式 `-f json` / `-f yaml`	按该格式预览完整 `TrainingJob`
显式 `-f table`	不支持
`--workload-file-out <path>`	仅输出 merge 后的 `instances[]` YAML；`-` 表示打印到标准输出；与任意显式 `-f` 互斥

示例流程：

# 1) 导出合并后的 instances 模板
sco ssp jobs create job-new \
  --image registry.example.com/train:v1 --args "python train.py" \
  --pod-count 4 --gpu-count 8 --machine-type h1ls.rp.k60a \
  --dry-run --workload-file-out tasks.yaml

# 2) 编辑 tasks.yaml（如 worker 多卡、按实例节点亲和）

# 3) 再 dry-run 确认，然后去掉 --dry-run 正式提交
sco ssp jobs create job-new \
  --image registry.example.com/train:v1 --args "python train.py" \
  --machine-type h1ls.rp.k60a \
  --workload-file tasks.yaml --dry-run

用法示例

统一规格 — PyTorch DDP（使用 profile 默认）

sco ssp jobs create job-my-train \
  --image registry.cn-sh-04.sensecore.dev/my-ns/train:v1 \
  --args "torchrun --nproc_per_node \$SENSECORE_ACCELERATE_DEVICE_COUNT main.py" \
  --pod-count 2 \
  --gpu-count 8 \
  --machine-type h1ls.rp.k60a

显式指定工作空间与队列

sco ssp jobs create job-my-train \
  -w other-workspace \
  --queue-id /subscriptions/.../queues/gpu-exclusive-01 \
  --image registry.cn-sh-04.sensecore.dev/my-ns/train:v1 \
  --args "python train.py" \
  --pod-count 2 \
  --gpu-count 8 \
  --machine-type h1ls.rp.k60a

纯 CPU + 存储挂载

sco ssp jobs create job-pt-example \
  --image registry.cn-sh-04.sensecore.dev/my-ns/ngc-pytorch:25.06 \
  --volume-mount PV_AFS:00000000-0000-7000-8000-000000000001:/data \
  --args "python train.py --config /data/config.yaml" \
  --cpu-count 4 --memory-gib 10 --gpu-count 0

GPU 机型但不用卡（`--gpu-count 0`）

可指定 GPU 机型并将卡数设为 0（须显式填 CPU/内存，且能被某单一档规格成对容纳）：

sco ssp jobs create job-cpu-on-gpu-type \
  --image registry.example.com/train:v1 \
  --args "python train.py" \
  --machine-type h1ls.rp.k60a \
  --gpu-count 0 --cpu-count 4 --memory-gib 64

Ray Job

sco ssp jobs create job-ray-train \
  --framework RAY_JOB \
  --image registry.cn-sh-04.sensecore.dev/my-ns/ray:2.9.0 \
  --args "python /home/ray/train.py" \
  --pod-count 5 \
  --gpu-count 1 \
  --machine-type h1ls.rp.k60a

按实例覆盖资源（CLI 默认 + workload-file）

sco ssp jobs create job-hetero-ddp \
  --framework PYTORCH_DDP \
  --image registry.example.com/train:v1 \
  --args "torchrun main.py" \
  --machine-type h1ls.rp.k60a \
  --gpu-count 0 --cpu-count 4 --memory-gib 64 \
  --workload-file tasks.yaml \
  --dry-run

tasks.yaml 见上文「只覆盖 worker GPU」示例。

成功输出

正式提交成功时标准输出：

training job {name} created successfully

--dry-run 不输出上述成功文案，而是按上文规则打印预览内容（或写入 --workload-file-out）。

常见约束（摘要）

规则	说明
互斥	`--config` 与参数化 flag（不含 `-w`）；`--pod-count` 与 `--workload-file`
`--image` / `--args`	合并后每个实例须有镜像；`--args` 必填
`--command`	仅 VcJob；`RAY_JOB` 下不得指定
910C	须填 `--logic-node-count`；单机 GPU 卡数须为偶数；分布式每副本 GPU 须为 16
节点亲和	SPOT 队列不可用；hostname 格式见上文

TrainingJob 配置字段与枚举说明见配置文件创建。

参数化创建任务

名称​

说明​

描述​

前置：Profile 默认（建议配置一次）​

命令行标志​

位置参数​

基本信息​

队列与优先级​

训练框架​

实例配置来源（二选一）​

资源默认与实例配置​

资源规格规则​

共享内存​

环境​

存储挂载​

容错与生命周期​

TensorBoard（仅 VcJob）​

节点亲和​

其他​

自动实例配置（无 --workload-file）​

显式实例配置（--workload-file）​

role 取值​

workload-file 示例​

--dry-run 与导出模板​

用法示例​

统一规格 — PyTorch DDP（使用 profile 默认）​

显式指定工作空间与队列​

纯 CPU + 存储挂载​

GPU 机型但不用卡（--gpu-count 0）​

Ray Job​

按实例覆盖资源（CLI 默认 + workload-file）​

成功输出​

常见约束（摘要）​

名称

说明

描述