API Documentation#

TensorFlow Models#

Ranking Model Constructors#

DCNModel(schema, depth[, deep_block, ...])

Create a model using the architecture proposed in DCN V2: Improved Deep & Cross Network [1].

DLRMModel(schema, *[, embeddings, ...])

DLRM-model architecture.

Retrieval Model Constructors#

MatrixFactorizationModel(schema, dim[, ...])

Builds a matrix factorization model.

TwoTowerModel(schema, query_tower[, ...])

Builds the Two-tower architecture, as proposed in [1].

YoutubeDNNRetrievalModel(schema[, ...])

Build the Youtube-DNN retrieval model.

Input Block Constructors#

InputBlock(schema[, branches, post, ...])

The entry block of the model to process input features from a schema.

ContinuousFeatures(*args, **kwargs)

Input block for continuous features.

ContinuousEmbedding(inputs, embedding_block)

EmbeddingFeatures(*args, **kwargs)

Input block for embedding-lookups for categorical features.

SequenceEmbeddingFeatures(*args, **kwargs)

Input block for embedding-lookups for categorical features. This module produces 3-D tensors, this is useful for sequential models like transformers. :param feature_config: This specifies what TableConfig to use for each feature. For shared embeddings, the same TableConfig can be used for multiple features. :type feature_config: Dict[str, FeatureConfig] :param item_id: The name of the feature that's used for the item_id. :type item_id: str, optional :param padding_idx: The symbol to use for padding. :type padding_idx: int :param pre: Transformations to apply on the inputs when the module is called (so before call). :type pre: Union[str, TabularTransformation, List[str], List[TabularTransformation]], optional :param post: Transformations to apply on the inputs after the module is called (so after call). :type post: Union[str, TabularTransformation, List[str], List[TabularTransformation]], optional :param aggregation: Aggregation to apply after processing the call-method to output a single Tensor.

Model Building Block Constructors#

DLRMBlock(schema, *[, embedding_dim, ...])

Builds the DLRM architecture, as proposed in the following `paper https://arxiv.org/pdf/1906.00091.pdf`_ [1]_.

MLPBlock(dimensions[, activation, use_bias, ...])

A block that applies a multi-layer perceptron to the input.

CrossBlock([depth, filter, low_rank_dim, ...])

This block provides a way to create high-order feature interactions

TwoTowerBlock(*args, **kwargs)

Builds the Two-tower architecture, as proposed in the following `paper https://doi.org/10.1145/3298689.3346996`_ [Xinyang19].

MatrixFactorizationBlock(schema, dim[, ...])

Returns a block for Matrix Factorization, which created the user and item embeddings based on the schema and computes the dot product between user and item L2-norm embeddings

DotProductInteraction(*args, **kwargs)

Modeling Prediction Task Constructors#

PredictionTasks(schema[, task_blocks, ...])

Creates Multi-task prediction Blocks from schema

PredictionTask(*args, **kwargs)

Base-class for prediction tasks.

BinaryClassificationTask(*args, **kwargs)

Prediction task for binary classification.

MultiClassClassificationTask(*args, **kwargs)

Prediction task for multi-class classification.

RegressionTask(*args, **kwargs)

Prediction task for regression-task.

ItemRetrievalTask(*args, **kwargs)

Prediction-task for item-retrieval.

Model Pipeline Constructors#

SequentialBlock(*args, **kwargs)

The SequentialLayer represents a sequence of Keras layers. It is a Keras Layer that can be used instead of tf.keras.layers.Sequential, which is actually a Keras Model. In contrast to keras Sequential, this layer can be used as a pure Layer in tf.functions and when exporting SavedModels, without having to pre-declare input and output shapes. In turn, this layer is usable as a preprocessing layer for TF Agents Networks, and can be exported via PolicySaver. Usage::.

ParallelBlock(*args, **kwargs)

Merge multiple layers or TabularModule's into a single output of TabularData.

ParallelPredictionBlock(*args, **kwargs)

Multi-task prediction block.

DenseResidualBlock([low_rank_dim, ...])

A block that applies a dense residual block to the input.

DualEncoderBlock(*args, **kwargs)

ResidualBlock(*args, **kwargs)

TabularBlock(*args, **kwargs)

Layer that's specialized for tabular-data by integrating many often used operations.

Filter(*args, **kwargs)

Transformation that filters out certain features from TabularData."

Masking Block Constructors#

Transformation Block Constructors#

ExpandDims(*args, **kwargs)

Expand dims of selected input tensors. Example:: inputs = { "cont_feat1": tf.random.uniform((NUM_ROWS,)), "cont_feat2": tf.random.uniform((NUM_ROWS,)), "multi_hot_categ_feat": tf.random.uniform( (NUM_ROWS, 4), minval=1, maxval=100, dtype=tf.int32 ), } expand_dims_op = tr.ExpandDims(expand_dims={"cont_feat2": 0, "multi_hot_categ_feat": 1}) expanded_inputs = expand_dims_op(inputs).

