セットアップガイド

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

· 15分で読めます

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

AI開発を始める際、Pythonバージョン、CUDA、cuDNN、各種ライブラリ（PyTorch、TensorFlow、JupyterLabなど）の環境構築は大きな障壁となります。Docker Composeを使えばこれらを一括で構築できますが、実際には以下のようなエラーに直面することが多いです。

  • ビルドエラー: ERROR: failed to solve: python:3.9-slim: pulling from docker.io/library/python failed のようなネットワーク関連のエラー。
  • GPU認識エラー: Could not load dynamic library 'libcudart.so.11.0' や docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]]. といったGPUがコンテナ内で使えないエラー。
  • メモリ不足エラー: Your container ran out of memory (OOM) や Killed というメッセージでプロセスが強制終了。
  • ボリュームマウントエラー: ERROR: for app Cannot start service app: Mounts denied のようにホストOSのファイルをコンテナと共有できない。
  • 依存関係の競合: ERROR: Cannot install -r requirements.txt で、PyTorchとTensorFlowのバージョンが競合する。

原因の解説

これらのエラーは、Dockerとホストマシンの環境、およびDocker Composeファイルの設定が適切に連携していないことが主な原因です。

1. ネットワーク・イメージ取得エラー

Docker Hubへの接続が不安定だったり、企業のファイアウォール内で作業している場合に発生します。また、指定したイメージタグ（例: python:3.9-slim）が存在しない、または削除された場合も同様のエラーになります。

2. GPU認識エラーの根本原因

DockerはデフォルトではホストマシンのGPUを認識しません。NVIDIA GPUを使用するには、NVIDIA Container Toolkit（旧nvidia-docker2）のインストールと、docker-compose.ymlでの正しいランタイム指定（runtime: nvidia または deploy.resources.reservations.devices）が必要です。ドライバのバージョンとコンテナ内のCUDAバージョンの不一致も原因となります。

3. リソース制限

Dockerはデフォルトでコンテナが利用できるメモリやCPUをホストマシンの全量に近く設定します。大規模なモデルを学習させる際、コンテナがメモリを食い尽くすとホストOSによって強制終了（OOM Killer）されます。docker-compose.ymlで明示的にリソース上限を設定していないことが原因です。

4. ファイルパーミッションとボリュームパス

特にLinux/macOSで、ホストマシンのディレクトリをコンテナ内にマウントする際、コンテナ内で動作するプロセス（通常はroot以外のユーザー）の権限と、ホスト側のファイル・ディレクトリのパーミッションが一致しないと、書き込みエラーが発生します。

解決方法：ステップバイステップで堅牢なAI環境を構築

ステップ1: 事前準備 – DockerとNVIDIA Container Toolkitのインストール確認

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

# DockerとDocker Composeのバージョン確認
docker --version
docker-compose --version

# NVIDIA Container Toolkitが正しくインストールされているか確認（GPUを使用する場合）
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

上記コマンドでnvidia-smiの出力が得られなければ、NVIDIA Container Toolkitの再インストールが必要です。

ステップ2: プロジェクト構造と基本ファイルの作成

以下のようなディレクトリ構造を作成します。

ai-dev-project/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── .env
└── workspace/ # ホストとコンテナで共有する作業ディレクトリ

ステップ3: エラー対策を施したDockerfileの作成

ベースイメージの取得失敗に備え、国内ミラーを利用したり、軽量なイメージを選定します。また、パッケージキャッシュをクリアしてイメージサイズを削減します。

# Dockerfile
# 軽量なOSイメージを選択
FROM python:3.10-slim-bullseye

