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 集群的管理与大模型服务。

---

一、环境准备

1. 硬件与系统要求

   • 确保系统已安装 NVIDIA GPU，并验证驱动兼容性（支持 CUDA 11.0 及以上版本）。
   • 推荐使用 Ubuntu 22.04 LTS 或 CentOS 7+ 系统。

2. 验证 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

1. 安装 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                                                             |
   +-----------------------------------------------------------------------------------------+
   

2. 安装 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
   

3. 配置 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 容器

1. 运行 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：持久化存储配置与模型数据。

2. 获取初始密码

   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 集群

1. 添加 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>
     

---

五、功能使用示例

1. 部署大模型
   在 GPUStack 控制台的 Models 页面，支持从 Hugging Face 或本地导入模型。例如部署 Llama3.2 模型时，系统会自动分配 GPU 资源并生成 API 端点。

2. Playground 调测
   在 Playground 中可测试多模态模型（如 Stable Diffusion）、文本嵌入模型（BERT）等，支持多模型对比与参数优化。

---

六、常见问题

• GPU 未识别：检查 nvidia-smi 是否正常，并确认 Docker 运行时配置正确。
• 容器启动失败：确保已启用 --ipc=host 并挂载持久化卷。
• 网络问题：跨节点通信需开放防火墙的 80 端口及内部 RPC 端口（默认为 6789）。

---

七、参考资源

• GPUStack 官方 Docker 部署文档
• NVIDIA Container Toolkit 配置指南

通过以上步骤，您可快速搭建一个支持异构 GPU 资源调度的企业级大模型服务平台，实现从单机到集群的高效扩展。