ORTモデル形式

内容

ORTモデル形式とは何ですか？

ORT形式は、縮小サイズのONNX Runtimeビルドでサポートされている形式です。縮小サイズのビルドは、モバイルやWebアプリケーションなどのサイズに制約のある環境での使用に適している場合があります。

ORT形式モデルとONNXモデルの両方が、完全なONNX Runtimeビルドでサポートされています。

下位互換性

一般的に、目標は、特定のバージョンのONNX Runtimeが、ONNX Runtimeリリースの時点で現在または古いバージョンのORT形式のモデルを実行できることです。

下位互換性を維持しようと努めていますが、いくつかの破壊的変更がありました。

ONNX Runtimeバージョン	ORT形式バージョンサポート	注意
1.14+	v5, v4 (限定サポート)	v4の限定サポートの詳細については、こちらを参照してください。
1.13	v5	v5の破壊的変更：カーネル定義ハッシュを削除しました。
1.12-1.8	v4	v4の破壊的変更：カーネル定義ハッシュの計算を更新しました。
1.7	v3, v2, v1
1.6	v2, v1
1.5	v1	ORT形式が導入されました

ONNXモデルをORT形式に変換する

ONNXモデルは、convert_onnx_models_to_ortスクリプトを使用してORT形式に変換されます。

変換スクリプトは2つの機能を実行します。

ONNX形式のモデルをロードして最適化し、ORT形式で保存します
必要に応じて、最適化されたモデルに必要な演算子、およびオプションでデータ型を決定し、これらを構成ファイルに保存して、縮小演算子ビルドで使用します。

変換スクリプトは、単一のONNXモデルまたはディレクトリに対して実行できます。ディレクトリに対して実行すると、ディレクトリは変換する「.onnx」ファイルを再帰的に検索します。

各「.onnx」ファイルはロード、最適化され、元の「.onnx」ファイルと同じ場所に「.ort」拡張子のファイルとしてORT形式で保存されます。

スクリプトの出力

ONNXモデルごとに1つのORT形式モデル
最適化されたONNXモデルに必要な演算子を含むビルド構成ファイル（‘required_operators.config’）。

型削減が有効になっている場合（ONNX Runtimeバージョン1.7以降）、構成ファイルには各演算子に必要な型も含まれ、「required_operators_and_types.config」という名前になります。

ビルド済みのONNX Runtime iOS、Android、またはwebパッケージを使用している場合、ビルド構成ファイルは使用されず、無視できます。

スクリプトの場所

ORTモデル形式は、ONNX Runtimeのバージョン1.5.2以降でサポートされています。

ONNX形式モデルからORT形式への変換では、モデルがONNX Runtimeにロードされ、変換プロセスの一部として最適化されるため、ONNX Runtime pythonパッケージを利用します。

ONNX Runtimeバージョン1.8以降では、変換スクリプトはONNX Runtime pythonパッケージから直接実行されます。

以前のバージョンでは、変換スクリプトはローカルのONNX Runtimeリポジトリから実行されます。

ONNX Runtimeのインストール

モデルをONNX形式から内部ORT形式に変換するには、https://pypi.org/project/onnxruntime/からonnxruntime pythonパッケージをインストールします。バージョン1.5.3以降が必要です。

以前のリリースのインストール

ソースからONNX Runtimeをビルドする場合（カスタム、縮小、または最小ビルド）、チェックアウトしたONNX Runtimeリポジトリのブランチにpythonパッケージのバージョンを一致させる必要があります。

たとえば、1.7リリースを使用するには：

git checkout rel-1.7.2
pip install onnxruntime==1.7.2

gitリポジトリでmainブランチを使用している場合は、ナイトリーONNX Runtime pythonパッケージを使用する必要があります。

pip install -U -i https://test.pypi.org/simple/ ort-nightly

ONNXモデルをORT形式に変換するスクリプトの使用法

ONNX Runtimeバージョン1.8以降：

python -m onnxruntime.tools.convert_onnx_models_to_ort <onnx model file or dir>

ここで：

onnx model file or dirは、.onnxファイルまたは1つ以上の.onnxモデルを含むディレクトリへのパスです。

現在のオプション引数は、--help引数を付けてスクリプトを実行することで利用できます。サポートされている引数とデフォルトは、ONNX Runtimeのバージョンによって若干異なります。

ONNX Runtime 1.11のヘルプテキスト：

