# Dockerイメージの使用

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

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

Pythonスクリプトの依存関係がuvでインストールできる場合は、[クイックスタート](./jobs-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 configuration](./jobs-configuration#uv-jobs)を参照してください。

Docker Hubなどのレジストリから既存のイメージを使用するか、[Docker Spaceで独自のイメージをビルドしてホストする](#build-your-own-image-with-a-docker-space)こともできます。

## 完成した画像を使用する

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

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

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

```bash
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` は、あなたのコマンドに渡されます。[引数の渡し方](./jobs-configuration#passing-arguments)を参照してください。

### 入力ファイルと出力ファイルを指定して、独自のスクリプトを実行する

`hf jobs run`で実行されるスクリプトは、Job内で利用可能である必要があります。イメージに含まれるスクリプトを使用するか、[ローカルディレクトリをマウント](./jobs-configuration#local-directories)できます。

例えば、`huggingface/trl` イメージで Transformers および PyTorch パッケージを使用する推論スクリプトがあるとします。ローカルの `work` ディレクトリには `inference.py` と `inputs.jsonl` が含まれており、スクリプトは `--input` と `--output` のパスを受け取ります。結果用に [Storage Bucket](./storage-buckets) を作成した後、次のように実行します。

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

## uvでイメージを使用する

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

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

- イメージ内の**システムツールやライブラリ**（`ffmpeg`やCUDAツールキットなど）は、イメージの設定に従ってJobから利用できます。
- イメージにインストールされている**Pythonパッケージ**は、その既存のPython環境に属します。
- **スクリプトの依存関係。** [インライン依存関係ヘッダー](https://docs.astral.sh/uv/guides/scripts/#declaring-script-dependencies)を使用すると、uvは隔離された環境にPythonパッケージをインストールします。イメージにプリインストールされているパッケージは自動的に利用できません。

例えば、vLLMのスクリプトは、uvを使用して宣言されたPython依存関係をインストールする一方で、CUDAツールを含むイメージを必要とする場合があります。システムツールは、uvがインストールするパッケージと互換性がある必要があります。

画像にプリインストールされているPyTorch、TRL、vLLMを直接使用したい場合は、`hf jobs run`を使用してください。uvを使用して追加の依存関係をインストールする必要がある場合は、[画像のパッケージを再利用してuvで依存関係を追加する](#reuse-the-images-packages-and-add-dependencies-with-uv)を参照してください。

## Docker Spaceで独自のイメージを構築する

Docker Spaceでは、ワークロードに必要なツール（独自のスクリプトを含む）を備えたイメージをビルドしてホストできます。また、レジストリアカウントがなくてもイメージをプライベートに設定できます。例えば、PythonのイメージにFFmpegを追加して、音声や動画の処理を行うための環境を整備できます。

[Docker Space](./spaces-sdks-docker#setting-up-docker-spaces)を作成し、そのリポジトリのルートにこの`Dockerfile`を追加します:

```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](./spaces-sdks-docker#permissions) と一致させます。`USER` はそのユーザーとしてコマンドを実行します。`CMD` はデフォルトのコマンドを設定し、ここでは FFmpeg のインストールを確認しています。

ファイルをコミットし、Space のビルドログにイメージがプッシュされたことを示す表示が出るまで待ってください。その後、通常はイメージ名を指定する箇所に Space の URL を渡します。この際、`YOUR_USERNAME/video-tools` をご自身の Space ID に置き換えてください。

```bash
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` を実行します。データのマウントと結果の保存については、[入力ファイルと出力ファイル](#run-your-own-script-with-input-and-output-files)を参照してください。

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

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

## 例の画像

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

| 画像                                         | 提供される機能                                                                  |
| --------------------------------------------- | --------------------------------------------------------------------------------- |
| `pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel` | 上記の例で使用されるPyTorchとCUDA開発環境。            |
| `huggingface/trl`                             | TRL、Transformers、PyTorch、uvは、ポストトレーニングおよび関連するPythonワークロード向けです。 |
| `vllm/vllm-openai`                            | LLM推論用のvLLM、uv、CUDAツール。                                      |

`hf jobs run` を使用して、イメージにインストールされたパッケージでコマンドを実行します。`hf jobs uv run` の場合は、イメージに uv がインストールされていることを確認し、上記の[環境に関するガイダンス](#use-an-image-with-uv)に従ってください。実行および適応可能なワークロードについては、[Examples & Tutorials](./jobs-examples)をご覧ください。

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

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

`# /// script` の依存関係ヘッダーに追加のパッケージを宣言し、uv をイメージのインタープリターに向かせ、その site-packages をインポートパスに追加することで、uv を使ってこれらの追加パッケージをインストールしながら、イメージにプリインストールされたスタックを再利用できます。

```bash
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`上でそれらを調査してください。

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

```text
/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` から継承）を使用します。

> [!TIP]
> これは、uv の依存関係リゾルバーではなく、インポート用のイメージのビルドを選択します。ヘッダーをトリミングすることで冗長なインストールを減らすことはできますが、それらが完全に排除されることを保証するものではありません。`PYTHONPATH` ステップをスキップする `uv run --system-site-packages` は、[アップストリームでリクエストされています](https://github.com/astral-sh/uv/issues/7999)。

`huggingface/trl`イメージの場合、対応するインタプリタとパッケージのパスは以下の通りです。

```bash
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のサンプラーが失敗することがあります。

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

必要なCUDAツールを含むフレームワークイメージを渡すことで、このツールキット欠如エラーを解決できます。

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

uv は引き続き、スクリプトの依存関係を個別に解決してインストールします。イメージはシステムツールを提供しますが、解決された Python パッケージがそれと互換性があることは保証されません。