Jobs를 사용한 학습

Hugging Face Jobs는 Hugging Face GPU에서 학습을 실행합니다. 각 실행에 사용할 하드웨어를 선택하고 실행된 시간(초)만큼만 비용을 지불합니다. --push_to_hub를 사용하면 학습이 끝난 후 모델이 Hub에 업로드됩니다.

이 가이드에서는 다음을 배웁니다:

TRL 학습 스크립트를 하나의 명령어로 실행
실행을 추적하고 손실 곡선을 확인합니다
… 파일에 하드웨어 설정을 포함하여 자체 스크립트를 실행합니다
체크포인트를 유지하고 중단된 실행을 재개합니다
여러 GPU에서 학습

하드웨어 및 가격 등 Jobs의 일반적인 작동 방식에 대해서는 Jobs 문서를 참고하세요.

요구 사항

양수 크레딧 잔액이 있는 Hugging Face 계정. Jobs는 사용량 과금 방식입니다: 사용한 초당만 과금됩니다.
Hugging Face Hub에 로그인했습니다(hf auth login)

첫 실행

이 명령은 TRL SFT 스크립트를 사용하여 Capybara 채팅 데이터셋으로 Qwen2-0.5B-Instruct를 파인튜닝한 후 모델을 사용자의 계정에 업로드합니다:

bash

python

a10g-small에서 몇 분 정도 소요되며 비용은 $1 미만입니다. -- 앞의 옵션은 Jobs에 대한 것입니다: 하드웨어, 시간 제한, 그리고 모델을 푸시하는 데 사용되는 토큰입니다. --secrets HF_TOKEN은 로그인할 때 사용한 토큰을 전송합니다. Python에서는 토큰 자체를 전달합니다. 스크립트 URL 뒤의 인수는 스크립트로 전달됩니다. hf jobs uv run은 uv로 Python 스크립트를 실행합니다. sft.py는 파일 상단의 헤더에 의존성을 나열하므로, Jobs는 스크립트가 시작되기 전에 TRL을 설치합니다. 스크립트가 종료되면 Job도 중단되고, 과금도 함께 중단됩니다.

--max_steps 100은 첫 실행을 짧게 유지합니다. 전체 실행을 위해 이 옵션을 제거하세요. 3개 epoch, 즉 스크립트의 기본값은 a10g-small에서 몇 시간이 걸리므로, 예를 들어 --timeout 3h처럼 --timeout을 그에 맞게 높여야 합니다. Jobs는 타임아웃에 도달하면 실행을 중단하며, 기본 타임아웃은 30분입니다. a100-large와 같은 더 큰 GPU는 더 빨리 완료됩니다. 플레버와 가격은 Hardware를 참조하세요.

실행을 따르세요

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

자세한 내용은 Manage Jobs를 참조하세요.

손실 곡선의 경우, TRL은 Trackio에 로깅합니다. 대시보드를 위한 Space 이름을 지정하려면 -- 앞에 --env TRACKIO_SPACE_ID=<your-username>/trackio를, 스크립트 URL 뒤에 --report_to trackio를 추가하세요. Trackio는 Space와 메트릭용 버킷이 존재하지 않는 경우 이를 생성합니다. 둘 다 기본적으로 공개됩니다. Transformers가 지원하는 다른 트래커도 사용할 수 있습니다. Weights & Biases의 경우, -- 앞에 --with wandb --secrets WANDB_API_KEY를, 스크립트 URL 뒤에 --report_to wandb를 추가하세요. --secrets WANDB_API_KEY는 로컬 환경의 WANDB_API_KEY에서 값을 읽습니다. 다른 전달 방법은 환경 변수 및 시크릿을 참고하세요.

스스로 스크립트 실행

Python 파일(예: train.py)에 학습 코드를 작성합니다. TRL 스크립트와 동일한 방식으로 파일 상단에 스크립트 헤더에 의존성을 나열합니다. Jobs는 스크립트가 시작되기 전에 이를 설치합니다:

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

헤더가 없는 스크립트의 경우, 패키지를 하나씩 지정하여 --with 플래그를 통해 런치 시점에 의존성을 나열합니다: --with trl --with peft (Python에서는 dependencies=["trl", "peft"]). 스크립트는 GitHub raw 링크, Gist 또는 공개 Hub 저장소의 파일과 같은 URL일 수도 있습니다.

