tf.compat.v1.data.Dataset

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

Унаследован от: Dataset

tf.compat.v1.data.Dataset()

Можно использовать Dataset для представления входной цепочки как набора элементов и «логического плана» преобразований, которые действуют над этими элементами.

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, а элемент_spec набора данных содержал только 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
)

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

Аналогично встроенной функции Python enumerate.

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 tf.sparse.SparseTensor в этом наборе данных по строкам. (устарело)

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

from_tensors

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

@staticmethod
from_tensors(
    tensors
)

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

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
)

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

Аргумент file_pattern должен содержать небольшое число шаблонов поиска. Если имена файлов уже отфильтрованы с помощью шаблонов поиска, используйте 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 (жадный или графический), 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).

Производительность часто можно улучшить, установив 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

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

prefetch(
    buffer_size
)

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

Большинство конвейеров ввода данных набора данных должны заканчиваться вызовом 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

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

@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)

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

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

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

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

take

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

take(
    count
)

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

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__()

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

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

__nonzero__

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

__nonzero__()