Hugging Face's logo

Hub documentation

Jobs에서 모델 학습

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Jobs에서 모델 학습

This page shows how to fine-tune and train models on Jobs, with a library’s script or your own. Every example is capped to a short run that finishes in minutes on a single A10G, for around $0.10 of compute. The Job runs on Hugging Face’s machines, so it keeps going if you close your terminal or your laptop. If you have not run a Job before, Quickstart covers installing the CLI, logging in and the credits a Job needs.

첫 실행

이 명령은 2,000개의 Food-101 이미지로 이미지 분류기를 미세 조정하고 약 3분 만에 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 섹션에서는 전체 실행 과정과 다른 예제 스크립트를 다룹니다.

학습 Job의 구성 방식

…

  • 실행 대상. hf jobs uv run으로 실행되는 uv 스크립트입니다. 상단 근처의 주석 블록(# /// script, PEP 723 형식)에 의존성을 선언하는 Python 스크립트로, uv가 이를 새로운 환경에 설치합니다. TRL 섹션에 예시가 있습니다. 또는 hf jobs run으로 실행되는 라이브러리 Docker 이미지입니다. 이미지에 이미 설치된 라이브러리를 사용합니다. 라이브러리가 pip로 설치되는 경우 uv 스크립트로 시작하세요. 컴파일된 의존성이 포함된 이미지를 제공하거나, 문서에서 그렇게 지시하는 경우 이미지를 사용하세요. 트레이드오프에 대해서는 Docker 이미지 사용을 참고하세요.
  • 토큰. 작업에는 기본적으로 Hugging Face 토큰이 제공되지 않습니다. -s HF_TOKEN을 사용하면 사용자의 토큰을 시크릿으로 전달하여 실행 중에 모델을 push하고 게이트드 또는 비공개 입력을 읽을 수 있습니다. 다른 시크릿도 동일한 방식으로 전달되며, 예를 들어 -s WANDB_API_KEY가 있습니다.
  • 하드웨어 및 시간. --flavor은 GPU를 선택합니다. --timeout은 시간 제한을 설정하며, 기본값은 30분입니다. 시간 제한에 도달한 실행은 중단되므로, 예상 실행 시간보다 --timeout을 더 길게 설정하세요. Hardware flavor 및 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 섹션에 예시가 하나 있습니다.

  • 로컬 import와 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 또는 스크립트 헤더에서 의존성을 설치하며, 로컬 import와 상대 경로는 변경 없이 작동합니다. 로컬 디렉터리를 참조하세요.

  • 시스템 패키지나 CUDA toolkit이 필요한 코드. 이미지를 한 번 빌드한 후 hf jobs run으로 실행합니다. Docker Space로 직접 이미지 빌드하기를 참고하세요.

스크립트 헤더의 [tool.hf-jobs] 테이블에 자체 런치 구성을 포함할 수도 있으며, TRL 섹션에서 확인하실 수 있습니다. 스크립트에서 런치 구성 정의를 참조하세요. 동일한 명령어는 구성에서 다루는 run_uv_job() 및 run_job()을 통해 Python에서도 사용할 수 있습니다.

긴 실행 전 체크

캡을 제거하기 전에, 몇 가지 확인을 통해 실패한 실행을 방지할 수 있습니다.

  • 먼저 스모크 테스트를 실행하세요. 이 페이지의 예시처럼, 작은 flavor에서 step 상한을 설정하여 명령을 실행합니다. 이를 통해 의존성이 설치되고, 데이터가 로드되며, 모델이 학습되고, push가 정상적으로 작동하는지 확인할 수 있습니다. 그런 다음 상한을 제거하고 전체 실행을 시작합니다.
  • 데이터가 디스크에 맞는지 확인하세요. 각 플레버는 가격 및 청구의 Ephemeral Storage 열에 나열된 고정 디스크를 사용합니다. 가중치, 데이터셋 및 저장된 체크포인트는 이 디스크를 공유합니다. 디스크 용량을 초과하는 데이터셋은 다운로드 대신 스트리밍하거나 마운트할 수 있습니다. 대형 데이터셋 처리를 참조하세요.
  • 실행 시간을 추정합니다. 스모크 테스트의 최종 train_* 지표에는 train_steps_per_second가 포함되어 있으며, trainer는 시작 시 총 스텝 수를 출력합니다. 이 두 값으로 전체 실행의 학습 시간을 계산할 수 있습니다. Job은 의존성 설치와 모델 다운로드에도 시간을 소요하므로, --timeout을 해당 시간보다 여유 있게 설정하세요. 각 flavor별 요금은 가격 및 청구에서 확인할 수 있습니다.
  • 멀티 GPU 플레버에서는 GPU당 하나의 프로세스를 시작합니다. x2, x4 또는 x8로 끝나는 플레버는 한 대의 머신에 여러 개의 GPU를 제공합니다. 실행 방식이 이를 활용하도록 확인하세요. Transformers와 TRL은 TRL 섹션에 나와 있듯이 accelerate launch가 필요합니다. Axolotl은 자체적으로 처리합니다. 단순한 python train.py는 하나의 GPU만 사용하며, Trainer는 GPU당 하나의 프로세스보다 느린 DataParallel로 폴백됩니다.
  • 다시 실행할 경우 고정하세요. 스크립트 URL은 main 대신 커밋에, 이미지는 latest 대신 특정 태그에 고정하세요. 그러면 다시 실행할 때 동일한 소프트웨어를 사용합니다. 아래 스크립트 URL은 main을 추적하므로, 다시 실행하기 전에 커밋을 고정하세요.
  • 에 Checkpoint long runs하여 타임아웃이나 크래시가 발생해도 실행이 손실되지 않도록 하세요. After it ends를 참조하세요.

실행되는 동안

hf jobs run과 hf jobs uv run은 모두 로그를 스트리밍하고 실행이 끝날 때까지 터미널을 유지합니다. Ctrl+C는 로그 스트림만 중지합니다. Job은 완료되거나 hf jobs cancel <job_id>로 중지할 때까지 계속 실행됩니다.

긴 실행의 경우, -d(detach)를 전달하여 Job ID를 즉시 반환받은 후, hf jobs logs -f <job_id>로 실행을 추적하고 hf jobs stats <job_id>로 GPU가 사용 중임을 확인합니다. detach된 실행 후, hf jobs wait <job_id>는 Job이 종료될 때까지 차단되며 실패 시 0이 아닌 값을 반환합니다. 이는 스크립트나 에이전트 루프에 필요한 동작입니다. detach되지 않은 실행은 이미 이 동작을 수행합니다. Job 관리를 참조하세요.

Job logs는 손실 값을 텍스트로 출력합니다. 곡선을 보려면 trackio와 같은 실험 트래커를 trainer에 지정하고, 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입니다. 마운트 옵션에 대해서는 Volumes을 참조하세요.

실패한 실행을 읽기. 실패한 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을 제거하세요. Food-101 학습 이미지 75,000개에 대해 3에포크를 학습하는 데 a10g-small에서 약 1시간이 소요되며, 해당 플레인의 요금 기준으로 약 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

이 과정은 약 6분 정도 소요됩니다. 전체 실행을 하려면 --max_steps를 제거하세요. Capybara 3에포크는 스크립트의 기본 설정이며, a10g-small에서 약 2시간 20분이 소요되므로 --timeout 값을 함께 높여야 합니다. TRL 자체 문서에서는 더 빠른 a100-large를 사용합니다.

huggingface/trl 이미지를 실행하는 방법과 직접 TRL 스크립트를 작성하는 방법을 포함한 전체 가이드는 TRL 문서의 Training with Jobs에 있습니다.

여러 GPU를 사용하는 경우, accelerate가 포함된 TRL 이미지로 전환하고 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 3에포크)은 A10G 2대에서 약 1시간 35분이 소요됩니다.

