沐曦 MetaX 部署实践

最近更新时间:2025-12-30 17:42:12

我的收藏
目前,TencentOS Server 已实现对沐曦 MetaX 驱动与 MXMACA SDK 的原生支持,为使用沐曦 GPU 提供了完整的 RPM 二进制软件包,包括内核级驱动、系统管理工具、计算库及 AI 框架适配组件。
本文档将指导如何在 TencentOS Server 4 上快速完成沐曦 MetaX 驱动与 MXMACA SDK 的安装部署,并无缝运行上层 AI 模型与应用。

基础环境要求及说明

支持 TencentOS 内核版本:系统及内核要求参见下表,仅支持该表中系统及内核版本。如果您的实例低于支持内核版本,请先升级内核(如 dnf install kernel-6.6.98-40.2.tl4)。同时,在使用 MXMACA-sdk 驱动时,建议 GCC 版本与系统发行版保持一致,CMake 版本不低于 3.10。
注意:
升级操作系统内核风险较高,可能会导致系统不稳定或出现兼容性问题。在操作内核升级前,请充分了解升级可能出现的问题,建议同步备份重要数据并谨慎操作。
如果您的实例高于支持的内核版本,请联系相关社区,OC 社区与沐曦官方将尽快完善支持。
CPU架构
操作系统
支持内核版本
x86_64
TencentOS 3
5.4.241-24.0017.23.tl3
x86_64
TencentOS 4
6.6.92-34.1.tl4
x86_64
TencentOS 4
6.6.98-40.2.tl4
支持的 GPU 设备:沐曦曦云 C500/C550/C588/C600/N260 系列
MetaX 驱动软件版本:3.1.0.26
其他要求
PCIe 需要支持 Gen5 X16。
MMIO 资源满足 GPU 板卡资源需求。
服务器电源满足整机最大工作负载。
单个 PCIe 槽位满足 GPU 单卡的供电需求。


环境检查

本文部署实践方案,主要以二进制形式安装驱动包,请通过以下命令确认系统环境符合要求,匹配软硬件系统。检查 CPU 架构、操作系统版本和内核版本满足基础环境要求。若存在任何一项不匹配,请参见 基础环境要求及说明 升级软硬件系统。
# 检查 CPU 架构
uname -m
# 检查操作系统版本
lsb_release -a
# 检查内核版本
uname -r
# 如内核版本不满足需求,请先升级至指定内核并设置成默认启动内核
dnf install kernel-6.6.98-40.2.tl4
# 检查是否已安装旧版驱动
yum list installed | grep metax-driver
# 如已安装旧驱动,请执行
yum remove metax-driver
# 检查 GPU 设备是否识别
lspci | grep 9999

安装 MetaX 驱动及 MXMACA SDK

安装 TencentOS EPOL 源

如使用 TencentOS 4 系统,请先安装 EPOL extras 软件源:
说明:
TencentOS 3系统需要使用编译方式安装驱动。如您存在相关需求,请 联系我们
dnf install epol-extras-release

安装 MetaX 驱动包

安装驱动及依赖包:
dnf install metax-driver-3.1.0.26

固件升级(可选)

如当前版本固件存在已知问题(如安全漏洞、稳定性问题)或硬件设备更新等场景下,请升级固件。MetaX 系列 GPU 采用沐曦带内管理工具 mx-smi 对固件进行升级。mx-smi 工具自动安装在驱动安装包的 /opt/mxdriver/bin 目录下。
# 查看当前固件版本
mx-smi --show-version
# 升级固件(需root)
sudo mx-smi -u /lib/firmware/metax/mxc500/mxvbios-xxx.bin -t 600
升级后需重启系统生效。
注意:
实例重启会导致正在运行的应用和服务被强制终止,或文件和内存数据会丢失。重启前请做好数据保存等操作。

虚拟化安装(可选)

