基于华为昇腾环境部署AgentX

本篇将介绍如何基于GPUStack在华为的昇腾环境中部署模型，具体教程如下：

环境准备

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

软硬件配置 规格要求 说明
操作系统 Linux 系统 要求部署用户具备 root 权限，或能够使用 sudo 执行命令。
显卡 华为昇腾 NPU Ascend 910B 系列或 310P3
磁盘空间 100G及以上 用于存放容器、模型文件等
CPU ARM64 架构 HUAWEI Kunpeng 920 5250
软件依赖 Docker 24.0.9及以上版本
Docker Compose 2.27及以上版本
NPU驱动与固件 查询与操作系统兼容的NPU驱动与固件资源并下载
Asend Docker Runtime  

软件依赖

安装Docker与Docker Compose

安装教程请参考：安装DOCKER

安装NPU驱动与固件

  1. 前往兼容性查询助手，选择与操作系统兼容的NPU驱动与固件资源，点击资源下载；
    图：查询操作系统兼容的资源
  2. 选择对应的服务器产品型号，点击查找配套资源
    图：查找配套资源
  3. 在弹出的页面中，找到对应的NPU固件与驱动，点击企业网下载；
    图：下载NPU固件与驱动
  4. 参考华为官方安装教程，完成NPU驱动与固件的安装

安装Ascend Docker Runtime

1. 参考安装NPU驱动与固件的第1、2个步骤，查看与操作系统兼容的 MindCluster 版本，并前往昇腾社区下载安装包；

图：下载Ascend Docker Runtime

2. 参考华为官方安装教程，完成Ascend Docker Runtime的安装。

模型在线部署（基于GPUStack）

启动GPUStack

完成环境配置后，即可启动 GPUStack 服务，您可以参考如下 docker run 命令示例：

1.拉取GPUStack镜像

docker pull quay.io/gpustack/gpustack:v2.0.2

2.启动GPUStack

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

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

  • 内置账户：admin
  • 密码： 可通过该命令获取

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

  • 默认端口：80
说明：

如果机器的80端口已被占用，或出于网络安全策略的考虑，可采用端口映射的方式修改GPUStack的访问端口：

# 示例：将GPUStack的访问端口修改为8080

sudo docker run -d --name gpustack

--restart=unless-stopped \

-p 8080:80 \

添加集群及配置节点

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

1.创建集群

点击集群 -> 添加集群。选择合适的集群类型，例如 Docker 集群。

2. 基本配置

填写名称与描述。

3. 添加节点

根据节点的实际环境，按界面步骤提示填写并匹配相应的配置信息，其中GPU厂商选择 Ascend。

4. 启动节点

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

docker run -d --name gpustack-worker \
      -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
      -e "GPUSTACK_TOKEN=YourGpustackToken" \
      --restart=unless-stopped \
      --privileged \
      --network=host \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      --volume gpustack-data:/var/lib/gpustack \
      -e ASCEND_VISIBLE_DEVICES=all \
      --runtime ascend \
      quay.io/gpustack/gpustack:v2.0.2 \
      --server-url http://ip:port \
      --worker-ip ip \
      --system-default-container-registry quay.io

  • --worker-ip：指的需要添加的工作节点的ip，在添加节点弹窗的第四步指定参数中填写节点IP后，启动指令中将会自动添加该参数设置。

注意：若容器里无法访问到驱动信息，建议参考如下命令手动将其挂载到容器里：

docker run -d --name gpustack-worker \
      -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
      -e "GPUSTACK_TOKEN=YourGpustackToken" \
      --restart=unless-stopped \
      --privileged \
      --network=host \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      --volume gpustack-data:/var/lib/gpustack \
      -e ASCEND_VISIBLE_DEVICES=all \
      --runtime ascend \
      --volume /usr/local/sbin/npu-smi:/usr/local/bin/npu-smi \
      --volume /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \
      --volume /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools \
      -e LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64:$LD_LIBRARY_PATH \
      quay.io/gpustack/gpustack:v2.0.2 \
      --server-url http://ip:port \
      --worker-ip ip \
      --system-default-container-registry quay.io