자체 TRL 스크립트를 작성할 때, 런치 구성이 스크립트와 함께 이동할 수 있습니다. 헤더의 [tool.hf-jobs] 테이블에서 flavor, timeout, secrets를 설정합니다:

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

이 과정은 약 5분 만에 완료되며 LoRA 어댑터를 푸시합니다. 전체 에포크를 실행하려면 --max-steps 50을 --num-epochs 1로 교체하고 --timeout을 높여야 합니다. 자세한 내용은 Hugging Face 블로그의 Fine-tune with Unsloth on 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

약 7분 만에 완료되며 어댑터가 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 스크립트 대부분은 스크립트 헤더에 의존성을 선언하므로, Transformers 스크립트와 마찬가지로 GitHub URL에서 바로 Jobs에서 실행됩니다. 다음 명령은 개의 사진 5장으로 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

이 과정은 약 5분 만에 완료되며 LoRA를 push합니다. 실제 실행을 위해서는 --max_train_steps 값을 높여야 하며, FLUX.2 README에서는 500을 사용합니다. 해당 폴더의 다른 README 파일들은 나머지 모델과 메모리 옵션을 다룹니다. 스크립트 상단의 # /// script 블록을 확인하세요. 이 블록이 없는 스크립트(예: SDXL 스크립트)의 경우, --with로 의존성을 전달해야 합니다.

더 깊이 파고들기

  • 학습한 모델을 평가 실행이나 데모를 위해 임시 엔드포인트 뒤에 배치하려면 Serve Models을 사용하세요. Inference Endpoints는 지속적으로 유지되는 엔드포인트를 실행합니다.
  • 비밀 정보, 환경 변수, 볼륨 및 스크립트가 자체적인 flavor와 timeout을 가질 수 있도록 하는 [tool.hf-jobs] 테이블에 대한 구성
  • Manage Jobs를 사용하여 Job을 나열, 검사, 디버깅 및 취소합니다.
  • 디스크에 맞지 않는 데이터를 스트리밍 및 마운트하기 위해 대형 데이터셋 처리를 사용하세요.
  • 타이머에 따라 학습 명령을 실행하려면 Schedule Jobs를 사용하세요.
  • 커뮤니티 작성물을 위한 예제 및 튜토리얼에는 비전-언어 파인튜닝과 학습 실행에 대규모 데이터셋을 스트리밍하는 내용이 포함되어 있습니다.
  • 코딩 에이전트에서 Jobs 사용: hf CLI 스킬을 사용하면 Claude Code, Codex, Cursor가 이러한 실행을 시작하고 모니터링할 수 있습니다.
Update on GitHub

←모델 서빙 예제 및 튜토리얼→