文档中心

Appearance

✨费用中心控制台

训练故障处理 ​

任务失败时，先根据任务当前阶段判断下一步看哪里。本页按症状组织常见问题，帮助您从任务状态、日志、容错日志、资源监控和输出目录中找到第一个有用信号。

先判断问题发生在哪个阶段 ​

先看任务列表中的状态和任务详情页中的详细进度。不同阶段对应的排查入口不同：

  • 无法提交或选不到资源：先检查资源池、Worker 规格、可启动数量和镜像可见性。
  • 排队很久：先看目标规格的可启动数量和负载排队情况。
  • 卡在部署中：先看详细进度，区分资源分配、镜像拉取、存储挂载和环境初始化。
  • 环境检测异常：先看 容错日志，确认是 GPU、RDMA、存储 I/O、通信还是运行时环境问题。
  • 环境检测通过后仍然失败：先找 Bootcheck Finished 或 Check Finished 之后的第一条错误。
  • 第一个 batch 前失败：优先检查环境变量、依赖包、数据路径、数据字段、tokenizer、data collator 和输出目录。
  • 运行中无进展、Hang 或变慢：先看任务日志、资源监控、checkpoint 更新时间和容错日志。
  • 任务成功但没有产出：先检查启动命令是否隐藏失败，以及输出是否写到了共享存储。
  • 自动重启、恢复或重跑后进度异常：先检查日志中是否真的加载了 checkpoint。

无法提交或选不到资源 ​

本节用于处理还没有进入训练执行阶段的问题。此时优先检查创建页和资源池信息，通常不需要先改训练代码。

检查资源池和可启动数量 ​

如果资源池、Worker 规格或 Worker 数量无法满足任务需求，任务可能无法提交，或提交后长时间排队。先检查目标规格的可启动数量，再查看占用情况和负载排队情况。

可启动数量不足通常来自以下情况：

  • 目标规格所在节点已被其他任务、开发机或推理服务占用。
  • 空闲 GPU 分散在多个节点上，无法拼成目标 Worker 规格。
  • 训练脚本要求完整 8 卡 Worker 或 RDMA，不能随意改成更小规格。

需要调整资源形状时，先判断训练代码是否支持减少 Worker 数量、降低单 Worker GPU 数量或关闭自定义卡数。详见选择资源规格与查看排队情况。

检查镜像可用服务和可用区 ​

如果创建页无法选择目标镜像，先检查镜像是否开放给任务服务，以及镜像可用区是否与资源池所在可用区一致。镜像不可见通常不是启动命令问题，直接改启动命令无法绕过。

不要根据 Registry 域名或完整镜像地址判断镜像所在可用区。即使地址和 tag 相同，不同可用区中的镜像也可能不存在或内容不同；请在镜像中心查看可用区，必要时比较镜像摘要。详见镜像仓库地址与可用区。

如果任务已经进入部署阶段但镜像拉取失败，继续查看任务事件和部署进度，确认是镜像仓库访问、镜像地址、可用区还是权限问题。详见准备并验证容器镜像。

确认 RDMA 配置是否可用 ​

需要多机高速通信时，先确认所选规格的训练网配置为 RoCE 或 IB，并且 Worker 规格满足 RDMA 使用条件。GPU 数量小于完整 8 卡时，通常无法开启 RDMA。

如果创建页不能开启 RDMA，或任务运行后通信速度明显不符合预期，继续查看RDMA 网络。

排队很久或卡在部署中 ​

本节用于区分任务是在等待资源，还是已经拿到资源但卡在镜像、存储或环境初始化。先看任务状态，再决定是等资源、改规格，还是排查启动环境。

判断继续等待还是调整规格 ​

任务处于排队中时，先查看资源池目标规格的可启动数量和负载排队情况。如果可启动数量长期不足，可以考虑降低 Worker 数量、改用可启动数量足够的规格，或等待完整节点释放。

如果训练代码必须使用完整 8 卡 Worker、RDMA 或固定多机规模，通常应优先等待符合条件的资源。改成训练代码不支持的资源形状后，任务即使启动，也可能在分布式初始化或第一个 batch 附近失败。

Spot 资源任务达到自动排队上限 ​

