tf.parse_example 函数

parse_example(
    serialized,
    features,
    name=None,
    example_names=None
)

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

请参阅指南：输入和读取器>协议缓冲区示例

把 Example 原型解析成张量字典.

解析 serialized 中给定的一系列序列化 Example 原型.我们提到的 serialized 作为一个批次与 batch_size 的许多条目的个别 Example 原型.

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

这个 op 将序列化的例子解析成一个用于 Tensor 和 SparseTensor 对象的字典映射键.features 是从键到 VarLenFeature、SparseFeature 和 FixedLenFeature 对象的字典.每个 VarLenFeature 和 SparseFeature 被映射到一个 SparseTensor,每个 FixedLenFeature 被映射到一个 Tensor.

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

每个 SparseFeature 映射到指定类型的 SparseTensor,表示 dense_shape [batch_size] + SparseFeature.size 的张量.它的值来自于示例中具有键 value_key 的特征.values[i] 来自于一个在批处理条目批次的例子中的位置 k.该位置信息作为 [batch, index_0, index_1, ...] 被记录在 indices[i] 中,其中 index_j 是该特征的 k-th,在示例中使用键 SparseFeature. index_key [j].也就是说,我们将 aSparseTensorby 的索引(表示批输入的第一个指数除外) 按照维度 分解为例的不同特征.由于其复杂性 aVarLenFeature 应优先于 aSparseFeature(只要有可能的话).

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

带有 default_value 的 FixedLenFeature 条目是可选的.如果没有默认值,则在 serialized 的任何示例中缺少该 Feature 时,我们将失败.

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

示例-1

例如,如果提供了一个 tf.float32 VarLenFeature ft 和三个序列化的 Examples：

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)) }

如果使用 FixedLenSequenceFeaturewith default_value = -1.0 和 shape=[],那么输出将如下所示：

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

示例-2

给出两个在 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 { } }
  }
]

和论据(arguments)：

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

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

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

示例-3

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

参数：

• serialized：一个字符串类型的向量(一维张量),一组二进制序列化 Example 原型.
• features：FixedLenFeature、VarLenFeature 和 SparseFeature 值的字典映射功能键.
• name：此操作的名称(可选).
• example_names：一个字符串类型的向量(一维张量)(可选),批处理中的序列化原型的名称.

返回：

映射功能键到 Tensor 和 SparseTensor 值的字典.

可能引发的异常：

• ValueError：如果存在任何功能无效.