tf.compat.v2.data.FixedLengthRecordDataset

A набор фиксированной длины записей из одного или нескольких двоичных файлов.

tf.compat.v2.data.FixedLengthRecordDataset(
    filenames, record_bytes, header_bytes=None, footer_bytes=None, buffer_size=None,
    compression_type=None, num_parallel_reads=None
)

Методы

apply

Просмотреть исходный код

apply(
    transformation_func
)

Применяет функцию преобразования к этому набору данных.

apply позволяет цеплять пользовательские Dataset преобразования, которые представлены как функции, принимающие один Dataset аргумент и возвращающие преобразованный Dataset.

Например:

dataset = (dataset.map(lambda x: x ** 2)
           .apply(group_by_window(key_func, reduce_func, window_size))
           .map(lambda x: x ** 3))

batch

Просмотреть исходный код

batch(
    batch_size, drop_remainder=False
)

Объединяет последовательные элементы этого набора данных в пакеты.

Компоненты результирующего элемента будут иметь дополнительное внешнее измерение, которое будет batch_size (или N % batch_size для последнего элемента, если batch_size не делит количество входных элементов N равномерно и drop_remainder является False). Если ваша программа зависит от того, что пакеты имеют одинаковое внешнее измерение, вы должны установить drop_remainder аргумент в True чтобы предотвратить создание меньшего пакета.

cache

Просмотреть исходный код

cache(
    filename=''
)

Кэширует элементы в этом наборе данных.

concatenate

Просмотреть исходный код

concatenate(
    dataset
)

Создаёт Dataset путём конкатенации заданного набора данных с этим набором данных.

a = Dataset.range(1, 4)  # ==> [ 1, 2, 3 ]
b = Dataset.range(4, 8)  # ==> [ 4, 5, 6, 7 ]

# The input dataset and dataset to be concatenated should have the same
# nested structures and output types.
# c = Dataset.range(8, 14).batch(2)  # ==> [ [8, 9], [10, 11], [12, 13] ]
# d = Dataset.from_tensor_slices([14.0, 15.0, 16.0])
# a.concatenate(c) and a.concatenate(d) would result in error.

a.concatenate(b)  # ==> [ 1, 2, 3, 4, 5, 6, 7 ]

enumerate

Просмотреть исходный код

enumerate(
    start=0
)

Пронумерует элементы этого набора данных.

Аналогично enumerate в Python.

Например:

# NOTE: The following examples use `{ ... }` to represent the
# contents of a dataset.
a = { 1, 2, 3 }
b = { (7, 8), (9, 10) }

# The nested structure of the `datasets` argument determines the
# structure of elements in the resulting dataset.
a.enumerate(start=5)) == { (5, 1), (6, 2), (7, 3) }
b.enumerate() == { (0, (7, 8)), (1, (9, 10)) }

filter

Просмотреть исходный код

filter(
    predicate
)

Фильтрация этого набора данных в соответствии с predicate.

d = tf.data.Dataset.from_tensor_slices([1, 2, 3])

d = d.filter(lambda x: x < 3)  # ==> [1, 2]

# `tf.math.equal(x, y)` is required for equality comparison
def filter_fn(x):
  return tf.math.equal(x, 1)

d = d.filter(filter_fn)  # ==> [1]

flat_map

Просмотреть исходный код

flat_map(
    map_func
)

Применяет map_func к этому набору данных и сглаживает результат.

Используйте flat_map если нужно убедиться, что порядок вашего набора данных сохранится. Например, для сглаживания набора данных пакетов в набор данных их элементов:

a = Dataset.from_tensor_slices([ [1, 2, 3], [4, 5, 6], [7, 8, 9] ])

a.flat_map(lambda x: Dataset.from_tensor_slices(x + 1)) # ==>
#  [ 2, 3, 4, 5, 6, 7, 8, 9, 10 ]

tf.data.Dataset.interleave() является обобщением flat_map, так как flat_map производит такой же результат, как tf.data.Dataset.interleave(cycle_length=1)

