Hub documentation

在任务上训练模型

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

在任务上训练模型

本页介绍如何在 Jobs 上使用库的脚本或您自己的脚本对模型进行微调和训练。每个示例都限制为短时间的运行，在单张 A10G 上几分钟内即可完成，计算成本约为 0.10 美元。Job 在 Hugging Face 的机器上运行，因此即使您关闭终端或笔记本电脑，它也会继续运行。如果您之前没有运行过 Job，快速入门涵盖了 CLI 的安装、登录以及 Job 所需的积分。

首次运行

该命令在 2,000 张 Food-101 图像上微调一个图像分类器，并将其推送到 Hub 上的您的命名空间，大约需要三分钟：

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/transformers/main/examples/pytorch/image-classification/run_image_classification.py \
  --model_name_or_path google/vit-base-patch16-224-in21k \
  --dataset_name ethz/food101 \
  --do_train --do_eval \
  --remove_unused_columns False \
  --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 \
  --output_dir vit-food101 \
  --push_to_hub

Transformers 部分涵盖了完整的运行流程以及其他示例脚本。

训练任务是如何构建的

上述命令包含五个部分，本页面上的每条命令都具有相同的结构。

运行内容。 可以是使用 hf jobs uv run 启动的 uv 脚本：一个在顶部附近的注释块中声明其依赖项的 Python 脚本（# /// script，即 PEP 723 格式），uv 会将其安装到一个全新的环境中。TRL 部分展示了一个示例。也可以是使用 hf jobs run 启动的库的 Docker 镜像，它使用镜像中已安装的库。如果库可以通过 pip 安装，请从 uv 脚本开始。如果库附带了包含编译依赖项的镜像，或其文档建议使用镜像，则使用镜像。有关权衡，请参阅使用 Docker 镜像。
一个令牌。任务默认不会获得 Hugging Face 令牌。-s HF_TOKEN 会将您的令牌作为机密转发，以便运行可以推送其模型并读取受限制或私有的输入。其他机密也以相同方式传输，例如 -s WANDB_API_KEY。
硬件与时间。 --flavor 用于选择 GPU。--timeout 用于设置时间限制，默认值为 30 分钟。如果运行达到超时时间，则会被停止，因此请将 --timeout 设置为高于预期运行时间。请参阅硬件类型和超时。
A -- between the hf flags and the script. Flags before -- are for hf jobs. After it come the script path and the script’s own arguments. Without it, a script argument that shares a name with an hf flag, such as --timeout or --token, is taken by hf. In the image form, what follows -- is the command to run in the container.
输出位置。 以下每个库都可以将训练完成的模型推送到 Hub 仓库，且每个示例都展示了相应的选项。对于 Transformers 和 TRL，仓库名称取自 --output_dir。运行过程中还可以将结果写入已挂载的存储桶，使用 -v 将其挂载到容器中。参见运行结束后。

您自己的训练代码。 使用最简洁且适用的形式：

一个文件。在脚本头部声明其依赖项，然后运行 hf jobs uv run train.py。TRL 部分展示了一个示例。
包含本地导入以及 pyproject.toml 或配置文件的项目文件夹。hf jobs uv run 仅上传脚本文件，因此请改为挂载该文件夹。由于挂载是只读的，该命令会将项目复制到可写目录中，并在那里运行，与本地运行方式相同：
```
hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./my-project:/code ghcr.io/astral-sh/uv:python3.12-bookworm -- \
  bash -c "cp -r /code /tmp/project && cd /tmp/project && uv run train.py --config configs/run.yaml"
```
uv run 会从 pyproject.toml 或脚本头部安装依赖项，本地导入和相对路径可保持不变。请参阅本地目录。
需要系统软件包或 CUDA 工具包的代码。 构建一次镜像，然后使用 hf jobs run 运行。请参阅使用 Docker Space 构建自己的镜像。

脚本还可以在脚本头部的 [tool.hf-jobs] 表中携带自己的启动配置，如 TRL 部分所示。请参阅在脚本中定义启动配置。相同的命令也可从 Python 中以 run_uv_job() 和 run_job() 的形式使用，相关内容见配置。

