使用 Python SDK 管理训练任务

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

创建训练任务

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

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

通过 SDK 参数创建

以下示例创建一个 PyTorchJob，并展示镜像、资源、Volume、增强能力、标签和环境变量等常用配置。

from siflow import SiFlow
from siflow.types import (
    TaskEnv,
    TaskEnhancements,
    TaskEnhancementsFaultTolerance,
    TaskEnhancementsPreemptNotify,
    TaskEnhancementsVscs,
    TaskMetricsMonitor,
    TaskUserSelectedInstance,
    TaskVolume,
)

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

uuid = client.tasks.create(
    name_prefix="demo-training",
    image_url="registry-cn-beijing.siflow.cn/siflow/ray:2.50.1-root",
    type="pytorchjob",
    priority=6,
    guarantee=False,
    enable_idle_resource=False,
    force_single_pod=False,
    cmd="python train.py --epochs 3",
    workers=1,
    resource_pool="<RESOURCE_POOL>",
    instances=[
        TaskUserSelectedInstance(name="sci.c23-2", count_per_pod=1),
    ],
    volumes=[
        TaskVolume(mount_dir="/volume/data", volume_id=1),
        TaskVolume(
            mount_dir="/volume/project",
            volume_id=11,
            sub_path="project-a/",
            read_only=False,
        ),
    ],
    enhancements=TaskEnhancements(
        fault_tolerance=TaskEnhancementsFaultTolerance(
            enabled=True,
            max_retry_count=1,
        ),
        metrics_monitor=TaskMetricsMonitor(
            enabled=True,
            port=9090,
            path="/metrics",
        ),
        vscs=TaskEnhancementsVscs(
            enabled=True,
            extension_dir="/volume/project/code-server/extensions",
            user_data_dir="/volume/project/code-server/user-data",
        ),
        preempt_notify=TaskEnhancementsPreemptNotify(
            enabled=False,
            port=9000,
            max_wait=600,
        ),
    ),
    labels={"project": "demo", "stage": "dev"},
    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],
)

print(uuid)

填写创建参数时，重点关注以下配置：

参数	说明
`name_prefix`	训练任务名称前缀。平台会基于该前缀生成任务名称。
`image_url`	完整镜像地址。使用该参数时，`image`、`image_version` 和 `image_type` 会被忽略。
`image` / `image_version` / `image_type`	不使用 `image_url` 时，用于按镜像名称、版本和类型定位唯一镜像。`image_type` 可选择 `preset` 或 `custom`，具体取值以 SDK 和当前镜像类型为准。
`type`	任务类型，例如 `pytorchjob` 或 `rayjob`。不同任务类型的专有配置不同。
`priority`	任务优先级。新版 SDK 支持整数优先级，通常为 `1` 到 `9`；闲时任务优先级为 `0`。
`guarantee`	是否启用资源预留。该配置仅对预留资源池有效，其他资源池类型会被忽略。
`enable_idle_resource`	使用预留资源池时，是否允许降级使用闲时资源。
`force_single_pod`	是否强制任务调度到单个 Pod 网络组。默认允许跨 Pod 网络组调度。
`cmd`	任务入口命令。
`workers`	Worker 数量。
`resource_pool`	任务使用的实例资源池名称。具体名称以控制台资源池为准。
`instances`	Worker 使用的实例规格和数量。`count_per_pod` 表示每个 Pod 使用的实例份数。
`volumes`	挂载到任务 Pod 的 Volume。开启目录级权限的 Volume 通常需要配置 `sub_path`；`sub_path` 是卷内相对路径，不能以 `/` 开头。如果目录只有读权限，请设置 `read_only=True`。
`datasets` / `models`	挂载到任务 Pod 的数据集或模型。
`enhancements`	任务增强能力配置，例如自动容错、监控指标采集、VSCS 访问、抢占通知等。
`labels`	任务标签，用于后续筛选、统计或治理。
`task_env`	任务环境变量。`hide=True` 时，非任务所有者查看任务详情时该值会隐藏。
`scheduling_policy_id_list`	调度策略 ID 列表。传入前请确认策略在当前区域、集群和资源池下可用。

