Docker运行GPUStack的详细教程

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 nvidia

root@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 --version

root@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 thesourceforcopying conditions. There is NO
warranty; not evenforMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

二、安装 NVIDIA 驱动与 Docker

1.安装 NVIDIA 驱动

# 安装内核头文件
sudoapt-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
sudodpkg -i cuda-keyring_1.1-1_all.deb
sudoapt-get update
sudoapt-get install nvidia-driver-535 -y
sudoreboot
# 验证驱动
nvidia-smi


root@i-28e6iose:/home/ubuntu# nvidia-smi
Sun Mar 9 2043 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 |  000000000C.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（如有）
sudoapt-get remove docker.io docker-doc containerd
# 添加 Docker 官方源
curl -fsSL https://download.docker.com/linux/ubuntu/gpg |sudogpg --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"|sudotee/etc/apt/sources.list.d/docker.list > /dev/null
sudoapt-get update
sudoapt-get install docker-ce docker-ce-cli containerd.io -y
# 验证 Docker
docker info

root@i-28e6iose:/home/ubuntu# docker info
Client: Docker Engine - Community
Version:  28.0.1
Context:  default
Debug Mode:false
Plugins:
 buildx: Docker Buildx (Docker Inc.)
  Version: v0.21.1
  Path:   /usr/libexec/docker/cli-plugins/docker-buildx
 compose: Docker Compose (Docker Inc.)
  Version: v2.33.1
  Path:   /usr/libexec/docker/cli-plugins/docker-compose

Server:
Containers: 10
 Running: 10
 Paused: 0
 Stopped: 0
Images: 10
Server 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 版本带来了许多改进和新特性，包括对新架构的支持、性能优化和新 APIhttps://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

# 添加仓库并安装工具包
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey |sudogpg --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 |sudotee/etc/apt/sources.list.d/nvidia-container-toolkit.list
sudoapt-get update
sudoapt-get install nvidia-container-toolkit -y
# 配置 Docker 运行时
sudonvidia-ctk runtime configure --runtime=docker
sudosystemctl restart docker

root@i-28e6iose:/home/ubuntu#sudonvidia-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-smi

root@i-28e6iose:/home/ubuntu# docker run --rm--gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi
Sun Mar 9 1355 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 |  000000000C.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.获取初始密码

dockerexec-it gpustackcat/var/lib/gpustack/initial_admin_password

root@i-28e6iose:/home/ubuntu# dockerexec-it gpustackcat/var/lib/gpustack/initial_admin_password
rjl@Ainm3dtQ

#账户信息：
admin/rjl@Ainm3dtQ
#修改密码：P@88w0rd

访问http://<服务器IP>，使用用户名admin和上述密码登录，首次需重置密码。

在这里插入图片描述

四、扩展 GPU 集群

1.添加 Worker 节点

• 在主节点获取 Token：

dockerexec-it gpustackcat/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 资源调度的企业级大模型服务平台，实现从单机到集群的高效扩展。

链接：https://blog.csdn.net/shenhonglei1234/article/details/146139022