Docker 運行 GPUStack 的詳細教程

GPUStack

GPUStack 是一個用于運行 AI 模型的開源 GPU 集群管理器。它具有廣泛的硬件兼容性，支持多種品牌的 GPU，并能在 Apple MacBook、Windows PC 和 Linux 服務器上運行。GPUStack 支持各種 AI 模型，包括大型語言模型（LLMs）、擴散模型、音頻模型、嵌入模型和重新排序模型。GPUStack 可以輕松擴展，只需添加更多 GPU 或節點即可擴展操作。它支持單節點多 GPU 和多節點推理和服務，并提供多種推理后端，如 llama-box、vox-box 和 vLLM。GPUStack 是一個輕量級的 Python 包，具有最小的依賴項和操作開銷，并且提供與 OpenAI 標準兼容的 API。此外，它還簡化了用戶和 API 密鑰的管理，提供了 GPU 性能和利用率的實時監控，以及令牌使用和速率限制的有效跟蹤。

關鍵特性

廣泛的硬件兼容性：支持管理 Apple Mac、Windows PC 和 Linux 服務器上不同品牌的 GPU。
廣泛的模型支持：支持從大語言模型（LLMs）、多模態模型（VLMs）、擴散模型、語音模型到嵌入和重新排序模型的廣泛模型。
異構 GPU 支持與擴展：能夠輕松添加異構 GPU 資源，并按需擴展算力規模。
分布式推理：支持單機多卡并行和多機多卡并行推理。
多推理后端支持：支持 llama-box（基于 llama.cpp 和 stable-diffusion.cpp）、vox-box 和 vLLM 作為推理后端。
輕量級 Python 包：最小的依賴和操作開銷。
OpenAI 兼容 API：提供兼容 OpenAI 標準的 API 服務。
用戶和 API 密鑰管理：簡化用戶和 API 密鑰的管理流程。
GPU 指標監控：實時監控 GPU 性能和利用率。
Token 使用和速率統計：有效跟蹤 token 使用情況，并管理速率限制。

支持的硬件平臺

Apple Metal（M 系列芯片）
NVIDIA CUDA（計算能力 6.0 及以上）
AMD ROCm
華為昇騰（CANN）
摩爾線程（MUSA）
海光 DTK

支持的模型類型

大語言模型（LLMs）：如 Qwen、LLaMA、Mistral、Deepseek、Phi、Yi 等。
多模態模型（VLMs）：如 Llama3.2-Vision、Pixtral、Qwen2-VL、LLaVA、InternVL2.5 等。
擴散模型：如 Stable Diffusion、FLUX 等。
嵌入模型：如 BGE、BCE、Jina 等。
重新排序模型：如 BGE、BCE、Jina 等。
語音模型：如 Whisper（語音轉文本）、CosyVoice（文本轉語音）等。

使用場景

GPUStack 適用于需要高效管理和調度 GPU 資源的場景，特別是在運行 AI 模型時。它支持單節點多 GPU 和多節點推理及服務，并提供多種推理后端，如 llama-box、vox-box 和 vLLM。GPUStack 是一個輕量級的 Python 包，具有最小的依賴項和操作開銷，并且提供與 OpenAI 標準兼容的 API。此外，它還簡化了用戶和 API 密鑰的管理，提供了 GPU 性能和利用率的實時監控，以及令牌使用和速率限制的有效跟蹤。

Docker 運行 GPUStack 的詳細教程

https://docs.gpustack.ai/latest/installation/docker-installation/

以下是使用 Docker 運行 GPUStack 的詳細教程，結合官方文檔與社區實踐整理而成。通過本指南，您可以在支持 NVIDIA GPU 的 Linux 環境中快速部署 GPUStack，并實現異構 GPU 集群的管理與大模型服務。

在這里插入圖片描述

一、環境準備

硬件與系統要求
- 確保系統已安裝 NVIDIA GPU，并驗證驅動兼容性（支持 CUDA 11.0 及以上版本）。
- 推薦使用 Ubuntu 22.04 LTS 或 CentOS 7+ 系統。

驗證 GPU 與依賴項

# 檢查 NVIDIA GPU 是否識別
lspci | grep -i nvidiaroot@i-28e6iose:/home/ubuntu# lspci | grep -i nvidia
00:0c.0 VGA compatible controller: NVIDIA Corporation TU102 [GeForce RTX 2080 Ti] (rev a1)
00:0d.0 Audio device: NVIDIA Corporation TU102 High Definition Audio Controller (rev a1)# 確認 GCC 已安裝
gcc --versionroot@i-28e6iose:/home/ubuntu# gcc --version
gcc (Ubuntu 9.5.0-6ubuntu2) 9.5.0
Copyright (C) 2019 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

二、安裝 NVIDIA 驅動與 Docker

