English | 简体中文 | 日本語

概述

GPUStack 是一款开源的 GPU 集群管理器，专为高效部署 AI 模型而设计。它能够配置并编排推理引擎——如 vLLM、SGLang、TensorRT-LLM 或您自定义的引擎——以优化跨 GPU 集群的性能。其核心功能包括：

• 多集群 GPU 管理。 可管理跨多个环境的 GPU 集群，包括本地服务器、Kubernetes 集群以及云服务提供商。
• 可插拔的推理引擎。 自动配置高性能推理引擎，如 vLLM、SGLang 和 TensorRT-LLM。您也可以根据需要添加自定义推理引擎。
• Day 0 模型支持。 GPUStack 的可插拔引擎架构使您能够在模型发布当天就将其部署上线。
• 性能优化配置。 提供针对低延迟或高吞吐量的预调模式。GPUStack 支持 LMCache 和 HiCache 等扩展 KV 缓存系统，以降低 TTFT；同时内置对 EAGLE3、MTP 和 N-grams 等推测解码方法的支持。
• 企业级运维功能。 支持自动故障恢复、负载均衡、监控、身份验证和访问控制。

架构

GPUStack 使开发团队、IT 组织和服务提供商能够大规模提供模型即服务（MaaS）。它支持 LLM、语音、图像和视频模型的行业标准 API。该平台内置用户身份验证和访问控制、GPU 性能与利用率的实时监控，以及详细的 Token 使用量和 API 请求速率计量。

下图展示了单个 GPUStack 服务器如何管理跨本地和云端的多个 GPU 集群。GPUStack 调度器会分配 GPU 以最大化资源利用率，并选择合适的推理引擎以实现最佳性能。管理员还可以通过集成的 Grafana 和 Prometheus 仪表板，全面了解系统健康状况和各项指标。

优化的推理性能

GPUStack 的自动化引擎选择和参数优化，开箱即用即可带来出色的推理性能。下图展示了相较于默认 vLLM 配置的吞吐量提升：

有关详细的基准测试方法和结果，请访问我们的 推理性能实验室。

支持的加速器

GPUStack 支持广泛的 AI 推理加速器：

• NVIDIA GPU
• AMD GPU
• Ascend NPU
• Hygon DCU
• MThreads GPU
• Iluvatar GPU
• MetaX GPU
• Cambricon MLU
• T-Head PPU

有关详细要求和设置说明，请参阅 安装要求 文档。

快速入门

前提条件

1. 至少配备一块 NVIDIA GPU 的节点。对于其他类型的 GPU，请在添加工作节点时查看 GPUStack UI 中的相关指南，或参考 安装文档 获取更多信息。
2. 确保工作节点上已安装 NVIDIA 驱动程序、Docker 和 NVIDIA Container Toolkit。
3. （可选）一台用于托管 GPUStack 服务器的 CPU 节点。GPUStack 服务器无需 GPU，可在纯 CPU 机器上运行。必须安装 Docker。也支持 Docker Desktop（适用于 Windows 和 macOS）。若无专用 CPU 节点，也可将 GPUStack 服务器安装在同一台 GPU 工作节点上。
4. GPUStack 工作节点仅支持 Linux 系统。若您使用 Windows，建议采用 WSL2，避免使用 Docker Desktop。macOS 不支持作为 GPUStack 工作节点。

安装 GPUStack

运行以下命令，使用 Docker 安装并启动 GPUStack 服务器：

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

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    --volume gpustack-data:/var/lib/gpustack \
    quay.io/gpustack/gpustack \
    --system-default-container-registry quay.io

检查 GPUStack 启动日志：

sudo docker logs -f gpustack

GPUStack 启动后，运行以下命令获取默认管理员密码：

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

打开浏览器，访问 http://your_host_ip 即可进入 GPUStack 管理界面。使用默认用户名 admin 和上述获取的密码登录。

设置 GPU 集群

1. 在 GPUStack 的 UI 界面中，导航到 Clusters 页面。

2. 点击 Add Cluster 按钮。

3. 选择 Docker 作为集群提供商。

4. 填写新集群的 Name 和 Description 字段，然后点击 Save 按钮。

5. 按照 UI 指南配置新的工作节点。您需要在工作节点上运行一个 Docker 命令，将其连接到 GPUStack 服务器。该命令大致如下：

   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
   

6. 在工作节点上执行该命令，以将其连接到 GPUStack 服务器。

7. 工作节点成功连接后，将显示在 GPUStack UI 的 Workers 页面上。

部署模型

1. 导航到 GPUStack UI 中的 Catalog 页面。

2. 从可用模型列表中选择 Qwen3 0.6B 模型。

3. 部署兼容性检查通过后，点击 Save 按钮以部署模型。

4. GPUStack 将开始下载模型文件并部署模型。当部署状态显示为 Running 时，模型已成功部署。

