コンテンツにスキップ
日昇 Docs

RKNN-Toolkit2モデル変換API説明

1.API詳細説明

1.1 RKNN初期化および解放

RKNN-Toolkit2のすべてのAPIを使用する場合、まずRKNN()メソッドを呼び出してRKNNオブジェクトを初期化する必要があります。このオブジェクトを使用しなくなった場合は、release()メソッドを呼び出して解放します。

RKNNオブジェクトの初期化時には、verboseおよびverbose_fileパラメータを設定し、詳細なログ情報を出力できます。verboseは詳細ログを出力するかどうかを指定します。verbose_fileを設定し、かつverboseがTrueの場合、ログ情報は指定したファイルにも書き込まれます。

例：

# 詳細ログを出力する
from rknn.api import RKNN
rknn = RKNN(verbose=True)
# ...
rknn.release()

1.2 モデル設定

RKNNモデルを構築する前に、モデルに対してチャンネル平均値、量子化画像のRGB2BGR変換、量子化タイプなどを設定する必要があります。これらの操作はconfigインターフェースで設定できます。

項目内容
APIconfig
説明モデル変換パラメータを設定します。
パラメータ以下の各パラメータを参照してください。
戻り値なし。

configパラメータ詳細

パラメータ説明
mean_values入力の平均値です。パラメータ形式はリストであり、リストには1つまたは複数の平均値サブリストを含めます。複数入力モデルでは、各入力に対応する複数のサブリストを指定します。各サブリストの長さは該当入力のチャンネル数と一致する必要があります。例：[[128,128,128]] は、1つの入力の3チャンネル値から128を減算することを表します。デフォルト値はNoneであり、すべてのmean値が0であることを示します。
std_values入力の正規化値です。パラメータ形式はリストであり、リストには1つまたは複数の正規化値サブリストを含めます。複数入力モデルでは、各入力に対応する複数のサブリストを指定します。各サブリストの長さは該当入力のチャンネル数と一致する必要があります。例：[[128,128,128]] は、1つの入力の3チャンネル値について、平均値を減算した後さらに128で除算することを表します。デフォルト値はNoneであり、すべてのstd値が1であることを示します。
quant_img_RGB2BGR量子化画像を読み込む際に、先にRGB2BGR処理を行うかどうかを示します。入力が複数ある場合は、[True, True, False] のようにリストで指定します。この設定は一般にCaffeモデルで使用されます。Caffeモデルの学習時には、多くの場合データセット画像に対してRGB2BGR変換を行うため、この場合はこの設定をTrueにします。なお、この設定は量子化画像形式がjpg/png/bmpの場合にのみ有効で、npy形式の読み込み時には無視されます。そのため、モデル入力がBGRである場合、npyデータもBGR形式で用意する必要があります。この設定は量子化段階（buildインターフェース）で量子化画像を読み込む場合、または量子化精度分析（accuracy_analysisインターフェース）でのみ使用され、最終的なRKNNモデルには保存されません。したがって、モデル入力がBGRの場合、toolkit2のinferenceまたはC-APIのrun関数を呼び出す前に、渡す画像データもBGR形式であることを保証する必要があります。
quantized_dtype量子化タイプです。現在サポートされる量子化タイプは w8a8、w4a16、w8a16、w4a8、w16a16i、w16a16i_dfp です。デフォルト値はw8a8です。
- w8a8：重みは8bit非対称量子化精度、活性値は8bit非対称量子化精度です。（RK2118は非対応）
- w4a16：重みは4bit非対称量子化精度、活性値は16bit浮動小数点精度です。（RK3576/RV1126Bのみ対応）
- w8a16：重みは8bit非対称量子化精度、活性値は16bit浮動小数点精度です。（RK3562のみ対応）
- w4a8：重みは4bit非対称量子化精度、活性値は8bit非対称量子化精度です。（現在未対応）
- w16a16i：重みは16bit非対称量子化精度、活性値は16bit非対称量子化精度です。（RV1103/RV1106のみ対応）
- w16a16i_dfp：重みは16bit動的固定小数点量子化精度、活性値は16bit動的固定小数点量子化精度です。（RV1103/RV1106のみ対応）
quantized_algorithm各層の量子化パラメータを計算する際に使用する量子化アルゴリズムです。現在サポートされる量子化アルゴリズムは normal、mmse、kl_divergence、gdq です。デフォルト値はnormalです。normal量子化アルゴリズムは速度が速いことが特徴で、推奨される量子化データセット量は一般に20～100枚程度です。より多いデータセットを使用しても精度が必ずしもさらに向上するとは限りません。mmse量子化アルゴリズムは総当たり反復方式を採用するため速度は遅いですが、通常normalより高い精度が得られます。推奨される量子化データセット量は一般に20～50枚程度で、ユーザーは必要に応じて量子化データセット量を適宜増減できます。kl_divergence量子化アルゴリズムはnormalより時間がかかりますが、mmseよりは大幅に少なく、feature分布が不均一な場面では良好な改善効果が得られる場合があります。推奨される量子化データセット量は一般に20～100枚程度です。gdq量子化アルゴリズムはw4a16およびw8a16でのみ有効で、w4a16およびw8a16の重み量子化精度を効果的に向上できます。推奨される量子化データセット量は200枚以上です。
quantized_method現在サポートされる方式は layer、channel、または group{SIZE} です。デフォルト値はchannelです。
- layer：各層のweightに対して1セットのみ量子化パラメータを持ちます。
- channel：各層のweightの各出力チャンネルごとに1セットの量子化パラメータを持ちます。通常、channelはlayerより高い精度になります。
- group{SIZE}：channelを基礎として、各出力チャンネルのweightを入力チャンネル方向でさらに{SIZE}単位の複数グループへ分割し、各グループが個別の量子化パラメータを持ちます。通常、group{SIZE}はchannelより高い精度になります。{SIZE}は32～256の間の32の倍数で、例としてgroup32またはgroup128があります。現在、group{SIZE}はquantized_dtypeがw4a16の場合にのみ有効です。
float_dtype非量子化の場合に使用する浮動小数点データ型を指定します。現在サポートされるデータ型はfloat16です。デフォルト値はfloat16です。
optimization_levelモデル最適化レベルです。デフォルト値は3です。この値を変更することで、モデル変換過程で使用される一部またはすべての最適化規則を無効化できます。デフォルト値3ではすべての最適化オプションが有効です。値を2または1に設定すると、モデル精度に影響を与える可能性のある一部の最適化オプションが無効になります。値を0に設定すると、すべての最適化オプションが無効になります。
target_platformRKNNモデルをどのターゲットチッププラットフォーム向けに生成するかを指定します。現在 “rv1103”、“rv1103b”、“rv1106”、“rv1106b”、“rv1126b”、“rk2118”、“rk3562”、“rk3566”、“rk3568”、“rk3576”、“rk3588” などをサポートします。このパラメータは大文字小文字を区別しません。デフォルト値はNoneです。
custom_stringRKNNモデルにユーザー定義の文字列情報を追加します。runtime時にqueryでこの情報を取得できるため、異なるRKNNモデルに応じた特殊処理をデプロイ時に行いやすくなります。デフォルト値はNoneです。
remove_weightconvなどのweightを除去し、RKNNの従属モデルを生成します。この従属モデルは完全なweightを持つRKNNモデルとweightを共有でき、メモリ消費を削減できます。デフォルト値はFalseです。
compress_weightモデルweightを圧縮し、RKNNモデルサイズを削減できます。デフォルト値はFalseです。
single_core_mode単一コアモデルのみを生成するかどうかを指定します。RKNNモデルサイズとメモリ消費を削減できます。デフォルト値はFalseです。現在RK3588 / RK3576にのみ有効です。
model_pruningモデルに対してロスレス枝刈りを行います。weightが疎なモデルでは、変換後のRKNNモデルサイズと計算量を削減できます。デフォルト値はFalseです。
op_targetOPの具体的な実行対象（NPU/CPU/GPUなどで実行するか）を指定します。出力tensor名を用いる方式では、{‘op0_output_name’:‘cpu’, ‘op1_output_name’:‘npu’, …} のように指定します。また、op_typeを指定する方式では、{‘op_type’:‘cpu’, …} のように指定できます。さらに、{‘op_type’:‘cpu’, ‘op0_output_name’:‘npu’, …} のような混在指定もサポートします。デフォルト値はNoneです。‘op0_output_name’および’op1_output_name’は対応するOPの出力tensor名であり、精度分析（accuracy_analysis）機能の結果から取得できます。指定値はそのtensorに対応するOPの実行対象がCPUまたはNPUであることを表します。現在選択可能な値は ‘cpu’ / ‘npu’ / ‘gpu’ / ‘auto’ で、‘auto’は実行対象を自動選択します。op_typeを指定する場合も精度分析結果から取得する必要があり、モデル内のすべての該当op_typeの実行対象をCPUまたはNPUに設定できます。例：{‘Add’:‘cpu’, ‘Expand’:‘cpu’, …}。
dynamic_inputユーザーが指定した複数組の入力shapeに基づき、動的入力を模擬する機能です。形式は [[input0_shapeA, input1_shapeA, …], [input0_shapeB, input1_shapeB, …], …] です。デフォルト値はNoneで、実験的機能です。例えば、元のモデル入力が1つでshapeが[1,3,224,224]の場合、または元のモデル入力shape自体が動的で、[1,3,height,width]または[1,3,-1,-1]のようなshapeである場合に、このモデルで3種類の入力shape [1,3,224,224]、[1,3,192,192]、[1,3,160,160] をサポートさせたい場合、dynamic_input=[[[1,3,224,224]], [[1,3,192,192]], [[1,3,160,160]]] と設定できます。RKNNモデルに変換後、推論時には対応するshapeの入力データを渡す必要があります。
注：
1. この機能を有効にするには、元のモデル自体が動的入力をサポートしている必要があります。そうでない場合はエラーになります。
2. 元のモデル入力shape自体が動的である場合、動的な軸のみ異なる値を設定できます。
quantize_weightbuildインターフェースのdo_quantizationがFalseの場合に、一部のweightを量子化してRKNNモデルサイズを削減します。デフォルト値はFalseです。
remove_reshapeモデルの入力および出力に存在する可能性のあるReshape OPを削除し、モデル実行時性能を向上させます（現在多くのプラットフォームではReshapeがCPU上で実行されるため）。デフォルト値はFalseです。
注：有効にすると、モデルの入力または出力ノードのshapeが変更される可能性があります。変換過程のwarning表示を注意深く確認し、デプロイ時にも入力および出力shapeの変化を考慮する必要があります。
sparse_inferすでに疎化されたモデルに対して疎化推論を行い、推論性能を向上させます。現在RK3576/RV1126Bにのみ有効です。デフォルト値はFalseです。
enable_flash_attentionFlash Attentionを有効にするかどうかを指定します。デフォルト値はFalseです。
注：FlashAttentionは https://arxiv.org/abs/2307.08691 に基づいて実装されており、高速キャッシュ内ループによって高速化し、帯域幅使用を削減します。ただし、モデルサイズが大きくなるため、モデルに応じて有効化するかどうかを選択してください。詳細は “RKNN Compiler Support Operator List” の exSDPAttention 説明を参照してください。
auto_hybrid_cos_threshモデル量子化時に自動混合量子化を有効にする際の余弦距離しきい値です。デフォルト値は0.98です。
auto_hybrid_euc_threshモデル量子化時に自動混合量子化を有効にする際のユークリッド距離しきい値です。デフォルト値はNoneで、デフォルトでは有効になりません。

