> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siflow.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Python SDK 管理训练任务

> 使用人工智能平台 Python SDK 创建、查询、停止、删除、重提训练任务，查看 Pod，并管理任务优先级和调度配置。

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

## 创建训练任务

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

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

### 通过 SDK 参数创建

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

```python theme={null}
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 使用同一实例规格。

```python theme={null}
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 参数含义保持一致。

```python theme={null}
uuid = client.tasks.create(yaml_file="/path/to/task-yaml-file.yml")
print(uuid)
```

示例：

```yaml theme={null}
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`：

```yaml theme={null}
type: rayjob
headInstances:
  - name: sci.c23-2
    countPerPod: 1
instances:
  - name: sci.c23-2
    countPerPod: 1
```

## 查询训练任务

根据任务 UUID 查询详情：

```python theme={null}
task = client.tasks.get(uuid="<TASK_UUID>")
print(task.name, task.status, task.created_at)
```

查询任务列表：

```python theme={null}
tasks = client.tasks.list(status="Running", count=20)

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

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

```python theme={null}
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 信息。

```python theme={null}
pods = client.tasks.list_pods(uuid="<TASK_UUID>")

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

如需继续查询日志、事件或指标，可将返回的 Pod 名称传入 [使用 Python SDK 查询日志和指标](./query-logs-and-metrics-with-python-sdk) 中的日志和指标接口。

## 更新任务优先级

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

```python theme={null}
ok = client.tasks.update_priority(
    uuid="<TASK_UUID>",
    priority=8,
)

print(ok)
```

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

## 停止训练任务

停止单个任务：

```python theme={null}
uuid = client.tasks.stop(uuid="<TASK_UUID>")
print(uuid)
```

批量停止任务：

```python theme={null}
uuids = client.tasks.batch_stop(
    uuids=[
        "<TASK_UUID>",
    ]
)
print(uuids)
```

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

## 删除训练任务

删除单个任务：

```python theme={null}
uuid = client.tasks.delete(uuid="<TASK_UUID>")
print(uuid)
```

批量删除任务：

```python theme={null}
uuids = client.tasks.batch_delete(
    uuids=[
        "<TASK_UUID>",
    ]
)
print(uuids)
```

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

## 重新提交训练任务

```python theme={null}
uuids = client.tasks.resubmit(
    uuids=[
        "<TASK_UUID>",
    ]
)
print(uuids)
```

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

## 相关文档

* [Python SDK 快速开始](./python-sdk-quickstart)
* [使用 Python SDK 查询日志和指标](./query-logs-and-metrics-with-python-sdk)
* [创建训练任务](../training/create-training-tasks)
* [查看和管理训练任务](../training/view-and-manage-training-tasks)