tf.data.Dataset

Представляет потенциально большой набор элементов.

tf.data.Dataset(
    variant_tensor
)

API tf.data.Dataset поддерживает создание описательных и эффективных конвейеров ввода. Dataset использование следует общему шаблону:

1. Создайте исходный датасет из ваших входных данных.
2. Примените преобразования датасета для предварительной обработки данных.
3. Итерируйтесь по датасету и обрабатывайте элементы.

Итерация происходит в потоковом режиме, поэтому весь датасет не обязательно должен помещаться в оперативную память.

Исходные наборы данных:

Самый простой способ создать датасет — создать его из Python list:

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
for element in dataset:
  print(element)
tf.Tensor(1, shape=(), dtype=int32)
tf.Tensor(2, shape=(), dtype=int32)
tf.Tensor(3, shape=(), dtype=int32)

Для обработки строк из файлов используйте tf.data.TextLineDataset:

dataset = tf.data.TextLineDataset(["file1.txt", "file2.txt"])

Для обработки записей, записанных в формате TFRecord, используйте TFRecordDataset:

dataset = tf.data.TFRecordDataset(["file1.tfrecords", "file2.tfrecords"])

Для создания набора данных всех файлов, соответствующих шаблону, используйте tf.data.Dataset.list_files:

dataset = tf.data.Dataset.list_files("/path/*.txt")  # doctest: +SKIP

См. tf.data.FixedLengthRecordDataset и tf.data.Dataset.from_generator для получения дополнительных способов создания наборов данных.

Преобразования:

После получения набора данных вы можете применить преобразования для подготовки данных для вашей модели:

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
dataset = dataset.map(lambda x: x*2)
list(dataset.as_numpy_iterator())
[2, 4, 6]

Общие термины:

Элемент: единственный результат вызова next() на итераторе датасета. Элементы могут быть вложенными структурами, содержащими несколько компонентов. Например, элемент (1, (3, "apple")) имеет один кортеж, вложенный в другой кортеж. Компонентами являются 1, 3, и "apple".

Компонент: лист во вложенной структуре элемента.

Поддерживаемые типы:

Элементы могут быть вложенными структурами кортежей, именованных кортежей и словарей. Обратите внимание, что списки Python не обрабатываются как вложенные структуры компонентов. Вместо этого списки преобразуются в тензоры и обрабатываются как компоненты. Например, элемент (1, [1, 2, 3]) имеет только два компонента; тензор 1 и тензор [1, 2, 3]. Компоненты элементов могут быть любого типа, представимого tf.TypeSpec, включая tf.Tensor, tf.data.Dataset, tf.sparse.SparseTensor, tf.RaggedTensor и tf.TensorArray.

a = 1 # Integer element
b = 2.0 # Float element
c = (1, 2) # Tuple element with 2 components
d = {"a": (2, 2), "b": 3} # Dict element with 3 components
Point = collections.namedtuple("Point", ["x", "y"]) # doctest: +SKIP
e = Point(1, 2) # Named tuple # doctest: +SKIP
f = tf.data.Dataset.range(10) # Dataset element

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
dataset.element_spec
TensorSpec(shape=(), dtype=tf.int32, name=None)

Методы

apply

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

apply(
    transformation_func
)

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

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

dataset = tf.data.Dataset.range(100)
def dataset_fn(ds):
  return ds.filter(lambda x: x < 5)
dataset = dataset.apply(dataset_fn)
list(dataset.as_numpy_iterator())
[0, 1, 2, 3, 4]

as_numpy_iterator

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

as_numpy_iterator()

Возвращает итератор, который преобразует все элементы набора данных в NumPy.

Используйте as_numpy_iterator для просмотра содержимого вашего набора данных. Чтобы увидеть формы и типы элементов, печатайте элементы набора данных напрямую, а не используйте as_numpy_iterator.

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
for element in dataset:
  print(element)
tf.Tensor(1, shape=(), dtype=int32)
tf.Tensor(2, shape=(), dtype=int32)
tf.Tensor(3, shape=(), dtype=int32)

Этот метод требует, чтобы вы выполняли код в режиме eager и спецификация элемента набора данных содержала только TensorSpec компоненты.

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
for element in dataset.as_numpy_iterator():
  print(element)
1
2
3

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
print(list(dataset.as_numpy_iterator()))
[1, 2, 3]

