Dockerイメージの使用

すべての Job は Docker イメージ内で実行され、システムツールやインストールされたライブラリを含むソフトウェア環境が提供されます。hf jobs run を使用する場合、イメージとコマンドを指定します。hf jobs uv run を使用する場合、uv がスクリプト用の Python 環境を準備し、Jobs がデフォルトのイメージを選択します（指定しない場合）。

ワークロードの実行方法を選択

Pythonスクリプトの依存関係がuvでインストールできる場合は、クイックスタートに示されているように、hf jobs uv runから開始してください。追加のシステムツールが必要이거나、用意されたソフトウェア環境を使用したい場合は、イメージを選択してください。

デフォルトのイメージにはPythonとuvが含まれています。現在のデフォルトのイメージと利用可能なオプションについては、UV Jobs configurationを参照してください。

Docker Hubなどのレジストリから既存のイメージを使用するか、Docker Spaceで独自のイメージをビルドしてホストすることもできます。

完成した画像を使用する

hf jobs run を、イメージと、その中で実行するコマンドを指定して使用します。Docker Hub やその他のレジストリからの公開イメージはすべて使用でき、特定のタグを指定することもできます。まずは小さなものから始めてみましょう:

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

Job はイメージをプルし、コマンドを実行して終了します。イメージがすでに提供しているソフトウェアを使用するには、そのソフトウェアを同梱したイメージを選択します。例えば、PyTorch イメージを使用して GPU 上でテンソルを作成し、その値を 2 倍にするには:

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 が終了した後も、結果は利用可能な状態のまま保持されます。スクリプトに合わせて、コマンドの引数、ハードウェア、タイムアウトを調整してください。その他の入力および出力のオプションについては、ボリューム を参照してください。

uvでイメージを使用する

スクリプトがデフォルトのイメージを超えるシステムツールを必要とする場合、かつuvのPython依存関係のワークフローを維持したい場合は、hf jobs uv run --imageを使用してください。選択したイメージにはuvがインストールされている必要があります。

環境には3つの部分があります:

• イメージ内のシステムツールやライブラリ（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 のビルドログにイメージがプッシュされたことを示す表示が出るまで待ってください。その後、通常はイメージ名を指定する箇所に 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 をワークロードに使用できます。独自のスクリプトをイメージに含めるには、Dockerfile に COPY --chown=user:user process.py /app/process.py のような行を追加し、python /app/process.py を実行します。データのマウントと結果の保存については、入力ファイルと出力ファイルを参照してください。

この例はバージョンを出力して終了するため、Space はビルド後にランタイムエラーを表示します。問題ありません。Jobs には実行中の Space ではなく、ビルド済みのイメージのみが必要だからです。

Spaceのビルド済みイメージが常にプル可能であることは保証されていません。レジストリのメンテナンスやリージョンの移動により失われる可能性があります。Jobがイメージが見つからないと報告した場合、Spaceをファクトリリブートして再ビルドしてください。Jobは常に最新のビルドを使用するため、新しいコミットがプッシュされるとイメージも置き換えられます。

例の画像

Registryのイメージはパブリッシャーによって管理されており、特定のタグにピン留めできます。

hf jobs run を使用して、イメージにインストールされたパッケージでコマンドを実行します。hf jobs uv run の場合は、イメージに uv がインストールされていることを確認し、上記の環境に関するガイダンスに従ってください。実行および適応可能なワークロードについては、Examples & Tutorialsを参照してください。

イメージのパッケージを再利用し、uvで依存関係を追加します

Framework imagesには、PyTorch、vLLM、およびそれらのCUDA拡張機能など、ビルドに時間がかかるか困難なパッケージがプリインストールされています。スクリプトには、特定のデータ形式を読み込むためや実験を追跡するためなど、追加のPythonパッケージが必要な場合があります。

# /// script の依存関係ヘッダーに追加のパッケージを宣言し、uv をイメージのインタープリターに向かせ、その site-packages をインポートパスに追加することで、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 は、コンパイル済み拡張機能で使用されている Python バージョンに一致する、イメージのインタープリターで uv の環境を作成します。それ自体では、イメージのパッケージを公開しません。
• -e PYTHONPATH=... を指定すると、その実行時に import vllm がイメージに事前ビルド済みのビルドを解決するようにします。
• # /// script の依存関係を、イメージに含まれていないものだけに絞り込んでください。PYTHONPATH は uv の環境よりも先に検索されるため、ヘッダーで宣言した同じパッケージのものは、ピン留めした新しいバージョンであっても、イメージによってシャドウされます。保持した依存関係は、それらのパッケージを間接的に引き込む可能性があります。uv は依存関係の解決に PYTHONPATH を使用しません。

画像ごとにパスが異なるため、ハードコードするのではなく、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 は仮想環境（/opt/venv/...）を使用し、huggingface/trl は conda（/opt/conda/lib/python3.11/site-packages、pytorch/pytorch から継承）を使用します。

これは、uv の依存関係リゾルバーではなく、インポート用のイメージのビルドを選択します。ヘッダーをトリミングすることで冗長なインストールを減らすことはできますが、それらが完全に排除されることを保証するものではありません。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 パッケージがそれと互換性があることは保証されません。