from_generator

Просмотреть исходный код

@staticmethod
from_generator(
    generator, output_types, output_shapes=None, args=None
)

Создаёт Dataset , элементы которого генерируются generator.

Аргумент generator должен быть вызываемым объектом, возвращающим объект, поддерживающий протокол iter() (например, генераторная функция). Элементы, генерируемые generator должны быть совместимы с заданными output_types и (необязательными) output_shapes аргументами.

Например:

import itertools
tf.compat.v1.enable_eager_execution()

def gen():
  for i in itertools.count(1):
    yield (i, [1] * i)

ds = tf.data.Dataset.from_generator(
    gen, (tf.int64, tf.int64), (tf.TensorShape([]), tf.TensorShape([None])))

for value in ds.take(2):
  print value
# (1, array([1]))
# (2, array([1, 1]))

Примечание: Текущая реализация Dataset.from_generator() использует tf.numpy_function и наследует те же ограничения. В частности, она требует, чтобы операции, связанные с Dataset и Iterator, были размещены на устройстве в том же процессе, что и Python-программа, вызывающая Dataset.from_generator(). Тело generator не будет сериализовано в GraphDef, и вам не следует использовать этот метод, если вам нужно сериализовать вашу модель и восстановить её в другой среде.

Примечание: Если generator зависит от изменяемых глобальных переменных или другого внешнего состояния, имейте в виду, что среда выполнения может вызывать generator несколько раз (для поддержки повторения Dataset) и в любое время между вызовом Dataset.from_generator() и производством первого элемента из генератора. Изменение глобальных переменных или внешнего состояния может привести к неопределённому поведению, и мы рекомендуем явным образом кэшировать любое внешнее состояние в generator перед вызовом Dataset.from_generator().

from_tensor_slices

Просмотр исходного кода

@staticmethod
from_tensor_slices(
    tensors
)

Создаёт Dataset, элементы которого являются срезами заданных тензоров.

Обратите внимание, что если tensors содержит массив NumPy, и режим выполнения eager не включён, значения будут встроены в граф как одна или несколько операций tf.constant. Для больших наборов данных (> 1 ГБ) это может привести к потере памяти и ограничению по размеру при сериализации графа. Если tensors содержит один или несколько больших массивов NumPy, рассмотрите альтернативный вариант, описанный в этом руководстве.

from_tensors

Просмотр исходного кода

@staticmethod
from_tensors(
    tensors
)

Создаёт Dataset с одним элементом, состоящим из заданных тензоров.

Обратите внимание, что если tensors содержит массив NumPy, и режим выполнения eager не включён, значения будут встроены в граф как одна или несколько операций tf.constant. Для больших наборов данных (> 1 ГБ) это может привести к потере памяти и ограничению по размеру при сериализации графа. Если tensors содержит один или несколько больших массивов NumPy, рассмотрите альтернативный вариант, описанный в этом руководстве.

interleave

Просмотр исходного кода

interleave(
    map_func, cycle_length=AUTOTUNE, block_length=1, num_parallel_calls=None
)

Применяет map_func к элементам этого набора данных и интерливирует результаты.

Например, вы можете использовать Dataset.interleave() для одновременной обработки многих входных файлов:

# Preprocess 4 files concurrently, and interleave blocks of 16 records from
# each file.
filenames = ["/var/data/file1.txt", "/var/data/file2.txt", ...]
dataset = (Dataset.from_tensor_slices(filenames)
           .interleave(lambda x:
               TextLineDataset(x).map(parse_fn, num_parallel_calls=1),
               cycle_length=4, block_length=16))

