一、非商用声明

该文档提供的内容为参考实践，仅供用户参考使用，用户可参考实践文档构建自己的软件，并按需进行安全、可靠性加固，但不建议将相关Demo或镜像文件直接集成到商用产品中。

二、方案介绍

2.1 背景

GPUStack作为一款开源的可用于运行AI 模型的推理集群管理软件，具有广泛的推理硬件设备兼容性、广泛的模型支持，灵活的推理后端支持等特点，非常适合在中小企业作为模型服务管理平台的参考软件使用。为了满足中小企业的模型服务管理需求，本文基于GPUStack开源软件，在高可靠部署、模型开箱即优、小模型推理部署、集群平滑扩容、多实例负载均衡等方面给出模型服务能力增强的参考实践。

2.2 方案简介

本参考实践，在《基于GPUStack搭建昇腾模型服务管理平台参考实践》的基础上，提供企业级能力增强的参考设计，供中小企业作为构建模型服务能力的使用指导：

1、通过自定义模型库能力，预集成常用模型的推荐配置参数，部署模型服务实例时可自动使用推荐配置，支持主流模型GLM5/GLM5.1、MiniMax-M2.5、Kimi-K2.5、Qwen3.5/Qwen3.6系列、DeepSeek-V4系列等模型；

2、通过对接openFuyao、Ceph、openGauss等组件，提供高可靠能力，支持模型服务多实例负载均衡、服务实例故障自启动、跨A2/A3代次节点平滑扩容；

3、通过自定义推理后端方式，提供支持KVCache 分级缓存的vLLM Ascend推理后端；

4、通过自定义推理后端方式，提供支持小模型推理服务化部署的Triton Inference Server推理后端；

5、通过Harbor提供本地镜像仓，支持推理后端镜像在多个推理服务器节点间共享；通过Ceph文件系统支持模型文件在多个推理服务器节点间共享；

6、基于Helm Charts提供在昇腾设备上全栈自动化部署模型推理服务平台的能力。

2.3 软件版本配套

本参考实践基于以下版本配套验证：

2.4 部署方案介绍

根据部署的推理集群规模，提供以下两种推荐部署方案，其中AI推理服务器的组网请参考昇腾推理解决方案组网。

（1）当集群规模小于8台推理服务器时，建议采用混合部署方案。混合部署，是指GPUStack Server、GPUStack Worker、openGauss、Ceph等全部共用推理服务器节点，从而达到节省部署成本的目的。

图1 混合部署方案图参考

注：如果混合部署场景下集群节点小于3台，则openGauss部署单机版，否则建议部署一主两备openGauss以提升可靠性。

（2）当集群规模为≥8台推理服务器时，建议采用分离部署方案。分离部署，是指GPUStack Server、openGauss、Ceph单独采用通算服务器资源，从而达到管理区和AI推理区隔离的效果，提升方案安全性和可靠性。

图2 分离部署方案图参考

注：如分离部署场景下管理节点少于3台，则openGauss部署单机版，否则建议部署一主两备openGauss以提升可靠性。

三、部署指导

3.1 部署流程介绍

3.2 详细部署指导

3.2.1 安装OS和配置网络

步骤1 按照操作系统安装指南文档，安装OS，并做好网络等配置。参考链接。

步骤2 （可选）如需使用多机推理，需要按照昇腾集群推理组网要求，完成网络连接，并配置参数面网络，参考链接。

注意：建议根分区预留150G以上的空间，作为默认的容器镜像存储目录。

3.2.2 安装依赖和NPU驱动固件

使用KADT工具，完成依赖、驱动、固件的自动化部署。本步骤支持多节点批量操作，仅需在其中一台节点上操作即可。

注意：安装依赖需要在安装openFuyao之前进行，否则openFuyao集群可能出现故障。

步骤1 登录下载机，下载机需要能访问网络，执行如下命令获取工具：

git clone -b appliance_deployer https://gitcode.com/Ascend/ascend-deployer --depth=1

或者直接到gitcode仓库下载appliance_deployer分支的压缩包，传到机器上。

