Principle:Huggingface Optimum Export Configuration Construction

Field	Value
Page Type	Principle
Source Repository	https://github.com/huggingface/optimum
Domains	NLP, Computer_Vision, Export
Last Updated	2026-02-15 00:00 GMT

Overview

Export Configuration Construction is the mechanism for constructing backend-specific export configurations that define input/output schemas, dynamic axes, and model-specific export parameters. It bridges the gap between a model's architecture and the requirements of a specific export backend.

Description

Export configuration bridges the gap between a model's architecture and the requirements of a specific export backend (ONNX, TFLite, OpenVINO). The configuration specifies:

• Input schema -- Which inputs the model expects (e.g., input_ids, attention_mask, pixel_values) and their axis definitions
• Output schema -- Which outputs the model produces (e.g., logits, last_hidden_state) and their axis definitions
• Dynamic axes -- Which tensor dimensions can vary at runtime (e.g., batch size, sequence length)
• Validation tolerances -- Acceptable numerical differences between original and exported model outputs
• Dummy input generators -- Classes responsible for generating synthetic inputs for tracing
• Past key-value handling -- Whether the model supports KV-cache variants (-with-past tasks)

Configuration constructors are looked up via a registry keyed on the tuple (exporter, model_type, task). For example, exporting a BERT model for text-classification via ONNX would look up the constructor for ("onnx", "bert", "text-classification").

Usage

Use Export Configuration Construction when preparing to export a model to a specific backend format, after task resolution. Typical workflow:

1. Resolve the task using Task and Model Resolution
2. Call TasksManager.get_exporter_config_constructor to obtain the configuration constructor
3. Invoke the constructor with the model's PretrainedConfig to produce an ExporterConfig instance
4. Pass the ExporterConfig to the export function along with the model

The configuration object is essential for all subsequent steps: dummy input generation, model tracing, and output validation.

Theoretical Basis

Export Configuration Construction is built on the Factory Pattern with registry lookup. The TasksManager maintains a mapping from (exporter, model_type, task) tuples to ExporterConfig subclass constructors.

The key data structures are:

• TasksManager._SUPPORTED_MODEL_TYPE -- A nested dictionary: model_type -> exporter -> task -> ExportConfigConstructor
• TasksManager._DIFFUSERS_SUPPORTED_MODEL_TYPE -- Same structure for diffusion model components
• TasksManager._TIMM_SUPPORTED_MODEL_TYPE -- Same structure for timm models
• TasksManager._SENTENCE_TRANSFORMERS_SUPPORTED_MODEL_TYPE -- Same structure for sentence-transformers models

The make_backend_config_constructor_for_task helper creates partially-applied constructors using functools.partial. For tasks that include -with-past, it sets use_past=True on the constructor. For regular tasks, it simply binds the task string.

This approach ensures that:

• Each model architecture can have its own specialized export configuration
• Configurations are reusable across different tasks for the same model
• New backends can be added by extending the registry without modifying existing code
• The -with-past variant logic is handled transparently

Related Pages

• Implemented by: Implementation:Huggingface_Optimum_TasksManager_Get_Exporter_Config

Connections

• Implementation:Huggingface_Optimum_TasksManager_Get_Exporter_Config