如您需要使用 GPU 的 SR-IOV 硬件虚拟化功能,以实现更高效的虚拟化资源分配与管理,请安装 mxgvm 工具包。
注意:
如您的业务场景不需要使用 SR-IOV 硬件虚拟化功能,建议您不要安装 mxgvm 工具包。因为安装该工具包可能导致系统无法检测到 GPU 硬件设备,引发一系列诸如实例无法获取 GPU 资源、图形处理任务异常中断等问题,影响系统的稳定性和正常使用。
启用 SR-IOV 功能后,物理 GPU 可凭借其硬件虚拟化特性,虚拟出多个 VF(虚拟功能)设备。这些 VF 设备使用灵活,既能在宿主机上,通过 metax-driver 驱动直接调用,实现高效的数据处理与图形渲染,也可绑定至虚拟机,为虚拟环境提供图形处理支持。
安装 mxgvm 时,系统会自动安装 metax-driver,无需手动安装。当使用虚拟机时,libvirt 会自动将 GPU 设备从 metax-driver 解绑,并重新绑定到 vfio(虚拟功能 I/O)驱动,确保虚拟机正确识别设备。
不过,虚拟机内要使 GPU 正常工作、发挥最佳性能,需单独安装 metax-driver 驱动,以满足复杂虚拟化应用场景需求。
dnf install mxgvm-3.0.26

安装验证

查看驱动安装结果。
mx-smi

安装 MXMACA SDK 包

由于相关 RPM 包较多,推荐使用如下命令一键安装。本次适配提供的 MXMACA SDK RPM 包清单,请参见 软件包清单
dnf install maca_sdk



AI 框架安装与验证

拉取 AI 镜像

在沐曦官方开发者社区 > 软件包下载 > AI 人工智能程序包 页面选择所需框架,此处以 vLLM 框架 为例,单击 wget 命令复制,进行框架的镜像拉取:

说明:
TencentOS 4 仅支持 Python 3.11 及 3.12 版本,因此在沐曦官网拉取 AI 框架时,请使用 py311py312 的版本。

配置 cu-bridge 环境

请参见以下方式配置 cu-bridge 环境:
dnf install -y git cmake
export MACA_PATH=/opt/maca
wget https://gitee.com/metax-maca/cu-bridge/repository/archive/3.1.0.zip
unzip 3.1.0.zip
mv cu-bridge-3.1.0 cu-bridge
sudo chmod 755 cu-bridge -Rf
cd cu-bridge
mkdir build && cd ./build
cmake -DCMAKE_INSTALL_PREFIX=/opt/maca/tools/cu-bridge ../
make && make install
export MACA_PATH=/opt/maca
export CUCC_PATH=/opt/maca/tools/cu-bridge
export PATH=$PATH:${CUCC_PATH}/tools:${CUCC_PATH}/bin
export CUCC_CMAKE_ENTRY=2 # 选择使用 cu-bridge 模拟 CMake 服务
export CUDA_PATH=${CUCC_PATH} # CUDA_PATH 入口重定向到 cu-bridge 安装位置

启动容器

在容器中运行 AI 框架及大模型需要使用宿主机 GPU 能力,及直通宿主机 GPU,主要有如下两种方式(可选其一):

Docker Run(推荐方式):

推荐按如下 Docker Run 方式直通宿主机 GPU,执行步骤更便捷,避免基础配置造成的环境差异:
docker run -it --restart=always --device=/dev/dri --device=/dev/mxcd --device=/dev/infiniband --group-add video --name deepspeed_test --network=host --security-opt seccomp=unconfined --security-opt apparmor=unconfined --shm-size 100gb --ulimit memlock=-1 --privileged=true -v /home:/home [image_id] bash

Metax-docker Run :

1. 安装 Metax-docker:
访问沐曦开发者社区,选择云平台工具 > Metax-docker。在该页面下载离线压缩包,解压完成后请参见以下方式安装。
# 安装 metax-docker
mkdir metax-docker
tar -C metax-docker -xvf metax-docker_0.13.1.tar
cd metax-docker
sudo ./metax-docker_0.13.1.<ARCH>.run
2. 使用 Metax-docker:
您需要安装高于或等于 19.03 版本的 Docker 工具,同时请确保主机上已经正确安装了 MXMACA 软件栈。
# 在容器中使用曦云GPU
metax-docker run -it --rm --gpus=all user-application:1.0 /bin/bash
Metax-docker 支持官方 Docker 的全部命令及参数,并在 .run 命令下支持的额外参数,详情请参见 Metax-docker 官方指导