步骤2 进入工具目录，下载所需要的依赖、软件。

cd ascend-deployer/ascend-deployer
bash start_download.sh --os-list=OpenEuler_24.03LTS-SP1_aarch64 --download=NPU,DL

下载完成，软件资源会放到resources目录下。

步骤3 安装依赖和NPU驱动、固件。

将步骤2中的ascend-deployer工具（包含下载的resources文件夹），打包后拷贝到其中一台待部署的昇腾服务器上。

进入工具目录，编辑inventory_file文件，在[master]和[worker]下添加待安装的节点信息；如果是单机部署场景，可不修改该文件。工具详细参数参考链接。

cd ascend-deployer/ascend-deployer
vim inventory_file
# 如下为示例, 删除或者注释原来worker下的localhost，填入本集群的机器节点IP和密码
[master]
xx.xx.xx.1 ansible_ssh_user="root" ansible_ssh_pass="*****" step_len=3
[worker]
xx.xx.xx.1 ansible_ssh_user="root" ansible_ssh_pass="*****" step_len=3
xx.xx.xx.2 ansible_ssh_user="root" ansible_ssh_pass="*****" step_len=3
xx.xx.xx.3 ansible_ssh_user="root" ansible_ssh_pass="*****" step_len=3

执行命令进行安装：

bash install.sh --install=sys_pkg,npu

步骤4 当看到如下日志信息，表示安装成功。如果安装失败，请根据提示到对应的日志中查看报错原因，并根据日志指引修复问题，再重试步骤3。

run cmd: --install=sys_pkg,npu successfully

步骤5 执行reboot命令重启所有业务机器。

reboot

等待机器重启完成。

----结束

3.2.3 部署openFuyao和Ceph存储

参考《算力底座参考实践》文档第2章，完成openFuyao业务集群和Ceph存储的部署和对接。

3.2.4 安装Ascend-Docker-Runtime

步骤1 登录其中一台昇腾服务器节点，使用工具安装Ascend-Docker-Runtime。参考3.2.2，配置inventory_file文件。如果为单机场景，则将[worker]下的localhost那行剪切到[master]下。

vim inventory_file
# 如下为单机场景示例：删除原来[worker]下的localhost，并复制到[master]下，如下：
[master]
localhost ansible_connection='local' ansible_ssh_user='root'
[worker]
# localhost ansible_connection='local' ansible_ssh_user='root'

执行命令安装Ascend-Docker-Runtime

cd ascend-deployer/ascend_deployer
bash install.sh --install=ascend-docker-runtime --skip_check

步骤2（可选）安装Ascend-Docker-Runtime出现报错“err is can not find plugin: io.containerd.runtime.v1.linux”，则执行如下脚本保证Ascend-Docker-Runtime生效。

# 批量执行batch_configure_containerd.sh脚本
# 本脚本以openEuler release 24.03 (LTS-SP1)、containerd v2.1.1为例
cd ascend-deployer/kadt/gpustack/scripts/
bash batch_configure_containerd.sh

----结束

3.2.5 部署openGauss和GPUStack

步骤1 登录openFuyao中的其中一个节点，使用KADT工具下载 GPUStack 依赖镜像并push到本地仓。

（1）部署openGauss单机版场景：

# 进入kadt/gpustack工具目录
cd ascend-deployer/kadt/gpustack/scripts
# 下载GPUStack相关镜像并推送到本地镜像仓
bash pull_images.sh 

（2）部署openGauss一主两备场景：

# 进入kadt/gpustack工具目录
cd ascend-deployer/kadt/gpustack/scripts
# 需要提前准备好相关镜像文件opengauss-cm.tar放到当前执行目录下
bash pull_images.sh --opengauss-ha true

注：

1、opengauss-cm.tar镜像制作方法参考链接。

2、如你的机器无法访问网络，可以在有网络的机器完成镜像下载，将镜像导出为tar包后再拷贝到openFuyao集群节点上导入。

步骤 2  添加 higress helm repo 并下载其依赖。

