选择 LLaMA-Factory 镜像准备方式

LLaMA-Factory 可以通过官方镜像快速启动，也可以在 AIStudio 开发机中构建成团队自己的训练镜像。先选择镜像准备方式，再创建开发机或训练任务。

官方镜像适合快速试跑和验证 LLaMA-Factory 是否可用；正式训练、分布式训练、DeepSpeed、FlashAttention、固定数据集配置和可复现实验，建议使用在开发机中构建 LLaMA-Factory 训练镜像。

使用官方镜像快速试跑

如果只是想打开 WebUI、确认框架可用，或用官方示例做小规模实验，可以先导入 LLaMA-Factory 官方镜像。先在 LLaMA Factory Docker Hub 镜像列表中选择固定 tag，不要在正式训练中依赖 latest。

使用 LLaMA-Factory 官方镜像有以下几个关键步骤。

1. 拉取固定 tag 的官方镜像。

   docker pull hiyouga/llamafactory:<tag>

   如果本地或开发机无法访问 Docker Hub，先解决网络访问问题，再继续导入。

2. 推送到租户镜像仓库。 由于租户可能在多个可用区均有独立的镜像仓库，为确保后续任务可使用该镜像，请将镜像推送到目标可用区的租户镜像仓库。

   • 如果从本地设备执行 docker push，请在镜像中心选择目标可用区，复制该可用区 Registry 公网访问地址和登录凭证。详见导入或跨可用区迁移镜像。
   • 如果从 AIStudio 开发机内部推送到当前开发机所在可用区，可以使用平台内部 Registry 域名，根路径格式为 cr.infini-ai.com/<租户ID>/。请通过已开启 Docker 容器 功能的开发机操作；登录方式、仓库根路径和推送方法参见在开发机中访问镜像仓库。
   • 如果从 AIStudio 开发机推送到其他可用区，请使用目标可用区 Registry 公网访问地址和登录凭证。平台内部 Registry 域名不能用于选择其他可用区。详见选择 Registry 访问地址和导入或跨可用区迁移镜像。

3. 按需基于官方镜像安装依赖。 如果只缺少 TensorBoard、少量 Python 包、系统工具或 pip 源配置，可以在镜像中心选择基于现有镜像构建自定义镜像，基础镜像选择刚导入的官方镜像，再用非交互式命令安装依赖。

   例如：

   set -eux
   
   python -m pip install --no-cache-dir tensorboard

   如需安装系统包，也可以使用 apt-get：

   set -eux
   
   apt-get update
   DEBIAN_FRONTEND=noninteractive apt-get install -y curl jq
   python -m pip install --no-cache-dir tensorboard

4. 在开发机中检查镜像能否使用 GPU。 先完成下文的 CUDA、PyTorch、NCCL、FlashAttention 和 TensorBoard 检查，再把镜像用于训练任务。

导入后，如果镜像没有出现在开发机、训练任务或推理服务的镜像列表中，先检查镜像的可用范围和可用区配置。镜像是否能被某类服务选择，取决于镜像中心中的可用范围配置，而不是镜像名称。

检查官方镜像是否适合训练

官方镜像能运行 LLaMA-Factory，不等于它一定适合当前 AIStudio 训练任务。提交任务前，至少检查 CUDA、PyTorch、NCCL、FlashAttention 和 TensorBoard。

警告

GPU 驱动来自平台节点，不能在镜像内修改。镜像中的 CUDA Toolkit、PyTorch CUDA wheel 和 NCCL 需要与节点驱动兼容。不要只根据镜像名称判断可用性；先运行最小检查。

在开发机中检查镜像时，可以使用命名容器和 docker logs 查看输出：

IMAGE=cr.infini-ai.com/YOUR_TENANT/llamafactory:YOUR_TAG

docker rm -f llamafactory-check 2>/dev/null || true

docker run --name llamafactory-check --gpus all "$IMAGE" \
  /bin/bash -lc '
    set -e
    echo "=== nvidia-smi ==="
    nvidia-smi

    echo "=== cuda toolkit ==="
    nvcc --version || true

    echo "=== torch ==="
    python - <<'"'"'PY'"'"'
import torch
print("torch:", torch.__version__)
print("torch cuda:", torch.version.cuda)
print("cuda available:", torch.cuda.is_available())
if torch.cuda.is_available():
    print("device:", torch.cuda.get_device_name(0))
    print("capability:", torch.cuda.get_device_capability(0))
    print("nccl:", torch.cuda.nccl.version())
    x = torch.randn(1024, 1024, device="cuda", dtype=torch.float16)
    y = x @ x
    torch.cuda.synchronize()
    print("matmul ok:", y.float().mean().item())
PY

    echo "=== optional packages ==="
    python -c "import flash_attn; print(\"flash_attn:\", flash_attn.__version__)" || true
    python -m pip show tensorboard || true
    llamafactory-cli version
  '

docker logs llamafactory-check
docker inspect llamafactory-check --format 'ExitCode={{.State.ExitCode}} Error={{.State.Error}}'
docker rm llamafactory-check

