NVIDIA Container Toolkit 安裝指南 GPU加速

在 Windows 11 上為 Docker 容器啟用 NVIDIA GPU 加速，提升 Ollama 和 Open WebUI 的推理速度

1
系統檢查
2
驅動安裝
3
工具包安裝
4
Docker配置
5
測試驗證

系統檢查與準備

1 確認您的 NVIDIA GPU 支援 CUDA

並非所有 NVIDIA GPU 都支援 CUDA 和 Docker 容器加速。請確認您的 GPU 屬於以下系列：

GPU 系列 CUDA 支援 VRAM 需求 效能等級
RTX 40 系列 (4090, 4080, 4070等) 完整支援 12GB+ (建議) 優秀
RTX 30 系列 (3090, 3080, 3070等) 完整支援 8GB+ (建議) 優秀
RTX 20 系列 (2080, 2070, 2060等) 完整支援 6GB+ (最低) 良好
GTX 16 系列 (1660, 1650等) 有限支援 4GB+ (最低) 一般
GTX 10 系列 (1080, 1070, 1060等) 有限支援 4GB+ (最低) 一般
Quadro 系列 完整支援 8GB+ (建議) 優秀
提示： 對於 AI 推理任務，建議至少使用具有 8GB VRAM 的 GPU。Llama 3.1 8B 模型需要約 5-6GB VRAM，如果 VRAM 不足，部分層將會使用系統記憶體，降低效能。

2 檢查當前 GPU 和驅動程式

在 Windows 上開啟 PowerShell 或命令提示字元，執行以下指令：

# 檢查 NVIDIA GPU 資訊
nvidia-smi

# 如果 nvidia-smi 指令不存在，表示尚未安裝 NVIDIA 驅動程式
# 或者使用 PowerShell 指令
Get-CimInstance -ClassName Win32_VideoController | Where-Object {$_.AdapterCompatibility -like "*NVIDIA*"} | Format-List Name, DriverVersion, AdapterRAM

如果您看到類似以下的輸出，表示 NVIDIA 驅動程式已安裝：

+-----------------------------------------------------------------------------+
| NVIDIA-SMI 535.154.05   Driver Version: 535.154.05   CUDA Version: 12.2    |
|-------------------------------+----------------------+----------------------+
| GPU  Name            TCC/WDDM | Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|                               |                      |               MIG M. |
|===============================+======================+======================|
|   0  NVIDIA GeForce ... WDDM  | 00000000:01:00.0  On |                  N/A |
| N/A   45C    P8    10W /  N/A |    500MiB /  8192MiB |      0%      Default |
|                               |                      |                  N/A |
+-------------------------------+----------------------+----------------------+
注意： 如果 nvidia-smi 指令未找到，請先安裝 NVIDIA 顯示驅動程式。前往 NVIDIA 驅動程式下載頁面 下載並安裝最新驅動程式。

3 確認 WSL2 已正確安裝

NVIDIA Container Toolkit 需要在 WSL2 環境中運作。確認 WSL2 已正確安裝：

# 檢查 WSL 版本
wsl --list --verbose

# 預期輸出應該類似：
#   NAME      STATE           VERSION
# * Ubuntu    Running         2
重要： 如果 VERSION 欄位顯示為 1，您需要將發行版轉換為 WSL2： 
wsl --set-version Ubuntu 2

安裝 NVIDIA 驅動程式與 CUDA 工具包

Windows 驅動程式
WSL2 驅動程式
CUDA 工具包

1 下載並安裝 NVIDIA 顯示驅動程式

如果您尚未安裝 NVIDIA 驅動程式，請按照以下步驟操作：

選擇您的 GPU 型號和作業系統（Windows 11）
下載 Game Ready 驅動程式（GRD）或 Studio 驅動程式
執行安裝程式，選擇「自訂安裝」並勾選所有元件
安裝完成後重新啟動電腦
建議： 安裝最新版本的驅動程式，但如果您遇到相容性問題，可以嘗試安裝較舊的穩定版本。CUDA 12.x 需要驅動程式版本 525.60.13 或更高。

2 為 WSL2 安裝 NVIDIA 驅動程式

WSL2 需要專門的 NVIDIA 驅動程式才能在 Linux 子系統中存取 GPU：

下載網址：https://developer.nvidia.com/cuda-downloads?target_os=Windows&target_arch=x86_64&target_version=11&target_type=exe_local
注意： 適用於 WSL2 的 NVIDIA 驅動程式與標準 Windows 驅動程式不同。即使您已安裝 Windows 驅動程式，仍需要安裝此 WSL2 專用驅動程式。

3 安裝 CUDA 工具包（可選）

CUDA 工具包主要用於開發，對於僅執行容器而言並非必要，但建議安裝以確保完整相容性：

下載網址：https://developer.nvidia.com/cuda-downloads

