使用 Python SDK 管理训练任务

Python SDK 可用于在训练流水线、批量实验或 CI/CD 流程中管理训练任务。使用本文示例前，请先完成安装并初始化，并确认当前账号具备目标资源池、镜像、Volume、数据集和模型的使用权限。

创建训练任务

训练任务支持两种创建方式：

通过 Python 参数创建，适合在脚本或流水线中动态组合任务配置。
通过 YAML 文件创建，适合复用已有任务配置文件。

两种方式共用下文的参数说明、任务类型配置和增强能力。以下示例及字段说明以 SDK 0.3.27 为准。

创建示例

以下两个页签使用相同的基础配置创建 PyTorchJob。请按实际环境替换镜像地址、实例规格和 <RESOURCE_POOL>，并确保启动命令引用的训练脚本已包含在镜像中，或通过 Volume 挂载到任务环境。

Python
YAML

先构建任务配置，再调用 client.tasks.create 提交。下文的 Python 补充配置示例沿用这里的 task_config，请在提交前加入所需配置。

from siflow import SiFlow
from siflow.types import TaskUserSelectedInstance

client = SiFlow(region="cn-beijing", cluster="auriga")

task_config = dict(
    name_prefix="demo-training",
    image_url="registry-cn-beijing.siflow.cn/siflow/ray:2.50.1-root",
    type="pytorchjob",
    priority=6,
    cmd="python train.py --epochs 3",
    workers=1,
    resource_pool="<RESOURCE_POOL>",
    instances=[
        TaskUserSelectedInstance(name="sci.c23-2", count_per_pod=1),
    ],
)

uuid = client.tasks.create(**task_config)
print(uuid)

将以下配置保存为 task.yml。下文的 YAML 补充示例均为局部配置，需要合并到该文件，不能单独提交。

task.yml

namePrefix: demo-training
imageUrl: registry-cn-beijing.siflow.cn/siflow/ray:2.50.1-root
type: pytorchjob
priority: 6
cmd: |
  python train.py --epochs 3
workers: 1
resourcePool: <RESOURCE_POOL>
instances:
  - name: sci.c23-2
    countPerPod: 1

完成客户端初始化后，通过 yaml_file 提交：

uuid = client.tasks.create(yaml_file="task.yml")
print(uuid)

yaml_file 是 Python 提交参数，不是任务 YAML 字段。

提交成功后，SDK 返回任务 UUID。请保存该 UUID，并通过查询训练任务查看任务状态。下文的补充配置仅用于创建新任务，不会修改已创建的任务。

参数说明

两种创建方式的主要参数说明如下。参数列使用 Python 命名；命名不同的 YAML 字段在说明中注明。

