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

RKNN-Toolkit-Lite2の使用方法

1. rknn-toolkit-lite2の使用方法

1.1. rknn-toolkit-lite2 の紹介

RKNN-Toolkit-Lite2 は、Rockchipが自社のRKシリーズチップ（RV1126B、RK3576、RK3588など）向けに特化して開発した軽量なAIモデルデプロイメントツールキットであり、エッジ/組み込みデバイスでのモデル推論シナリオに焦点を当てています。複雑な環境依存関係を必要とせず、システムリソースの消費も非常に少ないのが特徴です。コア機能は、RKNNツールチェーンによって変換されたAIモデルをロードして実行することであり、TensorFlowやPyTorchなどの主流フレームワークからエクスポートされたモデルの適応をサポートしています。

このツールキットは C/C++ および Python のバイリンガルAPIを提供しており、インターフェースはシンプルで使いやすく設計されています。また、RKチップのNPUハードウェアアクセラレーション向けに深く最適化されており、モデルの推論効率を大幅に向上させることができます。スマートセキュリティ、IoT、家電などのエッジAIシナリオに適しており、開発者がモデルのエッジ側へのデプロイを迅速に実現し、組み込みAI開発のハードルを大幅に下げるのに役立ちます。

rknn-toolkit-lite2 は現在、EASY-EAI-Nano-TB への適応が完了しており、ユーザーはこれを使用してディープラーニングアルゴリズムの純粋な Python 開発を行うことができます。また、コンパイル済みのモデルもサポートしており、わずか数行のコードでアルゴリズムの推論を完了できるため、開発コストを大幅に削減できます。同時に、C/C++に不慣れな多くのアルゴリズム開発者にとっても開発のハードルを効果的に下げます。本ドキュメントは、RKNNモデルへの変換が完了したモデルに基づいてボード上で推論を行うためのものです。

1.1. rknn-toolkit-lite2 の紹介 図1

1.1. rknn-toolkit-lite2 の紹介 図1

1.2. 環境構築

1.2. 1 gitツールのインストール

Terminal window
sudo apt update && sudo apt install git

1.2. 2 miniforge3ツールのインストール

複数の異なるバージョンの Python 環境に対するシステム要件の競合を防ぐため、miniforge3 を使用して Python 環境を管理することをお勧めします。miniforge3とcondaのバージョン情報がインストールされているか確認し、すでにインストールされている場合はこのセクションの手順を省略できます。

miniforge3 インストールパッケージのダウンロード：

Terminal window
cd /userdata
wget
https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-aarch64.sh

1.2. 2 miniforge3ツールのインストール 図2

1.2. 2 miniforge3ツールのインストール 図2

miniforge3 のインストール：

Terminal window
chmod 777 Miniforge3-Linux-aarch64.sh
bash Miniforge3-Linux-aarch64.sh

1.2.2 miniforge3ツールのインストール 図3

1.2.2 miniforge3ツールのインストール 図3

1.2.2 miniforge3ツールのインストール 図4

1.2.2 miniforge3ツールのインストール 図4

1.2.2 miniforge3ツールのインストール 図5

1.2.2 miniforge3ツールのインストール 図5

1.2.3 Conda環境の作成

Conda base環境に入る：

Terminal window
source ~/miniforge3/bin/activate

Python 3.8バージョン（推奨バージョン）で、`RKNN-Toolkit-lite2` という名前のConda環境を作成する：

Terminal window
conda create -n RKNN-Toolkit-lite2 python=3.8

RKNN-Toolkit Conda環境に入る：

Terminal window
conda activate RKNN-Toolkit-lite2

Conda環境から退出する：

Terminal window
conda deactivate

Conda環境を削除する：

Terminal window
conda remove -n RKNN-Toolkit-lite2 --all

1.2.4 RKNN-Toolkit-Lite2とOpenCVライブラリのインストール

クラウドストレージからのダウンロード：

Terminal window
pip install rknn_toolkit_lite2-2.3.2-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

1.2.4 RKNN-Toolkit-Lite2とOpenCVライブラリのインストール 図6

