From 729da27c5d208242e06b62b72fc21019d6af3f95 Mon Sep 17 00:00:00 2001 From: Oliver Holworthy Date: Mon, 12 Jun 2023 14:29:44 +0100 Subject: [PATCH] Build docs for stable branch and make default (#1116) * Update Merlin links to main to stable branch * Match only release tags for docs builds * Setup local branches for docs multi build * Setup docs redirect page to link to stable branch * Remove stable reference from docs link in readme (rely on redirect) --------- Co-authored-by: edknv <109497216+edknv@users.noreply.github.com> --- .github/workflows/docs-sched-rebuild.yaml | 6 +- CONTRIBUTING.md | 4 +- README.md | 16 ++--- docs/README.md | 4 +- docs/source/conf.py | 8 ++- docs/source/index.rst | 2 +- ...lin-Models-and-NVTabular-integration.ipynb | 2 +- examples/03-Exploring-different-models.ipynb | 4 +- examples/04-Exporting-ranking-models.ipynb | 6 +- examples/05-Retrieval-Model.ipynb | 2 +- ...-own-architecture-with-Merlin-Models.ipynb | 4 +- ...f-large-embedding-tables-by-LazyAdam.ipynb | 2 +- ...sed-next-item-prediction-for-fashion.ipynb | 6 +- ...rtainment-with-pretrained-embeddings.ipynb | 2 +- ...emental-training-with-layer-freezing.ipynb | 2 +- .../multi-gpu-data-parallel-training.ipynb | 4 +- .../ranking_with_multitask_learning.ipynb | 4 +- .../transformers-next-item-prediction.ipynb | 64 +++++++++---------- merlin/models/tf/inputs/base.py | 4 +- merlin/models/tf/inputs/embedding.py | 2 +- merlin/models/tf/outputs/block.py | 2 +- 21 files changed, 78 insertions(+), 72 deletions(-) diff --git a/.github/workflows/docs-sched-rebuild.yaml b/.github/workflows/docs-sched-rebuild.yaml index c7fcbfb2c8..1ec226dd73 100644 --- a/.github/workflows/docs-sched-rebuild.yaml +++ b/.github/workflows/docs-sched-rebuild.yaml @@ -26,6 +26,10 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip tox + - name: Setup local branches for docs build + run: | + git branch --track main origin/main || true + git branch --track stable origin/stable || true - name: Building docs (multiversion) run: | tox -vv -e docs-multi @@ -83,7 +87,7 @@ jobs: exit 0 fi # If any of these commands fail, fail the build. - def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" --jq ".default_branch") + def_branch="stable" html_url=$(gh api "repos/${GITHUB_REPOSITORY}/pages" --jq ".html_url") cat > index.html << EOF diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6cdc3bc868..9f33009849 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,7 +23,7 @@ into three categories: ### Your first issue -1. Read the project's [README.md](https://github.com/NVIDIA-Merlin/models/blob/main/README.md) +1. Read the project's [README.md](https://github.com/NVIDIA-Merlin/models/blob/stable/README.md) to learn how to setup the development environment. 2. Find an issue to work on. The best way is to look for the [good first issue](https://github.com/NVIDIA-Merlin/models/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or [help wanted](https://github.com/NVIDIA-Merlin/models/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) labels. @@ -116,7 +116,7 @@ deep_block: Block ``` The [Intersphinx](https://docs.readthedocs.io/en/stable/guides/intersphinx.html) -extension truncates the text to [Schema](https://nvidia-merlin.github.io/core/main/api/merlin.schema.html) +extension truncates the text to [Schema](https://nvidia-merlin.github.io/core/stable/api/merlin.schema.html) and makes it a link. ## Attribution diff --git a/README.md b/README.md index 8be0880602..bca6283a66 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ [![PyPI version shields.io](https://img.shields.io/pypi/v/merlin-models.svg)](https://pypi.python.org/pypi/merlin-models/) ![GitHub License](https://img.shields.io/github/license/NVIDIA-Merlin/models) -[![Documentation](https://img.shields.io/badge/documentation-blue.svg)](https://nvidia-merlin.github.io/models/main/) +[![Documentation](https://img.shields.io/badge/documentation-blue.svg)](https://nvidia-merlin.github.io/models/) The Merlin Models library provides standard models for recommender systems with an aim for high-quality implementations that range from classic machine learning models to highly-advanced deep learning models. @@ -17,7 +17,7 @@ In our initial releases, Merlin Models features a TensorFlow API. The PyTorch AP ### Benefits of Merlin Models -**[RecSys model implementations](https://nvidia-merlin.github.io/models/main/models_overview.html)** - The library provides a high-level API for classic and state-of-the-art deep learning architectures for recommender models. +**[RecSys model implementations](https://nvidia-merlin.github.io/models/stable/models_overview.html)** - The library provides a high-level API for classic and state-of-the-art deep learning architectures for recommender models. These models include both retrieval (e.g. Matrix Factorization, Two tower, YouTube DNN, ..) and ranking (e.g. DLRM, DCN-v2, DeepFM, ...) models. **Building blocks** - Within Merlin Models, recommender models are built on reusable building blocks. @@ -28,7 +28,7 @@ The library provides model definition blocks (MLP layers, factorization layers, For example, models depend on NVTabular for pre-processing and integrate easily with Merlin Systems for inference. The thoughtfully-designed integration makes it straightforward to build performant end-to-end RecSys pipelines. -**[Merlin Models DataLoaders](https://nvidia-merlin.github.io/models/main/api.html#loader-utility-functions)** - Merlin provides seamless integration with common deep learning frameworks, such as TensorFlow, PyTorch, and HugeCTR. +**[Merlin Models DataLoaders](https://nvidia-merlin.github.io/models/stable/api.html#loader-utility-functions)** - Merlin provides seamless integration with common deep learning frameworks, such as TensorFlow, PyTorch, and HugeCTR. When training deep learning recommender system models, data loading can be a bottleneck. To address the challenge, Merlin has custom, highly-optimized dataloaders to accelerate existing TensorFlow and PyTorch training pipelines. The Merlin dataloaders can lead to a speedup that is nine times faster than the same training pipeline used with the GPU. @@ -40,7 +40,7 @@ With the Merlin dataloaders, you can: - Prepare batches asynchronously into the GPU to avoid CPU-to-GPU communication. - Integrate easily into existing TensorFlow or PyTorch training pipelines by using a similar API. -To learn about the core features of Merlin Models, see the [Models Overview](https://nvidia-merlin.github.io/models/main/models_overview.html) page. +To learn about the core features of Merlin Models, see the [Models Overview](https://nvidia-merlin.github.io/models/stable/models_overview.html) page. ### Installation @@ -59,7 +59,7 @@ pip install merlin-models Merlin Models is included in the Merlin Containers. -Refer to the [Merlin Containers](https://nvidia-merlin.github.io/Merlin/main/containers.html) documentation page for information about the Merlin container names, URLs to the container images on the NVIDIA GPU Cloud catalog, and key Merlin components. +Refer to the [Merlin Containers](https://nvidia-merlin.github.io/Merlin/stable/containers.html) documentation page for information about the Merlin container names, URLs to the container images on the NVIDIA GPU Cloud catalog, and key Merlin components. #### Installing Merlin Models from Source @@ -75,7 +75,7 @@ cd models && pip install -e . Merlin Models makes it straightforward to define architectures that adapt to different input features. This adaptability is provided by building on a core feature of the NVTabular library. When you use NVTabular for feature engineering, NVTabular creates a schema that identifies the input features. -You can see the `Schema` object in action by looking at the [From ETL to Training RecSys models - NVTabular and Merlin Models integrated example](https://nvidia-merlin.github.io/models/main/examples/02-Merlin-Models-and-NVTabular-integration.html) example notebook. +You can see the `Schema` object in action by looking at the [From ETL to Training RecSys models - NVTabular and Merlin Models integrated example](https://nvidia-merlin.github.io/models/stable/examples/02-Merlin-Models-and-NVTabular-integration.html) example notebook. You can easily build popular RecSys architectures like [DLRM](http://arxiv.org/abs/1906.00091), as shown in the following code sample. After you define the model, you can train and evaluate it with a typical Keras model. @@ -107,11 +107,11 @@ eval_metrics = model.evaluate(valid, batch_size=1024, return_dict=True) The target binary feature is also inferred from the schema (i.e., tagged as 'TARGET'). You can find more details and information about a low-level API in our overview of the -[Deep Learning Recommender Model](https://nvidia-merlin.github.io/models/main/models_overview.html#deep-learning-recommender-model). +[Deep Learning Recommender Model](https://nvidia-merlin.github.io/models/stable/models_overview.html#deep-learning-recommender-model). ### Notebook Examples and Tutorials -View the example notebooks in the [documentation](https://nvidia-merlin.github.io/models/main/examples/README.html) to help you become familiar with Merlin Models. +View the example notebooks in the [documentation](https://nvidia-merlin.github.io/models/stable/examples/README.html) to help you become familiar with Merlin Models. The same notebooks are available in the `examples` directory from the [Merlin Models](https://github.com/NVIDIA-Merlin/models) GitHub repository. diff --git a/docs/README.md b/docs/README.md index b5b56f069e..b6220adb25 100644 --- a/docs/README.md +++ b/docs/README.md @@ -102,7 +102,7 @@ the link is to the repository: ```markdown Refer to the sample Python programs in the -[examples/blah](https://github.com/NVIDIA-Merlin/models/tree/main/examples/blah) +[examples/blah](https://github.com/NVIDIA-Merlin/models/tree/stable/examples/blah) directory of the repository. ``` @@ -139,7 +139,7 @@ a relative path works both in the HTML docs page and in the repository browsing Use a link to the HTML page like the following: ```markdown - + ``` > I'd like to change this in the future. My preference would be to use a relative diff --git a/docs/source/conf.py b/docs/source/conf.py index 087cd6d9ac..a062665709 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,6 +27,7 @@ # documentation root, use os.path.abspath to make it absolute, like shown here. # import os +import re import subprocess import sys @@ -115,24 +116,25 @@ if os.path.exists(gitdir): tag_refs = subprocess.check_output(["git", "tag", "-l", "v*"]).decode("utf-8").split() + tag_refs = [tag for tag in tag_refs if re.match(r"^v[0-9]+.[0-9]+.[0-9]+$", tag)] tag_refs = natsorted(tag_refs)[-6:] smv_tag_whitelist = r"^(" + r"|".join(tag_refs) + r")$" else: smv_tag_whitelist = r"^v.*$" -smv_branch_whitelist = r"^main$" +smv_branch_whitelist = r"^(main|stable)$" smv_refs_override_suffix = r"-docs" html_sidebars = {"**": ["versions.html"]} -html_baseurl = "https://nvidia-merlin.github.io/models/main" +html_baseurl = "https://nvidia-merlin.github.io/models/stable/" intersphinx_mapping = { "python": ("https://docs.python.org/3", None), "cudf": ("https://docs.rapids.ai/api/cudf/stable/", None), "distributed": ("https://distributed.dask.org/en/latest/", None), "torch": ("https://pytorch.org/docs/stable/", None), - "merlin-core": ("https://nvidia-merlin.github.io/core/main/", None), + "merlin-core": ("https://nvidia-merlin.github.io/core/stable/", None), } autodoc_inherit_docstrings = False diff --git a/docs/source/index.rst b/docs/source/index.rst index a5d8579c21..965e147c89 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -15,7 +15,7 @@ Merlin Models GitHub Repository About Merlin Merlin is the overarching project that brings together the Merlin projects. - See the `documentation `_ + See the `documentation `_ or the `repository `_ on GitHub. Developer website for Merlin diff --git a/examples/02-Merlin-Models-and-NVTabular-integration.ipynb b/examples/02-Merlin-Models-and-NVTabular-integration.ipynb index a3b1a86d44..961fa03c39 100644 --- a/examples/02-Merlin-Models-and-NVTabular-integration.ipynb +++ b/examples/02-Merlin-Models-and-NVTabular-integration.ipynb @@ -1409,7 +1409,7 @@ "\n", "In the next notebooks, we will explore multiple ranking models with Merlin Models.\n", "\n", - "You can learn more about NVTabular, its functionality and supported ops by visiting our [github repository](https://github.com/NVIDIA-Merlin/NVTabular/) or exploring the [examples](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/examples), such as [`Getting Started MovieLens`](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb) or [`Scaling Criteo`](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/examples/scaling-criteo)." + "You can learn more about NVTabular, its functionality and supported ops by visiting our [github repository](https://github.com/NVIDIA-Merlin/NVTabular/) or exploring the [examples](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/examples), such as [`Getting Started MovieLens`](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb) or [`Scaling Criteo`](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/examples/scaling-criteo)." ] } ], diff --git a/examples/03-Exploring-different-models.ipynb b/examples/03-Exploring-different-models.ipynb index a52bdb99af..e99afc4d78 100644 --- a/examples/03-Exploring-different-models.ipynb +++ b/examples/03-Exploring-different-models.ipynb @@ -47,7 +47,7 @@ "\n", "In this example, we'll demonstrate how to build and train several popular deep learning-based ranking model architectures. Merlin Models provides a high-level API to define those architectures, but allows for customization as they are composed by reusable building blocks.\n", "\n", - "In this example notebook, we use for training and evaluation synthetic data that mimics the schema (features and cardinalities) of [Ali-CCP dataset](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1): Alibaba Click and Conversion Prediction dataset. The Ali-CCP is a dataset gathered from real-world traffic logs of the recommender system in Taobao, the largest online retail platform in the world. To download the raw Ali-CCP training and test datasets visit [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can get the raw dataset via this [get_aliccp() function](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/datasets/ecommerce/aliccp/dataset.py#L43) and generate the parquet files from it to be used in this example.\n", + "In this example notebook, we use for training and evaluation synthetic data that mimics the schema (features and cardinalities) of [Ali-CCP dataset](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1): Alibaba Click and Conversion Prediction dataset. The Ali-CCP is a dataset gathered from real-world traffic logs of the recommender system in Taobao, the largest online retail platform in the world. To download the raw Ali-CCP training and test datasets visit [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can get the raw dataset via this [get_aliccp() function](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/datasets/ecommerce/aliccp/dataset.py#L43) and generate the parquet files from it to be used in this example.\n", "\n", "### Learning objectives\n", "- Preparing the data with NVTabular\n", @@ -432,7 +432,7 @@ } }, "source": [ - "We're ready to start training, for that, we create our dataset objects, and under the hood we use Merlin `Loader` class for reading chunks of parquet files. `Loader` asynchronously iterate through CSV or Parquet dataframes on GPU by leveraging an NVTabular `Dataset`. To read more about Merlin optimized dataloaders visit [here](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/dataset.py#L141)." + "We're ready to start training, for that, we create our dataset objects, and under the hood we use Merlin `Loader` class for reading chunks of parquet files. `Loader` asynchronously iterate through CSV or Parquet dataframes on GPU by leveraging an NVTabular `Dataset`. To read more about Merlin optimized dataloaders visit [here](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/dataset.py#L141)." ] }, { diff --git a/examples/04-Exporting-ranking-models.ipynb b/examples/04-Exporting-ranking-models.ipynb index 880fab1283..f0f05f9e31 100644 --- a/examples/04-Exporting-ranking-models.ipynb +++ b/examples/04-Exporting-ranking-models.ipynb @@ -141,7 +141,7 @@ "source": [ "We use the synthetic train and test datasets generated by mimicking the real [Ali-CCP: Alibaba Click and Conversion Prediction](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1) dataset to build our recommender system ranking models. \n", "\n", - "If you would like to use real Ali-CCP dataset instead, you can download the training and test datasets on [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can then use [get_aliccp()](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/datasets/ecommerce/aliccp/dataset.py#L43) function to curate the raw csv files and save them as parquet files." + "If you would like to use real Ali-CCP dataset instead, you can download the training and test datasets on [tianchi.aliyun.com](https://tianchi.aliyun.com/dataset/dataDetail?dataId=408#1). You can then use [get_aliccp()](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/datasets/ecommerce/aliccp/dataset.py#L43) function to curate the raw csv files and save them as parquet files." ] }, { @@ -459,7 +459,7 @@ } }, "source": [ - "In this example, we build, train, and export a Deep Learning Recommendation Model [(DLRM)](https://arxiv.org/abs/1906.00091) architecture. To learn more about how to train different deep learning models, how easily transition from one model to another and the seamless integration between data preparation and model training visit [03-Exploring-different-models.ipynb](https://github.com/NVIDIA-Merlin/models/blob/main/examples/03-Exploring-different-models.ipynb) notebook." + "In this example, we build, train, and export a Deep Learning Recommendation Model [(DLRM)](https://arxiv.org/abs/1906.00091) architecture. To learn more about how to train different deep learning models, how easily transition from one model to another and the seamless integration between data preparation and model training visit [03-Exploring-different-models.ipynb](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/03-Exploring-different-models.ipynb) notebook." ] }, { @@ -693,7 +693,7 @@ "source": [ "We trained and exported our ranking model and NVTabular workflow. In the next step, we will learn how to deploy our trained DLRM model into [Triton Inference Server](https://github.com/triton-inference-server/server) with [Merlin Systems](https://github.com/NVIDIA-Merlin/systems) library. NVIDIA Triton Inference Server (TIS) simplifies the deployment of AI models at scale in production. TIS provides a cloud and edge inferencing solution optimized for both CPUs and GPUs. It supports a number of different machine learning frameworks such as TensorFlow and PyTorch.\n", "\n", - "For the next step, visit [Merlin Systems](https://github.com/NVIDIA-Merlin/systems) library and execute [Serving-Ranking-Models-With-Merlin-Systems](https://github.com/NVIDIA-Merlin/systems/blob/main/examples/Serving-Ranking-Models-With-Merlin-Systems.ipynb) notebook to deploy our saved DLRM and NVTabular workflow models as an ensemble to TIS and obtain prediction results for a qiven request. In doing so, you need to mount the saved DLRM and NVTabular workflow to the inference container following the instructions in the [README.md](https://github.com/NVIDIA-Merlin/systems/blob/main/examples/README.md)." + "For the next step, visit [Merlin Systems](https://github.com/NVIDIA-Merlin/systems) library and execute [Serving-Ranking-Models-With-Merlin-Systems](https://github.com/NVIDIA-Merlin/systems/blob/stable/examples/Serving-Ranking-Models-With-Merlin-Systems.ipynb) notebook to deploy our saved DLRM and NVTabular workflow models as an ensemble to TIS and obtain prediction results for a qiven request. In doing so, you need to mount the saved DLRM and NVTabular workflow to the inference container following the instructions in the [README.md](https://github.com/NVIDIA-Merlin/systems/blob/stable/examples/README.md)." ] } ], diff --git a/examples/05-Retrieval-Model.ipynb b/examples/05-Retrieval-Model.ipynb index c38b880bd9..c2553347e5 100644 --- a/examples/05-Retrieval-Model.ipynb +++ b/examples/05-Retrieval-Model.ipynb @@ -997,7 +997,7 @@ "id": "155af447-97c4-4875-97ad-84e678fd7b40", "metadata": {}, "source": [ - "Note that above when we set `validation_data=valid` in the `model.fit()`, we compute evaluation metrics on validation set using the negative sampling strategy used for training. To determine the exact accuracy of our trained retrieval model, we need to compute the similarity score between a given query and all possible candidates. The higher the score of the positive candidate (the one that is already interacted with, i.e. target item_id returned by dataloader), the more accurate the model is. We can do this using the `topk_model` model that we create below via `to_top_k_encoder` method, and the following section shows how to instantiate it. The `to_top_k_encoder()` is a method of the [RetrievalModelV2](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/models/base.py) class. \n", + "Note that above when we set `validation_data=valid` in the `model.fit()`, we compute evaluation metrics on validation set using the negative sampling strategy used for training. To determine the exact accuracy of our trained retrieval model, we need to compute the similarity score between a given query and all possible candidates. The higher the score of the positive candidate (the one that is already interacted with, i.e. target item_id returned by dataloader), the more accurate the model is. We can do this using the `topk_model` model that we create below via `to_top_k_encoder` method, and the following section shows how to instantiate it. The `to_top_k_encoder()` is a method of the [RetrievalModelV2](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/models/base.py) class. \n", "\n", "`unique_rows_by_features` : A utility function allows extracting both unique user and item features tables as Merlin Dataset object that can easily be converted to a cuDF data frame. The function extracts unique rows from a specified dataset (transformed train set) based on a specified id-column tags (`ITEM` and `ITEM_ID`)." ] diff --git a/examples/06-Define-your-own-architecture-with-Merlin-Models.ipynb b/examples/06-Define-your-own-architecture-with-Merlin-Models.ipynb index 52218d4424..3caa6dbe3c 100644 --- a/examples/06-Define-your-own-architecture-with-Merlin-Models.ipynb +++ b/examples/06-Define-your-own-architecture-with-Merlin-Models.ipynb @@ -45,7 +45,7 @@ "\n", "This notebook is created using the latest stable [merlin-tensorflow](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow/tags) container. \n", "\n", - "In [Iterating over Deep Learning Models using Merlin Models](https://nvidia-merlin.github.io/models/main/examples/03-Exploring-different-models.html), we conducted a benchmark of standard and deep learning-based ranking models provided by the high-level Merlin Models API. The library also includes the standard components of deep learning that let recsys practitioners and researchers to define custom models, train and export them for inference.\n", + "In [Iterating over Deep Learning Models using Merlin Models](https://nvidia-merlin.github.io/models/stable/examples/03-Exploring-different-models.html), we conducted a benchmark of standard and deep learning-based ranking models provided by the high-level Merlin Models API. The library also includes the standard components of deep learning that let recsys practitioners and researchers to define custom models, train and export them for inference.\n", "\n", "\n", "In this example, we combine pre-existing blocks and demonstrate how to create the [DLRM](https://arxiv.org/abs/1906.00091) architecture.\n", @@ -1385,7 +1385,7 @@ "source": [ "## Conclusion \n", "\n", - "Merlin Models provides common and state-of-the-art RecSys architectures in a high-level API as well as all the required low-level building blocks for you to create your own architecture (input blocks, MLP layers, output blocks, loss functions, etc.). In this example, we explored a subset of these pre-existing blocks to create the DLRM model, but you can view our [documentation](https://nvidia-merlin.github.io/models/main/) to discover more. You can also [contribute](https://github.com/NVIDIA-Merlin/models/blob/main/CONTRIBUTING.md) to the library by submitting new RecSys architectures and custom building Blocks. \n", + "Merlin Models provides common and state-of-the-art RecSys architectures in a high-level API as well as all the required low-level building blocks for you to create your own architecture (input blocks, MLP layers, output blocks, loss functions, etc.). In this example, we explored a subset of these pre-existing blocks to create the DLRM model, but you can view our [documentation](https://nvidia-merlin.github.io/models/stable/) to discover more. You can also [contribute](https://github.com/NVIDIA-Merlin/models/blob/stable/CONTRIBUTING.md) to the library by submitting new RecSys architectures and custom building Blocks. \n", "\n", "\n", "\n", diff --git a/examples/usecases/accelerate-training-of-large-embedding-tables-by-LazyAdam.ipynb b/examples/usecases/accelerate-training-of-large-embedding-tables-by-LazyAdam.ipynb index 25be4beab9..957c8522c8 100644 --- a/examples/usecases/accelerate-training-of-large-embedding-tables-by-LazyAdam.ipynb +++ b/examples/usecases/accelerate-training-of-large-embedding-tables-by-LazyAdam.ipynb @@ -45,7 +45,7 @@ "\n", "This notebook is created using the latest stable [merlin-tensorflow](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow/tags) container. \n", "\n", - "Merlin Models provide various model APIs for training, as shown in notebook [Iterating over Deep Learning Models using Merlin Models](https://nvidia-merlin.github.io/models/main/examples/03-Exploring-different-models.html). We can create a model, such as [Two Tower](https://nvidia-merlin.github.io/models/main/models_overview.html?highlight=two%20tower#two-tower), [DLRM](https://nvidia-merlin.github.io/models/main/examples/03-Exploring-different-models.html#dlrm-model) and so on, by simply one line: `model=mm.DLRMModel(schema)`. Some models contain large embedding tables, and training could be slow on such large sparse embeddings. However, this process could be accelerated by using a special optimizer, LazyAdam.\n", + "Merlin Models provide various model APIs for training, as shown in notebook [Iterating over Deep Learning Models using Merlin Models](https://nvidia-merlin.github.io/models/stable/examples/03-Exploring-different-models.html). We can create a model, such as [Two Tower](https://nvidia-merlin.github.io/models/stable/models_overview.html?highlight=two%20tower#two-tower), [DLRM](https://nvidia-merlin.github.io/models/stable/examples/03-Exploring-different-models.html#dlrm-model) and so on, by simply one line: `model=mm.DLRMModel(schema)`. Some models contain large embedding tables, and training could be slow on such large sparse embeddings. However, this process could be accelerated by using a special optimizer, LazyAdam.\n", "\n", "In this example, we utilize LazyAdam for large embedding tables and original Adam for other trainable weights to accelerate the whole training process.\n", "\n", diff --git a/examples/usecases/ecommerce-session-based-next-item-prediction-for-fashion.ipynb b/examples/usecases/ecommerce-session-based-next-item-prediction-for-fashion.ipynb index 8d3eff7df5..6769dae3f2 100644 --- a/examples/usecases/ecommerce-session-based-next-item-prediction-for-fashion.ipynb +++ b/examples/usecases/ecommerce-session-based-next-item-prediction-for-fashion.ipynb @@ -427,7 +427,7 @@ "source": [ "## Feature Engineering with NVTabular\n", "\n", - "We use NVTabular for Feature Engineering. If you want to learn more about NVTabular, we recommend the [examples in the NVTabular GitHub Repository](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/examples)." + "We use NVTabular for Feature Engineering. If you want to learn more about NVTabular, we recommend the [examples in the NVTabular GitHub Repository](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/examples)." ] }, { @@ -576,7 +576,7 @@ "id": "a375e1d5", "metadata": {}, "source": [ - "Merlin Models can infer the neural network architecture from the dataset schema. We will Tag the columns accordingly based on the type of each column. If you want to learn more, we recommend our [Dataset Schema Example](https://github.com/NVIDIA-Merlin/models/blob/main/examples/02-Merlin-Models-and-NVTabular-integration.ipynb)." + "Merlin Models can infer the neural network architecture from the dataset schema. We will Tag the columns accordingly based on the type of each column. If you want to learn more, we recommend our [Dataset Schema Example](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/02-Merlin-Models-and-NVTabular-integration.ipynb)." ] }, { @@ -1081,7 +1081,7 @@ "id": "4c5cbe51-a5cb-4964-9bb2-7ecf53ee36ec", "metadata": {}, "source": [ - "Next, we define the prediction task. Our objective is multi-class classification - which is the item purchased at the end of the session. Therefore, this is a multi-class classification task, and the default_loss in the `CategoricalOutput` class is \"categorical_crossentropy\". [CategoricalOutput](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/outputs/classification.py#L112) class has the functionality to do `weight-tying`, when we provide the `EmbeddingTable` related to the target feature in the `to_call` method. Note that in our example we feed the embedding table for the `item_id_purchase_id` domain name, since it reflects the fact that the `item_id_list_seq` and `item_id_last` input columns were jointly encoded and they share the same embedding table." + "Next, we define the prediction task. Our objective is multi-class classification - which is the item purchased at the end of the session. Therefore, this is a multi-class classification task, and the default_loss in the `CategoricalOutput` class is \"categorical_crossentropy\". [CategoricalOutput](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/outputs/classification.py#L112) class has the functionality to do `weight-tying`, when we provide the `EmbeddingTable` related to the target feature in the `to_call` method. Note that in our example we feed the embedding table for the `item_id_purchase_id` domain name, since it reflects the fact that the `item_id_list_seq` and `item_id_last` input columns were jointly encoded and they share the same embedding table." ] }, { diff --git a/examples/usecases/entertainment-with-pretrained-embeddings.ipynb b/examples/usecases/entertainment-with-pretrained-embeddings.ipynb index fa33179feb..a3db3c19b0 100644 --- a/examples/usecases/entertainment-with-pretrained-embeddings.ipynb +++ b/examples/usecases/entertainment-with-pretrained-embeddings.ipynb @@ -48,7 +48,7 @@ "### Learning objectives\n", "\n", "- Training with pretrained embeddings\n", - "- Understanding [the Schema file](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/schema/schema.py)" + "- Understanding [the Schema file](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/schema/schema.py)" ] }, { diff --git a/examples/usecases/incremental-training-with-layer-freezing.ipynb b/examples/usecases/incremental-training-with-layer-freezing.ipynb index c44ff94286..6dff4f4d33 100644 --- a/examples/usecases/incremental-training-with-layer-freezing.ipynb +++ b/examples/usecases/incremental-training-with-layer-freezing.ipynb @@ -104,7 +104,7 @@ "source": [ "## Building a Two-Tower Model with Merlin Models\n", "\n", - "We choose Two-Tower model architecture for this example. To learn more about a Two-Tower model you can visit this [notebook](https://github.com/NVIDIA-Merlin/models/blob/main/examples/05-Retrieval-Model.ipynb)." + "We choose Two-Tower model architecture for this example. To learn more about a Two-Tower model you can visit this [notebook](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/05-Retrieval-Model.ipynb)." ] }, { diff --git a/examples/usecases/multi-gpu-data-parallel-training.ipynb b/examples/usecases/multi-gpu-data-parallel-training.ipynb index 0f3fe5b04a..a286a9c941 100644 --- a/examples/usecases/multi-gpu-data-parallel-training.ipynb +++ b/examples/usecases/multi-gpu-data-parallel-training.ipynb @@ -260,7 +260,7 @@ "metadata": {}, "source": [ "We can take a look what required code changes are automatically applied by Merlin Models:\n", - "- Horovod requires to initialize horovod (`hvd.init()`) see [distributed.backend](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/distributed/backend.py)\n", + "- Horovod requires to initialize horovod (`hvd.init()`) see [distributed.backend](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/distributed/backend.py)\n", "- After the first batch, we need to broadcast the initial variables from one worker to all other ones. As we initialize the model randomly, every worker would have different parameters. In the beginning, we need to ensure every worker starts with the same state.\n", "- We need to scale the learning rate by number of workers\n", "- We need to average the evaluation metrics (Note: AUC metrics could slightly be different, as averaging AUC vs. calculating AUC on the full dataset is different)\n", @@ -453,7 +453,7 @@ "source": [ "In this example notebook we learned how to scale a Merlin Models training pipeline using Horovod to multiple GPUs to reduce training time. In theory, you should be able to use horovod for multi-node training, as well.\n", "\n", - "If you want to learn about how to scale NVTabular feature engineering workflows to multi-GPU, check out our [example](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/examples/03-Running-on-multiple-GPUs-or-on-CPU.ipynb)." + "If you want to learn about how to scale NVTabular feature engineering workflows to multi-GPU, check out our [example](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/examples/03-Running-on-multiple-GPUs-or-on-CPU.ipynb)." ] } ], diff --git a/examples/usecases/ranking_with_multitask_learning.ipynb b/examples/usecases/ranking_with_multitask_learning.ipynb index 132354a4c4..0b47b42388 100644 --- a/examples/usecases/ranking_with_multitask_learning.ipynb +++ b/examples/usecases/ranking_with_multitask_learning.ipynb @@ -101,8 +101,8 @@ "id": "c39a0c62", "metadata": {}, "source": [ - "Here we generate synthetic dataset based on the [schema](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/datasets/entertainment/tenrec_video/schema.pbtxt) of the `tenrec-video` dataset. The original dataset was released by the [TenRec paper](https://arxiv.org/abs/2210.10629), and is suitable for multi-task learning for providing multiple targets (types of user-item events). \n", - "To make the synthetic data more realistic, our data generator takes into account the original cardinalities of categorical features and the dependency of user features to user id and item features to item id. For more information about how the schema API works you can check this [example](https://github.com/NVIDIA-Merlin/models/blob/main/examples/02-Merlin-Models-and-NVTabular-integration.ipynb)." + "Here we generate synthetic dataset based on the [schema](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/datasets/entertainment/tenrec_video/schema.pbtxt) of the `tenrec-video` dataset. The original dataset was released by the [TenRec paper](https://arxiv.org/abs/2210.10629), and is suitable for multi-task learning for providing multiple targets (types of user-item events). \n", + "To make the synthetic data more realistic, our data generator takes into account the original cardinalities of categorical features and the dependency of user features to user id and item features to item id. For more information about how the schema API works you can check this [example](https://github.com/NVIDIA-Merlin/models/blob/stable/examples/02-Merlin-Models-and-NVTabular-integration.ipynb)." ] }, { diff --git a/examples/usecases/transformers-next-item-prediction.ipynb b/examples/usecases/transformers-next-item-prediction.ipynb index 38801928af..b409170f00 100644 --- a/examples/usecases/transformers-next-item-prediction.ipynb +++ b/examples/usecases/transformers-next-item-prediction.ipynb @@ -70,13 +70,13 @@ "\n", "**Read more about libraries used in the import statements below**\n", "\n", - "- [get_lib](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/core/dispatch.py)\n", - "- [get_booking](https://github.com/NVIDIA-Merlin/models/tree/main/merlin/datasets/ecommerce)\n", - "- [nvtabular](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/nvtabular)\n", - "- [nvtabular ops](https://github.com/NVIDIA-Merlin/NVTabular/tree/main/nvtabular/ops)\n", - "- [schema tags](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/schema/tags.py)\n", - "- [merlin models tensorflow](https://github.com/NVIDIA-Merlin/models/tree/main/merlin/models/tf)\n", - "- [get_booking](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/datasets/ecommerce/booking/dataset.py)" + "- [get_lib](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/core/dispatch.py)\n", + "- [get_booking](https://github.com/NVIDIA-Merlin/models/tree/stable/merlin/datasets/ecommerce)\n", + "- [nvtabular](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/nvtabular)\n", + "- [nvtabular ops](https://github.com/NVIDIA-Merlin/NVTabular/tree/stable/nvtabular/ops)\n", + "- [schema tags](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/schema/tags.py)\n", + "- [merlin models tensorflow](https://github.com/NVIDIA-Merlin/models/tree/stable/merlin/models/tf)\n", + "- [get_booking](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/datasets/ecommerce/booking/dataset.py)" ] }, { @@ -327,21 +327,21 @@ "\n", "We will use NVTabular for this work. It offers optimized tabular data preprocessing operators that run on the GPU. If you would like to learn more about the NVTabular library, please take a look [here](https://github.com/NVIDIA-Merlin/NVTabular).\n", "\n", - "Read more about the [Merlin's Dataset API](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/io/dataset.py) \n", - "Read more about how [parquet files are read in and processed by Merlin](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/io/parquet.py) \n", - "Read more about [Tags](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/schema/tags.py) \n", - "- [schema_select_by_tag](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/schema/schema.py) \n", + "Read more about the [Merlin's Dataset API](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/io/dataset.py) \n", + "Read more about how [parquet files are read in and processed by Merlin](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/io/parquet.py) \n", + "Read more about [Tags](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/schema/tags.py) \n", + "- [schema_select_by_tag](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/schema/schema.py) \n", "\n", - "Read more about [NVTabular Workflows](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/workflow/workflow.py) \n", - "- [fit_transform](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/workflow/workflow.py)\n", - "- [transform](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/workflow/workflow.py) \n", + "Read more about [NVTabular Workflows](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/workflow/workflow.py) \n", + "- [fit_transform](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/workflow/workflow.py)\n", + "- [transform](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/workflow/workflow.py) \n", "\n", "Read more about the [NVTabular Operators]() \n", - "- [Categorify](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/ops/categorify.py)\n", - "- [AddTags](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/ops/add_metadata.py)\n", - "- [LambdaOp](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/ops/lambdaop.py)\n", - "- [Rename](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/ops/rename.py)\n", - "- [Filter](https://github.com/NVIDIA-Merlin/NVTabular/blob/main/nvtabular/ops/filter.py)\n", + "- [Categorify](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/ops/categorify.py)\n", + "- [AddTags](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/ops/add_metadata.py)\n", + "- [LambdaOp](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/ops/lambdaop.py)\n", + "- [Rename](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/ops/rename.py)\n", + "- [Filter](https://github.com/NVIDIA-Merlin/NVTabular/blob/stable/nvtabular/ops/filter.py)\n", "\n" ] }, @@ -794,19 +794,19 @@ "\n", "\n", "**Read more about the apis used to construct models** \n", - "- [blocks](https://github.com/NVIDIA-Merlin/models/tree/main/merlin/models/tf/blocks)\n", - "- [MLPBlock](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/blocks/mlp.py)\n", - "- [InputBlockV2](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/inputs/base.py)\n", - "- [Embeddings](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/inputs/embedding.py)\n", - "- [XLNetBlock](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/transformers/block.py)\n", - "- [CategoricalOutput](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/outputs/classification.py)\n", - "- [.schema.select_by_name](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/schema/schema.py)\n", - "- [.schema.select_by_tag](https://github.com/NVIDIA-Merlin/core/blob/main/merlin/schema/schema.py)\n", - "- [model.compile()](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/models/base.py)\n", - "- [model.fit()](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/models/base.py)\n", - "- [model.evaluate()](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/models/base.py)\n", - "- [mm.SequenceMaskRandom](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/transforms/sequence.py)\n", - "- [mm.SequenceMaskLast](https://github.com/NVIDIA-Merlin/models/blob/main/merlin/models/tf/transforms/sequence.py)" + "- [blocks](https://github.com/NVIDIA-Merlin/models/tree/stable/merlin/models/tf/blocks)\n", + "- [MLPBlock](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/blocks/mlp.py)\n", + "- [InputBlockV2](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/inputs/base.py)\n", + "- [Embeddings](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/inputs/embedding.py)\n", + "- [XLNetBlock](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/transformers/block.py)\n", + "- [CategoricalOutput](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/outputs/classification.py)\n", + "- [.schema.select_by_name](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/schema/schema.py)\n", + "- [.schema.select_by_tag](https://github.com/NVIDIA-Merlin/core/blob/stable/merlin/schema/schema.py)\n", + "- [model.compile()](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/models/base.py)\n", + "- [model.fit()](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/models/base.py)\n", + "- [model.evaluate()](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/models/base.py)\n", + "- [mm.SequenceMaskRandom](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/transforms/sequence.py)\n", + "- [mm.SequenceMaskLast](https://github.com/NVIDIA-Merlin/models/blob/stable/merlin/models/tf/transforms/sequence.py)" ] }, { diff --git a/merlin/models/tf/inputs/base.py b/merlin/models/tf/inputs/base.py index b3924c6741..c943db79fd 100644 --- a/merlin/models/tf/inputs/base.py +++ b/merlin/models/tf/inputs/base.py @@ -70,7 +70,7 @@ def InputBlock( ---------- schema: Schema Schema of the input data. This Schema object will be automatically generated using - [NVTabular](https://nvidia-merlin.github.io/NVTabular/main/Introduction.html). + [NVTabular](https://nvidia-merlin.github.io/NVTabular/stable/Introduction.html). Next to this, it's also possible to construct it manually. branches: Dict[str, Block], optional Dictionary of branches to use inside the InputBlock. @@ -262,7 +262,7 @@ def InputBlockV2( ---------- schema : Schema Schema of the input data. This Schema object will be automatically generated using - [NVTabular](https://nvidia-merlin.github.io/NVTabular/main/Introduction.html). + [NVTabular](https://nvidia-merlin.github.io/NVTabular/stable/Introduction.html). Next to this, it's also possible to construct it manually. categorical : Union[Tags, Layer], defaults to `Tags.CATEGORICAL` A block or column-selector to use for categorical-features. diff --git a/merlin/models/tf/inputs/embedding.py b/merlin/models/tf/inputs/embedding.py index 62192e0f45..aff30184a6 100644 --- a/merlin/models/tf/inputs/embedding.py +++ b/merlin/models/tf/inputs/embedding.py @@ -606,7 +606,7 @@ def Embeddings( ---------- schema: Schema Schema of the input data. This Schema object will be automatically generated using - [NVTabular](https://nvidia-merlin.github.io/NVTabular/main/Introduction.html). + [NVTabular](https://nvidia-merlin.github.io/NVTabular/stable/Introduction.html). Next to this, it's also possible to construct it manually. dim: Optional[Union[Dict[str, int], int]], optional A dim to use for all features, or a diff --git a/merlin/models/tf/outputs/block.py b/merlin/models/tf/outputs/block.py index 3114846487..1b41571e28 100644 --- a/merlin/models/tf/outputs/block.py +++ b/merlin/models/tf/outputs/block.py @@ -48,7 +48,7 @@ def OutputBlock( ---------- schema : Schema Schema of the input data. This Schema object will be automatically generated using - [NVTabular](https://nvidia-merlin.github.io/NVTabular/main/Introduction.html). + [NVTabular](https://nvidia-merlin.github.io/NVTabular/stable/Introduction.html). Next to this, it's also possible to construct it manually. model_outputs: Optional[Union[Sequence[ModelOutput], Dict[str, ModelOutput]]] Optional dict or list of ModelOutput. If a dict, the keys must be the