Adding support for new architectures

NOTE: ❗This section does not apply to the decoder model’s inference with autoregressive sampling integrated through transformers-neuronx. If you want to add support for these models, please open an issue on the Optimum Neuron GitHub repo, and ping maintainers for help.

You want to export and run a new model on AWS Inferentia or Trainium? Check the guideline, and submit a pull request to 🤗 Optimum Neuron’s GitHub repo!

To support a new model architecture in the Optimum Neuron library here are some steps to follow:

1. Implement a custom Neuron configuration.
2. Export and validate the model.
3. Contribute to the GitHub repo.

Implement a custom Neuron configuration

To support the export of a new model to a Neuron compatible format, the first thing to do is to define a Neuron configuration, describing how to export the PyTorch model by specifying:

1. The input names.
2. The output names.
3. The dummy inputs used to trace the model: the Neuron Compiler records the computational graph via tracing and works on the resulting TorchScript module.
4. The compilation arguments used to control the trade-off between hardware efficiency (latency, throughput) and accuracy.

Depending on the choice of model and task, we represent the data above with configuration classes. Each configuration class is associated with a specific model architecture, and follows the naming convention ArchitectureNameNeuronConfig. For instance, the configuration that specifies the Neuron export of BERT models is BertNeuronConfig.

Since many architectures share similar properties for their Neuron configuration, 🤗 Optimum adopts a 3-level class hierarchy:

1. Abstract and generic base classes. These handle all the fundamental features, while being agnostic to the modality (text, image, audio, etc).
2. Middle-end classes. These are aware of the modality. Multiple config classes could exist for the same modality, depending on the inputs they support. They specify which input generators should be used for generating the dummy inputs, but remain model-agnostic.
3. Model-specific classes like the BertNeuronConfig mentioned above. These are the ones actually used to export models.

Example: Adding support for ESM models

Here we take the support of ESM models as an example. Let’s create an EsmNeuronConfig class in the optimum/exporters/neuron/model_configs.py.

When an Esm model interprets as a text encoder, we are able to inherit from the middle-end class TextEncoderNeuronConfig. Since the modeling and configuration of Esm is almost the same as BERT when it is interpreted as an encoder, we can use the NormalizedConfigManager with model_type=bert to normalize the configuration to generate dummy inputs for tracing the model.

And one last step, since optimum-neuron is an extension of optimum, we need to register the Neuron config that we create to the TasksManager with the register_in_tasks_manager decorator by specifying the model type and supported tasks.

@register_in_tasks_manager("esm", *["feature-extraction", "fill-mask", "text-classification", "token-classification"])
class EsmNeuronConfig(TextEncoderNeuronConfig):
    NORMALIZED_CONFIG_CLASS = NormalizedConfigManager.get_normalized_config_class("bert")
    ATOL_FOR_VALIDATION = 1e-3  # absolute tolerance to compare for comparing model on CPUs

    @property
    def inputs(self) -> List[str]:
        return ["input_ids", "attention_mask"]

Export and validate the model

With the Neuron configuration class that you implemented, now do a quick test if it works as expected:

• Export

optimum-cli export neuron --model facebook/esm2_t33_650M_UR50D --task text-classification --batch_size 1 --sequence_length 16 esm_neuron/

During the export validate_model_outputs will be called to validate the outputs of your exported Neuron model by comparing them to the results of PyTorch on the CPU. You could also validate the model manually with:

from optimum.exporters.neuron import validate_model_outputs

validate_model_outputs(
    neuron_config, base_model, neuron_model_path, neuron_named_outputs, neuron_config.ATOL_FOR_VALIDATION
)

• Inference (optional)

from transformers import AutoTokenizer
from optimum.neuron import NeuronModelForSequenceClassification

model = NeuronModelForSequenceClassification.from_pretrained("esm_neuron/")
tokenizer = AutoTokenizer.from_pretrained("esm_neuron/")
inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")
logits = model(**inputs).logits

Contribute to the GitHub repo

We are almost all set. Now submit a pull request to make your work accessible to all community members!

• Open an issue in the Optimum Neuron GitHub repo to describe the new feature and make it visible to Optimum Neuron’s maintainers.
• Add the model to the exporter test in optimum-neuron/tests/exporters/exporters_utils.py and the inference test in optimum-neuron/tests/inference/inference_utils.py.
• Open a pull request! (Don’t forget to link it to the issue you opened, so that the maintainers could better track it and provide help when needed.)

You have made a new model accessible on Neuron for the community! Thanks for joining us in the endeavor of democratizing good machine learning 🤗.