配置文件创建任务

本文说明 --config 路径及 TrainingJob 字段。参数化创建见参数化创建；总览见创建任务。

名称

sco ssp jobs create - 配置文件创建任务。

说明

sco ssp jobs create --config <path> [-w <workspace_name>]

描述

通过 YAML 或 JSON 配置文件创建任务。任务名在配置文件顶层 name 中设置（须以 job- 开头）。

--config 与参数化 flag（如 --image、--workload-file、--dry-run）互斥；-w / --workspace-name 可与 --config 同时使用。

文件内容为 API TrainingJob 对象，字段名使用 snake_case。
工作空间由 -w / --workspace-name 或 profile ssp.workspace_name 提供；subscription / resource_group 由 profile 提供（亦可单次用 sco --subscription、sco --resource-group 覆盖），详见 sco ssp 使用前配置。
spec.queue.id 等业务字段须在配置中填写完整资源 ID。

若基于已有任务创建，可使用 copy；需在创建前修改配置时，可先 describe 导出再 create。字段与枚举说明见下文。

命令行标志

必要参数

--config：YAML 或 JSON 配置文件路径。

可选参数

-w / --workspace-name：工作空间名称；未传时使用 profile ssp.workspace_name。

示例

从配置文件创建（已配置 ssp.workspace_name 时可省略 -w）：

sco ssp jobs create --config job.yaml

sco ssp jobs create --config job.yaml -w my-workspace

基于已有任务复制，见 copy：

sco ssp jobs copy job-my-source --name job-my-new-job

导出配置并修改后创建：

sco ssp jobs describe job-my-source -f json > source-job.json
jq '{
  name: "job-my-new-job",
  display_name: (.display_name // "job-my-new-job"),
  spec: .spec,
  metadata: .metadata,
  enable_queuing: .enable_queuing
}' source-job.json > job.json
# 按需自行修改 job.json（如 name、spec、metadata 等）
sco ssp jobs create --config job.json

配置示例

占位符 {subscription}、{resource_group}、{region}、{cluster}、{queue_name} 等须替换为环境中的真实值。顶层 name 须以 job- 开头。下方为两份可独立保存的完整配置；节点调度、AOSS 挂载等见对应字段小节中的片段示例。

`spec.ray_job` 示例

# sco ssp jobs create --config ray-job.yaml
name: job-ray-demo
display_name: ray-demo-job
spec:
  queue:
    id: /subscriptions/{subscription}/resourceGroups/{resource_group}/regions/{region}/clusters/{cluster}/queues/{queue_name}
  priority: NORMAL
  framework: RAY_JOB
  ray_job:
    entrypoint: python /home/ray/samples/sample_code.py
    runtime_env_yaml: |
      pip:
        - requests==2.32.3
      env_vars:
        LOG_LEVEL: INFO
    ray_cluster_spec:
      ray_version: "2.9.0"
      head_group_spec:
        template:
          containers:
            - name: ray-head
              image: registry.example.com/ccr-xxx/ray:2.9.0
              image_type: PRIVATE
              resource_spec:
                cpu_count: 4
                memory_gib: 16
      worker_group_specs:
        - group_name: small-group
          replicas: 2
          min_replicas: 1
          max_replicas: 4
          template:
            containers:
              - name: ray-worker
                image: registry.example.com/ccr-xxx/ray:2.9.0
                image_type: PRIVATE
                resource_spec:
                  cpu_count: 4
                  memory_gib: 16

`spec.vc_job` 示例（PyTorch DDP）

# sco ssp jobs create --config vc-job.yaml
name: job-pytorch-demo
display_name: pytorch-ddp-demo
metadata:
  key: value