安裝步驟：

選擇「Windows」→「x86_64」→「11」→「exe (local)」
下載並執行安裝程式
選擇「自訂安裝」，建議取消勾選「Visual Studio Integration」除非您需要
安裝完成後，確認 CUDA 已加入系統 PATH

驗證 CUDA 安裝：

# 檢查 CUDA 版本
nvcc --version

# 或使用
nvidia-smi | findstr CUDA

# 預期輸出應顯示 CUDA 版本（如 12.2 或 12.4）

安裝 NVIDIA Container Toolkit

1 在 WSL2 中安裝 NVIDIA Container Toolkit

開啟 WSL2 終端機（Ubuntu），執行以下指令：

# 1. 更新套件清單
sudo apt-get update

# 2. 安裝依賴套件
sudo apt-get install -y ca-certificates curl gnupg

# 3. 添加 NVIDIA 的 GPG 金鑰
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/nvidia-container-toolkit.gpg

# 4. 添加 NVIDIA 的套件庫
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/etc/apt/keyrings/nvidia-container-toolkit.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 5. 更新套件清單
sudo apt-get update

# 6. 安裝 NVIDIA Container Toolkit
sudo apt-get install -y nvidia-container-toolkit

# 7. 重新啟動 Docker 服務
sudo systemctl restart docker

# 注意：如果 systemctl 在 WSL2 中不可用，請改用以下指令：
# sudo service docker restart
注意： 如果您使用的是 WSL2 的 Ubuntu 發行版，上述指令應該可以正常運作。如果使用其他發行版，請參考 官方安裝指南。

2 配置 Docker 以使用 NVIDIA 運行時

在 WSL2 終端機中執行以下指令：

# 1. 建立 nvidia-container-runtime 的配置
sudo nvidia-ctk runtime configure --runtime=docker

# 2. 重新啟動 Docker 服務
sudo systemctl restart docker
# 或
sudo service docker restart

# 3. 檢查 NVIDIA 運行時是否已註冊
sudo docker info | grep -i runtime

# 預期輸出應包含：
# Runtimes: nvidia runc
# Default Runtime: runc
提示： 如果上述指令無效，您可以手動編輯 Docker 配置檔案： 
sudo nano /etc/docker/daemon.json
添加以下內容： 
{
  "runtimes": {
    "nvidia": {
      "path": "nvidia-container-runtime",
      "runtimeArgs": []
    }
  },
  "default-runtime": "nvidia"
}
然後重新啟動 Docker。

配置 Docker Compose 使用 GPU

1 修改 docker-compose.yml 檔案

開啟您的 docker-compose.yml 檔案，取消註解 GPU 相關設定：

# 在 ollama 服務下添加或取消註解以下配置
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
      - ./ollama-models:/root/.ollama/models
    environment:
      - "OLLAMA_KEEP_ALIVE=24h"
      - "OLLAMA_HOST=0.0.0.0"
    # GPU 加速配置 - 取消註解以下區塊
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all  # 使用所有 GPU，或指定數量如 1
              capabilities: [gpu]
    restart: unless-stopped
    networks:
      - ai-network

完整版的 docker-compose.yml 應包含以下 GPU 配置：

version: '3.8'

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    environment:
      - "OLLAMA_BASE_URL=http://host.docker.internal:11434"
      - "WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY:-default_secret_key_change_me}"
      - "WEBUI_NAME=Local AI Assistant (GPU加速)"
      - "WEBUI_URL=http://localhost:3000"
    volumes:
      - open-webui-data:/app/backend/data
    depends_on:
      - ollama
    restart: unless-stopped
    networks:
      - ai-network

  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama-data:/root/.ollama
      - ./ollama-models:/root/.ollama/models
    environment:
      - "OLLAMA_KEEP_ALIVE=24h"
      - "OLLAMA_HOST=0.0.0.0"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped
    networks:
      - ai-network

volumes:
  open-webui-data:
    driver: local
  ollama-data:
    driver: local

networks:
  ai-network:
    driver: bridge

2 設定環境變數（可選）

建立 .env 檔案來管理環境變數，特別是設定 GPU 相關參數：

# GPU 相關設定
NVIDIA_VISIBLE_DEVICES=all
NVIDIA_DRIVER_CAPABILITIES=compute,utility

# Ollama 設定
OLLAMA_NUM_GPU=1
OLLAMA_GPU_LAYERS=999  # 使用所有可用的 GPU 層

# Open WebUI 設定
WEBUI_SECRET_KEY=your_secure_secret_key_here
WEBUI_NAME=Local AI Assistant (GPU加速)

# 記憶體限制（根據您的 GPU 調整）
OLLAMA_MAX_VRAM=8192  # 8GB VRAM

然後在 docker-compose.yml 中引用這些環境變數：