安裝 NVIDIA 驅動

# 安裝內核頭文件
sudo apt-get install linux-headers-$(uname -r)
# 添加 CUDA 倉庫并安裝驅動
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
sudo apt-get install nvidia-driver-535 -y
sudo reboot
# 驗證驅動
nvidia-smiroot@i-28e6iose:/home/ubuntu# nvidia-smi
Sun Mar  9 20:48:43 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 570.124.06             Driver Version: 570.124.06     CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 2080 Ti     Off |   00000000:00:0C.0 Off |                  N/A |
| 22%   29C    P8             20W /  250W |       4MiB /  11264MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------++-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

安裝 Docker Engine

# 卸載舊版本 Docker（如有）
sudo apt-get remove docker.io docker-doc containerd
# 添加 Docker 官方源
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io -y
# 驗證 Docker
docker inforoot@i-28e6iose:/home/ubuntu# docker info
Client: Docker Engine - CommunityVersion:    28.0.1Context:    defaultDebug Mode: falsePlugins:buildx: Docker Buildx (Docker Inc.)Version:  v0.21.1Path:     /usr/libexec/docker/cli-plugins/docker-buildxcompose: Docker Compose (Docker Inc.)Version:  v2.33.1Path:     /usr/libexec/docker/cli-plugins/docker-composeServer:Containers: 10Running: 10Paused: 0Stopped: 0Images: 10Server Version: 28.0.1

配置 NVIDIA Container Toolkit
在這里插入圖片描述

nvidia/cuda:12.2.0-base-ubuntu22.04 是一個基于 Ubuntu 22.04 操作系統的 NVIDIA CUDA 基礎鏡像，用于運行需要 GPU 加速的計算環境。CUDA（Compute Unified Device Architecture）是 NVIDIA 提供的一個并行計算平臺和編程模型，它使開發者可以使用 NVIDIA GPU 進行高性能計算。

這個鏡像提供了 CUDA 12.2.0 版本，適用于需要利用 NVIDIA GPU 進行深度學習、科學計算和其他計算密集型任務的場景。CUDA 12.2.0 版本帶來了許多改進和新特性，包括對新架構的支持、性能優化和新 API

https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

# 添加倉庫并安裝工具包
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/stable/deb/nvidia-container-toolkit.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install nvidia-container-toolkit -y
# 配置 Docker 運行時
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart dockerroot@i-28e6iose:/home/ubuntu# sudo nvidia-ctk runtime configure --runtime=docker
INFO[0000] Loading config from /etc/docker/daemon.json
INFO[0000] Wrote updated config to /etc/docker/daemon.json
INFO[0000] It is recommended that docker daemon be restarted.# 驗證 CUDA 容器
docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smiroot@i-28e6iose:/home/ubuntu# docker run --rm --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
Sun Mar  9 13:10:55 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 570.124.06             Driver Version: 570.124.06     CUDA Version: 12.8     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA GeForce RTX 2080 Ti     Off |   00000000:00:0C.0 Off |                  N/A |
| 22%   26C    P8             21W /  250W |       4MiB /  11264MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------++-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

三、部署 GPUStack 容器

運行 GPUStack 主節點
```
docker run -d \--gpus all \-p 890:80 \--ipc=host \--name gpustack \-v gpustack-data:/var/lib/gpustack \gpustack/gpustack:latest
```
- 參數說明
  - --gpus all：啟用所有 GPU 資源。
  - --ipc=host：共享主機 IPC 命名空間，提升性能。
  - -v gpustack-data：持久化存儲配置與模型數據。

獲取初始密碼

docker exec -it gpustack cat /var/lib/gpustack/initial_admin_passwordroot@i-28e6iose:/home/ubuntu# docker exec -it gpustack cat /var/lib/gpustack/initial_admin_password
rjl@Ainm3dtQ#賬戶信息：
admin/rjl@Ainm3dtQ
#修改密碼：P@88w0rd

訪問 http://<服務器IP>，使用用戶名 admin 和上述密碼登錄，首次需重置密碼。

在這里插入圖片描述

四、擴展 GPU 集群

添加 Worker 節點

在主節點獲取 Token：

docker exec -it gpustack cat /var/lib/gpustack/token

在 Worker 節點運行：

docker run -d \--gpus all \--network=host \--ipc=host \gpustack/gpustack \--server-url http://<主節點IP> \--token <獲取的Token>

五、功能使用示例

部署大模型
在 GPUStack 控制臺的 Models 頁面，支持從 Hugging Face 或本地導入模型。例如部署 Llama3.2 模型時，系統會自動分配 GPU 資源并生成 API 端點。
Playground 調測
在 Playground 中可測試多模態模型（如 Stable Diffusion）、文本嵌入模型（BERT）等，支持多模型對比與參數優化。