Аргументы cycle_length и block_length контролируют порядок вывода элементов. cycle_length управляет количеством входных элементов, обрабатываемых одновременно. Если вы установите cycle_length в 1, эта трансформация будет обрабатывать один входной элемент за раз и даст те же результаты, что и tf.data.Dataset.flat_map. В общем случае, эта трансформация применит map_func к cycle_length входным элементам, откроет итераторы на возвращённых Dataset объектах, и будет циклически проходить по ним, производя block_length последовательных элементов из каждого итератора, и потребляя следующий входной элемент каждый раз, когда достигает конца итератора.

Например:

a = Dataset.range(1, 6)  # ==> [ 1, 2, 3, 4, 5 ]

# NOTE: New lines indicate "block" boundaries.
a.interleave(lambda x: Dataset.from_tensors(x).repeat(6),
            cycle_length=2, block_length=4)  # ==> [1, 1, 1, 1,
                                             #      2, 2, 2, 2,
                                             #      1, 1,
                                             #      2, 2,
                                             #      3, 3, 3, 3,
                                             #      4, 4, 4, 4,
                                             #      3, 3,
                                             #      4, 4,
                                             #      5, 5, 5, 5,
                                             #      5, 5]

Примечание: Порядок элементов, возвращаемых этой трансформацией, является детерминированным, если map_func является чистой функцией. Если map_func содержит какие-либо операции с состоянием, порядок доступа к этому состоянию не определён.

list_files

Просмотр исходного кода

@staticmethod
list_files(
    file_pattern, shuffle=None, seed=None
)

Набор данных всех файлов, соответствующих одному или нескольким шаблонам glob.

Примечание: По умолчанию этот метод возвращает имена файлов в случайном, не детерминированном порядке. Передайте seed или shuffle=False для получения результатов в детерминированном порядке.

Пример:

Если у нас на файловой системе есть следующие файлы:

• /path/to/dir/a.txt
• /path/to/dir/b.py
• /path/to/dir/c.py Если мы передадим "/path/to/dir/*.py" как каталог, набор данных вернёт:
• /path/to/dir/b.py
• /path/to/dir/c.py

map

Просмотр исходного кода

map(
    map_func, num_parallel_calls=None
)

Применяет map_func к элементам этого набора данных.

Эта трансформация применяет map_func к каждому элементу этого набора данных и возвращает новый набор данных, содержащий преобразованные элементы в том же порядке, что и в исходном наборе.

Например:

a = Dataset.range(1, 6)  # ==> [ 1, 2, 3, 4, 5 ]

a.map(lambda x: x + 1)  # ==> [ 2, 3, 4, 5, 6 ]

Подпись входных данных map_func определяется структурой каждого элемента в этом наборе данных. Например:

# NOTE: The following examples use `{ ... }` to represent the
# contents of a dataset.
# Each element is a `tf.Tensor` object.
a = { 1, 2, 3, 4, 5 }
# `map_func` takes a single argument of type `tf.Tensor` with the same
# shape and dtype.
result = a.map(lambda x: ...)

# Each element is a tuple containing two `tf.Tensor` objects.
b = { (1, "foo"), (2, "bar"), (3, "baz") }
# `map_func` takes two arguments of type `tf.Tensor`.
result = b.map(lambda x_int, y_str: ...)

# Each element is a dictionary mapping strings to `tf.Tensor` objects.
c = { {"a": 1, "b": "foo"}, {"a": 2, "b": "bar"}, {"a": 3, "b": "baz"} }
# `map_func` takes a single argument of type `dict` with the same keys as
# the elements.
result = c.map(lambda d: ...)

Значение или значения, возвращаемые map_func , определяют структуру каждого элемента в возвращаемом наборе данных.

# `map_func` returns a scalar `tf.Tensor` of type `tf.float32`.
def f(...):
  return tf.constant(37.0)
result = dataset.map(f)
result.output_classes == tf.Tensor
result.output_types == tf.float32
result.output_shapes == []  # scalar

# `map_func` returns two `tf.Tensor` objects.
def g(...):
  return tf.constant(37.0), tf.constant(["Foo", "Bar", "Baz"])