如果 docker run 的实时输出没有显示，先看 docker logs。这是开发机 Docker 容器功能中的已知现象，见在开发机中使用 Dockerfile 构建镜像。

判断 CUDA 和驱动是否匹配

先区分两个版本：nvidia-smi 显示的是平台节点上的 GPU 驱动能力，torch.version.cuda 和 nvcc --version 显示的是镜像内的 CUDA 运行时或 Toolkit。

官方 CUDA 镜像通常使用带 devel 的基础镜像，镜像内可能包含系统级 CUDA Toolkit 和 nvcc。如果 tag 中出现 cu124 这类标记，通常表示镜像内 PyTorch/CUDA 组合面向 CUDA 12.4；实际版本以所选 tag、torch.version.cuda 和 nvcc --version 为准。

选择镜像时按以下顺序处理：

1. 优先选择 CUDA Toolkit 版本不高于当前 GPU 驱动原生支持上限的镜像。
2. 如果 nvidia-smi 显示的 CUDA Version 低于镜像内 CUDA Toolkit 版本，但仍希望依赖 CUDA 12.x 兼容行为运行，先完成 PyTorch GPU 矩阵计算、NCCL 版本和可选 FlashAttention kernel 检查。
3. 如果检查失败，换用与平台驱动更匹配的镜像 tag，或改为在开发机中构建自己的训练镜像。

例如，某些官方镜像 tag 可能对应 CUDA 12.4、PyTorch 2.6 和 FlashAttention 2.7.x 这类组合。CUDA 12.4 对 GPU 驱动有版本要求，Linux 原生最低驱动通常从 550.54.14 起；实际要求以 CUDA Toolkit Release Notes和 CUDA Compatibility为准。如果平台节点驱动低于该组合的原生要求，即使镜像能拉取成功，也可能在 CUDA 初始化、通信库或自定义 kernel 处失败。

检查 NCCL 和诊断能力

NCCL 通常随 PyTorch/CUDA 依赖组合进入镜像。NCCL 版本会影响 AIStudio进程栈采集中的 NCCL 状态 子页，也会影响容器内 ncclras 等 NCCL RAS 查询能力。

如果镜像中的 NCCL 低于 2.24，训练仍可能正常运行，但平台无法读取 NCCL RAS 状态。遇到 NCCL 状态 不可用时，不要直接判断为训练通信失败；继续看训练日志、进程栈报告和资源监控。

提交训练前，可以用以下命令确认 NCCL 版本：

python - <<'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

如果训练需要更好的 NCCL 诊断能力，最佳做法是在镜像构建阶段选择包含 NCCL 2.24 或更高版本的 PyTorch/CUDA 组合，然后做最小分布式通信检查。不要在已有 PyTorch 环境里临时替换 NCCL 动态库来“升级 NCCL”，以免引入新的动态库或 ABI 不匹配。

补齐 TensorBoard 和数据配置

LLaMA-Factory 支持把训练指标写到 TensorBoard，但官方镜像不一定预装 TensorBoard。若训练命令使用 report_to=tensorboard 或 --report_to tensorboard，先检查：

python -m pip show tensorboard
python -c "import tensorboard; print(tensorboard.__version__)"

临时试跑可以在容器内安装 TensorBoard；正式训练建议把 TensorBoard 写入镜像，避免任务拿到 GPU 后才因为网络或依赖版本失败。

如果训练使用自定义数据集，还要确认 LLaMA-Factory 的数据集配置已经随镜像或共享存储准备好。不要只把数据文件放到共享存储里，还要让训练命令中的 dataset 名称能被 LLaMA-Factory 配置解析到。

基于官方镜像做少量改造

如果官方镜像基本满足要求，只缺少 TensorBoard、少量 Python 包或团队固定配置，可以基于官方镜像构建一个派生镜像：

FROM hiyouga/llamafactory:<tag>

RUN python -m pip install --no-cache-dir tensorboard

这类派生镜像适合小改动。遇到以下情况时，直接改用开发机构建流程：

• 需要固定 LLaMA-Factory 源码版本。
• 需要修改或加入数据集配置文件。
• 需要重新编译 FlashAttention、DeepSpeed CUDA op、Apex 或自定义 CUDA kernel。
• 需要验证多机多卡训练、NCCL 诊断或完整训练启动脚本。

在开发机中构建正式训练镜像

正式训练建议在开发机中先克隆源码、固定版本、准备数据集配置并完成最小验证，再把源码和依赖固化进镜像。这样可以把网络、依赖、CUDA、NCCL 和 FlashAttention 问题提前暴露在构建和检查阶段，而不是等训练任务拿到 GPU 后才失败。

具体步骤见在开发机中构建 LLaMA-Factory 训练镜像。

使用镜像运行训练任务

镜像准备好后，再创建训练任务。训练任务中的启动命令、共享存储、TensorBoard、单机多卡和多机多卡配置，见使用 LLaMA-Factory 进行训练。