Docker 이미지 사용하기

Docker 이미지 사용하기

모든 Job은 Docker 이미지 안에서 실행돼요. 이미지가 시스템 도구와 설치된 라이브러리를 포함한 소프트웨어 환경을 제공하죠. hf jobs run으로 이미지와 명령을 제공하고, hf jobs uv run은 uv가 Python 환경을 준비해 주며 기본 이미지를 선택해요.

출처: 문서

본문

모든 Job은 Docker 이미지 안에서 실행돼요. 이미지가 시스템 도구와 설치된 라이브러리를 포함한 소프트웨어 환경을 제공하죠. hf jobs run으로 이미지와 명령을 제공하고, hf jobs uv run은 지정하지 않으면 uv가 스크립트용 Python 환경을 준비하고 Jobs가 기본 이미지를 선택해요.

작업 부하를 실행할 방법 선택하기

Python 스크립트의 의존성을 uv로 설치할 수 있으면 Quickstart에서처럼 hf jobs uv run으로 시작해요. 추가 시스템 도구가 필요하거나 준비된 소프트웨어 환경을 쓰려면 이미지를 선택해요.

필요한 것 시작 지점
선언된 의존성과 함께 Python 스크립트 실행 hf jobs uv run script.py
이미지에 이미 설치된 도구·Python 패키지 사용 hf jobs run IMAGE COMMAND
uv 관리 의존성 + 추가 시스템 도구로 스크립트 실행 hf jobs uv run --image IMAGE script.py

기본 이미지에는 Python과 uv가 포함돼 있어요. 현재 기본 이미지와 사용 가능한 옵션은 UV Jobs 구성을 참고해요.

Docker Hub 같은 레지스트리의 기존 이미지를 사용하거나, Docker Space로 나만의 이미지를 빌드·호스팅할 수 있어요.

준비된 이미지 사용하기

hf jobs run을 이미지와 그 안에서 실행할 명령과 함께 사용해요. Docker Hub나 다른 레지스트리의 공개 이미지(특정 태그 포함)라면 뭐든 동작해요. 작은 것으로 시작해 볼게요:

hf jobs run ubuntu echo 'Hello from the cloud!'

Job이 이미지를 가져오고, 명령을 실행하고, 종료돼요. 이미지가 제공하는 소프트웨어를 사용하려면 그걸 담고 있는 이미지를 선택해요. 예를 들어 PyTorch 이미지로 GPU에 텐서를 만들고 값을 두 배로 만들려면:

hf jobs run --flavor t4-small --timeout 5m \
    pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
    -- python -c 'import torch; x = torch.ones(3, device="cuda"); print(x * 2)'

이미지가 PyTorch와 CUDA 소프트웨어 스택을 제공해요. --flavor t4-small로 GPU를 선택하고, --timeout 5m으로 Job의 런타임을 제한하며, Python 명령은 이미지에 설치된 PyTorch 패키지를 사용해요. 그 출력은 Job의 로그에 나타나요.

[!TIP] --는 Jobs 옵션을 명령과 그 인자와 구분해요. 예를 들어 이 구분자 뒤의 --help는 여러분의 명령에 전달돼요. 인자 전달 (Passing arguments)을 참고해요.

입력·출력 파일로 나만의 스크립트 실행하기

hf jobs run으로 실행하는 스크립트는 Job 안에서 사용 가능해야 해요. 이미지에 포함된 스크립트를 사용하거나 로컬 디렉토리 마운트를 할 수 있어요.

예를 들어 huggingface/trl 이미지의 Transformers와 PyTorch 패키지를 사용하는 추론 스크립트가 있다고 해볼게요. 로컬 work 디렉토리에 inference.py와 inputs.jsonl이 있고, 스크립트는 --input과 --output 경로를 받아요. 결과용 Storage Bucket을 만든 뒤 이렇게 실행해요:

hf jobs run --flavor t4-small --timeout 10m \
    -v ./work:/work \
    -v hf://buckets/YOUR_USERNAME/results:/output \
    huggingface/trl \
    -- python /work/inference.py --input /work/inputs.jsonl --output /output/results.jsonl

YOUR_USERNAME을 버킷 소유자의 네임스페이스로 바꿔요. CLI가 로컬 디렉토리를 업로드해 /work에 마운트해요. 스크립트는 거기서 입력을 읽고 /output에 마운트된 버킷에 결과를 쓰며, Job이 끝난 뒤에도 그대로 남아요. 명령의 인자, 하드웨어, 타임아웃을 스크립트에 맞게 조정해요 — 다른 입출력 옵션은 볼륨 (Volumes)을 참고해요.

uv와 이미지 사용하기

기본 이미지를 넘어서는 시스템 도구가 필요하면서 uv의 Python 의존성 워크플로는 유지하려면 hf jobs uv run --image를 사용해요. 선택한 이미지에는 uv가 설치돼 있어야 해요.

환경은 세 부분으로 이뤄져요:

  • 이미지의 시스템 도구·라이브러리 — ffmpeg나 CUDA 툴킷 같은 것들이 이미지 구성에 따라 Job에 사용 가능해요.
  • 이미지에 설치된 Python 패키지 — 이미지의 기존 Python 환경에 속해요.
  • 스크립트 의존성 — 인라인 의존성 헤더로 uv가 Python 패키지를 격리된 환경에 설치해요. 이미지에 미리 설치된 패키지는 자동으로 사용 가능하지 않아요.

예를 들어 vLLM 스크립트는 uv로 자체 선언된 Python 의존성을 설치하면서 CUDA 도구가 있는 이미지가 필요할 수 있어요. 시스템 도구는 여전히 uv가 설치하는 패키지와 호환돼야 해요.

이미지에 미리 설치된 PyTorch, TRL, vLLM을 직접 사용하려면 hf jobs run을 쓰세요. uv로 추가 의존성도 설치해야 한다면 이미지 패키지 재사용 + uv로 의존성 추가를 참고해요.

Docker Space로 나만의 이미지 빌드하기

Docker Space는 작업 부하에 필요한 도구(여러분의 스크립트 포함)가 있는 이미지를 빌드·호스팅할 수 있고, 레지스트리 계정 없이 이미지를 프라이빗으로 유지할 수 있어요. 예를 들어 Python 이미지에 FFmpeg를 추가해 오디오·비디오 처리용 환경을 준비할 수 있어요.

Docker Space를 만들고 저장소 루트에 이 Dockerfile을 추가해요:

FROM python:3.12-slim-bookworm

# Install FFmpeg for audio and video processing.
RUN apt-get update \
    && apt-get install -y --no-install-recommends ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Match the non-root user ID used by Docker Spaces.
RUN useradd --create-home --uid 1000 user
USER user

# Check that FFmpeg is available.
CMD ["ffmpeg", "-version"]

FROM이 Python을 제공해요. FFmpeg는 이 기본 이미지에 없으니 RUN이 빌드 시점에 설치해요. useradd는 홈 디렉토리와 UID 1000을 가진 사용자를 만들어 Docker Spaces에 맞춰요; USER로 그 사용자로 명령을 실행해요. CMD는 기본 명령을 설정하는데, 여기선 FFmpeg 설치를 확인해요.

파일을 커밋하고 Space의 빌드 로그에 이미지가 push됐다고 표시될 때까지 기다려요. 그런 다음 보통 이미지 이름을 넣는 자리에 Space URL을 전달하고, YOUR_USERNAME/video-tools를 Space ID로 바꿔요:

hf jobs run --flavor cpu-basic --timeout 5m \
    hf.co/spaces/YOUR_USERNAME/video-tools -- ffmpeg -version

버전이 Job의 로그에 나타나요. Space URL 뒤에 다른 명령을 주면 작업 부하에 FFmpeg나 Python을 사용할 수 있어요. 이미지에 나만의 스크립트를 포함하려면 COPY --chown=user:user process.py /app/process.py 같은 줄을 Dockerfile에 추가하고 python /app/process.py를 실행해요. 데이터 마운트·결과 저장은 입력·출력 파일을 참고해요.

[!NOTE] 이 예시는 버전을 출력하고 종료하므로, 빌드 후 Space에 런타임 오류가 표시돼요. 괜찮아요: Jobs는 빌드된 이미지만 필요하지, 실행 중인 Space는 필요 없어요.

[!TIP] Space의 빌드된 이미지는 항상 pull 가능하다는 보장이 없어요. 레지스트리 유지보수나 지역 이동으로 사라질 수 있어요. Job이 이미지를 찾을 수 없다고 보고하면 Space를 팩토리 재부팅해 다시 빌드해요. Jobs는 항상 최신 빌드를 사용하므로, 새 커밋도 이미지를 교체해요.

예시 이미지

레지스트리 이미지는 게시자가 유지보수하며 특정 태그로 고정할 수 있어요.

이미지 제공 내용
pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel PyTorch와 CUDA 개발 환경 — 위 예시에서 사용.
huggingface/trl 포스트트레이닝과 관련 Python 작업용 TRL, Transformers, PyTorch, uv.
vllm/vllm-openai LLM 추론용 vLLM, uv, CUDA 도구.

hf jobs run으로 이미지의 설치된 패키지로 명령을 실행해요. hf jobs uv run의 경우 이미지에 uv가 설치돼 있는지 확인하고 위 환경 가이드를 따라요. 실행·변형할 작업 부하는 예시 & 튜토리얼에서 탐색해요.

이미지 패키지 재사용하고 uv로 의존성 추가하기

프레임워크 이미지는 PyTorch, vLLM과 그 CUDA 확장처럼 빌드가 느리거나 어려운 사전 설치 패키지를 제공해요. 그래도 스크립트에 추가 Python 패키지가 필요할 수 있어요 — 예를 들어 특정 데이터 형식을 로드하거나 실험을 추적하는 경우요.

이미지의 사전 설치 스택을 재사용하면서 uv로 추가 패키지를 설치할 수 있어요. 스크립트의 # /// script 의존성 헤더에 추가 패키지를 선언한 뒤, uv를 이미지의 인터프리터에 지정하고 site-packages를 import 경로에 추가해요:

hf jobs uv run \
    --image vllm/vllm-openai \
    --flavor l4x4 \
    --python /usr/bin/python3 \
    -e PYTHONPATH=/usr/local/lib/python3.12/dist-packages \
    -s HF_TOKEN \
    generate-responses.py
  • --python은 이미지의 인터프리터로 uv 환경을 만들어, 컴파일된 확장이 사용하는 Python 버전과 맞춰요. 그 자체로 이미지의 패키지를 노출하진 않아요.
  • -e PYTHONPATH=...는 해당 실행에서 import vllm이 이미지의 사전 빌드 빌드를 가리키게 해요.
  • # /// script 의존성을 이미지에 없는 것으로 줄여요. PYTHONPATH가 uv 환경보다 먼저 검색되므로, 헤더에서 선언한 같은 패키지(핀한 최신 버전 포함)를 이미지가 가리게 돼요. 유지하는 의존성은 여전히 그 패키지들을 전이적으로 끌어올 수 있어요; uv는 의존성 해결에 PYTHONPATH를 사용하지 않아요.

경로는 이미지마다 다르니 하드코딩하지 말고 cpu-basic에서 probe해요:

hf jobs run --flavor cpu-basic vllm/vllm-openai bash -c 'which python3; which uv; python3 -m pip show vllm | grep Location'

/usr/bin/python3                              # pass to --python
/usr/local/bin/uv                             # uv is present, so `uv run` works
Location: /usr/local/lib/python3.12/dist-packages   # pass to PYTHONPATH

vllm을 재사용하는 라이브러리로 바꿔요. 레이아웃은 다양해요 — vllm/vllm-openai와 lmsysorg/sglang은 위 시스템 dist-packages를 쓰고, unsloth/unsloth은 virtualenv(/opt/venv/...)를, huggingface/trl은 conda(/opt/conda/lib/python3.11/site-packages, pytorch/pytorch에서 상속)를 사용해요.

[!TIP] 이것은 import용으로 이미지의 빌드를 선택하는 거지, uv의 의존성 resolver용은 아니에요. 헤더를 줄이면 중복 설치를 줄일 수 있지만 제거가 보장되진 않아요. PYTHONPATH 단계를 건너뛰는 uv run --system-site-packages는 상류에 요청돼 있어요.

huggingface/trl 이미지의 경우 대응하는 인터프리터와 패키지 경로는:

hf jobs uv run \
    --image huggingface/trl \
    --flavor a100-large \
    --python /opt/conda/bin/python3 \
    -e PYTHONPATH=/opt/conda/lib/python3.11/site-packages \
    -s HF_TOKEN \
    train.py

이 명령들은 나만의 스크립트 이름으로 generate-responses.py와 train.py를 사용해요.

문제 해결

GPU 라이브러리에 프레임워크 이미지 사용하기

일부 GPU 라이브러리는 CUDA 컴파일러(nvcc), NCCL, cuDNN 같은 추가 시스템 도구가 필요해요. Python 패키지를 설치한다고 이미지에 필요한 모든 도구가 있다는 보장은 없어요. 예를 들어 FlashInfer의 sampler는 CUDA 툴킷이 없는 이미지에서 커널을 컴파일하려다 실패할 수 있어요:

RuntimeError: Could not find nvcc and default cuda_home='/usr/local/cuda' doesn't exist

필요한 CUDA 도구가 있는 프레임워크 이미지를 전달하면 이 누락 툴킷 오류가 해결돼요:

hf jobs uv run --image vllm/vllm-openai --flavor l4x4 -s HF_TOKEN generate-responses.py

uv는 여전히 스크립트 의존성을 별도로 해결·설치해요. 이미지는 시스템 도구를 제공하지만, 해결된 Python 패키지가 그것과 호환된다는 보장은 없어요.

더 알아보기 (Learn more)

  • Python 스크립트라면 hf jobs uv run, 이미지의 설치 패키지를 쓰려면 hf jobs run IMAGE COMMAND를 써요.
  • 프라이빗 커스텀 이미지는 Docker Space로 빌드·호스팅할 수 있어요.