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

# 训练任务高级配置

> 了解如何在人工智能平台中配置训练任务的低成本资源、调度策略、RayJob 增强、Debug 重提、任务协作、环境变量和自定义监控。

除基础创建流程外，训练任务还提供一组可按需启用的高级配置，用于控制成本、调度范围、RayJob 行为、故障排查、协作复用和观测方式。本文按配置目标说明入口、配置方式和使用限制；创建任务的完整流程请参考[创建训练任务](./create-training-tasks)。

## 低成本资源

### Spot 实例

Spot 实例适合可中断、有 checkpoint 或可重试机制的非关键任务。使用 Spot 资源时，任务可能在资源紧张时被驱逐，任务状态可能变为失败。

在创建训练任务时，进入 **计算资源** 配置，选择 **Spot** 资源类型，再按页面展示选择实例类型、实例规格和单节点实例规格数。Spot 资源可用量会随集群机器利用率变化；如果页面没有可选实例，说明当前筛选范围内暂不可用。

使用 Spot 时，建议关注以下信息：

* 适合实验性任务、批处理任务或可快速重提的训练。
* 不适合没有 checkpoint 的长时间关键训练。
* Spot 属于非保障型资源，所在机器资源紧张时任务可能被驱逐。
* 被驱逐后，任务可能进入失败状态。建议根据任务输出和 checkpoint 重新提交；关键训练改用预留或按量资源。

### 闲时任务

闲时任务使用集群当前空闲资源运行，提交时无需绑定已购买配额。闲时任务成本低，但资源不保障，可能被更高优先级任务抢占。

在创建训练任务时，进入 **计算资源** 配置，选择 **闲时资源**。选择后按页面展示选择实例类型、实例规格和单节点实例规格数，并按需配置 **闲时稳定性等级**。

使用闲时任务时，建议关注以下信息：

* 适合可中断、可重试、不要求固定完成时间的任务。
* 闲时资源可用量会动态变化，任务可能被更高优先级任务抢占。
* **闲时资源碎片** 会随稳定性等级变化。分布式训练需要每个副本能落到可用节点，不能把多行碎片简单相加判断是否可调度。
* 闲时资源不支持设置 **优先级** 和 **资源保障**，以页面禁用状态为准。
* 任务被抢占后可能进入失败状态，状态信息可能包含 `was preempted by another task`。
* 建议为训练脚本配置 checkpoint 或重试机制，避免把关键训练流程完全依赖在非保障资源上。

## 调度和资源保障

### 优先级

训练任务支持配置优先级。优先级会影响任务排队和调度顺序，也可能影响任务是否可被抢占。

在创建训练任务时，按页面展示配置任务优先级。通常可以按任务重要性和时效性选择优先级：

| 任务类型      | 建议                              |
| --------- | ------------------------------- |
| 关键训练      | 使用较高优先级，并结合资源保障，减少被抢占或长时间排队的风险。 |
| 常规实验      | 使用普通优先级，便于在稳定性和资源公平性之间取得平衡。     |
| 可中断实验或批处理 | 使用较低优先级或闲时资源，降低对关键任务的影响。        |

优先级不是资源预留承诺。任务能否启动仍取决于资源池状态、个人配额、实例规格和调度条件；如果长时间排队，请进入任务详情查看事件，再按[排查任务资源不足或长时间排队](../resources/troubleshoot-insufficient-resources-or-queued-tasks)处理。

### 资源保障

资源保障用于控制任务是否使用不可抢占资源。开启资源保障后，任务稳定性更高；不开启时，任务可能在资源竞争中被抢占。

在创建训练任务时，如果页面提供 **资源保障** 配置，可根据任务稳定性要求选择是否开启。关键训练、长时间训练或恢复成本较高的任务，建议开启资源保障；短时实验、可快速重提的任务，可以结合成本和资源紧张程度选择不开启。