例：

# model config
rknn.config(mean_values=[[103.94, 116.78, 123.68]],
            std_values=[[58.82, 58.82, 58.82]],
            quant_img_RGB2BGR=True,
            target_platform='rk3566')

1.3 モデル読み込み

RKNN-Toolkit2は現在、Caffe、TensorFlow、TensorFlow Lite、ONNX、DarkNet、PyTorchなどのモデル読み込みおよび変換に対応しています。これらのモデルを読み込む際は、それぞれ対応するインターフェースを呼び出す必要があります。以下に各インターフェースを説明します。

1.3.1 Caffeモデル読み込みインターフェース

項目内容
APIload_caffe
説明Caffeモデルを読み込みます。（ARM64版ではこのインターフェースは現在未対応）
パラメータmodel：Caffeモデルファイル（.prototxt拡張子）のパス。
blobs：Caffeモデルのバイナリデータファイル（.caffemodel拡張子）のパス。
input_name：Caffeモデルが複数入力の場合、このパラメータで入力層名の順序を指定できます。形式は[‘input1’,‘input2’,‘input3’]です。名前はモデル入力名と一致する必要があります。デフォルト値はNoneで、Caffeモデルファイル（.prototxt）に基づいて自動的に指定されます。
戻り値0：インポート成功。
-1：インポート失敗。