参数	说明
`name_prefix`	训练任务名称前缀。平台会基于该前缀生成任务名称。 YAML 字段：`namePrefix`。
`image_url`	完整镜像地址。使用该参数时，`image`、`image_version` 和 `image_type` 会被忽略。 YAML 字段：`imageUrl`。
`image` / `image_version` / `image_type`	不使用 `image_url` 时，用于按镜像名称、版本和类型定位唯一镜像。`image_type` 可选择 `preset` 或 `custom`。 YAML 字段：`image_version` → `imageVersion`、`image_type` → `imageType`。
`type`	任务类型，可选择 `pytorchjob` 或 `rayjob`。专有配置请参见按任务类型配置。
`priority`	任务优先级，支持整数 `1`～`9`；闲时任务优先级为 `0`。
`guarantee`	是否启用资源预留。该配置仅对预留资源池有效，其他资源池类型会被忽略。
`enable_idle_resource`	使用预留资源池时，是否允许降级使用闲时资源。 YAML 字段：`enableIdleResource`。
`force_single_pod`	是否禁止跨 Pod 网络组调度，仅在闲时资源出队时生效。SDK `0.3.27` 默认值为 `True`；设为 `False` 时允许跨组调度。 YAML 字段：`forceSinglePod`。
`cmd`	任务入口命令。
`workers`	Worker 数量。
`resource_pool`	任务使用的实例资源池名称。具体名称以控制台资源池为准。 YAML 字段：`resourcePool`。
`instances`	Worker 使用的实例规格和数量。Python 的 `count_per_pod` 对应 YAML 的 `countPerPod`，表示每个 Pod 使用的实例份数。
`head_instances`	RayJob 的 Head 实例配置。未配置时，Head 与 Worker 使用同一实例规格。 YAML 字段：`headInstances`。
`volumes`	挂载到任务 Pod 的 Volume。子字段对应关系为 `volume_id` → `volumeId`、`mount_dir` → `mountDir`、`sub_path` → `subPath`、`read_only` → `readOnly`。开启目录级权限的 Volume 通常需要配置 `sub_path`。 `sub_path` 是卷内相对路径，不能以 `/` 开头。如果目录只有读权限，请设置 `read_only=True`，YAML 中设置 `readOnly: true`。
`datasets` / `models`	挂载到任务 Pod 的数据集或模型。
`enhancements`	自动容错、指标采集、资源预检、VSCS 访问和抢占通知等配置。请参见配置增强能力。
`labels`	任务标签，用于后续筛选、统计或治理。通过 YAML 创建时，也需要在 `client.tasks.create` 调用中传入 `labels`，不能用 YAML 顶层的 `labels` 字段代替。
`task_env`	任务环境变量。子字段 `env_key`、`env_value` 分别对应 `envKey`、`envValue`。`hide=True` 时，非任务所有者查看任务详情时该值会隐藏；YAML 中使用 `hide: true`。 YAML 字段：`taskEnv`。
`scheduling_policy_id_list`	调度策略 ID 列表。传入前请确认策略在当前区域、集群和资源池下可用。 YAML 字段：`schedulingPolicyIdList`。

补充任务配置

以下补充配置适用于 Python 参数和 YAML 两种创建方式。

通用配置

以下示例补充 Volume 挂载、任务环境变量、资源调度和标签。请按需选用，并替换 Volume ID、调度策略 ID 和环境变量值。

Python
YAML

在创建示例的 client.tasks.create(**task_config) 调用前加入：

from siflow.types import TaskEnv, TaskVolume

task_config.update(
    guarantee=False,
    enable_idle_resource=False,
    force_single_pod=False,
    volumes=[
        TaskVolume(mount_dir="/volume/data", volume_id=1),
        TaskVolume(
            mount_dir="/volume/project",
            volume_id=11,
            sub_path="project-a/",
            read_only=False,
        ),
    ],
    task_env=[
        TaskEnv(env_key="TOKEN", env_value="<TOKEN>", hide=True),
        TaskEnv(env_key="LOG_LEVEL", env_value="INFO", hide=False),
    ],
    scheduling_policy_id_list=[12, 34],
    labels={"project": "demo", "stage": "dev"},
)

将以下字段合并到 task.yml 的顶层；如果字段已存在，请修改原字段，不要重复声明。

guarantee: false
enableIdleResource: false
forceSinglePod: false
volumes:
  - volumeId: 1
    mountDir: /volume/data
  - volumeId: 11
    mountDir: /volume/project
    subPath: project-a/
    readOnly: false
taskEnv:
  - envKey: TOKEN
    envValue: <TOKEN>
    hide: true
  - envKey: LOG_LEVEL
    envValue: INFO
    hide: false
schedulingPolicyIdList: [12, 34]

任务标签通过 Python 提交参数传入：

uuid = client.tasks.create(
    yaml_file="task.yml",
    labels={"project": "demo", "stage": "dev"},
)
print(uuid)

按任务类型配置

