环境准备

环境依赖

MUSA SDK 和 MUSA Driver 属于不同层级：

• MUSA SDK：镜像内的 Toolkits、Runtime 和运行库，供 vLLM、PyTorch 等软件使用。
• MUSA Driver：安装在宿主机，负责识别 GPU 并向容器提供设备访问能力。

对应关系如下。请根据宿主机上 mthreads-gmi 显示的 Driver Version 选择镜像：

MUSA SDK	宿主机 MUSA Driver（mthreads-gmi）	PyTorch	vLLM	镜像
4.3.5	3.3.5	2.9.0	0.24.1	registry.mthreads.com/presale/devtech/vllm-mt:d0930
5.2.0	5.2.0	2.11.0	0.29.1	registry.mthreads.com/presale/devtech/vllm-mt-0.29-sdk520:d0930

除上述驱动和镜像版本外，宿主机还需要安装以下组件：

组件	版本要求
mtml	按 MTML 安装指南安装与当前环境兼容的版本
mt-container-toolkit	2.2.0

建议将 mt-container-toolkit 升级到 2.2.0。版本过低时，Docker 容器可能无法正确使用 GPU。可从 KUAE Cloud Native Toolkits v2.2.0 下载安装包，并执行：

sudo dpkg -i mt-container-toolkit_2.2.0-1_amd64.deb
cd /usr/bin/musa && sudo ./docker setup "$PWD"

以上为依赖组件推荐版本，安装方式如下：

1. （推荐）通过 MUSA-Deploy 工具一键安装。
2. 通过官网下载对应软件包，然后依照文档指示通过软件管理工具（如 dpkg）安装：

• MUSA SDK：下载链接 | 文档链接
• 云原生套件：下载链接 | 文档链接

环境检测

基础配置检查

执行以下命令检查 OS 与 Linux kernel 版本：

lsb_release -a
uname -r

示例输出：

No LSB modules are available.
Distributor ID:	Ubuntu
Description:	Ubuntu 22.04.4 LTS
Release:	22.04
Codename:	jammy
5.15.0-105-generic

如果版本不符预期，建议更换系统或 Kernel 到推荐版本。

GMI 检查

执行以下命令确认系统可以识别 S4000 设备，并检查设备状态：

mthreads-gmi

如果命令不存在或无法输出设备信息，请先确认宿主机 MUSA Driver、MTML 和 mt-container-toolkit 是否正确安装。

容器工具配置检查

在使用 vLLM Docker 镜像前，需要先安装 mtml 和 mt-container-toolkit，并执行以下命令确保 MUSA 相关环境可以被正确映射进容器：

cd /usr/bin/musa
docker setup "$PWD"

IOMMU 配置检查

内存不小于 256 GB 的 S4000 服务器必须开启 IOMMU。先检查当前状态：

grep -E 'iommu|IOMMU' /proc/cmdline
ls /sys/class/iommu
sudo dmesg | grep -Ei 'DMAR|IOMMU|AMD-Vi'

/sys/class/iommu 下存在设备时，表示 IOMMU 已启用。如果未启用，先在 BIOS 中开启：Intel 平台开启 VT-d，AMD 或海光平台开启 IOMMU/AMD-Vi。然后备份并修改 GRUB：

sudo cp /etc/default/grub /etc/default/grub.bak.$(date +%F)

Intel CPU 执行：

sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT="\(.*\)"/GRUB_CMDLINE_LINUX_DEFAULT="\1 intel_iommu=on iommu.passthrough=0"/' /etc/default/grub

AMD 或海光 CPU 将 intel_iommu=on 替换为 amd_iommu=on。确认参数只出现一次后，更新配置并重启：

sudo update-grub
sudo reboot

重启后重新执行本节开头的检查命令。Intel 平台通常能看到 DMAR: IOMMU enabled；AMD 或海光平台通常能看到 AMD-Vi 和 Interrupt remapping enabled。

进程 / 任务数配置检查

针对全尺寸大参数量模型，比如 DeepSeek模型，如果出现问题 1.6: resource temporarily unavailable 错误，需要检查 systemd 任务数配置：

grep '^DefaultTasksMax=' /etc/systemd/system.conf

如未配置，可编辑 /etc/systemd/system.conf，找到或添加 DefaultTasksMax 参数，并根据需求调整值。例如：

DefaultTasksMax=70%

修改后重载 systemd 配置并重启 Docker：

sudo systemctl daemon-reload
sudo systemctl restart docker

如果使用 k8s 启动服务，还需检查 kubelet 配置：

grep '^podPidsLimit:' /var/lib/kubelet/config.yaml

可根据实际需求调大该值，例如：

podPidsLimit: 65535

修改后重启 kubelet：

sudo systemctl restart kubelet

启动容器

以下示例使用推荐镜像启动容器。请根据实际环境修改模型目录、数据目录、容器名称和镜像标签。

docker run -itd \
  --name vllm-musa-s4000 \
  --net host \
  --privileged \
  --pid=host \
  -e MTHREADS_VISIBLE_DEVICES=all \
  -v /data/llm_models:/data/llm_models \
  -v /data:/data \
  registry.mthreads.com/presale/devtech/vllm-mt:d0930 \
  sleep infinity

如果宿主机 mthreads-gmi 显示 Driver Version 为 5.2.0，将镜像替换为：

registry.mthreads.com/presale/devtech/vllm-mt-0.29-sdk520:d0930

参数说明：

参数	说明
docker run -itd	以交互终端方式在后台启动容器
--name vllm-musa-s4000	指定容器名称，可按需修改
--net host	使用宿主机网络，便于服务端口直接对外暴露
--privileged	使用特权模式，便于容器访问宿主机设备资源
--pid=host	与宿主机共享 PID namespace，便于部分运行时组件识别进程 / 设备状态
-e MTHREADS_VISIBLE_DEVICES=all	指定容器内可见的 MUSA 设备；如需限制设备，请按实际设备编号调整
-v /data/llm_models:/data/llm_models	挂载宿主机模型目录到容器内，可按需修改
-v /data:/data	挂载宿主机数据目录到容器内，可按需修改
registry.mthreads.com/presale/devtech/vllm-mt:d0930	MUSA SDK 4.3.5、宿主机 MUSA Driver 3.3.5 对应的 vLLM-MUSA 镜像
sleep infinity	保持容器运行，便于后续进入容器启动服务

进入容器环境

容器启动后，执行以下命令进入容器：

docker exec -it vllm-musa-s4000 /bin/bash

进入容器后，先验证 GPU 运行时和 vLLM 版本：

musaInfo
vllm --version

musaInfo 应显示 MTT S4000 以及与宿主机匹配的驱动和运行时版本。如果结果不正确，先返回宿主机检查驱动、mtml 和 mt-container-toolkit。如果容器内缺少 libmusa.so，可按宿主机上的实际版本执行：

docker cp /usr/lib/x86_64-linux-gnu/libmusa.so.4.3.5 vllm-musa-s4000:/usr/lib/x86_64-linux-gnu/