使用 Spot 资源提交的训练任务，在库存不足、运行中资源被抢占，或自动排队达到上限后，可能进入异常状态。先查看任务详情中的事件记录、日志和创建配置，确认是否达到单次最大排队时长或最大重新排队次数。

多 Worker Spot 训练任务按整任务成组调度。任务处于排队中时，表示整任务正在等待全部所需 Worker，不是其中一部分 Worker 已经被保留并继续运行。

如果已经达到自动排队上限，需要人工处理：可以等待库存恢复后重试，改用其他规格或可用区，重新提交任务，或改用包年包月资源。重新运行时会再次执行启动命令，训练代码必须从 checkpoint 恢复；如果恢复后进度异常，继续查看自动重启、恢复或重跑后进度异常。

定位部署阶段卡点 ​

任务处于部署中时，先打开详细进度，判断卡在资源分配、镜像拉取、存储挂载还是环境初始化。不同卡点对应不同检查：

  • 资源分配：回到资源池可启动数量和排队情况。
  • 镜像拉取：检查镜像可用服务、可用区、镜像仓库地址和访问权限。
  • 存储挂载：检查共享高性能存储、挂载路径和可用区。
  • 环境初始化：查看任务日志和容错日志，确认是否已经进入 Bootcheck。

详见查看任务状态、日志与事件。

环境检测异常 ​

环境检测用于验证平台运行环境。它可以帮助判断 Worker、GPU、RDMA、存储 I/O、通信和运行时库是否存在问题，但不会读取训练数据，也不会验证训练脚本逻辑。

查看容错日志 ​

「任务容错」与「训练变慢检测」的输出均展示在任务详情页的 容错日志 标签页。容错日志用于确认环境检测项、自动重启次数、重调度次数和 Hang 检测结果。

为了充分利用容错日志，建议在长期训练、分布式训练或无人值守训练中开启任务容错。训练变慢检测仅适用于 Megatron-LM 和 LLaMA-Factory 框架的任务。

判断环境检测发现了什么 ​

启动检测（Bootcheck）和异常定位（Troubleshoot）会检查关键的软件和硬件环境，包括 GPU、RDMA、存储 I/O、通信和 PyTorch/CUDA/NCCL 运行时。

如果发现 GPU 掉卡等硬件错误，平台会阻断任务继续执行，并尝试重调度到健康节点后重启训练。如集群中没有冗余健康节点，容错功能无法恢复该任务。

如果检测记录了 RDMA、I/O、通信或慢节点等其他异常，平台可能继续执行用户代码。此时应结合训练日志、资源监控和任务是否实际进入训练阶段继续判断。详见配置训练任务容错。

环境检测通过后仍然失败 ​

环境检测通过，说明平台在当前检测项中没有发现 Worker、存储、通信或运行时环境问题。随后任务仍可能因为镜像依赖、启动命令、Python 包、脚本逻辑或数据格式失败。

排查时，先在任务日志中找到 Bootcheck Finished 或 Check Finished 之后的第一条错误。通常这是用户启动命令开始执行后暴露的问题。

常见信号包括：

  • 镜像缺少启动命令依赖的系统包、Python 包、虚拟环境工具或命令行工具。
  • 启动脚本路径不存在、没有执行权限，或引用了错误的工作目录。
  • 输入路径可以挂载，但数据文件、字段名、样本格式或 tokenizer 输出不符合脚本预期。
  • 输出目录不可写、输出路径已存在，或中间目录清理逻辑不符合预期。
  • 启动命令中的日志转存、上传结果或保留现场逻辑隐藏了训练脚本的失败结果。

遇到这类问题时，优先检查镜像和启动命令；如果错误出现在数据读取或第一个 batch 附近，再检查数据格式、collator 和输出路径。详见在开发机中试跑训练脚本和编写可靠启动命令。

启动后立即失败 ​

启动后立即失败通常说明启动命令、镜像运行环境或脚本入口有问题。先看任务日志中的第一条异常；最后一条日志经常只是清理、重启或包装脚本输出。

检查启动命令 ​

启动命令应满足：训练脚本成功时，创建页中的启动命令正常结束；训练脚本报错时，创建页中的启动命令以失败状态结束。

