> ## 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.

# 创建训练任务

> 在人工智能平台中创建 PyTorchJob 或 RayJob 训练任务，并配置镜像、挂载、资源、调度策略、启动命令和增强能力。

创建训练任务后，平台会根据您选择的区域、集群、资源池和实例规格调度资源，并在容器中运行训练命令。本文以控制台表单创建为例说明完整配置流程。

## 创建训练任务

### 1. 进入创建页

1. 进入 **训练任务 > 任务管理**。
2. 在 **个人任务** 页签，单击 **新建**。

### 2. 填写通用配置

先填写 **PyTorchJob** 和 **RayJob** 共用的基础配置。任务类型会影响后续需要补充的专有配置。

#### 基本信息

| 配置项         | 说明                                                                      |
| ----------- | ----------------------------------------------------------------------- |
| **区域和集群**   | 决定任务运行位置，也会影响可选资源池、镜像、存储、数据集和模型。                                        |
| **项目组**     | 任务归属的项目组，用于资源和权限归类。                                                     |
| **名称前缀**    | 任务名称前缀。平台会在名称前缀后追加唯一后缀生成最终任务名。名称建议使用小写字母、数字和中划线，并以字母或数字开头和结尾。           |
| **任务类型**    | 选择任务类型。支持 **PyTorchJob** 和 **RayJob** 两种任务类型。不同任务类型会影响后续资源配置、启动方式和专有配置。 |
| **在项目组内公开** | 控制任务是否在项目组内可见。不公开时，通常仅任务所有者可见。                                          |
| **时区**      | 影响任务日志和时间字段的展示。                                                         |
| **标签**      | 为任务打标签，便于归类、筛选和审计。管理员开启标签验证后，提交任务时可能需要选择已维护的标签。                         |

#### 环境信息

运行环境决定训练容器使用什么镜像、读取哪些输入、把输出写到哪里，以及容器启动后执行什么命令。创建前请确认镜像、代码路径、数据路径和输出路径已经准备好。

| 配置项      | 说明                                                                                                                                                                                                     |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **镜像**   | 支持选择内置镜像、自定义镜像或直接填写镜像地址。镜像需要包含训练脚本运行所需框架和依赖。RayJob 需要使用包含 Ray 运行环境的镜像；如需 Ray Dashboard 完整功能，自定义镜像中也需要包含对应依赖。                                                                                           |
| **环境变量** | 单击 **Add** 为当前任务添加临时环境变量，可用于传递路径、参数、开关或凭据。配置时关注：<ul><li>环境变量名称只能包含字母、数字和下划线，不能以数字开头，也不能以 `KUBERNETES_` 开头。</li><li>可按需隐藏变量值；隐藏后，分享任务时其他用户看到的值会以掩码展示。</li><li>若与任务环境变量管理中的持久环境变量同名，以当前任务配置为准。</li></ul> |
| **存储**   | 挂载 Volume，用于保存代码、checkpoint、训练输出和模型文件。需要同时选择存储并填写 **Pod 中挂载路径**。同一存储卷在同一挂载路径只能挂载一次。                                                                                                                    |
| **数据集**  | 挂载数据集，供训练脚本读取输入数据。通常作为只读输入使用，需要填写容器内挂载路径。                                                                                                                                                              |
| **模型**   | 挂载模型，供微调、继续训练或评估使用，需要填写容器内挂载路径。                                                                                                                                                                        |
| **命令**   | 容器启动后执行的训练命令，平台以 `bash -c` 执行。PyTorchJob 可在命令中使用平台自动注入的分布式训练环境变量；RayJob 的命令通常是 Ray entrypoint，例如 `python main.py`。                                                                                     |

<Tip>
  存储、数据集和模型的挂载路径建议使用 `/volume`、`/mnt` 等开头的独立目录，避免覆盖 `/opt`、`/workspace`、`/usr` 等镜像默认目录。路径冲突可能导致依赖、代码或启动命令不可用。容器本地盘容量有限，写入大量数据可能导致负载系统变慢，重启或迁移后本地盘数据也可能被清空；训练代码、数据集、模型、checkpoint 和输出结果等重要文件，建议写入挂载的 Volume。
</Tip>

#### 计算资源

计算资源决定任务使用哪类资源、启动多少个副本，以及每个副本申请多少 CPU / GPU。建议按 **资源类型 -> 副本规模 -> 实例规格 -> 配额和调度** 的顺序填写。

**1. 选择资源类型**

不同资源类型会影响可选实例、配额校验、资源保障和中断风险。