# 执行成功会下载charts/gpustack-chart/charts/higress-core-x.x.x.tgz

cd ascend-deployer/kadt/gpustack 
helm repo add higress https://higress.io/helm-charts  --insecure-skip-tls-verify 
helm dependency build ./charts/gpustack-chart

注：如你的机器无法访问网络，可以在有网络的机器完成下载依赖步骤，再把代码仓及下载的包完整拷贝到你的机器上。

步骤 3 部署GPUStack前置资源，包括创建模型权重PVC、模型库配置文件PVC和数据迁移POD。拷贝本地模型库配置文件model-catalog.yaml 及模型权重文件到Ceph存储上。

# 默认模型权重PVC为1000G, 可以按需调整
helm install pre-gpustack ./charts/pre-gpustack-chart -n gpustack-system --create-namespace --set modelWeights.storageSize=1Ti

# 拷贝本地模型库配置文件model-catalog.yaml
kubectl cp ./conf/model-catalog-ascend.yaml gpustack-transfer:/model-catalog/model-catalog-ascend.yaml -n gpustack-system

# （可选）拷贝权重文件，也可以后续部署模型时再拷贝，具体路径请以实际为准
kubectl cp /data/weights/Eco-Tech/ gpustack-transfer:/mnt/models/Eco-Tech -n gpustack-system

步骤 4  （可选）如果是分离部署场景，需要按照部署规划给管理节点和非管理节点打好标签，并修改kadt/gpustack/charts/gpustack-chart/values.yaml中的nodeSelector参数。

# step1：先按照部署规划给节点打标签，如下为示例，请根据实际情况修改节点名称 
kubectl label node host01 gpustack-role=master 
kubectl label node host02 gpustack-role=worker 
kubectl label node host03 gpustack-role=worker 
... 

# 查看节点标签情况
kubectl get nodes --show-labels | grep gpustack-role

# step2: 设置节点选择策略，修改kadt/gpustack/charts/gpustack-chart/values.yaml
# 将global、server、opengauss-single的nodeSelector修改为：
  nodeSelector: 
    gpustack-role: master 
# 将worker的nodeSelector修改为： 
  nodeSelector: 
    gpustack-role: worker

步骤 5 部署GPUStack和openGauss，如对参数有自定义需求，请参照values.yaml文件中的注释修改参数值。

（1）场景一：GPUStack Server 对接使用单机 openGauss，参考部署命令如下：

helm install gpustack ./charts/gpustack-chart \
  --namespace gpustack-system \
  --set opengauss-single.password="Gpustack12#$"

（2）场景二：GPUStack Server 对接使用一主两备 openGauss，参考部署命令如下：

# 获取K8s Service ClusterIP POD 网段
kubectl get ippool default-ipv4-ippool -o yaml | grep -oP '^\s*cidr:\s*\K\S+'

# 如下为参考部署命令，其中openGauss节点需要提前规划，使用的主机名和网络信息请以实际为准
# 其中ogSubnet[1]为K8s Service ClusterIP POD 网段
helm install gpustack ./charts/gpustack-chart \
  --namespace gpustack-system \
  --set opengauss-single.enabled=false \
  --set opengauss-ha.enabled=true \
  --set opengauss-ha.gsPassword="Gpustack12#$" \
  --set opengauss-ha.master.hostname="host01" \
  --set opengauss-ha.master.nodeName="host01" \
  --set opengauss-ha.master.nodeIP="10.10.1.21" \
  --set opengauss-ha.slaves[0].hostname="host02" \
  --set opengauss-ha.slaves[0].nodeName="host02" \
  --set opengauss-ha.slaves[0].nodeIP="10.10.1.22" \
  --set opengauss-ha.slaves[1].hostname="host03" \
  --set opengauss-ha.slaves[1].nodeName="host03" \
  --set opengauss-ha.slaves[1].nodeIP="10.10.1.23" \
  --set opengauss-ha.ogSubnet[0]="10.10.1.0/24" \
  --set opengauss-ha.ogSubnet[1]="10.250.0.0/16"

查看 pod 是否都已启动成功：