result = dataset.map(g)
result.output_classes == (tf.Tensor, tf.Tensor)
result.output_types == (tf.float32, tf.string)
result.output_shapes == ([], [3])

# Python primitives, lists, and NumPy arrays are implicitly converted to
# `tf.Tensor`.
def h(...):
  return 37.0, ["Foo", "Bar", "Baz"], np.array([1.0, 2.0] dtype=np.float64)
result = dataset.map(h)
result.output_classes == (tf.Tensor, tf.Tensor, tf.Tensor)
result.output_types == (tf.float32, tf.string, tf.float64)
result.output_shapes == ([], [3], [2])

# `map_func` can return nested structures.
def i(...):
  return {"a": 37.0, "b": [42, 16]}, "foo"
result.output_classes == ({"a": tf.Tensor, "b": tf.Tensor}, tf.Tensor)
result.output_types == ({"a": tf.float32, "b": tf.int32}, tf.string)
result.output_shapes == ({"a": [], "b": [2]}, [])

map_func может принимать в качестве аргументов и возвращать любой тип элемента набора данных.

Обратите внимание, что независимо от контекста, в котором определен map_func (жадный или графический), tf.data отслеживает функцию и выполняет её как граф. Чтобы использовать код Python внутри функции, у вас есть два варианта:

1) Воспользуйтесь AutoGraph для преобразования кода Python в эквивалентное вычисление графа. Недостатком этого подхода является то, что AutoGraph может преобразовать некоторые, но не все фрагменты кода Python.

2) Используйте tf.py_function, что позволит вам написать произвольный код Python, но, как правило, это приведет к худшей производительности, чем вариант 1). Например:

d = tf.data.Dataset.from_tensor_slices(['hello', 'world'])

# transform a string tensor to upper case string using a Python function
def upper_case_fn(t: tf.Tensor) -> str:
    return t.numpy().decode('utf-8').upper()

d.map(lambda x: tf.py_function(func=upper_case_fn,
      inp=[x], Tout=tf.string))  # ==> [ "HELLO", "WORLD" ]

options

Просмотреть исходный код

options()

Возвращает параметры для этого набора данных и его входных данных.

padded_batch

Просмотреть исходный код

padded_batch(
    batch_size, padded_shapes, padding_values=None, drop_remainder=False
)

Объединяет последовательные элементы этого набора данных в заполненные пакеты.

Это преобразование объединяет несколько последовательных элементов входного набора данных в один элемент.

Подобно tf.data.Dataset.batch, компоненты результирующего элемента будут иметь дополнительное внешнее измерение, которое будет batch_size (или N % batch_size для последнего элемента, если batch_size не делит количество входных элементов N нацело, и drop_remainder является False). Если ваша программа зависит от того, чтобы пакеты имели одинаковое внешнее измерение, вы должны установить аргумент drop_remainder в True, чтобы предотвратить создание меньшего пакета.

В отличие от tf.data.Dataset.batch, входные элементы для пакетирования могут иметь разные формы, и это преобразование заполнит каждый компонент до соответствующей формы в padding_shapes. Аргумент padding_shapes определяет результирующую форму для каждого измерения каждого компонента в элементе вывода:

• Если измерение является постоянным (например, tf.compat.v1.Dimension(37)), компонент будет заполнен до этого размера в этом измерении.
• Если измерение неизвестно (например, tf.compat.v1.Dimension(None)), компонент будет заполнен до максимальной длины всех элементов в этом измерении.

См. также tf.data.experimental.dense_to_sparse_batch, который объединяет элементы, которые могут иметь разные формы, в tf.SparseTensor.

prefetch

Просмотреть исходный код

prefetch(
    buffer_size
)

Создаёт Dataset , который предварительно загружает элементы из этого набора данных.

Примечание: Как и другие методы Dataset, prefetch работает с элементами входного набора данных. У него нет понятия примеров и пакетов. examples.prefetch(2) предварительно загрузит два элемента (2 примера), в то время как examples.batch(20).prefetch(2) предварительно загрузит 2 элемента (2 пакета по 20 примеров каждый).

