セットアップガイド

【Docker/環境】JupyterLabでGPU対応AI開発環境を構築する手順とトラブルシューティング

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

1. 問題の概要：JupyterLab環境でGPUが認識されない・利用できない

Dockerを使用してJupyterLab環境を構築した際、以下のような問題に直面することがあります。

  • JupyterLab内で!nvidia-smiを実行してもGPUが表示されない
  • PyTorchやTensorFlowでtorch.cuda.is_available()がFalseを返す
  • 「CUDA driver version is insufficient for CUDA runtime version」などのエラーメッセージが表示される
  • Dockerコンテナ起動時に「Could not load dynamic library ‘libcudart.so.xx.x’」というエラーが発生する

これらの問題は、ホストマシンにGPUとNVIDIAドライバが正しくインストールされていても、Dockerコンテナ側の設定が不十分な場合に発生します。本記事では、NVIDIA Container Toolkitを使用して、JupyterLab環境でGPUを正しく認識・利用できるようにする手順を詳しく解説します。

2. 原因の解説：DockerのGPUサポートとNVIDIA Container Toolkit

従来のDocker環境では、GPUのようなハードウェアデバイスに直接アクセスすることができませんでした。この問題を解決するために、NVIDIAは「NVIDIA Container Toolkit」（旧称：nvidia-docker2）を提供しています。このツールキットは、Dockerコンテナ内からホストのNVIDIA GPUとドライバを安全に利用できるようにするブリッジの役割を果たします。

主な原因は以下の3点に集約されます：

  1. NVIDIA Container Toolkitがインストールされていない：DockerがGPUリソースを認識するためのランタイムがセットアップされていない。
  2. Dockerのランタイム設定が不適切：Dockerデーモンの設定ファイル（daemon.json）にNVIDIAランタイムが指定されていない。
  3. コンテナイメージのCUDAバージョン不一致：ホストのNVIDIAドライババージョンと、コンテナ内のCUDA Toolkitバージョンに互換性がない。

特に、CUDAドライバは下位互換性がありますが、上位互換性はない点に注意が必要です。つまり、コンテナ内のCUDAランタイムバージョンが、ホストのドライババージョンでサポートされている範囲内である必要があります。

3. 解決方法：ステップバイステップでの環境構築

ステップ1: 前提条件の確認

まず、ホストマシンに以下の要素が正しくインストールされていることを確認します。

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

# 出力例：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI 535.154.05   Driver Version: 535.154.05   CUDA Version: 12.2    |
# |-------------------------------+----------------------+----------------------+
# この「CUDA Version」は、ホストドライバがサポートする最大のCUDAバージョンを示します。

# Dockerのインストール確認
docker --version

ステップ2: NVIDIA Container Toolkitのインストール

Ubuntu/Debian系OSを例に、インストール手順を示します。

# パッケージリポジトリとGPGキーの設定
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | 
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | 
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# パッケージリストの更新とインストール
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# Dockerデーモンの再起動（設定を適用）
sudo systemctl restart docker

ステップ3: Dockerランタイムの設定

/etc/docker/daemon.jsonファイルを編集して、NVIDIAをデフォルトのランタイムとして設定します。ファイルが存在しない場合は新規作成します。

# daemon.jsonの設定
sudo tee /etc/docker/daemon.json <<EOF
{
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  },
  "default-runtime": "nvidia"
}
EOF

# Dockerデーモンの再起動
sudo systemctl daemon-reload
sudo systemctl restart docker

ステップ4: GPU対応JupyterLabコンテナの起動

CUDAと主要なAIフレームワークがプリインストールされた公式イメージを使用するのが効率的です。Jupyterの公式イメージにCUDAサポートを追加したものを使用します。

# 基本的なJupyterLabコンテナの起動（GPU対応）
docker run -d 
  --gpus all 
  -p 8888:8888 
  -v $(pwd)/workspace:/home/jovyan/work 
  --name jupyterlab-gpu 
  jupyter/tensorflow-notebook:latest

# または、PyTorch公式イメージを使用する場合
docker run -d 
  --gpus all 
  -p 8888:8888 
  -v $(pwd)/workspace:/workspace 
  --name pytorch-jupyter 
  pytorch/pytorch:latest

