快速开始

本章介绍在容器内运行镜像自带的 Python 与 C++ 示例，验证推理链路。开始前请先完成环境准备。

ONNX Runtime 1.23.0 + ep 镜像

镜像内主要内容

/opt/onnxruntime-musa/
├── VERSION                                        版本与校验信息
├── include/                                       C++ 头文件
├── lib/                                           C++ 运行库
├── onnxruntime-linux-x86_64-1.23.0-release.tgz    C++ 运行库原始压缩包
└── demo/
    ├── python/    run_demo.py · models/
    └── cpp/       main.cc · CMakeLists.txt · build/ort_musa_cpp_demo · models/

Python 接口已安装在系统 Python 3.10 中，可直接 import onnxruntime。

确认版本

cat /opt/onnxruntime-musa/VERSION

cd /tmp
python3 -c "
import onnxruntime as ort
print('version  :', ort.__version__)
print('providers:', ort.get_available_providers())
"

以 S5000 + MUSA SDK 4.3.8 镜像为例，预期输出如下：

ONNXRuntime-MUSA OrtMusaV0.27.7
commit        26d77422
platform      MTT S5000 (x86_64), MUSA SDK 4.3.8

python wheel  onnxruntime_musa-1.23.0+musa.26d77422-cp310-cp310-linux_x86_64.whl
  sha256      eb9c51a59b0808b31eaf64635352421fc1526e202ddad9c5e20b34e68914e0d6
c++ runtime   onnxruntime-linux-x86_64-1.23.0-release.tgz
  sha256      146b35094d6efc775ffc798f78a38b31b11493bd426e6ee5625d62f61a2b8236
version  : 1.23.0+musa.26d77422
providers: ['MUSAExecutionProvider', 'CPUExecutionProvider']

注意：version 为 1.23.0+musa.26d77422，且 providers 中含 MUSAExecutionProvider，才继续。providers 中含 MUSAExecutionProvider 表示 Execution Provider 已加载，不代表模型的全部节点都会在 GPU 上执行，确认方法见模型集成。

镜像内的 C++ 运行库解压自 /opt/onnxruntime-musa 下保留的原始压缩包，可与 VERSION 中的 sha256 核对：

cd /opt/onnxruntime-musa
sha256sum onnxruntime-linux-x86_64-1.23.0-release.tgz

预期输出：

146b35094d6efc775ffc798f78a38b31b11493bd426e6ee5625d62f61a2b8236  onnxruntime-linux-x86_64-1.23.0-release.tgz

运行 Python 示例

cd /opt/onnxruntime-musa/demo/python
python3 run_demo.py --model models/mobilenet_v2_fp16.onnx --device-id 0

注意：启动容器时若指定了 GPU 编号，需要与运行命令中的 --device_id 保持一致。

预期输出：

onnxruntime : 1.23.0+musa.26d77422
providers   : ['MUSAExecutionProvider', 'CPUExecutionProvider']
model       : mobilenet_v2_fp16.onnx
output      : (1, 1000)
inference   : <耗时> ms (mean of 20, after 3 warmup)
PASS: MUSA EP Python inference completed.

注意：以下四项同时满足即表示推理链路已跑通——providers 中含 MUSAExecutionProvider；output 为 (1, 1000)；末行为 PASS: MUSA EP Python inference completed.；输出中没有 EP Error 与 Falling back to ['CPUExecutionProvider'] and retrying. 字样。inference 一行随设备负载波动，仅用于说明输出格式。

出现 EP Error 字样表示 MUSA Execution Provider 加载失败、推理已改在 CPU 上执行，此时末行仍会打印 PASS，不能视为跑通。

运行 C++ 示例

镜像内已预先编译好 C++ 示例，可直接运行：

cd /opt/onnxruntime-musa/demo/cpp
./build/ort_musa_cpp_demo models/mobilenet_v2_fp16.onnx 0

注意：启动容器时若指定了 GPU 编号，需要与运行命令中的第二个参数保持一致。

预期输出：

model     = models/mobilenet_v2_fp16.onnx
device_id = 0
providers : MUSAExecutionProvider CPUExecutionProvider
output    : [1, 1000]
inference : <耗时> ms (mean of 20, after 3 warmup)
PASS: MUSA EP C++ inference completed.

注意：以下三项同时满足即表示链路已跑通——providers 中含 MUSAExecutionProvider；output 为 [1, 1000]；末行为 PASS: MUSA EP C++ inference completed.。

示例源码与 CMakeLists.txt 位于同一目录，可重新编译：

cd /opt/onnxruntime-musa/demo/cpp
cmake -S . -B /tmp/demo_build
cmake --build /tmp/demo_build -j4
/tmp/demo_build/ort_musa_cpp_demo models/mobilenet_v2_fp16.onnx 0

预期输出末行同上。示例的 CMakeLists.txt 直接链接 /opt/onnxruntime-musa 下的运行库，与模型集成中接入自有工程的写法相同。

示例说明

参数	Python 示例	C++ 示例	默认值
模型路径	--model	第一个参数	models/mobilenet_v2_fp16.onnx
GPU 编号	--device-id	第二个参数	0