5. 点击导航菜单中的 Playground - Chat，确保在右上角的 Model 下拉菜单中选择了 qwen3-0.6b 模型。现在您可以在 UI Playground 中与该模型进行对话。

通过 API 使用模型

1. 将鼠标悬停在用户头像上，进入 API Keys 页面，然后点击 New API Key 按钮。

2. 填写 Name 并点击 Save 按钮。

3. 复制生成的 API 密钥，并将其保存在安全的地方。请注意，您只能在创建时查看一次。

4. 现在您可以使用该 API 密钥访问 GPUStack 提供的与 OpenAI 兼容的 API 端点。例如，使用 curl 如下：

# 将 `your_api_key` 和 `your_gpustack_server_url`
# 替换为您的实际 API 密钥和 GPUStack 服务器 URL。
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-0.6b",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Tell me a joke."
      }
    ],
    "stream": true
  }'

文档

完整的文档请参阅 官方文档网站。

构建

1. 安装 Python（版本 3.10 至 3.12）。

2. 运行 make build。

构建好的 wheel 包可在 dist 目录中找到。

贡献

如果您有兴趣为 GPUStack 做贡献，请阅读 贡献指南。

加入社区

如有任何问题或建议，欢迎加入我们的 社区 获取支持。

许可证

版权所有 © 2024–2025 GPUStack 作者

根据 Apache License, Version 2.0（“许可证”）授权；除非符合许可证规定，否则不得使用本文件。有关详细信息，请参阅 LICENSE 文件。

除非适用法律要求或双方书面同意，否则软件按“原样”分发，不提供任何形式的保证或条件。许可证详细规定了权限和限制。

GPUStack 快速上手指南

GPUStack 是一款开源的 GPU 集群管理器，专为高效部署 AI 模型而设计。它支持自动配置 vLLM、SGLang、TensorRT-LLM 等推理引擎，并兼容 NVIDIA、AMD、华为昇腾等多种加速卡。

环境准备

在开始之前，请确保满足以下前置条件：

1. 硬件与系统要求

• GPU 节点 (Worker)：
  • 至少拥有一张 NVIDIA GPU（也支持 AMD、昇腾等，详见官方文档）。
  • 操作系统：仅支持 Linux。
  • 注意：Windows 用户建议使用 WSL2；macOS 不支持作为 Worker 节点。
• 管理节点 (Server)：
  • 可以是独立的 CPU 机器，也可以与 GPU 节点共用同一台机器。
  • 支持 Linux、Windows (Docker Desktop) 和 macOS (Docker Desktop)。

2. 软件依赖

在所有节点上安装以下软件：

• Docker: 安装指南
• NVIDIA Driver: 确保显卡驱动已正确安装。
• NVIDIA Container Toolkit: 安装指南 (GPU 节点必需)

安装步骤

1. 启动 GPUStack 服务器 (Server)

使用 Docker 运行 GPUStack 服务器。国内用户若拉取 Docker Hub 较慢，推荐使用提供的 Quay.io 镜像源。

标准安装命令：

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

国内加速方案 (使用 Quay.io 镜像)：

sudo docker run -d --name gpustack \
    --restart unless-stopped \
    -p 80:80 \
    --volume gpustack-data:/var/lib/gpustack \
    quay.io/gpustack/gpustack \
    --system-default-container-registry quay.io

2. 获取管理员密码

服务启动后，执行以下命令查看初始管理员密码：

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

3. 登录管理界面

打开浏览器访问 http://<你的服务器 IP>，使用用户名 admin 和上一步获取的密码登录。

基本使用

第一步：添加 GPU 工作节点

1. 在 GPUStack UI 中，进入 Clusters 页面，点击 Add Cluster。
2. 选择 Docker 作为集群提供商，填写名称和描述后保存。
3. 按照界面指引，复制生成的 Docker 运行命令。该命令类似于：

   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://<你的服务器 IP> \
         --token <你的 worker token> \
         --advertise-address <你的节点内网 IP>
   

4. 在拥有 GPU 的 Linux 节点上执行上述命令。执行成功后，该节点将出现在 UI 的 Workers 页面中。

第二步：部署模型

1. 进入 UI 的 Catalog 页面。
2. 从列表中选择模型（例如 Qwen3 0.6B）。
3. 通过兼容性检查后，点击 Save 开始部署。
4. 等待状态变为 Running，即表示模型部署成功。

第三步：体验对话与 API 调用

方式 A：在线对话框 (Playground)

点击顶部导航栏的 Playground - Chat，在下拉菜单中选择已部署的模型（如 qwen3-0.6b），即可直接在网页中进行对话测试。

方式 B：通过 API 调用

1. 点击右上角头像进入 API Keys 页面，创建一个新的 Key 并妥善保存。
2. 使用 curl 或任何兼容 OpenAI 格式的客户端进行调用：

# 替换为你的实际 API Key 和服务器地址
export GPUSTACK_API_KEY=<your_api_key>
export GPUSTACK_URL=http://<your_gpustack_server_url>

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