구성

구성 (Configuration)

hf jobs로 Job을 실행할 때 인증, 인자 전달, 환경 변수, 볼륨, 하드웨어 플레이버(falvor) 등을 어떻게 구성하는지 알아볼게요.

--를 기준으로 Jobs 옵션과 명령·스크립트를 분리해서 유연하게 실행할 수 있어요.

출처: 문서

본문

인증

Job을 실행하려면 hf auth login으로 인증되어야 하고, Job을 시작·관리할 권한이 있는 토큰을 사용해야 해요.

또는 CLI에서 --token으로, Python에서 token 인자로 Hugging Face 토큰을 직접 전달할 수 있어요.

인자 전달하기

--를 사용해 Jobs 옵션과 명령·스크립트 및 그 인자를 구분해요. -- 뒤의 옵션(--help, --timeout 등)은 Jobs가 해석하지 않고 그대로 전달돼요. 이는 UV 및 Docker Jobs 모두에 적용돼요.

hf jobs uv run --flavor t4-small -- script.py --early-stopping-patience 3
               └─ Jobs option ┘    └─ script + arguments ─────────────┘

UV Jobs

UV로 실행하듯 UV 스크립트나 python 명령을 지정해요:

>>> hf jobs uv run train.py

>>> hf jobs uv run python -c 'print("Hello from the cloud!")'

hf jobs uv run 명령은 --with, --python 같은 UV 인자를 받아요. --with는 파이썬 의존성을, --python은 사용할 파이썬 버전을 지정해요:

>>> hf jobs uv run --with trl train.py
>>> hf jobs uv run --python 3.12 train.py

예를 들어 --로 명령에 인자를 전달할 수 있어요:

>>> hf jobs uv run --with trl-jobs -- trl-jobs sft --model_name Qwen/Qwen3-0.6B --dataset_name trl-lib/Capybara

모든 인자 목록은 CLI 문서와 UV Commands 문서에서 찾을 수 있어요.

기본적으로 UV Jobs는 ghcr.io/astral-sh/uv:python3.12-bookworm Docker 이미지로 실행되지만, UV가 설치된 이미지라면 --image <docker-image>로 다른 이미지를 사용할 수 있어요.

이미지 선택과 그 환경이 UV 의존성과 어떻게 상호작용하는지 이해하려면 Docker 이미지 사용을 참고해요.

스크립트에서 런치 구성 정의하기

특정 런타임(주어진 이미지, GPU 플레이버, 시스템 인터프리터)에서만 제대로 실행되는 스크립트는 옵션인 [tool.hf-jobs] 테이블(PEP 723 헤더)에 그 구성을 함께 담을 수 있어요:

# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# image   = "vllm/vllm-openai:unlimited-ocr"
# flavor  = "l4x1"
# python  = "/usr/bin/python3"
# secrets = ["HF_TOKEN"]
# ///

hf jobs uv run ocr.py는 그런 다음 그 이미지와 하드웨어에서 실행돼요. 일반적인 uv run은 [tool.*] 테이블이 PEP 723의 일부이고 도구들이 소유하지 않은 테이블을 건너뛰므로 이 테이블을 무시해요.

지원되는 키(모두 옵션): image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group, network_aliases. 이들은 같은 이름의 플래그에 매핑돼요. 스크립트의 값은 기본값이에요: 명시적 플래그가 항상 우선하며, env, secrets, labels, volumes는 항목별로 병합되므로 -e와 -v가 스크립트가 선언한 것에 추가돼요. 알 수 없는 키는 오류이고, secrets는 이름만 나열하며 값은 스크립트를 실행하는 사람의 환경에서 오기 때문에 로컬에 설정되지 않은 시크릿도 오류예요.

--dry-run을 사용하면 제출하지 않고 해석된 구성을 출력하며, 스크립트에서 온 값은 (from script)로 표시돼요. 전체 병합 규칙은 hf CLI 가이드를 참고해요.

[!WARNING] 이 테이블은 hf CLI만 읽어요. run_uv_job()과 create_scheduled_uv_job()은 이를 무시하므로 Python에서는 image=, flavor=, ... 를 명시적으로 전달해요.

Docker Jobs

docker로 실행하듯 Docker 이미지와 실행할 명령을 지정해요:

>>> hf jobs run ubuntu echo "Hello from the cloud!"

