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 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 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-smi root@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 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 -
配置 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 docker root@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-smi root@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_password root@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>
- 在主节点获取 Token：
五、功能使用示例
-
部署大模型
在 GPUStack 控制台的 Models 页面，支持从 Hugging Face 或本地导入模型。例如部署 Llama3.2 模型时，系统会自动分配 GPU 资源并生成 API 端点。 -
Playground 调测
在 Playground 中可测试多模态模型（如 Stable Diffusion）、文本嵌入模型（BERT）等，支持多模型对比与参数优化。
六、常见问题
- GPU 未识别：检查
nvidia-smi是否正常，并确认 Docker 运行时配置正确。 - 容器启动失败：确保已启用
--ipc=host并挂载持久化卷。 - 网络问题：跨节点通信需开放防火墙的 80 端口及内部 RPC 端口（默认为 6789）。
七、参考资源
- GPUStack 官方 Docker 部署文档
- NVIDIA Container Toolkit 配置指南
通过以上步骤，您可快速搭建一个支持异构 GPU 资源调度的企业级大模型服务平台，实现从单机到集群的高效扩展。