运行大模型(以 vLLM+Qwen 示例)

# 安装依赖
dnf install pip curl

# 下载 modelscope
pip install modelscope

# 拉取大模型(以 Qwen 为例)
modelscope download --model 'Qwen/Qwen2-7b'

# 运行服务
vllm serve /root/.cache/modelscope/hub/models/Qwen/Qwen2-7b --port 8000 --served-model-name Qwen2-7b --served-model-name Qwen/Qwen2-7b

# 另起终端利用 curl 对话
curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{"model": "Qwen/Qwen2-7b","messages": [{"role": "system", "content": "你是一个有帮助的助手"},{"role": "user", "content": "法国首都在哪?"}],"max_tokens": 100,"temperature": 0.7}'


附录

附录一:软件包清单

分类
文件名
包名
驱动
metax-driver-3.1.0.26-1.x86_64.rpm
metax-driver
metax-linux-3.1.0.26-1.x86_64.rpm
metax-linux
mxgvm-3.0.26-1.x86_64.rpm
mxgvm
mxfw-3.1.0-1.noarch.rpm
mxfw
mxsmt-3.1.0-1.x86_64.rpm
mxsmt
SDK
commonlib_3.1.0-3.1.0.19-1.x86_64.rpm
commonlib
maca_sdk-3.1.0.19-1.x86_64.rpm
maca_sdk
maca_sdk_3.1.0-3.1.0.19-1.x86_64.rpm
maca_sdk
macainfo_3.1.0-3.1.0.19-1.x86_64.rpm
macainfo
mcanalyzer_3.1.0-3.1.0.19-1.x86_64.rpm
mcanalyzer
mcblas_3.1.0-3.1.0.19-1.x86_64.rpm
mcblas
mcblaslt_3.1.0-3.1.0.19-1.x86_64.rpm
mcblaslt
mcccl_3.1.0-3.1.0.19-1.x86_64.rpm
mcccl
mcccltests-3.1.0-3.1.0.19-1.x86_64.rpm
mcccltests
mccompiler_3.1.0-3.1.0.19-1.x86_64.rpm
mccompiler
mcdnn_3.1.0-3.1.0.19-1.x86_64.rpm
mcdnn
mcfft_3.1.0-3.1.0.19-1.x86_64.rpm
mcfft
mcfile_3.1.0-3.1.0.19-1.x86_64.rpm
mcfile
mcflashattn_3.1.0-3.1.0.19-1.x86_64.rpm
mcflashattn
mcflashinfer_3.1.0-3.1.0.19-1.x86_64.rpm
mcflashinfer
mcgpufort_3.1.0-3.1.0.19-1.x86_64.rpm
mcgpufort
mchotspot_3.1.0-3.1.0.19-1.x86_64.rpm
mchotspot
mcimage_3.1.0-3.1.0.19-1.x86_64.rpm
mcimage
mcjpeg_3.1.0-3.1.0.19-1.x86_64.rpm
mcjpeg
mckernellib_3.1.0-3.1.0.19-1.x86_64.rpm
mckernellib
mcmathlib_3.1.0-3.1.0.19-1.x86_64.rpm
mcmathlib
mcpti_3.1.0-3.1.0.19-1.x86_64.rpm
mcpti
mcrand_3.1.0-3.1.0.19-1.x86_64.rpm
mcrand
mcruntime_3.1.0-3.1.0.19-1.x86_64.rpm
mcruntime
mcsolver_3.1.0-3.1.0.19-1.x86_64.rpm
mcsolver
mcsolverit_3.1.0-3.1.0.19-1.x86_64.rpm
mcsolverit
mcsparse_3.1.0-3.1.0.19-1.x86_64.rpm
mcsparse
mcthrust_3.1.0-3.1.0.19-1.x86_64.rpm
mcthrust
mctlass_3.1.0-3.1.0.19-1.x86_64.rpm
mctlass
mctoolext_3.1.0-3.1.0.19-1.x86_64.rpm
mctoolext
mctracer-3.1.0-3.1.0.19-1.x86_64.rpm
mctracer
metax-fabricmanager_3.1.0-3.1.0.19-1.x86_64.rpm
metax-fabricmanager
mxccl_plugin_3.1.0-3.1.0.19-1.x86_64.rpm
mxccl_plugin
mxcompute_3.1.0-3.1.0.19-1.x86_64.rpm
mxcompute
mxdiagease-3.1.0-3.1.0.19-1.x86_64.rpm
mxdiagease
mxexporter-3.1.0-3.1.0.19-1.x86_64.rpm
mxexporter
mxffmpeg-3.1.0-3.1.0.19-1.x86_64.rpm
mxffmpeg
mxffmpeg-dev-3.1.0-3.1.0.19-1.x86_64.rpm
mxffmpeg-dev
mxfortran_3.1.0-3.1.0.19-1.x86_64.rpm
mxfortran
mxgdrcopy-3.1.0-3.1.0.19-1.x86_64.rpm
mxgdrcopy
mxgpu_llvm_3.1.0-3.1.0.19-1.x86_64.rpm
mxgpu_llvm
mxkw_3.1.0-3.1.0.19-1.x86_64.rpm
mxkw
mxmaca-install-3.1.0-3.1.0.19-1.x86_64.rpm
mxmaca-install
mxompi-3.1.0-3.1.0.19-1.x86_64.rpm
mxompi
mxreport-3.1.0-3.1.0.19-1.x86_64.rpm
mxreport
mxsm1-devel-3.1.0-3.1.0.19-1.x86_64.rpm
mxsm1-devel
mxucx-3.1.0-3.1.0.19-1.x86_64.rpm
mxucx
mxvpu_3.1.0-3.1.0.19-1.x86_64.rpm
mxvpu
mxvs-3.1.0-3.1.0.19-1.x86_64.rpm
mxvs
sample_3.1.0-3.1.0.19-1.x86_64.rpm
sample
vscode-clangd_3.1.0-3.1.0.19-1.x86_64.rpm
vscode-clangd
说明:
其中:
metax-driver 是驱动包元信息,安装依赖 metax-linux/mxfw/mxsmt。
mxgvm 是虚拟化驱动包,安装依赖 metax-linux。

