tf.lite

一、概述

1、模块

• constants 模块
• experimental 模块

2、类

• class Interpreter: TensorFlow Lite模型的解释器接口。
• class OpHint: 一个帮助构建tflite函数调用的类。
• class OpsSet: 类定义可用于生成TFLite模型的操作系统集。
• class Optimize: Enum定义在生成tflite图时要应用的优化。
• class RepresentativeDataset: 用于评估优化的代表性数据集。
• class TFLiteConverter: 将TensorFlow模型转换为output_format。
• class TargetSpec: 目标设备规格。
• class TocoConverter: 使用TOCO将TensorFlow模型转换为output_format。

3、函数

• toco_convert(...): 使用TOCO转换模型。(弃用)

二、tf.lite.OpHint类

它允许您使用一组TensorFlow操作并注释构造，以便toco知道如何将其转换为tflite。这在张量流图中嵌入了一个伪函数。这允许在较低级别的TensorFlow实现中嵌入高级API使用信息，以便以后可以替换其他实现。本质上，这个伪op中的任何“输入”都被输入到一个标识中，并且属性被添加到该输入中，然后由构成伪op的组成ops使用。

1、__init__()

__init__(
    function_name,
    level=1,
    children_inputs_mappings=None,
    **kwargs
)

创建一个OpHint。

参数：

