Docker 運(yùn)行 GPUStack 的詳細(xì)教程

GPUStack

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

關(guān)鍵特性

?廣泛的硬件兼容性：支持管理 Apple Mac、Windows PC 和 Linux 服務(wù)器上不同品牌的 GPU。

?廣泛的模型支持：支持從大語(yǔ)言模型（LLMs）、多模態(tài)模型（VLMs）、擴(kuò)散模型、語(yǔ)音模型到嵌入和重新排序模型的廣泛模型。

?異構(gòu) GPU 支持與擴(kuò)展：能夠輕松添加異構(gòu) GPU 資源，并按需擴(kuò)展算力規(guī)模。

?分布式推理：支持單機(jī)多卡并行和多機(jī)多卡并行推理。

?多推理后端支持：支持llama-box（基于 llama.cpp 和 stable-diffusion.cpp）、vox-box和vLLM作為推理后端。

?輕量級(jí) Python 包：最小的依賴和操作開(kāi)銷。

?OpenAI 兼容 API：提供兼容 OpenAI 標(biāo)準(zhǔn)的 API 服務(wù)。

?用戶和 API 密鑰管理：簡(jiǎn)化用戶和 API 密鑰的管理流程。

?GPU 指標(biāo)監(jiān)控：實(shí)時(shí)監(jiān)控 GPU 性能和利用率。

?Token 使用和速率統(tǒng)計(jì)：有效跟蹤 token 使用情況，并管理速率限制。

支持的硬件平臺(tái)

?Apple Metal（M 系列芯片）

?NVIDIA CUDA（計(jì)算能力 6.0 及以上）

?AMD ROCm

?華為昇騰（CANN）

?摩爾線程（MUSA）

?海光 DTK

支持的模型類型

?大語(yǔ)言模型（LLMs）：如 Qwen、LLaMA、Mistral、Deepseek、Phi、Yi 等。

?多模態(tài)模型（VLMs）：如 Llama3.2-Vision、Pixtral、Qwen2-VL、LLaVA、InternVL2.5 等。

?擴(kuò)散模型：如 Stable Diffusion、FLUX 等。

?嵌入模型：如 BGE、BCE、Jina 等。

?重新排序模型：如 BGE、BCE、Jina 等。

?語(yǔ)音模型：如 Whisper（語(yǔ)音轉(zhuǎn)文本）、CosyVoice（文本轉(zhuǎn)語(yǔ)音）等。

使用場(chǎng)景

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

Docker 運(yùn)行 GPUStack 的詳細(xì)教程

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

以下是使用 Docker 運(yùn)行 GPUStack 的詳細(xì)教程，結(jié)合官方文檔與社區(qū)實(shí)踐整理而成。通過(guò)本指南，您可以在支持 NVIDIA GPU 的 Linux 環(huán)境中快速部署 GPUStack，并實(shí)現(xiàn)異構(gòu) GPU 集群的管理與大模型服務(wù)。

在這里插入圖片描述

在這里插入圖片描述

一、環(huán)境準(zhǔn)備

1.硬件與系統(tǒng)要求

? 確保系統(tǒng)已安裝 NVIDIA GPU，并驗(yàn)證驅(qū)動(dòng)兼容性（支持 CUDA 11.0 及以上版本）。

? 推薦使用 Ubuntu 22.04 LTS 或 CentOS 7+ 系統(tǒng)。

2.驗(yàn)證 GPU 與依賴項(xiàng)

# 檢查 NVIDIA GPU 是否識(shí)別
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)

# 確認(rèn) 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 驅(qū)動(dòng)與 Docker

1.安裝 NVIDIA 驅(qū)動(dòng)

# 安裝內(nèi)核頭文件
sudoapt-get install linux-headers-$(uname-r)
# 添加 CUDA 倉(cāng)庫(kù)并安裝驅(qū)動(dòng)
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
# 驗(yàn)證驅(qū)動(dòng)
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
# 驗(yàn)證 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是一個(gè)基于 Ubuntu 22.04 操作系統(tǒng)的 NVIDIA CUDA 基礎(chǔ)鏡像，用于運(yùn)行需要GPU 加速的計(jì)算環(huán)境。CUDA（Compute Unified Device Architecture）是 NVIDIA 提供的一個(gè)并行計(jì)算平臺(tái)和編程模型，它使開(kāi)發(fā)者可以使用 NVIDIA GPU 進(jìn)行高性能計(jì)算。這個(gè)鏡像提供了 CUDA 12.2.0 版本，適用于需要利用 NVIDIA GPU 進(jìn)行深度學(xué)習(xí)、科學(xué)計(jì)算和其他計(jì)算密集型任務(wù)的場(chǎng)景。CUDA 12.2.0 版本帶來(lái)了許多改進(jìn)和新特性，包括對(duì)新架構(gòu)的支持、性能優(yōu)化和新 APIhttps://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html

# 添加倉(cāng)庫(kù)并安裝工具包
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 運(yùn)行時(shí)
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.

# 驗(yàn)證 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.運(yùn)行 GPUStack 主節(jié)點(diǎn)

docker run -d 
 --gpus all 
 -p 890:80 
 --ipc=host 
 --name gpustack 
 -v gpustack-data:/var/lib/gpustack 
 gpustack/gpustack:latest

?參數(shù)說(shuō)明

?--gpus all：?jiǎn)⒂盟?GPU 資源。

?--ipc=host：共享主機(jī) IPC 命名空間，提升性能。

?-v gpustack-data：持久化存儲(chǔ)配置與模型數(shù)據(jù)。

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

在這里插入圖片描述

四、擴(kuò)展 GPU 集群

1.添加 Worker 節(jié)點(diǎn)

? 在主節(jié)點(diǎn)獲取 Token：

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

? 在 Worker 節(jié)點(diǎn)運(yùn)行：

docker run -d 
 --gpus all 
 --network=host 
 --ipc=host 
 gpustack/gpustack 
 --server-url http://<主節(jié)點(diǎn)IP> 
 --token <獲取的Token>

五、功能使用示例

1.部署大模型
在 GPUStack 控制臺(tái)的Models頁(yè)面，支持從 Hugging Face 或本地導(dǎo)入模型。例如部署 Llama3.2 模型時(shí)，系統(tǒng)會(huì)自動(dòng)分配 GPU 資源并生成 API 端點(diǎn)。

2.Playground 調(diào)測(cè)
在 Playground 中可測(cè)試多模態(tài)模型（如 Stable Diffusion）、文本嵌入模型（BERT）等，支持多模型對(duì)比與參數(shù)優(yōu)化。

六、常見(jiàn)問(wèn)題

?GPU 未識(shí)別：檢查nvidia-smi是否正常，并確認(rèn) Docker 運(yùn)行時(shí)配置正確。

?容器啟動(dòng)失敗：確保已啟用--ipc=host并掛載持久化卷。

?網(wǎng)絡(luò)問(wèn)題：跨節(jié)點(diǎn)通信需開(kāi)放防火墻的 80 端口及內(nèi)部 RPC 端口（默認(rèn)為 6789）。

七、參考資源

?GPUStack 官方 Docker 部署文檔

?NVIDIA Container Toolkit 配置指南

通過(guò)以上步驟，您可快速搭建一個(gè)支持異構(gòu) GPU 資源調(diào)度的企業(yè)級(jí)大模型服務(wù)平臺(tái)，實(shí)現(xiàn)從單機(jī)到集群的高效擴(kuò)展。

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