1.2.4 RKNN-Toolkit-Lite2とOpenCVライブラリのインストール 図6

Terminal window
pip install opencv-python

1.2.4 RKNN-Toolkit-Lite2とOpenCVライブラリのインストール 図7

1.2.4 RKNN-Toolkit-Lite2とOpenCVライブラリのインストール 図7

1.3. ボードでのデモテスト

rknn-toolkit-lite2 の「テストプログラムinference_with_lite2.tar.bz2」をダウンロードし、ファイルをEASY-EAI-Nano-TB ボードのディレクトリに転送します。

以下のコマンドを実行して解凍します：

Terminal window
tar -xvf inference_with_lite2.tar.bz2

1.3. ボードでのデモテスト 図8

1.3. ボードでのデモテスト 図8

以下のコマンドを実行してディレクトリを切り替え、テストプログラムを実行します：

Terminal window
cd /userdata/inference_with_lite/
python test.py

結果は以下のようになります：

1.3. ボードでのデモテスト 図9

1.3. ボードでのデモテスト 図9

1.4. rknn-toolkit-lite2フローの説明

1.4.1 使用フローチャート

RKNN Tookit Lite2の使用フローは以下の通りです：

1.4.1 使用フローチャート 図10

1.4.1 使用フローチャート 図10

1.4.2 サンプルプログラム

第3節のサンプルプログラムは以下の通りです：

# -*- coding: utf-8 -*-
import cv2
import numpy as np
from rknnlite.api import RKNNLite


# ==================== 設定項目（実際の状況に応じて変更してください） ====================
RKNN_MODEL_PATH = "10class_ResNet50_rv1126b.rknn"  # RKNNモデルのパス
TEST_IMAGE_PATH = "./test-1.jpg"                   # テスト画像のパス
INPUT_SHAPE = (224, 224)                           # モデルの入力サイズ（モデル変換時と一致させる必要があります）
INPUT_CHANNELS = 3                                 # 入力チャンネル数
CLASSES = ("SUV", "bus", "family sedan", "fire engine", "heavy truck", "jeep", "minibus", "racing car", "taxi", "truck")


# ==================== コア関数 ====================
def preprocess_image(image_path, input_shape):
    """
    画像の前処理：読み込み→RGB変換→リサイズ→次元拡張→NCHW変換→型変換
    戻り値は4次元NCHWフォーマットの入力テンソル
    """
    # 1. 画像の読み込み
    img = cv2.imread(image_path)
    if img is None:
        raise ValueError(f"画像を読み込めません：{image_path}。パスが正しいか確認してください！")
    print(f"元の画像shape: {img.shape}")  # 元の次元（H,W,C）を出力


    # 2. BGRからRGBへの変換（OpenCVのデフォルトはBGR、モデル学習では一般的にRGBが使用されます）
    img_rgb = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    print(f"RGB変換後のshape: {img_rgb.shape}")


    # 3. モデルの入力サイズへのリサイズ
    img_resized = cv2.resize(img_rgb, input_shape)
    print(f"リサイズ後のshape: {img_resized.shape}")  # (224,224,3)


    # 4. 4次元への拡張（重要！バッチ次元を追加、N=1）
    img_4d_nhwc = np.expand_dims(img_resized, axis=0)
    print(f"バッチ次元拡張後のshape (NHWC): {img_4d_nhwc.shape}")  # (1,224,224,3)


    # 5. NCHWフォーマットへの変換（モデルログに framework layout: NCHW と表示されます）
    img_4d_nchw = np.transpose(img_4d_nhwc, (0, 3, 1, 2))
    print(f"NCHW変換後のshape: {img_4d_nchw.shape}")  # (1,3,224,224)


    # 6. 型変換（RKNN Lite2ではfloat32またはuint8が推奨されます。モデルの量子化タイプに応じて調整してください）
    img_input = img_4d_nchw.astype(np.float32)
    print(f"最終的な入力shape: {img_input.shape}, タイプ: {img_input.dtype}")


    return img_input


