TRL documentation

Huấn luyện với Jobs

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v1.18.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Huấn luyện với Jobs

model badge

Hugging Face Jobs chạy huấn luyện của bạn trên GPU của Hugging Face. Bạn chọn phần cứng cho mỗi lần chạy và chỉ trả tiền theo số giây nó chạy. Với --push_to_hub, mô hình đã huấn luyện sẽ được tải lên Hub khi kết thúc.

Trong hướng dẫn này, bạn sẽ học cách:

  • Chạy một script huấn luyện TRL bằng một lệnh
  • Theo dõi một lần chạy và xem các đường cong loss của nó
  • Chạy script của bạn, với các cài đặt phần cứng trong tệp
  • Giữ các checkpoint và tiếp tục một lần chạy bị gián đoạn
  • Huấn luyện trên nhiều GPU

Để tìm hiểu cách thức hoạt động chung của Jobs, bao gồm phần cứng và giá cả, hãy xem tài liệu về Jobs.

Yêu cầu

  • Tài khoản Hugging Face có số dư tín dụng dương. Việc chạy tác vụ được tính phí theo mức sử dụng: bạn chỉ trả tiền cho số giây đã dùng.
  • Đã đăng nhập vào Hugging Face Hub (hf auth login)

Chạy lần đầu

Lệnh này tinh chỉnh Qwen2-0.5B-Instruct trên bộ dữ liệu chat Capybara bằng script SFT của TRL, sau đó đẩy mô hình lên tài khoản của bạn:

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

Quá trình này mất vài phút và chi phí dưới 1 đô la trên a10g-small. Các tùy chọn trước -- dành cho Jobs: phần cứng, giới hạn thời gian và token được dùng để đẩy mô hình. --secrets HF_TOKEN gửi token mà bạn đã dùng để đăng nhập. Trong Python, hãy truyền chính token đó. Các đối số sau URL của script sẽ được chuyển đến script. hf jobs uv run chạy một script Python bằng uv. sft.py liệt kê các phụ thuộc của nó trong phần tiêu đề ở đầu tệp, vì vậy Jobs sẽ cài đặt TRL trước khi script bắt đầu. Job sẽ dừng khi script thoát, và việc tính phí cũng dừng theo.

--max_steps 100 giúp lần chạy đầu tiên này diễn ra nhanh. Hãy bỏ tham số này cho lần chạy đầy đủ: ba epoch, mặc định của script, mất vài giờ trên a10g-small, vì vậy hãy tăng --timeout cho phù hợp, ví dụ --timeout 3h. Jobs sẽ dừng một lần chạy khi nó đạt đến thời gian chờ, mặc định là 30 phút. Một GPU lớn hơn như a100-large sẽ hoàn thành sớm hơn. Xem Cấu hình phần cứng để biết các loại và giá của chúng.

Theo dõi quá trình chạy

hf jobs uv run sẽ phát trực tiếp nhật ký và giữ phiên terminal của bạn cho đến khi chạy xong. Nhấn Ctrl+C chỉ dừng luồng nhật ký: Job vẫn tiếp tục chạy. Thêm --detach để nhận ngay ID của Job, sau đó:

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

Xem Quản lý công việc để biết thêm.

Đối với đường cong loss, TRL ghi log vào Trackio. Thêm --env TRACKIO_SPACE_ID=<your-username>/trackio trước -- để đặt tên cho một Space dùng làm dashboard, và --report_to trackio sau URL của script. Trackio sẽ tạo Space và một bucket cho các metrics nếu chúng chưa tồn tại. Cả hai đều công khai theo mặc định. Các tracker khác mà Transformers hỗ trợ cũng hoạt động. Đối với Weights & Biases, thêm --with wandb --secrets WANDB_API_KEY trước -- và --report_to wandb sau URL của script. --secrets WANDB_API_KEY đọc giá trị từ WANDB_API_KEY trong môi trường cục bộ của bạn. Xem environment variables and secrets để biết các cách khác để truyền chúng.

Chạy script của riêng bạn

Viết mã huấn luyện của bạn trong một tệp Python (ví dụ, train.py). Liệt kê các phụ thuộc của nó ở đầu tệp, trong một tiêu đề script, theo cách mà các script của TRL làm. Jobs sẽ cài đặt chúng trước khi script bắt đầu:

