tf.compat.v1.parse_example

Разбирает протобуфы Example в dict тензоров.

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

Разбирает заданное количество сериализованных протобуфов Example, переданных в serialized. Мы рассматриваем serialized как пакет с batch_size множеством записей из отдельных протобуфов Example.

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] берется из позиции k признака примера с записью пакета batch. Эта позиционная информация записывается в 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.

Записи FixedLenFeature с default_value являются необязательными. Если значение по умолчанию не задано, операция завершится ошибкой, если этот Feature отсутствует хотя бы в одном примере из serialized.

Каждый 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.

Примеры:

Например, если ожидается ft типа tf.float32 с VarLenFeature, а переданы три сериализованных объекта 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)) }

Если вместо этого используется FixedLenSequenceFeature с default_value = -1.0 и shape=[], результат будет выглядеть так:

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

Для двух входных протобуфов Example в serialized:

[
  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. Например, для двух входных протобуфов Example в 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]),
}

Примеры получения RaggedTensorов с помощью RaggedFeature см. в документации по tf.io.RaggedFeature.