kubectl get pods -n gpustack-system

步骤6 获取 GPUStack 页面访问端口和密码，访问GPUStack管理页面。

# 获取访问端口信息 
kubectl get svc -n gpustack-system |grep higress-gateway 
 
# 获取初始化密码信息 
kubectl exec gpustack-server-0 -n gpustack-system -- cat /var/lib/gpustack/initial_admin_password

找到 80 端口映射的端口，访问 管理节点 IP:该端口号 即可进入 GPUStack 页面，默认管理员账号admin，使用获取到的初始密码登录，建议首次登录后修改密码。

----结束

注意：Helm Charts中的values配置文件包含用户名和密码信息，若在生产环境中使用，建议采用加密或外部密钥管理方式保护敏感信息，避免泄露。

3.2.6 （可选）部署MemCache分级缓存服务

如果需要使用MemCache分级缓存，则参考如下步骤进行部署。

步骤 1 在下载机上，提前构建带有 MemCache的后端推理镜像memcache.tar，并上传到集群上任意节点，执行如下命令导入到openFuyao集群。

# 下载机上构建镜像
cd ascend-deployer/kadt/memcache/build_image
nerdctl build -t deploy.bocloud.k8s:40443/kubernetes/memcache:v1.1.2 -f Dockerfile-vllm-memcache .
nerdctl save -o memcache.tar deploy.bocloud.k8s:40443/kubernetes/memcache:v1.1.2

# 集群节点上导入镜像
ctr -n k8s.io image import --platform=linux/arm64 ./memcache.tar
ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/memcache:v1.1.2

步骤 2 添加自定义推理后端。进入推理后端管理页面，选择vLLM后端进行编辑，添加后端版本0.18.0-memcache，并配置对应的镜像名称deploy.bocloud.k8s:40443/kubernetes/memcache:v1.1.2，框架选择”CANN”，点击保存。

步骤 3 登录其中一台业务集群节点，将集群中的节点打好组标签，如下为示例，请根据实际情况修改节点名称：

# 存在Device参数面网络互联的机器，可共用一个metaservice，适用于双机背靠背参数面组网、交换机参数面组网。同个参数面网络下的节点打同个标签。 
# 不存在Device参数面网络互联的机器，需要每个节点单独部署一个metaservice。这些节点每个单独打一个标签。 
# 如下例子：假设host01和host02双机互联，host03、host04为单机无参数面网络 
kubectl label node host01 group=meta-a 
kubectl label node host02 group=meta-a 
kubectl label node host03 group=meta-b 
kubectl label node host04 group=meta-c 
...

组标签不同的节点对应不同的内存池，并由不同的 MemCache metaservice 进行管理。

步骤 3 进入 MemCache helm chart 目录，根据需要修改 values.yaml 文件中的参数，通过 helm chart 启动服务：

helm install memcache ./charts/memcache-chart -n memcache-ha --create-namespace

查看 pod 是否都已启动成功，当设置meta-service的replicas为2时，有1个处于Pending状态为正常现象：

kubectl get pods -n memcache

----结束

注意：目前支持DRAM二级缓存。

四、特性使用指导

4.1 昇腾本地模型库使用指导

4.1.1 部署方法

使用昇腾本地模型库，需要在部署GPUStack Server时即启用该功能。

步骤1 获取配置文件：链接。

步骤2 拉起GPUStack Server时指定配置文件：

（1）openFuyao方式部署：

参考3.2.5章节方式进行部署即带有该功能。

（2）Docker方式部署，参考命令如下：

# 参考命令，请以实际为准
docker run -d --name gpustack-server-2.2.0 \
--restart=unless-stopped \
-p 80:80 \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume /data/gpustack-server-data:/var/lib/gpustack \
quay.io/gpustack/gpustack:v2.2.0rc1 \
--model-catalog-file /data/model-catalog-ascend.yaml

步骤3 添加推理后端。

由于当前GPUStack2.2.0未提供vLLM Ascend 0.19.1rc1版本，而GLM5需要使用该版本方可正常推理，因此需要进入推理后端页面，选择vLLM后端进行编辑，添加后端版本0.19.1rc1，并配置对应的镜像名称，点击保存：