PyTorchJob 通常只需要配置 workers、instances、启动命令和挂载资源。资源预检、任务 VSCS 访问和抢占通知仅对 pytorchjob 生效，配置方式请参见配置增强能力。 RayJob 支持为 Head 节点单独指定实例规格。未配置 head_instances（YAML 中的 headInstances）时，Head 与 Worker 使用同一实例规格。以下示例将基础创建配置改为 RayJob。Python 片段需在提交前执行；YAML 片段需合并到 task.yml，替换同名字段，保留镜像和资源池等其他基础配置。

Python
YAML

from siflow.types import TaskUserSelectedInstance

task_config.update(
    name_prefix="demo-ray",
    type="rayjob",
    cmd="python ray_train.py",
    workers=2,
    head_instances=[
        TaskUserSelectedInstance(name="sci.c23-2", count_per_pod=1),
    ],
    instances=[
        TaskUserSelectedInstance(name="sci.c23-2", count_per_pod=1),
    ],
)

namePrefix: demo-ray
type: rayjob
cmd: python ray_train.py
workers: 2
headInstances:
  - name: sci.c23-2
    countPerPod: 1
instances:
  - name: sci.c23-2
    countPerPod: 1

配置增强能力

增强能力按需启用，不必为每个任务都配置。以下说明共用于两种创建方式。使用 Python 参数创建时，在提交任务前初始化增强能力配置，再加入所需的能力片段：

from siflow.types import TaskEnhancements

enhancements = TaskEnhancements()
task_config["enhancements"] = enhancements

以下 Python 片段沿用该 enhancements 对象。YAML 片段需要合并到 task.yml 的 enhancements 对象中；启用多项能力时，只保留一个顶层 enhancements 字段，并在其下合并各能力配置。

自动容错

Python 的 fault_tolerance 对应 YAML 的 faultTolerance。

max_retry_count（maxRetryCount）设置任务异常后的最大重试次数。
auto_replace_enabled（autoReplaceEnabled）控制是否启用故障自动换机。
fault_strategy_enabled（faultStrategyEnabled）控制是否启用容错策略。省略时由服务端默认策略决定。
replace_pod_notify_max_wait（replacePodNotifyMaxWait）设置通知训练进程后等待确认的最长时间。
- 单位为秒，取值范围为 0～600；0 表示不等待，省略时使用服务端默认值。
- 仅在服务端最终配置中的 enabled 和 fault_strategy_enabled 均为 True 时生效。
- 等待发生在发送 SIGTERM 之前，不占用 Pod 的 terminationGracePeriodSeconds。

Python
YAML

from siflow.types import TaskEnhancementsFaultTolerance

enhancements["fault_tolerance"] = TaskEnhancementsFaultTolerance(
    enabled=True,
    max_retry_count=1,
    auto_replace_enabled=True,
    replace_pod_notify_max_wait=120,
)

enhancements:
  faultTolerance:
    enabled: true
    maxRetryCount: 1
    autoReplaceEnabled: true
    replacePodNotifyMaxWait: 120

自定义指标采集

Python 的 metrics_monitor 对应 YAML 的 metricsMonitor。单端点采集使用 port 和 path；多端点采集使用 endpoints，最多配置 16 项，且优先于 port 和 path。

每个 TaskMetricsEndpoint 需要指定 port，取值范围为 1～65535。单端点模式的 port 不能使用保留端口 8080。
path 为指标路径，需以 / 开头，默认值为 /metrics。
remark 为端点备注，仅用于展示，最多 128 字符。

以下示例配置两个采集端点：

Python
YAML

from siflow.types import TaskMetricsEndpoint, TaskMetricsMonitor

enhancements["metrics_monitor"] = TaskMetricsMonitor(
    enabled=True,
    endpoints=[
        TaskMetricsEndpoint(port=9090, path="/metrics", remark="训练进程指标"),
        TaskMetricsEndpoint(port=9091, path="/sidecar/metrics", remark="sidecar 指标"),
    ],
)

