TRL documentation

使用作业进行训练

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

使用作业进行训练

model badge

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 进行微调,然后将模型推送到您的账户:

bash
python
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_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 启动它:

bash
python
hf jobs uv run \
    --flavor a10g-small \
    --timeout 30m \
    --secrets HF_TOKEN \
    train.py

对于没有头部的脚本,请在启动时改用 --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 结束后仍然存在。

最简单的方法是在每个检查点保存时,将其推送到输出模型仓库:

bash
python
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 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指向该存储桶:

bash
python
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 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:

bash
python
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_hub

trl CLI 会将 --nproc_per_node 传递给 torchrun。请将其设置为该 flavor 中的 GPU 数量,此处为四块 L4。每个进程处理自己的批次,因此有效批次大小是单 GPU 运行的四倍。此运行需要几分钟。如果不使用 --max_steps,完整的三个 epoch 大约需要一小时,因此请提高 --timeout,例如设置为 2h。

您自己的脚本

您并不局限于使用 TRL 脚本。只要镜像中包含所需的软件包,任何能在本地通过 torchrun 运行的训练代码,在 Jobs 上也能以相同的方式运行。例如,将包含自定义奖励函数的 GRPO 脚本保存为 train_grpo.py 并放入一个文件夹中,然后将该文件夹挂载到 Job。Jobs 会将该文件夹上传到私有存储桶,并以只读方式挂载:

bash
python
hf jobs run \
    --flavor l4x4 \
    --timeout 30m \
    --secrets HF_TOKEN \
    --volume ./my-project:/code \
    huggingface/trl \
    -- \
    torchrun --nproc_per_node 4 /code/train_grpo.py

该脚本在已安装 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 工具链,这对于需要针对其进行编译的依赖项至关重要:

bash
python
hf jobs uv run \
    --flavor a100-large \
    --secrets HF_TOKEN \
    --image huggingface/trl \
    train.py

要运行镜像中已安装的 TRL,请改用 hf jobs run。它直接在镜像中运行命令,无需解析脚本头,因此执行的是镜像自带的 TRL。-- 用于将命令与 Jobs 选项分隔开,当命令本身带有选项时,这是必需的:

bash
python
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-SFT

该镜像以三种类型的标签发布:

标签目录
X.Y.Z该版本发布时构建的 TRL 对应版本
latest最新版本
dev在每次合并时重新构建的 main 分支

使用 dev 来运行开发版本,这对于尝试已合并到 main 但尚未发布的修复非常有用:

bash
python
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-SFT

标签仅决定镜像中安装了哪些内容,因此它们对 hf jobs run 很重要。使用 hf jobs uv run 时,版本来自脚本头部,标签不会影响导入的 TRL 版本。

将两者结合,使 uv 解析脚本头部,同时部分导入仍来自镜像,需要额外的标志。有关该形式及其所需的路径,请参阅 复用镜像中的包并使用 UV 添加依赖项。

Jobs 运行在来自 Hugging Face Spaces 或 Docker Hub 的 Docker 镜像上,因此您也可以指定任何自定义镜像:

bash
python
hf jobs uv run \
    --flavor a100-large \
    --secrets HF_TOKEN \
    --image <docker-image> \
    train.py

TRL Jobs 封装器可在 Jobs 上以预设配置启动 TRL 脚本,例如针对某些模型,trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara。

Update on GitHub