セットアップガイド

【Docker/環境】Docker ComposeでAI開発環境を一括構築！よくあるエラーと完全解決ガイド

· 18分で読めます · 1 閲覧

問題の概要：Docker ComposeによるAI環境構築で発生する典型的なエラー

機械学習や深層学習のプロジェクトを始める際、Pythonバージョン、CUDA/cuDNN、各種ライブラリ（PyTorch, TensorFlow, Jupyter, etc.）の依存関係を手動で整えるのは煩雑で、再現性に課題があります。Docker Composeを使えば、これらの環境をコードで定義し、一括で構築・起動できます。しかし、特にAI開発環境では、GPUの認識問題、ビルドの失敗、ボリュームマウントのエラー、メモリ不足など、特有のトラブルに遭遇することが少なくありません。

本記事では、以下のような具体的なエラーメッセージに直面した際の解決策を解説します。

  • ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?
  • ERROR: for ai-service Cannot start service jupyter: could not select device driver "" with capabilities: [[gpu]]
  • RuntimeError: CUDA error: no kernel image is available for execution on the device (コンテナ内で)
  • ERROR: failed to solve: process "/bin/sh -c pip install torch torchvision" did not complete successfully: exit code: 137 (メモリ不足によるビルド失敗)

原因の解説

これらのエラーは、主に以下の4つのカテゴリに分類され、根本原因を理解することが解決の第一歩です。

1. Dockerデーモン/GPUドライバの問題

Couldn't connect to Docker daemon はDockerエンジンそのものが起動していない状態です。また、GPU関連のエラーは、ホストマシンにNVIDIAドライバやNVIDIA Container Toolkitがインストールされていない、またはDocker Composeファイルの記述が不適切な場合に発生します。DockerはデフォルトではGPUリソースをコンテナに公開しません。

2. イメージのビルド失敗

Dockerfile内のRUN pip install ... コマンドが失敗する場合、ネットワークの問題、依存パッケージの競合、またはホストマシンのメモリ不足（特にexit code 137）が原因です。AIライブラリはサイズが大きく、ビルドプロセス中に多くのRAMを消費します。

3. CUDAとcuDNNのバージョン不一致

no kernel image is available は、コンテナ内にインストールされたPyTorchやTensorFlowが、ホストのGPU（または仮想GPU）のCompute Capabilityをサポートしていない場合に発生する典型的なエラーです。使用するベースイメージのCUDAバージョンと、ホストにインストールされたNVIDIAドライバのバージョンには互換性が必要です。

4. ボリューム/パーミッション問題

ホストのコードやデータをコンテナ内にマウントする際、コンテナ内のユーザー（多くの場合、root以外の一般ユーザー）とホストのファイル所有者のUID/GIDが一致しないと、Jupyter Notebookなどで「Permission Denied」エラーが発生し、ファイルの読み書きができなくなります。

解決方法：ステップバイステップガイド

ステップ1: 事前準備 – DockerとNVIDIA環境の確認

まず、ホストマシンの環境が整っていることを確認します。

# 1. Dockerデーモンの起動とバージョン確認
sudo systemctl start docker  # Dockerが起動していない場合
sudo systemctl enable docker # 自動起動を有効化
docker --version
docker compose version

# 2. NVIDIAドライバの確認
nvidia-smi

# 3. NVIDIA Container Toolkitのインストール（GPU利用の場合）
# 公式手順に従いインストール後、再起動推奨
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

ステップ2: Docker Composeファイルの作成と最適化

以下は、Jupyter Lab、PyTorch、TensorFlow、共通ユーティリティを含むAI開発環境のテンプレート例です。コメントで重要な設定ポイントを説明しています。

# docker-compose.yml
version: '3.8'

services:
  ai-workspace:
    build:
      context: .
      dockerfile: Dockerfile
      # ビルド時のメモリ不足を防ぐため、キャッシュを効果的に利用
      args:
        BUILDKIT_INLINE_CACHE: 1
    container_name: ai-dev-container
    restart: unless-stopped
    ports:
      - "8888:8888"  # Jupyter Lab
      - "6006:6006"  # TensorBoard
    deploy:  # GPUリソースの指定 (Compose v2.3+)
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    # 環境変数でライブラリの挙動を制御
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
      - TF_FORCE_GPU_ALLOW_GROWTH=true # TensorFlowのメモリ割り当てエラー防止
    volumes:
      # ホストのカレントディレクトリをコンテナの/workにマウント
      - ./:/work
      # キャッシュや設定ファイルを永続化
      - jupyter-data:/home/jovyan/.jupyter
      - pip-cache:/home/jovyan/.cache/pip
    working_dir: /work
    # ホストと同じUID/GIDで実行し、パーミッション問題を解決
    user: "${UID:-1000}:${GID:-1000}"
    stdin_open: true
    tty: true

volumes:
  jupyter-data:
  pip-cache:

# Dockerfile
# 軽量かつ互換性の高いCUDAイメージを選択
# ホストの`nvidia-smi`で表示されるCUDA Versionと互換性のあるタグを選ぶ
FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04

# ビルド引数でユーザー設定を渡す
ARG UID=1000
ARG GID=1000
ARG USERNAME=ai-developer