python -m onnxruntime.tools.convert_onnx_models_to_ort --help

  usage: convert_onnx_models_to_ort.py [-h] [--optimization_style {Fixed,Runtime} [{Fixed,Runtime} ...]] [--enable_type_reduction] [--custom_op_library CUSTOM_OP_LIBRARY] [--save_optimized_onnx_model] [--allow_conversion_failures] [--nnapi_partitioning_stop_ops NNAPI_PARTITIONING_STOP_OPS]
                                      [--target_platform {arm,amd64}]
                                      model_path_or_dir

  指定されたディレクトリのONNX形式のモデルをORT形式のモデルに変換します。.onnx拡張子を持つすべてのファイルが処理されます。各ファイルに対して、同じディレクトリにORT形式のモデルが作成されます。また、変換されたすべてのモデルに必要な演算子のリストを含む構成ファイルも作成されます。この構成ファイルは、--include_ops_by_configパラメータを介して最小ビルドへの入力として使用する必要があります。

  位置引数：
    model_path_or_dir     変換するONNXモデルまたはONNXモデルを含むディレクトリへのパスを指定します。.onnx拡張子を持つすべてのファイル（サブディレクトリ内のファイルを含む）が処理されます。

  オプション引数：
    -h, --help            このヘルプメッセージを表示して終了します
    --optimization_style {Fixed,Runtime} [{Fixed,Runtime} ...]
                          ORT形式モデルで実行する最適化のスタイル。複数の値を指定できます。変換は値ごとに1回実行されます。一般的なガイダンスは、NNAPIまたはCoreMLを使用する場合は「Runtime」スタイルで最適化されたモデルを使用し、それ以外の場合は「Fixed」スタイルを使用することです。「Fixed」：ORT形式モデルを保存する直前に最適化を実行します。これにより、プラットフォーム固有の最適化が組み込まれます。「Runtime」：基本的な最適化を直接実行し、可能であれば実行時に適用される特定の他の最適化を保存します。これは、NNAPIやCoreMLのようなコンパイルEPを使用する場合に役立ちます。コンパイルEPは、（モデル変換時に）未知の数のノードを実行する可能性があります。保存された最適化は、実行時にコンパイルEPに割り当てられていないノードをさらに最適化できます。
    --enable_type_reduction
                          構成ファイルに演算子固有の型情報を追加して、個々の演算子実装でサポートされる型を潜在的に削減します。
    --custom_op_library CUSTOM_OP_LIBRARY
                          登録するカスタム演算子カーネルを含む共有ライブラリへのパスを指定します。
    --save_optimized_onnx_model
                          各ONNXモデルの最適化されたバージョンを保存します。これは、ORT形式モデルと同じレベルの最適化が適用されます。
    --allow_conversion_failures
                          モデル変換の失敗が発生した後も続行するかどうか。
    --nnapi_partitioning_stop_ops NNAPI_PARTITIONING_STOP_OPS
                          NNAPI EP分割停止演算子のリストを指定します。特に、「ep.nnapi.partitioning_stop_ops」セッションオプション構成エントリの値を指定します。
    --target_platform {arm,amd64}
                          エクスポートされたモデルが使用されるターゲットプラットフォームを指定します。このパラメータは、プラットフォーム固有のオプション（QDQIsInt8Allowed(arm)、NCHWc (amd64)、NHWC (arm/amd64)形式、さまざまなオプティマイザレベルオプションなど）を選択するために使用できます。

オプションのスクリプト引数

最適化スタイル

ONNX Runtime 1.11以降

変換されたモデルが完全に最適化される（「Fixed」）か、保存されたランタイム最適化を持つ（「Runtime」）かを指定します。デフォルトでは両方のタイプのモデルが生成されます。詳細については、こちらを参照してください。

これは、以前のONNX Runtimeバージョンの最適化レベルオプションを置き換えます。

最適化レベル

ONNX Runtimeバージョン1.10以前

ORT形式で保存する前にモデルを最適化するためにONNX Runtimeが使用する最適化レベルを設定します。

ONNX Runtimeバージョン1.8以降では、モデルがCPU EPで実行される場合はallを推奨します。

以前のバージョンでは、allレベルには以前はモデルの移植性を制限するデバイス固有の最適化が含まれていたため、extendedを推奨します。

モデルがNNAPI EPまたはCoreML EPで実行される場合は、basic最適化レベルを使用してORT形式モデルを作成することをお勧めします。このモデルをNNAPIまたはCoreML EPを有効にして実行する場合と、CPU EPを使用してより高いレベルに最適化されたモデルを実行する場合のパフォーマンスを比較するために、パフォーマンステストを実行して最適な設定を決定する必要があります。

詳細については、モバイルシナリオのパフォーマンスチューニングのドキュメントを参照してください。

型削減を有効にする

ONNX Runtimeバージョン1.7以降では、ビルドサイズをさらに削減するために、必要な演算子がサポートするデータ型を制限することが可能です。このプルーニングは、このドキュメントでは「演算子型削減」と呼ばれます。ONNXモデルが変換されると、各演算子に必要な入力および出力データ型が蓄積され、構成ファイルに含まれます。

演算子型削減を有効にする場合は、Flatbuffers pythonパッケージをインストールする必要があります。

pip install flatbuffers

たとえば、SoftmaxのONNX Runtimeカーネルはfloatとdoubleの両方をサポートしています。モデルがSoftmaxを使用しているが、floatデータのみを使用している場合、doubleをサポートする実装を除外して、カーネルのバイナリサイズを削減できます。

カスタム演算子のサポート

