セットアップガイド

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

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

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

AI開発において、TensorFlow、PyTorch、JupyterLab、CUDAなど必要なツールを一括で構築できるDocker Composeは非常に便利です。しかし、特に初心者や中級者の方がテンプレートを使用して環境構築を試みる際、以下のようなエラーに直面することが頻繁にあります。

  • ビルドエラー: Dockerイメージのビルド中にパッケージの依存関係エラーが発生する。
  • 起動失敗: docker-compose up を実行してもコンテナがすぐに終了（Exit）してしまう。
  • GPU認識エラー: NVIDIA Dockerの設定が不十分で、コンテナ内からGPUが利用できない。
  • ボリュームマウントエラー: ホストマシンのディレクトリをコンテナにマウントできず、データやコードがアクセス不能になる。
  • ポート競合エラー: ホストマシンですでに使用中のポート（8888, 6006など）が指定され、JupyterLabやTensorBoardが起動できない。

これらの問題は、環境のわずかな差異（OS、Dockerバージョン、GPUドライバなど）が原因で発生し、開発開始までのハードルを高めてしまいます。

原因の解説

上記のエラーが発生する主な原因は、以下の4点に集約されます。

1. ベースイメージの指定ミスと依存関係の不一致

Dockerfile内で指定するベースイメージ（例: tensorflow/tensorflow:latest-gpu）のタグが曖昧だったり、イメージが提供するPythonバージョンやライブラリのバージョンが、後続のpip installで要求するバージョンと衝突することがあります。特にlatestタグは時とともに内容が変わるため、再現性が損なわれます。

2. Docker Composeファイルの記述ミス

docker-compose.ymlのYAMLフォーマットエラー（インデントの不備など）や、サービス定義の誤りが原因でコンテナが正しく起動しません。また、restart: "no"などの設定では、コンテナ内のメインプロセスが終了するとコンテナ自体も停止してしまいます。

3. NVIDIA Dockerランタイムの未設定またはバージョン不一致

GPUを使用するAI開発環境では、ホストマシンにNVIDIAドライバ、Docker、そしてNVIDIA Container Toolkit（旧NVIDIA-Docker）が正しくインストール・設定されている必要があります。これらが不足している、またはバージョンが古いと、コンテナからnvidia-smiコマンドを実行しても「GPUを認識できない」というエラーが発生します。

4. ホストマシンとのリソース競合

ポート番号やホストマシンのディレクトリパスは、他のアプリケーションや以前に起動したコンテナと競合する可能性があります。また、ホストマシンのユーザー権限とコンテナ内のユーザー権限が異なるため、マウントしたディレクトリへの書き込み権限エラーが発生することもあります。

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

ステップ1: プロジェクト構成の確認と基本テンプレートの作成

まず、以下のような標準的なディレクトリ構成を作成します。これにより、コード、データ、Docker設定が整理されます。

my_ai_project/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── scripts/          # エントリポイントスクリプトなど
├── src/              # アプリケーションコード
└── data/             # データセット（.gitignore対象）

ステップ2: Dockerfileの作成（再現性を重視）

ベースイメージは特定のバージョンをタグで明示し、必要なパッケージをインストールします。以下はPyTorch + Jupyter環境の例です。

# Dockerfile
# 特定バージョンのCUDAとPyTorchがプリインストールされたイメージを使用
FROM pytorch/pytorch:2.0.1-cuda11.7-cudnn8-runtime

# 作業ディレクトリを設定
WORKDIR /workspace