spec:
  queue:
    id: /subscriptions/{subscription}/resourceGroups/{resource_group}/regions/{region}/clusters/{cluster}/queues/{queue_name}
  priority: NORMAL
  framework: PYTORCH_DDP
  envs:
    NCCL_DEBUG: INFO
  volume_mounts:
    - type: PV_AFS
      id: "{volume_id}"
      mount_path: /data
  tensorboard:
    log_path: /data/tb-logs
  active_deadline_seconds: 86400
  ttl_seconds_after_finished: 3600
  vc_job:
    fault_tolerance:
      max_attempts: 1
    tasks:
      - name: master
        replicas: 1
        image: registry.example.com/ccr-xxx/pytorch:2.1.0
        image_type: PRIVATE
        image_pull_auth:
          username: "{registry_username}"
          password: "{registry_password}"
        command: ["bash", "-c"]
        args: ["python train.py"]
        role: PYTORCH_MASTER
        resource_spec:
          machine_types: ["{machine_type}"]
          cpu_count: 8
          memory_gib: 64
          accelerate_device_count: 1
          rdma_name: "{rdma_name}"
          shm_size_gib: 64
      - name: worker
        replicas: 1
        image: registry.example.com/ccr-xxx/pytorch:2.1.0
        image_type: PRIVATE
        image_pull_auth:
          username: "{registry_username}"
          password: "{registry_password}"
        command: ["bash", "-c"]
        args: ["python train.py"]
        role: PYTORCH_WORKER
        resource_spec:
          machine_types: ["{machine_type}"]
          cpu_count: 8
          memory_gib: 64
          accelerate_device_count: 1
          rdma_name: "{rdma_name}"
          shm_size_gib: 64

字段说明

以下均为 create 可输入字段（与 OpenAPI / training_job.proto 对齐）。

顶层 `TrainingJob`

字段	必填	说明
`name`	是	任务资源名，须以 `job-` 开头；全长不超过 32 字符，正则 `^[a-z][a-z0-9-]{0,30}[a-z0-9]$`（小写字母开头，字母或数字结尾）。`sco ssp jobs create` 在 CLI 层强制此前缀
`display_name`	否	展示名，1–256 字符；中英文字母、数字、下划线、连字符；以中文、字母或数字开头
`spec`	是	任务规格
`metadata`	否	业务元数据（YAML 键值对象，见配置示例）。键区分大小写；勿用 `sensetime*` 前缀及 `access-key`、`secret-key`
`enable_queuing`	否	是否在 quota 不足时启用排队等待

`spec`（必填）

字段	必填	说明
`queue.id`	是	完整队列资源 ID：`/subscriptions/.../resourceGroups/.../regions/.../clusters/.../queues/...`；获取方式见获取 queue.id
`priority`	是	调度优先级，见枚举：priority
`framework`	是	训练框架，见枚举：framework
`envs`	否	环境变量键值对象，作用于全部 task（见配置示例）
`volume_mounts`	否	卷挂载，最多 10 项；`type` 仅支持 `PV_AFS`、`PV_AOSS`；各 `mount_path` 须互不相同且不可层级包含；`PV_AFS` 填 `id`，`PV_AOSS` 填 `name`（见 AFS / AOSS）
`tensorboard`	否	填写即开启 Tensorboard，见 tensorboard 子字段；仅支持 `vc_job`（如 `PYTORCH_DDP`），`RAY_JOB` 暂不支持
`active_deadline_seconds`	否	任务运行时长上限（秒），超时由系统终止；未设置则不限制
`ttl_seconds_after_finished`	否	任务结束后的 GC TTL（秒）；`0` 表示立即可回收；未设置则永久保留
`vc_job` / `ray_job`	二选一	workload，必须且只能设置一个，须与 `framework` 匹配

获取 `queue.id`

列出集群下的队列，确认 Name（队列名称）：

sco ssp clusters list-queues <cluster_name>

查询队列详情，将输出中的 id 填入 spec.queue.id：

sco ssp queues get <cluster_name> <queue_name>

示例：

sco ssp clusters list-queues my-cluster
sco ssp queues get my-cluster my-queue --format json

文件存储挂载（`type: PV_AFS`）

字段	必填	说明
`type`	是	固定为 `PV_AFS`
`id`	是	文件存储卷 ID
`mount_path`	是	容器内绝对路径（如 `/data`）；不可为系统目录
`subdir`	否	卷内子目录；省略或 `/` 表示卷根目录；须为绝对路径且仅支持一级（如 `/subdir`）
`region`	否	跨 region 挂载时，目标卷所在区域
`zone`	否	可用区

示例

volume_mounts:
  - type: PV_AFS
    id: "{volume_id}"
    mount_path: /data
    # subdir: /          # 可选，省略表示卷根目录

对象存储挂载（`type: PV_AOSS`）

