Jobs 관리하기
Jobs 관리하기
hf jobs CLI로 Job을 나열·필터링·모니터링·검사·대기·취소하는 방법을 알아볼게요.
hf jobs ps, stats, inspect, logs, wait, cancel 같은 명령으로 Job 라이프사이클을 제어할 수 있어요.
출처: 문서
본문
Jobs 나열하기
Jobs 페이지나 조직 Jobs 페이지(사용자/조직 페이지 > settings > Jobs)에서 Job 목록을 찾을 수 있어요:
Hugging Face CLI에서도 사용할 수 있어요. 실행 중인 Jobs 목록은 hf jobs ps로 보여주고, 모든 Jobs를 보려면 -a를 사용해요:
>>> hf jobs ps
JOB ID IMAGE/SPACE COMMAND CREATED STATUS
------------ ---------------- ----------- ------------------- -------
69402ea6c... ghcr.io/astra... uv run p... 2025-12-15 15:52:06 RUNNING
>>> hf jobs ps -a
JOB ID IMAGE/SPACE COMMAND CREATED STATUS
------------ ---------- --------------- ------------------- ---------
69402ea6c... ghcr.io... uv run pytho... 2025-12-15 15:52:06 RUNNING
693b06b8c... ghcr.io... uv run pytho... 2025-12-11 18:00:24 CANCELED
693b069fc... ghcr.io... uv run pytho... 2025-12-11 17:59:59 ERROR
693aef401... ghcr.io... uv run pytho... 2025-12-11 16:20:16 COMPLETED
693aee76c... ubuntu echo Hello f... 2025-12-11 16:16:54 COMPLETED
693ae8e3c... python:... python -c pr... 2025-12-11 15:53:07 COMPLETED
조직 namespace를 지정해 조직 아래의 Jobs를 나열할 수 있어요:
>>> hf jobs ps --namespace <my-org-name>
Jobs 필터링
Jobs 목록 위에 자주 쓰는 라벨과 각각을 사용하는 Job 수가 표시돼요; 하나를 클릭해 필터링하거나 아무 key=value 라벨을 입력할 수 있어요:
CLI에서는 --status로 상태별, --label key=value로 라벨별 필터링해요. --label을 반복해서 한 번에 여러 라벨을 요구할 수 있어요:
# Jobs that ended in error
>>> hf jobs ps --status error
# Running or scheduling Jobs with a given label
>>> hf jobs ps --status running,scheduling --label env=prod
# All Jobs (any status) that have both labels
>>> hf jobs ps -a --label model=Qwen3-06B --label dataset=Capybara
# A label added without a value (`--label fine-tuning`) is matched with a trailing "="
>>> hf jobs ps -a --label fine-tuning=
--name으로 이름별로 필터링할 수 있어요. --label name=<name>의 단축어로, 예를 들어 이름 붙은 Job의 모든 실행을 나열해요:
>>> hf jobs ps -a --name daily-report
JOB_ID NAME IMAGE/SPACE COMMAND CREATED STATUS RUNTIME
----------- ------------ ----------- ------------ ------------ --------- -------
6a9042c2... daily-report python:3.12 python -c... 2026-08-2... COMPLETED 0s
6a904162... daily-report python:3.12 python -c... 2026-08-2... CANCELED --
[!TIP] 기본적으로
hf jobs ps는 실행·예약 중인 Jobs를 보여줘요. 모든 상태를 보려면-a를 사용하고,-a는--status와 함께 쓸 수 없어요.
리소스 사용량 모니터링
hf jobs stats로 실행 중인 Jobs의 CPU, 메모리, 네트워크, GPU(가 있다면) 사용 통계를 얻을 수 있어요:
>>> hf jobs stats
JOB ID CPU % NUM CPU MEM % MEM USAGE NET I/O GPU UTIL % GPU MEM % GPU MEM USAGE
------------------------ ----- ------- ----- ---------------- --------------- ---------- --------- ---------------
695e83c5d2f3efac77e8cf18 8% 12.0 7.18% 10.9GB / 152.5GB 0.0bps / 0.0bps 100% 31.92% 25.9GB / 81.2GB
Job id를 하나 또는 여러 개 지정해 특정 Jobs의 통계만 보여줄 수 있어요:
>>> hf jobs stats [job-ids]...
Job 검사하기
Job 페이지에서 Job의 상태 로그를 볼 수 있어요:
또는 CLI로:
>>> hf jobs inspect 693994e21a39f67af5a41ad0
[
{
"id": "693994e21a39f67af5a41ad0",
"created_at": "2025-12-10 15:42:26.835000+00:00",
"docker_image": "ghcr.io/astral-sh/uv:python3.12-bookworm",
"space_id": null,
"command": ["bash", "-c", "python -c \"import urllib.request; import os; from pathlib import Path; o = urllib.request.build_opener(); o.addheaders = [(\\\"Authorization\\\", \\\"Bearer \\\" + os.environ[\\\"UV_SCRIPT_HF_TOKEN\\\"])]; Path(\\\"/tmp/script.py\\\").write_bytes(o.open(os.environ[\\\"UV_SCRIPT_URL\\\"]).read())\" && uv run --with trl /tmp/script.py"],
"arguments": [],
"environment": {"UV_SCRIPT_URL": "https://huggingface.co/datasets/lhoestq/hf-cli-jobs-uv-run-scripts/resolve/728cc5682eb402d7ffe66a2f6f97645b34cb08dd/train.py"},
"secrets": ["HF_TOKEN", "UV_SCRIPT_HF_TOKEN"],
"flavor": "a100-large",
"status": {"stage": "COMPLETED", "message": null},
"owner": {"id": "5e9ecfc04957053f60648a3e", "name": "lhoestq", "type": "user"},
"endpoint": "https://huggingface.co",
"url": "https://huggingface.co/jobs/lhoestq/693994e21a39f67af5a41ad0"
}
]
그리고 로그는:
>>> hf jobs logs 693994e21a39f67af5a41ad0
Downloading nvidia-cuda-nvrtc-cu12 (84.0MiB)
Downloading numpy (15.8MiB)
Downloading nvidia-cuda-cupti-cu12 (9.8MiB)
Downloading tokenizers (3.1MiB)
Downloading nvidia-cusolver-cu12 (255.1MiB)
Downloading nvidia-cufft-cu12 (184.2MiB)
Downloading transformers (11.4MiB)
Downloading setuptools (1.1MiB)
...
조직 namespace를 지정해 조직 아래의 Job을 검사할 수 있어요:
hf jobs inspect --namespace <my-org-name> <job_id>
hf jobs logs --namespace <my-org-name> <job_id>
Jobs가 끝날 때까지 대기
hf jobs wait로 하나 이상의 Job이 종료 상태(COMPLETED, CANCELED, ERROR, DELETED)에 도달할 때까지 블록해요. 모든 Job이 성공적으로 완료된 경우에만 코드 0으로 종료하고, 그렇지 않으면 0이 아닌 코드로 종료해요 — 셸 스크립트나 CI에서 단계를 연결하기 편리해요:
# Wait for a single Job
>>> hf jobs wait 693994e21a39f67af5a41ad0
# Wait for several Jobs at once (all must be in the same namespace)
>>> hf jobs wait <job_id_1> <job_id_2>
# Wait for every currently running Job
>>> hf jobs ps -q | xargs hf jobs wait
--timeout으로 최대 대기 시간을 설정해요 (s, m, h, d 허용):
>>> hf jobs wait --timeout 30m 693994e21a39f67af5a41ad0
hf jobs wait는 Job이 실패하면 0이 아닌 종료 코드를 반환하므로 &&로 연결할 수 있어요. 비분리형 hf jobs run(또는 hf jobs uv run)은 이미 블록하고 실패 시 0이 아닌 코드로 종료하므로, 명시적 wait는 분리형 Jobs(-d)이거나 배치를 기다릴 때만 필요해요:
>>> hf jobs wait 693994e21a39f67af5a41ad0 && echo "job completed successfully"
결과 유지하기
Job의 파일시스템은 Job이 끝나면 삭제돼요. Job이 종료되기 전에 보관하고 싶은 것은 내구성 있는 곳에 써야 해요:
-
중간 산출물, 체크포인트, 로그 → Storage Bucket 볼륨. 버킷을 마운트하고 마운트 경로 아래에 출력을 써요 — 예시는 Volumes를 참고해요. 볼륨 마운트는 Job 생성 시 내 Hugging Face 신원으로 인가되므로 스크립트가 쓰기 위해 토큰이 필요 없어요.
-
최종 모델·데이터셋 → Hub 리포지토리에 푸시. 토큰을 전달하지 않는 한 Jobs에는 Hugging Face 토큰이 없어요, 예:
--secrets HF_TOKEN(기본 형태는 내 로그인 토큰으로 자동 해석돼요). 스크립트가push_to_hub()나create_repo()를 호출한다면 토큰에 쓰기 권한이 있는지 확인해요(세분화된 토큰에는 repo 쓰기·생성 권한이 필요해요). 흔한 실패 방식은 수시간 compute를 완료하고 나서 토큰이 쓸 수 없어 최종 업로드에서 오류가 나는 경우예요 — compute는 끝났지만 결과가 저장되지 않는 거죠. -
핵심 결과를 로그에 출력. Job 로그는 Job 종료 후에도 보존되고
hf jobs logs <job-id>로 언제든 가져올 수 있어요. 최종 메트릭을 stdout에 출력하면 업로드 단계가 실패해도 복구 가능하게 유지돼요.
Job 완료 후 출력이 실제로 도착했는지 확인해요(예: hf buckets list로) — COMPLETED 상태는 명령이 성공적으로 종료됐다는 뜻이지, 파일이 기대한 곳에 저장됐다는 뜻은 아니에요.
Job 디버깅
Job에 오류가 있으면 Job 페이지에서 볼 수 있어요.
Job 페이지의 상태 메시지와 로그를 봐서 무엇이 잘못됐는지 확인해요.
Job이 실패하기 전에 무슨 일이 있었는지 로그의 마지막 줄도 볼 수 있어요. Job 페이지나 CLI로 볼 수 있어요:
>>> hf jobs logs 69405cf51a39f67af5a41f29 | tail -n 10
Downloaded nvidia-cudnn-cu12
Downloaded torch
Installed 66 packages in 226ms
Generating train split: 100%|██████████| 15806/15806 [00:00<00:00, 73330.17 examples/s]
Generating test split: 100%|██████████| 200/200 [00:00<00:00, 45427.32 examples/s]
Traceback (most recent call last):
File "/tmp/script.py", line 7, in <module>
train_dataset=train_dataset,
^^^^^^^^^^^^^
NameError: name 'train_dataset' is not defined. Did you mean: 'load_dataset'?
로컬 UV 또는 Docker 설정으로 Job을 로컬에서 디버그해요:
hf jobs uv run ...->uv run ...hf jobs run ...->docker run ...
상태 메시지가 "Job timeout"일 수 있어요: Job이 타임아웃(기본 30분) 전에 끝나지 않아 중지됐다는 뜻이에요.
이 경우 CLI에서 --timeout으로 더 높은 타임아웃을 지정해야 해요. 예:
hf jobs uv run --timeout 3h ...
Jobs 취소하기
Job 페이지의 "Cancel" 버튼으로 Job을 취소할 수 있어요:
또는 CLI로:
hf jobs cancel 693b06b8c67c9f186cfe239e
조직 namespace를 지정해 조직 아래의 Job을 취소할 수 있어요:
hf jobs cancel --namespace <my-org-name> <job_id>
MacOS 메뉴 바
hfjobs-menubar MacOS 클라이언트에서 Job 목록을 찾을 수 있어요:
Jobs 정보를 얻고 로그와 리소스 사용 통계를 모니터링해요.