本篇将介绍如何基于GPUStack在海光环境中部署模型，具体教程如下：

环境准备

开始部署前，请确保部署环境满足以下要求：

软硬件配置	规格要求	说明
操作系统	Linux 系统	要求部署用户具备 root 权限，或能够使用 sudo 执行命令。
显卡	海光 DCU	K100_AI
磁盘空间	100G及以上	至少 100GB 的可用空间，用于存放容器、模型文件等
CPU	AMD64 架构	无
支持的推理后端	vLLM、Custom	无
软件依赖	DCU 驱动	rock-6.3 版本及以上，可访问海光开发者社区获取并安装驱动
	Docker	安装教程请参考：安装DOCKER

环境配置

环境依赖

• 安装海光 DCU 驱动。
• 安装海光 DTK 工具包。

验证

通过以下命令进行验证：

sudo hy-smi

启动GPUStack

完成环境配置后，即可启动 GPUStack 服务。建议您使用一个配置相对完整的命令来启动容器，以便于后续管理。您可以参考如下 docker run 命令示例，其中包含了数据持久化、模型缓存、版本锁定和初始密码设置：

sudo docker run -d --name gpustack \
      --restart=unless-stopped \
      --network=host \
      --ipc=host \
      -v /path/to/gpustack-data:/var/lib/gpustack \
      -v /path/to/model-cache:/opt/model-cache \
      gpustack/gpustack:v2.0.1 \
      --cache-dir /opt/model-cache \
      --bootstrap-password "YourSecurePassword"

您需要根据实际情况配置参数，参数说明如下：

• -v /path/to/gpustack-data: /var/lib/gpustack: 将主机的 /path/to/gpustack-data 目录挂载到容器内，用于持久化存储 GPUStack 的核心数据（数据库、配置等）。
• -v /path/to/model-cache: /opt/model-cache: 将主机的 /path/to/model-cache 目录挂载到容器内的 /opt/model-cache。
• --cache-dir /opt/model-cache: 将容器内的 /opt/model-cache 目录指定为模型缓存目录。在线下载的模型会默认存放在这里。如果不使用此参数，默认缓存目录为 /var/lib/gpustack/cache。
• --bootstrap-password "YourSecurePassword"： 预设初始管理员密码，免去首次登录时查找随机密码的步骤。

配置完成后，可以通过http://<IP>:<port>访问GPUStack页面，进行模型部署。

• 内置账户：admin
• 密码： --bootstrap-password 节点中设置的密码。
• 默认端口：80

添加集群及配置节点

GPUStack 启动后，默认不包含任何计算节点，您需要先添加节点才能使用平台功能。添加集群及配置节点流程如下：

1.创建集群

在左侧导航栏中点击集群 -> 添加集群。选择合适的集群类型，例如 Docker 集群。点击下一步。

2. 基本配置

填写集群基本信息，包括名称、描述、服务器地址等，其中名称为必填项。点击保存。

3. 添加节点

接着根据节点的实际环境，按界面步骤提示填写并匹配相应的配置信息，其中GPU厂商选择海光。若想为已创建好的集群添加节点，也可在集群列表的“操作”列中点击更多->添加节点。

4. 启动节点

节点信息填写完成后，平台会生成对应的节点启动指令。请在目标节点上运行该指令，即可将其成功接入集群并开始使用。

模型在线部署

GPUStack 提供了多个在线部署大模型的入口，下面以从“模型库”在线部署大模型为例，展示模型在线部署的流程：

1. 在左侧导航栏中点击模型库，进入模型库功能模块；
2. 在模型列表中通过浏览/检索找到目标模型（如 Qwen3），然后点击卡片；
3. 在弹出抽屉页面中，可自定义部署模型的名称、副本数等，通常保持默认即可；
4. 填写完成后，点击“保存” 按钮，GPUStack 将自动下载并部署模型；

   图：模型库中选择模型并填写部署参数
5. 稍后前往“部署” 页面，观察到模型状态变为 Running，即表示部署成功。

图：查看模型部署状态

模型离线部署

1. 准备容器镜像

在离线环境中，您需要先将必需的 Docker 镜像导入到内部可访问的容器仓库中。

2. 复制镜像

GPUStack 为不同的推理后端提供了多种容器镜像，这些镜像可在 Docker Hub 上获取。使用以下命令将所需容器镜像从外网机器传输到您的内网容器仓库：

sudo docker run --rm -it --entrypoint "" gpustack/gpustack \
    gpustack copy-images \
    --destination <your_internal_registry> \
    --destination-username <your_username> \
    --destination-password <your_password>

若从 Docker Hub 拉取镜像缓慢或受限，可使用官方提供的 quay.io 镜像源进行加速：

sudo docker run --rm -it --entrypoint "" gpustack/gpustack \
    gpustack copy-images \
    --source quay.io \
    --destination <your_internal_registry> \
    --destination-username <your_username> \
    --destination-password <your_password>

3. 查询镜像列表

若无法直接查询内网仓库，可先拉取 gpustack/gpustack 工具镜像，并使用其列出所有需要的镜像：

sudo docker run --rm -it --entrypoint "" gpustack/gpustack \
    gpustack list-images

该列表会显示所有支持的加速器、推理后端、版本和架构组合。

4. 安装部署

在内网仓库中完成镜像准备后，即可在离线环境中执行以下安装命令。GPUStack 主服务默认监听 80 端口，监控指标暴露于 10161 端口。

 sudo docker run -d --name gpustack \
     --restart unless-stopped \
     -p 80:80 \
     -p 10161:10161 \

     -v /path/to/model-cache:/opt/model-cache \
     --volume gpustack-data:/var/lib/gpustack \
     <your_internal_registry>/gpustack/gpustack \
     --system-default-container-registry <your_internal_registry>\

     --bootstrap-password "YourSecurePassword"

5. 从安全镜像仓库拉取推理后端镜像

如果您的内网容器仓库需要进行身份验证，则必须在启动命令中配置相应的环境变量，以便 GPUStack 能够成功拉取推理后端镜像：

 sudo docker run -d --name gpustack \
     ...
     --env GPUSTACK_RUNTIME_DEPLOY_DEFAULT_REGISTRY_USERNAME=<your_internal_registry_username> \
     --env GPUSTACK_RUNTIME_DEPLOY_DEFAULT_REGISTRY_PASSWORD=<your_internal_registry_password> \
     <your_internal_registry>/gpustack/gpustack \
     --system-default-container-registry <your_internal_registry>

6. 登陆GPUStack，依次执行以下步骤完成模型部署：

（1）配置完成后，可以通过http://<IP>:<port>访问GPUStack页面，进行模型部署；

1. 内置账户：admin
2. 密码： --bootstrap-password 节点中设置的密码
3. 默认端口：80

（2）在左侧导航栏点击模型文件，进入模型文件管理模块；

（3）依次点击添加模型文件->本地路径，在弹窗中填写模型在容器内的绝对路径。根据上一步的挂载，此处应填写 /opt/model-cache/对应模型目录；

（4）配置其他参数，完成后点击保存即可。

7. 稍后前往“部署” 页面，观察到模型状态变为 Running，即表示部署成功。

图：查看模型部署状态