diff --git a/README.md b/README.md index d1e394e85..75efa0048 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -## [NVIDIA Merlin](https://github.com/NVIDIA-Merlin) +# [NVIDIA Merlin](https://github.com/NVIDIA-Merlin) ![GitHub tag (latest SemVer)](https://img.shields.io/github/v/tag/NVIDIA-Merlin/Merlin?sort=semver) ![GitHub License](https://img.shields.io/github/license/NVIDIA-Merlin/Merlin) @@ -13,7 +13,7 @@ of data, which is all accessible through easy-to-use APIs. For more information, see [NVIDIA Merlin](https://developer.nvidia.com/nvidia-merlin) on the NVIDIA developer web site. -### Benefits +## Benefits NVIDIA Merlin is a scalable and GPU-accelerated solution, making it easy to build recommender systems from end to end. With NVIDIA Merlin, you can: @@ -26,7 +26,7 @@ build recommender systems from end to end. With NVIDIA Merlin, you can: - Deploy data transformations and trained models to production with only a few lines of code. -### Components of NVIDIA Merlin +## Components of NVIDIA Merlin NVIDIA Merlin consists of the following open source libraries: @@ -97,22 +97,20 @@ With Merlin Core, you can: - Simplify your code by using a shared API for constructing graphs of data transformation operators. -### Example Notebooks and Tutorials +## Example Notebooks and Tutorials -A collection of [end-to-end examples](./examples/) is available within this -repository in the form of Jupyter notebooks. The example notebooks demonstrate -how to: +A collection of [end-to-end examples](./examples/) are available in the form of Jupyter notebooks. +The example notebooks demonstrate how to: -- download and prepare the dataset. -- use preprocessing and engineering features. -- train deep learning recommendation models with TensorFlow, PyTorch, FastAI, or - HugeCTR. -- deploy the models to production. +- Download and prepare a dataset. +- Use preprocessing and engineering features. +- Train deep-learning recommendation models with TensorFlow, PyTorch, FastAI, or HugeCTR. +- Deploy the models to production with Triton Inference Server. These examples are based on different datasets and provide a wide range of real-world use cases. -### Merlin Is Built On +## Merlin Is Built On **[cuDF](https://github.com/rapidsai/cudf)**
Merlin relies on cuDF for GPU-accelerated DataFrame operations used in feature engineering. @@ -125,7 +123,7 @@ dataloading in Merlin Models and HugeCTR. Merlin leverages Triton Inference Server to provide GPU-accelerated serving for recommender system pipelines. -### Feedback and Support +## Feedback and Support To report bugs or get help, please [open an issue](https://github.com/NVIDIA-Merlin/Merlin/issues/new/choose). diff --git a/docs/requirements-doc.txt b/docs/requirements-doc.txt index 8d8ee798c..9b65a8ccc 100644 --- a/docs/requirements-doc.txt +++ b/docs/requirements-doc.txt @@ -6,9 +6,12 @@ markupsafe==2.0.1 natsort==8.1.0 sphinx_rtd_theme sphinx_markdown_tables -sphinx-multiversion -recommonmark>=0.6 -nbsphinx>=0.6 +recommonmark +sphinx-multiversion@git+https://github.com/mikemckiernan/sphinx-multiversion.git@v0.3.0 +sphinxcontrib-copydirs@git+https://github.com/mikemckiernan/sphinxcontrib-copydirs.git@v0.3.1 +sphinx-external-toc==0.2.4 +myst-nb==0.13.2 +linkify-it-py==1.0.3 # smx mergedeep==1.3.4 diff --git a/docs/source/conf.py b/docs/source/conf.py index 5eb723825..7412cb04d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,12 +1,8 @@ # Configuration file for the Sphinx documentation builder. -import errno import os -import shutil import subprocess -import sys from natsort import natsorted -from recommonmark.parser import CommonMarkParser docs_dir = os.path.dirname(__file__) repodir = os.path.abspath(os.path.join(__file__, r"../../..")) @@ -24,19 +20,36 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + "myst_nb", "sphinx_multiversion", "sphinx_rtd_theme", - "recommonmark", "sphinx_markdown_tables", - "nbsphinx", "sphinx.ext.autodoc", "sphinx.ext.coverage", "sphinx.ext.githubpages", "sphinx.ext.napoleon", "sphinx.ext.viewcode", "sphinx.ext.intersphinx", + "sphinx_external_toc", + "sphinxcontrib.copydirs", ] +# MyST configuration settings +external_toc_path = "toc.yaml" +myst_enable_extensions = [ + "deflist", + "html_image", + "linkify", + "replacements", + "tasklist", +] +myst_linkify_fuzzy_links = False +myst_heading_anchors = 3 +jupyter_execute_notebooks = "off" + +# Some documents are RST and include `.. toctree::` directives. +suppress_warnings = ["etoc.toctree", "myst.header", "misc.highlighting_failure"] + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". @@ -48,7 +61,9 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [] +exclude_patterns = [ + "generated", +] # -- Options for HTML output ------------------------------------------------- @@ -56,6 +71,9 @@ # a list of builtin themes. # html_theme = "sphinx_rtd_theme" +html_theme_options = { + "navigation_depth": 3, +} html_show_sourcelink = False # Whitelist pattern for tags (set to None to ignore all tags) @@ -69,23 +87,24 @@ tag_refs = natsorted(tag_refs)[-6:] smv_tag_whitelist = r"^(" + r"|".join(tag_refs) + r")$" else: - # SMV is reading conf.py from a Git archive of the repo at a specific commit. + # SMV is reading conf.py from a Git archive of the repo at a + # specific commit. smv_tag_whitelist = r"^v.*$" # Only include main branch for now smv_branch_whitelist = "^main$" +smv_refs_override_suffix = "-docs" + html_sidebars = {"**": ["versions.html"]} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -source_parsers = {".md": CommonMarkParser} source_suffix = [".rst", ".md"] nbsphinx_allow_errors = True -html_show_sourcelink = False autodoc_inherit_docstrings = False autodoc_default_options = { @@ -97,39 +116,8 @@ autosummary_generate = True +copydirs_additional_dirs = ["../../examples/", "../../README.md"] -def copy_files(src: str): - """ - src_dir: A path, specified as relative to the - docs/source directory in the repository. - The source can be a directory or a file. - Sphinx considers all directories as relative - to the docs/source directory. - - TIP: Add these paths to the .gitignore file. - """ - src_path = os.path.abspath(src) - if not os.path.exists(src_path): - raise FileNotFoundError(errno.ENOENT, os.strerror(errno.ENOENT), src_path) - out_path = os.path.basename(src_path) - out_path = os.path.abspath("{}/".format(out_path)) - - print( - r"Copying source documentation from: {}".format(src_path), - file=sys.stderr, - ) - print(r" ...to destination: {}".format(out_path), file=sys.stderr) - - if os.path.exists(out_path) and os.path.isdir(out_path): - shutil.rmtree(out_path, ignore_errors=True) - if os.path.exists(out_path) and os.path.isfile(out_path): - os.unlink(out_path) - - if os.path.isdir(src_path): - shutil.copytree(src_path, out_path) - else: - shutil.copyfile(src_path, out_path) - - -copy_files(r"../../README.md") -copy_files(r"../../examples/") +copydirs_file_rename = { + "README.md": "index.md", +} diff --git a/docs/source/index.rst b/docs/source/index.rst index 5306334f3..ef86017d8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,17 +1,19 @@ Merlin ====== -.. toctree:: - :maxdepth: 2 +NVIDIA Merlin is an open source library that accelerates recommender +systems on NVIDIA GPUs. +The library brings together several component libraries that simplifies +the process of building high-performing recommenders at scale. - Introduction - Example Notebooks - Merlin Containers - Support Matrix +For more information, see the `Introduction `_. -Indices and tables -================== +Related Resources +----------------- -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +Merlin GitHub Repository + ``_ + +Developer website for Merlin + More information about Merlin is available at our developer website: + ``_. \ No newline at end of file diff --git a/docs/source/support_matrix/index.rst b/docs/source/support_matrix/index.rst index ff4f482d5..bd5b2d89d 100644 --- a/docs/source/support_matrix/index.rst +++ b/docs/source/support_matrix/index.rst @@ -3,12 +3,3 @@ Merlin Support Matrix The following pages provide the software and model versions that Merlin supports for each container. -.. toctree:: - :maxdepth: 2 - - support_matrix_merlin_training - support_matrix_merlin_tensorflow_training - support_matrix_merlin_pytorch_training - support_matrix_merlin_inference - support_matrix_merlin_tensorflow_inference - support_matrix_merlin_pytorch_inference diff --git a/docs/source/toc.yaml b/docs/source/toc.yaml new file mode 100644 index 000000000..bdd4348d2 --- /dev/null +++ b/docs/source/toc.yaml @@ -0,0 +1,59 @@ +root: index +subtrees: + - caption: Contents + entries: + - file: README.md + title: Introduction + - file: examples/index + title: Example Notebooks + subtrees: + - titlesonly: True + entries: + - file: examples/getting-started-movielens/index + title: Getting Started using the MovieLens Dataset + entries: + - file: examples/getting-started-movielens/01-Download-Convert.ipynb + title: MovieLens Download and Convert + - file: examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb + title: Feature Engineering with NVTabular + - file: examples/getting-started-movielens/03-Training-with-HugeCTR.ipynb + title: Training with HugeCTR + - file: examples/getting-started-movielens/03-Training-with-TF.ipynb + title: Training with TensorFlow + - file: examples/getting-started-movielens/03-Training-with-PyTorch.ipynb + title: Training with PyTorch + - file: examples/getting-started-movielens/04-Triton-Inference-with-HugeCTR.ipynb + title: Serving the HugeCTR Model with Triton + - file: examples/getting-started-movielens/04-Triton-Inference-with-TF.ipynb + title: Serving the TensorFlow Model with Triton + - file: examples/Building-and-deploying-multi-stage-RecSys/index.md + entries: + - file: examples/Building-and-deploying-multi-stage-RecSys/01-Building-Recommender-Systems-with-Merlin.ipynb + title: Building the Recommender System + - file: examples/Building-and-deploying-multi-stage-RecSys/02-Deploying-multi-stage-RecSys-with-Merlin-Systems.ipynb + title: Deploying the Recommender System with Triton + - file: examples/scaling-criteo/index.md + entries: + - file: examples/scaling-criteo/01-Download-Convert.ipynb + title: Criteo Download and Convert + - file: examples/scaling-criteo/02-ETL-with-NVTabular.ipynb + title: Feature Engineering with NVTabular + - file: examples/scaling-criteo/03-Training-with-FastAI.ipynb + title: Training with FastAI + - file: examples/scaling-criteo/03-Training-with-HugeCTR.ipynb + title: Training with HugeCTR + - file: examples/scaling-criteo/03-Training-with-TF.ipynb + title: Training with TensorFlow + - file: examples/scaling-criteo/04-Triton-Inference-with-HugeCTR.ipynb + title: Serving the HugeCTR Model with Triton + - file: examples/scaling-criteo/04-Triton-Inference-with-TF.ipynb + title: Serving the TensorFlow Model with Triton + - file: containers.rst + - file: support_matrix/index.rst + entries: + - file: support_matrix/support_matrix_merlin_training.rst + - file: support_matrix/support_matrix_merlin_tensorflow_training.rst + - file: support_matrix/support_matrix_merlin_pytorch_training.rst + - file: support_matrix/support_matrix_merlin_inference.rst + - file: support_matrix/support_matrix_merlin_tensorflow_inference.rst + - file: support_matrix/support_matrix_merlin_pytorch_inference.rst diff --git a/examples/Building-and-deploying-multi-stage-RecSys/README.md b/examples/Building-and-deploying-multi-stage-RecSys/README.md index 5ec0bc4bb..6c9ac4d86 100644 --- a/examples/Building-and-deploying-multi-stage-RecSys/README.md +++ b/examples/Building-and-deploying-multi-stage-RecSys/README.md @@ -1,18 +1,20 @@ -# NVIDIA Merlin Example Notebooks +# Deploying a Multi-Stage Recommender System -We created two jupyter notebook examples based on different stages of a Recommender Systems to demonstrate how to deploy a multi-stage Recommender Systems on Triton Inference Server. The notebooks demonstrate how to use NVTabular, Merlin Models and Merlin Systems libraries for ETL, training, and inference, respectively. +We created two Jupyter notebooks that demonstrate two different stages of a Recommender Systems. +The goal of the notebooks is to show how to deploy a multi-stage Recommender System and serve recommendations with Triton Inference Server. +The notebooks demonstrate how to use the NVTabular, Merlin Models, and Merlin Systems libraries for feature engineering, training, and then inference. -## Structure +The two example notebooks are structured as follows: -Two example notebooks are structured as follows: -- 01-Building-Recommender-Systems-with-Merlin: - - Execute the preprocessing and feature engineering pipeline (ETL) with NVTabular on the GPU - - train a ranking and retrieval model with TensorFlow based on the ETL output - - export saved models, user and item features and item embeddings. -- 02-Deploying-multi-stage-RecSys-with-Merlin-Systems: - - set up Feast feature store for feature storing and Faiss index for similarity search - - build multi-stage recommender systems ensemble pipeline with Merlin Systems operators - - perform Inference with the Triton Inference Server using Merlin Systems library. +- [Building the Recommender System](01-Building-Recommender-Systems-with-Merlin.ipynb): + - Execute the preprocessing and feature engineering pipeline (ETL) with NVTabular on the GPU. + - Train a ranking and retrieval model with TensorFlow based on the ETL output. + - Export the saved models, user and item features, and item embeddings. + +- [Deploying the Recommender System with Triton](02-Deploying-multi-stage-RecSys-with-Merlin-Systems.ipynb): + - Set up a Feast feature store for feature storing and a Faiss index for similarity search. + - Build a multi-stage recommender system ensemble pipeline with Merlin Systems operators. + - Perform inference with the Triton Inference Server using the Merlin Systems library. ## Running the Example Notebooks diff --git a/examples/README.md b/examples/README.md index f7b447725..621287440 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,79 +1,100 @@ # NVIDIA Merlin Example Notebooks -We have created a collection of Jupyter example notebooks based on different datasets to provide end-to-end examples for NVIDIA Merlin. These example notebooks demonstrate how to use NVTabular with TensorFlow, PyTorch, and [HugeCTR](https://github.com/NVIDIA/HugeCTR). Each example provides additional details about the end-to-end workflow, which includes ETL, Training, and Inference. +We have a collection of Jupyter example notebooks that are based on different datasets to provide end-to-end examples for NVIDIA Merlin. +These example notebooks demonstrate how to use NVTabular with TensorFlow, PyTorch, and [HugeCTR](https://github.com/NVIDIA/HugeCTR). +Each example provides additional details about the end-to-end workflow, such as includes ETL, training, and inference. ## Inventory -### 1. [Building and Deploying multi stage RecSys](https://github.com/NVIDIA-Merlin/Merlin/tree/main/examples/Building-and-deploying-multi-stage-RecSys) +### [Building and Deploying a multi-stage RecSys](./Building-and-deploying-multi-stage-RecSys) -Recommender system pipelines are often based on multiple stages: Retrievel, Filtering, Scoring and Ordering. This example provides an end-to-end pipelines leveraging the Merlin framework by -- Processing the dataset using NVTabular -- Training a scoring model using Merlin Models -- Training a retrieval model using Merlin Models -- Building a feature store with feast and ANN index with fiass -- Deploying an end-to-end pipeline of retrieval, scoring, ANN search to Triton Inference Server with Merlin Models +Recommender system pipelines are often based on multiple stages: Retrieval, Filtering, Scoring and Ordering. +This example provides an end-to-end pipeline that leverages the Merlin framework: -### 2. [Getting Started with MovieLens](https://github.com/NVIDIA-Merlin/Merlin/tree/main/examples/getting-started-movielens) +- Processing the dataset using NVTabular. +- Training a scoring model using Merlin Models. +- Training a retrieval model using Merlin Models. +- Building a feature store with Feast and ANN index with Fiass. +- Deploying an end-to-end pipeline of retrieval, scoring, and ANN search to Triton Inference Server. -The MovieLens25M is a popular dataset for recommender systems and is used in academic publications. Most users are familiar with this dataset, so we're focusing primarily on the basic concepts of NVTabular, which includes: -- Learning NVTabular to GPU-accelerate ETL (Preprocess and Feature Engineering) -- Getting familiar with NVTabular's high-level API -- Using single-hot/multi-hot categorical input features with NVTabular -- Using the NVTabular dataloader with the TensorFlow Keras model -- Using the NVTabular dataloader with PyTorch +### [Getting Started with MovieLens](./getting-started-movielens) -### 3. [Scaling Large Datasets with Criteo](https://github.com/NVIDIA-Merlin/Merlin/tree/main/examples/scaling-criteo) +The MovieLens25M is a popular dataset for recommender systems and is used in academic publications. +Many users are familiar with this dataset, so the notebooks focus primarily on the basic concepts of NVTabular: -[Criteo](https://ailab.criteo.com/download-criteo-1tb-click-logs-dataset/) provides the largest publicly available dataset for recommender systems with a size of 1TB of uncompressed click logs that contain 4 billion examples. We demonstrate how to scale NVTabular, as well as: -- Use multiple GPUs and nodes with NVTabular for ETL -- Train recommender system models with the NVTabular dataloader for PyTorch -- Train recommender system models with the NVTabular dataloader for TensorFlow -- Train recommender system models with HugeCTR using a multi-GPU -- Inference with the Triton Inference Server and TensorFlow or HugeCTR +- Learning NVTabular to GPU-accelerate ETL (Preprocess and Feature Engineering). +- Getting familiar with NVTabular's high-level API. +- Using single-hot and multi-hot categorical input features with NVTabular. +- Using the NVTabular dataloader with the TensorFlow Keras model. +- Using the NVTabular dataloader with PyTorch. + +### [Scaling Large Datasets with Criteo](./scaling-criteo) + +[Criteo](https://ailab.criteo.com/download-criteo-1tb-click-logs-dataset/) provides the largest publicly available dataset for recommender systems with a size of 1TB of uncompressed click logs that contain 4 billion examples. +These notebooks demonstrate how to scale NVTabular: + +- Use multiple GPUs and nodes with NVTabular for ETL. +- Train recommender system models with the NVTabular dataloader for PyTorch. +- Train recommender system models with the NVTabular dataloader for TensorFlow. +- Train recommender system models with HugeCTR using a multi-GPU. +- Inference with the Triton Inference Server and TensorFlow or HugeCTR. ## Running the Example Notebooks -You can run the examples with Docker containers. Docker containers are available from the NVIDIA GPU Cloud. Access the catalog of containers at http://ngc.nvidia.com/catalog/containers. +You can run the examples with Docker containers. +Docker containers are available from the NVIDIA GPU Cloud. +Access the catalog of containers at . Depending on which example you want to run, you should use any one of these Docker containers: + - [Merlin-Training](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-training) (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular and HugeCTR) - [Merlin-PyTorch-Training](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-pytorch-inference) (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular and PyTorch) -- [Merlin-Tensorflow-Training] (https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow-training) (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular and TensorFlow) -- [Merlin-Tensorflow-Inference](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow-inference)_ (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular, TensorFlow and Triton Inference Server) +- [Merlin-Tensorflow-Training](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow-training) (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular and TensorFlow) +- [Merlin-Tensorflow-Inference](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-tensorflow-inference) (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular, TensorFlow and Triton Inference Server) - [Merlin-Inference](https://catalog.ngc.nvidia.com/orgs/nvidia/teams/merlin/containers/merlin-inference) (contains Merlin Core, Merlin Models, Merlin Systems, NVTabular, TensorFlow, PyTorch, HugeCTR and Triton Inference Server) -Alternatively, you can `install Merlin Models from source <../README.md#installing-merlin-models-from-source>`_ and other required libraries to run the notebooks on your host. +There are example docker-compose files referenced in [Scaling to large Datasets with Criteo](https://github.com/NVIDIA-Merlin/Merlin/tree/main/examples/scaling-criteo) that you can get from our GitHub repository. +To run the example notebooks using Docker containers, perform the following steps: -You can run the example notebooks by [installing NVTabular](https://github.com/NVIDIA/NVTabular#installation) and other required libraries. Alternatively, Docker containers are available on http://ngc.nvidia.com/catalog/containers/ with pre-installed versions. Depending on which example you want to run, you should use any one of these Docker containers: -- Merlin-Tensorflow-Training (contains NVTabular with TensorFlow) -- Merlin-Pytorch-Training (contains NVTabular with PyTorch) -- Merlin-Training (contains NVTabular with HugeCTR) -- Merlin-Inference (contains NVTabular with TensorFlow and Triton Inference support) +1. Pull and start the container by running the following command: -There are example docker-compose files referenced in [Scaling to large Datasets with Criteo](https://github.com/NVIDIA-Merlin/Merlin/tree/main/examples/scaling-criteo). + ```shell + docker run --gpus all --rm -it \ + -p 8888:8888 -p 8797:8787 -p 8796:8786 --ipc=host \ + /bin/bash + ``` -To run the example notebooks using Docker containers, do the following: + The container opens a shell when the run command execution is completed. + Your shell prompt should look similar to the following example: -1. Pull the container by running the following command: - ``` - docker run --gpus all --rm -it -p 8888:8888 -p 8797:8787 -p 8796:8786 -p 8000:8000 -p 8001:8001 -p 8002:8002 --ipc=host --cap-add SYS_PTRACE /bin/bash + ```shell + root@2efa5b50b909: ``` - The container will open a shell when the run command execution is completed. You will have to start JupyterLab on the Docker container. - -2. The container may require to install jupyter-lab with `conda` or `pip` by running the following command: - ``` +1. Install JupyterLab with `pip` by running the following command: + + ```shell pip install jupyterlab ``` - - For more information, see [Installation Guide](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html). -3. Start the jupyter-lab server by running the following command: + For more information, see the JupyterLab [Installation Guide](https://jupyterlab.readthedocs.io/en/stable/getting_started/installation.html). + +1. Start the JupyterLab server by running the following command: + + ```shell + jupyter-lab --allow-root --ip='0.0.0.0' ``` - jupyter-lab --allow-root --ip='0.0.0.0' --NotebookApp.token='' --notebook-dir=/ + + View the messages in your terminal to identify the URL for JupyterLab. + The messages in your terminal show similar lines to the following example: + + ```shell + Or copy and paste one of these URLs: + http://2efa5b50b909:8888/lab?token=9b537d1fda9e4e9cadc673ba2a472e247deee69a6229ff8d + or http://127.0.0.1:8888/lab?token=9b537d1fda9e4e9cadc673ba2a472e247deee69a6229ff8d ``` -4. Open any browser to access the jupyter-lab server using :8888. +1. Open a browser and use the `127.0.0.1` URL provided in the messages by JupyterLab. -5. Once in the server, navigate to the ```/Merlin/examples/``` directory and try out the example notebooks. +1. After you log in to JupyterLab, navigate to the `/Merlin/examples` directory to try out the example notebooks. diff --git a/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb b/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb index a5b8dc191..4c7e45cb0 100644 --- a/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb +++ b/examples/getting-started-movielens/02-ETL-with-NVTabular.ipynb @@ -366,7 +366,7 @@ "source": [ "In general, the `Op`s in our `Workflow` will require measurements of statistical properties of our data in order to be leveraged. For example, the `Normalize` op requires measurements of the dataset mean and standard deviation, and the `Categorify` op requires an accounting of all the categories a particular feature can manifest. However, we frequently need to measure these properties across datasets which are too large to fit into GPU memory (or CPU memory for that matter) at once.\n", "\n", - "NVTabular solves this by providing the `Dataset` class, which breaks a set of parquet or csv files into into a collection of `cudf.DataFrame` chunks that can fit in device memory. The main purpose of this class is to abstract away the raw format of the data, and to allow other NVTabular classes to reliably materialize a dask_cudf.DataFrame collection (and/or collection-based iterator) on demand. Under the hood, the data decomposition corresponds to the construction of a [dask_cudf.DataFrame](https://docs.rapids.ai/api/cudf/stable/dask-cudf.html) object. By representing our dataset as a lazily-evaluated [Dask](https://dask.org/) collection, we can handle the calculation of complex global statistics (and later, can also iterate over the partitions while feeding data into a neural network). `part_size` defines the size read into GPU-memory at once." + "NVTabular solves this by providing the `Dataset` class, which breaks a set of parquet or csv files into into a collection of `cudf.DataFrame` chunks that can fit in device memory. The main purpose of this class is to abstract away the raw format of the data, and to allow other NVTabular classes to reliably materialize a `dask_cudf.DataFrame` collection (and/or collection-based iterator) on demand. Under the hood, the data decomposition corresponds to the construction of a [dask_cudf.DataFrame](https://docs.rapids.ai/api/cudf/stable/) object. By representing our dataset as a lazily-evaluated [Dask](https://dask.org/) collection, we can handle the calculation of complex global statistics (and later, can also iterate over the partitions while feeding data into a neural network). `part_size` defines the size read into GPU-memory at once." ] }, { diff --git a/examples/getting-started-movielens/03-Training-with-HugeCTR.ipynb b/examples/getting-started-movielens/03-Training-with-HugeCTR.ipynb index f30b42c3d..58a713f73 100644 --- a/examples/getting-started-movielens/03-Training-with-HugeCTR.ipynb +++ b/examples/getting-started-movielens/03-Training-with-HugeCTR.ipynb @@ -30,6 +30,8 @@ "source": [ "\n", "\n", + "# Getting Started MovieLens: Training with HugeCTR\n", + "\n", "## Overview\n", "\n", "In this notebook, we want to provide an overview what HugeCTR framework is, its features and benefits. We will use HugeCTR to train a basic neural network architecture.\n", @@ -349,7 +351,7 @@ ")\n", "```\n", "\n", - "This is only a short introduction in the API. You can read more in the official docs: [Python Interface](https://github.com/NVIDIA/HugeCTR/blob/master/docs/python_interface.md) and [Layer Book](https://github.com/NVIDIA/HugeCTR/blob/master/docs/hugectr_layer_book.md)" + "This is only a short introduction in the API. You can read more in the official docs: [Python Interface](https://nvidia-merlin.github.io/HugeCTR/master/api/python_interface.html) and [HugeCTR Layer Classes and Methods](https://nvidia-merlin.github.io/HugeCTR/master/api/hugectr_layer_book.html)" ] }, { diff --git a/examples/getting-started-movielens/04-Triton-Inference-with-HugeCTR.ipynb b/examples/getting-started-movielens/04-Triton-Inference-with-HugeCTR.ipynb index 26cb87e67..7d4e9899e 100644 --- a/examples/getting-started-movielens/04-Triton-Inference-with-HugeCTR.ipynb +++ b/examples/getting-started-movielens/04-Triton-Inference-with-HugeCTR.ipynb @@ -30,6 +30,8 @@ "source": [ "\n", "\n", + "# Serve Recommendations from the HugeCTR Model\n", + "\n", "## Overview\n", "\n", "In this notebook, we will show how we do inference with our trained deep learning recommender model using Triton Inference Server. In this example, we deploy the NVTabular workflow and HugeCTR model with Triton Inference Server. We deploy them as an ensemble. For each request, Triton Inference Server will feed the input data through the NVTabular workflow and its output through the HugeCR model." diff --git a/examples/getting-started-movielens/04-Triton-Inference-with-TF.ipynb b/examples/getting-started-movielens/04-Triton-Inference-with-TF.ipynb index bc2c1dd6c..1cc7103dc 100644 --- a/examples/getting-started-movielens/04-Triton-Inference-with-TF.ipynb +++ b/examples/getting-started-movielens/04-Triton-Inference-with-TF.ipynb @@ -28,7 +28,7 @@ "source": [ "\n", "\n", - "## Serve Recommendations with Triton Inference Server\n", + "## Serve Recommendations from the TensorFlow Model\n", "\n", "The last step is to deploy the ETL workflow and saved model to production. In the production setting, we want to transform the input data as done during training ETL. We need to apply the same mean/std for continuous features and use the same categorical mapping to convert the categories to continuous integers before we use the deep learning model for a prediction. Therefore, we deploy the NVTabular workflow with the TensorFlow model as an ensemble model to Triton Inference. The ensemble model guarantees that the same transformation are applied to the raw inputs." ] @@ -37,7 +37,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "
" + "\n" ] }, { diff --git a/examples/getting-started-movielens/README.rst b/examples/getting-started-movielens/README.md similarity index 54% rename from examples/getting-started-movielens/README.rst rename to examples/getting-started-movielens/README.md index 84ad80ada..099a068a6 100644 --- a/examples/getting-started-movielens/README.rst +++ b/examples/getting-started-movielens/README.md @@ -1,5 +1,4 @@ -Getting Started with Merlin and the MovieLens Dataset -===================================================== +# Getting Started with Merlin and the MovieLens Dataset The MovieLens25M is a popular dataset for recommender systems and is used in academic publications. Most users are familiar with the dataset and we will teach the basic concepts of Merlin: @@ -12,10 +11,8 @@ Most users are familiar with the dataset and we will teach the basic concepts of Explore the following notebooks: -.. toctree:: :maxdepth: 1 - - Download and Convert <01-Download-Convert.ipynb> - Feature Engineering with NVTabular <02-ETL-with-NVTabular.ipynb> - Training with TensorFlow <03-Training-with-TF.ipynb> - Training with PyTorch <03-Training-with-PyTorch.ipynb> - Serve Recommendations with Triton Inference Server <04-Triton-Inference-with-TF.ipynb> +- [Download and Convert](01-Download-Convert.ipynb) +- [Feature Engineering with NVTabular](02-ETL-with-NVTabular.ipynb) +- [Training with TensorFlow](03-Training-with-TF.ipynb) +- [Training with PyTorch](03-Training-with-PyTorch.ipynb) +- [Serve Recommendations with Triton Inference Server](04-Triton-Inference-with-TF.ipynb) diff --git a/examples/index.rst b/examples/index.rst deleted file mode 100644 index 77a2f504e..000000000 --- a/examples/index.rst +++ /dev/null @@ -1,79 +0,0 @@ -Example Notebooks -================= - -We have collection of Jupyter example notebooks that are based on different datasets to provide end-to-end examples for NVIDIA Merlin. -These example notebooks demonstrate how to use NVTabular with TensorFlow, PyTorch, and `HugeCTR `_. -Each example provides additional details about the end-to-end workflow, which includes ETL, Training, and Inference. - -.. toctree:: - :maxdepth: 1 - - Getting Started with MovieLens - Scaling Large Datasets with Criteo - - -Running the Example Notebooks ------------------------------ - -Docker containers are available from the NVIDIA GPU Cloud. -Access the catalog of containers at http://ngc.nvidia.com/catalog/containers. - -All the training containers include NVTabular for feature engineering. -Choose the container that provides the modeling library that you prefer: - -- Merlin Training (modeling with HugeCTR) -- Merlin TensorFlow Training -- Merlin PyTorch Training - -All the inference containers include NVTabular so that workflows can be read and -they all include Triton Inference Server for deploying models to production and -serving recommendations. -Choose the container that can read models from the modeling library that you used: - -- Merlin Inference (HugeCTR models) -- Merlin TensorFlow Inference -- Merlin PyTorch Inference - -To run the example notebooks using Docker containers, perform the following steps: - -1. Pull and start the container by running the following command: - - .. code-block:: shell - - docker run --gpus all --rm -it \ - -p 8888:8888 -p 8797:8787 -p 8796:8786 --ipc=host \ - /bin/bash - - The container opens a shell when the run command execution is completed. - Your shell prompt should look similar to the following example: - - .. code-block:: shell - - root@2efa5b50b909: - -2. Install JupyterLab with ``pip`` by running the following command: - - .. code-block:: shell - - pip install jupyterlab - - For more information, see the JupyterLab `Installation Guide `_. - -3. Start the JupyterLab server by running the following command: - - .. code-block:: shell - - jupyter-lab --allow-root --ip='0.0.0.0' - - View the messages in your terminal to identify the URL for JupyterLab. - The messages in your terminal show similar lines to the following example: - - .. code-block:: shell - - Or copy and paste one of these URLs: - http://2efa5b50b909:8888/lab?token=9b537d1fda9e4e9cadc673ba2a472e247deee69a6229ff8d - or http://127.0.0.1:8888/lab?token=9b537d1fda9e4e9cadc673ba2a472e247deee69a6229ff8d - -4. Open a browser and use the ``127.0.0.1`` URL provided in the messages by JupyterLab. - -5. After you log in to JupyterLab, navigate to the ``/merlin/examples`` directory to try out the example notebooks. diff --git a/examples/scaling-criteo/02-ETL-with-NVTabular.ipynb b/examples/scaling-criteo/02-ETL-with-NVTabular.ipynb index 4f7cb4748..c2a111df2 100644 --- a/examples/scaling-criteo/02-ETL-with-NVTabular.ipynb +++ b/examples/scaling-criteo/02-ETL-with-NVTabular.ipynb @@ -57,7 +57,7 @@ "\n", "### Multi-GPU and multi-node scaling\n", "\n", - "NVTabular is built on top off [RAPIDS.AI cuDF](https://github.com/rapidsai/cudf/), [dask_cudf](https://docs.rapids.ai/api/cudf/stable/dask-cudf.html) and [dask](https://dask.org/).