如果启动脚本路径不存在、没有执行权限、工作目录错误或环境变量缺失，任务通常会在训练代码真正开始前失败。先在任务日志中定位第一条 Shell 或 Python 异常，再回到启动命令和脚本内容中修复。详见编写可靠启动命令。

修复任务显示成功但训练实际失败的问题 ​

有时日志里已经出现 Python 异常、OOM、依赖缺失或 data collator 报错，但任务列表仍显示运行成功。常见原因是启动命令在训练脚本报错后又继续执行了别的命令，例如写一行完成日志、睡眠保留现场，或用 python train.py | tee train.log 写日志。平台看到的是创建页中的启动命令最后是否正常结束，而不一定是 Python 报错本身。

排查时先看任务日志中的第一条异常，确认训练脚本是否已经报错；再检查创建页中的启动命令是否在报错后继续执行并正常结束。常见修复方式包括：

  • 普通训练命令：训练脚本报错后立即停止；如果后面还要执行 echo、sleep 或上传结果，要保留训练脚本的失败结果。
  • 需要同时写日志：优先使用编写可靠启动命令中的日志模板。继续使用 python train.py | tee train.log 时，在脚本中设置 set -o pipefail。
  • 需要失败后保留现场：保留结束后仍按训练脚本的失败结果结束任务。

详见编写可靠启动命令。

修复 Conda 或虚拟环境启动失败 ​

如果日志中出现 conda activate、source、ModuleNotFoundError、虚拟环境路径不存在或 Python 包缺失，先确认镜像中已经包含目标环境和依赖。通用基础镜像可能缺少创建虚拟环境、安装依赖或激活环境所需的系统包。

如果这是团队长期使用的训练环境，优先制作包含固定依赖的训练镜像。临时在启动命令中安装大量依赖，会让错误暴露到任务启动之后，也会让重跑结果不稳定。Conda 激活细节见修复 Conda 激活失败。

第一个 batch 前失败 ​

第一个 batch 前失败通常属于训练代码、数据、依赖或输出路径问题。环境检测通过不能证明这些内容正确。

检查环境变量、依赖和数据路径 ​

如果日志中出现缺少环境变量、缺少 Python 包、找不到模型路径或找不到数据路径，先用同一镜像、同一挂载路径和同一批关键环境变量在开发机中复现。这样可以在提交正式训练任务前发现问题。

常见检查项包括：

  • DATA_DIR、OUTPUT_DIR、模型路径、API Key 等变量是否在创建页或启动脚本中设置。
  • 镜像是否包含训练脚本实际导入的 Python 包和系统库。
  • 数据路径是否位于挂载的共享存储中，而不是仅存在于某个 Worker 本地目录。

详见在开发机中试跑训练脚本。

检查数据字段、tokenizer 和 data collator ​

如果 traceback 出现在 dataset、tokenizer、collator、DataLoader、forward 或 loss 计算附近，优先检查样本字段、空样本、变长 label、多模态字段和 batch padding 逻辑。

这类问题通常需要在开发机中用同一份数据跑到第一个 batch。环境检测不会读取或解析训练数据，也不会替用户判断 data collator 是否正确。

检查输出和 checkpoint 路径 ​

如果日志中出现 Permission denied、No such file or directory，或者任务结束后没有任何输出，先确认 checkpoint、TensorBoard 日志、模型权重和中间结果都写入挂载的共享高性能存储。

写到 /tmp、/root、/workspace 等 Worker 本地路径的结果，任务结束后通常无法取回。详见获取训练结果和验证 checkpoint 保存与恢复。

运行中无进展、Hang 或变慢 ​

任务已经进入训练后，先判断是训练进度没有前进，还是日志、指标或 checkpoint 没有正确输出。不同信号对应不同排查路径。

判断训练是否真的没有进展 ​

先同时检查以下信号：

  • 任务日志中 step、loss、epoch 或自定义阶段标记是否继续更新。
  • 资源监控中 GPU 利用率、显存、CPU、网络和存储读写是否符合预期。
  • TensorBoard 曲线和 checkpoint 更新时间是否继续变化。
  • 多 Worker 任务中是否只有部分 Worker 或 rank 卡住。

如果只有日志不更新，但资源监控和 checkpoint 仍正常变化，优先检查日志输出和筛选条件。如果资源监控也没有变化，再继续排查 Hang、数据加载、通信或硬件问题。

