Hugging Face's logo

Hub documentation

Huấn luyện Mô hình trên các Job

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Huấn luyện Mô hình trên các Job

Trang này cho thấy cách tinh chỉnh và huấn luyện mô hình trên Jobs, bằng script của thư viện hoặc script của riêng bạn. Mỗi ví dụ đều giới hạn ở một lần chạy ngắn, hoàn thành trong vài phút trên một A10G, với chi phí tính toán khoảng 0,10 USD. Job chạy trên máy chủ của Hugging Face, nên nó sẽ tiếp tục chạy ngay cả khi bạn đóng terminal hoặc laptop. Nếu bạn chưa từng chạy Job trước đây, Quickstart bao gồm việc cài đặt CLI, đăng nhập và số tín dụng mà Job cần.

Chạy lần đầu

Lệnh này tinh chỉnh một bộ phân loại hình ảnh trên 2.000 hình ảnh Food-101 và đẩy nó lên namespace của bạn trên Hub, trong khoảng ba phút:

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

Phần Transformers bao gồm toàn bộ quy trình chạy và các script ví dụ khác.

Cách một Job huấn luyện được xây dựng

Lệnh ở trên có năm phần, và mọi lệnh trên trang này đều có cùng các phần đó.

  • Điều gì được thực thi. Một uv script, được khởi chạy bằng hf jobs uv run: một script Python khai báo các phụ thuộc trong một khối chú thích gần đầu file (# /// script, định dạng PEP 723), mà uv sẽ cài đặt vào một môi trường mới. Phần TRL có minh họa một ví dụ. Hoặc một Docker image của thư viện, được khởi chạy bằng hf jobs run, sử dụng thư viện đã được cài sẵn trong image. Hãy bắt đầu với một uv script khi thư viện có thể cài đặt bằng pip. Hãy dùng image khi thư viện cung cấp một image kèm các phụ thuộc đã biên dịch, hoặc khi tài liệu của nó yêu cầu như vậy. Xem Sử dụng Docker images để biết về sự đánh đổi.
  • Một token. Các tác vụ không nhận token Hugging Face nào theo mặc định. -s HF_TOKEN chuyển token của bạn dưới dạng bí mật, cho phép phiên chạy đẩy mô hình và đọc các đầu vào có kiểm soát hoặc riêng tư. Các bí mật khác được truyền theo cách tương tự, ví dụ -s WANDB_API_KEY.
  • Cấu hình phần cứng và thời gian. --flavor dùng để chọn GPU. --timeout đặt giới hạn thời gian, mặc định là 30 phút. Một lần chạy chạm đến giới hạn này sẽ bị dừng, vì vậy hãy đặt --timeout cao hơn thời gian chạy dự kiến. Xem Loại phần cứng và Giới hạn thời gian.
  • Một -- giữa các cờ hf và script. Các cờ trước -- là dành cho hf jobs. Sau đó là đường dẫn script và các tham số riêng của script. Nếu không có nó, một tham số script trùng tên với một cờ hf, chẳng hạn như --timeout hoặc --token, sẽ được hf nhận. Ở dạng image, phần sau -- là lệnh để chạy trong container.
  • Nơi lưu kết quả đầu ra. Mọi thư viện bên dưới đều có thể đẩy mô hình hoàn chỉnh lên một kho Hub, và mỗi ví dụ đều hiển thị tùy chọn này. Với Transformers và TRL, kho sẽ lấy tên từ --output_dir. Một lần chạy cũng có thể ghi vào một bucket đã được gắn (mount) trong khi đang chạy, bằng cách dùng -v để gắn bucket vào container. Xem Sau khi kết thúc.

Mã huấn luyện của riêng bạn. Hãy sử dụng dạng đơn giản nhất phù hợp:

  • Một tệp. Khai báo các phụ thuộc trong phần đầu script và chạy hf jobs uv run train.py. Phần TRL có một ví dụ.

  • Một thư mục dự án với các import cục bộ, một tệp pyproject.toml hoặc các tệp cấu hình. hf jobs uv run chỉ tải lên tệp script, vì vậy hãy gắn (mount) thư mục thay vào đó. Việc gắn là chỉ đọc, nên lệnh sẽ sao chép dự án sang một thư mục có thể ghi và chạy ở đó, giống như khi chạy cục bộ:

    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 cài đặt các phụ thuộc từ pyproject.toml hoặc phần header của script, và các import cục bộ cũng như đường dẫn tương đối hoạt động không thay đổi. Xem Thư mục cục bộ.

  • Code cần các gói hệ thống hoặc bộ công cụ CUDA. Xây dựng một image một lần và chạy nó bằng hf jobs run. Xem Xây dựng image của riêng bạn với một Docker Space.

Một script cũng có thể chứa cấu hình khởi chạy riêng của nó trong bảng [tool.hf-jobs] ở phần đầu script, như phần TRL đã minh họa. Xem Định nghĩa cấu hình khởi chạy trong script. Các lệnh tương tự cũng có sẵn từ Python dưới dạng run_uv_job() và run_job(), được đề cập trong Cấu hình.

Kiểm tra trước khi chạy dài

Trước khi bạn gỡ bỏ các phần chặn, một vài bước kiểm tra sẽ giúp tránh lãng phí một lần chạy.

  • Thực hiện kiểm tra nhanh trước. Chạy lệnh với giới hạn số bước trên một phiên bản nhỏ, như các ví dụ trên trang này. Điều này chứng minh rằng các phụ thuộc được cài đặt, dữ liệu được nạp, mô hình được huấn luyện và thao tác đẩy hoạt động. Sau đó, bỏ giới hạn và khởi chạy phiên chạy đầy đủ.
  • Kiểm tra xem dữ liệu có vừa với dung lượng không. Mỗi cấu hình có một ổ đĩa cố định, được liệt kê trong cột Ephemeral Storage trên Pricing and Billing. Trọng số, tập dữ liệu và các checkpoint đã lưu dùng chung ổ đĩa này. Một tập dữ liệu quá lớn so với dung lượng ổ đĩa có thể được stream hoặc mount thay vì tải xuống. Xem Process Large Datasets.
  • Dự đoán thời gian chạy. Các chỉ số train_* cuối cùng của bài kiểm tra smoke bao gồm train_steps_per_second, và trainer sẽ in tổng số bước khi bắt đầu. Kết hợp lại, chúng cho biết thời gian huấn luyện của toàn bộ lần chạy. Đặt --timeout cao hơn mức đó một cách thoải mái, vì Job cũng mất thời gian để cài đặt các phụ thuộc và tải xuống model. Tốc độ theo từng flavor nằm ở Pricing and Billing.
  • Trên một cấu hình đa GPU, hãy khởi động một tiến trình cho mỗi GPU. Các cấu hình kết thúc bằng x2, x4 hoặc x8 cung cấp nhiều GPU trên một máy. Hãy đảm bảo cách bạn khởi động có sử dụng chúng. Transformers và TRL cần accelerate launch, như phần TRL đã minh họa. Axolotl tự thực hiện điều này. Một lệnh python train.py thông thường chỉ dùng một GPU, và Trainer sẽ quay lại dùng DataParallel, chậm hơn so với một tiến trình cho mỗi GPU.
  • Ghim nếu bạn sẽ chạy lại. Ghim URL của script vào một commit thay vì main, và ghim image vào một tag cụ thể thay vì latest. Khi đó, một lần chạy lại sẽ nhận được phần mềm giống hệt. Các URL script bên dưới theo dõi main, vì vậy hãy ghim commit trước khi bạn chạy lại một trong số chúng.
  • Checkpoint các phiên chạy dài vào một bucket đã gắn, để thời gian chờ hết hạn hoặc sự cố không làm mất phiên chạy. Xem Sau khi kết thúc.

Trong khi nó đang chạy

Cả hf jobs run và hf jobs uv run đều phát trực tiếp nhật ký và giữ cửa sổ terminal của bạn cho đến khi quá trình chạy kết thúc. Nhấn Ctrl+C chỉ dừng luồng nhật ký. Job vẫn tiếp tục chạy cho đến khi hoàn tất hoặc bạn dừng nó bằng hf jobs cancel <job_id>.

Với các lần chạy dài hơn, hãy truyền -d (detach) để nhận Job ID ngay lập tức, sau đó theo dõi lần chạy bằng hf jobs logs -f <job_id> và xác nhận GPU đang bận bằng hf jobs stats <job_id>. Sau một lần chạy detached, hf jobs wait <job_id> sẽ chặn cho đến khi Job kết thúc và thoát với mã khác không nếu nó thất bại, đây là điều mà một script hoặc vòng lặp agent cần. Một lần chạy không detached đã thực hiện điều này. Xem Quản lý Jobs.

Nhật ký công việc in các giá trị loss dưới dạng văn bản. Để vẽ đường cong, hãy chỉ định cho trainer một trình theo dõi thí nghiệm như trackio và, đối với trình theo dõi được lưu trữ như Weights & Biases, hãy truyền khóa của nó như một bí mật thứ hai.

Sau khi kết thúc

Đĩa của Job sẽ bị xóa khi Job kết thúc, bất kể là hoàn tất, thất bại hay hết thời gian chờ. Mọi thứ bạn muốn giữ lại phải được đưa ra khỏi container trước thời điểm đó.

Đẩy model lên một repo trên Hub. Mọi thư viện trên trang này đều có tùy chọn cho việc này: --push_to_hub cho Transformers, TRL và Diffusers, --output-repo cho các script của Unsloth, hub_model_id trong một file YAML của Axolotl. Vào cuối quá trình chạy, thư viện sẽ tải lên các trọng số, tokenizer và một model card được tạo tự động, ghi lại model gốc và các tham số huấn luyện. Repo sẽ được tạo nếu nó chưa tồn tại. Để đặt repo ở chế độ riêng tư, hãy tạo nó trước bằng lệnh hf repos create <name> --private. Một token chi tiết cần quyền ghi và tạo đối với model repo. Nếu không có quyền này, quá trình chạy sẽ huấn luyện đến cuối rồi sau đó thất bại ở bước tải lên.

Viết vào bucket trong khi chạy. Đối với một run kéo dài nhiều giờ, hãy mount một Storage Bucket hiện có ở chế độ đọc-ghi (tạo một bucket bằng hf buckets create) và trỏ thư mục output của thư viện vào đó. Các checkpoint sẽ được lưu vào bucket ngay khi được tạo, nên một timeout hay crash sẽ không làm mất run, và Job tiếp theo có thể tiếp tục từ chúng. Cách làm tương tự cũng áp dụng cho output của evaluation, logs và bất kỳ thứ gì khác không phải là model.

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

Các script của Transformers, TRL và Diffusers nhận --output_dir. Axolotl nhận output_dir trong YAML. Nếu bạn cũng truyền --push_to_hub, hãy đặt cả --hub_model_id, nếu không kho sẽ được đặt tên theo phần cuối của đường dẫn đầu ra (run-01). Để tiếp tục một lần chạy bị gián đoạn, hãy gắn lại cùng một bucket và truyền tùy chọn tiếp tục của thư viện, chẳng hạn như --resume_from_checkpoint cho Trainer của Transformers. Xem Volumes để biết các tùy chọn gắn.

Đọc một lần chạy thất bại. Một Job bị lỗi vẫn giữ lại nhật ký của nó: hf jobs logs <job_id> vẫn hoạt động sau khi kết thúc, và hf jobs inspect <job_id> cung cấp trạng thái cuối cùng cùng thông báo lỗi. hf jobs logs -f sẽ trả về khi luồng nhật ký kết thúc bất kể lần chạy có thành công hay không, vì vậy hãy kiểm tra inspect trước khi cho rằng nó đã chạy thành công.

Transformers

Các script mẫu trong kho Transformers khai báo các phụ thuộc trong phần đầu script, do đó chúng chạy trực tiếp trên Jobs từ URL GitHub của chúng. Các đối số sau URL được truyền vào script. Lần chạy đầu tiên sử dụng script phân loại hình ảnh.

Để chạy đầy đủ, hãy bỏ --max_train_samples 2000 --max_eval_samples 500 --num_train_epochs 1 khỏi lệnh đó: ba epoch trên 75.000 ảnh huấn luyện Food-101 mất khoảng một giờ trên a10g-small, với chi phí khoảng 1 USD theo mức giá của loại instance đó, và đạt độ chính xác 90%. Hãy tăng --timeout lên 2h trước khi khởi chạy. --push_to_hub tải mô hình lên dưới namespace của bạn, sử dụng tên thư mục đầu ra. Có sẵn các script cho phân loại văn bản, tóm tắt, dịch, phân loại token, nhận dạng giọng nói và nhiều hơn nữa.

TRL

TRL có sẵn một script chạy được ngay cho mỗi trainer (SFT, DPO, GRPO và các trainer khác), mỗi script khai báo các phụ thuộc riêng của nó, do đó chúng có thể chạy trực tiếp trên Jobs từ URL của chúng, giống như các script của Transformers. Lệnh này fine-tune một mô hình nhỏ trên một dataset chat:

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

Quá trình này hoàn thành trong khoảng sáu phút. Bỏ --max_steps để chạy đầy đủ: ba epoch của Capybara, mặc định của script, mất khoảng 2 giờ 20 phút trên a10g-small, vì vậy hãy tăng --timeout khi chạy. Tài liệu của TRL sử dụng a100-large, nhanh hơn.

Hướng dẫn đầy đủ, bao gồm việc tự viết script TRL và chạy image huggingface/trl, nằm trong Training with Jobs của tài liệu TRL.

Với nhiều GPU, hãy chuyển sang ảnh TRL, có sẵn accelerate, và để nó khởi động một tiến trình cho mỗi 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

Nếu không có --max_steps, toàn bộ quá trình chạy (ba epoch của Capybara, mặc định của script) mất khoảng 1 giờ 35 phút trên hai A10G.

Khi bạn tự viết script TRL, cấu hình khởi chạy có thể đi kèm với nó. Một bảng [tool.hf-jobs] trong phần tiêu đề sẽ thiết lập loại, thời gian chờ và các bí mật:

# /// 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 sau đó không cần cờ, và một cờ bạn truyền vào vẫn sẽ được ưu tiên. Xem Định nghĩa cấu hình khởi chạy trong script.

Unsloth

Unsloth cung cấp các script sẵn sàng để chạy trong dataset unsloth/jobs, mỗi script tương ứng với một họ model. Các script này cài đặt Unsloth từ phần header của script và nhận dataset cùng repo đầu ra làm đối số:

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

Quá trình này hoàn thành trong khoảng năm phút và đẩy một bộ thích ứng LoRA. Để chạy đủ một epoch, thay --max-steps 50 bằng --num-epochs 1 và tăng --timeout. Bài hướng dẫn là Fine-tune with Unsloth on Jobs trên blog Hugging Face.

Axolotl

Axolotl nhận một cấu hình YAML và chạy từ ảnh Docker riêng của nó, vì vậy phần này sử dụng hf jobs run với một tag được cố định và đồng bộ cấu hình từ một thư mục cục bộ bằng -v. Lưu một cấu hình từ Axolotl examples thành ./configs/lora.yml và thêm các khóa được hiển thị sau lệnh. Ví dụ này sử dụng examples/phi/lora-3.5.yaml, một fine-tune LoRA của Phi-3.5-mini, không thay đổi gì khác. Ảnh đã chứa sẵn lệnh 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 tải thư mục configs cục bộ lên bucket jobs-artifacts riêng tư của bạn (được tạo cho bạn khi sử dụng lần đầu) và gắn nó vào container ở chế độ chỉ đọc, nhờ đó file YAML trên đĩa chính là file YAML mà lần chạy sử dụng. Đầu ra được thiết lập trong YAML. Các khóa này đẩy model vào cuối lần chạy, và max_steps giới hạn lần chạy thử này:

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

Quá trình này hoàn thành trong khoảng bảy phút và đẩy adapter lên hub_model_id, dưới dạng kho riêng. Hãy xóa max_steps để chạy đầy đủ. Các định dạng thẻ hình được mô tả trong hướng dẫn Docker của Axolotl.

Với nhiều GPU hơn, chỉ cần thay đổi flavor và không cần thay đổi gì khác: trên a10g-largex4, axolotl train tự động khởi động một tiến trình cho mỗi GPU. DeepSpeed và FSDP sau đó chỉ là vấn đề của các khóa YAML, được đề cập trong hướng dẫn đa GPU của Axolotl.

Để biết thêm chi tiết, hãy xem hướng dẫn Hugging Face Jobs trong tài liệu Axolotl.

Diffusers

Hầu hết các script DreamBooth LoRA trong kho Diffusers khai báo các phụ thuộc trong phần đầu script, do đó chúng chạy trực tiếp trên Jobs từ URL GitHub của chúng, giống như các script của Transformers. Lệnh này huấn luyện một LoRA cho FLUX.2 [klein] 4B trên năm bức ảnh của một con chó:

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

Quá trình này hoàn tất trong khoảng năm phút và đẩy LoRA lên. Tăng --max_train_steps cho một lần chạy thực tế; FLUX.2 README sử dụng 500. Các README khác trong thư mục đó bao phủ các mô hình còn lại và các tùy chọn bộ nhớ của chúng. Kiểm tra đầu của một script để tìm khối # /// script: các script không có khối này, chẳng hạn như script SDXL, cần truyền các phụ thuộc của chúng bằng --with.

Đi xa hơn

  • Serve Models để đặt mô hình bạn đã huấn luyện phía sau một endpoint tạm thời, phục vụ cho một lần chạy đánh giá hoặc một buổi demo. Inference Endpoints chạy một endpoint duy trì hoạt động liên tục.
  • Cấu hình cho secrets, biến môi trường, volumes và bảng [tool.hf-jobs] cho phép một script tự mang theo cấu hình riêng và thời gian chờ.
  • Quản lý Jobs để liệt kê, kiểm tra, gỡ lỗi và hủy các Jobs.
  • Xử lý bộ dữ liệu lớn để phát trực tiếp và gắn kết dữ liệu không vừa với ổ đĩa.
  • Lịch công việc để chạy lệnh huấn luyện theo định kỳ.
  • Ví dụ & Hướng dẫn cho các bài viết của cộng đồng, bao gồm tinh chỉnh mô hình thị giác-ngôn ngữ và truyền trực tiếp các bộ dữ liệu lớn vào một phiên huấn luyện.
  • Sử dụng Jobs từ một coding agent: kỹ năng hf CLI cho phép Claude Code, Codex và Cursor khởi động và theo dõi các lần chạy này cho bạn.
Update on GitHub

←Cung cấp mô hình Ví dụ & Hướng dẫn→