例：

# 現在のパスからmobilenet_v2モデルを読み込む
ret = rknn.load_caffe(model='./mobilenet_v2.prototxt',
                      blobs='./mobilenet_v2.caffemodel')

1.3.2 TensorFlowモデル読み込みインターフェース

項目内容
APIload_tensorflow
説明TensorFlowモデルを読み込みます。（ARM64版ではこのインターフェースは現在未対応）
パラメータtf_pb：TensorFlowモデルファイル（.pb拡張子）のパス。
inputs：モデルの入力ノード（tensor名）。複数入力ノードをサポートします。すべての入力ノード名を1つのリストに入れます。
input_size_list：各入力ノードに対応するshapeです。すべての入力shapeを1つのリストに入れます。例のssd_mobilenet_v1モデルでは、入力ノードに対応する入力shapeは[[1, 300, 300, 3]]です。
outputs：モデルの出力ノード（tensor名）。複数出力ノードをサポートします。すべての出力ノード名を1つのリストに入れます。
input_is_nchw：モデル入力のlayoutがすでにNCHWかどうかを示します。デフォルト値はFalseで、デフォルト入力layoutはNHWCです。
戻り値0：インポート成功。
-1：インポート失敗。

例：

# 現在のディレクトリからssd_mobilenet_v1_coco_2017_11_17モデルを読み込む
ret = rknn.load_tensorflow(tf_pb='./ssd_mobilenet_v1_coco_2017_11_17.pb',
                           inputs=['Preprocessor/sub'],
                           outputs=['concat', 'concat_1'],
                           input_size_list=[[300, 300, 3]])

1.3.3 TensorFlow Liteモデル読み込みインターフェース

項目内容
APIload_tflite
説明TensorFlow Liteモデルを読み込みます。（ARM64版ではこのインターフェースは現在未対応）
パラメータmodel：TensorFlow Liteモデルファイル（.tflite拡張子）のパス。
input_is_nchw：モデル入力のlayoutがすでにNCHWかどうかを示します。デフォルト値はFalseで、デフォルト入力layoutはNHWCです。
戻り値0：インポート成功。
-1：インポート失敗。

