Principle:Huggingface Optimum Framework Detection

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

Framework Detection is the mechanism for automatically detecting whether a model uses PyTorch or TensorFlow based on available weight files. It ensures that the correct deep learning framework is selected before beginning the export process.

Description

Before exporting a model, the system must determine which deep learning framework the model weights are stored in. This is critical because:

• Export procedures differ between frameworks (e.g., PyTorch uses torch.onnx.export while TensorFlow uses tf2onnx)
• Model loading requires the correct framework-specific from_pretrained method
• Weight file formats are framework-specific

Framework Detection inspects the Hub repository (or local directory) for framework-specific weight files:

• PyTorch indicators -- Files matching pytorch_model*.bin or model*.safetensors patterns
• Diffusion model indicators -- Presence of model_index.json combined with .bin or .safetensors files
• Sentence Transformers indicator -- Presence of config_sentence_transformers.json (always implies PyTorch)

The detection follows a priority order:

1. User-specified framework (if provided, bypasses detection entirely)
2. Local checkpoint file inspection
3. Hub repository file listing (via API or cached snapshot)
4. Environment availability fallback (prefers PyTorch if both are available)

Usage

Use Framework Detection when the framework is not explicitly specified by the user during model export. It is called automatically by TasksManager.get_model_from_task when the framework parameter is None.

Typical scenarios:

• Automatic export where the user does not specify --framework
• Programmatic usage where the caller wants the system to select the best available framework
• Multi-framework environments where models may be stored in either format

Theoretical Basis

Framework Detection uses a file-based heuristic approach. It checks Hub file listings for framework-specific weight file patterns. The algorithm works as follows:

1. Retrieve the list of all files in the model repository (via HfApi.list_repo_tree or local directory walk)
2. Check for PyTorch weight files by matching stem and extension patterns against WEIGHTS_NAME (pytorch_model.bin) and SAFE_WEIGHTS_NAME (model.safetensors)
3. Check for diffusers-style repositories by looking for model_index.json
4. Check for Sentence Transformers by looking for config_sentence_transformers.json
5. If no framework can be determined from files, raise an error with instructions for manual specification

The heuristic is designed to be reliable for the vast majority of models on the Hugging Face Hub, where weight files follow standard naming conventions. Edge cases (custom file names, non-standard layouts) require explicit framework specification.

Related Pages

• Implemented by: Implementation:Huggingface_Optimum_TasksManager_Determine_Framework

Connections

• Implementation:Huggingface_Optimum_TasksManager_Determine_Framework