环境准备
环境依赖
| 组件 | 版本要求 |
|---|---|
| MUSA driver | 3.3.5 |
| mtml | 2.1.1-linux-R_amd64 |
| mt-container-toolkit | 2.1.0-1_amd64 |
以上为依赖组件推荐版本，安装方式如下：
- （推荐）通过 MUSA-Deploy 工具一键安装。
- 通过官网下载对应软件包，然后依照文档指示通过软件管理工具（如
dpkg）安装：
环境检测
基础配置检查
执行以下命令检查 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 SDK / driver 是否正确安装。
容器工具配置检查
在使用 vLLM Docker 镜像前，需要先安装 mtml 和 mt-container-toolkit，并执行以下命令确保 MUSA 相关环境可以被正确映射进容器：
cd /usr/bin/musa
docker setup "$PWD"
IOMMU 配置检查
如启动服务时报错并提示 IOMMU 相关问题，可检查 /etc/default/grub 中是否包含以下配置：
grep '^GRUB_CMDLINE_LINUX_DEFAULT=' /etc/default/grub
需要确保配置中包含以下参数：
intel_iommu=on iommu.passthrough=0 pci=disable_acs_redir=pci:1000:c030
修改后需执行：
sudo update-grub
sudo reboot
进程 / 任务数配置检查
针对全尺寸大参数量模型，比如 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_musa:s4000_4.3.5_d0708 \
/bin/bash
参数说明：
| 参数 | 说明 |
|---|---|
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_musa:s4000_4.3.5_d0708 | vLLM-MUSA 0.21 版本镜像 |
/bin/bash | 容器启动后执行的命令 |
进入容器环境
容器启动后，执行以下命令进入容器：
docker exec -it vllm-musa-s4000 /bin/bash
进入容器后，可执行以下命令验证 vLLM-MUSA 是否正确安装：
vllm --version