ONNXモデルがカスタム演算子を使用している場合、ONNXモデルを正常にロードできるように、カスタム演算子カーネルを含むライブラリへのパスを指定する必要があります。カスタム演算子はORT形式モデルに保持されます。

最適化されたONNXモデルを保存する

このフラグを追加して、最適化されたONNXモデルを保存します。最適化されたONNXモデルには、ORT形式モデルと同じノードと初期化子が含まれており、デバッグとパフォーマンスチューニングのためにNetronで表示できます。

以前のバージョンのONNX Runtime

ONNX Runtimeバージョン1.7より前では、モデル変換スクリプトはクローンされたソースリポジトリから実行する必要があります。

python <ONNX Runtimeリポジトリルート>/tools/python/convert_onnx_models_to_ort.py <onnxモデルファイルまたはディレクトリ>

ORT形式でモデルをロードして実行する

ORT形式モデルを実行するためのAPIは、ONNXモデルと同じです。

個々のAPIの使用法の詳細については、ONNX Runtime APIドキュメントを参照してください。

プラットフォーム別のAPI

プラットフォーム	利用可能なAPI
Android	C, C++, Java, Kotlin
iOS	C, C++, Objective-C (Swiftブリッジ経由)
Web	JavaScript

ORT形式モデルのロード

ORT形式モデルのファイル名を指定すると、「.ort」のファイル拡張子はORT形式モデルであると推測されます。

ORT形式モデルのインメモリバイトを指定すると、それらのバイト内のマーカーがチェックされ、ORT形式モデルであるかどうかが判断されます。

InferenceSession入力がORT形式モデルであることを明示的に指定したい場合は、SessionOptionsを介して行うことができますが、通常はこれは必要ありません。

ファイルパスからORT形式モデルをロードする

C++ API

Ort::SessionOptions session_options;
session_options.AddConfigEntry("session.load_model_format", "ORT");

Ort::Env env;
Ort::Session session(env, <モデルへのパス>, session_options);

Java API

SessionOptions session_options = new SessionOptions();
session_options.addConfigEntry("session.load_model_format", "ORT");

OrtEnvironment env = OrtEnvironment.getEnvironment();
OrtSession session = env.createSession(<モデルへのパス>, session_options);

JavaScript API

import * as ort from "onnxruntime-web";

const session = await ort.InferenceSession.create("<モデルへのパス>");

インメモリバイト配列からORT形式モデルをロードする

ORT形式モデルデータを含む入力バイト配列を使用してセッションが作成された場合、デフォルトでは、モデルバイトバッファが有効であることを保証するために、セッション作成時にモデルバイトをコピーします。

session.use_ort_model_bytes_directlyを1に設定することで、モデルバイトを直接使用するオプションを有効にすることもできます。これにより、ONNX Runtime Mobileのピークメモリ使用量が削減される場合がありますが、ORTセッションの存続期間中、モデルバイトが有効であることを保証する必要があります。ONNX Runtime Webの場合、このオプションはデフォルトで設定されています。

session.use_ort_model_bytes_directlyが有効になっている場合、初期化子にモデルバイトを直接使用してピークメモリ使用量をさらに削減するオプションもあります。これを有効にするには、セッションオプション構成エントリsession.use_ort_model_bytes_for_initializersを1に設定します。初期化子が事前にパックされると、その初期化子に対してモデルバイトを直接使用することによるピークメモリ使用量の節約が元に戻されることに注意してください。これは、事前にパックされたデータ用に新しいバッファを割り当てる必要があるためです。事前パッキングは、現在のプラットフォームに最適な順序に初期化子レイアウトを変更するオプションのパフォーマンス最適化です。ピークメモリ使用量の削減が潜在的なパフォーマンス最適化よりも重要な場合は、session.disable_prepackingを1に設定することで事前パッキングを無効にできます。

C++ API

Ort::SessionOptions session_options;
session_options.AddConfigEntry("session.load_model_format", "ORT");
session_options.AddConfigEntry("session.use_ort_model_bytes_directly", "1");

std::ifstream stream(<モデルへのパス>, std::ios::in | std::ios::binary);
std::vector<uint8_t> model_bytes((std::istreambuf_iterator<char>(stream)), std::istreambuf_iterator<char>());

Ort::Env env;
Ort::Session session(env, model_bytes.data(), model_bytes.size(), session_options);

Java API

SessionOptions session_options = new SessionOptions();
session_options.addConfigEntry("session.load_model_format", "ORT");
session_options.addConfigEntry("session.use_ort_model_bytes_directly", "1");

byte[] model_bytes = Files.readAllBytes(Paths.get(<モデルへのパス>));

OrtEnvironment env = OrtEnvironment.getEnvironment();
OrtSession session = env.createSession(model_bytes, session_options);

JavaScript API

import * as ort from "onnxruntime-web";

const response = await fetch(modelUrl);
const arrayBuffer = await response.arrayBuffer();
model_bytes = new Uint8Array(arrayBuffer);

const session = await ort.InferenceSession.create(model_bytes);

ORTモデル形式

ORTモデル形式

内容