\n", + "NVTabular is built on top off [RAPIDS.AI cuDF](https://github.com/rapidsai/cudf/), [dask_cudf](https://docs.rapids.ai/api/cudf/stable/) and [dask](https://dask.org/).

\n", "**Dask** is a task-based library for parallel scheduling and execution. Although it is certainly possible to use the task-scheduling machinery directly to implement customized parallel workflows (we do it in NVTabular), most users only interact with Dask through a Dask Collection API. The most popular \"collection\" API's include:\n", "\n", "* Dask DataFrame: Dask-based version of the Pandas DataFrame/Series API. Note that dask_cudf is just a wrapper around this collection module (dask.dataframe).\n", diff --git a/examples/scaling-criteo/03-Training-with-HugeCTR.ipynb b/examples/scaling-criteo/03-Training-with-HugeCTR.ipynb index 04266f85a..2debaea0a 100644 --- a/examples/scaling-criteo/03-Training-with-HugeCTR.ipynb +++ b/examples/scaling-criteo/03-Training-with-HugeCTR.ipynb @@ -68,8 +68,8 @@ "metadata": {}, "source": [ "If you are not familiar with HugeCTR's Python API and parameters, you can read more in its GitHub repository:\n", - "- [HugeCTR User Guide](https://github.com/NVIDIA/HugeCTR/blob/master/docs/hugectr_user_guide.md)\n", - "- [HugeCTR Python API](https://github.com/NVIDIA/HugeCTR/blob/master/docs/python_interface.md)\n", + "- [HugeCTR User Guide](https://nvidia-merlin.github.io/HugeCTR/master/hugectr_user_guide.html)\n", + "- [HugeCTR Python API](https://nvidia-merlin.github.io/HugeCTR/master/api/python_interface.html)\n", "- [HugeCTR example architectures](https://github.com/NVIDIA/HugeCTR/tree/master/samples)" ] }, diff --git a/examples/scaling-criteo/04-Triton-Inference-with-HugeCTR.ipynb b/examples/scaling-criteo/04-Triton-Inference-with-HugeCTR.ipynb index 167e6fe4f..ba3c6f6ab 100644 --- a/examples/scaling-criteo/04-Triton-Inference-with-HugeCTR.ipynb +++ b/examples/scaling-criteo/04-Triton-Inference-with-HugeCTR.ipynb @@ -99,8 +99,9 @@ "Now we can save our models to be deployed at the inference stage. To do so we will use export_hugectr_ensemble method below. With this method, we can generate the config.pbtxt files automatically for each model. In doing so, we should also create a hugectr_params dictionary, and define the parameters like where the amazonreview.json file will be read, slots which corresponds to number of categorical features, `embedding_vector_size`, `max_nnz`, and `n_outputs` which is number of outputs.