| 资源类型     | 适合场景                                     | 配置要点                                                                                     |
| -------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- |
| **预留实例** | 使用已购买或已分配的预留配额运行训练任务。                    | 选择 **共享资源池** 或 **专属资源池**，再选择实例规格。任务可接受闲时补充时，可开启 **接受闲时资源**，并按需要选择 **优先闲时**、**闲时稳定性等级**。  |
| **按量实例** | 临时启动训练任务，不希望提前占用预留配额。                    | 选择实例规格、**单节点实例规格数**、**资源优先级** 和 **资源保障**。分布式训练采用整体调度，资源不足时任务会整体排队。                       |
| **Spot** | 成本敏感、可中断、可重试的训练任务。                       | 选择实例规格、**单节点实例规格数**、**资源优先级** 和 **资源保障**。页面没有可选实例时，说明当前筛选范围内暂不可用，可切换区域、集群、资源类型或实例类型后再确认。 |
| **闲时资源** | 可接受不稳定运行时长，并且训练程序具备 checkpoint 或重提能力的任务。 | 选择 **闲时稳定性等级** 并关注 **闲时资源碎片**。闲时资源不支持设置 **优先级** 和 **资源保障**。                              |

**2. 配置副本规模**

| 配置项            | 说明                                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| **主节点 / 工作节点** | 主节点默认为 `1` 且不可更改，使用与工作节点相同规格的实例。工作节点数可填 `0`，用于单机训练；分布式训练时，工作节点数会影响需要同时调度的副本数量。                                      |
| **任务总副本数**     | PyTorchJob 通常按 `主节点数 + 工作节点数` 计算需要同时调度的副本数。RayJob 会包含 1 个 Head Pod 和若干 Worker Pod；如果单独配置 Head 实例规格，还需要同时考虑 Head 资源。 |

**3. 选择实例规格**

| 配置项          | 说明                                                                                |
| ------------ | --------------------------------------------------------------------------------- |
| **实例类型**     | 选择 **GPU** 或 **CPU**，再在实例列表中选择具体实例规格。实例详情展示该规格包含的 GPU、vCPU 和内存等资源。                |
| **单节点实例规格数** | 配置单个副本使用多少份所选实例规格。单个副本的资源需求 = 实例详情中的单份资源 × **单节点实例规格数**。                          |
| **资源优先级**    | 选择多个实例规格时，平台按优先级从高到低尝试调度，优先使用排在前面的实例。仅选择训练代码兼容的规格，避免任务调度到不兼容的 GPU 型号或 CPU / 内存组合。 |

**4. 确认配额和调度**

提交前不要只看单个实例规格是否可选，还需要确认整个任务能被同时调度。

| 关注项               | 判断方式                                                                        |
| ----------------- | --------------------------------------------------------------------------- |
| **用户剩余配额**        | 当前账号在该资源类型、资源池和实例规格下可继续使用的配额。创建任务时，按整个任务的资源需求核对，而不是只核对单个副本。                 |
| **资源池可用量**        | 资源池当前可提供的容量参考值。该值会随其他任务和资源池状态变化，不能视为资源预留。                                   |
| **闲时数量 / 闲时资源碎片** | 使用预留实例的闲时补充能力或直接选择闲时资源时，关注页面展示的闲时数量、稳定性等级和碎片情况。碎片信息只能作为可用性参考，分布式训练仍需满足整体调度。 |
| **资源保障**          | 按资源类型和页面能力选择是否启用更稳定的保障策略。关键训练、长时间训练或恢复成本较高的任务，建议优先使用支持资源保障的配置。              |

<Tip>
  分布式训练采用整体调度。任务需要的副本不能只看资源总量相加，还要确认每个副本能放入可用节点，并且所有副本能同时启动。资源不足时，任务会整体进入队列，待资源满足后自动调度，无需手动重试。
</Tip>

优先级会影响任务排队和调度顺序，也可能影响资源竞争中的处理结果。更完整的低成本资源、资源保障、节点调度策略和抢占说明，请参考[训练任务高级配置](./advanced-training-task-configuration)。

#### 高级选项

| 配置项           | 说明                                                                                                                                                                   |
| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **启用自动容错**    | 开启后，平台可在任务异常时按策略进行重试或恢复，并可按页面展示设置最大重试次数。基础容错可用于 PyTorchJob 和 RayJob；更细的容错策略、Hang 检测等能力以页面展示为准。自动重试不能解决代码、数据路径、显存不足等需要修改配置或脚本的问题。                                     |
| **监控看板**      | 开启后接入任务自定义监控指标，并按页面要求填写指标端口和路径，例如 `/metrics`。训练代码需要自行暴露对应端口和路径，任务进入运行中后才会产生可采集数据。                                                                                    |
| **镜像拉取容错**    | 配置镜像拉取失败的最大重试次数，用于处理短时拉取抖动。默认值以当前页面展示为准；配置为 `0` 表示首次失败即判定失败，配置为 `-1` 表示关闭本任务的镜像拉取熔断，配置为正整数表示使用本任务自定义阈值。                                                              |
| **Pod 间免密登录** | 开启该配置后，将自动启用多 Pod 之间的免密码 SSH 登录，并生成节点信息，分别保存在 `/root/hostfile` 和 `/root/hostfile.hostname` 文件中。该功能在常见操作系统（如 Ubuntu）以及常见镜像（如 NGC 镜像）中均可使用。但在某些特殊环境下可能不可用，如遇问题请联系技术支持。 |
| **告警订阅**      | 如果需要在任务创建时同步配置告警，可单击 **新增告警订阅**。告警订阅的详细配置请参考[创建告警订阅](../alerts/create-alert-subscriptions)。                                                                          |