附录二:沐曦曦云系列 GPU 应用程序系统架构



附录三:沐曦曦云 C500、C550系列硬件适配列表

产品
适配CPU
主推拓扑
已适配 OEM/厂商
优势
C500
Intel
common
浪潮信息、新华三、联想、超聚变、中兴、宁畅等
架构通用:基于经典4U PCIe AI 服务器形态,易于适配、安装、维护,量产机型已覆盖主流 OEM 厂商,在各类整机产品中可适用范围最广。
拓扑先进:通过 C500 4卡互连拓扑并支持4种 PCIe 服务器经典拓扑(common,balance,cascade,直通),适应各类训练计算场景。
多元平台:支持 Intel 及海光、飞腾、鲲鹏等国内外主流 CPU 平台。
成熟稳定:已实现大规模交付并在多个超大规模集群部署并稳定运行。
海光4号
balance
浪潮计算机、新华三、联想、中兴、中科可控等
飞腾S5000C
balance
长城等
鲲鹏920
cascade
超聚变、华鲲振宇等
C550
Intel
balance
浪潮信息、新华三、联想、超聚变、中兴等
架构通用:基于经典6U/8U OAM AI 服务器形态,兼容 OAM 1.5/2.0标准,可将 UBB+OAM 作为整体与机头进行适配,量产机型已覆盖主流 OEM 厂商。
拓扑先进:通过 C550 8卡全互连拓扑实现896GB/s 国内领先带宽卡间互连,为各类训练计算场景提供标准服务器单机最强性能。
多元平台:支持 Intel 及海光、飞腾、鲲鹏等国内外主流 CPU 平台。
成熟稳定:已实现大规模交付并在多个超大规模集群部署并稳定运行。
液冷兼容:提供液冷形态模组与液冷 OAM 服务器适配,已实现液冷 OAM 集群大规模部署。