长时间运行前的检查

在移除限制之前，进行几项检查可以避免浪费一次运行。

先进行冒烟测试。 参照本页示例，在小规格上运行该命令并设置步数上限。这可以验证依赖项安装、数据加载、模型适配以及推送操作均正常。随后移除上限，启动完整运行。
检查数据是否适配。每种规格都有固定的磁盘容量，列在定价与计费页面的 Ephemeral Storage 列中。模型权重、数据集和保存的检查点共享该磁盘空间。如果数据集过大无法放入磁盘，可以选择流式处理或挂载，而不是下载。请参阅处理大型数据集。
估算运行时间。 冒烟测试最终的 train_* 指标中包含 train_steps_per_second，而 Trainer 在启动时会打印总步数。两者结合即可得出完整运行的训练时长。请将 --timeout 设置为明显高于该值，因为 Job 还需要花费时间安装依赖项和下载模型。各规格的费率请参见定价与计费。
在多 GPU 规格上，请为每个 GPU 启动一个进程。 以 x2、x4 或 x8 结尾的规格表示一台机器上配备多个 GPU。请确保你的启动方式能够利用这些 GPU。Transformers 和 TRL 需要使用 accelerate launch，如 TRL 部分所示。Axolotl 会自行处理。直接使用 python train.py 只会使用一个 GPU，而 Trainer 会回退到 DataParallel，其速度低于每 GPU 一个进程的方式。
如果您将重新运行，请固定版本。 将脚本 URL 固定到某个 commit，而不是 main；将镜像固定到特定 tag，而不是 latest。这样重新运行时使用的软件版本就保持一致。下面的脚本 URL 跟踪的是 main，因此在重新运行之前请先固定 commit。
将长时间运行的任务检查点保存到已挂载的存储桶中，以避免因超时或崩溃而丢失运行结果。请参阅运行结束后。

运行期间

hf jobs run 和 hf jobs uv run 都会流式传输日志，并占用终端直到运行结束。按 Ctrl+C 仅停止日志流。任务会继续运行，直到完成，或者您使用 hf jobs cancel <job_id> 将其停止。

对于较长的运行，请传入 -d（detach）以立即获取 Job ID，然后使用 hf jobs logs -f <job_id> 跟踪运行状态，并使用 hf jobs stats <job_id> 确认 GPU 正在忙碌。在分离式运行后，hf jobs wait <job_id> 会阻塞直到 Job 结束，如果失败则以非零状态退出，这正是脚本或 agent 循环所需要的。非分离式运行已经具备此行为。请参阅管理 Jobs。

作业日志以文本形式打印损失值。若要绘制曲线，请将训练器指向实验跟踪器，例如 trackio；对于托管型跟踪器（如 Weights & Biases），请将其密钥作为第二个 secret 传入。

结束后

Job 结束时，其磁盘会被丢弃，无论该 Job 是成功完成、失败还是超时。任何需要保留的内容都必须在容器终止前移出。

将模型推送到 Hub 仓库。 本页面上的每个库都提供了相应选项：Transformers、TRL 和 Diffusers 使用 --push_to_hub，Unsloth 脚本使用 --output-repo，Axolotl YAML 中使用 hub_model_id。运行结束时，该库会上传权重、分词器以及一张生成的模型卡片，其中记录了基础模型和训练参数。如果仓库不存在，则会自动创建。若要将其设为私有，请先使用 hf repos create <name> --private 创建该仓库。细粒度令牌需要对模型仓库具有写入和创建权限。否则，运行会一直训练到最后，然后在上传阶段失败。

边运行边写入存储桶。 对于耗时数小时的运行任务，请以读写方式挂载一个现有的 Storage Bucket（可通过 hf buckets create 创建），并将库的输出目录指向该存储桶。检查点在保存时即会落入存储桶，因此超时或崩溃不会导致运行任务丢失，下一个 Job 也可以从中恢复。同样的方式也适用于评估输出、日志以及其他非模型产物。

hf jobs uv run --flavor a10g-large --timeout 8h -s HF_TOKEN \
  -v hf://buckets/your-username/checkpoints:/ckpt -- \
  train.py --output_dir /ckpt/run-01