def softmax(x):
    """softmax正規化、出力を確率に変換"""
    x = x - np.max(x)  # 数値のオーバーフローを防止
    return np.exp(x) / np.sum(np.exp(x))


def predict(rknn_lite, input_tensor):
    """モデル推論、入力フォーマットを明示的に指定"""
    try:
        # data_formatをNCHWに明示的に指定（重要！RKNN Runtimeに入力フォーマットを伝えます）
        outputs = rknn_lite.inference(
            inputs=[input_tensor],
            data_format='nchw'  # 入力フォーマットを強制指定し、自動認識エラーを回避
        )
        return outputs
    except Exception as e:
        print(f"推論失敗：{str(e)}")
        return None


# ==================== メインプログラム ====================
if __name__ == "__main__":
    # 1. RKNN Liteの初期化
    rknn_lite = RKNNLite()
    print("--> RKNNモデルをロード中")
    ret = rknn_lite.load_rknn(RKNN_MODEL_PATH)
    if ret != 0:
        print(f"モデルのロードに失敗しました。エラーコード：{ret}")
        exit(ret)
    print("モデルのロードが完了しました")


    # 2. ランタイム環境の初期化（コアの変更点：targetパラメータを削除し、ハードウェアを自動認識させます）
    print("--> ランタイムを初期化中")
    ret = rknn_lite.init_runtime()  # targetを削除し、システムにRV1126Bを自動認識させる
    if ret != 0:
        print(f"ランタイムの初期化に失敗しました。エラーコード：{ret}")
        exit(ret)
    print("ランタイムの初期化が完了しました")


    # 3. 画像の前処理（強制的に4次元入力を生成）
    print("--> 画像の前処理")
    try:
        input_tensor = preprocess_image(TEST_IMAGE_PATH, INPUT_SHAPE)
    except ValueError as e:
        print(e)
        exit(1)


    # 4. モデル推論
    print("--> 推論を実行中")
    outputs = predict(rknn_lite, input_tensor)
    if outputs is None or len(outputs) == 0:
        print("推論に出力がありません！")
        rknn_lite.release()
        exit(1)


    # 5. 結果の解析
    print("\n--> 推論結果の解析")
    output = outputs[0][0]  # 最初の出力の最初のバッチを取得
    prob = softmax(output)
    max_idx = np.argmax(prob)
    print(f"予測カテゴリ：{CLASSES[max_idx]}")
    print(f"信頼度：{prob[max_idx]:.4f}")


    # 6. リソースの解放
    rknn_lite.release()
    print("\nすべての操作が完了しました！")

1.5. APIの詳細説明

1.5.1 RKNNLite2の初期化とオブジェクトの解放

RKNN Toolkit Lite2を使用する際、まず RKNNLite()メソッドを呼び出してRKNNLiteオブジェクトを初期化し、使用後はそのオブジェクトのrelease()`メソッドを呼び出してリソースを解放する必要があります。 RKNNLiteオブジェクトを初期化する際、verbose および verbose_fileパラメータを設定して詳細なログ情報を出力することができます。verboseパラメータは画面に詳細なログ情報を出力するかどうかを指定します。verbose_fileパラメータが設定され、かつverbose`パラメータ値がTrueの場合、ログ情報はこのパラメータで指定されたファイルにも書き込まれます。

例は以下の通りです：

Terminal window
# 詳細なログ情報を画面に出力し、inference.logファイルにも書き込む
rknn_lite = RKNNLite(verbose=True, verbose_file='./inference.log')


# 画面にのみ詳細なログ情報を出力する
rknn_lite = RKNNLite(verbose=True)
...
rknn_lite.release()

1.5.2 RKNNモデルのロード

項目パラメータ名 / 値説明
APILoad_rknnRKNNモデルをロードします。
パラメータpathRKNNモデルファイルのパス。
load_model_in_npuNPU内のRKNNモデルを直接ロードするかどうか。この場合、path はNPU内のRKNNモデルのパスになります。RKNN Toolkit LiteがNPUデバイスを接続したPC、またはRK3399Pro Linux開発ボードで実行されている場合にのみ True に設定できます。デフォルト値は False です。
戻り値0ロード成功
-1ロード失敗

