gpustack/gpustack · 上手攻略

  • 仓库：gpustack/gpustack
  • 链接：https://github.com/gpustack/gpustack
  • 分类：ai
  • 作者：Tom
  • 更新：2026-07-12

这是什么

GPUStack 是一个开源的 GPU 集群管理器，专门面向 AI 模型服务（Model Serving）和 GPU 资源调度场景。它的核心职责是：把多个 GPU 节点组织成一个集群，自动配置 vLLM、SGLang、TensorRT-LLM 等推理引擎，然后暴露一个统一的 OpenAI 兼容 API 供上层应用调用。

从定位上看，它介于底层 GPU 运维工具（Slurm、Kubernetes）与上层推理框架（vLLM、SGLang）之间——让你不用懂 K8s 也能管理多卡推理集群。同时支持按需启动 SSH 可访问的 GPU 实例，适合开发、评测、微调等多种场景。

解决什么问题

运行大模型推理服务时，常见痛点：

  1. 多卡管理复杂：手动在每台机器上启动 vLLM、配置端口、负载均衡——机器多了根本无法维护
  2. 推理引擎选型难：vLLM 和 SGLang 各有优劣，换引擎要重配所有参数
  3. GPU 利用率低：单机单卡跑不满，多机多卡不知道如何调度
  4. 上线流程长：从模型文件到 API 服务，要折腾 Docker、NVIDIA 驱动、推理引擎参数，门槛不低

GPUStack 把这一切抽象成一个 Web UI + 一组 YAML 配置，点点鼠标就能把模型跑起来并暴露 API。

快速安装

前置要求

GPU Worker 节点（每台 GPU 服务器）： - Linux 系统（不支持 Windows/macOS 作为 Worker） - NVIDIA GPU + 驱动 + Docker + NVIDIA Container Toolkit - 至少一块 GPU

Server 节点（管理平面，可选 CPU-only）： - Docker 已安装 - 最好与 Worker 网络互通

一键安装 GPUStack Server（Docker）

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    --volume gpustack-data:/var/lib/gpustack \
    gpustack/gpustack

网络不通 Docker Hub 时，可用 Quay 镜像： quay.io/gpustack/gpustack --system-default-container-registry quay.io

启动完成后获取初始密码

sudo docker exec gpustack cat /var/lib/gpustack/initial_admin_password

然后打开浏览器访问 http://your_host_ip，用 admin + 初始密码登录。

核心用法

1. 添加 GPU Worker 节点

在 GPUStack UI → Clusters → Add Cluster → Docker，按提示在每台 GPU 服务器上执行类似如下命令：

sudo docker run -d --name gpustack-worker \
    --restart=unless-stopped \
    --privileged \
    --network=host \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume gpustack-data:/var/lib/gpustack \
    --runtime nvidia \
    gpustack/gpustack \
    --server-url http://your_gpustack_server_url \
    --token your_worker_token \
    --advertise-address 192.168.1.2

节点连上后会在 UI 的 Workers 页面显示。

2. 从模型目录部署模型

  1. UI → Catalog 页面
  2. 选择目标模型（如 Qwen3.5-0.8B，GPUStack 会自动选择合适的推理引擎）
  3. 点击 Save，GPUStack 自动下载模型文件并启动服务
  4. 状态变为 Running 后即可使用

3. 调用 API

# 创建 API Key: UI → Access Control → API Keys → New API Key
export GPUSTACK_API_KEY=your_api_key

curl http://your_gpustack_server_url/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GPUSTACK_API_KEY" \
  -d '{
    "model": "qwen3.5-0.8b",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Tell me a joke."}
    ],
    "stream": true
  }'

4. 配置推理引擎与性能参数

GPUStack 支持对 vLLM、SGLang、TensorRT-LLM 进行参数调优：

  • 低延迟模式 vs 高吞吐模式：预调优配置，UI 直接选
  • KV Cache 优化：内置 LMCache、HiCache 支持，减少 TTFT（Time To First Token）
  • 推测解码：内置 EAGLE3、MTP、N-grams 推测解码方法

5. 多集群跨环境管理

GPUStack 支持同时管理多个集群（跨云、跨本地、跨 Kubernetes），通过统一的 Scheduler 分配请求到最优节点。

典型适用场景

场景 推荐用法
小团队快速搭建多卡推理服务 Docker 一键部署，UI 管理
需要同时跑 vLLM + SGLang 引擎热插拔，无需重建
国产 GPU（昇腾、海光等） 支持多种国产加速卡
需要 SSH 访问 GPU 实例的开发场景 GPU Instances 按需创建
企业 MLaaS 平台底层 认证、访问控制、用量计量内置
评测 LLM 性能 预置 Performance Lab 对比基准

坑与注意

  1. Worker 节点必须是 Linux：Windows/macOS 无法作为 Worker，使用 Windows 桌面的用户需装 WSL2（但官方不推荐 Docker Desktop）。
  2. GPU 驱动和 Container Toolkit 必须正确配置：NVIDIA 驱动版本与 Container Toolkit 兼容性是常见报错来源，建议严格按照 官方文档 安装。
  3. 多节点部署需要网络互通：Server 与 Worker 之间需要 2375/2376 端口通信，生产环境建议放在同一私有网络。
  4. 首次下载模型耗时长：Qwen3.5-0.8B 等小模型测试够用，70B 大模型建议提前准备好模型文件或给足下载时间。
  5. 自定义推理引擎需要手动配置：虽然支持插件化添加推理引擎，但 UI 对自定义引擎的引导目前不如 vLLM/SGLang 丰富。
  6. 计量功能需要 API Key：用量计量和 API Key 认证相关功能需要创建 Key，不是完全无认证的。
  7. 国产 GPU 支持细节需实测：官方列出支持 AMD、昇腾等，但实际踩坑可能较多，企业使用前建议用小模型实测。

与同类对比

特性 GPUStack vLLM (直接部署) SGLang Ray Serve Kubernetes + vLLM
定位 集群管理 + 推理引擎编排 单机/多机推理 推理框架 分布式计算编排 通用容器编排
多引擎支持 ✅ vLLM/SGLang/TRT-LLM 热插拔 ❌ ❌ ❌ ❌
UI 管理 ✅ 完整 Web UI ❌ ❌ ❌ 需额外工具
多集群管理 ✅ ❌ ❌ ❌ K8s 多集群方案
国产 GPU ✅ 有限 有限 ❌ 视 K8s 配置
学习成本 低（开箱即用） 中 中 高 高
生产级监控 内置 Grafana/Prometheus 需自己搭 需自己搭 Ray dashboard K8s 生态

一句话：GPUStack 把「多 GPU 推理集群」这件事从 DevOps 级别降到了 SaaS 级别——点点鼠标就能管理多机多卡、切换推理引擎、拿到计量数据；不需要学 Kubernetes，也不需要写 YAML 拼凑 Ray Cluster。

一句话推荐结论

需要管理多卡推理集群但不想学 K8s 的团队，GPUStack 是目前最省力的开源选择——一行 Docker 命令起管理平面，UI 上点几下就能把模型跑起来、暴露 OpenAI 兼容 API，尤其适合有国产 GPU 需求或需要同时管理多个推理引擎的场景。