# システムパッケージの更新と必要ツールのインストール
RUN apt-get update && apt-get install -y 
    git 
    wget 
    curl 
    vim 
    && rm -rf /var/lib/apt/lists/*

# カレントディレクトリのrequirements.txtをコンテナにコピー
COPY requirements.txt .

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

# JupyterLabのポートを公開
EXPOSE 8888

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

ステップ3: docker-compose.ymlの作成（GPUサポート含む）

サービス、ボリューム、ポート、GPUリソースを定義します。YAMLのインデント（スペース2つ）に注意してください。

# docker-compose.yml
version: '3.8'

services:
  ai-dev:
    build: .
    container_name: my_ai_dev_env
    restart: unless-stopped # エラー時以外は再起動する
    ports:
      - "8888:8888" # JupyterLab
      - "6006:6006" # TensorBoard
    volumes:
      - ./src:/workspace/src # ソースコードをマウント
      - ./data:/workspace/data # データをマウント
      - ./notebooks:/workspace/notebooks # Jupyterノートブックをマウント
    environment:
      - NVIDIA_VISIBLE_DEVICES=all # GPUをコンテナから見えるようにする
    deploy: # GPUリソースの要求（Docker Compose v2.3+）
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    # stdin_openとttyはインタラクティブなシェルを使うために役立つ
    stdin_open: true
    tty: true

ステップ4: 環境構築と起動、およびトラブルシューティング

1. ビルドと起動:

# プロジェクトルート（docker-compose.ymlがある場所）で実行
docker-compose up --build

2. 起動失敗時のログ確認: コンテナがすぐに終了する場合は、ログを詳細に確認します。

docker-compose logs ai-dev
# または、ビルドログも含めて詳細に
docker-compose up --build 2>&1 | tee build.log

3. GPU認識確認: コンテナが起動したら、別のターミナルで実行中のコンテナ内でnvidia-smiを実行します。

docker exec my_ai_dev_env nvidia-smi

以下のようなエラーが出た場合:

docker: Error response from daemon: could not select device driver "" with capabilities: [[gpu]].

これはNVIDIA Container Toolkitがインストールされていない可能性が高いです。ホストマシンで以下のコマンドでインストールを確認・実行してください。

# NVIDIA Container Toolkitのインストール（Ubuntu例）
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

4. ポート競合の解決: ポート8888が既に使用中の場合は、docker-compose.ymlのports設定を変更します（例: "8899:8888"）。

コード例・コマンド例：実践的なテンプレート

以下は、上記の解決策を統合した、すぐに使える最小限のテンプレート例です。

# requirements.txt
jupyterlab
matplotlib
seaborn
pandas
scikit-learn
# tensorflow==2.12.0  # 必要に応じてコメントアウトを外す
# torchvision        # PyTorchイメージには基本含まれるが、必要なら追加

すべてのファイルを配置した後、以下のコマンドフローで環境を構築・利用します。

# 1. プロジェクトディレクトリに移動
cd my_ai_project

# 2. バックグラウンドでビルド＆起動（-dオプション）
docker-compose up --build -d

# 3. 起動状態を確認
docker-compose ps

# 4. JupyterLabにアクセス（ブラウザで）
# http://localhost:8888

# 5. コンテナ内でインタラクティブなbashシェルを開く（デバッグ用）
docker exec -it my_ai_dev_env /bin/bash

# 6. 環境の停止
docker-compose down

# 7. 環境の停止とボリューム、イメージの削除（完全クリーンアップ）
docker-compose down --volumes --rmi all

まとめ・補足情報

Docker Composeを用いたAI開発環境の一括構築は、再現性と移植性の高い環境をチームで共有するための強力な手段です。トラブルの大部分は、ベースイメージのバージョン固定、NVIDIA Container Toolkitの正しいインストール、docker-compose.ymlの構文と設定の確認の3点を徹底することで解決できます。

補足ポイント:

  • 開発と本番の分離: 開発用（Jupyterあり、ソースコードマウント）と本番用（軽量ランタイムイメージ、コード組み込み）でdocker-compose.override.ymlを使い分ける方法も効果的です。
  • Dockerのキャッシュ: requirements.txtの変更後にイメージを再ビルドする時、RUN pip installの前のレイヤーはキャッシュが効くようにCOPY requirements.txt .の順序を工夫しています。
  • セキュリティ: サンプルでは簡便さのため--allow-rootや空のトークンを使用していますが、本番環境や外部に公開する場合は、適切なユーザー作成とパスワード/トークンの設定が必須です。

このテンプレートとトラブルシューティング手順を参考に、スムーズなAI開発環境の構築を進めてください。環境構築でつまずく時間を減らし、本来のモデル開発や実験に集中できるようになります。

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