TensorFlow Plugin API reference

class nvidia.dali.plugin.tf.DALIDataset(pipeline, **kwargs)

Creates a DALIDataset compatible with tf.data.Dataset from a DALI pipeline. It supports TensorFlow 1.15 and 2.x family

Please keep in mind that TensorFlow allocates almost all available device memory by default. This might cause errors in DALI due to insufficient memory. On how to change this behaviour please look into the TensorFlow documentation, as it may differ based on your use case.

Parameters

  • pipeline (nvidia.dali.Pipeline) – defining the data processing to be performed.

  • output_dtypes (tf.DType or tuple of tf.DType, default = None) – expected output types

  • output_shapes (tuple of shapes, optional, default = None) – expected output shapes. If provided, must match arity of the output_dtypes. When set to None, DALI will infer the shapes on its own. Individual shapes can be also set to None or contain None to indicate unknown dimensions. If specified must be compatible with shape returned from DALI Pipeline and with batch_size argument which will be the outermost dimension of returned tensors. In case of batch_size = 1 it can be omitted in the shape. DALI Dataset will try to match requested shape by squeezing 1-sized dimensions from shape obtained from Pipeline.

  • fail_on_device_mismatch (bool, optional, default = True) – When set to True runtime check will be performed to ensure DALI device and TF device are both CPU or both GPU. In some contexts this check might be inaccurate. When set to False will skip the check but print additional logs to check the devices. Keep in mind that this may allow hidden GPU to CPU copies in the workflow and impact performance.

  • batch_size (int, optional, default = 1) – batch size of the pipeline.

  • num_threads (int, optional, default = 4) – number of CPU threads used by the pipeline.

  • device_id (int, optional, default = 0) – id of GPU used by the pipeline. A None value for this parameter means that DALI should not use GPU nor CUDA runtime. This limits the pipeline to only CPU operators but allows it to run on any CPU capable machine.

  • exec_separated (bool, optional, default = False) – Whether to execute the pipeline in a way that enables overlapping CPU and GPU computation, typically resulting in faster execution speed, but larger memory consumption.

  • prefetch_queue_depth (int, optional, default = 2) – depth of the executor queue. Deeper queue makes DALI more resistant to uneven execution time of each batch, but it also consumes more memory for internal buffers. Value will be used with exec_separated set to False.

  • cpu_prefetch_queue_depth (int, optional, default = 2) – depth of the executor cpu queue. Deeper queue makes DALI more resistant to uneven execution time of each batch, but it also consumes more memory for internal buffers. Value will be used with exec_separated set to True.

  • gpu_prefetch_queue_depth (int, optional, default = 2) – depth of the executor gpu queue. Deeper queue makes DALI more resistant to uneven execution time of each batch, but it also consumes more memory for internal buffers. Value will be used with exec_separated set to True.

Returns

Return type

DALIDataset object based on DALI pipeline and compatible with tf.data.Dataset API.

nvidia.dali.plugin.tf.DALIIterator()

TF Plugin Wrapper

This operator works in the same way as DALI TensorFlow plugin, with the exception that it also accepts Pipeline objects as an input, which are serialized internally. For more information, see nvidia.dali.plugin.tf.DALIRawIterator().

nvidia.dali.plugin.tf.DALIIteratorWrapper(pipeline=None, serialized_pipeline=None, sparse=[], shapes=[], dtypes=[], batch_size=- 1, prefetch_queue_depth=2, **kwargs)

TF Plugin Wrapper

This operator works in the same way as DALI TensorFlow plugin, with the exception that it also accepts Pipeline objects as an input, which are serialized internally. For more information, see nvidia.dali.plugin.tf.DALIRawIterator().

nvidia.dali.plugin.tf.DALIRawIterator()

DALI TensorFlow plugin

