TensorFlow's new data reading method: Dataset API introductory tutorial

Author | He Zhiyuan

The Dataset API is a new module introduced in TensorFlow 1.3. It mainly serves data reading and constructs the pipeline of input data.

Previously, there were generally two ways to read data in TensorFlow:

• Use placeholder to read data in memory
• Use the queue to read the data in the hard disk (for this method, you can refer to my previous article: Ten Figures Explain the TensorFlow Data Reading Mechanism )

The Dataset API supports reading from memory and hard disk at the same time. Compared with the previous two methods, the syntax is more concise and easy to understand. In addition, if you want to use TensorFlow's new Eager mode, you must use the Dataset API to read data.

This article will introduce the usage of the Dataset API in detail (including in the non-Eager mode and the Eager mode).

Import of Dataset API

In TensorFlow 1.3, the Dataset API is placed in the contrib package:

tf.contrib.data.Dataset

• 1

In TensorFlow 1.4, the Dataset API has been removed from the contrib package and has become a member of the core API:

tf.data.Dataset

• 1

The following sample code will take the TensorFlow 1.4 version as an example. If you use TensorFlow 1.3, you need to make simple modifications (that is, add contrib).

Basic Concepts: Dataset and Iterator

Let's understand the Dataset API from the basic classes. Refer to the class diagram in the Dataset API officially given by Google:

In the beginning, we only need to focus on the two most important basic classes: Dataset and Iterator.

A Dataset can be thought of as an ordered list of "elements" of the same type. In actual use, a single "element" can be a vector, a string, an image, or even a tuple or a dict.

Take the simplest example first, where each element of the Dataset is a number:

import tensorflow as tf
import numpy as np

dataset = tf.data.Dataset.from_tensor_slices(np.array([1.0, 2.0, 3.0, 4.0, 5.0]))

• 1
• 2
• 3
• 4

这样，我们就创建了一个dataset，这个dataset中含有5个元素，分别是1.0, 2.0, 3.0, 4.0, 5.0。

如何将这个dataset中的元素取出呢？方法是从Dataset中示例化一个Iterator，然后对Iterator进行迭代。

在非Eager模式下，读取上述dataset中元素的方法为：

iterator = dataset.make_one_shot_iterator()
one_element = iterator.get_next()
with tf.Session() as sess:
    for i in range(5):
        print(sess.run(one_element))

• 1
• 2
• 3
• 4
• 5

对应的输出结果应该就是从1.0到5.0。语句iterator = dataset.make_one_shot_iterator()从dataset中实例化了一个Iterator，这个Iterator是一个“one shot iterator”，即只能从头到尾读取一次。one_element = iterator.get_next()表示从iterator里取出一个元素。由于这是非Eager模式，所以one_element只是一个Tensor，并不是一个实际的值。调用sess.run(one_element)后，才能真正地取出一个值。

如果一个dataset中元素被读取完了，再尝试sess.run(one_element)的话，就会抛出tf.errors.OutOfRangeError异常，这个行为与使用队列方式读取数据的行为是一致的。在实际程序中，可以在外界捕捉这个异常以判断数据是否读取完，请参考下面的代码：

dataset = tf.data.Dataset.from_tensor_slices(np.array([1.0, 2.0, 3.0, 4.0, 5.0]))
iterator = dataset.make_one_shot_iterator()
one_element = iterator.get_next()
with tf.Session() as sess:
    try:
        while True:
            print(sess.run(one_element))
    except tf.errors.OutOfRangeError:
        print("end!")

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9

在Eager模式中，创建Iterator的方式有所不同。是通过tfe.Iterator(dataset)的形式直接创建Iterator并迭代。迭代时可以直接取出值，不需要使用sess.run()：

import tensorflow.contrib.eager as tfe
tfe.enable_eager_execution()

dataset = tf.data.Dataset.from_tensor_slices(np.array([1.0, 2.0, 3.0, 4.0, 5.0]))

for one_element in tfe.Iterator(dataset):
    print(one_element)

• 1
• 2
• 3
• 4
• 5
• 6
• 7

从内存中创建更复杂的Dataset

之前我们用tf.data.Dataset.from_tensor_slices创建了一个最简单的Dataset：

dataset = tf.data.Dataset.from_tensor_slices(np.array([1.0, 2.0, 3.0, 4.0, 5.0]))

• 1

其实，tf.data.Dataset.from_tensor_slices的功能不止如此，它的真正作用是切分传入Tensor的第一个维度，生成相应的dataset。

例如：

dataset = tf.data.Dataset.from_tensor_slices(np.random.uniform(size=(5, 2)))