# /// 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()

Sau đó, khởi chạy nó bằng CLI hf jobs hoặc API Python:

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

Đối với script không có header, hãy liệt kê các phụ thuộc khi khởi chạy bằng --with, mỗi gói một lần: --with trl --with peft (dependencies=["trl", "peft"] trong Python). Script cũng có thể là một URL, chẳng hạn như liên kết raw trên GitHub, một Gist hoặc một tệp trong kho Hub công khai.

Các cài đặt khởi chạy cũng có thể nằm trong script. Bảng [tool.hf-jobs] trong phần tiêu đề sẽ thiết lập phần cứng, thời gian chờ và các bí mật:

# /// script
# dependencies = [
#     "trl",
#     "peft",
# ]
#
# [tool.hf-jobs]
# flavor = "a10g-small"
# timeout = "30m"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run train.py sau đó không cần các tùy chọn, và một tùy chọn bạn truyền vào vẫn sẽ ghi đè lên script. Script chứa mọi thứ cần thiết để chạy, vì vậy bạn có thể chia sẻ nó, hoặc quay lại với nó sau này, mà không cần nhớ lại GPU và timeout nào được yêu cầu. hf jobs uv run --dry-run train.py hiển thị các cài đặt đã được phân giải và đánh dấu các giá trị đến từ script. Bảng này chỉ được đọc bởi CLI hf: run_uv_job() sẽ bỏ qua nó. Xem Định nghĩa cấu hình khởi chạy trong script.

Chạy bất kỳ script TRL nào

Cùng một mẫu này được áp dụng cho mọi script trainer của TRL (SFT, DPO, GRPO, reward modeling và các loại khác) cũng như các ví dụ .py độc lập trong Chỉ mục ví dụ. Mỗi script khai báo các phụ thuộc của nó trong phần header. Một ví dụ cần đọc các tệp khác nằm cùng thư mục thì thư mục đó phải được gắn (mount) vào Job. Xem Thư mục cục bộ. Các ví dụ chỉ chạy trên Notebook không thể được gửi theo cách này. Các đối số của script giống hệt như khi bạn chạy script cục bộ.

Giữ các điểm kiểm tra

Đĩa của Job sẽ bị xóa khi Job kết thúc, bao gồm cả khi nó hết thời gian chờ hoặc thất bại. Đối với một lần chạy dài, hãy lưu checkpoint bên ngoài Job để chúng được giữ lại.

Cách đơn giản nhất là đẩy từng checkpoint lên kho model đầu ra ngay khi nó được lưu:

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

Với --hub_strategy checkpoint, checkpoint mới nhất, bao gồm cả trạng thái optimizer, được giữ trong thư mục last-checkpoint của repo. Để tiếp tục một lần chạy bị gián đoạn, hãy mount repo vào một Job mới và khôi phục từ thư mục đó: khởi chạy cùng một lệnh với --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous trước -- và --resume_from_checkpoint /previous/last-checkpoint sau URL của script.

Để giữ một số checkpoint bên ngoài kho model, hãy ghi chúng vào Storage Bucket thay thế. Tạo một bucket bằng hf buckets create <your-username>/checkpoints --private, gắn nó vào Job và trỏ --output_dir đến bucket đó:

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

Để tiếp tục một lần chạy bị gián đoạn, hãy chạy lại cùng một lệnh với --resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step>. Xem Viết vào bucket trong khi chạy để biết thêm và Volumes cho các tùy chọn gắn.

Mỗi checkpoint lưu trữ trạng thái của model và optimizer, có kích thước gấp nhiều lần kích thước model. Thêm --save_total_limit 2 để chỉ giữ lại những checkpoint mới nhất. Nếu bạn cũng truyền --push_to_hub, hãy đặt --hub_model_id, hoặc repo sẽ được đặt tên theo phần cuối của đường dẫn output.

Nhiều GPU