enhancements:
  metricsMonitor:
    enabled: true
    endpoints:
      - port: 9090
        path: /metrics
        remark: 训练进程指标
      - port: 9091
        path: /sidecar/metrics
        remark: sidecar 指标

如果只采集一个端点，可将 endpoints 替换为 port=9090, path="/metrics"；YAML 中使用 port: 9090 和 path: /metrics。任务运行后，可通过使用 Python SDK 查询指标发现已采集的自定义指标。

资源预检

precheck 仅支持 pytorchjob。开启后，预检失败会使任务失败；可通过 envs 向预检脚本传入环境变量。

Python 的 env_key、env_value 对应 YAML 的 envKey、envValue。
env_key 仅允许 ASCII 字母、数字和下划线，不能以数字或 KUBERNETES_ 开头。
env_value 不能为空，不能包含换行符或 NUL 字符，最大 8 KiB。
precheck.envs 仅传给预检脚本，不会写入训练容器环境变量，请勿填写敏感信息。

Python
YAML

from siflow.types import TaskEnhancementsPrecheck, TaskPrecheckEnv

enhancements["precheck"] = TaskEnhancementsPrecheck(
    enabled=True,
    envs=[
        TaskPrecheckEnv(env_key="NETWORK_CHECK_TIMEOUT", env_value="300"),
        TaskPrecheckEnv(env_key="NCCL_DEBUG", env_value="INFO"),
    ],
)

enhancements:
  precheck:
    enabled: true
    envs:
      - envKey: NETWORK_CHECK_TIMEOUT
        envValue: "300"
      - envKey: NCCL_DEBUG
        envValue: INFO

任务 VSCS 访问

vscs 仅支持 pytorchjob。开启后，可从网页打开 VSCS 访问任务环境。 Python 的 extension_dir、user_data_dir 对应 YAML 的 extensionDir、userDataDir。建议使用持久化路径，避免扩展和用户配置随任务环境丢失。以下路径需先通过 Volume 挂载。

Python
YAML

from siflow.types import TaskEnhancementsVscs

enhancements["vscs"] = TaskEnhancementsVscs(
    enabled=True,
    extension_dir="/volume/project/code-server/extensions",
    user_data_dir="/volume/project/code-server/user-data",
)

enhancements:
  vscs:
    enabled: true
    extensionDir: /volume/project/code-server/extensions
    userDataDir: /volume/project/code-server/user-data

抢占通知

Python 的 preempt_notify 对应 YAML 的 preemptNotify，仅支持 pytorchjob。

port 为训练进程监听通知的端口，取值范围为 9000～9999。
max_wait（maxWait）为最长存盘等待秒数。

以下示例保留通知配置但不启用。确认训练进程已监听指定端口后，再将 enabled 设置为 True（YAML 中为 true）。

Python
YAML

from siflow.types import TaskEnhancementsPreemptNotify

enhancements["preempt_notify"] = TaskEnhancementsPreemptNotify(
    enabled=False,
    port=9000,
    max_wait=600,
)

enhancements:
  preemptNotify:
    enabled: false
    port: 9000
    maxWait: 600

查询训练任务

根据任务 UUID 查询详情：

task = client.tasks.get(uuid="<TASK_UUID>")
print(task.name, task.status, task.create_time)

查询任务列表，默认将容错重试等子任务展开到同一列表：

tasks = client.tasks.list(status="Running", count=20)

for task in tasks:
    print(task.uuid, task.name, task.status, task.sub_task, task.root_task_name)

返回结果中，sub_task 用于区分父任务和子任务，root_task_name 用于将子任务关联到父任务。父任务处于终态，不代表重试子任务已经结束；应查看子任务自身的 status。分页结果可能将父任务和子任务分开。如需获取完整关联链，可调用 client.tasks.get_related(uuid="<TASK_UUID>")。管理员如需查询更大范围的任务，可按所有者过滤或拉取全量分页结果：

