基于天数智芯环境部署AgentX

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

环境准备

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

软硬件配置 规格要求 说明
操作系统 Linux 系统 要求部署用户具备 root 权限，或能够使用 sudo 执行命令。
显卡 天数智芯 GPU MR-V100 DUO
磁盘空间 100G及以上 用于存放容器、模型文件等
CPU ARM64 架构 HUAWEI Kunpeng 920 5250
软件依赖 Docker 24.0.9及以上版本
Docker Compose 2.27及以上版本
GPU驱动与固件 查询与操作系统兼容的GPU驱动与固件资源并下载
部署镜像 核心服务镜像 quay.io/gpustack/gpustack:v2.1.0
推理业务镜像 registry.iluvatar.com.cn:10443/customer/sz/vllm0.11.2-4.4.0-aarch64:v1
运行时辅助镜像 quay.io/gpustack/runtime:pause
SuperMap AgentX Server产品镜像 SuperMap AgentX Server 产品镜像：12.1.0.0-alpha-arm64

前置环境安装

1. 安装必要包

根据系统需求安装必要的软件包。

  • Centos

yum install kernel-devel gcc make

  • Ubuntu

apt install linux-headers-$(uname -r) gcc make

2. 锁定内核版本不要升级

确保内核版本被锁定，避免后续升级导致驱动兼容性问题。

  • Centos：修改/etc/yum.conf，最后面加入 exclude=kernel*
  • Ubuntu

apt-mark hold linux-image-generic linux-headers-generic linux-headers-$(uname -r) linux-image$(uname -r) linux-modules$(uname -r) linux-modules-extra$(uname -r)

3. 下载并安装CUDA头文件

wget https://gitee.com/121786404/corex_knife/raw/master/driver/partial_install_cuda_header.tar.gz
tar xf partial_install_cuda_header.tar.gz
cd partial_install_cuda_header
bash install-cuda-header.sh 

4. 检查kernel头文件是否安装

ls /lib/modules/$(uname -r)/build

如果返回信息为空或者返回报错信息，则需要安装kernel头文件。

  • 使用yum作为软件包管理器的系统的安装命令：

yum install -y kernel-devel-$(uname -r)  kernel-headers-$(uname -r)

  • 使用apt作为软件包管理器的系统的安装命令：

apt install linux-headers-$(uname -r)

5. 下载并安装驱动

  • 下载

wget https://gitee.com/121786404/corex_knife/raw/master/driver/corex-driver-linux64-4.4.0_aarch64_10.2.run
wget https://gitee.com/121786404/corex_knife/raw/master/driver/corex.conf

  • 卸载旧的驱动（如有）和安装新驱动

/usr/local/corex/bin/corex-driver-uninstaller 
bash corex-driver-linux64-4.4.0_aarch64_10.2.run

请根据您的实际系统环境，访问官方支持平台选择匹配的驱动版本。

图：官方支持平台

6. 配置环境变量

cp corex.conf /etc/ld.so.conf.d/
echo "export PATH=\$PATH:/usr/local/corex/bin" >> /etc/profile
rm -f /usr/local/corex
ln -s /usr/local/corex-* /usr/local/corex
ldconfig
source /etc/profile

7. 检测驱动是否正常运行

运行 ixsmi 命令，若能正常显示GPU信息，则驱动安装成功。

8. 安装ix-container-toolkit工具

图：下载ix-container-toolkit工具
  • 安装并配置

chmod a+x ./ix-container-toolkit-1.1.0_aarch64.run
./ix-container-toolkit-1.1.0_aarch64.run --install
ix-ctk runtime configure --runtime docker --ix-set-as-default
systemctl daemon-reload
systemctl restart docker

  • 配置校验

cat/etc/docker/daemon.json

模型在线部署（基于GPUStack）

启动GPUStack

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

1.拉取GPUStack镜像

docker pull quay.io/gpustack/gpustack:v2.1.0
docker pull registry.iluvatar.com.cn:10443/customer/sz/vllm0.11.2-4.4.0-aarch64:v1

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厂商选择 天数智芯。

4. 启动节点

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

配置Worker节点

docker run -d \
  --name gpustack-worker \
  -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
  -e "GPUSTACK_TOKEN=gpustack_86cefb7d5710dbbd_f7a87e858ecdfe63151450148aa6cceb" \
  --restart=unless-stopped \
  --privileged \
  --network=host \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume gpustack-data:/var/lib/gpustack \
  --volume /usr/local/corex:/usr/local/corex:ro \
  --runtime iluvatar \
  quay.io/gpustack/gpustack:v2.1.0 \
      --server-url http://ip:port \
      --worker-ip ip \
      --system-default-container-registry quay.io      