• 1

传入的数值是一个矩阵，它的形状为(5, 2)，tf.data.Dataset.from_tensor_slices就会切分它形状上的第一个维度，最后生成的dataset中一个含有5个元素，每个元素的形状是(2, )，即每个元素是矩阵的一行。

在实际使用中，我们可能还希望Dataset中的每个元素具有更复杂的形式，如每个元素是一个Python中的元组，或是Python中的词典。例如，在图像识别问题中，一个元素可以是{“image”: image_tensor, “label”: label_tensor}的形式，这样处理起来更方便。

tf.data.Dataset.from_tensor_slices同样支持创建这种dataset，例如我们可以让每一个元素是一个词典：

dataset = tf.data.Dataset.from_tensor_slices(
    {
        "a": np.array([1.0, 2.0, 3.0, 4.0, 5.0]),                                       
        "b": np.random.uniform(size=(5, 2))
    }
)

• 1
• 2
• 3
• 4
• 5
• 6

这时函数会分别切分”a”中的数值以及”b”中的数值，最终dataset中的一个元素就是类似于{“a”: 1.0, “b”: [0.9, 0.1]}的形式。

利用tf.data.Dataset.from_tensor_slices创建每个元素是一个tuple的dataset也是可以的：

dataset = tf.data.Dataset.from_tensor_slices(
  (np.array([1.0, 2.0, 3.0, 4.0, 5.0]), np.random.uniform(size=(5, 2)))
)

• 1
• 2
• 3

对Dataset中的元素做变换

Dataset支持一类特殊的操作：Transformation。一个Dataset通过Transformation变成一个新的Dataset。通常我们可以通过Transformation完成数据变换，打乱，组成batch，生成epoch等一系列操作。

常用的Transformation有：

• map
• batch
• shuffle
• repeat

下面就分别进行介绍。

（1）map

map接收一个函数，Dataset中的每个元素都会被当作这个函数的输入，并将函数返回值作为新的Dataset，如我们可以对dataset中每个元素的值加1：

dataset = tf.data.Dataset.from_tensor_slices(np.array([1.0, 2.0, 3.0, 4.0, 5.0]))
dataset = dataset.map(lambda x: x + 1) # 2.0, 3.0, 4.0, 5.0, 6.0

• 1
• 2

（2）batch

batch就是将多个元素组合成batch，如下面的程序将dataset中的每个元素组成了大小为32的batch：

dataset = dataset.batch(32)

• 1

（3）shuffle

shuffle的功能为打乱dataset中的元素，它有一个参数buffersize，表示打乱时使用的buffer的大小：

dataset = dataset.shuffle(buffer_size=10000)

• 1

（4）repeat

repeat的功能就是将整个序列重复多次，主要用来处理机器学习中的epoch，假设原先的数据是一个epoch，使用repeat(5)就可以将之变成5个epoch：

dataset = dataset.repeat(5)

• 1

如果直接调用repeat()的话，生成的序列就会无限重复下去，没有结束，因此也不会抛出tf.errors.OutOfRangeError异常：

dataset = dataset.repeat()

• 1

读入磁盘图片与对应label

讲到这里，我们可以来考虑一个简单，但同时也非常常用的例子：读入磁盘中的图片和图片相应的label，并将其打乱，组成batch_size=32的训练样本。在训练时重复10个epoch。

对应的程序为（从官方示例程序修改而来）：

# 函数的功能时将filename对应的图片文件读进来，并缩放到统一的大小
def _parse_function(filename, label):
  image_string = tf.read_file(filename)
  image_decoded = tf.image.decode_image(image_string)
  image_resized = tf.image.resize_images(image_decoded, [28, 28])
  return image_resized, label

# 图片文件的列表
filenames = tf.constant(["/var/data/image1.jpg", "/var/data/image2.jpg", ...])
# label[i]就是图片filenames[i]的label
labels = tf.constant([0, 37, ...])

# 此时dataset中的一个元素是(filename, label)
dataset = tf.data.Dataset.from_tensor_slices((filenames, labels))

# 此时dataset中的一个元素是(image_resized, label)
dataset = dataset.map(_parse_function)

# 此时dataset中的一个元素是(image_resized_batch, label_batch)
dataset = dataset.shuffle(buffersize=1000).batch(32).repeat(10)

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12
• 13
• 14
• 15
• 16
• 17
• 18
• 19
• 20

在这个过程中，dataset经历三次转变：

