GPUStack使用指南

一、平台介绍

GPUStack 是一款开源的异构 GPU 集群 + 私有大模型推理管理平台。

• 核心定位：统一纳管 NVIDIA/AMD/Apple Silicon/昇腾/摩尔线程等异构显卡，支持一键部署 LLM/多模态/文生图/语音模型，提供 OpenAI 兼容 API，是本地私有化 AI 推理的理想底座。
• 部署方式：可替代单独部署 vLLM、llama.cpp、SD 服务等，支持 Linux/macOS/Windows(WSL2) 单机及多机集群。
• 基础功能：内置调度、监控、权限管理、负载均衡及故障自愈机制。
• 开源属性：100% 开源免费，支持私有化部署。
• 资源链接：
• 官网：https://gpustack.ai
• 开源仓库：https://github.com/gpustack/gpustack

二、主要功能

1. 异构算力统一纳管

• 支持多品牌显卡及多服务器合并为单集群。
• 具备自动分配显存/算力能力，支持分布式推理。

2. 全品类模型一键部署

• 模型类型：涵盖 LLM/VLM/Embedding/Rerank/文生图/STT/TTS。
• 下载便捷：直连 Hugging Face/ModelScope 自动下载，内置 GGUF/FP16 量化模板。

3. 多推理引擎兼容

• 支持 vLLM、llama-box(llama.cpp)、MindIE、SD.cpp 共存与切换。
• 用户可根据需求调节吞吐率或低延迟模式。

4. OpenAI 标准 API

• 兼容 Chat Completions、图像生成接口。
• 可无缝对接 Dify、LangChain、Agnes AI 或本地客户端。

5. 运维管控能力

• 提供 GPU 实时监控与用量统计。
• 管理 API 密钥、用户权限、Token 限流及请求配额。
• 支持高可用故障转移功能。

6. 内置模型市场 Catalog

• 预调好主流开源模型参数，无需手动填写显存或上下文配置，开箱即用。

三、适用人群

✅ 适合使用

1. 个人开发者/AI 爱好者：本地单机显卡跑私有大模型。
2. 算法团队：构建私有化 RAG、Agent、本地知识库底座。
3. 中小企业：自建离线 AI 服务，有效规避公有 API 数据泄露风险。
4. 算力运维人员：管理多服务器异构 GPU 统一集群。
5. 国产化需求方：实现昇腾/摩尔线程国产 NPU 的统一调度。

❌ 不适合使用

1. 纯小白用户：缺乏 Linux 或 Docker 基础，部署有一定门槛。
2. 无硬件资源用户：无本地 GPU 或云显卡资源。
3. C 端交互需求者：追求开箱即用的网页对话工具（平台侧重推理底层，无完善的 C 端交互界面）。

四、免费 & 付费定价

1. 开源核心：永久完全免费

• 适用范围：所有基础集群、模型部署、API、监控功能无限制。
• 限制说明：无节点/显卡数量锁死，本地私有化部署无按量扣费。

2. 商业付费：企业增值服务

• 产品形态：官方企业版，针对企业场景提供专属服务。
• 服务包含：
• 专属技术支持、私有化定制。
• SLA 保障、国产芯片深度适配。
• 企业权限审计、离线交付包。
• 获取方式：
• 定价页面：https://gpustack.ai/pricing
• 模式：按节点/服务器年度订阅，支持上门部署、7×24 工单。
• 定制：需联系销售获取定制报价。

3. 特别说明

• 目前无云端 SaaS 版，仅支持本地私有化部署。
• 无网页在线试用平台，必须自备显卡硬件。

五、快速使用步骤

方式 1：Docker 一键部署（推荐）

1. 环境准备：安装 Docker + NVIDIA Container Toolkit 显卡驱动。
2. 执行安装：运行官方安装脚本 curl -sfL https://get.gpustack.ai | sh。
3. 访问控制台：浏览器访问 http://本机 IP:80，默认账号 admin / 密码 GPUStack@123。
4. 构建集群：新建集群，添加本地 Worker 节点（系统自动生成接入命令供其他服务器使用）。
5. 部署模型：点击 Deploy Model → 选择 HF/ModelScope → 选量化规格 → 启动。
6. 获取 API：复制 API 地址 + 密钥，接入任意 OpenAI 兼容客户端。

方式 2：Windows 部署

• 前提条件：必须使用 WSL2 + Docker Engine。
• 注意：不支持原生 Docker Desktop，否则会导致显卡直通异常。
• 驱动要求：主机安装 NVIDIA 驱动，WSL 内部无需安装 CUDA Toolkit。

调用 JSON 示例（兼容 OpenAI）

接口地址：http://127.0.0.1:80/v1

json

{
  "model": "qwen3-7b-instruct",
  "messages": [
    {
      "role": "user",
      "content": "介绍 GPUStack"
    }
  ],
  "temperature": 0.7
}
{
  "model": "qwen3-7b-instruct",
  "messages": [
    {
      "role": "user",
      "content": "介绍 GPUStack"
    }
  ],
  "temperature": 0.7
}

六、避坑重点

1. 显存估算坑 vLLM 默认占用 90% 显存，多模型易冲突。

• 计算公式：模型权重 GB × 1.2 + 2GB。
• 后果：显存不足会持续 Pending 无法启动。

1. 国内模型下载慢

• 解决方法：部署前配置 HF 镜像环境变量 HF_ENDPOINT=https://hf-mirror.com。
• 否则：下载超时失败。

1. Windows 原生不兼容

• 严禁：不要直接 Windows 安装。
• 必须：使用 WSL2，Docker Desktop 会导致显卡直通异常。

1. 多节点网络坑

• 跨服务器：需开放 80 端口，内部通信端口需放行。
• 防火墙：局域网访问 WSL 需开启 Mirrored 网络模式。

1. 密钥安全

• 风险：API Key 仅控制台可见一次，泄露会被滥用占用显卡资源。
• 建议：按团队分配独立 Token 配额。

1. 版本升级风险

• 架构：大版本（如 v1→v2）可能涉及架构重构。
• 操作：升级前导出模型配置备份，生产环境不建议自动更新。

1. 国产芯片适配

• 建议：昇腾/摩尔线程优先使用对应专用驱动。
• 注意：通用 N 卡引擎在这些芯片上性能下降明显。

1. 无在线云端

• 现状：无法网页在线试用，必须自备显卡硬件，无云算力租赁服务。

1. 免费无售后

• 开源版：无官方技术支持，报错只能查 GitHub Issues。
• 建议：企业稳定场景建议购买商业服务以获取工单支持。