使用 Hang 检测和进程栈采集 ​

若任务长时间无进展、疑似卡死，可结合Hang 检测与进程栈采集排查。Hang 判定后可按配置自动采集栈，也可在任务详情页 手动采集。

报告 汇总整任务范围内各 Worker / rank 的函数调用统计，便于横向对比；原始线程栈仍在 进程栈 子标签中查看。

查看训练变慢检测结果 ​

任务开启训练变慢检测后，平台可自动分析训练日志，发现训练变慢后在容错日志中输出告警。训练变慢检测仅支持 Megatron-LM 和 LLaMA-Factory 框架。

如果您在 容错日志 中看到 Smoothed mean、baseline 和 threshold ratio，说明平台正在比较当前 step 耗时和历史较快耗时。数值明显增大时，优先结合资源监控判断是数据加载、通信、checkpoint 保存还是硬件性能问题。

例如：

language-shell
2025-04-21 15:19:58 Command running...
2025-04-21 15:25:56 Smoothed mean (iters 83-87: 9465.00 ms, baseline: 3101.00 ms), threshold ratio:2.05. Warning
2025-04-21 15:27:26 Smoothed mean (iters 88-92: 16704.00 ms, baseline: 3101.00 ms), threshold ratio:4.39. Warning

这个例子可以这样读：

  • Smoothed mean 是最近一小段 step 的平均耗时。iters 83-87: 9465.00 ms 表示第 83 到 87 步的平均耗时约为 9.5 秒。
  • baseline 是本次任务历史上较快的一段 step 平均耗时，用来作为对比基准。
  • threshold ratio 表示当前平均耗时相对 baseline 变慢的比例，可按 (当前平均耗时 - baseline) / baseline 理解。threshold ratio:2.05 表示当前 step 比 baseline 慢约 205%，也就是耗时约为 baseline 的 3.05 倍；threshold ratio:4.39 表示当前 step 比 baseline 慢约 439%。

当前告警阈值为 0.8。它表示当前 step 平均耗时比 baseline 慢约 80% 时触发告警；换算成耗时倍数，就是当前平均耗时约达到 baseline 的 1.8 倍。注意，0.8 不是指当前耗时为 baseline 的 0.8 倍。

训练变慢告警表示任务比自己早先的训练速度变慢，不直接等同于硬件故障。继续排查时，先看变慢时段是否正好发生在 checkpoint 保存、评估、数据加载高峰或序列长度变化阶段；再结合资源监控、Worker / rank 日志和通信错误判断是否存在慢节点、存储 I/O 或分布式通信问题。

当训练速度异常缓慢或 GPU 利用率低时，可使用 atlctl burn 烧机测试验证硬件性能是否正常。

分布式通信失败 ​

分布式通信问题通常需要同时检查平台注入的分布式信息、训练脚本启动参数、网络规格和镜像依赖。

检查 PyTorch DDP 启动参数 ​

PyTorch DDP 任务先检查 MASTER_ADDR、MASTER_PORT、WORLD_SIZE、RANK 是否被正确传给 torchrun。如果 Worker 数量、每个 Worker 的 GPU 数量和 torchrun 参数不一致，任务可能在初始化、allreduce 或第一个 batch 附近失败。

详见编写 PyTorch DDP torchrun 启动脚本。

检查 Ray Driver 和 Worker 连接 ​

Ray 任务先看 Driver 日志和 Ray Dashboard，确认 Driver 是否连接到 Ray Head，Worker 是否加入集群，以及资源请求是否与创建页配置一致。

详见提交 Ray Driver 入口命令。

检查 MPI hostfile 和进程数 ​

MPI 任务先检查 /etc/mpi/hostfile、启动命令中的 np 或进程数参数，以及镜像内 MPI 依赖。硬编码进程数可以使用，但必须与本次任务的 Worker 和进程数匹配。

详见使用 MPI hostfile 启动任务。

检查 RDMA 和 NCCL ​

多机训练通信异常或速度明显不符合预期时，检查所选规格是否支持 RoCE 或 IB，RDMA 配置是否开启，镜像是否包含 RDMA 依赖，并按需开启 NCCL 调试日志。

