常见问题（FAQ）

环境与设备检查

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

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

free -h

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

musaInfo

M1000 统一内存说明

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

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

CreatePlatform failed!

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

1. 使用 root 或 sudo 权限确认 musaInfo 是否正常：

   sudo musaInfo

2. 将当前用户加入 render、video 用户组：

   sudo usermod -aG render,video $USER

3. 重新登录或重启设备后再次验证。

4. 如果仍然报错，设备可能需要连接显示器并进入桌面环境。

找不到 musaInfo

AIBook AIOS 1.5.0 已在系统环境预装 MUSA 和 MUSA SDK。如果找不到 musaInfo，或 musaInfo 无法正常输出，请先确认系统版本是否为 AIOS 1.5.0。

如果系统版本正确但环境检测仍不通过，请联系客户服务或设备提供方确认系统镜像和预装环境。

MUSA 初始化失败

常见报错包括：

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

处理方式：

1. 确认当前用户已加入 render、video 用户组：

   sudo usermod -aG render,video $USER

2. 重新登录或重启设备。

3. 如果设备带桌面环境，连接显示器并解锁桌面；没有安全限制时，可在“设置 -> 用户”中开启自动登录。

运行时库问题

GLIBCXX_3.4.30 not found

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

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

sudo find / -name "libstdc++*"

如果 AIBook AIOS 1.5.0 系统预装环境中出现该问题，请联系客户服务或设备提供方确认系统镜像和预装环境。

CXXABI_1.3.15 not found

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

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

通常是当前进程加载到了版本不匹配的 libstdc++.so.6。AIBook AIOS 1.5.0 使用系统预装环境，如果出现该问题，请联系客户服务或设备提供方确认系统镜像和预装环境。

模型启动与推理问题

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

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

RuntimeError: gated_rms_norm: input/weight dtype mismatch

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

建议处理方式：

1. 优先去掉 --dtype float16，让 vLLM 按模型配置自动选择 dtype。

2. 如仍有问题，可尝试显式指定：

   --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，因此启动失败。

处理方式：

1. 先检查并关闭其他占用显存的进程，尤其是残留的 vLLM、spawn_main 或图形相关进程。
2. 如果确认没有可释放进程，可降低 --gpu_memory_utilization，例如从 0.7 调整为 0.6 后重试。
3. 如果是上一次 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。

处理方式：

1. 优先减小 --max-model-len，例如从 16384 调整为 8192。

2. 如果设置了较大的 --max-num-seqs，建议先降低到 1。

3. 根据上下文长度同步调整 --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。

4. 如果设备空闲显存充足，也可以适当提高 --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 的可扩展内存段配置。

处理方式：

1. 先关闭残留的 vLLM 服务进程组，确认没有其他进程占用显存。

2. 降低运行规格，例如减小 --max-model-len、--num-gpu-blocks-override 或 --gpu_memory_utilization。

3. 如日志提示内存碎片，可在启动服务前增加：

   export PYTORCH_MUSA_ALLOC_CONF=expandable_segments:True

4. 对多模态模型，减少图片分辨率、图片数量或并发数后重试。

通用处理

1. 可先清理缓存后重试：

sudo sh -c "echo 3 > /proc/sys/vm/drop_caches"

2. 如根据上述方法调整启动参数后仍然 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

注意

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 服务进程组，避免只单独杀子进程。

使用 MUSA Graph 时图捕获没有生效

AIBook AIOS 1.5.0 推荐使用 MUSA Graph 启动。启动命令中应包含：

--compilation-config '{"simple_cuda_graph": true, "cudagraph_capture_sizes": [1]}'

同时不要添加：

--enforce-eager

--enforce-eager 会强制使用 eager 模式，导致 MUSA Graph 图捕获无法生效。

多模态模型文本可用，但图片问答结果不符合预期

如果多模态模型可以正常启动并完成文本对话，但简单图片问答结果不符合预期，通常需要区分两类问题：

• 服务链路问题：请求失败、HTTP 状态异常、日志报错、图片输入格式不被接受。
• 模型输出质量问题：请求成功，但模型回答不稳定、漏识别颜色、输出与提示词不完全一致。

建议先使用“服务调用”章节中的本地四色块图片示例确认图片输入链路；如果链路正常，再使用真实业务图片和固定提示词评估多模态质量。