Transformers、TRL 和 Diffusers 脚本接受 --output_dir。Axolotl 在 YAML 中接受 output_dir。如果同时传入 --push_to_hub，也请设置 --hub_model_id，否则仓库将以输出路径的最后一部分命名（run-01）。若要继续中断的运行，请再次挂载相同的存储桶，并传入该库的恢复选项，例如 Transformers Trainer 的 --resume_from_checkpoint。有关挂载选项，请参阅卷。

读取失败的运行。 失败的 Job 会保留其日志：运行结束后，hf jobs logs <job_id> 仍然可用，而 hf jobs inspect <job_id> 会显示最终状态和错误信息。hf jobs logs -f 会在日志流结束时返回，无论运行是否成功，因此在假设运行成功之前，请先检查 inspect。

Transformers

Transformers 仓库中的示例脚本在脚本头部声明其依赖项，因此可以直接通过其 GitHub URL 在 Jobs 上运行。URL 之后的参数会传递给脚本。首次运行使用图像分类脚本。

对于完整训练，请从该命令中移除 --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1：在 a10g-small 上对 75,000 张 Food-101 训练图像进行三个 epoch 的训练大约需要一小时，按该规格的费率计算成本约为 1 美元，并能达到 90% 的准确率。在启动之前，请将 --timeout 提高到 2h。--push_to_hub 会使用输出目录的名称，在你的命名空间下上传模型。此外，还提供了用于文本分类、摘要生成、翻译、词元分类、语音识别等任务的脚本。

TRL

TRL 为每种训练器（SFT、DPO、GRPO 等）都提供了一个可直接运行的脚本，每个脚本都声明了各自的依赖项，因此可以像 Transformers 脚本一样，直接通过其 URL 在 Jobs 上运行。此命令在一个聊天数据集上微调一个小模型：

hf jobs uv run --flavor a10g-small --timeout 30m -s 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

整个过程大约需要六分钟。若要运行完整训练，请移除 --max_steps：Capybara 的三个 epoch（即脚本的默认设置）在 a10g-small 上大约需要 2 小时 20 分钟，因此请相应调高 --timeout。TRL 官方文档使用的是 a100-large，速度更快。

完整指南，包括编写您自己的 TRL 脚本以及运行 huggingface/trl 镜像，请参阅 TRL 文档中的使用 Jobs 进行训练。

对于多 GPU 环境，请切换到 TRL 镜像，该镜像已附带 accelerate，并让它为每个 GPU 启动一个进程：

hf jobs run --flavor a10g-largex2 --timeout 30m -s HF_TOKEN huggingface/trl -- \
  accelerate launch --num_processes 2 -m trl.scripts.sft \
  --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

如果不使用 --max_steps，完整运行（Capybara 的三个 epoch，即脚本的默认设置）在两块 A10G 上大约需要 1 小时 35 分钟。

当您编写自己的 TRL 脚本时，启动配置可以随脚本一起携带。在头部添加一个 [tool.hf-jobs] 表格即可设置 flavor、超时和密钥：

# /// script
# dependencies = ["trl"]
#
# [tool.hf-jobs]
# flavor  = "a10g-small"
# timeout = "1h"
# secrets = ["HF_TOKEN"]
# ///
from trl import SFTConfig, SFTTrainer
...

hf jobs uv run train.py 则无需任何标志，且您传入的标志仍然优先。请参阅在脚本中定义启动配置。

Unsloth

Unsloth 在 unsloth/jobs 数据集中提供了可直接运行的脚本，每个模型系列对应一个。这些脚本会从脚本头部安装 Unsloth，并将数据集和输出仓库作为参数：

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://huggingface.co/datasets/unsloth/jobs/resolve/main/sft-lfm2.5.py \
  --dataset mlabonne/FineTome-100k \
  --max-steps 50 \
  --output-repo your-username/lfm-finetuned

整个过程大约需要五分钟，并会推送一个 LoRA 适配器。若要训练完整一个 epoch，请将 --max-steps 50 替换为 --num-epochs 1，并调高 --timeout。相关教程是 Hugging Face 博客上的使用 Unsloth 在 Jobs 上进行微调。