여기서 --help는 Jobs 도움말이 아니라 Python에 도달해요:

>>> hf jobs run --flavor cpu-basic python:3.12 -- python --help

모든 인자 목록은 CLI 문서에서 찾을 수 있어요.

기존 이미지와 Docker Spaces가 빌드한 이미지를 사용하는 예시는 Docker 이미지 사용을 참고해요.

환경 변수와 시크릿

내장 환경 변수

Spaces의 내장 환경 변수와 유사하게, Jobs는 컨테이너 안에 다음 환경 변수를 자동으로 제공해요:

변수	설명
`JOB_ID`	현재 job의 고유 식별자 (예: `699d874f1aad19adb8aaeadc`). UI와 job URL에 표시되는 것과 같은 ID예요.
`ACCELERATOR`	사용 가능한 가속기 유형 (예: `t4-medium`, `a10g-small`, `a100x4`), CPU 전용 job은 `none`.
`CPU_CORES`	job에 할당된 CPU 코어 수.
`MEMORY`	job에 할당된 메모리 양 (예: `8Gi`).
`HF_NETWORK_GROUP_HOSTNAME`	job의 네트워크 그룹에 속한 모든 job으로 해석되는 호스트네임. job이 하나를 선언할 때만 설정됨.
`HF_NETWORK_GROUP_PREFIX`	그룹 구성원이 주장하는 별칭의 호스트네임을 얻기 위해 별칭 앞에 붙이는 접두어 (예: `${HF_NETWORK_GROUP_PREFIX}master`). job이 네트워크 그룹을 선언할 때만 설정됨.

이 변수들을 사용해 출력을 추적하거나, 코드를 사용 가능한 리소스에 맞추거나, 현재 job을 프로그래밍 방식으로 참조할 수 있어요:

# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"

사용자 정의 환경 변수

job에 환경 변수를 전달할 수 있어요:

# Pass environment variables
>>> hf jobs uv run -e FOO=foo -e BAR=bar python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass an environment from a local .env file
>>> hf jobs uv run --env-file .env python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'

# Pass secrets - they will be encrypted server side
>>> hf jobs uv run -s MY_SECRET=psswrd python -c 'import os; print(os.environ["MY_SECRET"])'

# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs uv run --secrets-file .env.secrets python -c 'import os; print(os.environ["MY_SECRET"])'

[!TIP] --secrets HF_TOKEN을 사용해 로컬 Hugging Face 토큰을 암묵적으로 전달해요. 이 구문에서 시크릿은 환경 변수에서 가져와요. HF_TOKEN의 경우 환경 변수가 설정되지 않았다면 Hugging Face 홈 폴더에 있는 토큰 파일을 읽을 수 있어요.

볼륨

-v 또는 --volume을 사용해 Hugging Face 리포지토리(모델, 데이터셋), Storage Buckets 또는 로컬 디렉터리를 job 컨테이너의 볼륨으로 마운트해요. Hub 소스는 hf:// URL 스킴을 사용해요: hf://[TYPE/]SOURCE:/MOUNT_PATH[:ro]; 로컬 디렉터리는 소스로 직접 전달돼요.

[!TIP] 마운트된 파일은 지연(lazily) 가져와지기 때문에 마운트하면 job이 로컬 디스크보다 훨씬 큰 데이터셋으로 작업할 수 있어요. 큰 데이터를 마운트·스트리밍·처리하는 방법은 대규모 데이터셋 처리를 참고해요.

볼륨 유형:

유형	예
모델 리포지토리	`-v hf://openai/gpt-oss-120b:/model`
데이터셋 리포지토리	`-v hf://datasets/stanfordnlp/imdb:/data`
스토리지 버킷	`-v hf://buckets/username/my-bucket:/mnt`
하위 폴더	`-v hf://datasets/org/my-dataset/train:/data`
로컬 디렉터리	`-v ./training-data:/data`

그런 다음 마운트된 볼륨을 컨테이너 안의 로컬 디렉터리처럼 사용해요:

# Mount a dataset and query it with DuckDB
>>> hf jobs run -v hf://datasets/stanfordnlp/imdb:/dataset \
...     duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"

# Mount a bucket to save training checkpoints
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
...     sft.py --output-dir /training-outputs/training-v3-final

-v 플래그를 반복해서 여러 볼륨을 마운트할 수 있어요:

