TRL documentation
使用作业进行训练
使用作业进行训练
Hugging Face Jobs 在 Hugging Face 的 GPU 上运行您的训练任务。您可以为每次运行选择硬件,并仅按实际运行的秒数付费。使用 --push_to_hub 后,训练完成的模型将在结束时上传到 Hub。
在本指南中,您将学习如何:
- 通过一条命令启动 TRL 训练脚本
- 跟踪一次运行并查看其损失曲线
- 在文件中设置硬件配置,然后运行你自己的脚本
- 保存检查点并恢复中断的运行
- 在多个 GPU 上训练
有关 Jobs 的一般工作原理(包括硬件和定价),请参阅 Jobs 文档。
要求
- 拥有正数信用额度的 Hugging Face 账户。任务按使用量计费:您只需为实际使用的秒数付费。
- 已登录 Hugging Face Hub(
hf auth login)
首次运行
此命令使用 TRL SFT 脚本在 Capybara 聊天数据集上对 Qwen2-0.5B-Instruct 进行微调,然后将模型推送到您的账户:
hf jobs uv run \
--flavor a10g-small \
--timeout 30m \
--secrets HF_TOKEN \
-- \
https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--max_steps 100 \
--output_dir Qwen2-0.5B-SFT \
--push_to_hubfrom huggingface_hub import run_uv_job
run_uv_job(
"https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py",
flavor="a10g-small",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
script_args=[
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--max_steps", "100",
"--output_dir", "Qwen2-0.5B-SFT",
"--push_to_hub",
],
)在 a10g-small 上运行只需几分钟,成本远低于 1 美元。-- 之前的选项用于配置 Job:硬件、时间限制以及用于推送模型的 token。--secrets HF_TOKEN 会发送你登录时使用的 token。在 Python 中,直接传递 token 本身。脚本 URL 之后的参数会传递给脚本。hf jobs uv run 使用 uv 运行 Python 脚本。sft.py 在文件顶部的头部列出了其依赖项,因此 Job 会在脚本启动前安装 TRL。当脚本退出时,Job 停止,计费也随之停止。
--max_steps 100 用于缩短首次运行。完整运行时请移除该参数:三个 epoch(脚本的默认值)在 a10g-small 上需要数小时,因此请相应调高 --timeout,例如 --timeout 3h。当运行达到超时时间时,Jobs 会停止该任务,默认超时时间为 30 分钟。使用 a100-large 等更大的 GPU 可以更快完成。有关实例规格及其价格,请参阅 硬件。
跟踪运行
hf jobs uv run 会流式传输日志,并在运行结束前保持终端打开。按 Ctrl+C 仅停止日志流:Job 会继续运行。添加 --detach 可立即获取 Job ID,然后:
hf jobs logs -f <job_id> # stream the logs
hf jobs ps # list your running Jobs
hf jobs inspect <job_id> # status, and the error message if it failed
hf jobs cancel <job_id> # stop it有关更多信息,请参阅 管理任务。
对于损失曲线,TRL 会将日志记录到 Trackio。在 -- 之前添加 --env TRACKIO_SPACE_ID=<your-username>/trackio 以指定用于仪表板的 Space 名称,并在脚本 URL 之后添加 --report_to trackio。如果 Space 和用于存储指标的 bucket 不存在,Trackio 会自动创建它们。两者默认均为公开状态。Transformers 支持的其他跟踪器也可以使用。对于 Weights & Biases,请在 -- 之前添加 --with wandb --secrets WANDB_API_KEY,并在脚本 URL 之后添加 --report_to wandb。--secrets WANDB_API_KEY 会从本地环境中读取 WANDB_API_KEY 的值。有关传递这些变量的其他方法,请参阅 环境变量和密钥。
运行你自己的脚本
将训练代码编写在一个 Python 文件中(例如 train.py)。在文件顶部以 脚本头部 的形式列出其依赖项,方式与 TRL 脚本相同。任务会在脚本启动前安装这些依赖项:
# /// script
# dependencies = [
# "trl",
# "peft",
# ]
# ///
from datasets import load_dataset
from peft import LoraConfig
from trl import SFTConfig, SFTTrainer
dataset = load_dataset("trl-lib/Capybara", split="train")
trainer = SFTTrainer(
model="Qwen/Qwen2.5-0.5B",
train_dataset=dataset,
peft_config=LoraConfig(),
args=SFTConfig(output_dir="Qwen2.5-0.5B-SFT", max_steps=100),
)
trainer.train()
trainer.push_to_hub()然后使用 hf jobs CLI 或 Python API 启动它:
hf jobs uv run \
--flavor a10g-small \
--timeout 30m \
--secrets HF_TOKEN \
train.pyfrom huggingface_hub import run_uv_job
run_uv_job(
"train.py",
flavor="a10g-small",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
)对于没有头部的脚本,请在启动时改用 --with 列出依赖项,每个包使用一次:--with trl --with peft(在 Python 中为 dependencies=["trl", "peft"])。该脚本也可以是 URL,例如 GitHub raw 链接、Gist 或公共 Hub 仓库中的文件。
启动设置也可以放在脚本中。头部中的 [tool.hf-jobs] 表格用于设置硬件、超时和密钥:
# /// script
# dependencies = [
# "trl",
# "peft",
# ]
#
# [tool.hf-jobs]
# flavor = "a10g-small"
# timeout = "30m"
# secrets = ["HF_TOKEN"]
# ///hf jobs uv run train.py 因此无需任何选项,且您传入的选项仍会覆盖脚本中的设置。脚本包含了运行所需的一切,因此您可以分享它,或稍后返回使用,而无需记住它需要哪种 GPU 和超时时间。hf jobs uv run --dry-run train.py 会显示解析后的设置,并标记出来自脚本的值。该表格仅由 hf CLI 读取:run_uv_job() 会忽略它。请参阅 在脚本中定义启动配置。
运行任意 TRL 脚本
相同的模式适用于每个 TRL 训练器脚本(SFT、DPO、GRPO、奖励建模等)以及 示例索引 中的独立 .py 示例。每个脚本都在其头部声明依赖项。需要读取同目录下其他文件的示例,必须将其所在文件夹挂载到 Job 中。请参阅 本地目录。仅限 Notebook 的示例无法通过此方式提交。脚本参数与在本地运行该脚本时相同。
保留检查点
Job 的磁盘会在 Job 结束时被删除,包括其达到超时时间或运行失败的情况。对于长时间运行的任务,请将检查点保存在 Job 外部,以确保其在 Job 结束后仍然存在。
最简单的方法是在每个检查点保存时,将其推送到输出模型仓库:
hf jobs uv run \
--flavor a10g-small \
--timeout 3h \
--secrets HF_TOKEN \
-- \
https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--output_dir Qwen2-0.5B-SFT \
--push_to_hub \
--save_steps 500 \
--hub_strategy checkpointfrom huggingface_hub import run_uv_job
run_uv_job(
"https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py",
flavor="a10g-small",
timeout="3h",
secrets={"HF_TOKEN": "hf_..."},
script_args=[
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "Qwen2-0.5B-SFT",
"--push_to_hub",
"--save_steps", "500",
"--hub_strategy", "checkpoint",
],
)使用 --hub_strategy checkpoint 时,包含优化器状态在内的最新检查点会保存在仓库的 last-checkpoint 文件夹中。若要继续中断的运行,请将仓库挂载到新的 Job 中,并从该文件夹恢复:在 -- 之前添加 --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous,并在脚本 URL 之后添加 --resume_from_checkpoint /previous/last-checkpoint,然后启动相同的命令。
若要将多个检查点保存在模型仓库之外,请改为将其写入存储桶。使用hf buckets create <your-username>/checkpoints --private创建一个,将其挂载到 Job 中,并将--output_dir指向该存储桶:
hf jobs uv run \
--flavor a10g-small \
--timeout 3h \
--secrets HF_TOKEN \
--volume hf://buckets/<your-username>/checkpoints:/checkpoints \
-- \
https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--output_dir /checkpoints/Qwen2-0.5B-SFT \
--save_steps 500from huggingface_hub import Volume, run_uv_job
run_uv_job(
"https://raw.githubusercontent.com/huggingface/trl/refs/heads/main/trl/scripts/sft.py",
flavor="a10g-small",
timeout="3h",
secrets={"HF_TOKEN": "hf_..."},
volumes=[Volume(type="bucket", source="<your-username>/checkpoints", mount_path="/checkpoints")],
script_args=[
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "/checkpoints/Qwen2-0.5B-SFT",
"--save_steps", "500",
],
)若要继续中断的运行,请再次运行相同的命令,并添加 --resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step>。有关更多信息,请参阅 边运行边写入存储桶;有关挂载选项,请参阅 Volumes。
每个检查点都包含模型和优化器状态,其大小是模型本身的数倍。添加
--save_total_limit 2以仅保留最新的检查点。如果同时传入--push_to_hub,请设置--hub_model_id,否则仓库名称将取自输出路径的最后部分。
多个 GPU
使用配备多块 GPU 的 flavor 可以缩短运行时间。为此,请使用 hf jobs run,它会在 Docker 镜像中运行命令,而不是运行脚本,并使用 huggingface/trl 镜像,该镜像已安装 TRL 和 Accelerate。然后为每块 GPU 启动一个进程。此方法适用于 TRL 脚本以及您自己的训练代码。
加速 TRL 脚本
在本指南开头运行的 SFT 训练,使用四块 GPU:
hf jobs run \
--flavor l4x4 \
--timeout 30m \
--secrets HF_TOKEN \
huggingface/trl \
-- \
trl sft --nproc_per_node 4 \
--model_name_or_path Qwen/Qwen2-0.5B-Instruct \
--dataset_name trl-lib/Capybara \
--max_steps 100 \
--output_dir Qwen2-0.5B-SFT \
--push_to_hubfrom huggingface_hub import run_job
run_job(
image="huggingface/trl",
command=[
"trl", "sft", "--nproc_per_node", "4",
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--max_steps", "100",
"--output_dir", "Qwen2-0.5B-SFT",
"--push_to_hub",
],
flavor="l4x4",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
)trl CLI 会将 --nproc_per_node 传递给 torchrun。请将其设置为该 flavor 中的 GPU 数量,此处为四块 L4。每个进程处理自己的批次,因此有效批次大小是单 GPU 运行的四倍。此运行需要几分钟。如果不使用 --max_steps,完整的三个 epoch 大约需要一小时,因此请提高 --timeout,例如设置为 2h。
您自己的脚本
您并不局限于使用 TRL 脚本。只要镜像中包含所需的软件包,任何能在本地通过 torchrun 运行的训练代码,在 Jobs 上也能以相同的方式运行。例如,将包含自定义奖励函数的 GRPO 脚本保存为 train_grpo.py 并放入一个文件夹中,然后将该文件夹挂载到 Job。Jobs 会将该文件夹上传到私有存储桶,并以只读方式挂载:
hf jobs run \
--flavor l4x4 \
--timeout 30m \
--secrets HF_TOKEN \
--volume ./my-project:/code \
huggingface/trl \
-- \
torchrun --nproc_per_node 4 /code/train_grpo.pyfrom huggingface_hub import run_job, sync_job_volume
code = sync_job_volume("./my-project", "/code")
run_job(
image="huggingface/trl",
command=["torchrun", "--nproc_per_node", "4", "/code/train_grpo.py"],
flavor="l4x4",
timeout="30m",
secrets={"HF_TOKEN": "hf_..."},
volumes=[code],
)该脚本在已安装 TRL 的镜像中运行,因此无需脚本头部。GRPOTrainer 默认使用 transformers 生成补全,因此此操作在单个 Job 中运行,无需 vLLM 服务器。如需更快的生成速度,请参阅 vLLM Integration。下一节将说明 hf jobs run 如何使用该镜像。
Docker 镜像
Jobs 使用 uv 运行您的脚本,该工具会将 # /// script 头部中声明的依赖项安装到一个全新的环境中。因此,您的脚本导入的 TRL 来自该头部,而非来自镜像,上述 hf jobs uv run 示例也完全不需要 --image。
预装了 TRL 的 Docker 镜像可在 huggingface/trl 获取。将其传递给 hf jobs uv run 可为作业提供该镜像的系统层,例如 CUDA 工具链,这对于需要针对其进行编译的依赖项至关重要:
hf jobs uv run \
--flavor a100-large \
--secrets HF_TOKEN \
--image huggingface/trl \
train.pyfrom huggingface_hub import run_uv_job
run_uv_job(
"train.py",
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
image="huggingface/trl",
)要运行镜像中已安装的 TRL,请改用 hf jobs run。它直接在镜像中运行命令,无需解析脚本头,因此执行的是镜像自带的 TRL。-- 用于将命令与 Jobs 选项分隔开,当命令本身带有选项时,这是必需的:
hf jobs run \
--flavor a100-large \
--secrets HF_TOKEN \
huggingface/trl \
-- \
trl sft --model_name_or_path Qwen/Qwen2-0.5B-Instruct --dataset_name trl-lib/Capybara --output_dir Qwen2-0.5B-SFTfrom huggingface_hub import run_job
run_job(
image="huggingface/trl",
command=[
"trl", "sft",
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "Qwen2-0.5B-SFT",
],
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
)该镜像以三种类型的标签发布:
| 标签 | 目录 |
|---|---|
X.Y.Z | 该版本发布时构建的 TRL 对应版本 |
latest | 最新版本 |
dev | 在每次合并时重新构建的 main 分支 |
使用 dev 来运行开发版本,这对于尝试已合并到 main 但尚未发布的修复非常有用:
hf jobs run \
--flavor a100-large \
--secrets HF_TOKEN \
huggingface/trl:dev \
-- \
trl sft --model_name_or_path Qwen/Qwen2-0.5B-Instruct --dataset_name trl-lib/Capybara --output_dir Qwen2-0.5B-SFTfrom huggingface_hub import run_job
run_job(
image="huggingface/trl:dev",
command=[
"trl", "sft",
"--model_name_or_path", "Qwen/Qwen2-0.5B-Instruct",
"--dataset_name", "trl-lib/Capybara",
"--output_dir", "Qwen2-0.5B-SFT",
],
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
)标签仅决定镜像中安装了哪些内容,因此它们对 hf jobs run 很重要。使用 hf jobs uv run 时,版本来自脚本头部,标签不会影响导入的 TRL 版本。
将两者结合,使 uv 解析脚本头部,同时部分导入仍来自镜像,需要额外的标志。有关该形式及其所需的路径,请参阅 复用镜像中的包并使用 UV 添加依赖项。
Jobs 运行在来自 Hugging Face Spaces 或 Docker Hub 的 Docker 镜像上,因此您也可以指定任何自定义镜像:
hf jobs uv run \
--flavor a100-large \
--secrets HF_TOKEN \
--image <docker-image> \
train.pyfrom huggingface_hub import run_uv_job
run_uv_job(
"train.py",
flavor="a100-large",
secrets={"HF_TOKEN": "hf_..."},
image="<docker-image>",
)Update on GitHubTRL Jobs 封装器可在 Jobs 上以预设配置启动 TRL 脚本,例如针对某些模型,
trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara。