Docker 이미지 사용

모든 Job은 시스템 도구와 설치된 라이브러리를 포함한 소프트웨어 환경을 제공하는 Docker 이미지 내에서 실행됩니다. hf jobs run을 사용하면 이미지와 명령어를 지정합니다. hf jobs uv run을 사용하면 uv가 스크립트를 위한 Python 환경을 준비하고, 사용자가 지정한 이미지가 없으면 Jobs가 기본 이미지를 선택합니다.

워크로드 실행 방법 선택

Python 스크립트의 의존성이 uv로 설치 가능한 경우, Quickstart에 나와 있듯이 hf jobs uv run으로 시작하세요. 추가 시스템 도구가 필요하거나 준비된 소프트웨어 환경을 사용하려면 이미지를 선택하세요.

기본 이미지에는 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의 로그에 표시됩니다.

--는 Jobs 옵션과 명령 및 해당 인자를 구분합니다. 예를 들어, 이 구분자 뒤에 오는 --help는 사용자의 명령으로 전달됩니다. 인자 전달을 참조하세요.

입력 및 출력 파일을 사용하여 자체 스크립트 실행

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 스크립트는 자체적으로 선언된 Python 의존성을 uv로 설치하는 동안 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의 로그에 표시됩니다. 워크로드에 FFmpeg 또는 Python을 사용하려면 Space URL 뒤에 다른 명령을 지정하세요. 이미지 자체에 스크립트를 포함하려면 Dockerfile에 COPY --chown=user:user process.py /app/process.py와 같은 한 줄을 추가하고 python /app/process.py를 실행하세요. 데이터를 마운트하고 결과를 저장하는 방법은 입력 및 출력 파일을 참고하세요.

이 예제는 버전을 출력하고 종료되므로, 빌드 후 Space에서 런타임 오류가 표시됩니다. 이는 문제가 되지 않습니다. Jobs는 실행 중인 Space가 아니라 빌드된 이미지만 필요하기 때문입니다.

Space의 빌드된 이미지가 항상 pull 가능하도록 유지된다는 보장은 없습니다. 레지스트리 유지보수 또는 리전 이동으로 인해 이미지가 손실될 수 있습니다. Job에서 이미지가 발견되지 않았다고 보고되면, Space를 factory reboot하여 이미지를 다시 빌드하세요. Job은 항상 최신 빌드를 사용하므로, 새로운 커밋이 생성되면 이미지도 교체됩니다.

예시 이미지

Registry 이미지는 게시자가 관리하며 특정 태그로 고정할 수 있습니다.

hf jobs run을 사용하여 이미지에 설치된 패키지로 명령을 실행합니다. hf jobs uv run의 경우, 이미지에 uv가 설치되어 있는지 확인하고 위의 환경 가이드를 따르세요. 실행 및 적용할 워크로드를 확인하려면 예제 및 튜토리얼을 참조하세요.

uv를 사용하여 이미지의 패키지를 재사용하고 의존성을 추가합니다

Framework images에는 PyTorch, vLLM 및 해당 CUDA 확장과 같이 빌드하는 데 시간이 오래 걸리거나 어려운 사전 설치 패키지가 포함되어 있습니다. 스크립트 실행을 위해 특정 데이터 형식을 로드하거나 실험을 추적하는 등의 추가 Python 패키지가 여전히 필요할 수 있습니다.

# /// script 의존성 헤더에 추가 패키지를 선언한 후, uv를 이미지의 인터프리터로 지정하고 해당 site-packages를 import 경로에 추가하면, 이미지에 미리 설치된 스택을 재사용하면서 uv로 해당 추가 항목을 설치할 수 있습니다.

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의 dependencies를 이미지가 제공하지 않는 항목으로만 줄이세요. PYTHONPATH는 uv의 환경보다 먼저 검색되므로, 동일한 패키지에 대해 헤더에서 선언한 항목(고정된 더 새로운 버전 포함)은 이미지에 의해 가려집니다. 유지한 dependencies는 여전히 해당 패키지를 전이적으로 가져올 수 있으며, uv는 PYTHONPATH를 사용하여 dependency resolution을 해결하지 않습니다.

이미지마다 경로가 다르므로, 하드코딩 대신 cpu-basic에서 경로를 확인하세요:

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에서 상속)를 사용합니다.

이 설정은 uv의 의존성 리졸버가 아닌, import를 위한 이미지의 빌드를 선택합니다. 헤더를 줄이면 중복 설치를 줄일 수 있지만, 완전히 제거된다는 보장은 없습니다. 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 패키지를 설치한다고 해서 이미지에 필요한 모든 도구가 포함되어 있다고 보장되지 않습니다. 예를 들어, CUDA 툴킷이 없는 이미지에서 커널을 컴파일하려고 하면 FlashInfer의 샘플러가 실패할 수 있습니다:

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 패키지가 해당 시스템 도구와 호환됨을 보장하지는 않습니다.