range

Просмотреть исходный код

@staticmethod
range(
    *args
)

Создаёт Dataset диапазона значений с шагом.

Например:

Dataset.range(5) == [0, 1, 2, 3, 4]
Dataset.range(2, 5) == [2, 3, 4]
Dataset.range(1, 5, 2) == [1, 3]
Dataset.range(1, 5, -2) == []
Dataset.range(5, 1) == []
Dataset.range(5, 1, -2) == [5, 3]

reduce

Просмотреть исходный код

reduce(
    initial_state, reduce_func
)

Сокращает входной набор данных до одного элемента.

Преобразование последовательно вызывает reduce_func на каждом элементе входного набора данных до тех пор, пока набор данных не будет исчерпан, аккумулируя информацию во внутренней состоянии. Аргумент initial_state используется для начального состояния, а конечное состояние возвращается как результат.

Например:

• tf.data.Dataset.range(5).reduce(np.int64(0), lambda x, _: x + 1) производит 5
• tf.data.Dataset.range(5).reduce(np.int64(0), lambda x, y: x + y) производит 10

repeat

Просмотреть исходный код

repeat(
    count=None
)

Повторяет этот набор данных count раз.

Примечание: Если этот набор данных зависит от глобального состояния (например, от генератора случайных чисел), то различные повторения могут производить разные элементы.

shard

Просмотреть исходный код

shard(
    num_shards, index
)

Создаёт набор данных Dataset, включающий только 1/num_shards часть исходного набора данных.

Этот оператор набора данных очень полезен при распределённом обучении, так как позволяет каждому рабочему узлу читать уникальный подмножество.

При чтении одного входного файла вы можете пропустить элементы следующим образом:

d = tf.data.TFRecordDataset(input_file)
d = d.shard(num_workers, worker_index)
d = d.repeat(num_epochs)
d = d.shuffle(shuffle_buffer_size)
d = d.map(parser_fn, num_parallel_calls=num_map_threads)

Важные замечания:

• Убедитесь, что оператор фрагментации используется до применения любых случайных операторов (таких как перемешивание).
• В общем случае лучше всего использовать оператор фрагментации на ранней стадии обработки набора данных. Например, при чтении из набора файлов TFRecord, фрагментируйте набор данных перед преобразованием его в входные образцы. Это предотвращает чтение каждого файла на каждом рабочем узле. Следующее является примером эффективной стратегии фрагментации в полной обработке набора данных:

d = Dataset.list_files(pattern)
d = d.shard(num_workers, worker_index)
d = d.repeat(num_epochs)
d = d.shuffle(shuffle_buffer_size)
d = d.interleave(tf.data.TFRecordDataset,
                 cycle_length=num_readers, block_length=1)
d = d.map(parser_fn, num_parallel_calls=num_map_threads)

shuffle

Просмотреть исходный код

shuffle(
    buffer_size, seed=None, reshuffle_each_iteration=None
)

Случайным образом перемешивает элементы в этом наборе данных.

Этот набор данных заполняет буфер элементами buffer_size, затем случайным образом выбирает элементы из этого буфера, заменяя выбранные элементы новыми элементами. Для идеального перемешивания требуется размер буфера, большего или равного полному размеру набора данных.

Например, если ваш набор данных содержит 10 000 элементов, но buffer_size установлено в 1000, тогда shuffle изначально выберет случайный элемент только из первых 1000 элементов в буфере. После выбора элемента, его место в буфере замещается следующим (т.е. 1001-м) элементом, поддерживая буфер размером 1000 элементов.

skip

Просмотреть исходный код

skip(
    count
)

Создаёт набор данных Dataset, пропускающий count элементов из этого набора данных.

take

Просмотреть исходный код

take(
    count
)

Создаёт набор данных Dataset, содержащий не более count элементов из этого набора данных.

unbatch

Просмотреть исходный код

unbatch()