as_numpy_iterator() сохранит вложенную структуру элементов набора данных.

dataset = tf.data.Dataset.from_tensor_slices({'a': ([1, 2], [3, 4]),
                                              'b': [5, 6]})
list(dataset.as_numpy_iterator()) == [{'a': (1, 3), 'b': 5},
                                      {'a': (2, 4), 'b': 6}]
True

batch

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

batch(
    batch_size, drop_remainder=False
)

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

dataset = tf.data.Dataset.range(8)
dataset = dataset.batch(3)
list(dataset.as_numpy_iterator())
[array([0, 1, 2]), array([3, 4, 5]), array([6, 7])]

dataset = tf.data.Dataset.range(8)
dataset = dataset.batch(3, drop_remainder=True)
list(dataset.as_numpy_iterator())
[array([0, 1, 2]), array([3, 4, 5])]

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

cache

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

cache(
    filename=''
)

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

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

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

dataset = tf.data.Dataset.range(5)
dataset = dataset.map(lambda x: x**2)
dataset = dataset.cache()
# The first time reading through the data will generate the data using
# `range` and `map`.
list(dataset.as_numpy_iterator())
[0, 1, 4, 9, 16]
# Subsequent iterations read from the cache.
list(dataset.as_numpy_iterator())
[0, 1, 4, 9, 16]

При кэшировании в файл кэшированные данные будут сохраняться между запусками. Даже первая итерация по данным будет читать данные из файла кэша. Изменение конвейера ввода данных до вызова .cache() не повлияет на результат, пока не будет удален файл кэша или не будет изменено имя файла.

dataset = tf.data.Dataset.range(5)
dataset = dataset.cache("/path/to/file")  # doctest: +SKIP
list(dataset.as_numpy_iterator())  # doctest: +SKIP
[0, 1, 2, 3, 4]
dataset = tf.data.Dataset.range(10)
dataset = dataset.cache("/path/to/file")  # Same file! # doctest: +SKIP
list(dataset.as_numpy_iterator())  # doctest: +SKIP
[0, 1, 2, 3, 4]

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

cardinality

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

cardinality()

Возвращает мощность набора данных, если она известна.

cardinality может вернуть tf.data.INFINITE_CARDINALITY, если набор данных содержит бесконечное количество элементов, или tf.data.UNKNOWN_CARDINALITY, если анализ не смог определить количество элементов в наборе данных (например, когда источником набора данных является файл).

dataset = tf.data.Dataset.range(42)
print(dataset.cardinality().numpy())
42
dataset = dataset.repeat()
cardinality = dataset.cardinality()
print((cardinality == tf.data.INFINITE_CARDINALITY).numpy())
True
dataset = dataset.filter(lambda x: True)
cardinality = dataset.cardinality()
print((cardinality == tf.data.UNKNOWN_CARDINALITY).numpy())
True

concatenate

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

concatenate(
    dataset
)

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

a = tf.data.Dataset.range(1, 4)  # ==> [ 1, 2, 3 ]
b = tf.data.Dataset.range(4, 8)  # ==> [ 4, 5, 6, 7 ]
ds = a.concatenate(b)
list(ds.as_numpy_iterator())
[1, 2, 3, 4, 5, 6, 7]
# The input dataset and dataset to be concatenated should have the same
# nested structures and output types.
c = tf.data.Dataset.zip((a, b))
a.concatenate(c)
Traceback (most recent call last):
TypeError: Two datasets to concatenate have different types
<dtype: 'int64'> and (tf.int64, tf.int64)
d = tf.data.Dataset.from_tensor_slices(["a", "b", "c"])
a.concatenate(d)
Traceback (most recent call last):
TypeError: Two datasets to concatenate have different types
<dtype: 'int64'> and <dtype: 'string'>

enumerate

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

enumerate(
    start=0
)

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

Аналогично функции enumerate в Python.

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
dataset = dataset.enumerate(start=5)
for element in dataset.as_numpy_iterator():
  print(element)
(5, 1)
(6, 2)
(7, 3)

# The nested structure of the input dataset determines the structure of
# elements in the resulting dataset.
dataset = tf.data.Dataset.from_tensor_slices([(7, 8), (9, 10)])
dataset = dataset.enumerate()
for element in dataset.as_numpy_iterator():
  print(element)
(0, array([7, 8], dtype=int32))
(1, array([ 9, 10], dtype=int32))