注：运行推理模型需要的vLLM版本及镜像参考链接附录。

----结束

4.1.2 本地模型部署样例

4.1.2.1 部署单机模型实例

以Qwen3.6-27B-W8A8在Atlas800I A2上两卡部署为例：

步骤 1 进入模型库页面，选择模型“Qwen3.6-27B-W8A8-A2-Single-Ascend-Optimized”：

步骤 2  进入部署模型页面，按需修改实例名称，点击保存即可一键拉起模型实例：

步骤 3 等待模型实例拉起成功，状态变为Running，即可试验场->对话页面使用该模型。

----结束

4.1.2.2 部署双机模型实例

以GLM5-W4A8在2台Atlas800I A2上按照TP8、DP2部署为例：

步骤 1 进入模型页面，选择模型“glm-5-w4a8-a2-double-ascend-optimized”:

步骤 2 进入部署模型页面，按需修改实例名称，点击保存即可一键拉起模型实例：

步骤 3 等待模型实例拉起成功，状态变为Running，即可试验场->对话页面使用该模型。

----结束

4.2 小模型推理服务化使用指导

传统小模型的推理服务化部署，推荐采用Triton Inference Server方案，方案详细内容具体可参考链接。该方案可以以自定义推理后端方式，在GPUStack统一进行小模型推理的部署。该功能的使用指导如下：

步骤1 在能访问网络的机器上构建小模型服务化推理后端镜像，并拷贝后导入到openFuyao集群中，构建镜像步骤参考链接。镜像导入openFuyao集群的命令参考：

ctr -n k8s.io image import --digests=true --platform=linux/arm64 /your_path/tritonserver-cann_aarch64.tar
ctr -n k8s.io images tag docker.io/library/tritonserver-cann:24.10 deploy.bocloud.k8s:40443/kubernetes/docker.io/library/tritonserver-cann:24.10
ctr -n k8s.io images push --platform linux/arm64 --skip-verify --local deploy.bocloud.k8s:40443/kubernetes/docker.io/library/tritonserver-cann:24.10

步骤2 进入GPUStack管理页面->推理后端，点击添加后端，使用YAML模式方式，填入自定义后端信息，保存。YAML内容参考链接。

注：image_name以实际为准。

步骤3 准备好小模型的model_repository文件夹，拷贝到Ceph文件系统上。参考命令如下：

kubectl cp /data/weights/resnet50/ gpustack-transfer:/mnt/models/resnet50/ -n gpustack-system

步骤4 进入GPUStack管理页面->模型文件，添加本地模型文件。

步骤5 使用本地模型文件进行部署，推理后端选择步骤2中添加的后端，并修改后端参数，将其参数值改为空闲端口。点击保存即可拉起小模型推理服务。

步骤6 等待模型实例启动成功，从部署页面查看模型实例，可以获取其IP和http端口，grpc端口以部署时手动指定的后端参数为准。用户可以使用IP和端口以http/grpc接口方式访问模型服务。

----结束

4.3 MemCache分级缓存使用指导

部署 GPUStack 及 MemCache 后可以在拉起模型时启用 MemCache 分级缓存特性，需要使用已安装好 MemCache 的推理后端，具体步骤如下：

步骤 1 拉起 MemCache 服务后，执行 kubectl get svc -n memcache 查看 MemCache 服务的 IP 和端口：

步骤 2 编辑 kadt/gpustack/conf/mmc-local.conf文件，编辑其中 ock.mmc.meta_service_url 及 ock.mmc.local_service.config_store_url 为 MemCache 服务对应的 CLUSTER-IP 和端口：

ock.mmc.meta_service_url = tcp://10.96.51.84:18081 
ock.mmc.local_service.config_store_url = tcp://10.96.51.84:18091

将该文件放到 model-weights-pvc 的 memcache 目录下。该 PVC 会挂载到 GPUStack Worker的 /mnt/models 路径，可在模型实例中访问。

