在 AIStudio 训练任务中使用 LLaMA Factory

LLaMA Factory 提供监督微调、LoRA、QLoRA 和偏好对齐等大模型后训练能力。本页面向已经熟悉 LLaMA Factory 的机器学习工程师，说明怎样把框架原生配置映射到 AIStudio 的镜像、训练任务、共享存储、输出与可选任务可视化。可复制执行的模型训练参数由独立场景教程提供。

判断 LLaMA Factory 是否适合当前任务

以下场景适合使用 LLaMA Factory：

• 使用指令—回答样本做 SFT；
• 使用 LoRA 或 QLoRA 适配模型的行为、输出格式或领域表达；
• 使用成对偏好数据做 DPO 等偏好对齐；
• 已经有 LLaMA Factory YAML，希望迁移到可重复运行的 GPU 训练任务。

如果目标只是让模型读取会持续变化的企业知识，先评估 prompt、上下文注入或 RAG 是否已经足够。微调更适合改变稳定行为，例如意图路由、固定 JSON 输出或回答风格；它不能替代知识检索，也不会自动证明模型在业务任务上变得更好。

如果任务需要模型生成多条回答、计算可验证奖励，再通过 GRPO 或 PPO 更新模型，可以改用 verl 或相应的 RLinf 场景教程。

选择 AIStudio 运行方式

不同产品负责不同阶段：

工作	推荐位置	原因
检查数据、生成清单、编写评测客户端	AICoder	CPU 工作不需要占用 GPU，并且可以读写同可用区共享存储
可重复的 LoRA、QLoRA 或其它训练	训练任务	镜像、GPU、启动命令和输出路径可以随任务配置一起记录
微调前后的稳定 API 评测	推理服务	基础模型和候选模型可以通过同一 API 合约比较
交互式排查 CUDA、显存或算子问题	短时开发机	只在确实需要逐步 GPU 调试时使用，排查结束后及时停止

运行中的 GPU 开发机会持续占用所选 GPU。不要为了编辑 YAML、检查 JSON 或汇总指标而让开发机长期运行。

推理服务在运行期间也会占用所选 GPU。它的优势是把模型运行端与 CPU 评测客户端分开，并可供多个客户端复用，而不是只在收到请求时才分配 GPU。评测窗口结束后默认停止服务；只有租户已经申请并开通相应能力时，才使用定时缩容到 0。

准备固定运行环境和输入

创建训练任务前，准备以下内容：

• 镜像：固定 LLaMA Factory、PyTorch、CUDA、Transformers、PEFT 和数据处理依赖。不要在任务获得 GPU 后再临时安装依赖。
• 模型：优先复用当前可用区中已经验证的只读公共数据或共享存储模型；记录模型文件和 tokenizer 身份。
• 数据：固定来源、许可、原始文件哈希、转换脚本、训练/验证/评测边界和处理后文件哈希。
• 配置：保存框架原生 YAML，并把模型、数据、输出和运行 ID 作为显式路径或变量传入。
• 输出：把 adapter、checkpoint、日志和数据清单写到可写共享存储；只有固定镜像包含并通过 TensorBoard 资格验证时，才同时保存事件文件。

/infini-data 是只读公共数据路径，且只在部分可用区提供。不要把 cache、adapter、checkpoint 或日志写入该目录。公共数据和用户共享存储的准备方式分别见公共数据和准备代码、数据与输出目录。

可以把固定 tag 的官方 LLaMA Factory 镜像导入当前可用区的镜像仓库，也可以构建只包含所需依赖的固定镜像。优先从本地或其它不占用 GPU 的环境使用 regctl 复制远程镜像，或在镜像中心基于现有镜像构建派生镜像；完整选择方式见选择 LLaMA Factory 镜像准备方式。只有需要交互式验证 CUDA、算子或目标 GPU 运行时，才短时使用开发机构建与验证流程。

