沐曦AI服务器上跑模型前，驱动与工具链怎么装
沐曦AI服务器的配置核心不是“把驱动装完就结束”，而是要让加速卡在系统里被正确识别、工具链能调用设备、上层框架能实际跑通计算。
如果只装驱动不做验证，很容易出现mx-smi能看到卡但框架跑模型时报错的情况。
下面按实际操作顺序说明每一步做什么、怎么检查、失败了看哪里。
先确认卡型号和系统版本
动手之前先登录服务器，用系统命令确认两件事：加速卡的具体型号，以及操作系统发行版和内核版本。
沐曦不同型号的卡对驱动和工具链版本有对应关系，装错版本可能导致设备无法识别。
# 查看操作系统版本
cat /etc/os-release
# 查看内核版本
uname -r
# 查看PCI设备中是否出现沐曦加速卡
lspci | grep -i metaxlspci能列出设备只代表硬件被主板识别，不代表驱动已经正常工作。
记录下卡型号和系统版本后，去沐曦官方文档或随卡资料中核对对应的驱动包和MXMACA工具链版本，不要直接拿其他型号的安装包混用。
如果服务器是刚装好的系统，还需要确认已安装编译工具和内核头文件，因为驱动安装过程可能需要编译内核模块：
# 以CentOS/RHEL系为例
yum install -y gcc make kernel-devel-$(uname -r) dkms
# Ubuntu/Debian系示例
apt install -y gcc make linux-headers-$(uname -r) dkms安装驱动和MXMACA工具链
沐曦的软件栈通常包含驱动包和MXMACA工具链两部分。
驱动负责让系统识别并管理加速卡，工具链提供运行时库、编译器和监控工具。
安装顺序一般是先驱动后工具链，具体包名以拿到的安装介质为准。
进入安装包所在目录后，按官方提供的安装方式执行。
常见形式是运行安装脚本或使用包管理器安装：
# 示例：运行安装脚本（实际文件名以安装包为准）
chmod +x metax-driver-installer.run
./metax-driver-installer.run安装过程中如果提示内核模块编译失败，优先检查kernel-devel版本是否与当前内核完全一致，uname -r的输出和已安装的头文件版本必须匹配。
安装完成后通常需要重启服务器让驱动模块生效：
reboot重启后检查驱动模块是否加载：
lsmod | grep -i metax没有输出说明驱动模块未加载，需要回到安装日志中查找报错原因，不要继续往下装工具链。
用mx-smi确认设备状态
驱动正常加载后，使用沐曦提供的设备管理工具检查卡的状态。
这个工具类似NVIDIA的nvidia-smi，能显示设备数量、温度、功耗和显存占用。
mx-smi正常输出应能看到加速卡列表和基本信息。
如果命令不存在，说明工具链没有安装完整或环境变量未生效，可以检查安装目录下的bin路径是否已加入PATH。
如果能看到卡但状态异常，记录下错误码和提示信息，对照官方文档排查。
此时可以顺便确认设备节点是否存在：
ls /dev/ | grep -i metax设备节点缺失通常意味着驱动没有正确创建设备文件，需要重新检查驱动安装日志。
在容器或框架中做一次实际计算验证
设备能被mx-smi识别，不代表上层框架可以直接使用。
建议用官方提供的容器镜像或示例程序做一次最小验证，确认工具链和运行时库能被框架正确调用。
如果使用容器方式，需要确保容器运行时已配置沐曦设备映射，启动容器后执行设备检查命令，确认容器内也能看到加速卡。
随后运行官方示例中的矩阵计算或推理脚本，观察是否正常输出结果。
如果不使用容器，直接在宿主机上验证时，需要确认框架版本与MXMACA工具链版本匹配。
跑通一个简单计算后，再逐步迁移实际模型，不要一上来就加载大模型，否则报错信息会被模型加载过程掩盖。
常见问题和避坑点
驱动装完但mx-smi找不到设备：先看lsmod是否有驱动模块，再看dmesg中是否有加载失败记录。
内核版本与驱动不匹配是最常见原因。
容器内看不到加速卡：检查容器启动参数是否挂载了设备节点和驱动库目录，不同容器运行时配置方式不同，以官方容器文档为准。
框架报找不到设备或运行时库：确认LD_LIBRARY_PATH是否包含工具链的库目录，以及框架是否安装了对应沐曦后端的版本。
不要跳过版本核对：沐曦驱动、工具链和框架后端之间有版本对应关系，混用不同批次的安装包可能导致设备识别正常但计算报错。
完成以上步骤后，建议把mx-smi输出、驱动版本和框架验证结果记录到服务器维护文档中，后续升级或迁移时可以直接对照，减少重复排查。
