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

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

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

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

このドキュメントの残りの部分では、TFLite でのオペレーションのバージョニングについて説明します。まず、深度方向畳み込みオペレーションに拡張パラメータを追加する方法について説明します。

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

  • dilation_width_factor と dilation_height_factor の 2 つの新しい整数パラメータが追加されます。
  • 拡張をサポートしていない古い深度方向畳み込みカーネルは、拡張係数を 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 op バージョンを変更する

次のステップでは、オペレーションの実行に必要な最小バージョンを TFLite に入力します。この例では、次のことを意味します。

  • 拡張係数がすべて 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 関数で、委任コード内のすべてのノードでバージョンがサポートされているかどうかを確認します。

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 オペレーションのみをサポートする場合でも必要です。これにより、委任は、より高いバージョンのオペレーションを取得するときに非互換性を検出できます。