把 LLaMA Factory YAML 映射到训练任务

建议保留一份可审计的 LLaMA Factory YAML，而不是把全部训练参数展开到创建页的长命令中。关键字段与 AIStudio 配置的对应关系如下：

LLaMA Factory 配置	AIStudio 中需要确认的内容
model_name_or_path	公共数据或共享存储在 Worker 内的实际模型路径
dataset、dataset_dir	已注册的数据集名称和挂载后的数据目录
template	与目标模型及 Thinking/Non-Thinking 行为匹配的模板
output_dir	每次运行独立的可写共享存储目录
report_to	镜像中存在并已验证 TensorBoard 时设为 tensorboard；否则设为 none，并从持久化 JSON 和日志核对指标
batch、长度、精度和 LoRA 参数	与所选 GPU 显存及教程已验证配置一致

创建任务时，“启动命令”只负责完成运行前校验，然后执行固定版本的启动脚本或 llamafactory-cli train config.yaml。启动命令应返回真实训练退出状态；不要用常驻进程掩盖训练失败。可靠入口的要求见编写可靠启动命令。

正式训练预计运行较长或使用多个 Worker 时，开启训练变慢检测。平台会分析 LLaMA Factory 的训练日志；发现 step 耗时持续增加后，到任务详情页的 容错日志 查看告警，再结合数据加载、checkpoint、存储 I/O、通信和资源监控定位原因。告警字段和排查方法见查看训练变慢检测结果。

TensorBoard 路径应与当前运行的 YAML 和输出目录一致。路径中使用变量时，先阅读 TensorBoard，确认变量来自哪里以及平台如何解析该值。若固定镜像不含 TensorBoard，请保持 report_to: none，不要开启任务可视化，也不要在任务获得 GPU 后临时安装依赖。

选择单 Worker 或多 Worker

一个 Worker 是单机路径，多个 Worker 是多机多卡路径。按实际训练规模选择：

• 单 Worker：在 分布式框架 中选择 单机。配套 Qwen3-8B LoRA 教程使用 1 个 Worker 和 1 张 GPU，适合先完成模型、数据、模板、首个 batch、adapter 保存和任务外回读。
• 多 Worker：在 分布式框架 中选择 PyTorch DDP。AIStudio 会在每个 Worker 中执行同一份启动脚本；脚本需要把平台注入的 Worker 数量和编号映射为 LLaMA Factory 的多节点启动变量。

GPU 数量本身不要求使用多 Worker。单 Worker 已经满足显存或训练时间目标时，继续使用单机路径。RDMA 也不是多 Worker 的固定前提；先按所选规格完成有界通信和训练验证，再决定是否开启。

使用 LLaMA Factory 启动多 Worker 训练

LLaMA Factory 0.9.5 的官方启动器读取 FORCE_TORCHRUN、NNODES、NODE_RANK、NPROC_PER_NODE、MASTER_ADDR 和 MASTER_PORT。AIStudio 的 PyTorch DDP 任务则注入 WORLD_SIZE（Worker 数量）、RANK（Worker 编号）、MASTER_ADDR 和 MASTER_PORT。下面的启动脚本完成两组变量之间的映射，并让训练命令的退出状态直接成为任务结果：

#!/usr/bin/env bash
set -euo pipefail

CONFIG_PATH=${CONFIG_PATH:?Set CONFIG_PATH to a YAML file on shared storage}
RUN_ROOT=${RUN_ROOT:?Set RUN_ROOT to a unique directory on shared storage}

PLATFORM_NNODES=${WORLD_SIZE:?AIStudio WORLD_SIZE is required}
PLATFORM_NODE_RANK=${RANK:?AIStudio RANK is required}
PLATFORM_MASTER_ADDR=${MASTER_ADDR:?AIStudio MASTER_ADDR is required}
PLATFORM_MASTER_PORT=${MASTER_PORT:-29500}
GPUS_PER_NODE=$(nvidia-smi --query-gpu=index --format=csv,noheader | wc -l | tr -d ' ')