filter

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

filter(
    predicate
)

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

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
dataset = dataset.filter(lambda x: x < 3)
list(dataset.as_numpy_iterator())
[1, 2]
# `tf.math.equal(x, y)` is required for equality comparison
def filter_fn(x):
  return tf.math.equal(x, 1)
dataset = dataset.filter(filter_fn)
list(dataset.as_numpy_iterator())
[1]

flat_map

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

flat_map(
    map_func
)

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

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

dataset = tf.data.Dataset.from_tensor_slices(
               [[1, 2, 3], [4, 5, 6], [7, 8, 9]])
dataset = dataset.flat_map(lambda x: Dataset.from_tensor_slices(x))
list(dataset.as_numpy_iterator())
[1, 2, 3, 4, 5, 6, 7, 8, 9]

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

from_generator

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

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

Создаёт набор данных Dataset, элементы которого генерируются функцией generator (устаревшие аргументы).

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

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

Рекомендуется использовать аргумент output_signature. В этом случае вывод будет предполагаться состоящим из объектов с классами, формами и типами, определёнными объектами tf.TypeSpec из аргумента output_signature.

def gen():
  ragged_tensor = tf.ragged.constant([[1, 2], [3]])
  yield 42, ragged_tensor

dataset = tf.data.Dataset.from_generator(
     gen,
     output_signature=(
         tf.TensorSpec(shape=(), dtype=tf.int32),
         tf.RaggedTensorSpec(shape=(2, None), dtype=tf.int32)))

list(dataset.take(1))
[(<tf.Tensor: shape=(), dtype=int32, numpy=42>,
<tf.RaggedTensor [[1, 2], [3]]>)]

Также существует устаревший способ вызова from_generator с помощью только аргумента output_types или вместе с аргументом output_shapes. В этом случае вывод функции будет предполагаться состоящим из объектов tf.Tensor с типами, определёнными аргументом output_types, и с формами, которые неизвестны или определены аргументом output_shapes.

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

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

from_tensor_slices

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

@staticmethod
from_tensor_slices(
    tensors
)

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

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

# Slicing a 1D tensor produces scalar tensor elements.
dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
list(dataset.as_numpy_iterator())
[1, 2, 3]

# Slicing a 2D tensor produces 1D tensor elements.
dataset = tf.data.Dataset.from_tensor_slices([[1, 2], [3, 4]])
list(dataset.as_numpy_iterator())
[array([1, 2], dtype=int32), array([3, 4], dtype=int32)]

# Slicing a tuple of 1D tensors produces tuple elements containing
# scalar tensors.
dataset = tf.data.Dataset.from_tensor_slices(([1, 2], [3, 4], [5, 6]))
list(dataset.as_numpy_iterator())
[(1, 3, 5), (2, 4, 6)]

# Dictionary structure is also preserved.
dataset = tf.data.Dataset.from_tensor_slices({"a": [1, 2], "b": [3, 4]})
list(dataset.as_numpy_iterator()) == [{'a': 1, 'b': 3},
                                      {'a': 2, 'b': 4}]
True

# Two tensors can be combined into one Dataset object.
features = tf.constant([[1, 3], [2, 1], [3, 3]]) # ==> 3x2 tensor
labels = tf.constant(['A', 'B', 'A']) # ==> 3x1 tensor
dataset = Dataset.from_tensor_slices((features, labels))
# Both the features and the labels tensors can be converted
# to a Dataset object separately and combined after.
features_dataset = Dataset.from_tensor_slices(features)
labels_dataset = Dataset.from_tensor_slices(labels)
dataset = Dataset.zip((features_dataset, labels_dataset))
# A batched feature and label set can be converted to a Dataset
# in similar fashion.
batched_features = tf.constant([[[1, 3], [2, 3]],
                                [[2, 1], [1, 2]],
                                [[3, 3], [3, 2]]], shape=(3, 2, 2))
batched_labels = tf.constant([['A', 'A'],
                              ['B', 'B'],
                              ['A', 'B']], shape=(3, 2, 1))
dataset = Dataset.from_tensor_slices((batched_features, batched_labels))
for element in dataset.as_numpy_iterator():
  print(element)
(array([[1, 3],
       [2, 3]], dtype=int32), array([[b'A'],
       [b'A']], dtype=object))
