tf.compat.v2.data.experimental.RandomDataset

A Dataset псевдослучайных значений.

tf.compat.v2.data.experimental.RandomDataset(
    seed=None
)

Методы

apply

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

apply(
    transformation_func
)

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

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

Например:

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

batch

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

batch(
    batch_size, drop_remainder=False
)

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

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

cache

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

cache(
    filename=''
)

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

concatenate

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

concatenate(
    dataset
)

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

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

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

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

enumerate

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

enumerate(
    start=0
)

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

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

Например:

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

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

filter

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

filter(
    predicate
)

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

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

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

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

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

flat_map

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

flat_map(
    map_func
)

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

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

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

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

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

from_generator

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

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

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

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

Например:

import itertools
tf.compat.v1.enable_eager_execution()

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

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

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

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

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

from_tensor_slices

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

@staticmethod
from_tensor_slices(
    tensors
)

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

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

from_tensors

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

@staticmethod
from_tensors(
    tensors
)

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

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

interleave

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

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

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

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

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

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

Например:

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

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

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

list_files

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

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

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

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

Пример:

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

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

map

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

map(
    map_func, num_parallel_calls=None
)

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

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

Например:

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

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

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

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

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

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

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

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

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

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

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

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

Обратите внимание, что независимо от контекста, в котором определен map_func (режим 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) -> str:
    return t.numpy().decode('utf-8').upper()

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

options

View source

options()

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

padded_batch

View source

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

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

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

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

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

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

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

prefetch

View source

prefetch(
    buffer_size
)

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

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

range

View source

@staticmethod
range(
    *args
)

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

For example:

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

reduce

View source

reduce(
    initial_state, reduce_func
)

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

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

For example:

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

repeat

View source

repeat(
    count=None
)

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

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

shard

View source

shard(
    num_shards, index
)

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

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

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

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

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

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

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

shuffle

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

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

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

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

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

skip

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

skip(
    count
)

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

take

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

take(
    count
)

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

unbatch

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

unbatch()

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

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

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

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

window

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

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

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

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

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

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

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

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

Например:

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

with_options

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

with_options(
    options
)

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

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

zip

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

@staticmethod
zip(
    datasets
)

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

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

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

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

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

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

__iter__

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

__iter__()

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

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