test -r "$CONFIG_PATH"
test "$GPUS_PER_NODE" -gt 0
mkdir -p "$RUN_ROOT/nodes/node-$PLATFORM_NODE_RANK"

export FORCE_TORCHRUN=1
export NNODES="$PLATFORM_NNODES"
export NODE_RANK="$PLATFORM_NODE_RANK"
export NPROC_PER_NODE="$GPUS_PER_NODE"
export MASTER_ADDR="$PLATFORM_MASTER_ADDR"
export MASTER_PORT="$PLATFORM_MASTER_PORT"

llamafactory-cli train "$CONFIG_PATH" \
  > >(tee -i "$RUN_ROOT/nodes/node-$PLATFORM_NODE_RANK/train.log") 2>&1

把启动脚本和 YAML 放在所有 Worker 都能读取的共享存储中。YAML 中的 output_dir 也应指向本次运行独占的共享存储目录。创建任务时，把 CONFIG_PATH 和 RUN_ROOT 设置为实际路径；同一次运行的所有 Worker 使用相同值。

首次运行时使用少量 step，并从日志和共享存储依次确认：

1. 每个 Worker 的 node rank 不同，num nodes 等于创建页中的 Worker 数量；
2. PyTorch 进程的 world size 等于 Worker 数量乘以每个 Worker 的 GPU 数量；
3. 所有 rank 都进入训练，至少完成一个 optimizer step；
4. adapter、checkpoint 和每个 Worker 的日志写入共享存储；
5. 启动脚本末尾没有 sleep、|| true 或其它常驻逻辑，训练命令的真实退出码会返回给任务。

LLaMA Factory 的变量定义见官方多节点训练示例。AIStudio 的 Worker 变量和通用 torchrun 规则见编写 PyTorch DDP torchrun 启动脚本。

运行一个完整的 Qwen3-8B LoRA 场景

要在 AIStudio 中完成一次单卡训练，请继续阅读在 AIStudio 训练任务中使用 LLaMA Factory 微调 Qwen3-8B。该教程提供模型、BANKING77 数据、固定镜像、单 Worker 任务和共享存储输出的完整步骤：

• 按照教程配置完成 100 步训练；
• 从任务外回读 checkpoint、adapter、指标和日志；
• 在训练进程退出后，用新的 Python 进程重新加载 adapter。

这条路径只证明训练与产物链路可用，不依赖微调前评估或 adapter A/B，也不声称模型效果已经提升。业务效果评测和推理服务部署应使用各自独立的数据、资源和验收条件；其中任一路径未完成，不应阻断这条训练教程。

任务结束后，通过获取训练结果从共享存储核对 adapter、checkpoint、日志和清单。训练任务显示“成功”只说明入口命令正常退出，不能代替模型效果评测或 adapter 推理验证。

排查迁移问题

• 镜像中找不到框架入口：确认实际镜像摘要、工作目录和 llamafactory-cli version，不要假设不同 tag 的目录结构相同。
• 第一个 batch 前失败：检查模型架构、Transformers 版本、模板、数据字段、最大长度、精度和 LoRA target。
• 数据集加载失败：确认 dataset_info.json 中的名称与 YAML 一致，并从每个 Worker 读取实际挂载路径。
• adapter 没有持久化：确认 output_dir 位于可写共享存储，且每次运行使用新的输出目录。
• TensorBoard 没有曲线：确认 report_to、镜像依赖、事件文件位置和创建页 TensorBoard 路径指向同一次运行。
• 多 Worker 初始化超时：先确认单 Worker 路径已经通过，再核对 Worker 数、平台注入变量、每节点 GPU 数和网络配置。
• 任务状态与训练结果不一致：检查启动脚本是否保留训练进程的非零退出码，并核对任务外读取到的完成标记和必要产物。