>>> hf jobs run -v hf://datasets/username/my-dataset:/data -v hf://buckets/username/my-bucket:/output \
...     python:3.12 python script.py

모델과 데이터셋은 항상 읽기 전용으로 마운트돼요. 스토리지 버킷은 기본적으로 읽기-쓰기라 출력, 체크포인트, 중간 결과를 저장하는 데 유용해요. 버킷을 읽기 전용으로 마운트하려면 :ro를 사용해요:

>>> hf jobs run -v hf://buckets/username/my-bucket:/mnt:ro python:3.12 ls /mnt

로컬 디렉터리

로컬 디렉터리를 소스로 전달하면 Job이 시작되기 전에 비공개 jobs-artifacts Storage Bucket(자동 생성)에 동기화된 후 컨테이너에 마운트돼요. 로컬 디렉터리는 기본적으로 읽기 전용으로 마운트되고, 출력을 쓰려면 :rw를 사용해요:

>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py

같은 디렉터리를 다시 동기화하면 새 파일이나 수정된 파일만 업로드돼요. Job이 읽기-쓰기 볼륨에 쓴 파일을 가져오려면 Job이 끝난 후 해당 버킷 폴더를 다시 동기화해요 — CLI가 Job 시작 시 정확한 hf buckets sync 명령을 출력해요. 예약 job도 동작해요: 디렉터리는 스케줄 생성 시 한 번 동기화되고, 매 트리거마다 같은 폴더를 마운트해요. Python에서는 sync_job_volume을 사용해요.

Python에서는 Volume 클래스를 사용해요:

from huggingface_hub import Volume, run_job

job = run_job(
    image="python:3.12",
    command=["python", "-c", "import os; print(os.listdir('/data'))"],
    volumes=[
        Volume(type="dataset", source="username/my-dataset", mount_path="/data"),
        Volume(type="bucket", source="username/my-bucket", mount_path="/output"),
    ],
)

[!NOTE] 볼륨 마운트에는 huggingface_hub >= 1.8.0이 필요해요. 자세한 내용은 Python 클라이언트 문서와 설치 가이드를 참고해요.

하드웨어 플레이버

flavor 인자로 GPU 또는 TPU에서 job을 실행해요. 예를 들어 PyTorch job을 A10G GPU에서 실행하려면:

>>> hf jobs uv run --with torch --flavor a10g-small python -c "import torch; print(f'This code ran with the following GPU: {torch.cuda.get_device_name()}')"

이 실행 결과는 다음과 같아요!

This code ran with the following GPU: NVIDIA A10G

trl/scripts/sft.py 같은 파인튜닝 스크립트를 실행하는 또 다른 예시예요:

>>> hf jobs uv run --with trl --flavor a10g-small -s HF_TOKEN -- sft.py --model_name_or_path Qwen/Qwen2-0.5B ...

[!TIP] Hugging Face 인프라에서 TRL로 모델 학습 job을 실행하는 종합적인 가이드는 TRL Jobs Training 문서를 확인해요. 파인튜닝 레시피, 하드웨어 선택, 효율적 학습 모범 사례를 다뤄요.

hf jobs hardware 명령으로 사용 가능한 --flavor 옵션 목록을 확인해요(기본값은 cpu-basic):

