User guide

This package builds on top of tensorflow (at least 2.3 is needed). You are expected to have some familiarity with it before continuing. The best way to use tensorflow is to use its tf.keras and tf.data API. We recommend reading at least the following pages:

If you were used to Tensorflow 1 API, then reading these pages are also recommended:

In the rest of this guide, you will learn a few tips and examples on how to:

  • Port v1 checkpoints to tf v2 format.

  • Create datasets and save TFRecords.

  • Create models with custom training and evaluation logic.

  • Mixed-precision training

  • Multi-GPU and multi-worker training

After reading this page, you may look at a complete example in: https://gitlab.idiap.ch/bob/bob.learn.tensorflow/-/blob/master/examples/MSCeleba_centerloss_mixed_precision_multi_worker.py

Porting V1 Tensorflow checkpoints to V2

Take a look at the notebook located at: https://gitlab.idiap.ch/bob/bob.learn.tensorflow/-/blob/master/examples/convert_v1_checkpoints_to_v2.ipynb for an example.

Creating datasets from data

If you are working with Bob databases, below is an example of converting them to tf.data.Dataset’s using bob.learn.tensorflow.data.dataset_using_generator:

>>> import bob.db.atnt
>>> from bob.learn.tensorflow.data import dataset_using_generator
>>> import tensorflow as tf

>>> db = bob.db.atnt.Database()
>>> samples = db.objects(groups="world")

>>> # construct integer labels for each identity in the database
>>> CLIENT_IDS = (str(f.client_id) for f in samples)
>>> CLIENT_IDS = list(set(CLIENT_IDS))
>>> CLIENT_IDS = dict(zip(CLIENT_IDS, range(len(CLIENT_IDS))))

>>> def reader(sample):
...     img = sample.load(db.original_directory, db.original_extension)
...     label = CLIENT_IDS[str(sample.client_id)]
...     return img, label

>>> dataset = dataset_using_generator(samples, reader)
>>> dataset
<FlatMapDataset shapes: ((112, 92), ()), types: (tf.uint8, tf.int32)>

Create TFRecords from tf.data.Datasets

Use bob.learn.tensorflow.data.dataset_to_tfrecord and bob.learn.tensorflow.data.dataset_from_tfrecord to painlessly convert any tf.data.Dataset to TFRecords and create datasets back from those TFRecords:

>>> from bob.learn.tensorflow.data import dataset_to_tfrecord
>>> from bob.learn.tensorflow.data import dataset_from_tfrecord
>>> path = f"{temp_dir}/my_dataset"
>>> dataset_to_tfrecord(dataset, path)
>>> dataset = dataset_from_tfrecord(path)
>>> dataset
<MapDataset shapes: ((112, 92), ()), types: (tf.uint8, tf.int32)>

There is also a script called bob tf dataset-to-tfrecord that wraps the bob.learn.tensorflow.data.dataset_to_tfrecord for easy Grid job submission.

Create models with custom training and evaluation logic

Training models for biometrics recognition (and metric learning in general) is different from the typical classification problems since the labels during training and testing are different. We found that overriding the compile, train_step, and test_step methods as explained in https://www.tensorflow.org/guide/keras/customizing_what_happens_in_fit is the best trade-off between the control of what happens during training and evaluation and writing boilerplate code.

Mixed-precision training

When doing mixed precision training: https://www.tensorflow.org/guide/mixed_precision it is important to scale the loss before computing the gradients.

Multi-GPU and multi-worker training

It is important that custom metrics and losses do not average their results by the batch size as the values should be averaged by the global batch size: https://www.tensorflow.org/tutorials/distribute/custom_training Take a look at custom metrics and losses in this package for examples of correct implementations.