如果 NCCL 状态 无法连接 RAS 服务，先确认镜像中的 NCCL 版本是否支持 RAS。版本过低时，NCCL 状态不可用是预期结果，不等同于训练通信失败。

详见RDMA 网络、查看 NCCL 状态和调试 NCCL。

任务失败后定位第一条异常 ​

任务失败后，先找第一次失败的位置。最后一条日志经常是清理、重启或包装脚本输出，真正原因通常出现在更早的位置。

查看任务日志 ​

在任务运行过程中的所有日志（任务所有 Worker 的日志），均会展示在任务详情页的 任务日志 标签页，包括训练代码输出，也包括「任务容错」与「训练变慢检测」的输出。

在查看任务日志时，可组合筛选条件：

  • Worker：选择单个或全部 Worker。
  • 时间：根据时间筛选日志，精确到秒。

搜索第一条异常日志 ​

任务日志支持全文查询、短语查询和正则表达式搜索。排查失败时，优先搜索 error、exception、traceback、failed、No such file、Permission denied、CUDA、NCCL 等关键词，再按时间回到第一条异常附近。

每条日志的前缀（时间、实例名称、Worker 名称）不在日志搜索范围中。您可以通过组合筛选条件获取最准确的结果，支持先筛后搜或先搜后筛。

区分错误来源 ​

找到第一条异常后，先判断错误来自哪一层：

  • 平台环境：容错日志中出现 GPU、RDMA、I/O、通信或运行时环境检测异常。
  • 镜像环境：日志中出现 Python 包、系统包、CUDA/cuDNN/NCCL、Conda 或虚拟环境错误。
  • 训练代码：日志中出现 dataset、collator、DataLoader、forward、backward、loss 或 checkpoint 错误。
  • 启动命令：日志中出现脚本路径、工作目录、退出码、tee、sleep、上传结果或脚本继续执行相关问题。

导出任务日志 ​

在任务详情页 任务日志 页面可选择 导出日志。

信息

日志下载功能需申请开通。

  • 若您未对日志做任何筛选，则默认导出过去 30 天日志。
  • 若当前已经进行筛选或搜索，则下载筛选、搜索后的日志。

导出日志量大时比较耗时。平台将为您保存最近 5 条导出记录。

任务成功但没有产出 ​

任务显示成功只说明创建页中的启动命令正常结束，不代表模型权重、checkpoint、TensorBoard 日志或业务结果已经写到正确位置。

检查启动命令是否隐藏失败 ​

如果日志中已经出现 Python 异常、OOM、依赖缺失或 data collator 报错，但任务仍显示成功，优先检查启动命令是否在训练脚本失败后继续执行，并最终以成功状态结束。

常见风险包括 python train.py | tee train.log、训练后上传结果、失败后 sleep 保留现场、最后执行 echo done 等。详见修复任务显示成功但训练实际失败的问题。

检查输出是否写到共享存储 ​

如果任务没有报错但找不到结果，先检查启动命令、训练配置和日志中实际使用的输出路径。训练结果、checkpoint 和 TensorBoard 日志应写入挂载的共享高性能存储。

写到 Worker 本地路径的文件会随任务结束被清理。详见获取训练结果。

检查 TensorBoard 和 checkpoint 路径 ​

如果 TensorBoard 没有曲线，检查任务可视化配置中的日志目录是否与训练脚本实际写入路径一致。如果重启或重跑后找不到进度，检查 checkpoint 目录是否与训练脚本加载路径一致。

详见TensorBoard和验证 checkpoint 保存与恢复。

自动重启、恢复或重跑后进度异常 ​

平台可以重新执行任务，但不能恢复 Python 进程内存中的模型、优化器、dataloader 和随机数状态。训练代码必须自己保存并加载 checkpoint。

确认自动重启后真的加载 checkpoint ​

自动重启后，先在任务日志中查找 checkpoint 加载记录，确认恢复的 step、epoch、checkpoint 路径和输出路径符合预期。如果日志中没有加载记录，说明训练代码可能从头开始执行。

详见编写可恢复的训练代码。

避免手动重跑覆盖旧结果 ​

手动重跑会再次执行启动命令。重跑前先确认输出目录不会覆盖旧结果；建议使用 RUN_ID、任务名称或时间戳区分每次运行。

详见手动重跑训练任务。

