Principle:Huggingface Optimum Task and Model Resolution

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

Task and Model Resolution is the mechanism for automatically determining the appropriate ML task and loading the correct model class from a model identifier. It is the first step in the model export pipeline and allows users to specify just a model name (e.g., a Hugging Face Hub repository ID) and have the system automatically determine the correct task, framework, and model class.

Description

In the model export pipeline, the first step is resolving what task a model was trained for (e.g., text-classification, text-generation, image-classification) and loading the correct model class. This abstraction allows users to specify just a model name and have the system automatically determine:

• The task the model was trained for (e.g., text-classification, token-classification, text-generation)
• The framework the model uses (PyTorch or TensorFlow)
• The model class to instantiate (e.g., AutoModelForSequenceClassification, AutoModelForCausalLM)

The resolution process works through multiple strategies depending on the input type:

• String model identifier -- Queries the Hugging Face Hub for model metadata, inspects the model's config.json for architecture information, and matches architecture names against a registry of known task-to-model mappings.
• Model instance -- Inspects the class hierarchy of the already-loaded model to determine which AutoModel class it corresponds to.
• Model class (type) -- Directly matches the class against known model loader registrations.

Usage

Use Task and Model Resolution when beginning any model export process where the task is not explicitly specified by the user. Typical scenarios include:

• Command-line export via optimum-cli export where the user provides only a model name
• Programmatic export where the caller wants automatic task detection
• Pipeline construction where the correct model variant must be selected automatically

If the user explicitly provides the --task argument, the resolution step is bypassed and the provided task string is used directly.

Theoretical Basis

Task and Model Resolution is built on the Registry Pattern, mapping model architectures to task categories. The TasksManager class maintains several internal registries:

• _TRANSFORMERS_TASKS_TO_MODEL_LOADERS -- Maps task strings to AutoModel class names for the Transformers library
• _DIFFUSERS_TASKS_TO_MODEL_LOADERS -- Maps task strings to pipeline class names for the Diffusers library
• _LIBRARY_TO_TASKS_TO_MODEL_LOADER_MAP -- A top-level registry keyed by library name

The resolution algorithm uses model config inspection and Hub metadata to resolve task strings to AutoModel classes. When given a model identifier string, it:

1. Fetches the model's config.json from the Hub
2. Extracts the architectures field (e.g., ["BertForSequenceClassification"])
3. Looks up the architecture name in a reverse mapping from architecture classes to tasks
4. Falls back to inspecting the pipeline_tag metadata on the Hub if config-based resolution fails

Related Pages

• Implemented by: Implementation:Huggingface_Optimum_TasksManager_Infer_Task

Connections

• Implementation:Huggingface_Optimum_TasksManager_Infer_Task