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）等，支持多模型对比与参数优化。