Axolotl

Axolotl 接受 YAML 配置文件，并从其自身的 Docker 镜像中运行，因此本节使用带有固定标签的 hf jobs run，并通过 -v 从本地目录同步配置文件。将 Axolotl examples 中的某个配置保存为 ./configs/lora.yml，并在命令后添加所示的键。本示例使用 examples/phi/lora-3.5.yaml，即对 Phi-3.5-mini 进行 LoRA 微调，其余内容保持不变。该镜像中已包含 axolotl 命令。

hf jobs run --flavor a10g-small --timeout 30m -s HF_TOKEN \
  -v ./configs:/configs \
  axolotlai/axolotl:0.19.0-py3.12-cu130-2.13.0 -- \
  axolotl train /configs/lora.yml

-v ./configs:/configs 会将本地的 configs 目录上传到您的私有 jobs-artifacts 存储桶（首次使用时自动为您创建），并以只读方式挂载到容器中，因此磁盘上的 YAML 文件就是本次运行实际使用的 YAML 文件。输出配置在 YAML 中设置。以下键值会在运行结束时推送模型，而 max_steps 则用于限制本次试运行：

hub_model_id: your-username/my-adapter
hub_strategy: end
max_steps: 20

整个过程大约需要七分钟，并将适配器推送到 hub_model_id，作为私有仓库。若要执行完整训练，请移除 max_steps。镜像标签的格式在 Axolotl 的 Docker 指南中有说明。

对于更多 GPU，只需更改 flavor，其他保持不变：在 a10g-largex4 上，axolotl train 会自动为每个 GPU 启动一个进程。DeepSpeed 和 FSDP 则通过 YAML 键来配置，相关内容见 Axolotl 多 GPU 指南。

有关更多详细信息，请参阅 Axolotl 文档中的 Hugging Face Jobs 指南。

Diffusers

Diffusers 仓库中的大多数 DreamBooth LoRA 脚本都在脚本头部声明了依赖项，因此可以直接通过其 GitHub URL 在 Jobs 上运行，与 Transformers 脚本类似。以下命令使用五张狗的照片为 FLUX.2 [klein] 4B 训练一个 LoRA：

hf jobs uv run --flavor a10g-small --timeout 30m -s HF_TOKEN -- \
  https://raw.githubusercontent.com/huggingface/diffusers/main/examples/dreambooth/train_dreambooth_lora_flux2_klein.py \
  --pretrained_model_name_or_path black-forest-labs/FLUX.2-klein-4B \
  --dataset_name diffusers/dog-example \
  --instance_prompt "a photo of sks dog" \
  --resolution 512 --mixed_precision bf16 --guidance_scale 1 \
  --gradient_checkpointing --cache_latents \
  --optimizer adamW --use_8bit_adam --learning_rate 1e-4 \
  --max_train_steps 20 --seed 0 \
  --output_dir /tmp/out \
  --push_to_hub --hub_model_id your-username/klein-dog-lora

整个过程大约需要五分钟，随后会推送 LoRA。若要正式运行，请调高 --max_train_steps；FLUX.2 README 中使用的值为 500。该文件夹中的其他 README 涵盖了其余模型及其内存选项。请检查脚本顶部的 # /// script 代码块：没有该块的脚本（例如 SDXL 脚本）需要通过 --with 传入其依赖项。

进一步探索

使用 Serve Models 将您训练的模型部署到临时端点，用于评估运行或演示。Inference Endpoints 则运行一个持续在线的端点。
用于机密、环境变量、卷以及[tool.hf-jobs]表的配置，该表可让脚本携带自身的 flavor 和超时设置。
使用管理任务来列出、检查、调试和取消任务。
使用处理大型数据集来流式传输和挂载无法放入磁盘的数据。
使用 Schedule Jobs 按定时器运行训练命令。
社区撰写的示例与教程，包括视觉-语言微调以及将大型数据集流式传输到训练运行中。
从编码代理使用 Jobs：hf CLI 技能可让 Claude Code、Codex 和 Cursor 为您启动并监控这些运行。

Update on GitHub

←部署模型示例与教程→