优先级和资源保障会共同影响资源竞争中的调度结果。资源保障不处理代码异常、镜像拉取失败、数据路径错误或硬件故障；这些问题需要结合日志、事件和容错机制排查。

### 节点调度策略

节点调度策略用于指定任务只调度到某些节点，或屏蔽某些节点。它适合以下场景：

* 排查某个节点可能导致的训练异常。
* 临时绕过已知异常节点。
* 将任务固定到特定节点范围内运行。

您可以在创建训练任务时的 **计算资源** 区域查看或配置节点调度策略，也可以从任务列表或任务详情页中页面提供的节点调度入口进入。配置节点调度策略时，通常需要选择生效范围、调度类型、节点名称和过期时间；具体字段以当前页面展示为准。

常见调度类型包括：

* **NodeIn**：仅调度到指定节点。
* **NodeNotIn**：屏蔽指定节点。

节点调度策略可能影响调度成功率。节点屏蔽策略可按当前用户生效，也可由管理员配置为租户范围内生效。配置屏蔽策略时，过期时间通常需在 1 分钟到 72 小时之间。

查看节点调度策略时，可以重点关注当前仍在生效的策略。通常情况下，您可以看到自己创建的策略，以及管理员配置的租户级未过期策略。

如果任务因节点屏蔽策略无法调度，事件或错误信息中可能出现 `quota check failed due to node blacklist: XXX`。此时请检查当前用户和租户范围内是否存在命中的屏蔽策略。

## RayJob 增强能力

### 共享存储

RayJob 可配置共享存储，将同一个 Volume 挂载到 Head 和 Worker Pod 中，用于共享 checkpoint、日志、中间结果或缓存数据。

在创建训练任务时，选择任务类型为 **RayJob**，在 RayJob 专有配置中打开 **挂载共享存储**，选择要挂载的 Volume。按需选择是否在任务退出后清理共享存储数据。

提交后，平台会校验当前账号对 Volume 的权限，并将共享存储挂载到 RayJob 各 Pod。任务代码可通过 `/tmp/ray` 读写共享存储。

```python theme={null}
import os
import torch

with open("/tmp/ray/checkpoint.pt", "wb") as f:
    torch.save(model.state_dict(), f)

state_dict = torch.load("/tmp/ray/checkpoint.pt")
files = os.listdir("/tmp/ray")
```

共享存储适合以下任务：

| 任务            | 说明                             |
| ------------- | ------------------------------ |
| checkpoint 共享 | 多个 Ray Pod 需要读写同一份 checkpoint。 |
| 日志聚合          | 希望把 Head 和 Worker 的输出写入统一目录。   |
| 中间结果传递        | 多阶段 Ray Pipeline 需要直接读取前序阶段输出。 |
| 数据预处理缓存       | Head 预处理后，Worker 复用缓存结果。       |
| 调试数据收集        | 将 profiling、trace 或临时排查文件集中保存。 |

使用共享存储时，建议关注以下信息：

* 共享存储仅适用于 RayJob，PyTorchJob 不支持该能力。
* 共享存储会挂载到 RayJob 各 Pod 的 `/tmp/ray` 目录。
* 调试阶段可以不勾选退出后清理，便于保留现场数据；生产任务建议开启清理，避免空间泄漏。
* 共享存储适合跨 Pod 共享数据，不替代任务输入数据集或长期模型归档。
* 共享存储不参与调度决策；任务是否能调度成功仍取决于资源池、实例规格、节点策略和配额。
* 共享存储需要使用支持多 Pod 读写的 Volume，具体可选 Volume 以页面展示和管理员配置为准。
* 共享存储会按任务组织目录，同一任务的 Head 和 Worker Pod 可在 `/tmp/ray` 下共享数据。需要减少不同任务之间的数据混淆时，建议使用不同的任务名称前缀，并在代码中使用明确的子目录。
* 任务退出后清理共享存储数据不会改变任务最终状态。清理失败时，可进入对应 Volume 手动清理本任务目录。