(array([[2, 1],
       [1, 2]], dtype=int32), array([[b'B'],
       [b'B']], dtype=object))
(array([[3, 3],
       [3, 2]], dtype=int32), array([[b'A'],
       [b'B']], dtype=object))

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

from_tensors

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

@staticmethod
from_tensors(
    tensors
)

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

from_tensors создаёт набор данных, содержащий только один элемент. Для нарезки входного тензора на несколько элементов, используйте from_tensor_slices.

dataset = tf.data.Dataset.from_tensors([1, 2, 3])
list(dataset.as_numpy_iterator())
[array([1, 2, 3], dtype=int32)]
dataset = tf.data.Dataset.from_tensors(([1, 2, 3], 'A'))
list(dataset.as_numpy_iterator())
[(array([1, 2, 3], dtype=int32), b'A')]

# You can use `from_tensors` to produce a dataset which repeats
# the same example many times.
example = tf.constant([1,2,3])
dataset = tf.data.Dataset.from_tensors(example).repeat(2)
list(dataset.as_numpy_iterator())
[array([1, 2, 3], dtype=int32), array([1, 2, 3], dtype=int32)]

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

id="interleave" data-text="interleave">interleave

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

interleave(
    map_func, cycle_length=None, block_length=None, num_parallel_calls=None,
    deterministic=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",
             "/var/data/file3.txt", "/var/data/file4.txt"]
dataset = tf.data.Dataset.from_tensor_slices(filenames)
def parse_fn(filename):
  return tf.data.Dataset.range(10)
dataset = dataset.interleave(lambda x:
    tf.data.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 последовательных элементов из каждого итератора, и потребляя следующий входной элемент каждый раз, когда достигает конца итератора.

id="for_example" data-text="For example:">Например:

dataset = Dataset.range(1, 6)  # ==> [ 1, 2, 3, 4, 5 ]
# NOTE: New lines indicate "block" boundaries.
dataset = dataset.interleave(
    lambda x: Dataset.from_tensors(x).repeat(6),
    cycle_length=2, block_length=4)
list(dataset.as_numpy_iterator())
[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 — чистая функция и deterministic=True. Если map_func содержит какие-либо операции с состоянием, порядок доступа к этому состоянию не определён.

Производительность часто можно улучшить, установив num_parallel_calls, чтобы interleave использовало несколько потоков для извлечения элементов. Если детерминизм не требуется, производительность также можно улучшить, установив deterministic=False.

filenames = ["/var/data/file1.txt", "/var/data/file2.txt",
             "/var/data/file3.txt", "/var/data/file4.txt"]
dataset = tf.data.Dataset.from_tensor_slices(filenames)
dataset = dataset.interleave(lambda x: tf.data.TFRecordDataset(x),
    cycle_length=4, num_parallel_calls=tf.data.AUTOTUNE,
    deterministic=False)

id="list_files" data-text="list_files">list_files

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

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

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

Аргумент file_pattern должен содержать небольшое количество шаблонов. Если имена файлов уже обработаны с помощью glob, используйте Dataset.from_tensor_slices(filenames) вместо этого, поскольку повторная обработка каждого имени файла с list_files может привести к низкой производительности с удалёнными системами хранения.

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

id="example" data-text="Example:">Пример:

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

• /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

id="map" data-text="map">map

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

map(
    map_func, num_parallel_calls=None, deterministic=None
)

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

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

dataset = Dataset.range(1, 6)  # ==> [ 1, 2, 3, 4, 5 ]
dataset = dataset.map(lambda x: x + 1)
list(dataset.as_numpy_iterator())
[2, 3, 4, 5, 6]

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

dataset = Dataset.range(5)
# `map_func` takes a single argument of type `tf.Tensor` with the same
# shape and dtype.
result = dataset.map(lambda x: x + 1)

# Each element is a tuple containing two `tf.Tensor` objects.
elements = [(1, "foo"), (2, "bar"), (3, "baz")]
dataset = tf.data.Dataset.from_generator(
    lambda: elements, (tf.int32, tf.string))
# `map_func` takes two arguments of type `tf.Tensor`. This function
# projects out just the first component.
result = dataset.map(lambda x_int, y_str: x_int)
list(result.as_numpy_iterator())
[1, 2, 3]

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

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

dataset = tf.data.Dataset.range(3)
# `map_func` returns two `tf.Tensor` objects.
def g(x):
  return tf.constant(37.0), tf.constant(["Foo", "Bar", "Baz"])
result = dataset.map(g)
result.element_spec
(TensorSpec(shape=(), dtype=tf.float32, name=None), TensorSpec(shape=(3,), dtype=tf.string, name=None))
# Python primitives, lists, and NumPy arrays are implicitly converted to
# `tf.Tensor`.
def h(x):
  return 37.0, ["Foo", "Bar"], np.array([1.0, 2.0], dtype=np.float64)
result = dataset.map(h)
result.element_spec
(TensorSpec(shape=(), dtype=tf.float32, name=None), TensorSpec(shape=(2,), dtype=tf.string, name=None), TensorSpec(shape=(2,), dtype=tf.float64, name=None))
# `map_func` can return nested structures.
def i(x):
  return (37.0, [42, 16]), "foo"
result = dataset.map(i)
result.element_spec
((TensorSpec(shape=(), dtype=tf.float32, name=None),
  TensorSpec(shape=(2,), dtype=tf.int32, name=None)),
 TensorSpec(shape=(), dtype=tf.string, name=None))

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):
  return t.numpy().decode('utf-8').upper()
d = d.map(lambda x: tf.py_function(func=upper_case_fn,
          inp=[x], Tout=tf.string))
list(d.as_numpy_iterator())
[b'HELLO', b'WORLD']

3) Используйте tf.numpy_function, что также позволяет писать произвольный Python-код. Обратите внимание, что tf.py_function принимает tf.Tensor, в то время как tf.numpy_function принимает NumPy-массивы и возвращает только NumPy-массивы. Например:

