├── .gitignore ├── .devcontainer ├── noop.txt ├── devcontainer.json └── Dockerfile ├── environment.yml ├── LICENSE ├── notebooks ├── exporting.ipynb └── introduction.ipynb └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | *onnx 2 | -------------------------------------------------------------------------------- /.devcontainer/noop.txt: -------------------------------------------------------------------------------- 1 | This file is copied into the container along with environment.yml* from the 2 | parent folder. This is done to prevent the Dockerfile COPY instruction from 3 | failing if no environment.yml is found. -------------------------------------------------------------------------------- /environment.yml: -------------------------------------------------------------------------------- 1 | name: huggingface-onnx 2 | 3 | dependencies: 4 | - python=3.8 5 | - pytorch::pytorch 6 | - pip 7 | - transformers[onnx] 8 | - onnxruntime 9 | - pip: 10 | - ipywidgets 11 | - ipykernel 12 | -------------------------------------------------------------------------------- /.devcontainer/devcontainer.json: -------------------------------------------------------------------------------- 1 | // For format details, see https://aka.ms/devcontainer.json. For config options, see the 2 | // README at: https://github.com/devcontainers/templates/tree/main/src/miniconda 3 | { 4 | "name": "Miniconda (Python 3)", 5 | "build": { 6 | "context": "..", 7 | "dockerfile": "Dockerfile" 8 | } 9 | 10 | // Features to add to the dev container. More info: https://containers.dev/features. 11 | // "features": {}, 12 | 13 | // Use 'forwardPorts' to make a list of ports inside the container available locally. 14 | // "forwardPorts": [], 15 | 16 | // Use 'postCreateCommand' to run commands after the container is created. 17 | // "postCreateCommand": "python --version", 18 | 19 | // Configure tool-specific properties. 20 | // "customizations": {}, 21 | 22 | // Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root. 23 | // "remoteUser": "root" 24 | } 25 | -------------------------------------------------------------------------------- /.devcontainer/Dockerfile: -------------------------------------------------------------------------------- 1 | FROM mcr.microsoft.com/devcontainers/miniconda:0-3 2 | 3 | # Copy environment.yml (if found) to a temp location so we update the environment. Also 4 | # copy "noop.txt" so the COPY instruction does not fail if no environment.yml exists. 5 | COPY environment.yml* .devcontainer/noop.txt /tmp/conda-tmp/ 6 | RUN if [ -f "/tmp/conda-tmp/environment.yml" ]; then umask 0002 && /opt/conda/bin/conda env update -n base -f /tmp/conda-tmp/environment.yml; fi \ 7 | && rm -rf /tmp/conda-tmp 8 | 9 | # [Optional] Uncomment to install a different version of Python than the default 10 | # RUN conda install -y python=3.6 \ 11 | # && pip install --no-cache-dir pipx \ 12 | # && pipx reinstall-all 13 | 14 | # [Optional] Uncomment this section to install additional OS packages. 15 | # RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \ 16 | # && apt-get -y install --no-install-recommends 17 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2022 Alfredo Deza 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /notebooks/exporting.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# Exporting 🤗 Hugging Face models to ONNX\n", 8 | "You can use both Python modules used as a command-line tool or use the libraries directly. This notebook will explore how to export using the `transformers.onnx` module as a CLI and then consume that resulting model with Hugging Face and the `onnxruntime` library." 9 | ] 10 | }, 11 | { 12 | "cell_type": "markdown", 13 | "metadata": {}, 14 | "source": [ 15 | "## Find the features\n", 16 | "List the available features for a specific model. You can then use that feature when exporting to ONNX." 17 | ] 18 | }, 19 | { 20 | "cell_type": "code", 21 | "execution_count": null, 22 | "metadata": {}, 23 | "outputs": [], 24 | "source": [ 25 | "from transformers.onnx.features import FeaturesManager\n", 26 | "\n", 27 | "distilbert_features = list(FeaturesManager.get_supported_features_for_model_type(\"distilbert\").keys())\n", 28 | "print(distilbert_features)" 29 | ] 30 | }, 31 | { 32 | "cell_type": "code", 33 | "execution_count": null, 34 | "metadata": {}, 35 | "outputs": [], 36 | "source": [ 37 | "!python -m transformers.onnx --model=distilbert-base-uncased-finetuned-sst-2-english \\\n", 38 | " --feature=question-answering ." 39 | ] 40 | }, 41 | { 42 | "cell_type": "markdown", 43 | "metadata": {}, 44 | "source": [ 45 | "## Explore and further reading\n", 46 | "Go through the ONNX models and how they can work with the `onnxruntime` in the [ONNX Zoo](https://github.com/onnx/models)" 47 | ] 48 | } 49 | ], 50 | "metadata": { 51 | "kernelspec": { 52 | "display_name": "Python 3.8.13 ('base')", 53 | "language": "python", 54 | "name": "python3" 55 | }, 56 | "language_info": { 57 | "codemirror_mode": { 58 | "name": "ipython", 59 | "version": 3 60 | }, 61 | "file_extension": ".py", 62 | "mimetype": "text/x-python", 63 | "name": "python", 64 | "nbconvert_exporter": "python", 65 | "pygments_lexer": "ipython3", 66 | "version": "3.8.13" 67 | }, 68 | "orig_nbformat": 4, 69 | "vscode": { 70 | "interpreter": { 71 | "hash": "d4d1e4263499bec80672ea0156c357c1ee493ec2b1c70f0acce89fc37c4a6abe" 72 | } 73 | } 74 | }, 75 | "nbformat": 4, 76 | "nbformat_minor": 2 77 | } 78 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Using 🤗 Hugging Face with ONNX 2 | 3 | This repository contains example notebooks to work with ONNX using 🤗 Hugging Face libraries and tools. It is part of the [Duke University MLOps Coursera Specialization](https://www.coursera.org/specializations/mlops-machine-learning-duke) 4 | 5 | ## Exercise 6 | 7 | This repository is ready to use with GitHub Codespaces. All dependencies will be installed and the notebooks will be ready to use. If you are running this locally and without Codespaces, you'll need to follow these steps: 8 | 9 | 1. Create a new Conda environment and install the dependencies listed in `environment.yml` 10 | 1. Open the Jupyter Notebooks and select the Python from the Conda environment created 11 | 12 | With the environment in place, go through the notebooks and use the examples that already work and then try these challenges: 13 | 14 | 1. Use a different model to port over to Hugging Face 15 | 1. Try a specific feature for a different model 16 | 1. Load the resulting ONNX model with the ONNX Runtime and try using it 17 | 18 | ## Objectives 19 | 20 | This introductory repository will expose you to learn how does ONNX and Hugging Face works together. It shows what and how you install the necessary libraries to create ONNX models. 21 | 22 | 23 | ## Learning Resources 24 | 25 | There are a few sources that are useful to dive deeper into working with ONNX and Hugging Face. Here are a few you can explore: 26 | 27 | - [The ONNX Model Zoo](https://github.com/onnx/models) 28 | - [Exporting to ONNX - Hugging Face documentation](https://huggingface.co/docs/transformers/serialization) 29 | - [Main ONNX landing page ](https://onnx.ai/) 30 | - [ONNX documentation](https://learn.microsoft.com/azure/machine-learning/concept-onnx?WT.mc_id=academic-0000-alfredodeza) 31 | 32 | **Related Coursera courses** 33 | - [Linux and Bash for Data Engineering](https://www.coursera.org/learn/linux-and-bash-for-data-engineering-duke) 34 | - [Open Source Platforms for MLOps](https://www.coursera.org/learn/open-source-platforms-duke) 35 | - [Python Essentials for MLOps](https://www.coursera.org/learn/python-essentials-mlops-duke) 36 | - [Web Applications and Command-Line tools for Data Engineering](https://www.coursera.org/learn/web-app-command-line-tools-for-data-engineering-duke) 37 | - [Python and Pandas for Data Engineering](https://www.coursera.org/learn/python-and-pandas-for-data-engineering-duke) 38 | - [Scripting with Python and SQL for Data Engineering](https://www.coursera.org/learn/scripting-with-python-sql-for-data-engineering-duke) 39 | 40 | -------------------------------------------------------------------------------- /notebooks/introduction.ipynb: -------------------------------------------------------------------------------- 1 | { 2 | "cells": [ 3 | { 4 | "cell_type": "markdown", 5 | "metadata": {}, 6 | "source": [ 7 | "# 🤗 Hugging Face and ONNX introduction\n", 8 | "ONNX Runtime is a performance-focused inference engine for ONNX models. It is cross-platform and open source. It supports execution of models on a wide range of devices, from CPUs to GPUs.\n", 9 | "\n", 10 | "ONNX allows for interoperability between different frameworks and tools, it is open source and therefore can be easily extended, and it is efficient and scalable.\n", 11 | "\n", 12 | "This notebook will explore the ONNX runtime and how to use it with Hugging Face Transformers." 13 | ] 14 | }, 15 | { 16 | "cell_type": "markdown", 17 | "metadata": {}, 18 | "source": [ 19 | "## Installation \n", 20 | "Make sure you are using the right libraries. It might be easier to use conda to install the dependencies and runtime settings. For example:\n", 21 | "\n", 22 | "```yaml\n", 23 | "name: huggingface-onnx\n", 24 | "\n", 25 | "dependencies:\n", 26 | " - python=3.8\n", 27 | " - pytorch::pytorch\n", 28 | " - pip\n", 29 | " - transformers[onnx]\n", 30 | " - pip:\n", 31 | " - ipywidgets\n", 32 | "```" 33 | ] 34 | }, 35 | { 36 | "cell_type": "markdown", 37 | "metadata": {}, 38 | "source": [ 39 | "## Supported with ready-made configurations\n", 40 | "There are a few models that are supported right away with configurations, which means that it will be easy to port an existing Hugging Face model over to ONNX.\n", 41 | "\n", 42 | "Some of the popular models are:\n", 43 | "\n", 44 | "- BART\n", 45 | "- BERT\n", 46 | "- Data2VecText\n", 47 | "- Data2VecVision\n", 48 | "- DistilBERT\n", 49 | "- OpenAI GPT-2\n", 50 | "- RoBERTa\n", 51 | "- T5\n", 52 | "- Whisper\n", 53 | "- YOLOS" 54 | ] 55 | }, 56 | { 57 | "cell_type": "code", 58 | "execution_count": null, 59 | "metadata": {}, 60 | "outputs": [], 61 | "source": [ 62 | "!python -m transformers.onnx --help" 63 | ] 64 | }, 65 | { 66 | "cell_type": "markdown", 67 | "metadata": {}, 68 | "source": [ 69 | "## Configs\n", 70 | "Configurations are important because they allow you correctly interact and map with the resulting model. Hugging Face already includes ready-to-use configurations for the popular models, so no need to figure out how that mapping should go." 71 | ] 72 | }, 73 | { 74 | "cell_type": "code", 75 | "execution_count": null, 76 | "metadata": {}, 77 | "outputs": [], 78 | "source": [ 79 | "from transformers.models.roberta import RobertaConfig, RobertaOnnxConfig\n", 80 | "config = RobertaConfig()\n", 81 | "onnx_config = RobertaOnnxConfig(config)\n", 82 | "print(list(onnx_config.inputs.keys()))" 83 | ] 84 | }, 85 | { 86 | "cell_type": "markdown", 87 | "metadata": {}, 88 | "source": [ 89 | "## Suggested reading\n", 90 | "Learn more about some other options and other supported serialization to ONNX in the [Hugging Face Transformers Serialization](https://huggingface.co/docs/transformers/serialization) documentation." 91 | ] 92 | } 93 | ], 94 | "metadata": { 95 | "kernelspec": { 96 | "display_name": "Python 3.8.13 ('base')", 97 | "language": "python", 98 | "name": "python3" 99 | }, 100 | "language_info": { 101 | "codemirror_mode": { 102 | "name": "ipython", 103 | "version": 3 104 | }, 105 | "file_extension": ".py", 106 | "mimetype": "text/x-python", 107 | "name": "python", 108 | "nbconvert_exporter": "python", 109 | "pygments_lexer": "ipython3", 110 | "version": "3.8.13" 111 | }, 112 | "orig_nbformat": 4, 113 | "vscode": { 114 | "interpreter": { 115 | "hash": "d4d1e4263499bec80672ea0156c357c1ee493ec2b1c70f0acce89fc37c4a6abe" 116 | } 117 | } 118 | }, 119 | "nbformat": 4, 120 | "nbformat_minor": 2 121 | } 122 | --------------------------------------------------------------------------------