GPUStack v2.1.2 安装教程

关注🌟⌈GPUStack⌋ 💻一起学习 AI、GPU 管理与大模型相关技术实践。

GPUStack 是一个开源 GPU 集群管理与 AI 模型服务平台，旨在高效部署 AI 模型。它可以配置并编排多种推理引擎——如 vLLM、SGLang、TensorRT-LLM，甚至自定义引擎——以在 GPU 集群上实现最佳性能。核心功能包括多异构 GPU 集群池化调度、可插拔推理引擎架构、Day 0 模型支持、性能优化配置（低延迟/高吞吐）、以及企业级运维能力，如故障恢复、负载均衡、监控与权限管理。

GPUStack 可以帮助我们高效地管理 vLLM、SGLang 等推理引擎，并推动模型从部署走向企业生产落地运营。本文演示 GPUStack 控制面的安装，并将节点纳入管理。

准备容器环境

GPUStack 以容器方式运行，因此需要提前准备好容器运行环境（如 Docker、Podman 或 Kubernetes）。本文以 Docker 为例进行说明。

在各节点上安装 Docker，确保服务已正常启动：

docker info

启动 GPUStack Server

GPUStack Server 无需依赖 GPU，可运行在普通 CPU 节点，也可直接部署在 GPU 节点上，同时支持 Server 与 Worker 单节点部署。本文以单机双卡 NVIDIA RTX 4090 48GB 为实验环境，在同一节点上部署 GPUStack Server 与 Worker。

启动 GPUStack Server 容器：

sudo docker run -d --name gpustack \  --restart unless-stopped \  -p 80:80 \  --volume gpustack-data:/var/lib/gpustack \  swr.cn-south-1.myhuaweicloud.com/gpustack/gpustack:v2.1.2 \  --bootstrap-password GPUStack@123

参数说明：

• -p 80:80：docker run 的参数，用于对外暴露 Web 控制台端口，如需修改为其他端口（例如 8080），可调整为 -p 8080:80。
• --volume：docker run 的参数，持久化平台数据（包括模型服务、计量数据、API Key 等）
• --bootstrap-password：初始化 admin 用户密码

容器启动后，可以通过日志确认服务是否正常运行：

docker logs -f gpustack

访问控制台并初始化

打开浏览器访问：http://<Server 主机 IP>:80

使用默认账号登录：

• 用户名：admin
• 密码：GPUStack@123

登录后，首先创建一个 Docker 类型的集群，用于统一管理后续接入的节点。

添加 NVIDIA GPU 节点

集群创建完成后，可接入 Worker 节点，但需先完成基础环境检查。

（1）驱动版本检查

在目标节点上执行以下命令：

nvidia-smi

该命令会显示当前安装的 NVIDIA 驱动版本、支持 CUDA 最高版本，及 GPU 显存、功率等详细信息，如下图所示：

（2）Nvidia Container Toolkit 检查

执行以下命令检查 Docker 是否正确配置了 Nvidia Container Toolkit：

sudo docker info 2>/dev/null | grep -q "Runtime.*nvidia" && echo "Nvidia Container Toolkit OK" || (echo "Nvidia Container Toolkit not configured"; exit 1)

• 该命令会从 docker info 输出中查找是否存在 nvidia 运行时配置。
• 如果输出 "Nvidia Container Toolkit OK"，说明 Docker 已正确配置，可在容器中访问 GPU。
• 如果输出 "Nvidia Container Toolkit not configured"，则说明未正确配置，需要安装并启用 Nvidia Container Toolkit，否则推理容器无法使用 GPU 资源。

（3）接入 Worker 节点

在 GPUStack 控制台中，选择添加节点（Worker），按照步骤提示填写信息，并复制系统生成的接入命令，在目标节点执行。

图中 gpustack/gpustack:v2.1.2 可替换为国内镜像 swr.cn-south-1.myhuaweicloud.com/gpustack/gpustack:v2.1.2

该命令本质是启动一个 Worker 容器，并自动注册到 Server。

（4）验证 Worker 状态

节点接入后，可以在节点上查看容器日志：

docker logs -f gpustack-worker

同时，在 GPUStack 控制台中也可以看到节点状态是否为 Ready。

至此，GPUStack 的控制面已成功部署，NVIDIA GPU 节点也顺利接入集群，并能够正常采集设备名称、索引、厂商信息、温度、利用率及显存使用等指标。接下来即可在该环境中部署具体的推理服务。

GPU 资源监控数据

部署与测试模型

进入 GPUStack 控制台（Web UI），在左侧边栏打开 模型库。这里以 Qwen3-0.6B 为例进行演示：

注意：图中显示需要 40GB 以上显存，是因为 vLLM 的 --gpu-memory-utilization 参数默认值为 0.9，即默认占用所使用 GPU 90% 的显存。可根据实际需求自行调整。

点击保存后，页面会自动跳转至左侧边栏的部署页面。等待模型状态变为 Running 后，即可前往 对话试验场 进行测试：

参考文档：

• 官方文档：https://docs.gpustack.ai/
• 镜像选择器：https://docs.gpustack.ai/latest/image-selector/

加入 GPUStack 社区

GPUStack 社区聚焦 AI 基础设施与大模型实践。

社区中持续分享真实环境下的部署经验、问题排查案例，以及推理引擎、算力管理和系统架构相关讨论。

欢迎扫码加入 GPUStack 社区，与更多关注 AI Infra 与大模型推理实践的伙伴一起交流、学习与分享。

若群聊已满或二维码失效，请访问以下页面查看最新群二维码：https://github.com/gpustack/gpustack/blob/main/docs/assets/wechat-group-qrcode.jpg

About GPUStack GPUStack 是由 GPUStack.ai 所推出的开源项目。GPUStack.ai 成立于2022年，是 AI Infra 解决方案提供商，目前已完成5300万元种子轮融资。创始团队成员均来自业界应用广泛的 Kubernetes 管理平台 Rancher 的核心团队。其中，联合创始人及 CTO 梁胜博士是前 SUSE 全球工程及创新总裁，加入 SUSE 之前，梁胜博士于2014年9月创立全球著名的容器管理平台公司 Rancher Labs 并担任 CEO。我们的愿景是赋能企业可以在任意环境使用人工智能以实现业务的卓越运营。GPUStack 是实现这一目标的重要一步。使用 GPUStack 迅速搭建你的专属 MaaS 平台！开始在本地快速构建 GPU 集群，运行和使用各种 AI 模型，赋能您的 AI 应用。【开源地址】：github.com/gpustack/gpustack