Разделяет элементы набора данных на несколько элементов.

Например, если элементы набора данных имеют форму [B, a0, a1, ...], где B может изменяться для каждого входного элемента, то для каждого элемента в наборе данных, набор данных unbatch будет содержать B последовательных элементов формы [a0, a1, ...].

# NOTE: The following example uses `{ ... }` to represent the contents
# of a dataset.
ds = { ['a', 'b', 'c'], ['a', 'b'], ['a', 'b', 'c', 'd'] }

ds.unbatch() == {'a', 'b', 'c', 'a', 'b', 'a', 'b', 'c', 'd'}

window

Просмотреть исходный код

window(
    size, shift=None, stride=1, drop_remainder=False
)

Объединяет (вложенные) входные элементы в набор данных (вложенных) окон.

«Окно» — это конечный набор данных плоских элементов размера size (или возможно меньше, если нет достаточного количества входных элементов для заполнения окна и drop_remainder имеет значение false).

Аргумент stride определяет шаг входных элементов, а аргумент shift определяет сдвиг окна.

Например, пусть {...} представляет набор данных:

• tf.data.Dataset.range(7).window(2) производит { {0, 1}, {2, 3}, {4, 5}, {6} }
• tf.data.Dataset.range(7).window(3, 2, 1, True) производит { {0, 1, 2}, {2, 3, 4}, {4, 5, 6} }
• tf.data.Dataset.range(7).window(3, 1, 2, True) производит { {0, 2, 4}, {1, 3, 5}, {2, 4, 6} }

Обратите внимание, что когда преобразование window применяется к набору данных вложенных элементов, оно производит набор данных вложенных окон.

Например:

• tf.data.Dataset.from_tensor_slices((range(4), range(4))).window(2) производит {({0, 1}, {0, 1}), ({2, 3}, {2, 3})}
• tf.data.Dataset.from_tensor_slices({"a": range(4)}).window(2) производит { {"a": {0, 1} }, {"a": {2, 3} } }

with_options

Просмотреть исходный код

with_options(
    options
)

Возвращает новый tf.data.Dataset с заданными параметрами.

Параметры «глобальные» в том смысле, что они применяются ко всему набору данных. Если параметры заданы несколько раз, они объединяются, при условии, что разные параметры не используют разные значения, отличные от значений по умолчанию.

zip

Просмотреть исходный код

@staticmethod
zip(
    datasets
)

Создает Dataset путем объединения заданных наборов данных.

Этот метод имеет семантику, аналогичную встроенной функции zip() в Python, с основным отличием, заключающимся в том, что аргумент datasets может быть произвольной вложенной структурой объектов Dataset. Например:

a = Dataset.range(1, 4)  # ==> [ 1, 2, 3 ]
b = Dataset.range(4, 7)  # ==> [ 4, 5, 6 ]
c = Dataset.range(7, 13).batch(2)  # ==> [ [7, 8], [9, 10], [11, 12] ]
d = Dataset.range(13, 15)  # ==> [ 13, 14 ]

# The nested structure of the `datasets` argument determines the
# structure of elements in the resulting dataset.
Dataset.zip((a, b))  # ==> [ (1, 4), (2, 5), (3, 6) ]
Dataset.zip((b, a))  # ==> [ (4, 1), (5, 2), (6, 3) ]

# The `datasets` argument may contain an arbitrary number of
# datasets.
Dataset.zip((a, b, c))  # ==> [ (1, 4, [7, 8]),
                        #       (2, 5, [9, 10]),
                        #       (3, 6, [11, 12]) ]

# The number of elements in the resulting dataset is the same as
# the size of the smallest dataset in `datasets`.
Dataset.zip((a, d))  # ==> [ (1, 13), (2, 14) ]

__iter__

Просмотреть исходный код

__iter__()

Создает Iterator для перечисления элементов этого набора данных.

Возвращаемый итератор реализует протокол Python-итератора и поэтому может использоваться только в режиме eager.