例：

# 現在のディレクトリからmobilenet_v1モデルを読み込む
ret = rknn.load_tflite(model='./mobilenet_v1.tflite')

1.3.4 ONNXモデル読み込み

項目内容
APIload_onnx
説明ONNXモデルを読み込みます。
パラメータmodel：ONNXモデルファイル（.onnx拡張子）のパス。
inputs：モデル入力ノード（tensor名）。複数入力ノードをサポートし、すべての入力ノード名を1つのリストに入れます。デフォルト値はNoneで、モデルから取得します。
input_size_list：各入力ノードに対応するshapeです。すべての入力shapeを1つのリストに入れます。inputsを設定する場合は、input_size_listも設定する必要があります。デフォルト値はNoneです。
input_initial_val：モデル入力の初期値を設定します。形式はndarrayのリストです。デフォルト値はNoneです。主に一部の入力を定数に固定するために使用します。定数に固定しない入力はNoneに設定できます。例：[None, np.array([1])]。
outputs：モデルの出力ノード（tensor名）。複数出力ノードをサポートし、すべての出力ノード名を1つのリストに入れます。デフォルト値はNoneで、モデルから取得します。
戻り値0：インポート成功。
-1：インポート失敗。

例：

# 現在のディレクトリからarcfaceモデルを読み込む
ret = rknn.load_onnx(model='./arcface.onnx')

1.3.5 DarkNetモデル読み込みインターフェース

項目内容
APIload_darknet
説明DarkNetモデルを読み込みます。（ARM64版ではこのインターフェースは現在未対応）
パラメータmodel：DarkNetモデルファイル（.cfg拡張子）のパス。
weight：重みファイル（.weights拡張子）のパス。
戻り値0：インポート成功。
-1：インポート失敗。

例：

# 現在のディレクトリからyolov3-tinyモデルを読み込む
ret = rknn.load_darknet(model='./yolov3-tiny.cfg',
                        weight='./yolov3.weights')

1.3.6 PyTorchモデル読み込みインターフェース

項目内容
APIload_pytorch
説明PyTorchモデルを読み込みます。量子化意識学習（QAT）モデルにも対応しますが、torchのバージョンを1.9.0以上へ更新する必要があります。
パラメータmodel：PyTorchモデルファイル（.pt拡張子）のパスです。torchscript形式のモデルである必要があります。
input_size_list：各入力ノードに対応するshapeです。すべての入力shapeを1つのリストに入れます。
戻り値0：インポート成功。
-1：インポート失敗。

例：

# 現在のディレクトリからresnet18モデルを読み込む
ret = rknn.load_pytorch(model='./resnet18.pt',
                        input_size_list=[[1,3,224,224]])

1.4 RKNNモデルの構築

項目内容
APIbuild
説明RKNNモデルを構築します。
パラメータdo_quantization：モデルを量子化するかどうかを指定します。デフォルト値はTrueです。
dataset：量子化校正に使用するデータセットです。現在テキストファイル形式をサポートします。ユーザーは校正に使用する画像（jpgまたはpng形式）またはnpyファイルのパスを.txtファイルに記述できます。テキストファイルでは1行に1つのパスを記述します。例：
a.jpg
b.jpg
または
a.npy
b.npy
複数入力の場合は、各入力に対応するファイルをスペースで区切ります。例：
a.jpg a2.jpg
b.jpg b2.jpg
または
a.npy a2.npy
b.npy b2.npy
注：量子化画像は、予測シーンに比較的近い画像を選択することを推奨します。
rknn_batch_size：モデル入力のBatchパラメータ調整です。デフォルト値はNoneで、調整しないことを示します。1より大きい場合、1回の推論で複数フレームの入力画像または入力データを同時に推論できます。例えばMobileNetモデルの元のinput次元が[1, 224, 224, 3]、output次元が[1, 1001]の場合、rknn_batch_sizeを4に設定すると、input次元は[4,224,224,3]、output次元は[4,1001]になります。
注：
1. rknn_batch_sizeはNPUマルチコアプラットフォームでのみ性能向上（コア利用率向上）が期待できます。そのため、rknn_batch_sizeの値はコア数と一致させることを推奨します。
2. rknn_batch_sizeを変更すると、モデルのinput/outputのshapeが変更されます。inferenceでモデルを推論する場合は、対応するinputサイズを設定する必要があり、後処理時にも返却されたoutputsを処理する必要があります。
auto_hybrid：自動混合量子化を有効にし、精度またはオーバーフローを調整するかどうかを指定します。デフォルト値はFalseで、調整しないことを示します。モデルを量子化する場合、自動混合量子化を有効にすると、指定したしきい値より低い余弦距離/ユークリッド距離のopをfp16計算へ変換します（現在w8a8量子化でのみ対応）。モデルを量子化しない場合、自動混合量子化を有効にすると、fp16の数値範囲を超えるopをint16計算へ変換します。
注：
1. 余弦距離およびユークリッド距離のしきい値は、configインターフェースのauto_hybrid_cos_threshおよびauto_hybrid_euc_threshで設定できます。
戻り値0：構築成功。
-1：構築失敗。