• 运行dataset = tf.data.Dataset.from_tensor_slices((filenames, labels))后，dataset的一个元素是(filename, label)。filename是图片的文件名，label是图片对应的标签。
• 之后通过map，将filename对应的图片读入，并缩放为28x28的大小。此时dataset中的一个元素是(image_resized, label)
• 最后，dataset.shuffle(buffersize=1000).batch(32).repeat(10)的功能是：在每个epoch内将图片打乱组成大小为32的batch，并重复10次。最终，dataset中的一个元素是(image_resized_batch, label_batch)，image_resized_batch的形状为(32, 28, 28, 3)，而label_batch的形状为(32, )，接下来我们就可以用这两个Tensor来建立模型了。

Dataset的其它创建方法

除了tf.data.Dataset.from_tensor_slices外，目前Dataset API还提供了另外三种创建Dataset的方式：

• tf.data.TextLineDataset()：这个函数的输入是一个文件的列表，输出是一个dataset。dataset中的每一个元素就对应了文件中的一行。可以使用这个函数来读入CSV文件。
• tf.data.FixedLengthRecordDataset()：这个函数的输入是一个文件的列表和一个record_bytes，之后dataset的每一个元素就是文件中固定字节数record_bytes的内容。通常用来读取以二进制形式保存的文件，如CIFAR10数据集就是这种形式。
• tf.data.TFRecordDataset()：顾名思义，这个函数是用来读TFRecord文件的，dataset中的每一个元素就是一个TFExample。

它们的详细使用方法可以参阅文档：Module: tf.data

更多类型的Iterator

在非Eager模式下，最简单的创建Iterator的方法就是通过dataset.make_one_shot_iterator()来创建一个one shot iterator。除了这种one shot iterator外，还有三个更复杂的Iterator，即：

• initializable iterator
• reinitializable iterator
• feedable iterator

initializable iterator必须要在使用前通过sess.run()来初始化。使用initializable iterator，可以将placeholder代入Iterator中，这可以方便我们通过参数快速定义新的Iterator。一个简单的initializable iterator使用示例：

limit = tf.placeholder(dtype=tf.int32, shape=[])

dataset = tf.data.Dataset.from_tensor_slices(tf.range(start=0, limit=limit))

iterator = dataset.make_initializable_iterator()
next_element = iterator.get_next()

with tf.Session() as sess:
    sess.run(iterator.initializer, feed_dict={limit: 10})
    for i in range(10):
      value = sess.run(next_element)
      assert i == value

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12

此时的limit相当于一个“参数”，它规定了Dataset中数的“上限”。

initializable iterator还有一个功能：读入较大的数组。

在使用tf.data.Dataset.from_tensor_slices(array)时，实际上发生的事情是将array作为一个tf.constants保存到了计算图中。当array很大时，会导致计算图变得很大，给传输、保存带来不便。这时，我们可以用一个placeholder取代这里的array，并使用initializable iterator，只在需要时将array传进去，这样就可以避免把大数组保存在图里，示例代码为（来自官方例程）：

# 从硬盘中读入两个Numpy数组
with np.load("/var/data/training_data.npy") as data:
  features = data["features"]
  labels = data["labels"]

features_placeholder = tf.placeholder(features.dtype, features.shape)
labels_placeholder = tf.placeholder(labels.dtype, labels.shape)

dataset = tf.data.Dataset.from_tensor_slices((features_placeholder, labels_placeholder))
iterator = dataset.make_initializable_iterator()
sess.run(iterator.initializer, feed_dict={features_placeholder: features,
                                          labels_placeholder: labels})

• 1
• 2
• 3
• 4
• 5
• 6
• 7
• 8
• 9
• 10
• 11
• 12

reinitializable iterator和feedable iterator相比initializable iterator更复杂，也更加少用，如果想要了解它们的功能，可以参阅官方介绍，这里就不再赘述了。

总结

本文主要介绍了Dataset API的基本架构：Dataset类和Iterator类，以及它们的基础使用方法。

在非Eager模式下，Dataset中读出的一个元素一般对应一个batch的Tensor，我们可以使用这个Tensor在计算图中构建模型。

在Eager模式下，Dataset建立Iterator的方式有所不同，此时通过读出的数据就是含有值的Tensor，方便调试。

作为兼容两种模式的Dataset API，在今后应该会成为TensorFlow读取数据的主流方式。关于Dataset API的进一步介绍，可以参阅下面的资料：

• Importing Data ：官方Guide
• Module: tf.data： API文档
• Introduction to TensorFlow Datasets and Estimators：如何联合使用Dataset和Estimator

作者：何之源，复旦大学计算机科学硕士在读，研究方向为人工智能以及机器学习的应用。 
欢迎人工智能领域技术投稿、约稿、给文章纠错，请发送邮件至[email protected]