StochasticSwapNoise(*args, **kwargs)

Applies Stochastic replacement of sequence features

AsTabular(*args, **kwargs)

Converts a Tensor to TabularData by converting it to a dictionary.

Multi-Task Block Constructors#

MMOEBlock(outputs, expert_block, num_experts)

CGCBlock(*args, **kwargs)

Data Loader Customization Constructor#

Metrics#

NDCGAt(*args, **kwargs)

AvgPrecisionAt(*args, **kwargs)

RecallAt(*args, **kwargs)

Sampling#

ItemSampler(*args, **kwargs)

InBatchSampler(*args, **kwargs)

Provides in-batch sampling [1]_ for two-tower item retrieval models.

PopularityBasedSampler(*args, **kwargs)

Provides a popularity-based negative sampling for the softmax layer to ensure training efficiency when the catalog of items is very large.

Losses#

CategoricalCrossEntropy([from_logits])

Extends tf.keras.losses.SparseCategoricalCrossentropy by making from_logits=True by default (in this case an optimized softmax activation is applied within this loss, you should not include softmax activation manually in the output layer).

SparseCategoricalCrossEntropy([from_logits])

Extends tf.keras.losses.SparseCategoricalCrossentropy by making from_logits=True by default (in this case an optimized softmax activation is applied within this loss, you should not include softmax activation manually in the output layer).

BPRLoss([reduction, name])

The Bayesian Personalised Ranking (BPR) pairwise loss [1]_

BPRmaxLoss([reg_lambda])

The BPR-max pairwise loss proposed in [1]_

HingeLoss([reduction, name])

Pairwise hinge loss, as described in [1]_: max(0, 1 + r_uj - r_ui)), where r_ui is the score of the positive item and r_uj the score of negative items.

LogisticLoss([reduction, name])

Pairwise log loss, as described in [1]_: log(1 + exp(r_uj - r_ui)), where r_ui is the score of the positive item and r_uj the score of negative items.

TOP1Loss([reduction, name])

The TOP pairwise loss proposed in [1]_

TOP1maxLoss([reduction, name])

The TOP1-max pairwise loss proposed in [1]_

TOP1v2Loss([reduction, name])

An adapted version of the TOP pairwise loss proposed in [1]_, but following the current GRU4Rec implementation [2]_.

Schema Functions#

merlin.models.utils.schema_utils.select_targets(schema)

merlin.models.utils.schema_utils.schema_to_tensorflow_metadata_json(schema)

merlin.models.utils.schema_utils.tensorflow_metadata_json_to_schema(value)

merlin.models.utils.schema_utils.create_categorical_column(...)

merlin.models.utils.schema_utils.create_continuous_column(name)

merlin.models.utils.schema_utils.filter_dict_by_schema(...)

Filters out entries from input_dict, returns a dictionary where every entry corresponds to a column in the schema

merlin.models.utils.schema_utils.categorical_cardinalities(schema)

merlin.models.utils.schema_utils.categorical_domains(schema)

merlin.models.utils.schema_utils.get_embedding_sizes_from_schema(schema)

Provides a heristic (from Google) that suggests the embedding sizes as a function (forth root) of categorical features cardinalities, obtained from the schema.

merlin.models.utils.schema_utils.get_embedding_size_from_cardinality(...)

Provides a heuristic (from Google) that suggests the embedding dimension as a function (forth root) of the feature cardinality.

Utilities#

Miscellaneous Utility Functions#

merlin.models.utils.misc_utils.filter_kwargs(...)

merlin.models.utils.misc_utils.safe_json(data)

merlin.models.utils.misc_utils.get_filenames(...)

merlin.models.utils.misc_utils.get_label_feature_name(...)

Analyses the feature map config and returns the name of the label feature (e.g.

merlin.models.utils.misc_utils.get_timestamp_feature_name(...)

Analyses the feature map config and returns the name of the label feature (e.g.

merlin.models.utils.misc_utils.get_parquet_files_names(...)

merlin.models.utils.misc_utils.Timing(message)

A context manager that prints the execution time of the block it manages

merlin.models.utils.misc_utils.get_object_size(obj)

Recursively finds size of objects

merlin.models.utils.misc_utils.validate_dataset(...)

Util function to load NVTabular Dataset from disk

Registry Functions#

merlin.models.utils.registry.camelcase_to_snakecase(name)

merlin.models.utils.registry.snakecase_to_camelcase(name)

merlin.models.utils.registry.default_name(...)

Default name for a class or function.

merlin.models.utils.registry.default_object_name(obj)

merlin.models.utils.registry.Registry(...[, ...])

Dict-like class for managing function registrations.

merlin.models.utils.registry.RegistryMixin(...)

merlin.models.utils.registry.display_list_by_prefix(...)

Creates a help string for names_list grouped by prefix.