• function_name:函数名(tflite中的自定义op名)
• level:OpHint水平。
• Children _inputs_mappings:子OpHint输入/输出映射。children_inputs_mappings应该如下:"parent_first_child_input": [{"parent_input_index": num， "child_input_index": num}，…[{"parent_output_index": num， "child_output_index": num}，…[{"child_input_index": num， "child_output_index": num}，…]
• **kwargs:函数的任何常量属性的关键字参数。

2、add_input

add_input(
    *args,
    **kwargs
)

向提示添加一个包装好的输入参数。

参数：

• args:输入张量。
• **kwargs:“name”标签“tag”标签用来对多个参数进行分组，这些参数将被聚合。例如，像'cool_input'这样的字符串。基本上，可以将多个输入添加到相同的提示中，用于最终组合的并行操作。一个例子是static_rnn，它创建状态或输入的多个副本。“聚合”聚合策略，仅对标记非None有效。可接受的值是OpHint。AGGREGATE_FIRST OpHint。AGGREGATE_LAST, OpHint.AGGREGATE_STACK。“index_override”要使用的全局索引。这对应于将生成的最终存根中的参数顺序。

返回值：

• 被包裹的输入张量。

3、add_output

add_output(
    *args,
    **kwargs
)

在提示中添加一个包装好的输出参数。

参数：

• *args:输出张量。
• **kwargs:“name”标签“tag”标签用来对多个参数进行分组，这些参数将被聚合。例如，像'cool_input'这样的字符串。基本上，可以将多个输入添加到相同的提示中，用于最终组合的并行操作。一个例子是static_rnn，它创建状态或输入的多个副本。“聚合”聚合策略，仅对标记非None有效。可接受的值是OpHint。AGGREGATE_FIRST OpHint。AGGREGATE_LAST, OpHint.AGGREGATE_STACK。“index_override”要使用的全局索引。这对应于将生成的最终存根中的参数顺序。

返回值：

• 缠绕输出张量。

4、add_outputs

add_outputs(
    *args,
    **kwargs
)

将一系列输出添加到函数调用中。

参数：

• *args:要转换的输出列表(应该是tf.张量)。
• * * kwargs:明白了

返回值：

• 包装输出(具有附加元数据的标识替代)。这些也是tf.Tensor。

三、tf.lite.OpHint.OpHintArgumentTracker

从概念上跟踪“OpHint 函数”参数的索引。这些函数的输入和参数都使用类的实例，因此它们可以有独立的编号。

1、__init__

__init__(
    function_name,
    unique_function_id,
    node_name_prefix,
    attr_name,
    level=1,
    children_inputs_mappings=None
)

初始化ophint论点。

参数：

• function_name:跟踪参数的函数的名称。
• unique_function_id:用于跟踪参数的函数的UUID。
• node_name_prefix:如何命名创建的标识。
• attr_name:用于存储此提示的索引的属性的名称。例如FUNCTION_INPUT_INDEX或FUNCTION_OUTPUT_INDEX
• level:层次层次的Ophint节点，一个数字。
• children_inputs_mappings:子提示的输入/输出映射。

2、add

add(
    arg,
    tag=None,
    name=None,
    aggregate=None,
    index_override=None
)

返回输入张量的一个包绕张量作为参数。

参数：

• arg:一个张量应该被认为是一个参数。
• tag:用于标识应该打包的参数的字符串标记。
• name:参数名。这包括在标识提示op名称中。
• aggregate:聚合策略。可接受的值是OpHint。AGGREGATE_FIRST OpHint。AGGREGATE_LAST, OpHint.AGGREGATE_STACK。注意，只有在指定标记时聚合才有效。
• index_override:指定最终存根中的输入/输出索引。即添加(arg0,指数= 1);add(arg1, index=0)将使最终存根为stub_func(输入[arg1, arg0]，输出=[])，而不是基于默认调用顺序的排序。

返回值：

• 一个张量表示被包裹的参数。

可能产生的异常：

• ValueError: When indices are not consistent.

四、tf.lite.Interpreter

这使得在Python中可以访问TensorFlow Lite解释器。可以在多线程Python环境中使用这个解释器，但是必须确保每次只从一个线程调用特定实例的函数。因此，如果希望有4个线程同时运行不同的推论，请为每个线程创建一个解释器作为线程本地数据。类似地，如果您在单个解释器的一个线程中调用invoke()，但是希望在另一个线程上使用张量()，那么在调用张量()之前，必须在线程之间使用同步原语，以确保调用已经返回。

1、__init__

__init__(
    model_path=None,
    model_content=None
)

构造函数。

参数：

• model_path:到TF-Lite Flatbuffer文件的路径。
• model_content:模型的内容。

可能产生的异常：

• ValueError: If the interpreter was unable to create.

2、allocate_tensors

allocate_tensors()

3、get_input_details

get_input_details()

获取模型输入细节。

返回值：

• 输入详细信息的列表。

4、get_output_details

get_output_details()

获取模型输出详细信息。

返回值：

• 输出详细信息的列表。

5、get_tensor

get_tensor(tensor_index)

获取输入张量的值(获取副本)。如果希望避免复制，可以使用张量()。此函数不能用于读取中间结果。

参数：

• 张量指标:要得到的张量的张量指标。这个值可以从get_output_details中的'index'字段中获得。

返回值：

• 一个numpy数组。

6、get_tensor_details

get_tensor_details()

获取具有有效张量细节的每个张量的张量细节。如果找不到张量所需的信息，张量就不会添加到列表中。这包括没有名称的临时张量。

返回值：

• 包含张量信息的字典列表。

7、invoke

invoke()

调用解释器。在调用此函数之前，请确保设置输入大小、分配张量和填充值。另外，请注意，这个函数释放了GIL，因此在Python解释器继续运行时，可以在后台完成繁重的计算。当invoke()调用尚未完成时，不应调用此对象上的任何其他函数。

可能产生的异常：

• ValueError: When the underlying interpreter fails raise ValueError.

8、reset_all_variables

reset_all_variables()

9、resize_tensor_input

resize_tensor_input(
    input_index,
    tensor_size
)

调整输入张量的大小。

参数：

• input_index:要设置的输入的张量索引。这个值可以从get_input_details中的'index'字段中得到。
• tensor_size:要调整输入大小的tensor_shape。

可能产生的异常：

• ValueError: If the interpreter could not resize the input tensor.

10、set_tensor

set_tensor(
    tensor_index,
    value
)

设置输入张量的值。注意，这将复制值中的数据。如果希望避免复制，可以使用张量()函数获得指向tflite解释器中的输入缓冲区的numpy缓冲区。

参数：

• tensor_index:张量的张量索引。这个值可以从get_input_details中的'index'字段中得到。
• value:要设置的张量的值。

可能产生的异常：

• ValueError: If the interpreter could not set the tensor.

11、tensor

tensor(tensor_index)

返回一个函数，该函数给出当前张量缓冲区的numpy视图。这允许读写这个张量的w/o拷贝。这更紧密地反映了c++解释器类接口的张量()成员，因此得名。注意不要通过调用allocate_tenators()和invoke()来保存这些输出引用。此函数不能用于读取中间结果。

用法：

interpreter.allocate_tensors()
input = interpreter.tensor(interpreter.get_input_details()[0]["index"])
output = interpreter.tensor(interpreter.get_output_details()[0]["index"])
for i in range(10):
  input().fill(3.)
  interpreter.invoke()
  print("inference %s" % output())

注意这个函数如何避免直接生成numpy数组。这是因为重要的是不要对数据持有实际的numpy视图超过必要的时间。如果这样做，则不能再调用解释器，因为解释器可能会调整大小并使引用的张量无效。NumPy API不允许底层缓冲区的任何可变性。

错误：

input = interpreter.tensor(interpreter.get_input_details()[0]["index"])()
output = interpreter.tensor(interpreter.get_output_details()[0]["index"])()
interpreter.allocate_tensors()  # This will throw RuntimeError
for i in range(10):
  input.fill(3.)
  interpreter.invoke()  # this will throw RuntimeError since input,output

参数：

• 张量指标:要得到的张量的张量指标。这个值可以从get_output_details中的'index'字段中获得。

返回值：

• 一个函数，它可以返回一个指向任意点的内部TFLite张量状态的新的数字数组。永久保存该函数是安全的，但是永久保存numpy数组是不安全的。

五、tf.lite.OpsSet

类定义可用于生成TFLite模型的操作系统集。

六、tf.lite.Optimize

Enum定义在生成tflite图时要应用的优化。

七、tf.lite.RepresentativeDataset

用于评估优化的代表性数据集。可用于评估转换器优化的代表性数据集。例如，转换器可以使用这些例子来估计(最小，最大)范围校准模型的输入。这可以允许转换器量化转换后的浮点模型。

1、__init__

__init__(input_gen)

创建一个代表性数据集。

参数：

• input_gen:一个输入生成器，可用于为模型生成输入样本。这必须是一个可调用的对象，返回一个支持iter()协议的对象(例如一个生成器函数)。生成的元素必须具有与模型输入相同的类型和形状。

八、tf.lite.TargetSpec

目标设备规格。关于目标设备的详细信息。转换器为特定的设备优化生成的模型。

属性：

• supported_ops:实验标志，可能会更改。设备支持的一组OpsSet选项。(默认设置((OpsSet.TFLITE_BUILTINS)))

1、__init__

__init__(supported_ops=None)

九、tf.lite.TFLiteConverter

将TensorFlow模型转换为output_format。这用于将TensorFlow GraphDef或SavedModel转换为TFLite FlatBuffer或图形可视化。

属性：

• inference_type:输出文件中实数数组的目标数据类型。必须{特遣部队。float32 tf.uint8}。如果提供了优化，则忽略此参数。(默认tf.float32)
• inference_input_type:实数输入数组的目标数据类型。允许不同类型的输入数组。如果提供了整数类型而没有使用优化，则必须提供quantized_inputs_stats。如果推论类型是tf。从具有量化意识的训练输入模型到完全量化模型的信号转换，然后推论_input_type默认为tf.uint8。在所有其他情况下，推论_input_type默认为tf.float32。必须{特遣部队。float32,特遣部队。uint8, tf.int8}
• inference_output_type:实数输出数组的目标数据类型。允许不同类型的输出数组。如果推论类型是tf。从具有量化意识的训练输出模型到完全量化模型的信号转换，然后推论_output_type默认为tf.uint8。在所有其他情况下，推论_output_type必须是tf。否则将抛出一个错误。必须{特遣部队。float32,特遣部队。uint8, tf.int8}
• output_format:输出文件格式。当前必须是{TFLITE, GRAPHVIZ_DOT}。(默认TFLITE)
• quantized_input_stats:表示输入张量名称的字符串的Dict，映射到表示训练数据的平均值和标准偏差的浮点数元组(例如，{"foo":(0。1)})。仅当推论_input_type是QUANTIZED_UINT8时才需要。real_input_value = (quantized_input_value - mean_value) / std_dev_value。(默认{})
• default_ranges_stats:整数的元组，表示没有指定范围的所有数组的(最小、最大)范围值。旨在通过“虚拟量化”实验量化。(默认没有)
• drop_control_dependency:布尔值，指示是否静默地删除控件依赖项。这是因为TFLite不支持控件依赖关系。(默认正确)
• reorder_across_fake_quant:布尔值，指示是否在意外位置重新排序FakeQuant节点。当FakeQuant节点的位置阻止转换图形所需的图形转换时使用。结果生成与量化训练图不同的图，可能导致不同的算术行为。(默认错误)
• change_concat_input_ranges:布尔值，用于更改用于量化模型的concat操作符的输入和输出的最小/最大范围的行为。当为真时，更改concat操作符重叠的范围。(默认错误)
• allow_custom_ops:布尔值，指示是否允许自定义操作。当false时，任何未知操作都是错误。如果为真，则为任何未知的op创建自定义操作。开发人员将需要使用自定义解析器向TensorFlow Lite运行时提供这些。(默认错误)
• post_training_quantize:不推荐，请指定[optimization]。而不是优化。布尔值，指示是否对转换后的浮点模型的权重进行量化。模型大小将会减小，并且会有延迟改进(以精度为代价)。(默认错误)
• dump_graphviz_dir:在处理GraphViz .dot文件的各个阶段转储图形的文件夹的完整文件路径。优先选择——output_format=GRAPHVIZ_DOT，以便保留输出文件的需求。(默认没有)
• dump_graphviz_video:布尔值，指示是否在每次图形转换之后转储图形。(默认错误)
• target_ops:实验标志，可能会更改。一组OpsSet选项，指示要使用哪个转换器。(默认设置((OpsSet.TFLITE_BUILTINS)))
• optimizations:实验标志，可能会更改。转换模型时要应用的优化列表。如[Optimize.DEFAULT]。
• representative_dataset:可用于为模型生成输入和输出示例的代表性数据集。转换器可以使用数据集来评估不同的优化。

用例：

# Converting a GraphDef from session.
converter = lite.TFLiteConverter.from_session(sess, in_tensors, out_tensors)
tflite_model = converter.convert()
open("converted_model.tflite", "wb").write(tflite_model)

# Converting a GraphDef from file.
converter = lite.TFLiteConverter.from_frozen_graph(
  graph_def_file, input_arrays, output_arrays)
tflite_model = converter.convert()
open("converted_model.tflite", "wb").write(tflite_model)

# Converting a SavedModel.
converter = lite.TFLiteConverter.from_saved_model(saved_model_dir)
tflite_model = converter.convert()

# Converting a tf.keras model.
converter = lite.TFLiteConverter.from_keras_model_file(keras_model)
tflite_model = converter.convert()

1、__init__

__init__(
    graph_def,
    input_tensors,
    output_tensors,
    input_arrays_with_shape=None,
    output_arrays=None
)

TFLiteConverter构造函数。

参数：

• graph_def:冻结的TensorFlow GraphDef。
• input_tenators:输入张量列表。类型和形状使用foo计算。形状和foo.dtype。
• output_tensors:输出张量列表(仅使用.name)。
• input_arrays_with_shape:表示输入张量名称的字符串元组和表示输入形状的整数列表(例如，[("foo":[1,16,16,3])))。仅当图无法加载到TensorFlow中，且input_tensors和output_tensors为空时才使用。(默认没有)
• output_arrays:用于冻结图形的输出张量列表。仅当图无法加载到TensorFlow中，且input_tensors和output_tensors为空时才使用。(默认没有)

可能产生的异常：

• ValueError: Invalid arguments.

2、convert

convert()

基于实例变量转换TensorFlow GraphDef。

返回值：

• 以序列化格式转换的数据。根据output_format中的值，可以是TFLite Flatbuffer，也可以是Graphviz图形。

可能产生的异常：

• ValueError: Input shape is not specified. None value for dimension in input_tensor.

3、from_frozen_graph

@classmethod
from_frozen_graph(
    cls,
    graph_def_file,
    input_arrays,
    output_arrays,
    input_shapes=None
)

从包含冻结GraphDef的文件中创建TFLiteConverter类。

参数：

• graph_def_file:包含冻结GraphDef的文件的完整文件路径。
• input_arrays:用于冻结图形的输入张量列表。
• output_arrays:用于冻结图形的输出张量列表。
• input_shapes:表示输入张量名称的字符串的Dict到表示输入形状的整数列表(例如，{"foo":[1,16,16,3]])。自动确定何时输入形状为None(例如，{"foo": None})。(默认没有)

返回值：

• TFLiteConverter类。

可能产生的异常：

• IOError: File not found. Unable to parse input file.
• ValueError: The graph is not frozen. input_arrays or output_arrays contains an invalid tensor name. input_shapes is not correctly defined when required

4、from_keras_model_file

@classmethod
from_keras_model_file(
    cls,
    model_file,
    input_arrays=None,
    input_shapes=None,
    output_arrays=None,
    custom_objects=None
)

从tf创建TFLiteConverter类。keras模型文件。

参数：

• model_file:包含tf的HDF5文件的完整文件路径。keras模型。
• input_arrays:用于冻结图形的输入张量列表。如果不提供输入数组，则使用SignatureDef中的输入数组。(默认没有)
• input_shapes:表示输入张量名称的字符串的Dict到表示输入形状的整数列表(例如，{"foo":[1,16,16,3]])。自动确定何时输入形状为None(例如，{"foo": None})。(默认没有)
• output_arrays:用于冻结图形的输出张量列表。如果没有提供SignatureDef的输出数组，则使用它。(默认没有)
• custom_objects: Dict将名称(字符串)映射到要在模型反序列化期间考虑的自定义类或函数。(默认没有)

返回值：

• TFLiteConverter类。

5、from_session

@classmethod
from_session(
    cls,
    sess,
    input_tensors,
    output_tensors
)

从TensorFlow会话创建TFLiteConverter类。

参数：

• sess:TensorFlow会话。
• input_tenators:输入张量列表。类型和形状使用foo计算。形状和foo.dtype。
• output_tensors:输出张量列表(仅使用.name)。

返回值：

• TFLiteConverter类。

6、get_input_arrays

get_input_arrays()

返回输入张量的名称列表。

返回值：

• 字符串的列表。

十、tf.lite.TocoConverter

使用TOCO将TensorFlow模型转换为output_format。这个类已经被弃用。请使用lite。TFLiteConverter代替。

1、from_frozen_graph

@classmethod
from_frozen_graph(
    cls,
    graph_def_file,
    input_arrays,
    output_arrays,
    input_shapes=None
)

从包含冻结图的文件创建TocoConverter类。(弃用)

2、from_keras_model_file

@classmethod
from_keras_model_file(
    cls,
    model_file,
    input_arrays=None,
    input_shapes=None,
    output_arrays=None
)

从tf创建一个TocoConverter类。keras模型文件。(弃用)

3、from_saved_model

@classmethod
from_saved_model(
    cls,
    saved_model_dir,
    input_arrays=None,
    input_shapes=None,
    output_arrays=None,
    tag_set=None,
    signature_key=None
)

从保存模型创建TocoConverter类。(弃用)

4、from_session

@classmethod
from_session(
    cls,
    sess,
    input_tensors,
    output_tensors
)

从TensorFlow会话创建TocoConverter类。(弃用)

十一、tf.lite.toco_convert

使用TOCO转换模型。(弃用)

tf.lite.toco_convert(
    input_data,
    input_tensors,
    output_tensors,
    *args,
    **kwargs
)

通常，这个函数用于将TensorFlow GraphDef转换为TFLite。可以通过提供传递给build_toco_convert_protos的参数来定制转换(有关详细信息，请参阅文档)。此函数已被弃用。请使用lite。TFLiteConverter代替。

参数：

• input_data:输入数据(通常是ss.graph_def)，
• input_tenators:输入张量列表。类型和形状使用foo计算。形状和foo.dtype。
• output_tensors:输出张量列表(仅使用.name)。
• * args:看到build_toco_convert_protos,
• * * kwargs: build_toco_convert_protos见。

返回：

• 转换后的数据。例如，如果TFLite是目标，那么这将是一个字节数组中的TFLite flatbuffer。

可能产生的异常：

• Defined in build_toco_convert_protos.