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 文檔。