kubectl cp ./conf/mmc-local.conf gpustack-transfer:/mnt/models/mmc-local.conf -n gpustack-system

步骤 3 进入 GPUStack 管理界面，点击模型进行部署，选择推理后端版本为0.18.0-memcache-custom，同时在高级配置中需要配置以下环境变量：

MMC_LOCAL_CONFIG_PATH=/mnt/models/mmc-local.conf
LD_LIBRARY_PATH=/usr/local/python3.11.14/lib/python3.11/site-packages/memfabric_hybrid/lib:/usr/local/python3.11.14/lib/python3.11/site-packages/memcache_hybrid/lib:/usr/local/python3.11.14/lib/python3.11/site-packages/memfabric_hybrid/lib:/usr/local/python3.11.14/lib/python3.11/site-packages/memcache_hybrid/lib:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/lib:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/examples:/usr/local/Ascend/nnal/atb/latest/atb/cxx_abi_1/tests/atbopstest:/usr/local/Ascend/ascend-toolkit/latest/tools/aml/lib64:/usr/local/Ascend/ascend-toolkit/latest/tools/aml/lib64/plugin:/usr/local/Ascend/ascend-toolkit/latest/lib64:/usr/local/Ascend/ascend-toolkit/latest/lib64/plugin/opskernel:/usr/local/Ascend/ascend-toolkit/latest/lib64/plugin/nnengine:/usr/local/Ascend/ascend-toolkit/latest/opp/built-in/op_impl/ai_core/tbe/op_tiling:/usr/local/Ascend/cann-8.5.1/tools/aml/lib64:/usr/local/Ascend/cann-8.5.1/tools/aml/lib64/plugin:/usr/local/Ascend/cann-8.5.1/lib64:/usr/local/Ascend/cann-8.5.1/lib64/plugin/opskernel:/usr/local/Ascend/cann-8.5.1/lib64/plugin/nnengine:/usr/local/Ascend/cann-8.5.1/opp/built-in/op_impl/ai_core/tbe/op_tiling:/usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64/common/:/usr/local/Ascend/driver/lib64/driver/:/usr/local/python3.11.14/lib:/usr/local/lib

同时在 vLLM 后端参数中启用 MemCache特性：

--kv-transfer-config '{"kv_connector": "AscendStoreConnector", "kv_role": "kv_both", "kv_connector_extra_config": {"backend": "memcache"}}'

如图所示：

保存，即可拉起开启了分级缓存特性的模型服务实例。

----结束

4.4 多实例负载均衡&集群节点平滑扩容

4.4.1 集群节点扩容指导

支持集群节点扩容，支持跨代际A2、A3节点平滑扩容，扩容步骤如下：

步骤 1 参考3.2.1和3.2.2完成OS、依赖、驱动固件等的安装。

步骤 2 参考《算力底座参考实践》第2.3章节，进行openFuyao集群和Ceph存储扩容。

步骤 3 参考3.2.4安装Ascend-Docker-Runtime。

步骤 4 （可选）如果为分离部署场景，执行如下命令为新加的节点打上标签。

# 如下为示例，请修改为你的节点名称 
kubectl label node host05 gpustack-role=worker 
...

步骤 5 等待集群自动扩容GPUStack Worker节点。

步骤 6 扩容后的节点，可以部署新的模型实例，并按需使用模型多副本、路由的方式实现对外统一的模型服务。

----结束

4.4.2 多实例负载均衡指导

多实例负载均衡，可以通过模型实例多副本或者使用模型路由功能来实现。

4.4.2.1 模型实例多副本

多副本模型实例，在调用时使用统一的模型服务API，会自动进行负载均衡。

在部署模型实例时可以指定副本数大于1，即开启模型多副本，如下图：

已经部署的模型，在部署页面编辑修改副本数，保存后实例副本数会按需调整，如下图：

4.4.2.2 路由

进入模型路由页面，添加路由，填写路由名称，并在路由目标中添加多个模型实例，按需配置目标流量权重，点击保存。

添加路由后，可以使用路由名称来访问多个模型实例：