From 021f2ea9870a1fad154d4309762320a5379f4246 Mon Sep 17 00:00:00 2001 From: lewtun Date: Wed, 12 Jan 2022 16:33:32 +0100 Subject: [PATCH] Add ONNX configuration classes to docs (#15121) * Add ONNX classes to main package * Remove permalinks from ONNX guide * Fix ToC entry * Revert "Add ONNX classes to main package" This reverts commit eb794a5b00d66b0b4eab234987301676d8357630. * Add ONNX classes to main doc * Fix syntax highlighting in doc * Fix text * Add FeaturesManager to doc * Use paths to reference ONNX classes * Add FeaturesManager to init * Add missing ONNX paths --- docs/source/_toctree.yml | 4 ++- docs/source/main_classes/onnx.mdx | 50 +++++++++++++++++++++++++++++++ docs/source/serialization.mdx | 24 +++++++-------- src/transformers/onnx/__init__.py | 2 ++ src/transformers/onnx/convert.py | 4 +-- 5 files changed, 67 insertions(+), 17 deletions(-) create mode 100644 docs/source/main_classes/onnx.mdx diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml index 3867551f12..3c3968f25d 100644 --- a/docs/source/_toctree.yml +++ b/docs/source/_toctree.yml @@ -60,7 +60,7 @@ - local: debugging title: Debugging - local: serialization - title: Exporting transformers models + title: Exporting 🤗 Transformers models - local: pr_checks title: Checks on a Pull Request title: Advanced guides @@ -86,6 +86,8 @@ title: Logging - local: main_classes/model title: Models + - local: main_classes/onnx + title: ONNX - local: main_classes/optimizer_schedules title: Optimization - local: main_classes/output diff --git a/docs/source/main_classes/onnx.mdx b/docs/source/main_classes/onnx.mdx new file mode 100644 index 0000000000..ff20f315a1 --- /dev/null +++ b/docs/source/main_classes/onnx.mdx @@ -0,0 +1,50 @@ + + +# Exporting 🤗 Transformers models to ONNX + +🤗 Transformers provides a `transformers.onnx` package that enables you to +convert model checkpoints to an ONNX graph by leveraging configuration objects. + +See the [guide](../serialization) on exporting 🤗 Transformers models for more +details. + +## ONNX Configurations + +We provide three abstract classes that you should inherit from, depending on the +type of model architecture you wish to export: + +* Encoder-based models inherit from [`~onnx.config.OnnxConfig`] +* Decoder-based models inherit from [`~onnx.config.OnnxConfigWithPast`] +* Encoder-decoder models inherit from [`~onnx.config.OnnxSeq2SeqConfigWithPast`] + +### OnnxConfig + +[[autodoc]] onnx.config.OnnxConfig + +### OnnxConfigWithPast + +[[autodoc]] onnx.config.OnnxConfigWithPast + +### OnnxSeq2SeqConfigWithPast + +[[autodoc]] onnx.config.OnnxSeq2SeqConfigWithPast + +## ONNX Features + +Each ONNX configuration is associated with a set of _features_ that enable you +to export models for different types of topologies or tasks. + +### FeaturesManager + +[[autodoc]] onnx.features.FeaturesManager + diff --git a/docs/source/serialization.mdx b/docs/source/serialization.mdx index e2b52cd652..bba638c924 100644 --- a/docs/source/serialization.mdx +++ b/docs/source/serialization.mdx @@ -109,7 +109,7 @@ which should show the following logs: ```bash Validating ONNX model... - -[✓] ONNX model outputs' name match reference model ({'last_hidden_state'}) + -[✓] ONNX model output names match reference model ({'last_hidden_state'}) - Validating ONNX Model output "last_hidden_state": -[✓] (2, 8, 768) matches (2, 8, 768) -[✓] all values close (atol: 1e-05) @@ -189,7 +189,7 @@ which will display the following logs: ```bash Validating ONNX model... - -[✓] ONNX model outputs' name match reference model ({'logits'}) + -[✓] ONNX model output names match reference model ({'logits'}) - Validating ONNX Model output "logits": -[✓] (2, 2) matches (2, 2) -[✓] all values close (atol: 1e-05) @@ -228,9 +228,9 @@ Let's start with the ONNX configuration object. We provide three abstract classes that you should inherit from, depending on the type of model architecture you wish to export: -* Encoder-based models inherit from [`OnnxConfig`](https://github.com/huggingface/transformers/blob/c4fa908fa98c3d538462c537d29b7613dd71306e/src/transformers/onnx/config.py#L52) -* Decoder-based models inherit from [`OnnxConfigWithPast`](https://github.com/huggingface/transformers/blob/c4fa908fa98c3d538462c537d29b7613dd71306e/src/transformers/onnx/config.py#L264) -* Encoder-decoder models inherit from [`OnnxSeq2SeqConfigWithPast`](https://github.com/huggingface/transformers/blob/c4fa908fa98c3d538462c537d29b7613dd71306e/src/transformers/onnx/config.py#L399) +* Encoder-based models inherit from [`~onnx.config.OnnxConfig`] +* Decoder-based models inherit from [`~onnx.config.OnnxConfigWithPast`] +* Encoder-decoder models inherit from [`~onnx.config.OnnxSeq2SeqConfigWithPast`] @@ -321,11 +321,9 @@ OrderedDict([('logits', {0: 'batch'})]) -All of the base properties and methods associated with -[`OnnxConfig`] -and the other configuration classes can be overriden if needed. Check out -[`BartOnnxConfig`] -for an advanced example. +All of the base properties and methods associated with [`~onnx.config.OnnxConfig`] and the +other configuration classes can be overriden if needed. Check out +[`BartOnnxConfig`] for an advanced example. @@ -400,10 +398,8 @@ to the library, you will need to: * Implement the ONNX configuration in the corresponding `configuration_.py` file -* Include the model architecture and corresponding features in -[`onnx.features.FeatureManager`](https://github.com/huggingface/transformers/blob/c4fa908fa98c3d538462c537d29b7613dd71306e/src/transformers/onnx/features.py#L71) -* Add your model architecture to the tests in -`test_onnx_v2.py` +* Include the model architecture and corresponding features in [`~onnx.features.FeatureManager`] +* Add your model architecture to the tests in `test_onnx_v2.py` Check out how the configuration for [IBERT was contributed](https://github.com/huggingface/transformers/pull/14868/files) to diff --git a/src/transformers/onnx/__init__.py b/src/transformers/onnx/__init__.py index 8c146cee74..95200fa842 100644 --- a/src/transformers/onnx/__init__.py +++ b/src/transformers/onnx/__init__.py @@ -27,6 +27,7 @@ _import_structure = { "PatchingSpec", ], "convert": ["export", "validate_model_outputs"], + "features": ["FeaturesManager"], "utils": ["ParameterFormat", "compute_serialized_parameters_size"], } @@ -40,6 +41,7 @@ if TYPE_CHECKING: PatchingSpec, ) from .convert import export, validate_model_outputs + from .features import FeaturesManager from .utils import ParameterFormat, compute_serialized_parameters_size else: diff --git a/src/transformers/onnx/convert.py b/src/transformers/onnx/convert.py index fed280d19e..4aa1ba3812 100644 --- a/src/transformers/onnx/convert.py +++ b/src/transformers/onnx/convert.py @@ -183,7 +183,7 @@ def validate_model_outputs( ref_outputs_set, onnx_outputs_set = set(ref_outputs_dict.keys()), set(onnx_named_outputs) if not onnx_outputs_set.issubset(ref_outputs_set): logger.info( - f"\t-[x] ONNX model outputs' name {onnx_outputs_set} doesn't match reference model {ref_outputs_set}" + f"\t-[x] ONNX model output names {onnx_outputs_set} do not match reference model {ref_outputs_set}" ) raise ValueError( @@ -191,7 +191,7 @@ def validate_model_outputs( f"{onnx_outputs_set.difference(ref_outputs_set)}" ) else: - logger.info(f"\t-[✓] ONNX model outputs' name match reference model ({onnx_outputs_set})") + logger.info(f"\t-[✓] ONNX model output names match reference model ({onnx_outputs_set})") # Check the shape and values match for name, ort_value in zip(onnx_named_outputs, onnx_outputs):