tf.io.decode_proto

Операция извлекает поля из сериализованного сообщения protocol buffers в тензоры.

tf.io.decode_proto(
    bytes: Annotated[Any, _atypes.String],
    message_type: str,
    field_names,
    output_types,
    descriptor_source: str = 'local://',
    message_format: str = 'binary',
    sanitize: bool = False,
    name=None
)

Примечание: этот API разработан с упором на ортогональность, а не на удобство использования. Его можно применять для ручного анализа входных proto-сообщений, однако он предназначен для использования в сгенерированном коде.

Операция decode_proto извлекает поля из сериализованного сообщения protocol buffers в тензоры. Поля в field_names декодируются и, если возможно, преобразуются в соответствующие output_types.

Чтобы задать контекст для имен полей, необходимо указать имя message_type. Дескриптор самого сообщения можно найти либо в связанной с бинарным файлом таблице дескрипторов, либо в файле, указанном вызывающим кодом с помощью атрибута descriptor_source.

Каждый выходной тензор является плотным тензором. Это означает, что в нем есть дополнение, позволяющее вместить наибольшее количество повторяющихся элементов, обнаруженных во входном мини-пакете. (Размерность также дополнена на единицу, чтобы избежать размерностей нулевого размера.) Фактическое количество повторений для каждого примера в мини-пакете можно найти в выходе sizes. Во многих случаях результат decode_proto сразу передается в tf.squeeze, если наличие отсутствующих значений не имеет значения. При использовании tf.squeeze всегда явно указывайте размерность, по которой нужно выполнить сжатие, чтобы избежать неожиданностей.

В большинстве случаев соответствие между типами полей Proto и типами данных TensorFlow очевидно. Однако есть несколько особых случаев:

• Поле proto, содержащее подсообщение или группу, можно преобразовать только в DT_STRING (сериализованное подсообщение). Это позволяет уменьшить сложность API. Полученную строку можно использовать в качестве входных данных для другого экземпляра операции decode_proto.

• TensorFlow не поддерживает беззнаковые целые числа. Операции представляют типы uint64 как DT_INT64 с тем же битовым шаблоном в дополнительном коде (очевидный способ). Значения uint32 можно точно представить, указав тип DT_INT64 или используя дополнительный код, если вызывающий код задает DT_INT32 в атрибуте output_types.

• Поля map не декодируются напрямую. Они обрабатываются как поля repeated соответствующего типа записи. Компилятор proto определяет типы записей для каждого поля map. Имя типа совпадает с именем поля, преобразованным в "CamelCase", к которому добавлено "Entry". Сообщение tf.train.Features.FeatureEntry — пример одного из таких неявных типов Entry.

• Поля enum следует считывать как int32.

Поддерживаются как двоичная, так и текстовая сериализация proto; нужный формат можно выбрать с помощью атрибута format.

Атрибут descriptor_source задает источник дескрипторов протокола, используемый для поиска message_type. Возможны следующие варианты:

• Пустая строка или "local://": в этом случае дескрипторы протокола создаются для определений proto на C++ (но не на Python), связанных с бинарным файлом.

• Файл: в этом случае дескрипторы протокола создаются из файла, который должен содержать FileDescriptorSet, сериализованный в виде строки. ПРИМЕЧАНИЕ. Файл descriptor_source можно создать с помощью параметров --descriptor_set_out и --include_imports компилятора протокола protoc.

• "bytes://": в этом случае дескрипторы протокола создаются из <bytes>, которое должно быть FileDescriptorSet, сериализованным в виде строки.

Пример:

Внутренний proto Summary.Value содержит oneof {float simple_value; Image image; ...}

from google.protobuf import text_format

# A Summary.Value contains: oneof {float simple_value; Image image}
values = [
   "simple_value: 2.2",
   "simple_value: 1.2",
   "image { height: 128 width: 512 }",
   "image { height: 256 width: 256 }",]
values = [
   text_format.Parse(v, tf.compat.v1.Summary.Value()).SerializeToString()
   for v in values]

Следующий код декодирует оба поля из сериализованных строк:

sizes, [simple_value, image]  = tf.io.decode_proto(
 values,
 tf.compat.v1.Summary.Value.DESCRIPTOR.full_name,
 field_names=['simple_value', 'image'],
 output_types=[tf.float32, tf.string])

Тензор sizes имеет ту же форму, что и входной тензор, с дополнительной осью для декодированных полей. Здесь первый столбец sizes содержит размер декодированного поля simple_value:

print(sizes)
tf.Tensor(
[[1 0]
 [1 0]
 [0 1]
 [0 1]], shape=(4, 2), dtype=int32)

Каждый результирующий тензор имеет на один индекс больше, чем входные байтовые строки. Допустимые элементы каждого результирующего тензора указаны в соответствующем столбце sizes. Недопустимые элементы дополняются значением по умолчанию:

print(simple_value)
tf.Tensor(
[[2.2]
 [1.2]
 [0. ]
 [0. ]], shape=(4, 1), dtype=float32)

Вложенные proto извлекаются в виде строковых тензоров:

print(image.dtype)
<dtype: 'string'>
print(image.shape.as_list())
[4, 1]

Чтобы преобразовать результат в представление tf.RaggedTensor, используйте:

tf.RaggedTensor.from_tensor(simple_value, lengths=sizes[:, 0]).to_list()
[[2.2], [1.2], [], []]