例：

# RKNNモデルを構築し、量子化を行う
ret = rknn.build(do_quantization=True, dataset='./dataset.txt')

1.5 RKNNモデルのエクスポート

本ツールで構築したRKNNモデルは、このインターフェースによりRKNNモデルファイルとしてエクスポートし、モデルデプロイに使用できます。

項目内容
APIexport_rknn
説明RKNNモデルを指定ファイル（.rknn拡張子）に保存します。
パラメータexport_path：エクスポートするモデルファイルのパス。
戻り値0：エクスポート成功。
-1：エクスポート失敗。

例：

# 構築済みRKNNモデルを現在のパスのmobilenet_v1.rknnファイルに保存する
ret = rknn.export_rknn(export_path='./mobilenet_v1.rknn')

1.6 RKNNモデルの読み込み

項目内容
APIload_rknn
説明RKNNモデルを読み込みます。RKNNモデルを読み込んだ後は、モデル設定、モデル読み込み、RKNNモデル構築の手順は不要です。また、読み込み後のモデルはNPUハードウェアに接続して推論または性能データ取得などを行う場合に限定され、シミュレータや精度分析には使用できません。
パラメータpath：RKNNモデルファイルのパス。
戻り値0：読み込み成功。
-1：読み込み失敗。

例：

# 現在のパスからmobilenet_v1.rknnモデルを読み込む
ret = rknn.load_rknn(path='./mobilenet_v1.rknn')

1.7 ランタイム環境の初期化

モデル推論または性能評価の前に、必ずランタイム環境を初期化し、モデルの実行プラットフォーム（具体的なターゲットハードウェアプラットフォームまたはソフトウェアシミュレータ）を明確にする必要があります。

項目内容
APIinit_runtime
説明ランタイム環境を初期化します。
パラメータtarget：ターゲットハードウェアプラットフォームです。“rv1103”、“rv1103b”、“rv1106”、“rv1106b”、“rv1126b”、“rk3562”、“rk3566”、“rk3568”、“rk3576”、“rk3588” をサポートします。デフォルト値はNoneで、PC上でツールを使用する場合、モデルはシミュレータ上で実行されます。注：targetをNoneに設定する場合、モデルをシミュレータ上で実行するには先にbuildまたはhybrid_quantizationインターフェースを呼び出す必要があります。
device_id：デバイス番号です。PCに複数のデバイスが接続されている場合、このパラメータを指定する必要があります。デバイス番号はlist_devicesインターフェースで確認できます。デフォルト値はNoneです。
perf_debug：性能評価時にdebugモードを有効にするかどうかを指定します。debugモードでは各層の実行時間を取得できます。有効でない場合はモデル全体の実行時間のみ取得できます。デフォルト値はFalseです。
eval_mem：メモリ評価モードに入るかどうかを指定します。メモリ評価モードに入ると、eval_memoryインターフェースでモデル実行時のメモリ使用状況を取得できます。デフォルト値はFalseです。
async_mode：非同期モードを使用するかどうかを指定します。デフォルト値はFalseです。推論インターフェース呼び出し時には、入力画像設定、モデル推論、推論結果取得の3段階があります。非同期モードを有効にすると、現在フレームの入力設定と前フレームの推論を同時に実行できます。そのため、最初のフレームを除き、以降の各フレームで入力設定時間を隠蔽し、性能を向上できます。非同期モードでは、毎回返される推論結果は前フレームの結果です。（現在バージョンではこのパラメータは未対応）
core_mask：ランタイム時のNPUコアを設定します。対応プラットフォームはRK3588 / RK3576で、設定は以下のとおりです。
RKNN.NPU_CORE_AUTO：モデルを自動スケジューリングし、現在空いているNPUコアで自動実行します。
RKNN.NPU_CORE_0：NPU0コア上で実行します。
RKNN.NPU_CORE_1：NPU1コア上で実行します。
RKNN.NPU_CORE_2：NPU2コア上で実行します。
RKNN.NPU_CORE_0_1：NPU0およびNPU1コア上で同時実行します。
RKNN.NPU_CORE_0_1_2：NPU0、NPU1、NPU2コア上で同時実行します。
RKNN.NPU_CORE_ALL：プラットフォームに基づいてNPUコア数を自動設定します。デフォルト値はRKNN.NPU_CORE_AUTOです。
注：RK3576には2コアしかないため、NPU_CORE_2およびNPU_CORE_0_1_2は設定できません。
fallback_prior_device：OPがNPU仕様を超えた場合のfallback優先順位を設定します。現在 “cpu” または “gpu” をサポートします。“gpu” はGPUハードウェアが存在するプラットフォームでのみ有効です。デフォルト値は “cpu” です。
戻り値0：ランタイム環境初期化成功。
-1：ランタイム環境初期化失敗。

例：

# ランタイム環境を初期化する
ret = rknn.init_runtime(target='rk3566')