rows = client.tasks.list(is_task_admin=True, count=50)
rows = client.tasks.list(is_task_admin=True, owners="<USERNAME>", count=50)
all_rows = client.tasks.list(is_task_admin=True, owners="<USERNAME>", fetch_all=True)

常用查询参数如下：

参数	说明
`status`	按任务状态过滤。SDK 返回值以接口枚举为准。
`count`	本次单页查询返回的最大行数，包含子任务，不是去重后的任务数量。使用 `fetch_all=True` 时，不作为全部结果的数量上限。
`need_sub_task`	是否在单页查询中请求返回容错重试等子任务，默认为 `True`。
`is_task_admin`	以任务管理员视角查询。需要当前账号具备对应权限。
`owners`	按任务所有者过滤，支持传入一个或多个用户名。
`fetch_all`	拉取全部分页结果。任务数量较多时请谨慎使用。

查看任务 Pod

需要定位多 Pod 任务中的异常副本时，可以查询任务下的 Pod 信息。

pods = client.tasks.list_pods(uuid="<TASK_UUID>")

for pod in pods:
    print(pod.name, pod.status, pod.ip, pod.node)

如需继续查询日志、事件或指标，可将返回的 Pod 名称传入使用 Python SDK 查询日志或使用 Python SDK 查询指标中的相关接口。

更新任务优先级

对于排队中的非闲时任务，可以按需调整优先级。

ok = client.tasks.update_priority(
    uuid="<TASK_UUID>",
    priority=8,
)

print(ok)

优先级调整只影响后续调度竞争，不保证任务立即获得资源。调整后建议继续查询任务状态、事件或排队信息。

停止训练任务

停止单个任务：

uuid = client.tasks.stop(uuid="<TASK_UUID>")
print(uuid)

批量停止任务：

uuids = client.tasks.batch_stop(
    uuids=[
        "<TASK_UUID>",
    ]
)
print(uuids)

停止任务会影响正在运行的训练。执行前，请确认任务产物、checkpoint 和日志已按预期写入持久化存储。

删除训练任务

删除单个任务：

uuid = client.tasks.delete(uuid="<TASK_UUID>")
print(uuid)

批量删除任务：

uuids = client.tasks.batch_delete(
    uuids=[
        "<TASK_UUID>",
    ]
)
print(uuids)

删除前，请确认不再需要该训练任务记录及相关运行信息。

重新提交训练任务

uuids = client.tasks.resubmit(
    uuids=[
        "<TASK_UUID>",
    ]
)
print(uuids)

重新提交会基于原任务配置创建新的运行任务。提交前请确认原任务引用的镜像、资源池、Volume、数据集和模型仍可用。

开始使用

资源准备

开发与训练

模型与推理

运维与治理

最佳实践

开发者接入

常见问题

文档工具

使用 Python SDK 管理训练任务

创建训练任务

创建示例

参数说明

补充任务配置

通用配置

按任务类型配置

配置增强能力

自动容错

自定义指标采集

资源预检

任务 VSCS 访问

抢占通知

查询训练任务

查看任务 Pod

更新任务优先级

停止训练任务

删除训练任务

重新提交训练任务

相关文档

​创建训练任务

​创建示例

​参数说明

​补充任务配置

​通用配置

​按任务类型配置

​配置增强能力

​自动容错

​自定义指标采集

​资源预检

​任务 VSCS 访问

​抢占通知

​查询训练任务

​查看任务 Pod

​更新任务优先级

​停止训练任务

​删除训练任务

​重新提交训练任务

​相关文档

创建训练任务

创建示例

参数说明

补充任务配置

通用配置

按任务类型配置

配置增强能力

自动容错

自定义指标采集

资源预检

任务 VSCS 访问

抢占通知

查询训练任务

查看任务 Pod

更新任务优先级

停止训练任务

删除训练任务

重新提交训练任务

相关文档