目前,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 软件源:
说明:
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 包
dnf install maca_sdk
AI 框架安装与验证
拉取 AI 镜像

说明:
TencentOS 4 仅支持 Python 3.11 及 3.12 版本,因此在沐曦官网拉取 AI 框架时,请使用
py311 或 py312 的版本。配置 cu-bridge 环境
请参见以下方式配置 cu-bridge 环境:
dnf install -y git cmakeexport MACA_PATH=/opt/macawget https://gitee.com/metax-maca/cu-bridge/repository/archive/3.1.0.zipunzip 3.1.0.zipmv cu-bridge-3.1.0 cu-bridgesudo chmod 755 cu-bridge -Rfcd cu-bridgemkdir build && cd ./buildcmake -DCMAKE_INSTALL_PREFIX=/opt/maca/tools/cu-bridge ../make && make installexport MACA_PATH=/opt/macaexport CUCC_PATH=/opt/maca/tools/cu-bridgeexport PATH=$PATH:${CUCC_PATH}/tools:${CUCC_PATH}/binexport 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-dockermkdir metax-dockertar -C metax-docker -xvf metax-docker_0.13.1.tarcd metax-dockersudo ./metax-docker_0.13.1.<ARCH>.run
2. 使用 Metax-docker:
您需要安装高于或等于 19.03 版本的 Docker 工具,同时请确保主机上已经正确安装了 MXMACA 软件栈。
# 在容器中使用曦云GPUmetax-docker run -it --rm --gpus=all user-application:1.0 /bin/bash
运行大模型(以 vLLM+Qwen 示例)
# 安装依赖dnf install pip curl# 下载 modelscopepip 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 集群大规模部署。 |