1.8 モデル推論

モデル推論を行う前に、必ず1つのRKNNモデルを構築または読み込む必要があります。

項目内容
APIinference
説明現在のモデルに対して推論を行い、推論結果を返します。ランタイム環境初期化時にtargetをRockchip NPUデバイスに設定している場合、ハードウェアプラットフォーム上の推論結果が得られます。targetを設定していない場合は、シミュレータ上の推論結果が得られます。
パラメータinputs：推論対象入力リストで、形式はndarrayです。
data_format：入力データのlayoutリストで、“nchw”または“nhwc”を指定します。4次元入力にのみ有効です。デフォルト値はNoneで、すべての入力layoutがNHWCであることを示します。
inputs_pass_through：入力の透過リストです。デフォルト値はNoneで、すべての入力が透過しないことを示します。非透過モードでは、入力をNPUドライバへ渡す前に、ツールが平均値減算や標準偏差除算などを行います。透過モードではこれらの処理を行わず、入力を直接NPUへ渡します。このパラメータ値はリストです。例えばinput0を透過し、input1を透過しない場合、値は[1, 0]です。
戻り値results：推論結果で、型はndarray listです。

分類モデル（mobilenet_v1など）の例：

# モデルを使用して画像を推論し、TOP5結果を取得する
outputs = rknn.inference(inputs=[img])
show_outputs(outputs)

出力されるTOP5結果の例：

-----TOP 5-----
[ 156] score:0.928223 class:"Shih-Tzu"
[ 155] score:0.063171 class:"Pekinese, Pekingese, Peke"
[ 205] score:0.004299 class:"Lhasa, Lhasa apso"
[ 284] score:0.003096 class:"Persian cat"
[ 285] score:0.000171 class:"Siamese cat, Siamese

1.9 モデル性能評価

項目内容
APIeval_perf
説明モデル性能を評価します。モデルはPCに接続されたRV1103 / RV1103B / RV1106 / RV1106B / RV1126B / RK3562 / RK3566 / RK3568 / RK3576 / RK3588上で実行する必要があります。init_runtimeでランタイム環境を初期化する際にperf_debugをFalseに設定した場合、ハードウェア上でのモデル全体実行時間が得られます。perf_debugをTrueに設定した場合、全体時間に加えて各層の耗時情報も返されます。
パラメータis_print：性能情報を出力するかどうか。デフォルト値はTrueです。
fix_freq：ハードウェアデバイスの周波数を固定するかどうか。デフォルト値はTrueです。
戻り値perf_result：性能情報（文字列）。

例：

# モデル性能を評価する
perf_detail = rknn.eval_perf()

1.10 メモリ使用状況の取得

項目内容
APIeval_memory
説明モデルがハードウェアプラットフォーム上で実行される際のメモリ使用状況を取得します。モデルはPCに接続されたRV1103 / RV1103B / RV1106 / RV1106B / RV1126B / RK3562 / RK3566 / RK3568 / RK3576 / RK3588上で実行する必要があります。
パラメータis_print：メモリ使用状況を規定フォーマットで出力するかどうか。デフォルト値はTrueです。
戻り値memory_detail：メモリ使用状況で、型は辞書です。メモリ使用状況は下記の形式で辞書に格納されます。
{
‘weight_memory’: 3698688,
‘internal_memory’: 1756160,
‘other_memory’: 484352,
‘total_memory’: 5939200,
}
‘weight_memory’ フィールドはランタイム時のモデルweightのメモリ占有を表します。
‘internal_memory’ フィールドはランタイム時のモデル中間tensorメモリ占有を表します。
‘other_memory’ フィールドはランタイム時のその他メモリ占有を表します。
‘total_model_allocation’ はランタイム時の総メモリ占有を表し、weight、中間tensor、その他メモリ占有の合計です。

例：

# モデルのメモリ使用状況を評価する
memory_detail = rknn.eval_memory()

examples/caffe/mobilenet_v2をRK3588上で実行した場合のメモリ占有例：

======================================================
Memory Profile Info Dump
======================================================
NPU model memory detail(bytes):
Weight Memory: 3.53 MiB
Internal Tensor Memory: 1.67 MiB
Other Memory: 473.00 KiB
Total Memory: 5.66 MiB


INFO: When evaluating memory usage, we need consider
      the size of model, current model size is: 4.09 MiB
======================================================

1.11 SDKバージョンの照会

項目内容
APIget_sdk_version
説明SDK APIおよびドライバのバージョン番号を取得します。注：このインターフェースを使用する前に、モデル読み込みとランタイム環境初期化を完了している必要があります。また、このインターフェースはハードウェアプラットフォームRV1103 / RV1103B / RV1106 / RV1106B / RV1126B / RK3562 / RK3566 / RK3568 / RK3576 / RK3588上でのみ使用できます。
パラメータなし。
戻り値sdk_version：APIおよびドライバのバージョン情報。型は文字列です。

例：

# SDKバージョン情報を取得する
sdk_version = rknn.get_sdk_version()
print(sdk_version)

