セットアップガイド

【Docker/環境】Docker ComposeでAI開発環境を構築！よくあるエラーと解決法を徹底解説

· 16分で読めます · 3 閲覧

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

AI開発、特に機械学習や深層学習のプロジェクトでは、Pythonバージョン、CUDA/cuDNN、各種ライブラリ（TensorFlow, PyTorch, scikit-learnなど）の依存関係が複雑で、環境構築に多くの時間を要します。Docker Composeを使えば、これらを一括で定義・構築できますが、実際に試すと以下のようなエラーに遭遇することが少なくありません。

  • ERROR: Couldn't connect to Docker daemon at http+docker://localhost - is it running?
  • ERROR: for ai-jupyter Cannot start service jupyter: driver failed programming external connectivity on endpoint ...: Bind for 0.0.0.0:8888 failed: port is already allocated
  • ERROR: failed to solve: process "/bin/sh -c pip install -r requirements.txt" did not complete successfully: exit code: 1
  • GPUがコンテナ内から認識されない（torch.cuda.is_available()がFalseを返す）
  • コンテナ内で作成したファイルのホスト側でのパーミッション問題

本記事では、これらのエラーの原因と、実践的な解決手順をステップバイステップで解説します。

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

上記のエラーは、主に以下の4つのカテゴリに分類され、それぞれ根本原因が異なります。

1. Dockerデーモン/サービスの問題

Docker Engine（デーモン）が起動していない、またはユーザーがdockerグループに属していないために権限不足が発生します。Linux環境ではサービス管理、Windows/macOSではDocker Desktopアプリケーションの起動状態が関わります。

2. リソース競合（ポート、ボリューム名）

ホストマシンですでに使用中のポート（例：8888, 6006）をdocker-compose.ymlで指定すると、バインド失敗エラーが発生します。同様に、既存のDockerボリュームやコンテナ名と重複する定義も問題を引き起こします。

3. ビルド時の依存関係解決失敗

Dockerfile内のRUN pip installコマンドで、互換性のないライブラリバージョンが指定されている、またはネットワークの問題でパッケージのダウンロードに失敗することが原因です。特に、PyTorchやTensorFlowのような巨大なパッケージや、特定のPythonバージョンに依存するライブラリで起こりがちです。

4. GPUリソースの認識問題

NVIDIA Docker Toolkit（nvidia-docker2）がインストールされていない、またはdocker-compose.ymlでGPUアクセスを許可する設定（deployセクションやruntime指定）が正しく記述されていない場合、コンテナ内からGPUを利用できません。

解決方法：ステップバイステップで環境を構築・トラブルシューティング

ステップ1: ベースとなるdocker-compose.ymlとDockerfileの準備

まず、最小限の構成から始め、段階的に機能を追加していくことが安定構築のコツです。プロジェクトルートに以下のファイルを作成します。

# docker-compose.yml
version: '3.8'

services:
  ai-jupyter:
    build: .
    container_name: ai-dev-container
    ports:
      - "8888:8888"
      - "6006:6006" # TensorBoard用
    volumes:
      - ./work:/workspace
      - ./data:/data
    working_dir: /workspace
    tty: true
    stdin_open: true
    # ステップ4でGPU設定を追加

# Dockerfile
FROM python:3.9-slim

WORKDIR /workspace