两个示例都从 session 自动查询第一个输入的名称与形状并构造随机输入，因此更换为单输入、静态 shape、fp32 输入的同类模型时无需修改代码。多输入、动态维度、多输出等情形的适配方式见模型集成。

注意：两个示例中都设置了 prefer_nhwc = 1。该开关的适用性见性能特性开关。

ONNX Runtime 1.26.0 + plugin-ep 镜像

运行 Python 示例

示例一：直接运行镜像已有的 Gemm 推理示例，它会将 MUSA 输出与 CPU 参考结果比较：

# 使用已安装 ORT 主机和 MUSA 插件的 Python
python3 /home/onnxruntime-musa/examples/python/ort_musa_ep_probe.py

# 输出结果参考
registered_ep=MUSAExecutionProvider visible_devices=1
model=/home/onnxruntime-musa/examples/cpp/single_gemm_opset19.onnx
input_X=[[1.0, -2.0, 3.0]]
single_stream_output=[[10.5, 11.5]]
multi_stream_output=verified workers=4 repeats=16
cpu_output=[[10.5, 11.5]]

示例二：运行以下 Python 代码示例，它在内存中构建一个 MatMul 模型，关闭 CPU fallback，并检查实际推理结果：

import numpy as np
import onnx
import onnxruntime as ort
import onnxruntime_musa as musa_ep
from onnx import TensorProto, helper

print("ONNX Runtime:", ort.__version__)

ep_name = musa_ep.get_ep_name()
ort.register_execution_provider_library(ep_name, musa_ep.get_library_path())
devices = [d for d in ort.get_ep_devices() if d.ep_name == ep_name]
if not devices:
    raise RuntimeError("没有发现可用的 MUSA 设备")
print("MUSA 设备数量:", len(devices))

graph = helper.make_graph(
    [helper.make_node("MatMul", ["X", "X"], ["Y"])],
    "musa_matmul",
    [helper.make_tensor_value_info("X", TensorProto.FLOAT, [2, 2])],
    [helper.make_tensor_value_info("Y", TensorProto.FLOAT, [2, 2])],
)
model = helper.make_model(
    graph, opset_imports=[helper.make_opsetid("", 19)], ir_version=9
)
onnx.checker.check_model(model)

options = ort.SessionOptions()
options.add_session_config_entry("session.disable_cpu_ep_fallback", "1")
options.add_provider_for_devices([devices[0]], {})
session = ort.InferenceSession(model.SerializeToString(), sess_options=options)

x = np.array([[1.0, 2.0], [3.0, 4.0]], dtype=np.float32)
y = session.run(None, {"X": x})[0]
np.testing.assert_allclose(y, x @ x, rtol=1e-5, atol=1e-6)
print(y)

预期数值结果为：

# 执行上面的代码示例
python3 MatMul.py
# 预期运行结果
ONNX Runtime: 1.26.0
MUSA 设备数量: 1
[[ 7. 10.]
 [15. 22.]]

运行 C++ 示例

Step 1：设置环境变量

# onnxruntime-musa 源码位于镜像的 /home/onnxruntime-musa 目录
cd /home/onnxruntime-musa

export ORT_ROOT="$PWD/build/ort-sdk/onnxruntime-linux-x64-1.26.0"
export MUSA_PLUGIN_SO="$PWD/build/Release/libonnxruntime_providers_musa_plugin.so"
export LD_LIBRARY_PATH="$ORT_ROOT/lib:/usr/local/musa/lib:/usr/local/musa/lib64:${LD_LIBRARY_PATH:-}"

test -f "$ORT_ROOT/include/onnxruntime_cxx_api.h"
test -f "$ORT_ROOT/lib/libonnxruntime.so"
test -f "$MUSA_PLUGIN_SO"

注意：ORT_ROOT 必须指向标准 ORT C++ SDK 目录，插件和 ORT SDK 使用的 ORT_API_VERSION 必须匹配，当前仓库对应 API version 26。

Step 2：编译 C++ probe

cmake -S examples/cpp -B build/cxx-probe \
  -DORT_ROOT="$ORT_ROOT"
cmake --build build/cxx-probe -j

注意：probe 只链接 libonnxruntime.so，运行时通过插件路径动态加载 libonnxruntime_providers_musa_plugin.so。

Step 3：加载单算子模型进行验证

build/cxx-probe/ort_musa_ep_probe \
  "$MUSA_PLUGIN_SO" \
  "$PWD/examples/cpp/single_gemm_opset19.onnx"

该 probe 会注册 MUSA EP、检查可见 MUSA 设备，并在关闭 CPU fallback 的情况下创建 MUSA-only Session。当前 ort_musa_ep_probe 的模型路径分支只创建 Session，没有准备输入并调用 Session::Run()；因此这一步验证的是插件加载、设备发现和模型 Session 创建。

成功时应看到类似输出：

registered_ep=MUSAExecutionProvider visible_devices=1
session_created model=/home/onnxruntime-musa/examples/cpp/single_gemm_opset19.onnx