验证 checkpoint 恢复结果 ​

恢复是否成功，需要从日志和结果中确认。至少检查恢复的 checkpoint 路径、global step、epoch、loss 曲线和输出目录是否符合预期。

详见验证 checkpoint 保存与恢复。

登录 Worker 做原地调试 ​

原地调试适合任务仍在运行、需要进入 Worker 查看文件、进程、GPU 状态或临时执行检查命令的场景。任务已失败并清理后，通常无法再登录原 Worker。

保留现场时返回原始失败结果 ​

如果需要失败后保留现场，仅在启动命令最后追加 sleep 会改变平台看到的最终结果。应先保存训练脚本的退出结果，保留现场结束后仍用原始退出结果结束任务。否则任务可能显示成功，掩盖真正失败。

详见编写可靠启动命令。

登录任务 Worker ​

在任务详情页可查看任务 Worker 的状态，可点击 刷新 获取当前最新状态。必要时可以登录 Worker 进行错误排查。

Worker 的登录入口在任务详情页 Worker 信息 中。点击登录按钮后可从网页端打开命令行界面。

信息

  • 仅在任务运行中时可登录 Worker。
  • 仅支持从网页端登录 Worker，暂不支持 SSH 远程登录任务的 Worker。

使用 atlctl 下发调试命令 ​

AIStudio 在任务 Worker 的 Web Terminal 中内置了 atlctl 调试工具，可对所有 Worker 下发检测、烧机测试或自定义调试命令。需要确认 GPU、通信或环境状态时，优先使用 atlctl 的内置检查命令。

排查镜像、RDMA、Conda 和 NCCL ​

如果前面的症状判断指向镜像、RDMA、Conda 或 NCCL，再进入对应小节。长期使用的训练环境应优先固化到镜像中，减少任务启动后的临时安装和临时调试配置。

检查系统级 CUDA/cuDNN ​

如果训练框架需要编译 CUDA 扩展，或日志提示找不到 nvcc、CUDA header、cuDNN 或相关动态库，先检查镜像是否包含系统级 CUDA/cuDNN。例如 DeepSpeed 明确依赖 nvcc。

📖 获取系统级 CUDA/cuDNN 环境
📖 NVIDIA CUDA Toolkit 与 PyTorch 安装中的 CUDA 的区别

检查 RDMA 网络 ​

如果多机训练无法使用 RDMA 网络，或训练速度明显低于预期，请检查以下项目：

  1. 前往任务详情页，检查 规格信息，查看当前所使用的规格的 训练网配置 是否为 RoCE / IB 训练网。若为其他训练网类型，请更换为支持 IB 或 RoCE 的规格。
  2. 前往任务详情页，检查 规格信息，查看当前所使用的规格的 RDMA 配置 是否为开启状态。若未开启，可选择重跑任务，并选择 改配重跑，启用 RDMA 配置。
  3. 如果问题仍然持续，请验证镜像是否支持 RDMA。可在任务运行中前往详情页，在底部找到 Worker 信息，登录 Worker 后执行以下命令，检查镜像中是否已安装 RDMA 所有依赖项。也可以用该任务镜像新建开发机后执行检查。如有缺失，可参考 RDMA 网络。
language-shell
# Ubuntu 22.04
dpkg -l infiniband-diags perftest ibverbs-providers libibumad3 libibverbs1 libnl-3-200 libnl-route-3-200 librdmacm1

修复 Conda 激活失败 ​

在训练任务中使用镜像里的 Conda 时，如果启动命令或外部脚本直接执行 conda activate，可能因 Shell 初始化文件未加载而失败。

警告

在训练场景下，为了缩小镜像体积、降低复杂性，建议制作一个最小化专用镜像。长期训练环境应尽量把固定依赖构建进镜像，而不是在启动命令中临时安装。

在镜像中初始化 Conda ​

如果可以修改镜像，建议在镜像中心以预置镜像或自定义镜像为基础，执行以下命令构建新版镜像。使用新版镜像运行训练任务即可。

language-shell
conda init --system

在启动命令中初始化 Conda ​

如果您直接在任务的 启动命令 中执行 conda activate，先确认镜像中 conda 的实际安装路径，再选择一种初始化方式。

使用 conda hook：