# タイムゾーンとロケールの設定（エラー防止）
ENV TZ=Asia/Tokyo
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# システム依存パッケージのインストール（必要に応じて）
RUN apt-get update && apt-get install -y --no-install-recommends 
    git 
    curl 
    wget 
    && rm -rf /var/lib/apt/lists/* # キャッシュクリアでイメージ縮小

# 作業ディレクトリの作成と権限設定
RUN mkdir -p /workspace
WORKDIR /workspace

# 依存関係を先にコピーしてキャッシュを効かせる
COPY requirements.txt .
RUN pip install --no-cache-dir --upgrade pip && 
    pip install --no-cache-dir -r requirements.txt

# rootユーザー以外で実行するためのユーザー作成（セキュリティとパーミッション対策）
RUN useradd -m -u 1000 -s /bin/bash developer
RUN chown -R developer:developer /workspace
USER developer

# コンテナ起動時のデフォルトコマンド
CMD ["/bin/bash"]

ステップ4: 総合的なdocker-compose.ymlの作成

GPUサポート、リソース制限、ボリュームマウントを全て設定した完全版です。

# docker-compose.yml
version: '3.8'

services:
  ai-dev:
    build: .
    container_name: ai_development_container
    # 環境変数は.envファイルから読み込み
    env_file:
      - .env
    environment:
      - PYTHONUNBUFFERED=1 # ログバッファリングをオフ
      - NVIDIA_VISIBLE_DEVICES=all # GPU可視化
    # ホストマシンのworkspaceディレクトリをコンテナ内にマウント
    volumes:
      - ./workspace:/workspace
      - ~/.gitconfig:/home/developer/.gitconfig:ro # Git設定の共有（オプション）
    # リソース制限を設定（OOM防止）
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
        limits:
          memory: 16G # メモリ制限。ホストの容量に応じて調整
          cpus: '4.0' # CPU制限
    # インタラクティブな開発用
    stdin_open: true
    tty: true
    # JupyterLabなどを使う場合はポート公開
    ports:
      - "8888:8888"
    # コンテナ内でホストと同じユーザーIDを使う（Linux/macOSのパーミッション問題解決）
    user: "${UID:-1000}:${GID:-1000}"
    # NVIDIAランタイムの指定（docker-compose v2.3以降では`deploy`セクションで代用可能）
    # runtime: nvidia

# 必要に応じて別サービス（DBなど）を定義
#  postgres:
#    image: postgres:15
#    environment:
#      POSTGRES_PASSWORD: example

ステップ5: 環境設定ファイルと依存関係ファイルの作成

# .env (環境変数ファイル。gitignoreに追加を推奨)
UID=1000
GID=1000
# プロキシ環境下の場合
# HTTP_PROXY=http://your-proxy:port
# HTTPS_PROXY=http://your-proxy:port

# requirements.txt (依存ライブラリ。バージョンを固定して再現性を確保)
torch==2.1.0
torchvision==0.16.0
torchaudio==2.1.0
--index-url https://download.pytorch.org/whl/cu118 # CUDA 11.8用
tensorflow==2.13.0
jupyterlab==4.0.7
pandas==2.1.3
scikit-learn==1.3.2
matplotlib==3.8.2

ステップ6: ビルドと起動、およびトラブルシューティングコマンド

実際に環境を構築し、問題が発生した際の確認コマンドです。

# 1. イメージのビルド（初回またはDockerfile変更時）
docker-compose build --no-cache # キャッシュを使わず完全リビルド

# 2. コンテナの起動（バックグラウンドで）
docker-compose up -d

# 3. 起動したコンテナ内でインタラクティブシェルを実行
docker-compose exec ai-dev bash

# --- トラブルシューティングコマンド ---
# ビルドログを詳細に確認
docker-compose build --no-cache 2>&1 | tee build.log

# コンテナのログをリアルタイムで確認
docker-compose logs -f ai-dev

# コンテナ内でGPUが認識されているか確認
docker-compose exec ai-dev python -c "import torch; print(torch.cuda.is_available())"

# コンテナのリソース使用状況を確認
docker stats ai_development_container

# 問題が解決しない場合は、一旦すべてをクリーンアップして再開
docker-compose down -v # ボリュームも削除
docker system prune -a # 未使用のイメージ、コンテナ全削除（注意して使用）

まとめ・補足情報

Docker Composeを使用したAI開発環境の構築は、環境の再現性と移植性を劇的に高めます。本ガイドで紹介したテンプレートと対策により、ほとんどの初期構築エラーを回避できるでしょう。

重要な補足点:

  • イメージの軽量化: 本番デプロイを考える場合は、マルチステージビルドを検討し、最終イメージから開発ツールを削除しましょう。
  • Docker Compose V2: 最近のDocker Desktopではdocker compose（ハイフンなし）コマンドが標準です。機能はほぼ同等ですが、docker-compose.ymlのversion指定が不要になるなど、いくつかの違いがあります。
  • データの永続化: 学習済みモデルや重要なデータは、workspaceボリューム以外に、名前付きボリュームやクラウドストレージにバックアップすることをお勧めします。
  • セキュリティ: .envファイルにはパスワードなどの機密情報を直接書かず、Dockerのシークレット機能や外部のシークレット管理サービスを利用してください。

このテンプレートをベースに、ご自身のプロジェクトに必要なサービス（MySQL、Redis、MLflowなど）をdocker-compose.ymlに追加していくことで、複雑なAI開発環境も簡単に管理できるようになります。環境構築でつまずく時間を減らし、本質的なモデル開発や実験に集中しましょう。

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