# TorchRec (Beta Release)
[Docs](https://pytorch.org/torchrec/)
TorchRec is a PyTorch domain library built to provide common sparsity & parallelism primitives needed for large-scale recommender systems (RecSys). It allows authors to train models with large embedding tables sharded across many GPUs.
## TorchRec contains:
- Parallelism primitives that enable easy authoring of large, performant multi-device/multi-node models using hybrid data-parallelism/model-parallelism.
- The TorchRec sharder can shard embedding tables with different sharding strategies including data-parallel, table-wise, row-wise, table-wise-row-wise, column-wise, table-wise-column-wise sharding.
- The TorchRec planner can automatically generate optimized sharding plans for models.
- Pipelined training overlaps dataloading device transfer (copy to GPU), inter-device communications (input_dist), and computation (forward, backward) for increased performance.
- Optimized kernels for RecSys powered by FBGEMM.
- Quantization support for reduced precision training and inference.
- Common modules for RecSys.
- Production-proven model architectures for RecSys.
- RecSys datasets (criteo click logs and movielens)
- Examples of end-to-end training such the dlrm event prediction model trained on criteo click logs dataset.
# Installation
Torchrec requires Python >= 3.8 and CUDA >= 11.8 (CUDA is highly recommended for performance but not required). The example below shows how to install with Python 3.8 and CUDA 12.1. This setup assumes you have conda installed.
## Binaries
Experimental binary on Linux for Python 3.8, 3.9, 3.10, 3.11 and 3.12 (experimental), and CPU, CUDA 11.8 and CUDA 12.1 can be installed via pip wheels from [download.pytorch.org](download.pytorch.org) and PyPI (only for CUDA 12.1).
Below we show installations for CUDA 12.1 as an example. For CPU or CUDA 11.8, swap "cu121" for "cpu" or "cu118".
### Installations
```
Nightly
pip install torch --index-url https://download.pytorch.org/whl/nightly/cu121
pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cu121
pip install torchmetrics==1.0.3
pip install torchrec --index-url https://download.pytorch.org/whl/nightly/cu121
Stable via pytorch.org
pip install torch --index-url https://download.pytorch.org/whl/cu121
pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/cu121
pip install torchmetrics==1.0.3
pip install torchrec --index-url https://download.pytorch.org/whl/cu121
Stable via PyPI (only for CUDA 12.1)
pip install torch
pip install fbgemm-gpu
pip install torchrec
```
### Colab example: introduction + install
See our colab notebook for an introduction to torchrec which includes runnable installation.
- [Tutorial Source](https://github.com/pytorch/torchrec/blob/main/Torchrec_Introduction.ipynb)
- Open in [Google Colab](https://colab.research.google.com/github/pytorch/torchrec/blob/main/Torchrec_Introduction.ipynb)
## From Source
We are currently iterating on the setup experience. For now, we provide manual instructions on how to build from source. The example below shows how to install with CUDA 12.1. This setup assumes you have conda installed.
1. Install pytorch. See [pytorch documentation](https://pytorch.org/get-started/locally/).
```
CUDA 12.1
pip install torch --index-url https://download.pytorch.org/whl/nightly/cu121
CUDA 11.8
pip install torch --index-url https://download.pytorch.org/whl/nightly/cu118
CPU
pip install torch --index-url https://download.pytorch.org/whl/nightly/cpu
```
2. Clone TorchRec.
```
git clone --recursive https://github.com/pytorch/torchrec
cd torchrec
```
3. Install FBGEMM.
```
CUDA 12.1
pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cu121
CUDA 11.8
pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cu118
CPU
pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cpu
```
4. Install other requirements.
```
pip install -r requirements.txt
```
4. Install TorchRec.
```
python setup.py install develop
```
5. Test the installation (use torchx-nightly for 3.11; for 3.12, torchx currently doesn't work).
```
GPU mode
torchx run -s local_cwd dist.ddp -j 1x2 --gpu 2 --script test_installation.py
CPU Mode
torchx run -s local_cwd dist.ddp -j 1x2 --script test_installation.py -- --cpu_only
```
See [TorchX](https://pytorch.org/torchx/) for more information on launching distributed and remote jobs.
5. If you want to run a more complex example, please take a look at the torchrec [DLRM example](https://github.com/facebookresearch/dlrm/blob/main/torchrec_dlrm/dlrm_main.py).
## Contributing
### Pyre and linting
Before landing, please make sure that pyre and linting look okay. To run our linters, you will need to
```
pip install pre-commit
```
, and run it.
For Pyre, you will need to
```
cat .pyre_configuration
pip install pyre-check-nightly==<VERSION FROM CONFIG>
pyre check
```
We will also check for these issues in our GitHub actions.
## License
TorchRec is BSD licensed, as found in the [LICENSE](LICENSE) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/pytorch/torchrec",
"name": "torchrec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "pytorch, recommendation systems, sharding",
"author": "TorchRec Team",
"author_email": "packages@pytorch.org",
"download_url": null,
"platform": null,
"description": "# TorchRec (Beta Release)\n[Docs](https://pytorch.org/torchrec/)\n\nTorchRec is a PyTorch domain library built to provide common sparsity & parallelism primitives needed for large-scale recommender systems (RecSys). It allows authors to train models with large embedding tables sharded across many GPUs.\n\n## TorchRec contains:\n- Parallelism primitives that enable easy authoring of large, performant multi-device/multi-node models using hybrid data-parallelism/model-parallelism.\n- The TorchRec sharder can shard embedding tables with different sharding strategies including data-parallel, table-wise, row-wise, table-wise-row-wise, column-wise, table-wise-column-wise sharding.\n- The TorchRec planner can automatically generate optimized sharding plans for models.\n- Pipelined training overlaps dataloading device transfer (copy to GPU), inter-device communications (input_dist), and computation (forward, backward) for increased performance.\n- Optimized kernels for RecSys powered by FBGEMM.\n- Quantization support for reduced precision training and inference.\n- Common modules for RecSys.\n- Production-proven model architectures for RecSys.\n- RecSys datasets (criteo click logs and movielens)\n- Examples of end-to-end training such the dlrm event prediction model trained on criteo click logs dataset.\n\n# Installation\n\nTorchrec requires Python >= 3.8 and CUDA >= 11.8 (CUDA is highly recommended for performance but not required). The example below shows how to install with Python 3.8 and CUDA 12.1. This setup assumes you have conda installed.\n\n## Binaries\n\nExperimental binary on Linux for Python 3.8, 3.9, 3.10, 3.11 and 3.12 (experimental), and CPU, CUDA 11.8 and CUDA 12.1 can be installed via pip wheels from [download.pytorch.org](download.pytorch.org) and PyPI (only for CUDA 12.1).\n\nBelow we show installations for CUDA 12.1 as an example. For CPU or CUDA 11.8, swap \"cu121\" for \"cpu\" or \"cu118\".\n\n### Installations\n```\nNightly\n\npip install torch --index-url https://download.pytorch.org/whl/nightly/cu121\npip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cu121\npip install torchmetrics==1.0.3\npip install torchrec --index-url https://download.pytorch.org/whl/nightly/cu121\n\nStable via pytorch.org\n\npip install torch --index-url https://download.pytorch.org/whl/cu121\npip install fbgemm-gpu --index-url https://download.pytorch.org/whl/cu121\npip install torchmetrics==1.0.3\npip install torchrec --index-url https://download.pytorch.org/whl/cu121\n\nStable via PyPI (only for CUDA 12.1)\n\npip install torch\npip install fbgemm-gpu\npip install torchrec\n\n```\n\n\n### Colab example: introduction + install\nSee our colab notebook for an introduction to torchrec which includes runnable installation.\n - [Tutorial Source](https://github.com/pytorch/torchrec/blob/main/Torchrec_Introduction.ipynb)\n - Open in [Google Colab](https://colab.research.google.com/github/pytorch/torchrec/blob/main/Torchrec_Introduction.ipynb)\n\n## From Source\n\nWe are currently iterating on the setup experience. For now, we provide manual instructions on how to build from source. The example below shows how to install with CUDA 12.1. This setup assumes you have conda installed.\n\n1. Install pytorch. See [pytorch documentation](https://pytorch.org/get-started/locally/).\n ```\n CUDA 12.1\n\n pip install torch --index-url https://download.pytorch.org/whl/nightly/cu121\n\n CUDA 11.8\n\n pip install torch --index-url https://download.pytorch.org/whl/nightly/cu118\n\n CPU\n\n pip install torch --index-url https://download.pytorch.org/whl/nightly/cpu\n ```\n\n2. Clone TorchRec.\n ```\n git clone --recursive https://github.com/pytorch/torchrec\n cd torchrec\n ```\n\n3. Install FBGEMM.\n ```\n CUDA 12.1\n\n pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cu121\n\n CUDA 11.8\n\n pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cu118\n\n CPU\n\n pip install fbgemm-gpu --index-url https://download.pytorch.org/whl/nightly/cpu\n ```\n\n4. Install other requirements.\n ```\n pip install -r requirements.txt\n ```\n\n4. Install TorchRec.\n ```\n python setup.py install develop\n ```\n\n5. Test the installation (use torchx-nightly for 3.11; for 3.12, torchx currently doesn't work).\n ```\n GPU mode\n\n torchx run -s local_cwd dist.ddp -j 1x2 --gpu 2 --script test_installation.py\n\n CPU Mode\n\n torchx run -s local_cwd dist.ddp -j 1x2 --script test_installation.py -- --cpu_only\n ```\n See [TorchX](https://pytorch.org/torchx/) for more information on launching distributed and remote jobs.\n\n5. If you want to run a more complex example, please take a look at the torchrec [DLRM example](https://github.com/facebookresearch/dlrm/blob/main/torchrec_dlrm/dlrm_main.py).\n\n## Contributing\n\n### Pyre and linting\n\nBefore landing, please make sure that pyre and linting look okay. To run our linters, you will need to\n```\npip install pre-commit\n```\n\n, and run it.\n\nFor Pyre, you will need to\n```\ncat .pyre_configuration\npip install pyre-check-nightly==<VERSION FROM CONFIG>\npyre check\n```\n\nWe will also check for these issues in our GitHub actions.\n\n## License\nTorchRec is BSD licensed, as found in the [LICENSE](LICENSE) file.\n",
"bugtrack_url": null,
"license": "BSD-3",
"summary": "Pytorch domain library for recommendation systems",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/pytorch/torchrec"
},
"split_keywords": [
"pytorch",
" recommendation systems",
" sharding"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7d5fb35e6eba4a8b830f6b558a785a0e1cc3c9cf4e3ad705386949758d4fa443",
"md5": "95a175f51519d5a0a73a67f96b8917ce",
"sha256": "a89603c5eb94b20058b498b3a2c0c8612058ce9de8a1b447757a4d702b9264cb"
},
"downloads": -1,
"filename": "torchrec-0.7.0-py310-none-any.whl",
"has_sig": false,
"md5_digest": "95a175f51519d5a0a73a67f96b8917ce",
"packagetype": "bdist_wheel",
"python_version": "py310",
"requires_python": ">=3.8",
"size": 467616,
"upload_time": "2024-04-22T21:44:29",
"upload_time_iso_8601": "2024-04-22T21:44:29.216064Z",
"url": "https://files.pythonhosted.org/packages/7d/5f/b35e6eba4a8b830f6b558a785a0e1cc3c9cf4e3ad705386949758d4fa443/torchrec-0.7.0-py310-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "eab9ca91a7c23e38f855e1b2f7d6c2d2f5bdfa8aac7e81f21e410f099804cee5",
"md5": "b13fb14bea0031aef20a10f1fe425ff7",
"sha256": "636a64d8b66143b12e08da203ee90fc5a06f2227b8f6a546558aee8f98cbccde"
},
"downloads": -1,
"filename": "torchrec-0.7.0-py311-none-any.whl",
"has_sig": false,
"md5_digest": "b13fb14bea0031aef20a10f1fe425ff7",
"packagetype": "bdist_wheel",
"python_version": "py311",
"requires_python": ">=3.8",
"size": 467616,
"upload_time": "2024-04-22T21:45:08",
"upload_time_iso_8601": "2024-04-22T21:45:08.990452Z",
"url": "https://files.pythonhosted.org/packages/ea/b9/ca91a7c23e38f855e1b2f7d6c2d2f5bdfa8aac7e81f21e410f099804cee5/torchrec-0.7.0-py311-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0ae2318f0f35aa15b5da9c2ffce6ed33f13f58813b3d2fa5852d55d05942197f",
"md5": "4da16ada0c30a29724901aee8f80c788",
"sha256": "be647ceed716b813e3c5cf0135de74d7d9d75bfd0e512b5710bd7625d04689a1"
},
"downloads": -1,
"filename": "torchrec-0.7.0-py312-none-any.whl",
"has_sig": false,
"md5_digest": "4da16ada0c30a29724901aee8f80c788",
"packagetype": "bdist_wheel",
"python_version": "py312",
"requires_python": ">=3.8",
"size": 467616,
"upload_time": "2024-04-22T21:44:19",
"upload_time_iso_8601": "2024-04-22T21:44:19.499024Z",
"url": "https://files.pythonhosted.org/packages/0a/e2/318f0f35aa15b5da9c2ffce6ed33f13f58813b3d2fa5852d55d05942197f/torchrec-0.7.0-py312-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3b838c4aae0932957a259d59ea9abbd5e0cf3f54b32beec22b363364ffe91703",
"md5": "c8c88075b90a3ace2bec157e47655e34",
"sha256": "76782d62c4dc3aebdd37f3e71558234601c530ec65449eceff4924f4f9d43642"
},
"downloads": -1,
"filename": "torchrec-0.7.0-py38-none-any.whl",
"has_sig": false,
"md5_digest": "c8c88075b90a3ace2bec157e47655e34",
"packagetype": "bdist_wheel",
"python_version": "py38",
"requires_python": ">=3.8",
"size": 467614,
"upload_time": "2024-04-22T21:44:25",
"upload_time_iso_8601": "2024-04-22T21:44:25.876201Z",
"url": "https://files.pythonhosted.org/packages/3b/83/8c4aae0932957a259d59ea9abbd5e0cf3f54b32beec22b363364ffe91703/torchrec-0.7.0-py38-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1d551ed2345e8f287fe6eb6da1faa7364f165a69e737106d6bb1345297015575",
"md5": "bdffeb3379ba230e0016e6ff395ff881",
"sha256": "a4cb52bd8be959a90a161bcd1191fb181490534dfcc1d8d5fc65ddebeb9073e3"
},
"downloads": -1,
"filename": "torchrec-0.7.0-py39-none-any.whl",
"has_sig": false,
"md5_digest": "bdffeb3379ba230e0016e6ff395ff881",
"packagetype": "bdist_wheel",
"python_version": "py39",
"requires_python": ">=3.8",
"size": 467615,
"upload_time": "2024-04-22T21:44:25",
"upload_time_iso_8601": "2024-04-22T21:44:25.147840Z",
"url": "https://files.pythonhosted.org/packages/1d/55/1ed2345e8f287fe6eb6da1faa7364f165a69e737106d6bb1345297015575/torchrec-0.7.0-py39-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-22 21:44:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pytorch",
"github_project": "torchrec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "torchrec"
}
JSON