>>> hf jobs hardware
name             pretty name             cpu       ram      storage   accelerator               cost/min  cost/hour
cpu-basic        CPU Basic               2 vCPU    16 GB    50 GB                               $0.0002   $0.01
cpu-upgrade      CPU Upgrade             8 vCPU    32 GB    50 GB                               $0.0005   $0.03
cpu-performance  CPU Performance         32 vCPU   256 GB   1024 GB                             $0.0317   $1.90
cpu-xl           CPU XL                  16 vCPU   124 GB   1000 GB                             $0.0167   $1.00
t4-small         Nvidia T4 - small       4 vCPU    15 GB    50 GB     1x T4 (16 GB)             $0.0067   $0.40
t4-medium        Nvidia T4 - medium      8 vCPU    30 GB    100 GB    1x T4 (16 GB)             $0.0100   $0.60
a10g-small       Nvidia A10G - small     4 vCPU    15 GB    110 GB    1x A10G (24 GB)           $0.0167   $1.00
a10g-large       Nvidia A10G - large     12 vCPU   46 GB    200 GB    1x A10G (24 GB)           $0.0250   $1.50
a10g-largex2     2x Nvidia A10G - large  24 vCPU   92 GB    1000 GB   2x A10G (48 GB)           $0.0500   $3.00
a10g-largex4     4x Nvidia A10G - large  48 vCPU   184 GB   2000 GB   4x A10G (96 GB)           $0.0833   $5.00
a100-large       Nvidia A100 - large     12 vCPU   142 GB   1000 GB   1x A100 (80 GB)           $0.0417   $2.50
a100x4           4x Nvidia A100          48 vCPU   568 GB   4000 GB   4x A100 (320 GB)          $0.1667   $10.00
a100x8           8x Nvidia A100          96 vCPU   1136 GB  8000 GB   8x A100 (640 GB)          $0.3333   $20.00
h200             Nvidia H200             23 vCPU   256 GB   3000 GB   1x H200 (141 GB)          $0.0833   $5.00
h200x2           Nvidia H200             46 vCPU   512 GB   6000 GB   2x H200 (282 GB)          $0.1667   $10.00
h200x4           Nvidia H200             92 vCPU   1024 GB  12000 GB  4x H200 (564 GB)          $0.3333   $20.00
h200x8           Nvidia H200             184 vCPU  2048 GB  24000 GB  8x H200 (1128 GB)         $0.6667   $40.00
rtx-pro-6000     Nvidia RTX PRO 6000     23 vCPU   256 GB   475 GB    1x RTX PRO 6000 (96 GB)   $0.0458   $2.75
rtx-pro-6000x2   Nvidia RTX PRO 6000     46 vCPU   512 GB   950 GB    2x RTX PRO 6000 (192 GB)  $0.0917   $5.50
rtx-pro-6000x4   Nvidia RTX PRO 6000     92 vCPU   1024 GB  1900 GB   4x RTX PRO 6000 (384 GB)  $0.1833   $11.00
rtx-pro-6000x8   Nvidia RTX PRO 6000     184 vCPU  2048 GB  3800 GB   8x RTX PRO 6000 (768 GB)  $0.3667   $22.00
l4x1             1x Nvidia L4            8 vCPU    30 GB    400 GB    1x L4 (24 GB)             $0.0133   $0.80
l4x4             4x Nvidia L4            48 vCPU   186 GB   3200 GB   4x L4 (96 GB)             $0.0633   $3.80
l40sx1           1x Nvidia L40S          8 vCPU    62 GB    380 GB    1x L40S (48 GB)           $0.0300   $1.80
l40sx4           4x Nvidia L40S          48 vCPU   382 GB   3200 GB   4x L40S (192 GB)          $0.1383   $8.30
l40sx8           8x Nvidia L40S          192 vCPU  1534 GB  6500 GB   8x L40S (384 GB)          $0.3917   $23.50

포트 노출하기

Jobs는 --expose <port>(CLI) 또는 expose=[<port>](Python API)를 사용해 공용 jobs 프록시를 통해 컨테이너 포트를 노출할 수 있어요. 노출된 각 포트는 https://<job_id>--<port>.hf.jobs에서 접근할 수 있고, job의 네임스페이스에 대한 read 접근 권한이 있는 HF 토큰이 필요해요:

curl -H "Authorization: Bearer ***" https://<job_id>--<port>.hf.jobs/

이는 hf jobs run, hf jobs uv run 및 그 예약 변형에서 동작해요. 플래그를 반복해 여러 포트를 노출하거나(--expose 8000 --expose 8001), 목록에 여러 포트를 전달해요(expose=[8000, 8001]).

[!NOTE] 노출된 포트는 job 실행 중에만 job의 하드웨어 가격 위에 소액의 고정 시간당 요금으로 청구돼요. 자세한 내용은 가격 페이지를 참고해요.

CLI

# Expose a web server running on port 8000
>>> hf jobs run --expose 8000 python:3.12 python -m http.server 8000
✓ Job started
  id: 6a2aa7cec4f53f9fc5aa4cff
  url: https://huggingface.co/jobs/Wauplin/6a2aa7cec4f53f9fc5aa4cff
Hint: Exposed ports are reachable at (requires an HF token with read access to the job):
  https://6a2aa7cec4f53f9fc5aa4cff--8000.hf.jobs
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["python", "-m", "http.server", "8000"], expose=[8000])
>>> job.status.expose_urls
['https://6a2ab384c4f53f9fc5aa4d4f--8000.hf.jobs']