# システム依存パッケージのインストール（必要に応じて）
RUN apt-get update && apt-get install -y 
    git 
    wget 
    && rm -rf /var/lib/apt/lists/*

# 必要なPythonパッケージを明示的にインストール（requirements.txtより安定）
RUN pip install --upgrade pip
RUN pip install 
    jupyterlab==3.6.0 
    numpy==1.23.5 
    pandas==1.5.3 
    matplotlib==3.7.0 
    scikit-learn==1.2.2

# 必要に応じてPyTorchやTensorFlowを追加（CUDAバージョンに注意）
# RUN pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# RUN pip install tensorflow[and-cuda]==2.12.0

CMD ["jupyter", "lab", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root", "--NotebookApp.token=''"]

ステップ2: Dockerデーモンの起動と基本コマンド

ターミナルで以下のコマンドを実行し、Dockerが正しく動作するか確認します。

# Dockerサービスの状態確認（Linux）
sudo systemctl status docker

# Docker Desktop (Windows/macOS) はアプリケーションから起動

# Dockerデーモンとの通信テスト
docker version

# 現在のユーザーをdockerグループに追加（Linuxで権限エラーが出る場合）
sudo usermod -aG docker $USER
# 変更を反映するため、一度ログアウト&ログインするか、newgrp dockerを実行

docker versionでClientとServerの両方の情報が表示されれば成功です。Server情報が表示されない場合は、Dockerデーモンが起動していません。

ステップ3: ビルドと起動、ポート競合の解決

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

# イメージをビルド
docker-compose build

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

# 起動ログを確認
docker-compose logs -f ai-jupyter

ポート8888が既に使用されている場合のエラー対処法:

# ホストでポート8888を使用しているプロセスを確認
# Linux/macOS
lsof -i :8888
# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 8888

# 使用中ならプロセスを終了するか、docker-compose.ymlのポートマッピングを変更
# 例: "8899:8888" に変更（ホストの8899ポートをコンテナの8888に転送）

ステップ4: GPUサポートの有効化（NVIDIA GPUユーザー向け）

GPUを使用するには、ホストマシンにNVIDIAドライバとNVIDIA Container Toolkitがインストールされている必要があります。確認後、docker-compose.ymlを修正します。

# docker-compose.yml (修正版 - GPUサポート追加)
services:
  ai-jupyter:
    build: .
    container_name: ai-dev-container
    ports:
      - "8888:8888"
    volumes:
      - ./work:/workspace
    working_dir: /workspace
    deploy:  # Docker Compose v3形式でのGPU指定
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    # または runtime 指定（環境に応じて）
    # runtime: nvidia
    environment:
      - NVIDIA_VISIBLE_DEVICES=all
    tty: true
    stdin_open: true

コンテナ内でGPUが認識されているか確認:

# コンテナ内でPythonを実行
docker exec -it ai-dev-container python3

# Pythonインタラクティブシェル内で
>>> import torch
>>> print(torch.cuda.is_available())  # True と表示されれば成功
>>> print(torch.cuda.device_count())  # 利用可能なGPU数

ステップ5: 依存関係エラー（pip install失敗）のデバッグ

ビルド中にpip installが失敗した場合、Dockerのビルドキャッシュを利用して効率的にデバッグします。

# エラーが出たステップから再ビルド（キャッシュを使用）
docker-compose build --no-cache

# または、Dockerfileを一時的に修正してインタラクティブシェルで調査
# DockerfileのCMDの前に以下を追加:
# CMD ["/bin/bash"]

# ビルド後、コンテナに入って手動でpip実行
docker-compose run --rm ai-jupyter /bin/bash
# コンテナ内で
root@xxxx:/workspace# pip install -v 問題のパッケージ名
# 詳細なエラーメッセージを確認

よくある原因は、ベースイメージのPythonバージョンとライブラリの互換性です。python:3.9-slimのような安定版タグを使用し、ライブラリのバージョンを==で明示的に固定することが推奨されます。

コード例・コマンド例：実践的なAI開発環境テンプレート

以下は、PyTorchとJupyter Labを含む、より実践的な環境構築の例です。

# docker-compose.override.yml (環境別設定例)
# 本番用と開発用で設定を分けたい場合に使用
version: '3.8'
services:
  ai-jupyter:
    environment:
      - PYTHONPATH=/workspace
      - JUPYTER_ENABLE_LAB=yes
    # 開発中はホストのファイル変更を即時反映させるため、ボリュームを追加
    volumes:
      - ./src:/workspace/src
      - ./configs:/workspace/configs

# 便利な日常コマンド集
# コンテナ内でシェルを開く
docker-compose exec ai-jupyter /bin/bash

# コンテナを停止せずに再ビルド（変更を反映）
docker-compose up -d --build

# すべてのコンテナ、イメージ、ボリュームを一括削除（クリーンアップ）
docker-compose down --rmi all --volumes

# 特定サービスのログをリアルタイム表示
docker-compose logs -f ai-jupyter

# コンテナ内のリソース使用状況（CPU, メモリ）を確認
docker stats ai-dev-container

まとめ・補足情報

Docker Composeを使用したAI開発環境の構築は、再現性と移植性を大幅に向上させる強力な手法です。トラブルの大部分は、1) Dockerデーモンの状態、2) ポート・リソース競合、3) 依存関係のバージョン不一致、4) GPUランタイムの設定の4点に起因しています。本記事で紹介したステップバイステップの検証手順と、最小構成から始めて機能を追加していくアプローチを実践すれば、これらの問題を効率的に解決できるでしょう。

補足として、チームで開発環境を共有する場合は、docker-compose.ymlとDockerfileをバージョン管理システム（Git）にコミットし、.dockerignoreファイルで不要なファイル（__pycache__, 大きなデータセット, 仮想環境ディレクトリなど）がイメージにコピーされないように設定することをお勧めします。これにより、イメージサイズの肥大化を防ぎ、ビルド時間を短縮できます。

Docker Composeをマスターすることで、AIプロジェクトの環境構築にかかる時間と労力を最小限に抑え、本質的なモデル開発と実験に集中できるようになります。

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