ONNX Runtime React Native 端到端测试中的 MNIST 模型准备opset 升级与 ORT 格式转换实战【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntimeMNIST 手写数字识别是 ONNX Runtime 各语言绑定中最经典的入门模型。在 ONNX Runtime 仓库的 React Native 端到端e2e测试工程中mnist.readme.md位于 js/react_native/e2e/src/mnist.readme.md用两条命令精确记录了测试模型的生产流程先把仓库自带的mnist.onnx升级到 opset 15再通过 ONNX Runtime 官方 Python 工具链转换为 ORT 格式模型.ort供 Android 与 JS 侧测试加载。阅读本文后你将掌握update_onnx_opset与convert_onnx_models_to_ort两个工具的使用方法、关键参数语义及其底层实现能够独立复现 React Native 端到端测试所需的全部模型资产。MNIST 测试图片一、模型资产的来源与最终形态在进入命令之前先理清这份文档所描述的模型资产链路。React Native e2e 测试工程位于js/react_native/e2e其模型相关文件分布在两处文件相对仓库根目录的路径用途源模型onnxruntime/test/testdata/mnist.onnxONNX Runtime 测试数据集中自带的原始 MNIST 模型升级后的 ONNX 模型js/react_native/e2e/src/mnist.onnx由源模型升级到 opset 15 后的 ONNX 模型ORT 格式模型JS 侧js/react_native/e2e/src/mnist.ort供 RN 测试代码加载的 ORT 格式模型ORT 格式模型Android 侧js/react_native/e2e/android/app/src/main/assets/mnist.ort打包进 Android App 静态资源的 ORT 格式模型从目录结构可以推断Android 侧的assets目录中已经实际放置了mnist.ort及一批测试模型说明该文档描述的命令正是 e2e 测试工程构建模型资产的标准流程而js/react_native/e2e/src/目录下同时保留mnist.onnx与mnist.ort则是为了兼顾查看模型结构Netron 可直接打开 ONNX与运行时加载 ORT 格式两种场景。二、第一步使用update_onnx_opset将模型升级到 opset 152.1 命令原文文档给出的升级命令如下注意命令在仓库根目录下的js/子目录中执行cd repo root/js python -m onnxruntime.tools.update_onnx_opset --opset 15 ../onnxruntime/test/testdata/mnist.onnx ./react_native/e2e/src/mnist.onnx命令的四个组成部分分别是python -m onnxruntime.tools.update_onnx_opset以模块方式调用 ONNX Runtime Python 包中的工具脚本其实现位于 tools/python/util/update_onnx_opset.py--opset 15指定目标 opset 版本为 15。该参数在脚本中声明为requiredFalse, default15即即使省略此参数也会默认升级到 opset 15显式写出更有利于流程可读性第一个位置参数input_model待升级的输入模型路径即测试数据集中的../onnxruntime/test/testdata/mnist.onnx第二个位置参数output_model升级结果的输出路径即./react_native/e2e/src/mnist.onnx。2.2 底层实现ONNX version_converter 与 opset 升级约束update_onnx_opset的命令行入口非常薄真正的逻辑在onnx_model_utils模块中。对应源码 tools/python/util/onnx_model_utils.py 的update_onnx_opset函数其核心调用链如下model onnx.load(model_path_str) new_model version_converter.convert_version(model, opset) if out_path: onnx.save(new_model, str(out_path))三个关键细节值得注意依赖官方onnx包opset 转换复用 ONNX 官方 Python 包的onnx.version_converter.convert_version属于标准 ONNX 工具链能力ONNX Runtime 只是提供了便捷的命令行封装opset 只能升不能降脚本的 argparsedescription明确写明 New opset must be later than the existing one即目标 opset 必须大于模型当前 opset转换是单向的。对mnist.onnx这类经典测试模型其原始 opset 通常低于 15因此升级到 15 是合法操作子图一并处理同一文件中的iterate_graph_per_node_func/iterate_graph_per_graph_func工具函数会递归遍历Scan、Loop、If等控制流节点的子图说明这套工具链对包含子图的模型同样适用虽然 MNIST 模型本身并不涉及。2.3 升级之后升级完成后js/react_native/e2e/src/mnist.onnx即为 opset 15 的 ONNX 模型。需要说明的是升级只是调整算子集的版本声明并尽可能做算子等价转换并不会改变模型的推理语义真正带来运行时收益的是下一步的 ORT 格式转换。三、第二步使用convert_onnx_models_to_ort转换为 ORT 格式3.1 命令原文文档给出了两条几乎相同的转换命令区别仅在输出目录cd repo root/js python -m onnxruntime.tools.convert_onnx_models_to_ort --optimization_styleFixed --output_dir ./react_native/e2e/android/app/src/main/assets ./react_native/e2e/src/mnist.onnx python -m onnxruntime.tools.convert_onnx_models_to_ort --optimization_styleFixed --output_dir ./react_native/e2e/src ./react_native/e2e/src/mnist.onnx两条命令都完成了三件事加载./react_native/e2e/src/mnist.onnx上一步升级后的模型以Fixed优化风格执行图优化将结果序列化为.ort格式模型写入--output_dir。第一条把mnist.ort写入 Android 的assets目录js/react_native/e2e/android/app/src/main/assets/mnist.ort第二条写入 JS 源码目录js/react_native/e2e/src/mnist.ort两份文件内容一致、分属不同的加载入口。3.2 参数语义详解根据 tools/python/util/convert_onnx_models_to_ort.py 的 argparse 定义与本文相关的参数及默认值如下--optimization_style可选Fixed与Runtime默认同时包含两者default[Fixed, Runtime]因此显式指定Fixed可以避免多生成一份Runtime风格的模型。其语义为Fixed在保存 ORT 格式模型之前直接执行全部图优化并固化进模型任何平台特定优化都会烘焙进文件。这是通用场景如 CPU 上的 React Native 推理的推荐选择Runtime仅执行基础优化把部分优化以待重放形式保存运行时再按需应用适用于 NNAPI、CoreML 这类编译型 Execution ProviderEP——转换时无法预知有多少节点会被 EP 接管。帮助文本明确指出使用 NNAPI/CoreML 时优先选Runtime其余情况用Fixed--output_dir转换产物输出目录缺省时输出到与输入模型相同的目录model_path_or_dir位置参数单个 ONNX 模型路径或包含多个.onnx的目录。工具会递归处理目录下所有.onnx文件并自动忽略*.optimized.onnx避免重复转换上一次运行的中间产物其他可选参数本文命令未使用供进阶参考--enable_type_reduction在配置文件中加入算子类型信息以进一步裁剪构建体积、--custom_op_library注册自定义算子库、--save_optimized_onnx_model额外输出同名.optimized.onnx便于 Netron 查看、--allow_conversion_failures遇错继续、--target_platformarm/amd64。3.3 底层实现一次 InferenceSession 创建完成转换转换的实现思路非常巧妙——它不写任何独立的序列化器而是复用 ONNX Runtime 自身的会话创建流程见 tools/python/util/convert_onnx_models_to_ort.pyso ort.SessionOptions() so.optimized_model_filepath str(ort_target_path) so.graph_optimization_level optimization_level so.add_session_config_entry(session.save_model_format, ORT) _ ort.InferenceSession(str(model), sess_optionsso, providersproviders, ...)即通过SessionOptions.optimized_model_filepath指定输出路径再通过会话配置项session.save_model_formatORT指定输出格式为 ORT 格式随后创建一次 CPU 推理会话图优化与序列化便在一次会话初始化中完成。结合源码还可以看到几个面向移动端的重要细节优化级别默认为allconvert_onnx_models_to_ort中优化级别通过环境变量ORT_CONVERT_ONNX_MODELS_TO_ORT_OPTIMIZATION_LEVEL读取默认值为all对应ORT_ENABLE_ALLARM 平台自动排除 NCHWc 优化当优化级别达到layout/all且target_platform ! amd64时工具会自动把NchwcTransformer加入disabled_optimizers因为 NCHWc 布局变换不适用于 ARM 设备、且会生成设备相关的模型React Native 的典型目标正是 ARM 手机自动生成算子配置文件转换完成后工具还会根据产物生成required_operators_all.config之类的配置文件--enable_type_reduction时名为required_operators_and_types_all.config供后续通过--include_ops_by_config做最小化构建使用。这为将 e2e 模型资产复用为按需裁剪的输入提供了直接通路。3.4 ORT 格式的价值.ort是 ONNX Runtime 的原生序列化格式基于 FlatBuffers相比 ONNX 格式模型已预先完成图优化、算子/类型信息可按需裁剪因而加载更快、包体更小、启动时不再需要重复执行优化流程。这正是移动端 e2e 测试选择以.ort资产作为运行时加载对象的原因。四、模型在 React Native e2e 测试中的实际使用模型资产准备好之后是如何被测试代码消费的答案在 js/react_native/e2e/src/MNISTTest.tsx 中。该组件演示了onnxruntime-react-native的两种会话创建方式// 方式一通过文件路径创建 const modelPath await MNIST.getLocalModelPath(); const pathSession: InferenceSession await InferenceSession.create(modelPath); // 方式二通过字节数组创建读取 base64 后解码 const base64Str await readFile(modelPath, base64); const bytes Buffer.from(base64Str, base64); const session: InferenceSession await InferenceSession.create(bytes);组件挂载时先以路径方式创建会话并立即release()验证可用性再以字节方式创建正式会话随后从原生模块MNISTDataHandler对应 js/react_native/e2e/src/mnist-data-handler.ts 中声明的接口获取测试图片路径与本地模型路径执行预处理、session.run()推理与后处理最终把识别结果显示在界面上组件卸载时调用session.release()释放资源。e2e 测试正是借助这段链路用mnist.ort模型与3.jpg图片验证 React Native 绑定的完整推理通路。五、完整流程复盘与注意事项把整条链路串起来一份可复现的模型准备流程为# 1. 进入 js 目录以下命令均在此目录执行 cd repo root/js # 2. 将测试数据集中的 mnist.onnx 升级到 opset 15 python -m onnxruntime.tools.update_onnx_opset --opset 15 \ ../onnxruntime/test/testdata/mnist.onnx \ ./react_native/e2e/src/mnist.onnx # 3. 转换为 ORT 格式分别输出到 Android assets 与 JS 源码目录 python -m onnxruntime.tools.convert_onnx_models_to_ort --optimization_styleFixed \ --output_dir ./react_native/e2e/android/app/src/main/assets \ ./react_native/e2e/src/mnist.onnx python -m onnxruntime.tools.convert_onnx_models_to_ort --optimization_styleFixed \ --output_dir ./react_native/e2e/src \ ./react_native/e2e/src/mnist.onnx实践中的几个关键注意点工作目录两条命令都要求以仓库js/目录为当前工作目录其内部相对路径../onnxruntime/...、./react_native/...均以此为基准切勿在仓库根目录直接执行前置依赖需要已安装含onnxruntime.tools的 ONNX Runtime Python 包onnx、onnxruntime为必需依赖onnx_model_utils.py顶部import onnx/import onnxruntime可见opset 单向约束--opset只能大于模型当前 opset若源模型已是 opset 15可跳过升级步骤直接转换风格选择面向 CPU 推理的 React Native 场景使用Fixed即可若后续接入 NNAPI/CoreML 编译型 EP则应改用Runtime风格并注意仅在可信模型上开启session.enable_saved_runtime_optimizations产物同步Android 侧的mnist.ort必须位于android/app/src/main/assets/否则 App 打包时不会携带该资源测试将因模型文件缺失而失败。这套源模型 → opset 升级 → ORT 格式转换 → 分目录部署的流程不仅适用于 MNIST也完全适用于 React Native e2e 工程中其他测试模型如test_types_*.onnx/.ort可作为为移动端准备 ONNX Runtime 测试与发布模型资产的标准操作模板。【免费下载链接】onnxruntimeONNX Runtime: cross-platform, high performance ML inferencing and training accelerator项目地址: https://gitcode.com/GitHub_Trending/on/onnxruntime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考