LiteRT 運算子版本

本文說明 LiteRT 的操作版本化結構定義。透過作業版本管理功能，開發人員就能在現有作業中新增新功能和參數。此外，還提供下列保證：

回溯相容性：新的 LiteRT 實作應處理舊的模型檔案。
前向相容性：只要未使用新功能，舊版 LiteRT 實作項目應可處理新版轉換器產生的模型檔案。
前向相容性偵測：如果舊版 LiteRT 導入程式讀取新模型，而該模型包含不支援的新版作業，則應回報錯誤。

範例：在深度卷積中加入擴張

本文的其餘部分將說明 TFLite 中的運算子版本，並說明如何在深度卷積運算中新增擴張參數。

您不必瞭解延遲處理，也能瞭解本文。請注意：

將新增 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 中定義) 提供幾個函式，用於註冊運算核心。預設的最低和最高版本為 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 版本的新運算核心，因此需要變更這行程式碼：

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 填入執行作業所需的最低版本。在本例中，這表示：

當擴張係數全為 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 版，也必須執行這項操作，這樣委派作業才能在取得較高版本的作業時偵測不相容的情況。