返されるSDK情報例：

==============================================
RKNN VERSION:
API: 1.5.2 (8babfea build@2023-08-25T02:31:12)
DRV: rknn_server: 1.5.2 (8babfea build@2023-08-25T10:30:12)
DRV: rknnrt: 1.5.3b13 (42cbca6f5@2023-10-27T10:13:21)
==============================================

1.12 ハイブリッド量子化

1.12.1 hybrid_quantization_step1

ハイブリッド量子化機能を使用する場合、第一段階で呼び出す主要インターフェースはhybrid_quantization_step1です。このインターフェースは一時モデルファイル（<model_name>.model）、データファイル（<model_name>.data）、量子化設定ファイル（<model_name>.quantization.cfg）を生成します。

項目内容
APIhybrid_quantization_step1
説明読み込まれた元モデルに基づいて、対応する一時モデルファイル、設定ファイル、量子化設定ファイルを生成します。
パラメータdataset：1.4「RKNNモデルの構築」のdataset説明を参照してください。
rknn_batch_size：1.4「RKNNモデルの構築」のrknn_batch_size説明を参照してください。
proposal：ハイブリッド量子化の設定推奨値を生成します。デフォルト値はFalseです。
proposal_dataset_size：proposalで使用するdatasetの枚数です。デフォルト値は1です。proposal機能は比較的時間がかかるため、デフォルトではdataset内の最初の1枚のみを使用します。
custom_hybrid：ユーザーが指定した複数組の入力名と出力名に基づき、混合量子化対象サブグラフを選択します。形式は[[input0_name, output0_name], [input1_name, output1_name], …]です。デフォルト値はNoneです。
注：入力名と出力名は生成された一時モデルファイル（<model_name>.model）に基づいて選択する必要があります。
戻り値0：成功。
-1：失敗。

例：

# hybrid_quantization_step1を呼び出して量子化設定ファイルを生成する
ret = rknn.hybrid_quantization_step1(dataset='./dataset.txt')

1.12.2 hybrid_quantization_step2

ハイブリッド量子化機能を使用する場合にRKNNモデルを生成するためのインターフェースです。

項目内容
APIhybrid_quantization_step2
説明一時モデルファイル、設定ファイル、量子化設定ファイル、校正データセットを入力として受け取り、混合量子化後のRKNNモデルを生成します。
パラメータmodel_input：hybrid_quantization_step1で生成された一時モデルファイル（<model_name>.model）のパス。
data_input：hybrid_quantization_step1で生成されたデータファイル（<model_name>.data）のパス。
model_quantization_cfg：hybrid_quantization_step1で生成され、修正済みのモデル量子化設定ファイル（<model_name>.quantization.cfg）のパス。
戻り値0：成功。
-1：失敗。

例：

# Call hybrid_quantization_step2 to generate hybrid quantized RKNN model
ret = rknn.hybrid_quantization_step2(
    model_input='./ssd_mobilenet_v2.model',
    data_input='./ssd_mobilenet_v2.data',
    model_quantization_cfg='./ssd_mobilenet_v2.quantization.cfg')

1.13 量子化精度分析

このインターフェースは、浮動小数点推論と量子化推論を実行し、各層のデータを生成して量子化精度分析を行います。

項目内容
APIaccuracy_analysis
説明推論を実行してスナップショットを生成します。すなわち各層のtensorデータをdumpします。fp32とquantの2種類のデータ型のスナップショットをdumpし、量子化誤差の計算に使用します。
注：
1. このインターフェースはbuildまたはhybrid_quantization_step2の後にのみ呼び出せます。
2. targetを指定せず、かつ元モデルが量子化済みモデル（QATモデル）である場合、呼び出しは失敗します。
3. このインターフェースで使用する量子化方式はconfigで指定した方式と一致します。
パラメータinputs：画像（jpg / png / bmp / npyなど）のパスlist。
output_dir：出力ディレクトリです。すべてのスナップショットはこのディレクトリに保存されます。デフォルト値は’./snapshot’です。

targetが設定されていない場合、output_dir配下には以下が出力されます。
- simulatorディレクトリ：量子化モデル全体をsimulator上で完全に実行した際の各層結果（float32に変換済み）を保存します。
- goldenディレクトリ：浮動小数点モデル全体をsimulator上で完全に実行した際の各層結果を保存します。
- error_analysis.txt：simulator上で量子化モデルを層ごとに実行した際の各層結果とgolden浮動小数点モデルの各層結果との余弦距離（entire_error cosine）、および量子化モデルが前層の浮動小数点結果を入力として受け取った場合の出力と浮動小数点モデルとの余弦距離（single_error cosine）を記録します。詳細情報はerror_analysis.txtを確認してください。

targetを設定した場合、output_dirにはさらに以下が出力されます。
- runtimeディレクトリ：量子化モデル全体をNPU上で完全に実行した際の各層結果（float32に変換済み）を保存します。
- error_analysis.txt：上記記録内容に加え、量子化モデルをsimulator上で層ごとに実行した各層結果とNPU上で層ごとに実行した各層結果との余弦距離（entire_error cosine）などの情報を記録します。詳細情報はerror_analysis.txtを確認してください。