### 自动扩缩容

RayJob 可根据负载自动调整 Worker 数量。配置时需要关注缩容下限、扩容上限、回收时间和扩容模式。

在创建训练任务时，选择任务类型为 **RayJob**，在 Ray 自动扩缩容配置中启用该能力，并填写扩缩容参数。

| 配置项  | 说明                              |
| ---- | ------------------------------- |
| 缩容下限 | Worker 最小副本数，避免缩容后低于任务可运行的最小规模。 |
| 扩容上限 | Worker 最大副本数，用于控制资源消耗上限。        |
| 回收时间 | Worker 空闲超过该时长后，平台可回收对应 Worker。 |
| 扩容模式 | 控制扩容节奏。保守模式更平稳，激进模式更快扩到期望副本数。   |

负载波动明显的 Ray 任务适合开启自动扩缩容。对资源稳定性要求高的任务，应谨慎设置扩缩容上下限，避免频繁扩缩容影响训练或计算过程。

### Runtime Env

Runtime Env 用于配置 Ray 作业运行时依赖、环境变量等内容。使用前请确认镜像中已有基础 Ray 环境，并确认 Runtime Env 配置格式正确。

在创建训练任务时，选择任务类型为 **RayJob**，在 RayJob 专有配置中填写 Runtime Env。Runtime Env 使用 Ray 支持的 YAML 格式，可用于声明运行时依赖、环境变量等配置；不需要额外运行时配置时可以留空。

RayJob 需要使用包含 Ray 运行环境的镜像。如果使用自定义镜像，请确认镜像内包含任务所需的 Ray 组件和依赖，否则 Ray 进程可能无法启动，任务无法进入运行中状态。

### Pod 组成和日志

RayJob 提交后通常包含以下 Pod：

| Pod 类型        | 说明                            | 是否占用配额       |
| ------------- | ----------------------------- | ------------ |
| Head Pod      | Ray 集群的 Head 节点，数量为 1。        | 是            |
| Worker Pod    | Ray 集群的 Worker 节点，数量由工作节点数决定。 | 是            |
| Submitter Pod | 执行 Ray 提交命令并汇总用户代码日志。         | 通常不占用训练资源配额。 |

RayJob 最终占用训练资源的 Pod 数通常为 `Worker 数 + 1`。用户代码日志通常通过 Submitter Pod 查看；Ray 集群自身日志可查看 Head Pod 或 Worker Pod。

如果需要访问 Ray Dashboard，请确认镜像中包含对应依赖，并以任务详情页展示的入口为准。

RayJob 运行过程中，如果未开启 Debug，Ray 集群通常会在 Submitter Pod 结束后回收；如果开启 Debug，Ray 集群会在配置的保存时间内继续保留，便于进入 Head Pod 查看集群状态。非停止状态下停止 RayJob 会释放相关 Pod 资源。

## 调试和恢复

### Debug 重提

Debug 重提适合任务失败原因不明确、需要进入容器检查环境、路径、依赖或节点现场的场景。它会基于原任务配置重新提交一个用于排查的新任务，通常保留原资源需求，并以 `sleep inf` 等排查命令启动，不会直接执行原训练命令。

在任务列表中找到目标任务，单击 **重提**，并在重提弹窗中选择 Debug 模式。提交前，请确认需要保留的 checkpoint、日志或模型输出已经写入持久化 Volume。

对于 RayJob，如果在创建任务时开启 Debug 并设置集群保存时间，任务结束后 Ray 集群会保留一段时间，便于进入 Head Pod 查看集群状态。默认保留时间通常为 600 秒，具体值以创建任务时的配置为准。Debug 期间任务可能处于 `DebugHolding` 状态。如果页面提供 Terminal 入口，可进入 Head Pod 查看 Ray 集群状态。

### 自动容错