런치 설정은 스크립트 안에 포함할 수도 있습니다. 헤더의 [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 trainer 스크립트(SFT, DPO, GRPO, reward modeling 등)와 Examples Index의 독립형 .py 예제에 적용됩니다. 각 스크립트는 헤더에 자신의 의존성을 선언합니다. 같은 폴더의 다른 파일을 읽는 예제는 해당 폴더를 Job에 마운트해야 합니다. Local directories를 참조하세요. Notebook 전용 예제는 이 방식으로 제출할 수 없습니다. 스크립트 인수는 로컬에서 스크립트를 실행할 때와 동일합니다.

체크포인트 유지

Job이 종료되면, 타임아웃에 도달하거나 실패하는 경우를 포함하여 해당 Job의 디스크가 삭제됩니다. 장시간 실행되는 경우, Job이 종료되어도 체크포인트가 유지되도록 Job 외부에 저장하세요.

가장 간단한 방법은 각 체크포인트가 저장될 때마다 출력 모델 저장소에 푸시하는 것입니다:

bash

python

--hub_strategy checkpoint를 사용하면 옵티마이저 상태를 포함한 최신 체크포인트가 리포지토리의 last-checkpoint 폴더에 유지됩니다. 중단된 실행을 계속하려면 리포지토리를 새 Job에 마운트하고 해당 폴더에서 재개하십시오: 스크립트 URL 앞에 --를, 그 뒤에 --resume_from_checkpoint /previous/last-checkpoint를 추가하고, -- 앞에 --volume hf://<your-username>/Qwen2-0.5B-SFT:/previous를 사용하여 동일한 명령을 실행합니다.

모델 저장소 외부에 여러 체크포인트를 유지하려면, 대신 Storage Bucket에 작성하세요. hf buckets create <your-username>/checkpoints --private로 하나를 생성하고, Job에 마운트한 뒤 --output_dir를 해당 버킷으로 지정하세요:

bash

python

중단된 실행을 계속하려면 --resume_from_checkpoint /checkpoints/Qwen2-0.5B-SFT/checkpoint-<step>를 추가하여 동일한 명령을 다시 실행하세요. 자세한 내용은 버킷에 진행하면서 쓰기를, 마운트 옵션은 볼륨을 참고하세요.

각 체크포인트에는 모델과 옵티마이저 상태가 저장되며, 모델 크기의 몇 배에 달합니다. 최신 것만 유지하려면 --save_total_limit 2를 추가하세요. --push_to_hub도 함께 전달하는 경우, --hub_model_id를 설정하거나 저장소 이름이 출력 경로의 마지막 부분과 같아야 합니다.

여러 GPU

여러 개의 GPU를 사용하는 flavor는 실행 시간을 단축합니다. 이를 위해 hf jobs run을 사용하세요. 이 명령은 스크립트가 아닌 Docker 이미지에서 명령을 실행하며, TRL과 Accelerate가 설치된 huggingface/trl 이미지를 사용합니다. 그런 다음 GPU당 하나의 프로세스를 시작합니다. 이 방법은 TRL 스크립트와 자체 학습 코드 모두에 적용됩니다.

TRL 스크립트 속도 향상

이 가이드의 시작 부분에서 4개의 GPU로 실행한 SFT:

bash

python

trl CLI는 --nproc_per_node를 torchrun에 전달합니다. 이를 해당 flavor의 GPU 수, 여기서는 L4 4개로 설정합니다. 각 프로세스는 자체 배치를 처리하므로, 실효 배치 크기는 단일 GPU 실행의 4배가 됩니다. 이 실행에는 몇 분 정도가 소요됩니다. --max_steps가 없으면 전체 3에포크에 약 1시간이 소요되므로, --timeout를 예를 들어 2h로 늘리세요.

직접 작성한 스크립트

TRL 스크립트로만 제한되지 않습니다. 로컬에서 torchrun으로 실행되는 학습 코드는 이미지에 필요한 패키지가 포함되어 있는 한 Jobs에서도 동일한 방식으로 실행됩니다. 예를 들어, 자체 보상 함수가 포함된 GRPO 스크립트를 train_grpo.py로 저장한 후 해당 폴더를 Job에 마운트합니다. Jobs는 폴더를 비공개 버킷으로 업로드하고 읽기 전용으로 마운트합니다:

bash

python

이미지에 TRL이 설치되어 있으므로 스크립트는 스크립트 헤더가 필요하지 않습니다. GRPOTrainer는 기본적으로 transformers를 사용하여 completions을 생성하므로, vLLM 서버 없이 단일 Job에서 실행됩니다. 더 빠른 생성을 위해 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

이미지에 설치된 TRL을 실행하려면 hf jobs run을 대신 사용하세요. 이 명령은 스크립트 헤더를 해석할 필요가 없이 이미지에서 명령을 직접 실행하므로, 이미지에 포함된 TRL이 실행됩니다. --는 명령과 Jobs 옵션을 구분하는 역할을 하며, 명령 자체에 옵션이 필요한 경우 항상 필요합니다:

bash

python

이미지는 세 가지 유형의 태그로 게시됩니다:

태그	목차
`X.Y.Z`	해당 버전이 릴리스될 때 빌드되는 TRL 릴리스
`latest`	가장 최근 릴리스
`dev`	모든 병합 시 재빌드되는 `main` 브랜치

dev를 사용하여 개발 버전을 실행합니다. 이는 main에 반영되었지만 아직 릴리스되지 않은 수정 사항을 테스트하는 데 유용합니다:

bash

python

Tags는 이미지에 설치된 항목만 선택하므로 hf jobs run의 경우에만 중요합니다. hf jobs uv run의 경우 버전은 스크립트 헤더에서 가져오므로, 어떤 TRL이 가져와지는지에 대해 태그는 차이를 만들지 않습니다.

두 가지를 결합하여 uv가 스크립트 헤더를 해석하는 동안 일부 import는 여전히 이미지에서 가져오도록 하려면 추가 플래그가 필요합니다. 해당 형태와 필요한 경로에 대해서는 이미지의 패키지를 재사용하고 UV로 의존성을 추가하기를 참조하세요.

Jobs는 Hugging Face Spaces 또는 Docker Hub의 Docker 이미지에서 실행되므로, 사용자 정의 이미지를 지정할 수도 있습니다:

bash

python

TRL Jobs 래퍼는 일부 모델에 대한 사전 설정 구성으로 Jobs에서 TRL 스크립트를 실행하며, 예를 들어 trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara와 같습니다.

Update on GitHub