torchdistill

A coding-free framework built on PyTorch for reproducible deep learning studies. 🏆25 knowledge distillation methods presented at CVPR, ICLR, ECCV, NeurIPS, ICCV, etc are implemented so far. 🎁 Trained models, training logs and configurations are available for ensuring the reproducibiliy and benchmark.

yoshitomo-matsubara
1393
131
Python

torchdistill logo

torchdistill: A Modular, Configuration-Driven Framework for Knowledge Distillation

PyPI version
Build Status
GitHub Discussions
DOI:10.1007/978-3-030-76423-4_3
DOI:10.18653/v1/2023.nlposs-1.18

torchdistill (formerly kdkit) offers various state-of-the-art knowledge distillation methods
and enables you to design (new) experiments simply by editing a declarative yaml config file instead of Python code.
Even when you need to extract intermediate representations in teacher/student models,
you will NOT need to reimplement the models, that often change the interface of the forward, but instead
specify the module path(s) in the yaml file. Refer to these papers for more details.

In addition to knowledge distillation, this framework helps you design and perform general deep learning experiments
(WITHOUT coding) for reproducible deep learning studies. i.e., it enables you to train models without teachers
simply by excluding teacher entries from a declarative yaml config file.
You can find such examples below and in configs/sample/.

When you refer to torchdistill in your paper, please cite these papers
instead of this GitHub repository.
If you use torchdistill as part of your work, your citation is appreciated and motivates me to maintain and upgrade this framework!

Documentation

You can find the API documentation and research projects that leverage torchdistill at https://yoshitomo-matsubara.net/torchdistill/

Forward hook manager

Using ForwardHookManager, you can extract intermediate representations in model without modifying the interface of its forward function.
This example notebook Open In Colab Open In Studio Lab
will give you a better idea of the usage such as knowledge distillation and analysis of intermediate representations.

1 experiment → 1 declarative PyYAML config file

In torchdistill, many components and PyTorch modules are abstracted e.g., models, datasets, optimizers, losses,
and more! You can define them in a declarative PyYAML config file so that can be seen as a summary of your experiment,
and in many cases, you will NOT need to write Python code at all.
Take a look at some configurations available in configs/.
You’ll see what modules are abstracted and how they are defined in a declarative PyYAML config file to design an experiment.

If you want to use your own modules (models, loss functions, datasets, etc) with this framework,
you can do so without editing code in the local package torchdistill/.
See the official documentation and Discussions for more details.

Benchmarks

Top-1 validation accuracy for ILSVRC 2012 (ImageNet)

Examples

Executable code can be found in examples/ such as

For CIFAR-10 and CIFAR-100, some models are reimplemented and available as pretrained models in torchdistill.
More details can be found here.

Some Transformer models fine-tuned by torchdistill for GLUE tasks are available at Hugging Face Model Hub.
Sample GLUE benchmark results and details can be found here.

Google Colab Examples

The following examples are available in demo/.
Note that these examples are for Google Colab users and compatible with Amazon SageMaker Studio Lab.
Usually, examples/ would be a better reference
if you have your own GPU(s).

CIFAR-10 and CIFAR-100

  • Training without teacher models Open In Colab Open In Studio Lab
  • Knowledge distillation Open In Colab Open In Studio Lab

GLUE

  • Fine-tuning without teacher models Open In Colab Open In Studio Lab
  • Knowledge distillation Open In Colab Open In Studio Lab

These examples write out test prediction files for you to see the test performance at the GLUE leaderboard system.

PyTorch Hub

If you find models on PyTorch Hub or GitHub repositories supporting PyTorch Hub,
you can import them as teacher/student models simply by editing a declarative yaml config file.

e.g., If you use a pretrained ResNeSt-50 available in huggingface/pytorch-image-models
(aka timm) as a teacher model for ImageNet dataset, you can import the model via PyTorch Hub with the following entry
in your declarative yaml config file.

models:
  teacher_model:
    name: 'resnest50d'
    repo_or_dir: 'huggingface/pytorch-image-models'
    kwargs:
      num_classes: 1000
      pretrained: True

How to setup

  • Python >= 3.9
  • pipenv (optional)

Install by pip/pipenv

pip3 install torchdistill
# or use pipenv
pipenv install torchdistill

Install from this repository (not recommended)

git clone https://github.com/yoshitomo-matsubara/torchdistill.git
cd torchdistill/
pip3 install -e .
# or use pipenv
pipenv install "-e ."

Issues / Questions / Requests / Pull Requests

Feel free to create an issue if you find a bug.
If you have either a question or feature request, start a new discussion here.
Please search through Issues and Discussions and make sure your issue/question/request has not been addressed yet.

Pull requests are welcome.
Please start with an issue and discuss solutions with me rather than start with a pull request.

Citation

If you use torchdistill in your research, please cite the following papers:
[Paper] [Preprint]

@inproceedings{matsubara2021torchdistill,
  title={{torchdistill: A Modular, Configuration-Driven Framework for Knowledge Distillation}},
  author={Matsubara, Yoshitomo},
  booktitle={International Workshop on Reproducible Research in Pattern Recognition},
  pages={24--44},
  year={2021},
  organization={Springer}
}

[Paper] [OpenReview] [Preprint]

@inproceedings{matsubara2023torchdistill,
  title={{torchdistill Meets Hugging Face Libraries for Reproducible, Coding-Free Deep Learning Studies: A Case Study on NLP}},
  author={Matsubara, Yoshitomo},
  booktitle={Proceedings of the 3rd Workshop for Natural Language Processing Open Source Software (NLP-OSS 2023)},
  publisher={Empirical Methods in Natural Language Processing},
  pages={153--164},
  year={2023}
}

Acknowledgments

This project has been supported by Travis CI’s OSS credits and JetBrain’s Free License Programs (Open Source)
since November 2021 and June 2022, respectively.
PyCharm logo

References