Creates a DALI pipeline from a serialized pipeline, obtained from serialized_pipeline argument. shapes must match the shape of the coresponding DALI Pipeline output tensor shape. dtypes must match the type of the coresponding DALI Pipeline output tensors type.

Parameters

  • serialized_pipeline – A string.

  • shapes – A list of shapes (each a tf.TensorShape or list of ints) that has length >= 1.

  • dtypes – A list of tf.DTypes from: tf.half, tf.float32, tf.uint8, tf.int16, tf.int32, tf.int64 that has length >= 1.

  • num_threads – An optional int. Defaults to -1.

  • device_id – An optional int. Defaults to -1.

  • exec_separated – An optional bool. Defaults to False.

  • gpu_prefetch_queue_depth – An optional int. Defaults to 2.

  • cpu_prefetch_queue_depth – An optional int. Defaults to 2.

  • sparse – An optional list of bools. Defaults to [].

  • batch_size – An optional int. Defaults to -1.

  • enable_memory_stats – An optional bool. Defaults to False.

  • name – A name for the operation (optional).

Returns

A list of Tensor objects of type dtypes.

Please keep in mind that TensorFlow allocates almost all available device memory by default. This might cause errors in DALI due to insufficient memory. On how to change this behaviour please look into the TensorFlow documentation, as it may differ based on your use case.

nvidia.dali.plugin.tf.dataset_compatible_tensorflow()

Returns True if current TensorFlow version is compatible with DALIDataset.

nvidia.dali.plugin.tf.dataset_distributed_compatible_tensorflow()

Returns True if the tf.distribute APIs for current TensorFlow version are compatible with DALIDataset.

nvidia.dali.plugin.tf.dataset_options()
nvidia.dali.plugin.tf.serialize_pipeline(pipeline)

Experimental

nvidia.dali.plugin.tf.experimental.DALIDatasetWithInputs(pipeline, output_dtypes=None, output_shapes=None, fail_on_device_mismatch=True, *, input_datasets=None, input_names=None, input_layouts=None, batch_size=1, num_threads=4, device_id=0, exec_separated=False, prefetch_queue_depth=2, cpu_prefetch_queue_depth=2, gpu_prefetch_queue_depth=2, dtypes=None, shapes=None)

Experimental variant of DALIDataset. This dataset adds support for input tf.data.Datasets.

Each of the input datasets must be mapped to a external_source() operator that will represent the input to the DALI pipeline. The input is represented by the name parameter of external_source() and needs to be provided for the corresponding input dataset via the input_names argument of DALIDatasetWithInputs.

The input datasets are assumed to operate in sample mode - it means that every input dataset is treated as if providing individual samples. DALIDataset will query the inputs dataset batch_size-times to build a batch that would be fed into the DALI Pipeline. In sample mode, each sample produced by the input dataset can have a different shape, but not a different number of dimensions.

Warning

This class is experimental and its API might change without notice.

The operator adds additional parameters to the ones supported by the DALIDataset:

Parameters

  • input_datasets (tf.data.Dataset or tuple of tf.data.Dataset, optional, default = None) –

    input datasets to the DALI Pipeline. When provided, user must specify the input_names as well to provide the mapping of input datasets to External Source nodes.

    Warning

    Input dataset must be placed on the same device as DALIDatasetWithInputs. If the input has different placement (for instance, input is placed on CPU, while DALIDatasetWithInputs is placed on GPU) the tf.data.experimental.copy_to_device with GPU argument must be first applied to input.

  • input_names (str or tuple of str, optional, default = None) – names of inputs to the DALI Pipeline. Must match arity of the input_datasets. input_datasets[i] will be provided to the external source instance with the name input_names[i].

  • input_layouts (str or tuple of str, optional, default = None) – layouts of inputs to the DALI Pipeline. Must match arity of the input_datasets. input_layouts[i] will be set for input_datasets[i] provided to the external source instance with the name input_names[i]. If not provided while specifying the input_datasets, an empty layout string will be used.