自动容错用于在任务异常时按策略进行重试或恢复。它适合已经把 checkpoint 写入持久 Volume、且训练程序能够从 checkpoint 继续运行的任务。

在创建训练任务时，进入 **高级选项**，开启 **自动容错**，并按页面展示配置最大重试次数、容错策略或 Hang 检测等能力。基础自动重试可用于任务失败后的重新提交；更细的容错策略和 Hang 检测以当前任务类型和页面能力为准。

自动容错不能修复确定性的配置错误。遇到镜像不可用、启动命令错误、数据路径错误或显存不足时，应先修改任务配置或训练脚本，再重新提交。

任务失败后，可在任务详情页查看容错详情、关联重试任务和故障说明。具体排查方法请参考[使用自动容错恢复训练任务](./recover-training-tasks-with-auto-fault-tolerance)。

## 协作和复用

### 标签

标签用于归类、筛选、统计和审计训练任务。管理员开启标签校验后，提交任务时需要选择标签。

在创建训练任务时，可按页面展示为任务选择标签。任务创建后，也可以在任务列表或任务详情页提供的标签入口中调整标签。标签本身不影响任务运行，但会影响筛选、统计、审计和团队治理。

管理员可以在[管理标签](../configuration/manage-labels)中维护可选标签和标签验证规则。开启标签验证后，训练任务提交时可能需要选择已维护的标签。

在任务列表中按多个标签筛选时，通常按与关系过滤，即只展示同时匹配所选标签的任务。

### 分享

任务所有者可以将任务分享给组织内其他用户。被分享用户通常可以查看任务详情、日志并克隆任务；是否可以执行停止或删除等操作，以控制台权限规则为准。克隆被分享任务时，如果包含当前账号无权限使用的 Volume，需要重新选择存储并核对命令中的路径。

在任务列表或任务详情页中，如果页面提供 **分享** 入口，可选择要分享的用户并提交。被分享用户可在 **被分享任务** 页签查看任务。

克隆被分享任务前，建议先进入任务详情核对资源、挂载和启动命令。若原任务包含当前账号无权限使用的 Volume，需要重新选择存储并同步调整命令中的路径。

### 环境变量

训练任务环境变量分为临时环境变量和持久环境变量：

* **临时环境变量**：在创建任务时填写，仅对当前任务生效。
* **持久环境变量**：在[管理任务环境变量](../configuration/manage-task-environment-variables)中维护，可自动注入训练任务。

如果两类环境变量 Key 冲突，以创建任务时填写的临时环境变量为准。

环境变量 Key 只能包含字母、数字和下划线，不能以数字开头，也不能使用 `KUBERNETES_` 前缀。

## 自定义监控

如果训练代码暴露 metrics，可在创建任务时开启监控看板接入，并配置 metrics 端口和路径。任务进入运行中后，可以在监控页使用自定义视角查看指标。

配置路径如下：

1. 在创建训练任务时，打开 **监控看板** 开关。
2. 填写指标端口和路径，例如 `/metrics`。
3. 提交任务。
4. 任务进入运行中后，进入任务详情页的 **监控** 页签，查看自定义指标。

使用建议：

* 指标名称和 label 应保持稳定，便于跨任务对比。
* 推荐使用任务 UUID 等唯一标识过滤指标，避免不同任务数据混淆。
* 任务需要自行暴露配置的 metrics 端口和路径；如果任务未暴露指标，监控看板不会产生预期数据。

训练任务自定义指标常见 label 包括 `cluster`、`orgname`、`user`、`module`、`task_type`、`task_name`、`task_uuid`、`resource_pool` 和 `region`。查询单个任务指标时，优先使用 `task_uuid` 过滤。

```promql theme={null}
training_steps_total{task_uuid="<TASK_UUID>"}
```

如需将常用 PromQL 查询沉淀为可复用图表，可在[管理监控看板](../configuration/manage-monitoring-dashboards)中创建看板。

## 相关文档

* [创建训练任务](./create-training-tasks)