language-shell
# 按镜像中的实际 conda 安装路径修改
export PATH="/usr/local/miniconda3/bin:$PATH"
eval "$(conda shell.bash hook)"
conda activate your-env

使用 conda 预置的初始化脚本 conda.sh：

language-shell
# 按镜像中的实际 conda 安装路径修改
source /usr/local/miniconda3/etc/profile.d/conda.sh
conda activate your-env

如果在任务 启动命令 中执行外部 Shell 脚本，请把初始化命令写入被调用的脚本。若镜像的 .bashrc 中已存在有效 conda 配置，也可以用 interactive shell 执行：

language-shell
bash -i myscript.sh

信息

  • 平台在执行任务 启动命令 时，会加上 --login 参数。Login shell 会依次读取 /etc/profile、~/.bash_profile、~/.bash_login、~/.profile，默认不读取 ~/.bashrc。
  • 修改或制作自定义镜像时，可以考虑使用 conda init --system，将 conda 相关配置写入系统全局配置，如 /etc/profile.d/conda.sh。

调试 NCCL ​

在调试分布式通信问题时，可以临时设置 NCCL 环境变量。调试结束后再移除或收敛这些设置，避免长期影响训练性能。

确认 NCCL 版本是否支持 RAS ​

NCCL 状态 依赖 NCCL RAS。NCCL RAS 从 NCCL 2.24 开始提供；如果镜像中的 NCCL 低于 2.24，页面可能显示无法连接 RAS 服务。

登录 Worker 后，先查看训练进程实际能看到的 PyTorch、CUDA 和 NCCL 版本：

language-shell
env | grep -E 'NCCL|NV_LIBNCCL' || true

python3 - <<'PY'
import torch

print("torch:", torch.__version__)
print("cuda:", torch.version.cuda)
print("nccl:", torch.cuda.nccl.version() if torch.cuda.is_available() else None)
PY

python3 -m pip show nvidia-nccl-cu12 || true

如果输出中出现 NCCL_VERSION=2.21.5-1、libnccl2=2.21.5-1+cuda12.4 或 nvidia-nccl-cu12 版本低于 2.24，说明该镜像不满足 NCCL RAS 的版本要求。此时 NCCL 状态 不可用是预期结果；继续用任务日志、进程栈、资源监控和 checkpoint 更新时间判断训练是否真的卡住或通信失败。

如果需要使用 NCCL 状态 辅助排查，使用包含 NCCL 2.24 或更高版本的镜像。使用 pip 安装 PyTorch 时，NCCL 可能来自 nvidia-nccl-cu12 依赖；构建镜像后应再次运行上述命令确认实际版本。

打印 NCCL 日志 ​

打印 NCCL 日志：

language-shell
export NCCL_DEBUG=INFO

指定 NCCL 通信使用的网络接口。一般情况下平台已预置，只有在排查网络选择问题时再显式设置：

language-shell
export NCCL_SOCKET_IFNAME=eth0

如果自定义镜像来自 NGC 镜像，或加载了 NCCL SHARP 等插件，可临时禁用网络通信插件，帮助诊断问题或验证网络配置：

language-shell
export NCCL_NET_PLUGIN=none

信息

打印大量调试信息可能会影响 NCCL 性能。部分外部迁移镜像可能携带预设环境变量，提交正式训练前请检查并清理不需要的调试配置。

配置任务状态通知 ​

任务运行时间长、排队成本高或需要团队协作时，配置任务状态通知可以减少人工刷新任务列表的成本。无人值守训练建议同时配置告警和可恢复 checkpoint。

配置飞书机器人告警 ​

为了及时获取任务异常、运行失败等情况，建议配置飞书机器人告警通知。

联系支持前准备信息 ​

如果问题持续出现，先整理任务 ID、任务状态、第一条异常日志、容错日志、资源规格、镜像名称、启动命令和输出路径。这样支持团队可以更快判断问题来自资源、镜像、平台环境还是训练代码。

建议联系商务或售后服务的情况包括：

  • 环境检测反复发现 GPU 掉卡或硬件异常。
  • 同一资源池、同一规格持续出现无法自助判断的问题。
  • 镜像仓库、权限、资源池或账号配置导致无法提交或无法拉取镜像。
  • 需要平台侧导出更多诊断信息。