# システムパッケージのインストールとキャッシュクリーンアップを1行にまとめ、レイヤー数を削減
RUN apt-get update && apt-get install -y --no-install-recommends 
    python3-pip 
    python3-dev 
    git 
    curl 
    wget 
    && rm -rf /var/lib/apt/lists/*

# 一般ユーザーを作成（パーミッション問題対策）
RUN groupadd -g $GID $USERNAME && 
    useradd -m -s /bin/bash -u $UID -g $GID $USERNAME

# ワークディレクトリを作成し、所有者を変更
RUN mkdir -p /work && chown -R $UID:$GID /work

# ユーザーを切り替え
USER $USERNAME
WORKDIR /home/$USERNAME

# 必要なPythonパッケージをインストール
# requirements.txtを事前に用意してコピーする方法がより効率的
COPY --chown=$UID:$GID requirements.txt /tmp/requirements.txt
RUN pip3 install --user --no-cache-dir -r /tmp/requirements.txt && 
    rm /tmp/requirements.txt

# Jupyter Labのデフォルト設定
ENV JUPYTER_ENABLE_LAB=yes

WORKDIR /work
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]

# requirements.txt (例)
torch==2.1.2
torchvision==0.16.2
torchaudio==2.1.2
--index-url https://download.pytorch.org/whl/cu121
tensorflow==2.15.0
jupyterlab==4.0.11
pandas==2.1.4
scikit-learn==1.3.2
matplotlib==3.8.2
seaborn==0.13.0

ステップ3: 環境構築と起動

作成したファイルを用いて環境を構築・起動します。

# 1. ホスト側のUID/GIDを環境変数として渡してビルド・起動
# ビルド時のメモリ不足が心配な場合は、Docker Desktopの設定でメモリを増やすか、スワップを有効にする
export UID=$(id -u)
export GID=$(id -g)
docker compose build --no-cache  # 初回または依存関係を更新した場合
# または、キャッシュを利用して高速にビルド
# docker compose build

# 2. コンテナを起動（デタッチモード）
docker compose up -d

# 3. 起動ログを確認（Jupyterのトークン取得など）
docker compose logs -f ai-workspace
# 出力に `http://127.0.0.1:8888/lab?token=...` のような行が表示される

# 4. GPUが認識されているか確認
docker compose exec ai-workspace python3 -c "import torch; print(f'PyTorch CUDA available: {torch.cuda.is_available()}'); if torch.cuda.is_available(): print(f'Device: {torch.cuda.get_device_name(0)}')"
docker compose exec ai-workspace python3 -c "import tensorflow as tf; print(f'TF Num GPUs Available: {len(tf.config.list_physical_devices("GPU"))}')"

ステップ4: よくあるトラブルとその対処

ケースA: ビルド中のメモリ不足（exit code 137）
Docker Desktopの設定（Preferences > Resources）でメモリ割り当てを増やす（例: 8GB以上）。または、ホストのスワップ領域を確保する。ビルドコマンドに--memoryフラグはComposeビルドでは使えないため、デーモン側の設定が必要です。

ケースB: CUDAバージョンエラー
nvidia-smiのCUDA Versionが11.8なのに、Dockerfileでnvidia/cuda:12.1.1-...を使っている場合、互換性の問題が発生する可能性があります。ホストのドライバを更新するか、Dockerfileのベースイメージを下位バージョン（例: nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04）に変更し、requirements.txt内のPyTorchインストールURLもcu118に合わせます。

ケースC: ボリューム内でのファイル作成権限エラー
Composeファイルでuser: "${UID}:${GID}"を設定していることを確認します。もしコンテナ内でroot権限が必要な操作（例: システムパッケージの追加インストール）がある場合は、Dockerfile内でUSER rootとUSER $USERNAMEを適切に切り替えるか、コンテナ起動後にdocker compose exec -u root ai-workspace <command>で実行します。

まとめ・補足情報

Docker Composeを用いたAI開発環境のテンプレート化は、プロジェクトの再現性を劇的に高め、異なるマシン間や複数メンバー間での環境差異による「私のマシンでは動いたのに」問題を解消する強力な手段です。本記事で紹介したテンプレートとトラブルシューティング手順は、以下の点を意識しています。

  • GPUサポートの明示的定義: deploy.resourcesまたは古い形式のruntime: nvidiaを使って、確実にGPUをコンテナに渡します。
  • パーミッション問題の予防: ホストのユーザーID/グループIDをコンテナ内ユーザーに合わせることで、ファイル操作のエラーを未然に防ぎます。
  • ビルドの安定化: メモリ不足対策と、CUDA/ドライバのバージョン互換性の確認を徹底します。
  • 開発体験の向上: Jupyter LabやTensorBoardのポート公開、ワークディレクトリのマウントにより、ホストとシームレスに連携できます。

この環境をベースに、docker-compose.override.ymlを使って開発用と本番用の設定を分けたり、PostgreSQLやRedisなどのサービスを追加してより複雑なMLパイプライン環境を構築することも可能です。Docker Composeは、AI開発における「環境そのもの」をコード化し、バージョン管理するための基盤として、非常に有効なツールです。

この記事は役に立ちましたか？