常见问题（FAQ）

环境与设备检查

如何查看内存 / 显存占用？

推荐优先使用 free -h 查看系统统一内存占用：

free -h

free -h 输出示例

也可以使用 musaInfo 查看 MUSA 设备侧信息：

musaInfo

musaInfo 正常输出示例

M1000 统一内存说明

M1000 是 SoC 统一内存形态，free 看到的是系统统一内存视角，musaInfo 或 mthreads-gmi 看到的是 MUSA 设备侧视角。

排查模型加载和推理峰值时，建议优先关注模型启动前后和请求期间的内存增量，例如“模型加载增量”和“请求峰值增量”。

`CreatePlatform failed!`

如果执行 MUSA 相关命令时报 CreatePlatform failed!，按以下顺序检查：

使用 root 或 sudo 权限确认 musaInfo 是否正常：
```
sudo musaInfo
```
将当前用户加入 render、video 用户组：
```
sudo usermod -aG render,video $USER
```
重新登录或重启设备后再次验证。
如果仍然报错，设备可能需要连接显示器并进入桌面环境。

找不到 `musaInfo`

先补充 MUSA 的可执行文件和库路径：

export PATH=/usr/local/musa/bin:${PATH}
export LD_LIBRARY_PATH=/usr/local/musa/lib:${LD_LIBRARY_PATH}

如果补充 PATH 后仍找不到 musaInfo，通常说明 musa-sdk 没有正确安装。建议清理旧目录后重新安装 musa-sdk：

sudo rm -rf /usr/local/musa*

然后按照“环境准备与部署”章节重新安装 musa-sdk。

MUSA 初始化失败

常见报错包括：

RuntimeError: MUSA error: initialization error
RuntimeError: MUSA driver initialization failed, you might not have a Mthreads GPU

处理方式：

确认当前用户已加入 render、video 用户组：
```
sudo usermod -aG render,video $USER
```
重新登录或重启设备。
如果设备带桌面环境，连接显示器并解锁桌面；没有安全限制时，可在“设置 -> 用户”中开启自动登录。

运行时库问题

`GLIBCXX_3.4.30 not found`

原因：系统或 conda 环境中存在多个 libstdc++ 版本，当前进程加载到了版本较低的运行时库。

可以先查看系统里的 libstdc++：

sudo find / -name "libstdc++*"

建议在 conda 环境中安装新版运行时库：

conda install -c conda-forge libstdcxx-ng libgcc-ng

`CXXABI_1.3.15 not found`

如果启动 vLLM、导入 sqlite3 或加载相关 Python 模块时出现类似错误：