# 起動ログの確認（トークンを取得）
docker logs jupyterlab-gpu
# 出力に含まれる「http://127.0.0.1:8888/lab?token=xxxxxxxx」のようなURLをブラウザで開く

ステップ5: コンテナ内での動作確認

JupyterLabのNotebookまたはターミナルで、以下のコマンドを実行してGPUが正しく認識されているか確認します。

# コンテナ内での確認コマンド
!nvidia-smi

# Pythonでの確認
import torch
print(f"PyTorch CUDA available: {torch.cuda.is_available()}")
if torch.cuda.is_available():
    print(f"GPU device count: {torch.cuda.device_count()}")
    print(f"Current device: {torch.cuda.current_device()}")
    print(f"Device name: {torch.cuda.get_device_name(0)}")

# TensorFlowでの確認
import tensorflow as tf
print(f"TensorFlow GPU available: {len(tf.config.list_physical_devices('GPU')) > 0}")

4. よくあるエラーとトラブルシューティング

エラー1: 「docker: Error response from daemon: could not select device driver…」

このエラーは、NVIDIA Container Toolkitが正しくインストールされていないか、Dockerデーモンの再起動が行われていない場合に発生します。

# 解決策：NVIDIA Container Toolkitの再インストールとDocker再起動
sudo apt-get purge nvidia-container-toolkit
sudo apt-get install nvidia-container-toolkit
sudo systemctl restart docker

エラー2: 「CUDA error: no kernel image is available for execution on the device」

このエラーは、コンテナ内のPyTorch/TensorFlowが、ホストGPUのアーキテクチャ（Compute Capability）をサポートしていないバージョンでコンパイルされている場合に発生します。

# 解決策：正しいバージョンのイメージを使用する
# 例：CUDA 11.8とPyTorch 2.0の組み合わせで、広範なGPUをサポート
docker run --gpus all pytorch/pytorch:2.0.1-cuda11.8-cudnn8-runtime

エラー3: 「Could not load dynamic library ‘libcudart.so.xx.x’」

コンテナ内のCUDAランタイムバージョンとホストのドライババージョンに互換性がない場合に発生します。

# ホストのドライバがサポートするCUDAバージョンを確認
nvidia-smi

# 互換性のあるCUDAバージョンのイメージを選択
# 例：ホストのドライバがCUDA 12.2をサポートしている場合
docker run --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

エラー4: JupyterLabのカーネルがGPUを認識しない

コンテナ内のPython環境にCUDA対応版のPyTorch/TensorFlowがインストールされていない可能性があります。

# コンテナ内で正しいパッケージをインストール
# JupyterLabのターミナルまたはNotebookセルで実行
!pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# または
!pip install tensorflow[and-cuda]

5. まとめ・補足情報

JupyterLabでGPU対応のAI開発環境を構築するには、ホスト側のNVIDIAドライバ、Docker、NVIDIA Container Toolkitの正しいセットアップが不可欠です。特に、ホストのドライババージョンとコンテナ内のCUDAランタイムバージョンの互換性に注意を払う必要があります。

ベストプラクティス：

  1. ホストのNVIDIAドライバは、可能な限り最新の安定版を使用する。
  2. Dockerイメージは、nvidia/cudaやフレームワーク公式のCUDA対応イメージを利用する。
  3. プロジェクトごとに異なる環境が必要な場合は、docker-compose.ymlファイルを作成して管理する。
  4. データの永続化のために、ホストのディレクトリをコンテナにマウントする（-vオプション）。

docker-compose.ymlの例：

version: '3.8'
services:
  jupyterlab:
    image: jupyter/tensorflow-notebook:latest
    runtime: nvidia
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    ports:
      - "8888:8888"
    volumes:
      - ./workspace:/home/jovyan/work
    environment:
      - JUPYTER_ENABLE_LAB=yes
      - GRANT_SUDO=yes

この設定により、再現性の高いGPU対応のJupyterLab環境を簡単に構築・共有することができます。環境構築で問題が発生した場合は、各コンポーネント（ドライバ、Docker、NVIDIA Container Toolkit、コンテナイメージ）のバージョン互換性をまず確認し、段階的に問題を切り分けることが解決への近道です。

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