本文件說明 TensorFlow Lite 的運算版本結構定義。營運版本管理功能可讓開發人員在現有的作業中新增功能和參數。此外,它也能保證下列事項:
- 回溯相容性:新的 TensorFlow Lite 實作應處理舊模型檔案。
- 前瞻相容性:舊版 TensorFlow Lite 實作應處理由新版轉換工具產生的新模型檔案,但前提是未使用新功能。
- 前瞻相容性偵測:如果舊版 TensorFlow Lite 實作讀取了包含不支援的新運算版本的新模型,則應回報錯誤。
範例:將除法新增至深度卷積
本文的其餘部分說明如何在深度卷積運算中加入加法參數,以說明 TFLite 的運算版本。
閱讀本文件不必瞭解加除知識。請注意:
- 將會新增 2 個新的整數參數:
dilation_width_factor
和dilation_height_factor
。 - 不支援除法的舊深度卷積核心,相當於將除法係數設為 1。
變更 FlatBuffer 結構定義
如要在運算中新增參數,請變更 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 結構和核心實作
在 TensorFlow Lite 中,核心實作與 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;
}
這裡不需要查看操作版本。當新實作項目讀取缺少除法係數的舊模型檔案時,該檔案會使用 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%
對應至 tensorflow/core/public/version.h 中定義的目前執行階段版本。
委派實作
TensorFlow Lite 提供委派 API,可將作業委派給硬體後端。在委派的 Prepare
函式中,檢查委派程式碼中的所有節點是否支援該版本。
const int kMaxVersion = 1;
TfLiteNode* node;
TfLiteRegistration* registration = nullptr;
TF_LITE_ENSURE_STATUS(context->GetNodeAndRegistration(context, node_index, &node, ®istration));
if (registration->version > kMaxVersion) {
// Reject the node if the version isn't supported.
}
即使委派功能僅支援第 1 版作業,也需執行這項步驟,因此委派功能可在取得較高版本運算時偵測不相容情形。