在线部署模型

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

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

模型离线部署（基于GPUStack）

启动GPUStack

1. 准备容器镜像

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

# 在线环境拉取镜像
docker pull quay.io/gpustack/gpustack:v2.0.2
docker pull quay.io/gpustack/runner:cann8.3-910b-vllm0.12.0
docker pull quay.io/gpustack/runtime:pause

# 打包镜像
docker save -o gpustack.tar quay.io/gpustack/gpustack:v2.0.2
docker save -o gpustack-runner-cann8.3.tar quay.io/gpustack/runner:cann8.3-910b-vllm0.12.0
docker save -o gpustack-runtime-pause.tar quay.io/gpustack/runtime:pause

# 在离线环境导入
docker load -i gpustack-runner-cann8.3.tar
docker load -i gpustack.tar
docker load -i gpustack-runtime-pause.tar 

2. 准备离线模型文件

前往ModelScope下载模型文件，并传入到离线环境。

3.启动GPUStack

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

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

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

  • 内置账户：admin
  • 密码： 可通过该命令获取

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

  • 默认端口：80

添加集群及配置节点

1.创建集群

点击集群 -> 添加集群。选择合适的集群类型，例如 Docker 集群。

2. 基本配置

填写名称与描述。

3. 添加节点

根据节点的实际环境，按界面步骤提示填写并匹配相应的配置信息，其中GPU厂商选择 Ascend。

4. 启动节点

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

docker run -d --name gpustack-worker \
      -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
      -e "GPUSTACK_TOKEN=YourGpustackToken" \
      --restart=unless-stopped \
      --privileged \
      --network=host \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      --volume gpustack-data:/var/lib/gpustack \
      -v /path/to/model-cache:/opt/model-cache \
      -e ASCEND_VISIBLE_DEVICES=all \
      --runtime ascend \
      quay.io/gpustack/gpustack:v2.0.2 \
      --server-url http://ip:port \
      --worker-ip ip \
      --system-default-container-registry quay.io

  • --worker-ip：指的需要添加的工作节点的ip，在添加节点弹窗的第四步指定参数中填写节点IP后，启动指令中将会自动添加该参数设置。

注意：若容器里无法访问到驱动信息，建议参考如下命令手动将其挂载到容器里：

docker run -d --name gpustack-worker \
      -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
      -e "GPUSTACK_TOKEN=YourGpustackToken" \
      --restart=unless-stopped \
      --privileged \
      --network=host \
      --volume /var/run/docker.sock:/var/run/docker.sock \
      --volume gpustack-data:/var/lib/gpustack \
      -v /path/to/model-cache:/opt/model-cache \
      -e ASCEND_VISIBLE_DEVICES=all \
      --runtime ascend \
      --volume /usr/local/sbin/npu-smi:/usr/local/bin/npu-smi \
      --volume /usr/local/Ascend/driver/lib64:/usr/local/Ascend/driver/lib64 \
      --volume /usr/local/Ascend/driver/tools:/usr/local/Ascend/driver/tools \
      -e LD_LIBRARY_PATH=/usr/local/Ascend/driver/lib64/driver:/usr/local/Ascend/driver/lib64/common:/usr/local/Ascend/driver/lib64:$LD_LIBRARY_PATH \
      quay.io/gpustack/gpustack:v2.0.2 \
      --server-url http://ip:port \
      --worker-ip ip \
      --system-default-container-registry quay.io

离线部署模型

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

  1. 在左侧导航栏中点击模型文件，进入模型文件功能模块；
  2. 点击右上角按钮，添加模型文件->本地路径；将离线环境中准备好的模型文件上传；
  3. 在弹出抽屉页面中，可自定义部署模型的名称、副本数等，通常保持默认即可；
  4. 填写完成后，在模型文件列表中找到上传的模型，点击部署；
    图：模型库中选择模型并填写部署参数
  5. 稍后前往“部署” 页面，观察到模型状态变为 Running，即表示部署成功。

安装SuperMap AgentX Server

AgentX的安装与启动流程请参考：Docker环境安装SuperMap AgentX Server