LiteRT オペレーターのバージョン

このドキュメントでは、LiteRT の op バージョニング スキーマについて説明します。Op バージョニングにより、デベロッパーは既存の Op に新しい機能とパラメータを追加できます。また、次のことも保証します。

  • 下位互換性: 新しい LiteRT 実装は古いモデルファイルを処理する必要があります。
  • 前方互換性: 新しい機能が使用されていない限り、古い LiteRT 実装は、新しいバージョンのコンバータで生成された新しいモデルファイルを処理する必要があります。
  • 前方非互換性検出: 古い LiteRT 実装が、サポートされていない新しいバージョンの op を含む新しいモデルを読み取った場合、エラーを報告する必要があります。

例: 深さ方向の畳み込みに拡張を追加する

このドキュメントの残りの部分では、深層畳み込み演算に拡張パラメータを追加する方法を示して、TFLite の op バージョニングについて説明します。

このドキュメントを理解するうえで、拡張に関する知識は必要ありません。次のことに注意してください。

  • 2 つの新しい整数パラメータ dilation_width_factor と dilation_height_factor が追加されます。
  • 拡張をサポートしていない古い深度方向の畳み込みカーネルは、拡張係数を 1 に設定することと同じです。

FlatBuffer スキーマを変更する

op に新しいパラメータを追加するには、lite/schema/schema.fbs のオプション テーブルを変更します。

たとえば、デプスワイズ畳み込みのオプション テーブルは次のようになります。

table DepthwiseConv2DOptions {
  padding:Padding;
  stride_w:int;
  stride_h:int;
  depth_multiplier:int;
  fused_activation_function:ActivationFunctionType;
}

新しいパラメータを追加する場合:

  • どのパラメータがどのバージョンでサポートされているかを示すコメントを追加します。
  • 新しい実装で、新しく追加されたパラメータのデフォルト値を取得すると、古い実装とまったく同じように動作します。

新しいパラメータを追加すると、テーブルは次のようになります。

table DepthwiseConv2DOptions {
  // Parameters for DepthwiseConv version 1 or above.
  padding:Padding;
  stride_w:int;
  stride_h:int;
  depth_multiplier:int;
  fused_activation_function:ActivationFunctionType;
  // Parameters for DepthwiseConv version 2 or above.
  dilation_w_factor:int = 1;
  dilation_h_factor:int = 1;
}

新しいスキーマ用にファイル lite/schema/schema_generated.h を再生成する必要があります。

C 構造体とカーネル実装を変更する

LiteRT では、カーネル実装は FlatBuffer 定義から切り離されています。カーネルは、lite/c/builtin_op_data.h で定義された C 構造体からパラメータを読み取ります。

元のデプスワイズ畳み込みパラメータは次のとおりです。

typedef struct {
  TfLitePadding padding;
  int stride_width;
  int stride_height;
  int depth_multiplier;
  TfLiteFusedActivation activation;
} TfLiteDepthwiseConvParams;

FlatBuffer スキーマと同様に、どのパラメータがどのバージョンからサポートされているかを示すコメントを追加します。結果は次のようになります。

typedef struct {
  // Parameters for DepthwiseConv version 1 or above.
  TfLitePadding padding;
  int stride_width;
  int stride_height;
  int depth_multiplier;
  TfLiteFusedActivation activation;
  // Parameters for DepthwiseConv version 2 or above.
  int dilation_width_factor;
  int dilation_height_factor;
} TfLiteDepthwiseConvParams;

また、新しく追加されたパラメータを C 構造体から読み取るようにカーネル実装を変更してください。ここでは詳細を省略します。

FlatBuffer 読み取りコードを変更する

FlatBuffer を読み取って C 構造体を生成するロジックは lite/core/api/flatbuffer_conversions.cc にあります。

以下のように、新しいパラメータを処理するようにファイルを更新します。