d = tf.data.Dataset.from_tensor_slices(['hello', 'world'])
def upper_case_fn(t: np.ndarray):
  return t.decode('utf-8').upper()
d = d.map(lambda x: tf.numpy_function(func=upper_case_fn,
          inp=[x], Tout=tf.string))
list(d.as_numpy_iterator())
[b'HELLO', b'WORLD']

Обратите внимание, что использование tf.numpy_function и tf.py_function в целом исключает возможность параллельного выполнения пользовательских преобразований (из-за Python GIL).

Производительность часто можно улучшить, установив num_parallel_calls, чтобы map использовало несколько потоков для обработки элементов. Если определённый порядок элементов не требуется, производительность также можно улучшить, установив deterministic=False.

dataset = Dataset.range(1, 6)  # ==> [ 1, 2, 3, 4, 5 ]
dataset = dataset.map(lambda x: x + 1,
    num_parallel_calls=tf.data.AUTOTUNE,
    deterministic=False)

id="options" data-text="options">options

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

options()

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

id="padded_batch" data-text="padded_batch">padded_batch

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

padded_batch(
    batch_size, padded_shapes=None, 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, входные элементы для пакетной обработки могут иметь разные формы, и это преобразование будет дополнять каждый компонент до соответствующей формы в padded_shapes. Аргумент padded_shapes определяет результирующую форму для каждого измерения каждого компонента в элементе вывода:

• Если размерность является константой, компонент будет дополнен до этой длины в этом измерении.
• Если размерность неизвестна, компонент будет дополнен до максимальной длины всех элементов в этом измерении.

A = (tf.data.Dataset
     .range(1, 5, output_type=tf.int32)
     .map(lambda x: tf.fill([x], x)))
# Pad to the smallest per-batch size that fits all elements.
B = A.padded_batch(2)
for element in B.as_numpy_iterator():
  print(element)
[[1 0]
 [2 2]]
[[3 3 3 0]
 [4 4 4 4]]
# Pad to a fixed size.
C = A.padded_batch(2, padded_shapes=5)
for element in C.as_numpy_iterator():
  print(element)
[[1 0 0 0 0]
 [2 2 0 0 0]]
[[3 3 3 0 0]
 [4 4 4 4 0]]
# Pad with a custom value.
D = A.padded_batch(2, padded_shapes=5, padding_values=-1)
for element in D.as_numpy_iterator():
  print(element)
[[ 1 -1 -1 -1 -1]
 [ 2  2 -1 -1 -1]]
[[ 3  3  3 -1 -1]
 [ 4  4  4  4 -1]]
# Components of nested elements can be padded independently.
elements = [([1, 2, 3], [10]),
            ([4, 5], [11, 12])]
dataset = tf.data.Dataset.from_generator(
    lambda: iter(elements), (tf.int32, tf.int32))
# Pad the first component of the tuple to length 4, and the second
# component to the smallest size that fits.
dataset = dataset.padded_batch(2,
    padded_shapes=([4], [None]),
    padding_values=(-1, 100))
list(dataset.as_numpy_iterator())
[(array([[ 1,  2,  3, -1], [ 4,  5, -1, -1]], dtype=int32),
  array([[ 10, 100], [ 11,  12]], dtype=int32))]
# Pad with a single value and multiple components.
E = tf.data.Dataset.zip((A, A)).padded_batch(2, padding_values=-1)
for element in E.as_numpy_iterator():
  print(element)
(array([[ 1, -1],
       [ 2,  2]], dtype=int32), array([[ 1, -1],
       [ 2,  2]], dtype=int32))
(array([[ 3,  3,  3, -1],
       [ 4,  4,  4,  4]], dtype=int32), array([[ 3,  3,  3, -1],
       [ 4,  4,  4,  4]], dtype=int32))

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

prefetch

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

prefetch(
    buffer_size
)

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

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

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

dataset = tf.data.Dataset.range(3)
dataset = dataset.prefetch(2)
list(dataset.as_numpy_iterator())
[0, 1, 2]

range

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

@staticmethod
range(
    *args, **kwargs
)

Создаёт Dataset шага с заданным шагом.

list(Dataset.range(5).as_numpy_iterator())
[0, 1, 2, 3, 4]
list(Dataset.range(2, 5).as_numpy_iterator())
[2, 3, 4]
list(Dataset.range(1, 5, 2).as_numpy_iterator())
[1, 3]
list(Dataset.range(1, 5, -2).as_numpy_iterator())
[]
list(Dataset.range(5, 1).as_numpy_iterator())
[]
list(Dataset.range(5, 1, -2).as_numpy_iterator())
[5, 3]
list(Dataset.range(2, 5, output_type=tf.int32).as_numpy_iterator())
[2, 3, 4]
list(Dataset.range(1, 5, 2, output_type=tf.float32).as_numpy_iterator())
[1.0, 3.0]

reduce

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

reduce(
    initial_state, reduce_func
)

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

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

tf.data.Dataset.range(5).reduce(np.int64(0), lambda x, _: x + 1).numpy()
5
tf.data.Dataset.range(5).reduce(np.int64(0), lambda x, y: x + y).numpy()
10

repeat

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

repeat(
    count=None
)

Повторяет этот набор данных, так что каждое исходное значение отображается count раз.

dataset = tf.data.Dataset.from_tensor_slices([1, 2, 3])
dataset = dataset.repeat(3)
list(dataset.as_numpy_iterator())
[1, 2, 3, 1, 2, 3, 1, 2, 3]

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

shard

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

shard(
    num_shards, index
)

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

shard детерминирован. Набор данных, созданный A.shard(n, i) , будет содержать все элементы A, для которых индекс mod n = i.

A = tf.data.Dataset.range(10)
B = A.shard(num_shards=3, index=0)
list(B.as_numpy_iterator())
[0, 3, 6, 9]
C = A.shard(num_shards=3, index=1)
list(C.as_numpy_iterator())
[1, 4, 7]
D = A.shard(num_shards=3, index=2)
list(D.as_numpy_iterator())
[2, 5, 8]

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

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

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 элементов.

reshuffle_each_iteration управляет тем, должен ли порядок перемешивания отличаться для каждой эпохи. В TF 1.X стандартный способ создания эпох был посредством преобразования repeat:

dataset = tf.data.Dataset.range(3)
dataset = dataset.shuffle(3, reshuffle_each_iteration=True)
dataset = dataset.repeat(2)  # doctest: +SKIP
[1, 0, 2, 1, 2, 0]

dataset = tf.data.Dataset.range(3)
dataset = dataset.shuffle(3, reshuffle_each_iteration=False)
dataset = dataset.repeat(2)  # doctest: +SKIP
[1, 0, 2, 1, 0, 2]

В TF 2.0 объекты tf.data.Dataset являются итерируемыми объектами Python, что позволяет создавать эпохи также через итерацию по Python:

dataset = tf.data.Dataset.range(3)
dataset = dataset.shuffle(3, reshuffle_each_iteration=True)
list(dataset.as_numpy_iterator())  # doctest: +SKIP
[1, 0, 2]
list(dataset.as_numpy_iterator())  # doctest: +SKIP
[1, 2, 0]

dataset = tf.data.Dataset.range(3)
dataset = dataset.shuffle(3, reshuffle_each_iteration=False)
list(dataset.as_numpy_iterator())  # doctest: +SKIP
[1, 0, 2]
list(dataset.as_numpy_iterator())  # doctest: +SKIP
[1, 0, 2]

skip

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

skip(
    count
)

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

dataset = tf.data.Dataset.range(10)
dataset = dataset.skip(7)
list(dataset.as_numpy_iterator())
[7, 8, 9]

take

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

take(
    count
)

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

dataset = tf.data.Dataset.range(10)
dataset = dataset.take(3)
list(dataset.as_numpy_iterator())
[0, 1, 2]

unbatch

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

unbatch()

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

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

elements = [ [1, 2, 3], [1, 2], [1, 2, 3, 4] ]
dataset = tf.data.Dataset.from_generator(lambda: elements, tf.int64)
dataset = dataset.unbatch()
list(dataset.as_numpy_iterator())
[1, 2, 3, 1, 2, 1, 2, 3, 4]

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

window

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

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

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

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

Аргумент shift определяет количество входных элементов, на которые окно смещается на каждой итерации. Если номера окон и элементов начинаются с 0, первый элемент в окне k будет элементом k * shift входного набора данных. В частности, первый элемент первого окна всегда будет первым элементом входного набора данных.

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

Например:

dataset = tf.data.Dataset.range(7).window(2)
for window in dataset:
  print(list(window.as_numpy_iterator()))
[0, 1]
[2, 3]
[4, 5]
[6]
dataset = tf.data.Dataset.range(7).window(3, 2, 1, True)
for window in dataset:
  print(list(window.as_numpy_iterator()))
[0, 1, 2]
[2, 3, 4]
[4, 5, 6]
dataset = tf.data.Dataset.range(7).window(3, 1, 2, True)
for window in dataset:
  print(list(window.as_numpy_iterator()))
[0, 2, 4]
[1, 3, 5]
[2, 4, 6]

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

nested = ([1, 2, 3, 4], [5, 6, 7, 8])
dataset = tf.data.Dataset.from_tensor_slices(nested).window(2)
for window in dataset:
  def to_numpy(ds):
    return list(ds.as_numpy_iterator())
  print(tuple(to_numpy(component) for component in window))
([1, 2], [5, 6])
([3, 4], [7, 8])

dataset = tf.data.Dataset.from_tensor_slices({'a': [1, 2, 3, 4]})
dataset = dataset.window(2)
for window in dataset:
  def to_numpy(ds):
    return list(ds.as_numpy_iterator())
  print({'a': to_numpy(window['a'])})
{'a': [1, 2]}
{'a': [3, 4]}

with_options

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

with_options(
    options
)

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

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

ds = tf.data.Dataset.range(5)
ds = ds.interleave(lambda x: tf.data.Dataset.range(5),
                   cycle_length=3,
                   num_parallel_calls=3)
options = tf.data.Options()
# This will make the interleave order non-deterministic.
options.experimental_deterministic = False
ds = ds.with_options(options)

zip

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

@staticmethod
zip(
    datasets
)

Создаёт набор данных, объединяя заданные наборы данных.

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

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

# The `datasets` argument may contain an arbitrary number of datasets.
c = tf.data.Dataset.range(7, 13).batch(2)  # ==> [ [7, 8],
                                           #       [9, 10],
                                           #       [11, 12] ]
ds = tf.data.Dataset.zip((a, b, c))
for element in ds.as_numpy_iterator():
  print(element)
(1, 4, array([7, 8]))
(2, 5, array([ 9, 10]))
(3, 6, array([11, 12]))

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

__bool__

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

__bool__()

__iter__

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

__iter__()

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

Возвращаемый итератор реализует протокол Python Iterator.

__len__

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

__len__()

Возвращает длину набора данных, если она известна и конечна.

Этот метод требует, чтобы вы работали в режиме eager и длина набора данных была известна и конечна. Если длина неизвестна или бесконечна, или если вы работаете в режиме графа, используйте tf.data.Dataset.cardinality вместо этого.

__nonzero__

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

__nonzero__()