Python tf.io.RaggedFeature用法及代碼示例

用於傳遞 RaggedTensor 輸入函數的配置。

用法

tf.io.RaggedFeature(
    dtype, value_key=None, partitions=(), row_splits_dtype=tf.dtypes.int32,
    validate=False
)

value_key 為可變長度的值列表指定特征鍵； partitions 指定零個或多個特征鍵，用於將這些值劃分為更高的維度。 partitions 的每個元素必須是以下之一：

• tf.io.RaggedFeature.RowSplits(key:string)
• tf.io.RaggedFeature.RowLengths(key:string)
• tf.io.RaggedFeature.RowStarts(key:string)
• tf.io.RaggedFeature.RowLimits(key:string)
• tf.io.RaggedFeature.ValueRowIds(key:string)
• tf.io.RaggedFeature.UniformRowLength(length:int) 。

其中key 是一個特征鍵，其值用於對值進行分區。分區從最外到最內列出。

• 如果len(partitions) == 0(默認)，那麽：

  • 來自單個 tf.Example 的特征被解析為一維 tf.Tensor 。
  • 一批 tf.Example 中的特征被解析為 2D tf.RaggedTensor ，其中外部維度是批次維度，內部(不規則)維度是每個示例中的特征長度。

• 如果 len(partitions) == 1 ，則：

  • 來自單個 tf.Example 的特征被解析為 2D tf.RaggedTensor ，其中從 value_key 獲取的值使用分區鍵分隔成行。
  • 一批 tf.Example 的特征被解析為 3D tf.RaggedTensor ，其中外部維度是批次維度，兩個內部維度是通過使用該示例的分區將每個示例的 value_key 值分成行來形成的鑰匙。

• 如果 len(partitions) > 1 ，則：

  • 來自單個 tf.Example 的特征被解析為 tf.RaggedTensor ，其等級為 len(partitions)+1 ，其 ragged_rank 為 len(partitions) 。

  • 來自一批 tf.Example 的特征被解析為 tf.RaggedTensor，其排名為 len(partitions)+2 並且其 ragged_rank 為 len(partitions)+1 ，其中外部維度是批次維度。

有一個異常：如果 partitions 的最後一個(即最裏麵的)元素是 UniformRowLength ，那麽這些值會被簡單地重新整形(作為更高維的 tf.Tensor )，而不是被包在一個tf.RaggedTensor 。

例子

import google.protobuf.text_format as pbtext
example_batch = [
  pbtext.Merge(r'''
    features {
      feature {key:"v" value {int64_list {value:[3, 1, 4, 1, 5, 9]} } }
      feature {key:"s1" value {int64_list {value:[0, 2, 3, 3, 6]} } }
      feature {key:"s2" value {int64_list {value:[0, 2, 3, 4]} } }
    }''', tf.train.Example()).SerializeToString(),
  pbtext.Merge(r'''
    features {
      feature {key:"v" value {int64_list {value:[2, 7, 1, 8, 2, 8, 1]} } }
      feature {key:"s1" value {int64_list {value:[0, 3, 4, 5, 7]} } }
      feature {key:"s2" value {int64_list {value:[0, 1, 1, 4]} } }
    }''', tf.train.Example()).SerializeToString()]

features = {
    # Zero partitions:returns 1D tf.Tensor for each Example.
    'f1':tf.io.RaggedFeature(value_key="v", dtype=tf.int64),
    # One partition:returns 2D tf.RaggedTensor for each Example.
    'f2':tf.io.RaggedFeature(value_key="v", dtype=tf.int64, partitions=[
        tf.io.RaggedFeature.RowSplits("s1")]),
    # Two partitions:returns 3D tf.RaggedTensor for each Example.
    'f3':tf.io.RaggedFeature(value_key="v", dtype=tf.int64, partitions=[
        tf.io.RaggedFeature.RowSplits("s2"),
        tf.io.RaggedFeature.RowSplits("s1")])
}

feature_dict = tf.io.parse_single_example(example_batch[0], features)
for (name, val) in sorted(feature_dict.items()):
  print('%s:%s' % (name, val))
f1:tf.Tensor([3 1 4 1 5 9], shape=(6,), dtype=int64)
f2:<tf.RaggedTensor [[3, 1], [4], [], [1, 5, 9]]>
f3:<tf.RaggedTensor [[[3, 1], [4]], [[]], [[1, 5, 9]]]>

feature_dict = tf.io.parse_example(example_batch, features)
for (name, val) in sorted(feature_dict.items()):
  print('%s:%s' % (name, val))
f1:<tf.RaggedTensor [[3, 1, 4, 1, 5, 9],
                      [2, 7, 1, 8, 2, 8, 1]]>
f2:<tf.RaggedTensor [[[3, 1], [4], [], [1, 5, 9]],
                      [[2, 7, 1], [8], [2], [8, 1]]]>
f3:<tf.RaggedTensor [[[[3, 1], [4]], [[]], [[1, 5, 9]]],
                      [[[2, 7, 1]], [], [[8], [2], [8, 1]]]]>

領域：

• dtype:數據類型RaggedTensor.必須是以下之一：tf.dtypes.int64,tf.dtypes.float32,tf.dtypes.string.
• value_key：(可選。) key Feature在輸入Example, 其解析Tensor將是結果RaggedTensor.flat_values.如果未指定，則默認為此鍵RaggedFeature.
• partitions：(可選。)指定row-partitioning張量的對象列表(從最外層到最內層)。此列表中的每個條目必須是以下之一：
  • tf.io.RaggedFeature.RowSplits(key:string)
  • tf.io.RaggedFeature.RowLengths(key:string)
  • tf.io.RaggedFeature.RowStarts(key:string)
  • tf.io.RaggedFeature.RowLimits(key:string)
  • tf.io.RaggedFeature.ValueRowIds(key:string)
  • tf.io.RaggedFeature.UniformRowLength(length:int) 。其中 key 是輸入 Example 中 Feature 的鍵，其解析後的 Tensor 將是生成的 row-partitioning 張量。
• row_splits_dtype：(可選。)row-partitioning 張量的數據類型。之一int32或者int64.默認為int32.
• validate：(可選。)布爾值，指示是否驗證輸入值形成有效的 RaggedTensor。默認為False.

子類

class RowLengths

class RowLimits

class RowSplits

class RowStarts

class UniformRowLength

class ValueRowIds