# 注意GPUSTACK_TOKEN、--server-url、--worker-ip需修改为自己对应的地址
# GPUSTACK_TOKEN：认证Token,在根据步骤添加节点时，官方提供的命令默认提供（无需自己填写）
# --worker-ip：指的需要添加的工作节点的ip（需要自己填写）
# --server-url：主节点服务地址，在根据步骤添加节点时，官方提供的命令默认提供（无需自己填写）

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

在线部署模型

首先需要配置推理后端：

  1. 在左侧导航栏中点击推理后端；
  2. 点击右上角添加后端->自定义；
  3. 配置下载好的vLLM版本信息，配置好后点击+添加版本->保存。

然后在“部署”中部署大模型：

  1. 在左侧导航栏中点击部署；
  2. 点击右上角部署模型->ModelScope；
  3. 选择目标模型并在“高级”选项卡下配置模型参数。

以vLLM为例展示配置参数

图：LLM模型配置参数
图：Embedding模型配置参数
图：Rerank模型配置参数

参数说明

  • --max-model-len：最大上下文长度
  • --gpu-memory-utilization：GPU 显存占用率，允许推理引擎预先占用显卡显存的比例（0.9 代表 90%）
  • --enable-auto-tool-choice：开启工具调用
  • --tool-call-parser=hermes：工具调用解析器
  • --reasoning-parser=qwen3：将模型生成的思考内容解析为结构化消息

模型离线部署（基于GPUStack）

启动GPUStack

1. 准备容器镜像

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

# 在线环境拉取镜像
docker pull quay.io/gpustack/gpustack:v2.1.0
docker pull registry.iluvatar.com.cn:10443/customer/sz/vllm0.11.2-4.4.0-aarch64:v1
docker pull quay.io/gpustack/runtime:pause
# 打包镜像
docker save -o gpustack.tar quay.io/gpustack/gpustack:v2.1.0
docker save -o iluvatar-vllm.tar registry.iluvatar.com.cn:10443/customer/sz/vllm0.11.2-4.4.0-aarch64:v1
docker save -o gpustack-runtime-pause.tar quay.io/gpustack/runtime:pause
# 在离线环境导入
docker load -i iluvatar-vllm.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:v2.1.0 \
    --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. 启动节点

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

配置Worker节点

注意将宿主机的模型文件挂载进容器中：
即：-v /path/to/model-cache:/opt/model-cache
docker run -d \
  --name gpustack-worker \
  -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
  -e "GPUSTACK_TOKEN=gpustack_86cefb7d5710dbbd_f7a87e858ecdfe63151450148aa6cceb" \
  --restart=unless-stopped \
  --privileged \
  --network=host \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume gpustack-data:/var/lib/gpustack \
  --volume /usr/local/corex:/usr/local/corex:ro \
  -v /path/to/model-cache:/opt/model-cache \
  --runtime iluvatar \
  quay.io/gpustack/gpustack:v2.1.0 \
      --server-url http://ip:port \
      --worker-ip ip \
      --system-default-container-registry quay.io 
      
# 注意GPUSTACK_TOKEN、--server-url、--worker-ip需修改为自己对应的地址

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

离线部署模型

首先需要配置推理后端：

  1. 在左侧导航栏中点击推理后端；
  2. 点击右上角添加后端->自定义；
  3. 配置下载好的vLLM版本信息，配置好后点击+添加版本->保存。

添加容器内挂载的模型文件：

  1. 在左侧导航栏中点击模型文件；
  2. 点击添加模型文件->本地路径；
  3. 在“模型路径”字段中，填写模型文件在容器内的挂载路径。
  4. 在模型文件列表中，单击目标模型右侧的部署图标，进入模型部署页面并配置相关参数。

以vLLM为例展示配置参数

图：LLM模型配置参数
图：Embedding模型配置参数
图：Rerank模型配置参数

参数说明

  • --max-model-len：最大上下文长度
  • --gpu-memory-utilization：GPU 显存占用率，允许推理引擎预先占用显卡显存的比例（0.9 代表 90%）
  • --enable-auto-tool-choice：开启工具调用
  • --tool-call-parser=hermes：工具调用解析器
  • --reasoning-parser=qwen3：将模型生成的思考内容解析为结构化消息

安装SuperMap AgentX Server

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