ImportError: /lib/aarch64-linux-gnu/libstdc++.so.6: version `CXXABI_1.3.15' not found

通常是当前进程优先加载了系统 /lib/aarch64-linux-gnu/libstdc++.so.6，而不是 conda 环境中的新版 libstdc++.so.6。

建议在 AIModule 1.4.1 的 v1.4.1 环境中显式指定 conda 运行时库路径：

source /home/dev/miniforge3/etc/profile.d/conda.sh
conda activate v1.4.1
export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"
python -c "import sqlite3; print('sqlite3 ok')"

如果环境中缺少新版运行时库，可先安装：

conda install -c conda-forge libstdcxx-ng libgcc-ng

确认 sqlite3 ok 后，再启动 vLLM 服务。若需要长期生效，可将下面内容写入 conda 环境激活脚本：

export LD_LIBRARY_PATH="$CONDA_PREFIX/lib:$LD_LIBRARY_PATH"

tip

LD_LIBRARY_PATH 中的 $CONDA_PREFIX/lib 需要在 conda activate v1.4.1 之后设置，否则 CONDA_PREFIX 可能为空。

模型启动与推理问题

Qwen3.5 模型启动时报 `gated_rms_norm dtype mismatch`

如果 Qwen3.5 系列模型启动时报类似错误：

RuntimeError: gated_rms_norm: input/weight dtype mismatch

通常是启动时显式指定了 --dtype float16，但模型中部分权重或算子路径使用 bfloat16，导致 dtype 不一致。

建议处理方式：

优先去掉 --dtype float16，让 vLLM 按模型配置自动选择 dtype。
如仍有问题，可尝试显式指定：
```
--dtype bfloat16
```

`Engine process failed to start`

常见报错如下：

RuntimeError: Engine process failed to start. See stack trace for the root cause.
There appear to be 1 leaked semaphore objects to clean up at shutdown

建议先查看 vLLM 服务日志中的根因。如果日志没有明确可处理的错误，优先重启设备后重试：

sudo reboot

OOM / 内存不足

常见现象包括模型启动失败、请求过程中进程退出、日志中出现 OOM、KV Cache block 不足或启动前空闲显存不足。不同报错对应的处理方式略有区别，建议先根据日志中的关键信息定位类型。

启动前空闲显存不足

典型报错如下：

ValueError: Free memory on device (19.97/31.03 GiB) on startup is less than desired GPU memory utilization (0.7, 21.72 GiB).

表示设备启动前的空闲显存低于 --gpu_memory_utilization 期望预留的显存。以上示例中设备总显存约 31.03 GiB，--gpu_memory_utilization 0.7 需要约 21.72 GiB，但实际空闲只有 19.97 GiB，因此启动失败。

处理方式：

先检查并关闭其他占用显存的进程，尤其是残留的 vLLM、spawn_main 或图形相关进程。
如果确认没有可释放进程，可降低 --gpu_memory_utilization，例如从 0.7 调整为 0.6 后重试。
如果是上一次 vLLM 服务退出后仍有残留占用，参考下方“vLLM 进程退出后仍有内存占用残留”处理。

KV Cache 不足

典型报错如下：

ValueError: To serve at least one request with the models's max seq len (16384), (1.50 GiB) KV cache is needed, which is larger than the available KV cache memory (1.32 GiB).

表示当前配置下，可用于 KV Cache 的显存不足以支撑 --max-model-len 设置的最大上下文长度。上例中 max seq len 为 16384，至少需要 1.50 GiB KV Cache，但实际可用 KV Cache 只有 1.32 GiB。

处理方式：

优先减小 --max-model-len，例如从 16384 调整为 8192。
如果设置了较大的 --max-num-seqs，建议先降低到 1。
根据上下文长度同步调整 --num-gpu-blocks-override。两者需要满足：
```
max-model-len <= num-gpu-blocks-override * block_size / max-num-seqs
```
例如 block_size=32、max-num-seqs=1、num-gpu-blocks-override=512 时，理论上 max-model-len 不应超过 16384。
如果设备空闲显存充足，也可以适当提高 --gpu_memory_utilization 后重试；如果启动前空闲显存不足，不建议继续提高该参数。

运行时 MUSA OOM

典型报错如下：

MUSA out of memory. Tried to allocate 34.00 MiB. GPU 0 has a total capacity of 14.95 GiB of which 96.94 MiB is free.

表示模型加载或请求执行过程中再次申请显存失败。此时通常是显存已经接近用满，也可能存在内存碎片。日志中如果出现 reserved by PyTorch but unallocated，可尝试开启 PyTorch MUSA 的可扩展内存段配置。

处理方式：

先关闭残留的 vLLM 服务进程组，确认没有其他进程占用显存。
降低运行规格，例如减小 --max-model-len、--num-gpu-blocks-override 或 --gpu_memory_utilization。
如日志提示内存碎片，可在启动服务前增加：
```
export PYTORCH_MUSA_ALLOC_CONF=expandable_segments:True
```
对多模态模型，减少图片分辨率、图片数量或并发数后重试。

通用处理

可先清理缓存后重试：

export TRITON_CACHE_DIR="/tmp/triton"
sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"

如根据上述方法调整启动参数后仍然 OOM，可尝试开启 swap 分区：

# 先把当前所有分区都关闭了
swapoff -a
# 创建要作为 Swap 分区文件
dd if=/dev/zero of=/var/swapfile bs=1G count=16
# 建立 Swap 的文件系统
mkswap /var/swapfile
# 启用 Swap 分区
swapon /var/swapfile
# 查看 Linux 当前分区
free -m
# 清理cache
sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"

vLLM 进程退出后仍有内存占用残留

vLLM 服务进程被杀掉后仍看到内存占用残留，是已知现象。常见原因是只杀掉了某个子进程，而 launcher、spawn_main 等同一进程组内的相关进程仍未完全退出。

建议按端口找到 vLLM 服务的 launcher 进程，再杀掉整个进程组。下面以端口 32104 为例，实际使用时请替换为你的服务端口：

LAUNCHER_PID=$(lsof -ti :32104)
PGID=$(ps -o pgid= -p $LAUNCHER_PID | tr -d ' ')
kill -9 -- -$PGID

warning

kill -9 -- -$PGID 会杀掉该进程组内的全部进程。执行前请确认 LAUNCHER_PID 和 PGID 对应的是需要关闭的 vLLM 服务。

执行后等待 2 秒，检查 vLLM 相关进程和内存释放情况：

sleep 2
ps -ef | grep -E "vllm|spawn_main|start.sh" | grep -v grep
free -h

如果仍有残留进程，继续确认它是否属于同一个 vLLM 服务进程组，避免只单独杀子进程。

环境与设备检查​

如何查看内存 / 显存占用？​

CreatePlatform failed!​

找不到 musaInfo​

MUSA 初始化失败​

运行时库问题​

GLIBCXX_3.4.30 not found​

CXXABI_1.3.15 not found​

模型启动与推理问题​

Qwen3.5 模型启动时报 gated_rms_norm dtype mismatch​

Engine process failed to start​

OOM / 内存不足​

启动前空闲显存不足​

KV Cache 不足​

运行时 MUSA OOM​

通用处理​

vLLM 进程退出后仍有内存占用残留​

这篇文章对您有帮助吗？

环境与设备检查

如何查看内存 / 显存占用？

`CreatePlatform failed!`

找不到 `musaInfo`

MUSA 初始化失败

运行时库问题

`GLIBCXX_3.4.30 not found`

`CXXABI_1.3.15 not found`

模型启动与推理问题

Qwen3.5 模型启动时报 `gated_rms_norm dtype mismatch`

`Engine process failed to start`

OOM / 内存不足

启动前空闲显存不足

KV Cache 不足

运行时 MUSA OOM

通用处理

vLLM 进程退出后仍有内存占用残留