\n", "The script below creates an ensemble triton server model where\n", "- workflow is the the nvtabular workflow used in preprocessing,\n", - "- hugectr_model_path is the HugeCTR model that should be served. \n", - "- This path includes the .model files.name is the base name of the various triton models\n", + "- hugectr_model_path is the HugeCTR model that should be served.\n", + "- This path includes the model files.\n", + "- name is the base name of the various triton models.\n", "- output_path is the path where is model will be saved to.\n", "- cats are the categorical column names\n", "- conts are the continuous column names" diff --git a/examples/scaling-criteo/README.rst b/examples/scaling-criteo/README.md similarity index 60% rename from examples/scaling-criteo/README.rst rename to examples/scaling-criteo/README.md index 4cad4f9cf..6e12e6b25 100644 --- a/examples/scaling-criteo/README.rst +++ b/examples/scaling-criteo/README.md @@ -1,5 +1,4 @@ -Scaling Large Datasets with Criteo -================================== +# Scaling Large Datasets with Criteo Criteo provides the largest publicly available dataset for recommender systems with a size of 1TB of uncompressed click logs that contain 4 billion examples. We demonstrate how to scale NVTabular, as well as: @@ -15,13 +14,10 @@ The compose files enable you to run a pair of training and inference containers. Explore the following notebooks: -.. toctree:: - :maxdepth: 1 - - Download and Convert <01-Download-Convert.ipynb> - Feature Engineering with NVTabular <02-ETL-with-NVTabular.ipynb> - Training with FastAI <03-Training-with-FastAI.ipynb> - Training with HugeCTR <03-Training-with-HugeCTR.ipynb> - Training with TensorFlow <03-Training-with-TF.ipynb> - Deploy the HugeCTR Model with Triton Inference Server <04-Triton-Inference-with-HugeCTR.ipynb> - Deploy the TensorFlow Model with Triton Inference Server <04-Triton-Inference-with-TF.ipynb> \ No newline at end of file +- [Download and Convert](01-Download-Convert.ipynb) +- [Feature Engineering with NVTabular](02-ETL-with-NVTabular.ipynb) +- [Training with FastAI](03-Training-with-FastAI.ipynb) +- [Training with HugeCTR](03-Training-with-HugeCTR.ipynb) +- [Training with TensorFlow](03-Training-with-TF.ipynb) +- [Deploy the HugeCTR Model with Triton Inference Server](04-Triton-Inference-with-HugeCTR.ipynb) +- [Deploy the TensorFlow Model with Triton Inference Server](04-Triton-Inference-with-TF.ipynb) \ No newline at end of file