按任务类型补充配置

PyTorchJob 通常只需要配置 workers、instances、启动命令和挂载资源。开启 enhancements.vscs 后，可从网页打开 VSCS 访问任务环境；该能力仅对 pytorchjob 生效。 RayJob 支持为 Head 节点单独指定实例规格。未配置 head_instances 时，Head 与 Worker 使用同一实例规格。

uuid = client.tasks.create(
    name_prefix="demo-ray",
    image_url="registry-cn-beijing.siflow.cn/siflow/ray:2.50.1-root",
    type="rayjob",
    cmd="python ray_train.py",
    workers=2,
    resource_pool="<RESOURCE_POOL>",
    head_instances=[
        TaskUserSelectedInstance(name="sci.c23-2", count_per_pod=1),
    ],
    instances=[
        TaskUserSelectedInstance(name="sci.c23-2", count_per_pod=1),
    ],
)

print(uuid)

配置增强能力

增强能力建议按需要启用，不必为每个任务都配置。

配置	说明
`fault_tolerance`	自动容错配置。启用后可设置 `max_retry_count`，用于任务异常后的重试。
`metrics_monitor`	自定义指标采集配置。`port` 为训练进程暴露指标的端口，请勿使用 `8080`；`path` 为指标路径，例如 `/metrics`。
`vscs`	任务 VSCS 访问配置。`extension_dir` 和 `user_data_dir` 建议使用持久化路径，避免扩展和用户配置随任务环境丢失。
`preempt_notify`	抢占通知配置。`port` 为训练进程监听通知的端口，建议使用 `9000` 到 `9999`；`max_wait` 为最长存盘等待秒数。

通过 YAML 创建

如果已有任务 YAML，可以通过 yaml_file 提交。YAML 字段与 SDK 参数含义保持一致。

uuid = client.tasks.create(yaml_file="/path/to/task-yaml-file.yml")
print(uuid)

示例：

namePrefix: demo-training
imageUrl: registry-cn-beijing.siflow.cn/siflow/ray:2.50.1-root
type: pytorchjob
priority: 6
guarantee: false
enableIdleResource: false
forceSinglePod: false
cmd: |
  python train.py --epochs 3
workers: 1
resourcePool: <RESOURCE_POOL>
instances:
  - name: sci.c23-2
    countPerPod: 1
volumes:
  - volumeId: 1
    mountDir: /volume/data
  - volumeId: 11
    mountDir: /volume/project
    subPath: project-a/
    readOnly: false
enhancements:
  faultTolerance:
    enabled: true
    maxRetryCount: 1
  metricsMonitor:
    enabled: true
    port: 9090
    path: /metrics
  vscs:
    enabled: true
    extensionDir: /volume/project/code-server/extensions
    userDataDir: /volume/project/code-server/user-data

RayJob YAML 可增加 headInstances：

type: rayjob
headInstances:
  - name: sci.c23-2
    countPerPod: 1
instances:
  - name: sci.c23-2
    countPerPod: 1

查询训练任务

根据任务 UUID 查询详情：

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

查询任务列表：

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

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

管理员如需查询更大范围的任务，可按所有者过滤或拉取全量分页结果：

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`	本次查询返回的最大任务数量。
`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 查询日志和指标中的日志和指标接口。

更新任务优先级

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

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 管理训练任务

创建训练任务

通过 SDK 参数创建

按任务类型补充配置

配置增强能力

通过 YAML 创建

查询训练任务

查看任务 Pod

更新任务优先级

停止训练任务

删除训练任务

重新提交训练任务

相关文档

​创建训练任务

​通过 SDK 参数创建

​按任务类型补充配置

​配置增强能力

​通过 YAML 创建

​查询训练任务

​查看任务 Pod

​更新任务优先级

​停止训练任务

​删除训练任务

​重新提交训练任务

​相关文档

创建训练任务

通过 SDK 参数创建

按任务类型补充配置

配置增强能力

通过 YAML 创建

查询训练任务

查看任务 Pod

更新任务优先级

停止训练任务

删除训练任务

重新提交训练任务

相关文档