字段	必填	说明
`type`	是	固定为 `PV_AOSS`
`name`	是	存储桶名称
`endpoint`	是	桶 Endpoint
`mount_path`	是	容器内绝对路径；不可为系统目录
`subdir`	否	桶内前缀；省略或 `/` 表示桶根路径；须为绝对路径且仅支持一级
`metadata.access_key`	否	AK；非公共读写桶需填写
`metadata.secret_key`	否	SK；非公共读写桶需填写
`mount_options`	否	GeeseFS 挂载参数，如 `--no-preload-dir --uid=1000`
`region`	否	跨 region 挂载时，目标卷所在区域
`zone`	否	可用区

示例

volume_mounts:
  - type: PV_AOSS
    name: "{bucket_name}"
    endpoint: "{endpoint}"
    mount_path: /data
    metadata:
      access_key: "{ak}"      # 公共读写桶可省略
      secret_key: "{sk}"
    # subdir: /prefix         # 可选
    # mount_options: "--no-preload-dir --uid=1000"

tensorboard 子字段

子字段	必填	说明
`log_path`	是	Tensorboard 日志目录，须写在已挂载的共享存储路径下（如 `volume_mounts` 挂到 `/data`，可填 `/data/tb-logs`）；训练过程需将事件文件写入该目录
`port`	否	服务端口，默认 `6006`

framework 与 workload 对应关系

`spec.framework`	填写 workload
`PYTORCH_DDP`、`MPI`、`TENSORFLOW_PS`、`FRAMEWORK_CUSTOM`	`vc_job`
`RAY_JOB`	`ray_job`

`spec.vc_job`（Volcano 类任务）

字段	必填	说明
`tasks`	是	至少 1 项、最多 10 项，见 spec.vc_job.tasks[]
`fault_tolerance`	否	容错配置
`fault_tolerance.max_attempts`	否	最大尝试次数，默认 1；须 ≥ 0

spec.vc_job.tasks[]

字段	必填	说明
`name`	是	1–20 字符，正则 `^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`；亦作为容器名
`replicas`	是	副本数，须 > 0；`PYTORCH_MASTER`、`MPI_LAUNCHER` 须为 1
`image`	是	镜像完整地址
`image_type`	否	见枚举：image_type；不填时服务端根据 `image` 推断，填写时须与推断结果一致
`command`	否	容器启动命令（不填则用镜像默认）
`args`	否	命令参数（不填则用镜像默认）
`role`	是	须与 `framework` 匹配，见枚举：role
`image_pull_auth`	否	自定义镜像拉取凭证（仅输入，服务端不回显），见 image_pull_auth
`resource_spec`	是	见 resource_spec
`scheduling`	否	指定或排除物理节点，见节点调度策略

`image_pull_auth`（vc_job tasks / ray 容器共用）

填写时 username、password 均必填。

子字段	必填	说明
`username`	是	镜像仓库用户名
`password`	是	镜像仓库密码

`resource_spec`（vc_job tasks / ray 容器共用）

字段	必填	说明
`cpu_count`	是	CPU 核数
`memory_gib`	是	内存（GiB）
`machine_types`	否	允许调度的机型编码列表（如 `n12lp.nn.i50`）。填写对应节点的规格编码；可从节点详情查看；留空表示不限制机型；填写后 Pod 只会调度到列表中的机型节点
`accelerate_device_count`	否	加速设备数量（如 GPU、昇腾 NPU 等），须 ≥ 0；`0` 表示纯 CPU 任务；具体设备类型由 `machine_types`/机型决定
`rdma_name`	否	RDMA 网络名
`shm_size_gib`	否	共享内存（GiB），须 ≥ 0；省略或 0 时默认 64

节点调度策略（`spec.vc_job.tasks[].scheduling`）

可选。用于指定物理节点或排除物理节点（限制机型请使用 resource_spec.machine_types，由服务端自动处理，无需在此配置）。

配置写在 scheduling.affinity.node_affinity.required_during_scheduling_ignored_during_execution.node_selector_terms[].match_expressions[]：

字段	必填	说明
`match_expressions[].key`	是	固定为 `kubernetes.io/hostname`
`match_expressions[].operator`	是	`IN`：仅调度到 `values` 所列节点；`NOT_IN`：排除 `values` 所列节点
`match_expressions[].values`	是	集群节点 Hostname（与 `kubernetes.io/hostname` 一致）；格式 `host-{ip}`（将 IP 中 `.` 替换为 `-`），例如 `host-10-201-2-10`

指定物理节点示例