### 3. 按任务类型补充配置

#### PyTorchJob

PyTorchJob 适合运行基于 PyTorch 的单机或分布式训练任务。完成通用配置后，请重点检查 **命令** 是否能正确启动训练脚本。

PyTorchJob 多机多卡训练可在启动命令中使用平台注入的分布式训练环境变量：

| 环境变量          | 说明         |
| ------------- | ---------- |
| `MASTER_ADDR` | 主节点地址。     |
| `MASTER_PORT` | 主节点端口。     |
| `WORLD_SIZE`  | 参与训练的总机器数。 |
| `RANK`        | 当前节点编号。    |

平台还会注入任务上下文相关环境变量，例如 `X_USER_NAME`、`X_ORG_NAME`、`X_TENANT_ID`、`X_REGION`、`X_CLUSTER` 和 `TASK_UUID`。如果训练脚本需要记录任务来源、区域、集群或唯一任务标识，可以读取这些变量。

示例：

```bash theme={null}
torchrun \
  --master_addr "$MASTER_ADDR" \
  --master_port "$MASTER_PORT" \
  --nnodes "$WORLD_SIZE" \
  --nproc_per_node 8 \
  --node_rank "$RANK" \
  train.py
```

请根据实际单节点 GPU 数量调整 `--nproc_per_node`，并将 `train.py` 替换为实际训练脚本。

#### RayJob

RayJob 适合运行基于 Ray 的分布式训练、调度或并行计算任务。完成通用配置后，请重点检查 Head / Worker、Runtime Env、共享存储和自动扩缩容等配置。

| 配置项                   | 说明                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Head 实例规格**         | 配置 Head 节点使用的实例规格。不单独配置时，通常使用与 Worker 相同的规格。                                                                             |
| **Runtime Env**       | 填写 Ray Runtime Env，使用 Ray 支持的 YAML 格式，可用于声明运行时依赖、环境变量等；不需要额外运行时配置时可以留空。                                                  |
| **挂载共享存储**            | 将同一个 Volume 挂载到 RayJob 各 Pod 的 `/tmp/ray` 目录，用于跨 Pod 共享 checkpoint、日志、中间结果或缓存数据。共享存储仅适用于 RayJob，且需要选择支持多 Pod 读写的 Volume。 |
| **任务退出后清理共享存储数据**     | 勾选后，任务结束时清理本任务在共享存储中的数据；不勾选则保留数据，便于调试，但需要关注存储空间占用。                                                                       |
| **Debug 模式 / 集群保存时间** | 开启后，RayJob 结束时保留 Ray 集群一段时间，便于进入 Head Pod 排查。默认保留时间通常为 600 秒，具体值以创建任务时的配置为准。                                             |
| **自动扩缩容**             | 开启后，Ray 可根据负载调整 Worker 数量。配置时关注缩容下限、扩容上限、回收时间和扩容模式，避免扩缩容范围超过任务预期或资源预算。                                                   |

选择 RayJob 后，需要关注 Ray 运行方式和资源占用：

* RayJob 会包含 1 个 Head Pod 和若干 Worker Pod。
* Worker 数由创建表单中的工作节点数决定，最终占用资源的 Pod 数通常为 `Worker 数 + 1`。
* RayJob 的用户代码日志通常通过 Submitter Pod 查看。
* Ray 集群自身日志可查看 Head Pod 或 Worker Pod。
* RayJob 的启动命令通常是 Ray entrypoint，例如 `python main.py`。

如需了解共享存储、自动扩缩容、Runtime Env 或 Debug 模式的更多配置建议，请参考[训练任务高级配置](./advanced-training-task-configuration)。

### 4. 提交创建

单击 **新建** 提交任务。任务提交后会进入队列等待调度，您可以在任务列表中查看状态，也可以进入详情页查看事件、日志和监控。

如果任务长时间排队、调度失败或启动失败，请先查看详情页事件，再根据事件信息检查资源配额、镜像、挂载路径和启动命令。

## 后续操作

* [查看和管理训练任务](./view-and-manage-training-tasks)