Python tf.io.parse_example用法及代码示例

将Example protos 解析为张量的dict。

用法

tf.io.parse_example(
    serialized, features, example_names=None, name=None
)

解析 serialized 中给出的一些序列化 Example protos。我们将serialized 称为带有batch_size 的批次，其中包含许多单独的Example protos 条目。

example_names 可能包含相应序列化原型的说明性名称。这些可能对调试有用，但它们对输出没有影响。如果不是 None , example_names 必须与 serialized 长度相同。

此操作将序列化示例解析为字典，将键映射到 Tensor SparseTensor 和 RaggedTensor 对象。 features 是从键到 VarLenFeature , SparseFeature , RaggedFeature 和 FixedLenFeature 对象的字典。每个 VarLenFeature 和 SparseFeature 都映射到一个 SparseTensor ；每个 FixedLenFeature 都映射到一个 Tensor ；并且每个 RaggedFeature 都映射到一个 RaggedTensor 。

每个VarLenFeature 映射到一个指定类型的SparseTensor，表示一个参差不齐的矩阵。它的索引是 [batch, index] 其中 batch 标识 serialized 中的示例，而 index 是与该函数和示例关联的值列表中的值的索引。

每个 SparseFeature 映射到指定类型的 SparseTensor ，表示 dense_shape [batch_size] + SparseFeature.size 的张量。它的 values 来自带有键 value_key 的示例中的函数。 values[i] 来自批处理条目 batch 示例特征中的位置 k 。此位置信息在indices[i] 中记录为[batch, index_0, index_1, ...]，其中index_j 是示例中特征的k-th 值，键为SparseFeature.index_key[j]。换句话说，我们将 SparseTensor 的索引(除了指示批处理条目的第一个索引)按维度拆分为 Example 的不同特征。由于其复杂性，应尽可能首选VarLenFeature 而不是SparseFeature。

每个 FixedLenFeature df 映射到指定类型的 Tensor(或 tf.float32 如果未指定)和形状 (serialized.size(),) + df.shape 。

带有default_value 的FixedLenFeature 条目是可选的。如果没有默认值，如果 serialized 中的任何示例中缺少 Feature，我们将失败。

每个 FixedLenSequenceFeature df 映射到指定类型的 Tensor(或 tf.float32 如果未指定)和形状 (serialized.size(), None) + df.shape 。 serialized 中的所有示例都将沿第二维填充 default_value。

每个 RaggedFeature 映射到指定类型的 RaggedTensor。它是通过堆叠每个示例的 RaggedTensor 形成的，其中每个单独示例的 RaggedTensor 是使用 RaggedTensor.values_key 和 RaggedTensor.partition 指定的张量构造的。有关详细信息和示例，请参阅tf.io.RaggedFeature 文档。

例子：

例如，如果希望提供 tf.float32 VarLenFeature ft 和三个序列化的 Example ：

serialized = [
  features
    { feature { key:"ft" value { float_list { value:[1.0, 2.0] } } } },
  features
    { feature []},
  features
    { feature { key:"ft" value { float_list { value:[3.0] } } }
]

那么输出将如下所示：

{"ft":SparseTensor(indices=[[0, 0], [0, 1], [2, 0]],
                    values=[1.0, 2.0, 3.0],
                    dense_shape=(3, 2)) }

如果改为使用带有 default_value = -1.0 和 shape=[] 的 FixedLenSequenceFeature，则输出将如下所示：

{"ft":[[1.0, 2.0], [3.0, -1.0]]}

给定 serialized 中的两个 Example 输入原型：

[
  features {
    feature { key:"kw" value { bytes_list { value:[ "knit", "big" ] } } }
    feature { key:"gps" value { float_list { value:[] } } }
  },
  features {
    feature { key:"kw" value { bytes_list { value:[ "emmy" ] } } }
    feature { key:"dank" value { int64_list { value:[ 42 ] } } }
    feature { key:"gps" value { } }
  }
]

和参数

example_names:["input0", "input1"],
features:{
    "kw":VarLenFeature(tf.string),
    "dank":VarLenFeature(tf.int64),
    "gps":VarLenFeature(tf.float32),
}

然后输出是一个字典：

{
  "kw":SparseTensor(
      indices=[[0, 0], [0, 1], [1, 0]],
      values=["knit", "big", "emmy"]
      dense_shape=[2, 2]),
  "dank":SparseTensor(
      indices=[[1, 0]],
      values=[42],
      dense_shape=[2, 1]),
  "gps":SparseTensor(
      indices=[],
      values=[],
      dense_shape=[2, 0]),
}

对于两个序列化 Example 中的密集结果：

[
  features {
    feature { key:"age" value { int64_list { value:[ 0 ] } } }
    feature { key:"gender" value { bytes_list { value:[ "f" ] } } }
   },
   features {
    feature { key:"age" value { int64_list { value:[] } } }
    feature { key:"gender" value { bytes_list { value:[ "f" ] } } }
  }
]

我们可以使用参数：

example_names:["input0", "input1"],
features:{
    "age":FixedLenFeature([], dtype=tf.int64, default_value=-1),
    "gender":FixedLenFeature([], dtype=tf.string),
}

预期的输出是：

{
  "age":[[0], [-1]],
  "gender":[["f"], ["f"]],
}

VarLenFeature 获得 SparseTensor 的替代方法是 SparseFeature 。例如，给定 serialized 中的两个 Example 输入原型：

[
  features {
    feature { key:"val" value { float_list { value:[ 0.5, -1.0 ] } } }
    feature { key:"ix" value { int64_list { value:[ 3, 20 ] } } }
  },
  features {
    feature { key:"val" value { float_list { value:[ 0.0 ] } } }
    feature { key:"ix" value { int64_list { value:[ 42 ] } } }
  }
]

和参数

example_names:["input0", "input1"],
features:{
    "sparse":SparseFeature(
        index_key="ix", value_key="val", dtype=tf.float32, size=100),
}

然后输出是一个字典：

{
  "sparse":SparseTensor(
      indices=[[0, 3], [0, 20], [1, 42]],
      values=[0.5, -1.0, 0.0]
      dense_shape=[2, 100]),
}

有关如何使用 RaggedFeature 获取 RaggedTensor 的示例，请参阅 tf.io.RaggedFeature 文档。