Một flavor với nhiều GPU sẽ rút ngắn thời gian chạy. Để làm điều này, hãy dùng hf jobs run, lệnh này chạy một command trong một Docker image thay vì một script, với image huggingface/trl, trong đó đã cài sẵn TRL và Accelerate. Sau đó, hãy khởi động một process cho mỗi GPU. Cách này hoạt động với các script của TRL cũng như với mã huấn luyện riêng của bạn.

Tăng tốc một script TRL

Chạy SFT từ đầu hướng dẫn này, trên bốn 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 truyền --nproc_per_node cho torchrun. Đặt giá trị này bằng số lượng GPU trong flavor, ở đây là bốn L4. Mỗi tiến trình nhận một batch riêng, do đó kích thước batch hiệu dụng gấp bốn lần so với chạy trên một GPU. Lần chạy này mất vài phút. Nếu không có --max_steps, ba epoch đầy đủ sẽ mất khoảng một giờ, vì vậy hãy tăng --timeout, ví dụ thành 2h.

Script của riêng bạn

Bạn không bị giới hạn trong các script của TRL. Mã huấn luyện chạy với torchrun cục bộ sẽ chạy theo cách tương tự trên Jobs, miễn là image có các gói cần thiết. Ví dụ, hãy lưu một script GRPO với hàm reward của bạn dưới tên train_grpo.py trong một thư mục, và gắn (mount) thư mục đó vào Job. Jobs sẽ tải thư mục lên một bucket riêng tư và gắn nó ở chế độ chỉ đọc:

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

Script được chạy với TRL đã được cài đặt trong image, vì vậy không cần phần header của script. GRPOTrainer mặc định tạo ra các completion bằng transformers, do đó quy trình này chạy trong một Job duy nhất mà không cần server vLLM. Để tạo completion nhanh hơn, hãy xem vLLM Integration. Phần tiếp theo giải thích cách hf jobs run sử dụng image.

Ảnh Docker

Jobs chạy script của bạn bằng uv, công cụ này cài đặt các phụ thuộc được khai báo trong phần # /// script của nó vào một môi trường mới. Do đó, TRL mà script của bạn import sẽ đến từ phần header đó, chứ không phải từ image, và các ví dụ hf jobs uv run ở trên hoàn toàn không cần --image.

Một Docker image có TRL được cài đặt sẵn có sẵn tại huggingface/trl. Truyền nó vào hf jobs uv run sẽ cung cấp cho job lớp hệ thống của image, chẳng hạn như CUDA toolchain, điều này quan trọng đối với các dependency được biên dịch dựa trên nó:

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

Để chạy TRL được cài đặt trong image, hãy dùng hf jobs run thay thế. Lệnh này chạy một command trực tiếp trong image, không cần script header để resolve, nên chính TRL của image sẽ được thực thi. -- dùng để tách command khỏi các tùy chọn của Jobs, điều này cần thiết bất cứ khi nào bản thân command có các tùy chọn:

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

Hình ảnh được phát hành dưới ba loại thẻ:

ThẻNội dung
X.Y.ZPhiên bản phát hành TRL của phiên bản đó, được xây dựng khi phiên bản đó được phát hành
latestPhiên bản phát hành gần nhất
devNhánh main, được xây dựng lại sau mỗi lần hợp nhất

Sử dụng dev để chạy phiên bản phát triển, rất hữu ích khi muốn thử nghiệm một bản sửa lỗi đã được đưa vào main nhưng chưa được phát hành:

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

Tags chỉ chọn phiên bản được cài đặt trong image, do đó chúng có ý nghĩa với hf jobs run. Với hf jobs uv run, phiên bản được lấy từ phần header của script, và tag không ảnh hưởng đến việc TRL nào được import.

Việc kết hợp cả hai, để uv phân giải phần đầu script trong khi một số import vẫn đến từ image, cần thêm các cờ bổ sung. Xem Tái sử dụng các gói của image và thêm phụ thuộc bằng UV cho dạng đó và các đường dẫn mà nó yêu cầu.

Jobs chạy trên một ảnh Docker từ Hugging Face Spaces hoặc Docker Hub, vì vậy bạn cũng có thể chỉ định bất kỳ ảnh tùy chỉnh nào:

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

Wrapper TRL Jobs khởi chạy các script TRL trên Jobs với các cấu hình có sẵn cho một số model, ví dụ trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara.

Update on GitHub