セットアップガイド

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

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

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

AI開発を始める際、Pythonバージョン、CUDA、cuDNN、各種ライブラリ（PyTorch、TensorFlow、JupyterLabなど）の環境構築は複雑で時間がかかります。Docker Composeを使えば、これらの依存関係をコードで定義し、一括で環境を構築・共有できます。しかし、特に初心者・中級者がこのテンプレートを利用する際、以下のようなエラーに頻繁に遭遇します。

  • ビルドエラー: ERROR: failed to solve: python:3.9-slim: pulling image failed などのイメージ取得失敗。
  • 起動エラー: ERROR: .IOError: [Errno 13] Permission denied: '/workspace' などのパーミッション問題。
  • GPU認識エラー: WARNING: Detected NVIDIA GPU, but nvidia-container-toolkit is not installed. や、PyTorch内で torch.cuda.is_available() が False を返す。
  • ポート競合エラー: ERROR: for jupyter Cannot start service jupyter: driver failed programming external connectivity on endpoint: Bind for 0.0.0.0:8888 failed: port is already allocated。
  • メモリ不足エラー: モデルの学習中に Killed や CUDA out of memory が発生する。

本記事では、これらの問題を解決し、誰でも再現可能なAI開発環境をDocker Composeで構築するための実践的なテンプレートとトラブルシューティング手順を解説します。

原因の解説：なぜエラーが発生するのか？

上記のエラーは、主に以下の4つの原因に分類されます。

1. ホストマシンのDocker環境設定不足

GPUサポートにはNVIDIA Container Toolkitのインストールが必須です。また、Dockerデーモンが正しく起動していない、またはユーザーがdockerグループに属していないとパーミッションエラーの原因となります。

2. Dockerfileやdocker-compose.ymlの記述ミス

ベースイメージの指定ミス、依存パッケージのバージョン競合、ボリュームマウント設定の誤り、ビルドコンテキストの指定漏れなど、YAMLやDockerfileの些細な記述ミスがビルド・実行失敗を招きます。

3. リソース（ポート、メモリ、GPU）の競合

ホストマシンですでに使用中のポート（8888, 6006など）をコンテナが使おうとすると競合が発生します。また、Docker Desktopなどではデフォルトでメモリ制限がかかっており、大規模モデルの学習時に不足することがあります。

4. ネットワーク環境の問題

企業内プロキシ下などでは、Dockerイメージのプルやpipインストールが失敗することがあります。

解決方法：ステップバイステップで構築する

以下に、PyTorch, TensorFlow, JupyterLab, TensorBoardを含む標準的なAI開発環境を構築する手順を示します。

ステップ1: 事前準備（ホストマシン側）

まず、ホストマシンにDocker、Docker Compose、そしてGPUを使う場合はNVIDIA Container Toolkitをインストールします。

# DockerとDocker Composeのインストール（Ubuntu例）
sudo apt-get update
sudo apt-get install docker.io docker-compose

# ユーザーをdockerグループに追加（再ログインが必要）
sudo usermod -aG docker $USER

# 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

# インストール確認
docker --version
docker-compose --version
docker run --rm --gpus all nvidia/cuda:11.8.0-base-ubuntu22.04 nvidia-smi

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

プロジェクトルートに以下の3つのファイルを作成します。

your-ai-project/
├── docker-compose.yml
├── Dockerfile
└── requirements.txt

Dockerfile: ベースイメージと基本的なセットアップを定義。

# Dockerfile
FROM pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime

# 作業ディレクトリの設定と必要なパッケージインストール
WORKDIR /workspace
RUN apt-get update && apt-get install -y 
    git 
    wget 
    curl 
    vim 
    && rm -rf /var/lib/apt/lists/*

# プロキシ環境下でのpip設定（必要な場合）
# ENV PIP_PROXY=http://your-proxy:port

# 依存Pythonパッケージのインストール
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt 
    && pip install jupyterlab tensorboard

# JupyterLabのポート公開
EXPOSE 8888
# TensorBoardのポート公開
EXPOSE 6006

# コンテナ起動時のデフォルトコマンド
CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root", "--NotebookApp.token=''"]

requirements.txt: インストールするPythonライブラリを列挙。

# requirements.txt
torchvision>=0.16.0
tensorflow>=2.13.0
scikit-learn
pandas
matplotlib
seaborn
opencv-python-headless
transformers
datasets

docker-compose.yml: サービス（コンテナ）の構成、ボリューム、ポート、GPU設定を定義。

# docker-compose.yml
version: '3.8'

services:
  ai-dev:
    build: .
    container_name: ai-development-env
    # ホストマシンのカレントディレクトリをコンテナの/workspaceにマウント
    volumes:
      - ./:/workspace
      - ~/.cache:/root/.cache # pip/ huggingfaceのキャッシュを永続化
    ports:
      - "8888:8888" # JupyterLab
      - "6006:6006" # TensorBoard
    # GPUリソースの指定（NVIDIA GPU利用時）
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    # 環境変数の設定（例: 日本時間、プロキシ）
    environment:
      - TZ=Asia/Tokyo
      - PYTHONUNBUFFERED=1
    # コンテナ内で特権モード（必要な場合のみ。セキュリティリスクに注意）
    # privileged: true
    # インタラクティブなシェルを維持
    stdin_open: true
    tty: true
    # リソース制限の設定（メモリ、CPU）
    mem_limit: 16g
    cpus: 4.0

ステップ3: ビルドと起動

プロジェクトルートで以下のコマンドを実行します。

# イメージをビルド（初回またはDockerfile変更時）
docker-compose build

# コンテナをバックグラウンドで起動
docker-compose up -d

# ログを確認（起動エラー時など）
docker-compose logs -f ai-dev

# 起動中のコンテナに入る（シェルアクセス）
docker-compose exec ai-dev /bin/bash

# コンテナの停止
docker-compose down

ステップ4: 動作確認

ブラウザで http://localhost:8888 にアクセスし、JupyterLabが起動していることを確認します。コンテナ内で以下のPythonコードを実行し、GPUが認識されているか確認しましょう。

# コンテナ内で実行
python -c "import torch; print(f'PyTorch CUDA available: {torch.cuda.is_available()}'); print(f'GPU device: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else "None"}')"
python -c "import tensorflow as tf; print(f'TF Version: {tf.__version__}'); print(f'TF GPUs: {tf.config.list_physical_devices("GPU")}')"

よくあるエラーとその対処法

エラー1: ビルド時の「pull access denied」またはネットワークエラー

エラーメッセージ: ERROR: failed to solve: pytorch/pytorch:2.1.0-cuda11.8-cudnn8-runtime: pulling image failed

解決策: Dockerのログイン状態を確認し、プロキシ環境下ではDockerデーモンのプロキシ設定を行います。

# Docker Hubにログイン（公開イメージでもレート制限回避のため推奨）
docker login

# プロキシ設定（/etc/systemd/system/docker.service.d/http-proxy.conf を作成）
# [Service]
# Environment="HTTP_PROXY=http://proxy.example.com:8080/"
# Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
# 設定後、デーモンを再起動
sudo systemctl daemon-reload
sudo systemctl restart docker

エラー2: 起動時の「Permission denied」ボリュームマウントエラー

エラーメッセージ: ERROR: for ai-dev Cannot start service ai-dev: error while mounting volume '/var/lib/docker/volumes/...': permission denied

解決策: ホスト側のディレクトリパーミッションを調整するか、Dockerfile内でユーザーを作成・切り替えを行います。

# 解決策A: ホスト側のプロジェクトディレクトリのオーナーを調整（セキュリティに注意）
sudo chown -R $USER:$USER .

# 解決策B: Dockerfileに非rootユーザー作成処理を追加（推奨）
# Dockerfile内に以下を追記
RUN useradd -m -u 1000 -s /bin/bash developer
RUN chown -R developer:developer /workspace
USER developer

エラー3: GPUが認識されない

状況: torch.cuda.is_available() が False を返す。

解決策: NVIDIA Container Toolkitのインストールを確認し、docker-compose.ymlのdeployセクションが正しく記述されているか確認します。また、ホストのCUDAドライババージョンとコンテナ内のCUDAバージョンの互換性を確認します。

# ホストのCUDAドライババージョン確認
nvidia-smi

# コンテナ内のCUDAツールキットバージョン確認
docker-compose exec ai-dev nvcc --version

# docker-compose.ymlの代わりにruntimeを直接指定する方法（compose v2.3以下）
# services:
#   ai-dev:
#     runtime: nvidia
#     environment:
#       - NVIDIA_VISIBLE_DEVICES=all

エラー4: ポートが既に使用中

解決策: 競合しているポートを変更するか、使用中のプロセスを停止します。

# ポート8888を使用しているプロセスを確認
sudo lsof -i:8888

# docker-compose.ymlのports設定を変更（例: ホストの8899をコンテナの8888にマップ）
# ports:
#   - "8899:8888"

まとめ・補足情報

Docker Composeを用いたAI開発環境のテンプレート構築は、環境の再現性を劇的に高め、チームでの開発や複数マシンでの作業を効率化します。本記事で紹介したテンプレートは、PyTorchとTensorFlowの両方を含む汎用的なものですが、特定のフレームワーク（例: Stable Diffusion WebUI, LangChain）に特化した環境も同様の手法で構築可能です。

さらに環境を発展させるためのヒント:

  • マルチステージビルド: 最終イメージのサイズを小さくするために、ビルド用と実行用のイメージを分離できます。
  • .dockerignoreファイル: ビルドコンテキストに不要なファイル（.git, __pycache__, 大容量データ）を含めないようにし、ビルドを高速化します。
  • 開発/本番用のcomposeファイル分離: docker-compose.override.yml を使って開発時のみ有効な設定（ソースコードのマウント、デバッグポート開放など）を管理できます。
  • VS Code Dev Containers連携: 作成したDockerfileを元に、VS CodeのRemote – Containers拡張機能を使ってシームレスなコンテナ内開発が可能になります。

このテンプレートを出発点として、プロジェクトの要件に合わせてカスタマイズを加えることで、ストレスのないAI開発環境の基盤を手に入れることができるでしょう。エラーが発生した場合は、まずdocker-compose logsで詳細なログを確認し、問題を特定することを心がけてください。

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