fairseq2.models.hg.factory

Factory functions for creating HuggingFace models.

This module provides the core factory functionality for creating HuggingFace models within fairseq2. It handles model loading, device placement, custom model classes, and error handling.

Functions

create_hg_model(config)	Create a HuggingFace model from configuration.
register_hg_model_class(config_class_name, ...)	Register a custom model class for models not supported by Auto classes.

Classes

HgFactory(config[, gangs])

Factory for creating HuggingFace models.

Exceptions

HuggingFaceModelError(model_name, message)

Exception raised when HuggingFace model loading fails.

exception fairseq2.models.hg.factory.HuggingFaceModelError(model_name: str, message: str)

Bases: Exception

Exception raised when HuggingFace model loading fails.

fairseq2.models.hg.factory.register_hg_model_class(config_class_name: str, model_class: Type[PreTrainedModel] | str, tokenizer_class: Type[PreTrainedTokenizer] | str | None = None, processor_class: str | None = None) → None

Register a custom model class for models not supported by Auto classes.

This function allows registration of custom model classes that cannot be loaded automatically by HuggingFace’s Auto classes. This is useful for new or experimental model architectures.

Parameters:

• config_class_name – The name of the config class (e.g., ‘Qwen2_5OmniConfig’)

• model_class – The model class or its string name

• tokenizer_class – The tokenizer class or its string name (optional)

• processor_class – The processor class or its string name (optional)

Raises:

OperationalError: If transformers library is not available

Example:

Register a custom model:

register_hg_model_class(
    "Qwen2_5OmniConfig",
    "Qwen2_5OmniForConditionalGeneration",
    processor_class="Qwen2_5OmniProcessor",
)

fairseq2.models.hg.factory.create_hg_model(config: HuggingFaceModelConfig) → Any

Create a HuggingFace model from configuration.

This factory loads models directly from HuggingFace Hub with transformers.

Parameters:

config – HuggingFace model configuration

Returns:

HuggingFace PreTrainedModel

Raises:

OperationalError: If transformers library is not available

Raises:

HuggingFaceModelError: If model loading fails

Raises:

NotSupportedError: If transformers library is not available

class fairseq2.models.hg.factory.HgFactory(config: HuggingFaceModelConfig, gangs: Gangs | None = None)

Bases: object

Factory for creating HuggingFace models.

Parameters:

• config – The HuggingFace model configuration.

• gangs – The gangs to use for distributed model loading.

Initialize the factory with configuration.

create_model() → Any

Create the model according to the configuration.

Returns:

The loaded model.

Raises:

• NotSupportedError – If transformers is not available.

• HuggingFaceModelError – If model loading fails.