SSH

실행 중인 Job에 인터랙티브 SSH 세션을 열어 컨테이너 안에서 직접 디버그·검사·작업할 수 있어요. job 생성 시 --ssh(CLI) 또는 ssh=True(Python API)로 활성화한 다음, hf jobs ssh <job_id>로 연결해요.

Job의 네임스페이스에 대한 Write 접근 권한이 있는 사용자만 허용돼요(즉 Job 생성자 또는 Write 권한이 있는 소유 조직 구성원). 인증은 https://huggingface.co/settings/keys에 등록된 SSH 공개 키로 수행돼요.

SSH는 hf jobs run과 hf jobs uv run에서 사용 가능해요. 예약 job에서는 지원되지 않아요.

CLI

# Start a job with SSH enabled
>>> hf jobs run --ssh --detach --timeout 10m python:3.12 sleep infinity
✓ Job started
  id: 6a2bd1f1871c005b5352ad31
  url: https://huggingface.co/jobs/Wauplin/6a2bd1f1871c005b5352ad31
Hint: Use `hf jobs ssh 6a2bd1f1871c005b5352ad31` to open an SSH session into the job.

# Open an SSH session into the job
>>> hf jobs ssh 6a2bd1f1871c005b5352ad31

실행하지 않고 SSH 명령을 출력하거나(--dry-run), 특정 identity 파일을 전달할 수도 있어요(-i/--identity-file):

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 --dry-run
ssh [email protected]

>>> hf jobs ssh 6a2bd1f1871c005b5352ad31 -i ~/.ssh/id_ed25519

Python

>>> from huggingface_hub import run_job
>>> job = run_job(image="python:3.12", command=["sleep", "infinity"], ssh=True)
>>> job.status.ssh_url
'ssh://[email protected]'

그런 다음 터미널에서 hf jobs ssh <job_id>로 연결하거나 ssh <job_id>@ssh.hf.jobs로 직접 연결해요.

포트 포워딩

이건 일반 SSH 연결이므로 SSH의 -L과 -R 플래그로 내 컴퓨터와 Job 사이에 포트를 포워딩할 수 있어요. ssh로 직접 연결해요(정확한 목적지는 hf jobs ssh <job_id> --dry-run으로 얻어요) 포워딩 플래그를 추가해요.

-L(로컬 포워딩)을 사용해 내 컴퓨터에서 Job 안에서 실행 중인 서비스에 접근해요. 예를 들어 학습 Job에서 시작한 TensorBoard에 접근하려면:

# Forward local port 6006 to the Job's TensorBoard on port 6006
>>> ssh -L 6006:localhost:6006 [email protected]

그런 다음 브라우저에서 http://localhost:6006을 열어요.

-R(원격 포워딩)을 사용해 Job이 내 컴퓨터에서 실행 중인 서비스에 접근하도록 해요. 예를 들어 로컬 데이터베이스나 API를 Job에 노출하려면:

# Make your local port 8080 reachable from inside the Job on port 8080
>>> ssh -R 8080:localhost:8080 [email protected]

네트워크 그룹

Jobs는 --network-group <name>(CLI) 또는 network_group="<name>"(Python API)으로 네트워크 그룹에 참여할 수 있어요. 같은 네임스페이스·리소스 그룹에서 그룹을 공유하는 Jobs는 모든 포트에서 서로에게 도달할 수 있어요: HF_NETWORK_GROUP_HOSTNAME은 모든 구성원으로 해석되고, ${HF_NETWORK_GROUP_PREFIX}<alias>는 --network-alias <alias>(CLI) 또는 network_aliases=[<alias>](Python API)로 별칭을 주장한 구성원으로 해석돼요.

이는 hf jobs run과 hf jobs uv run에서 동작해요. 구성원은 준비되기 전에 해석 가능하므로 재시도와 함께 연결해요. 그룹 이름과 별칭은 소문자 영숫자와 대시로, 최대 46 및 34자예요; job의 별칭은 고유해야 해요.

CLI

# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000

# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'

Python

