常见问题（FAQ）
容器与设备
MUSAExecutionProvider 不在 providers 列表中
运行以下命令
ls /dev/mtgpu*
无输出或报 No such file or directory 时，在宿主机检查默认的容器运行时是否已设为 mthreads。若不是，先根据 mt-container-toolkit 文档进行安装设置。
报 initialization error 或 status: 3
与上一条同因：容器内不存在 /dev/mtgpu* 设备节点。按上一条处理。
若设备节点存在、仍报 MUSA call failed: initialization error，请确认容器以 root 用户运行。镜像默认用户为 root；以 --user 指定非 root 用户启动时，该用户可能没有 GPU 设备节点的访问权限。
指定的 GPU 没有生效
GPU 由创建容器时的 MTHREADS_VISIBLE_DEVICES 变量决定，进入容器后再修改无效。只使用一张卡时，程序中的 device_id 应与该变量值保持一致。
安装与导入
以下问题与 Python 接口的安装和导入有关。
组件版本号和镜像相关信息不匹配
环境中存在其他 ONNX Runtime 版本并被优先加载，常见于用户目录（user-site）中安装过其他版本。该情况不产生任何报错，但实际运行的是另一个引擎。
cd /tmp
python3 -c "import onnxruntime as ort; print(ort.__version__); print(ort.__file__)"
__file__ 若落在 ~/.local/lib/python3.10/site-packages/ 下即可确认。临时确认可加 PYTHONNOUSERSITE=1 重跑上述命令；彻底处理需卸载用户目录中的版本。
libmusart.so.x: cannot open shared object file
容器环境的 MUSA SDK 和宿主机驱动版本不匹配，或者 mt-container-toolkit 版本低于 2.2.0。
ModuleNotFoundError: No module named 'onnxruntime.capi'
在包含 onnxruntime 同名目录的路径下执行 Python 导致导入路径冲突。切换到其他目录后重试：
cd /tmp
python3 -c "import onnxruntime as ort; print(ort.__version__)"
推理过程
模型输出全零或数值异常，但没有任何报错
按模型集成的精度验证方法，对同一模型、同一输入分别使用 CPUExecutionProvider 与 MUSAExecutionProvider 执行并对比输出。
若验证不通过，请按本页末尾的方式采集信息并联系摩尔线程技术支持，同时提供模型输入输出的 name、shape、dtype。
providers 中有 MUSA，但推理速度接近 CPU
Execution Provider 已加载，但模型中部分节点由引擎改用 CPU 执行。按模型集成中禁用 CPU 回退的方法定位无法在 GPU 上执行的节点。
更换为自研模型后输入报错
快速开始中的示例是单输入、fp32 输入的模板。多输入、fp16 输入输出、动态维度等情形按模型集成中的适配表修改。
IOBinding 下更新输入后输出不变
见模型集成中的 IOBinding 使用约束。
技术支持
反馈问题时请提供以下信息。第一条在宿主机执行：
mthreads-gmi
其余在容器内执行：
cat /opt/onnxruntime-musa/VERSION
ls -l /usr/local/musa
grep -m1 -A1 musa_toolkits /usr/local/musa/version.json
ls /dev/mtgpu*
cd /tmp && python3 -c "import onnxruntime as o; print(o.__version__); print(o.__file__); print(o.get_available_providers())"
以及 Execution Provider 的依赖解析情况：
cd /tmp
ORT_MUSA_PROVIDER="$(python3 -c 'import onnxruntime, os; print(os.path.dirname(onnxruntime.__file__))')/capi/libonnxruntime_providers_musa.so"
ldd "$ORT_MUSA_PROVIDER" | grep -E "musart|mudnn|mublas|not found"
输出会列出若干行 MUSA 相关的依赖库，开头几行形如：
libmusart.so.4 => /usr/local/musa/lib/libmusart.so.4 (0x...)
libmudnn.so.3 => /usr/local/musa/lib/libmudnn.so.3 (0x...)
libmublas.so.1 => /usr/local/musa/lib/libmublas.so.1 (0x...)
注意：行数与具体条目随 MUSA SDK 版本不同，无需逐行核对。判断依据是输出中不出现 not found，且各库均解析到 /usr/local/musa/lib 下。
另请一并提供：宿主机驱动与 mt-container-toolkit 版本、完整的运行输出、ONNX 模型输入输出的 name、shape 与 dtype。