environment:
  - "NVIDIA_VISIBLE_DEVICES=${NVIDIA_VISIBLE_DEVICES:-all}"
  - "OLLAMA_NUM_GPU=${OLLAMA_NUM_GPU:-1}"
  - "OLLAMA_KEEP_ALIVE=24h"
  - "OLLAMA_HOST=0.0.0.0"

測試與驗證 GPU 加速

1 啟動服務並測試 GPU

在包含 docker-compose.yml 的目錄中執行：

# 停止現有服務（如果正在運行）
docker-compose down

# 使用新的配置啟動服務
docker-compose up -d

# 檢查容器是否使用 GPU
docker exec ollama nvidia-smi

# 或從主機檢查
docker inspect ollama | grep -i nvidia

# 查看容器日誌確認 GPU 是否被識別
docker logs ollama | grep -i cuda

GPU 加速測試指令

執行以下指令來驗證 GPU 加速是否正常工作：

# 1. 測試 Ollama 是否使用 GPU
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.1:8b",
  "prompt": "簡短解釋 GPU 加速的重要性",
  "stream": false
}'

# 2. 檢查 Ollama 中模型的 GPU 層使用情況
docker exec ollama ollama ps

# 3. 測試基準效能（需要安裝 benchmarks）
docker run --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi --query-gpu=name,memory.total,memory.used --format=csv

# 4. 簡單的 CUDA 測試
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi -L

2 效能比較與最佳化

啟用 GPU 加速後，您應該看到顯著的效能提升：

任務 僅 CPU (估計) GPU 加速 (估計) 加速倍數
Llama 3.1 8B 載入時間 15-30 秒 3-8 秒 3-5x
生成回應 (10 tokens) 2-5 秒 0.1-0.3 秒 10-20x
生成長文 (100 tokens) 20-40 秒 1-3 秒 10-15x
批次處理 (多個請求) 線性增長 平行處理 依 GPU 核心數

最佳化提示

調整 Ollama 參數以獲得最佳 GPU 效能：

  • 設定 OLLAMA_NUM_GPU 為 GPU 數量
  • 調整 OLLAMA_GPU_LAYERS 為模型可用的最大層數
  • 使用量化模型 (如 q4_0, q8_0) 減少 VRAM 使用

監控工具

監控 GPU 使用情況：

  • nvidia-smi - 即時監控
  • nvtop - 類似 htop 的 GPU 監控
  • Windows 工作管理員 - 效能標籤頁

疑難排解

常見問題
錯誤訊息
進階除錯

常見問題與解決方案

問題： Docker 容器無法啟動，顯示 "could not select device driver" 錯誤
解決： 確認 NVIDIA Container Toolkit 已正確安裝並重新啟動 Docker
問題： nvidia-smi 在容器內無法執行
解決： 確保容器以 --gpus all 標籤執行，或 docker-compose.yml 中已正確配置 GPU
問題： 記憶體不足 (OOM) 錯誤
解決：
  • 使用較小的模型 (如 Gemma 2B)
  • 減少 OLLAMA_GPU_LAYERS 值
  • 增加系統虛擬記憶體
  • 使用量化模型 (q4_0)

常見錯誤訊息與解決方法

# 錯誤：OCI runtime create failed: container_linux.go:380
# 解決：更新 Docker 和 NVIDIA Container Toolkit 到最新版本

# 錯誤：could not select device driver with capabilities: [[gpu]]
# 解決：執行 sudo nvidia-ctk runtime configure --runtime=docker 並重啟 Docker

# 錯誤：CUDA error: out of memory
# 解決：減少模型大小或批次大小，或使用量化版本

# 錯誤：Failed to initialize NVML: Driver/library version mismatch
# 解決：重新啟動系統，確保驅動程式版本一致

# 錯誤：WSL2 does not support NVIDIA GPU
# 解決：安裝適用於 WSL2 的 NVIDIA 驅動程式，而不是標準 Windows 驅動程式

進階除錯步驟

# 1. 檢查 Docker 運行時配置
cat /etc/docker/daemon.json

# 2. 檢查 NVIDIA 容器工具包配置
cat /etc/nvidia-container-runtime/config.toml

# 3. 測試基本 GPU 容器
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi

# 4. 檢查 WSL2 中的 GPU 存取
wsl.exe --list --verbose
wsl.exe -d Ubuntu -- nvidia-smi

# 5. 查看系統日誌中的 GPU 相關錯誤
dmesg | grep -i nvidia
journalctl -u docker | grep -i nvidia

# 6. 驗證 CUDA 版本相容性
nvidia-smi | grep CUDA
docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvcc --version

GPU 加速配置完成！

恭喜！您已成功配置 NVIDIA GPU 加速。現在您的 Ollama 和 Open WebUI 應該能夠利用 GPU 進行快速推理。

前往 http://localhost:3000 測試效能提升。