>>> from huggingface_hub import run_job
>>> server = run_job(
...     image="python:3.12",
...     command=["python", "-m", "http.server", "8000"],
...     network_group="train",
...     network_aliases=["master"],
... )
>>> client = run_job(
...     image="python:3.12",
...     command=["sh", "-c", 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'],
...     network_group="train",
... )

멀티노드 학습 프레임워크는 별칭을 rendezvous 호스트로 사용할 수 있어요. 예: torchrun --master_addr "${HF_NETWORK_GROUP_PREFIX}master".

타임아웃

Jobs에는 기본 타임아웃(30분)이 있고, 이후 자동으로 중지돼요. 모델 학습 같은 장기 실행 작업을 할 때 중요하게 알아야 해요.

job 실행 시 --timeout 파라미터로 커스텀 타임아웃 값을 지정할 수 있어요. 타임아웃은 두 가지 방식으로 지정할 수 있어요:

숫자로 (초로 해석):

--timeout에 초 단위 숫자를 전달해요(여기서 2시간 = 7200초):

>>> hf jobs uv run --timeout 7200 --with torch --flavor a10g-large train.py

시간 단위 문자열로:

또는 --timeout에 다른 시간 단위를 사용해요:

>>> hf jobs uv run --timeout 2h --with torch --flavor a10g-large train.py

다른 예시:

--timeout 30m    # 30 minutes
--timeout 1.5h   # 1.5 hours
--timeout 1d     # 1 day
--timeout 3600s  # 3600 seconds

지원되는 시간 단위:

s - 초
m - 분
h - 시간
d - 일

[!WARNING] 타임아웃을 지정하지 않으면 기본 타임아웃이 job에 적용돼요. 몇 시간이 걸릴 수 있는 모델 학습 같은 장기 실행 작업은 예상치 못한 중단을 피하기 위해 적절한 타임아웃을 설정해야 해요.

네임스페이스

--namespace 인자로 조직 계정 아래에서 Jobs를 실행해요. 조직 계정 아래에서 Jobs를 시작·관리할 권한이 있는 토큰으로 로그인했는지 확인해요.

>>> hf jobs uv run --namespace my-org-name python -c "print('Running in an org account')"

올바른 권한의 토큰을 직접 전달할 수도 있어요:

>>> hf jobs uv run --namespace my-org-name --token hf_xxx python -c "print('Running in an org account')"

라벨

-l 또는 --label로 Job에 메타데이터를 추가하기 위해 하나 이상의 라벨을 붙여요. 나중에 이 메타데이터로 웹사이트나 CLI에서 Jobs를 필터링할 수 있어요.

--label my-label로 라벨을 추가하거나 --label key=value로 키-값 라벨을 추가해요. 키와 값은 문자, 숫자, -, _를 포함할 수 있어요. 예:

hf jobs uv run --label fine-tuning --label model=Qwen3-06B --label dataset=Capybara ...

같은 key를 여러 번 사용하면 마지막 key=value가 이전 key 라벨을 덮어쓰고 버려요.

Job 이름 짓기

UI에서 찾고 식별하기 쉽도록 Job에 이름을 붙여요. 이름은 name 라벨로 저장되며 고유할 필요가 없어요. UI에서 Jobs는 이름별로 그룹화돼요.

hf jobs run --name daily-report python:3.12 python report.py

--name을 전달하지 않으면 Job은 Docker 이미지나 스크립트 이름에 명령의 짧은 해시를 더한 이름을 가져요. 그래서 같은 명령 재실행은 이름을 공유하고 다른 명령은 다른 이름을 얻어요(예: python:3.12에서 실행되는 Job의 python-3-12-6b9d662c).

라벨 업데이트

hf jobs labels로 기존 Job의 라벨을 업데이트해요. --label을 전달하면 기존 라벨을 모두 대체하고, --name만 전달하면 유지해요:

# Replace the labels on a Job
hf jobs labels <job_id> --label env=prod --label team=ml

# Name an existing Job (keeps its other labels)
hf jobs labels <job_id> --name daily-report

# Remove all labels from a Job
hf jobs labels <job_id> --clear

더 알아보기 (Learn more)

--로 Jobs 옵션과 명령 인자를 구분해 전달해요.
볼륨(-v)으로 Hub의 대규모 데이터를 지연 마운트하고, --flavor로 GPU를 선택해요.
Jobs 관리와 Jobs 개요 문서에서 전체 워크플로를 확인해 보세요.