例は以下の通りです：

Terminal window
ret = rknn_lite.load_rknn('10class_ResNet50_pre.rknn')

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

モデルの推論を行う前に、まずランタイム環境を初期化し、モデルがどのチッププラットフォームで実行されるかを決定する必要があります。

項目パラメータ名 / 値説明
APIinit_runtimeランタイム環境を初期化します。モデルが実行されるデバイス情報（チップモデル、デバイスID）を決定します。
パラメータtargetターゲットハードウェアプラットフォーム。現在「rk3399pro」、「rk1806」、「rk1808」、「rv1109」、「rv1126」をサポートしています。デフォルトは None で、アプリケーションが実行されている開発ボードに基づいて自動的に選択されます。
device_idデバイス番号。PCが複数のスマートデバイスに接続されている場合、このパラメータを指定する必要があります。デバイス番号は「list_devices」インターフェースで確認できます。デフォルト値は None です。
async_mode非同期モードを使用するかどうか。推論インターフェースを呼び出す際、入力画像の設定、モデル推論、推論結果の取得という3つの段階が含まれます。非同期モードを有効にした場合、現在のフレームの入力設定は前のフレームの推論と同時に行われるため、最初のフレームを除き、後続の各フレームは入力設定の時間を隠すことができ、パフォーマンスを向上させることができます。非同期モードでは、毎回返される推論結果は前のフレームのものです。デフォルト値は False です。
戻り値0成功（原文：ロード成功）
-1失敗（原文：ロード失敗）

例は以下の通りです：

Terminal window
# init runtime environment
print('--> Init runtime environment')
ret = rknn_lite.init_runtime(target=None)
if ret != 0:
    print('Init runtime environment failed')
    exit(ret)
print('done')

1.5.4 モデル推論

項目パラメータ名 / 値説明
APIinference指定された入力に対して推論を行い、推論結果を返します。
パラメータinputs推論を行う入力（cv2で処理された画像など）。型は list で、リストの要素は ndarray です。
data_type入力データの型。以下の値を指定できます：‘float32’、‘float16’、‘uint8’、‘int8’、‘int16’。デフォルト値は ‘uint8’ です。
data_formatデータモード（フォーマット）。以下の値を指定できます：“nchw”、“nhwc”。デフォルト値は ‘nhwc’ です。これら2つの違いは、channel（チャンネル）が配置される位置です。
inputs_pass_through入力をNPUドライバにパススルー（透過的伝達）します。非パススルーモードでは、入力をNPUドライバに渡す前に、ツールは入力に対して平均の減算や分散による除算などの操作を行います。一方、パススルーモードでは、これらの操作は行われません。このパラメータの値は配列であり、例えば input0 をパススルーし、input1 をパススルーしない場合、このパラメータの値は [1, 0] になります。デフォルト値は None で、すべての入力をパススルーしません。
戻り値results推論結果。型は list で、リストの要素は ndarray です。

例は以下の通りです（resnet50などの分類モデルを例とします。完全なコードは第3節を参照してください）：

Terminal window
# Inference
print('--> Running model')
outputs = rknn_lite.inference(inputs=[resize_img])


print("outputs[0]:", outputs[0])
print("outputs[0].shape:", outputs[0].shape)
show_outputs(softmax(np.array(outputs[0][0])))

1.5.5 SDKバージョンの照会

項目パラメータ名 / 値説明
APIget_sdk_versionSDK APIとドライバのバージョン番号を取得します。

注：このインターフェースを使用する前に、モデルのロードとランタイム環境の初期化を完了させる必要があります。
パラメータなし
戻り値sdk_versionAPIおよびドライバのバージョン情報。型は文字列です。

例は以下の通りです：

Terminal window
# SDKバージョン情報を取得
...
sdk_version = rknn_lite.get_sdk_version()

返される SDK 情報は以下のようになります：

1.5.5 SDKバージョンの照会 図11

1.5.5 SDKバージョンの照会 図11