TfLiteStatus ParseDepthwiseConv2D(const Operator* op,
                                  ErrorReporter* error_reporter,
                                  BuiltinDataAllocator* allocator,
                                  void** builtin_data) {
  CheckParsePointerParams(op, error_reporter, allocator, builtin_data);

  SafeBuiltinDataAllocator safe_allocator(allocator);

  std::unique_ptr<TfLiteDepthwiseConvParams,
                  SafeBuiltinDataAllocator::BuiltinDataDeleter>
      params = safe_allocator.Allocate<TfLiteDepthwiseConvParams>();
  TF_LITE_ENSURE(error_reporter, params != nullptr);

  const DepthwiseConv2DOptions* schema_params =
      op->builtin_options_as_DepthwiseConv2DOptions();

  if (schema_params != nullptr) {
    params->padding = ConvertPadding(schema_params->padding());
    params->stride_width = schema_params->stride_w();
    params->stride_height = schema_params->stride_h();
    params->depth_multiplier = schema_params->depth_multiplier();
    params->activation =
        ConvertActivation(schema_params->fused_activation_function());

    params->dilation_width_factor = schema_params->dilation_w_factor();
    params->dilation_height_factor = schema_params->dilation_h_factor();
  }

  *builtin_data = params.release();
  return kTfLiteOk;
}

ここでは op バージョンを確認する必要はありません。新しい実装で、拡張率が欠落している古いモデルファイルを読み取ると、デフォルト値として 1 が使用され、新しいカーネルは古いカーネルと一貫して動作します。

カーネル登録を変更する

MutableOpResolver（lite/mutable_op_resolver.h で定義）は、op カーネルを登録するためのいくつかの関数を提供します。最小バージョンと最大バージョンはデフォルトで 1 です。

void AddBuiltin(tflite::BuiltinOperator op, TfLiteRegistration* registration,
                int min_version = 1, int max_version = 1);
void AddCustom(const char* name, TfLiteRegistration* registration,
               int min_version = 1, int max_version = 1);

組み込みのオペレーションは lite/kernels/register.cc に登録されます。この例では、DepthwiseConv2D バージョン 1 と 2 を処理できる新しい op カーネルを実装したため、次の行を変更する必要があります。

AddBuiltin(BuiltinOperator_DEPTHWISE_CONV_2D, Register_DEPTHWISE_CONV_2D());

これを、次のように変更します。

AddBuiltin(BuiltinOperator_DEPTHWISE_CONV_2D, Register_DEPTHWISE_CONV_2D(),
             /* min_version = */ 1,
             /* max_version = */ 2);

TFLite オペレーションのバージョンを変更する

次のステップでは、TFLite が op の実行に必要な最小バージョンを設定するようにします。この例では、次のようになります。

  • 拡張係数がすべて 1 の場合は、version=1 を入力します。
  • それ以外の場合は version=2 を入力します。

lite/tools/versioning/op_version.cc のオペレーターの GetBuiltinOperatorVersion 関数を変更して、DepthwiseConv2D のケースに新しいバージョンを追加します。

case BuiltinOperator_DEPTHWISE_CONV_2D:
  auto depthwise_conv_params =
      reinterpret_cast<TfLiteDepthwiseConvParams*>(op_sig.builtin_data);
  TFLITE_DCHECK(depthwise_conv_params != nullptr);
  if (depthwise_conv_params->dilation_width_factor != 1 ||
       depthwise_conv_params->dilation_height_factor != 1) {
    return 2;
  }
  return 1;

オペレーター バージョン マップを更新する

最後のステップは、新しいバージョン情報をオペレータ バージョン マップに追加することです。この手順が必要なのは、このバージョン マップに基づいてモデルの最小限必要なランタイム バージョンを生成する必要があるためです。

これを行うには、lite/tools/versioning/runtime_version.cc に新しいマップ エントリを追加する必要があります。

この例では、op_version_map に次のエントリを追加する必要があります。

{ {BuiltinOperator_DEPTHWISE_CONV_2D, 2}, %CURRENT_RUNTIME_VERSION%}

ここで、%CURRENT_RUNTIME_VERSION% は release_version.h で定義されている現在のランタイム バージョンに対応します。

委任の実装

LiteRT は、オペレーションをハードウェア バックエンドに委任できる委任 API を提供します。デリゲートの Prepare 関数で、Delegation コードのすべてのノードでバージョンがサポートされているかどうかを確認します。

const int kMaxVersion = 1;
TfLiteNode* node;
TfLiteRegistration* registration = nullptr;
TF_LITE_ENSURE_STATUS(context->GetNodeAndRegistration(context, node_index, &node, &registration));

if (registration->version > kMaxVersion) {
  // Reject the node if the version isn't supported.
}

委任がバージョン 1 のオペレーションのみをサポートしている場合でも、これは必要です。これにより、委任は上位バージョンのオペレーションを取得するときに非互換性を検出できます。