target：ターゲットハードウェアプラットフォームです。“rv1103”、“rv1103b”、“rv1106”、“rv1106b”、“rv1126b”、“rk3562”、“rk3566”、“rk3568”、“rk3576”、“rk3588”をサポートします。デフォルト値はNoneです。targetを設定した場合、NPU実行時の各層結果を取得し、精度分析を行います。
device_id：デバイス番号です。PCに複数デバイスが接続されている場合、このパラメータを指定する必要があります。デバイス番号はlist_devicesインターフェースで確認できます。デフォルト値はNoneです。
戻り値0：成功。
-1：失敗。

例：

# Accuracy analysis
ret = rknn.accuracy_analysis(inputs=['./dog_224x224.jpg'])

1.14 デバイス一覧の取得

項目内容
APIlist_devices
説明接続済みのRV1103 / RV1103B / RV1106 / RV1106B / RV1126B / RK3562 / RK3566 / RK3568 / RK3576 / RK3588を列挙します。注：現在、デバイス接続モードにはADBとNTBの2種類があります。複数デバイス接続時は、それらのモードがすべて同一であることを確認してください。
パラメータなし。
戻り値adb_devicesリストおよびntb_devicesリストを返します。デバイスが空の場合は空リストを返します。

例：

rknn.list_devices()

返されるデバイス一覧例：

*************************
all device(s) with adb mode:
VD46C3KM6N
*************************

注：複数デバイスを使用する場合、接続モードが一致している必要があります。一致しない場合、競合が発生し、デバイス接続に失敗します。

1.15 暗号化モデルのエクスポート

このインターフェースは、通常のRKNNモデルを暗号化し、暗号化後のモデルを生成します。

項目内容
APIexport_encrypted_rknn_model
説明ユーザーが指定した暗号化レベルに基づき、通常のRKNNモデルを暗号化します。注：RV1103/RV1103B/RV1106/RV1106B/RK2118プラットフォームは現在未対応です。
パラメータinput_model：暗号化対象のRKNNモデルパス。
output_model：暗号化後モデルの保存パス。デフォルト値はNoneで、{original_model_name}.crypt.rknnを暗号化後モデル名として使用します。
crypt_level：暗号化レベルです。1、2、3の3段階があります。デフォルト値は1です。レベルが高いほど安全性は高くなりますが、復号にかかる時間も長くなります。逆に、レベルが低いほど安全性は低くなりますが、復号は速くなります。データ型は整数です。
戻り値0：成功。
-1：失敗。

例：

ret = rknn.export_encrypted_rknn_model('test.rknn')

1.16 カスタム演算子の登録

このインターフェースは、カスタム演算子を登録するためのものです。

項目内容
APIreg_custom_op
説明ユーザーが提供するカスタム演算子クラスを登録します。現在ONNXモデルのみサポートします。
パラメータcustom_op：ユーザー定義の演算子クラスです。ONNX演算子仕様内に存在しない新しい演算子を定義する必要がある場合に使用します。この演算子のop_typeは“cst”で始めることを推奨し、その演算子クラスのshape_infer関数およびcompute関数はユーザー自身が実装する必要があります。
注：custom_op演算子クラスはモデル変換およびカスタム演算子付きRKNNモデル生成のみに使用されます。デバイス側でデプロイする場合は、《RKNN SDK User Guide》の5.5章も参照してください。
戻り値0：成功。
-1：失敗。

例：

import numpy as np
from rknn.api.custom_op import get_node_attr


class cstSoftmax:
    op_type = 'cstSoftmax'


    def shape_infer(self, node, in_shapes, in_dtypes):
        out_shapes = in_shapes.copy()
        out_dtypes = in_dtypes.copy()
        return out_shapes, out_dtypes


    def compute(self, node, inputs):
        x = inputs[0]
        axis = get_node_attr(node, 'axis')
        x_max = np.max(x, axis=axis, keepdims=True)
        tmp = np.exp(x - x_max)
        s = np.sum(tmp, axis=axis, keepdims=True)
        outputs = [tmp / s]
        return outputs


ret = rknn.reg_custom_op(cstSoftmax)

1.17 C++デプロイ例の生成

項目内容
APIcodegen
説明C++のデプロイ例を自動生成します。
パラメータoutput_path：出力フォルダのディレクトリです。ユーザーはディレクトリ名を設定できます。
inputs：モデル入力のパスリストを指定します。省略可能です。有効なファイル形式はjpg/png/npyです。npyファイルを入力とする場合、npyデータの次元情報はモデル入力の次元情報と一致している必要があります。
overwrite：Trueに設定すると、output_pathで指定したディレクトリ内のファイルを上書きします。デフォルト値はFalseです。
戻り値0：成功。
-1：失敗。

例：

ret = rknn.codegen(output_path='./rknn_app_demo',
                   inputs=['./mobilenet_v2/dog_224x224.jpg'],
                   overwrite=True)