GPUStack 离线部署镜像准备与国内加速源

在 GPUStack 的实际部署中，经常会遇到一个问题：
离线环境如何准备完整的镜像？

GPUStack 的核心服务镜像实际上只有一个：gpustack/gpustack。
无论是 Server 还是 Worker 节点，运行的都是这个主镜像。

但在模型推理时，GPUStack 会根据所使用的 GPU 类型、计算框架以及推理后端，自动拉取对应的 运行时镜像（Runner）。在在线环境中，这些镜像可以按需自动下载；而在 离线或内网环境 中，如果提前不知道需要哪些镜像，就可能在部署过程中反复补充镜像，影响部署效率。

为了解决这个问题，我们在官方文档中提供了一个网页工具：

GPUStack 容器镜像选择器（Container Image Selector）

通过简单的选项选择，就可以 动态生成所需的 GPUStack 镜像列表，方便提前准备离线部署所需的镜像。

打开 GPUStack 容器镜像选择器

打开 GPUStack 官方文档：

https://docs.gpustack.ai

在顶部导航栏中，可以看到新增的 Container Image Selector 菜单。

桌面端界面：

移动端界面：

点击该菜单即可进入镜像选择工具，也可以直接访问：

https://docs.gpustack.ai/latest/image-selector/

进入 GPUStack 容器镜像选择器 页面。

切换中文界面

首次打开页面时默认是英文界面，可以在右上角语言菜单切换为 简体中文。

切换为中文后，还会显示 国内镜像源选项，方便在国内网络环境中准备镜像。

配置镜像选择条件

通过几个常见的部署参数，即可生成对应的镜像列表。

GPU 类型

默认选择 NVIDIA。

如果使用其他硬件平台，可以在这里进行选择。

计算框架版本

默认选择 最新版本。

昇腾计算框架版本区分芯片类型，同一框架版本在不同芯片上对应不同镜像，请根据实际芯片型号选择对应镜像。

例如：计算框架 CANN 8.5 根据芯片不同，分为 CANN 8.5 (910b)、CANN 8.5 (a3)，以及 CANN 8.5 (310p)。

如图所示：

驱动版本要求说明

不同计算框架版本对底层驱动版本有明确要求。部署 GPU 推理环境时，需要确保驱动版本满足对应框架版本的最低要求，否则可能出现容器无法启动、GPU 无法识别或推理异常等问题。

下面以 NVIDIA CUDA 和 昇腾 CANN 为例说明常见版本的驱动要求。

NVIDIA CUDA 与驱动版本要求

CUDA 版本	推荐驱动版本（Linux）
CUDA 12.9	≥ 575
CUDA 12.8	≥ 570
CUDA 12.6	≥ 560

说明：

CUDA 程序运行需要兼容的 NVIDIA 驱动版本。
新版本驱动通常向下兼容旧 CUDA 版本。

昇腾 CANN 与驱动版本要求

CANN 版本	推荐昇腾 NPU Driver
CANN 8.5	25.5.0
CANN 8.3	25.3.0
CANN 8.2	25.2.0

说明：

昇腾计算框架 CANN 需要匹配对应版本的 昇腾 NPU Driver。
Driver 与 CANN 通常需要保持官方推荐组合，否则可能出现算子或运行时异常。

推理后端

推理后端按 最新版本排序。如果不选择，则默认显示全部可用后端。

目前内置推理后端包括例如：

vLLM
SGLang
MindIE
VoxBox

如果未找到所需的内置推理后端或对应版本，可以尝试 切换到较低版本的计算框架。一般来说，较高版本的 GPU 驱动能够兼容运行较低版本的计算框架。

可选镜像

默认使用 GPUStack 内置镜像。

服务器架构

服务器架构会根据硬件给出默认值：

昇腾 GPU：默认 ARM64
其他 GPU：默认 AMD64

如果服务器架构不同，也可以手动修改。

镜像源

默认镜像源为 Docker Hub。

在中文界面下，还可以选择 国内镜像源，用于加速镜像准备。

查看生成的镜像列表

根据所选择的条件，页面会 动态生成对应的镜像列表，并且提供了拆分后 Server 节点和 Worker 节点所需的镜像列表。

这些镜像就是在运行 GPUStack 与模型推理过程中需要使用的镜像。

对于离线部署环境，可以提前将这些镜像准备好并导入到目标环境中。

镜像准备参考命令

页面底部提供了 离线部署相关的镜像准备命令和文档说明。

小结

GPUStack 在运行时会根据模型和推理后端自动拉取运行时镜像。在在线环境中，这一过程通常是自动完成的；而在离线或内网环境中，提前准备所需镜像就变得十分重要。

GPUStack 容器镜像选择器提供了一种简单的方法：通过常见的部署参数组合，生成对应的镜像列表，帮助用户更清晰地了解需要准备哪些镜像，从而减少离线部署过程中反复补充镜像的情况。

工具地址：