scheduling:
  affinity:
    node_affinity:
      required_during_scheduling_ignored_during_execution:
        node_selector_terms:
          - match_expressions:
              - key: kubernetes.io/hostname
                operator: IN
                values:
                  - host-10-201-2-10
                  - host-10-201-2-11

排除物理节点示例：将 operator 设为 NOT_IN，values 填写要排除的节点 Hostname。

`spec.ray_job`（Ray 任务）

对应 KubeRay RayJob 的 spec；与 vc_job 互斥。当 framework=RAY_JOB 时填写 ray_job，不要再填 vc_job。

字段	必填	说明
`entrypoint`	是	Ray 作业入口命令
`ray_cluster_spec`	是	Ray 集群定义，见 ray_cluster_spec
`runtime_env_yaml`	否	Ray runtime 环境（YAML 字符串）

ray_cluster_spec

字段	必填	说明
`ray_version`	否	Ray 版本
`head_group_spec`	是	Head 节点组，见 ray_cluster_spec 容器
`worker_group_specs`	否	Worker 节点组列表，见 ray_cluster_spec.worker_group_specs[]

ray_cluster_spec.worker_group_specs[]

字段	必填	说明
`group_name`	是	节点组名称，1–20 字符
`replicas`	是	副本数
`min_replicas`	否	最小副本数
`max_replicas`	否	最大副本数
`template.containers`	是	容器列表，见 ray_cluster_spec 容器

ray_cluster_spec 容器

字段	必填	说明
`name`	是	Head 须为 `ray-head`；Worker 须为 `ray-worker`
`image`	是	镜像完整地址
`image_type`	否	见枚举：image_type；不填时服务端根据 `image` 推断，填写时须与推断结果一致
`image_pull_auth`	否	自定义镜像拉取凭证（仅输入，服务端不回显），见 image_pull_auth
`resource_spec`	是	见 resource_spec

枚举值

以下枚举供查阅；字段说明中的链接可跳转至对应小节。

枚举：`spec.priority`

值	说明
`NORMAL`	普通优先级（常用）
`HIGH`	高优先级
`HIGHEST`	最高优先级

枚举：`spec.framework`

值	说明
`PYTORCH_DDP`	PyTorch DDP（配 `vc_job`）
`MPI`	MPI（配 `vc_job`）
`TENSORFLOW_PS`	TensorFlow PS（配 `vc_job`）
`RAY_JOB`	Ray 作业（配 `ray_job`）
`FRAMEWORK_CUSTOM`	自定义框架，平台不做额外自动配置（配 `vc_job`）

枚举：`image_type`

适用于 spec.vc_job.tasks[].image_type 及 spec.ray_job 下容器的 image_type。

值	说明
`OFFICIAL`	CCR 官方 namespace 镜像
`PRIVATE`	CCR 私有镜像（非官方 namespace）
`THIRD_PARTY`	第三方镜像（不在 CCR）

枚举：`role`

适用于 spec.vc_job.tasks[].role，须与 framework 匹配。

值	说明
`CUSTOM`	自定义角色
`PYTORCH_MASTER`	PyTorch Master（`replicas` 须为 1）
`PYTORCH_WORKER`	PyTorch Worker
`MPI_LAUNCHER`	MPI Launcher（`replicas` 须为 1）
`MPI_WORKER`	MPI Worker
`TENSORFLOW_WORKER`	TensorFlow Worker
`TENSORFLOW_PARAMETER_SERVER`	TensorFlow Parameter Server

配置文件创建任务

名称​

说明​

描述​

命令行标志​

必要参数​

可选参数​

示例​

配置示例​

spec.ray_job 示例​

spec.vc_job 示例（PyTorch DDP）​

字段说明​

顶层 TrainingJob​

spec（必填）​

获取 queue.id​

文件存储挂载（type: PV_AFS）​

对象存储挂载（type: PV_AOSS）​

tensorboard 子字段​

framework 与 workload 对应关系​

spec.vc_job（Volcano 类任务）​

spec.vc_job.tasks[]​

image_pull_auth（vc_job tasks / ray 容器共用）​

resource_spec（vc_job tasks / ray 容器共用）​

节点调度策略（spec.vc_job.tasks[].scheduling）​

spec.ray_job（Ray 任务）​

ray_cluster_spec​

ray_cluster_spec.worker_group_specs[]​

ray_cluster_spec 容器​

枚举值​

枚举：spec.priority​

枚举：spec.framework​

枚举：image_type​

枚举：role​

名称

说明

描述