tf.compat.v1.data.TFRecordDataset

Составной объект, содержащий записи из одного или нескольких файлов TFRecord.

tf.compat.v1.data.TFRecordDataset(
    filenames, compression_type=None, buffer_size=None, num_parallel_reads=None
)

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
)

Создаёт новый набор данных, конкатенируя заданный набор данных с этим набором данных.

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]

filter_with_legacy_function

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

filter_with_legacy_function(
    predicate
)

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

Примечание: Это временное решение для существующего использования filter , которое не работает с функциями V2. Новые использования не рекомендуются, и существующие должны быть перенесены на filter, так как этот метод будет удалён в V2.

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, output_shapes=None, args=None
)

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

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

import itertools

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

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

list(dataset.take(3).as_numpy_iterator())
[(1, array([1])), (2, array([1, 1])), (3, array([1, 1, 1]))]

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

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

from_sparse_tensor_slices

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

@staticmethod
from_sparse_tensor_slices(
    sparse_tensor
)

Разделяет каждый тензор ранга N в этом наборе данных построчно. (устарело)

from_tensor_slices

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

@staticmethod
from_tensor_slices(
    tensors
)

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

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

# 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, а жадное выполнение не включено, значения будут встроены в граф как одна или несколько операций 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, рассмотрите альтернативу, описанную в этом руководстве.

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 последовательных элементов из каждого итератора и потребляя следующий входной элемент каждый раз, когда достигает конца итератора.

Пример:

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.experimental.AUTOTUNE,
    deterministic=False)

list_files

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

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

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

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

Примечание: По умолчанию этот метод возвращает имена файлов в случайном порядке, не гарантирующем детерминированность. Используйте 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

make_initializable_iterator

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

make_initializable_iterator(
    shared_name=None
)

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

Примечание: Возвращённый итератор будет в неинициализированном состоянии, и вы должны выполнить операцию iterator.initializer перед его использованием:

# Building graph ...
dataset = ...
iterator = dataset.make_initializable_iterator()
next_value = iterator.get_next()  # This is a Tensor.

# ... from within a session ...
sess.run(iterator.initializer)
try:
  while True:
    value = sess.run(next_value)
    ...
except tf.errors.OutOfRangeError:
    pass

make_one_shot_iterator

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

make_one_shot_iterator()

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

Примечание: Возвращаемый итератор будет инициализирован автоматически. Итератор "one-shot" в настоящее время не поддерживает повторную инициализацию. Для этого см. make_initializable_iterator.

Пример:

# Building graph ...
dataset = ...
next_value = dataset.make_one_shot_iterator().get_next()

# ... from within a session ...
try:
  while True:
    value = sess.run(next_value)
    ...
except tf.errors.OutOfRangeError:
    pass

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 определен (eager или граф), 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.experimental.AUTOTUNE,
    deterministic=False)

map_with_legacy_function

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

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

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

Примечание: Это "лазейка" для существующих использований map которые не работают с функциями V2. Новые использования категорически не рекомендуются, и существующие должны мигрировать на map, так как этот метод будет удален в V2.

options

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

options()

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

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

View source

prefetch(
    buffer_size
)

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

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

Примечание: Как и другие методы Dataset, prefetch работает с элементами входного набора данных. Он не понимает разницу между примерами и пачками. 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

View source

@staticmethod
range(
    *args, **kwargs
)

Создаёт набор данных с диапазоном значений с заданным шагом.

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

View source

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

View source

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

View source

shard(
    num_shards, index
)

Создаёт набор данных, который включает только 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)

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

• Убедитесь, что вы разделили данные перед использованием любого случайного оператора (такого как shuffle).
• В целом лучше, если оператор shard используется на ранней стадии конвейера набора данных. Например, при чтении из набора файлов 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

View source

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
)

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

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

take

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

take(
    count
)

Создаёт набор данных Dataset, содержащий не более 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
)

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

Этот метод имеет сходную семантику с встроенной функцией 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__()