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

@@ -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

docs/source/main_classes/onnx.mdx

@@ -0,0 +1,50 @@
+<!--Copyright 2020 The HuggingFace Team. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.
+-->
+
+# 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
+

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)
+* Encoder-based models inherit from [`~onnx.config.OnnxConfig`]
-* Decoder-based models inherit from [`OnnxConfigWithPast`](https://github.com/huggingface/transformers/blob/c4fa908fa98c3d538462c537d29b7613dd71306e/src/transformers/onnx/config.py#L264)
+* Decoder-based models inherit from [`~onnx.config.OnnxConfigWithPast`]
-* Encoder-decoder models inherit from [`OnnxSeq2SeqConfigWithPast`](https://github.com/huggingface/transformers/blob/c4fa908fa98c3d538462c537d29b7613dd71306e/src/transformers/onnx/config.py#L399)
+* Encoder-decoder models inherit from [`~onnx.config.OnnxSeq2SeqConfigWithPast`]
 
 <Tip>
 
@@ -321,11 +321,9 @@ OrderedDict([('logits', {0: 'batch'})])
 
 <Tip>
 
-All of the base properties and methods associated with
+All of the base properties and methods associated with [`~onnx.config.OnnxConfig`] and the
-[`OnnxConfig`]
+other configuration classes can be overriden if needed. Check out
-and the other configuration classes can be overriden if needed. Check out
+[`BartOnnxConfig`] for an advanced example.
-[`BartOnnxConfig`]
-for an advanced example.
 
 </Tip>
 
@@ -400,10 +398,8 @@ to the library, you will need to:
 
 * Implement the ONNX configuration in the corresponding `configuration_<model_name>.py`
 file
-* Include the model architecture and corresponding features in
+* Include the model architecture and corresponding features in [`~onnx.features.FeatureManager`]
-[`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`
-* 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

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:

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):