TensorFlow函数教程：tf.io.parse_example

tf.io.parse_example函数

别名：

• tf.io.parse_example
• tf.parse_example

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

定义在：tensorflow/python/ops/parsing_ops.py。

将Example原型解析为张量的dict。

解析serialized中给出的一些序列化Example原型。我们将serialized称为具有batch_size的批处理，单个Example原型的许多条目。

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

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

每个VarLenFeature映射到指定类型的SparseTensor，表示不规则矩阵。它的索引是[batch, index]，其中batch标识serialized中的例子，并且index是与该功能和示例关联的值列表中的值索引。

每个SparseFeature映射到指定类型的SparseTensor，表示dense_shape [batch_size] + SparseFeature.size的Tensor。它values来自带有value_key键的示例中的功能。values[i]来自批处理输入batch的示例的功能中的位置k。该位置信息在indices[i]中记录为[batch, index_0, index_1, ...]，其中index_j是具有键SparseFeature.index_key [j]的示例中的功能的第k个值。换句话说，我们将SparseTensorby维度的索引（指示批处理输入的第一个索引除外）拆分为Example的不同的特征。由于其复杂性，VarLenFeature应尽可能优先于SparseFeature。

每个FixedLenFeature df映射到指定类型（如果未指定，则为tf.float32）的Tensor并且具有shape (serialized.size(),) + df.shape。

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

每个FixedLenSequenceFeature df映射到指定类型的Tensor（如果未指定则为tf.float32）并且具有shape (serialized.size(), None) + df.shape。serialized中的所有示例将在第二维上使用default_value填充。

例子：

例如，如果需要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代替FixedLenSequenceFeature，并且使用shape=[]，那么输出将如下所示：

{"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"]],
}

用于获取SparseTensor的VarLenFeature的替代方法是SparseFeature。例如，给定两个serialized的示例输入原型：

[
  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]),
}

参数：

• serialized：一个字符串的向量（1-D Tensor），一批二进制序列化的Example原型。
• features：一个dict映射功能键到FixedLenFeature， VarLenFeature和SparseFeature的值。
• name：此操作的名称（可选）。
• example_names：字符串的向量（1-D Tensor）（可选），批处理中序列化原型的名称。

返回：

一个dict映射功能键到Tensor和SparseTensor值。

可能引发的异常：

• ValueError：如果任何功能无效。