fairseq2.models.hg

This module provides an API for converting state dicts and configurations of fairseq2 models to their Hugging Face Transformer equivalents.

ABCs

class fairseq2.models.hg.HuggingFaceConverter

Bases: ABC

Converts the state dict and configuration of a fairseq2 model to its Hugging Face Transformers equivalent.

Model authors must register their converter implementations with fairseq2 as part of library initialization as shown below:

from fairseq2.models.hg import HuggingFaceConverter
from fairseq2.runtime.dependency import DependencyContainer, register_model_family

class MyModelConverter(HuggingFaceConverter):
    ...

def register_my_model(container: DependencyContainer) -> None:
    register_model_family(container, name="my_model_family", ...)

    container.register_type(
        HuggingFaceConverter, MyModelConverter, key="my_model_family",
    )

abstract to_hg_config(config: object) → HuggingFaceConfig

Converts the specified fairseq2 model configuration to its Hugging Face Transformers equivalent.

Raises:

TypeError – config is not of valid type. The expected type is one registered as part of the ModelFamily.

abstract to_hg_state_dict(state_dict: dict[str, object], config: object) → dict[str, object]

Converts the specified fairseq2 state dict to its Hugging Face Transformers equivalent.

config is the fairseq2 model configuration and can be used to adjust the converted state dict when necessary.

Raises:

TypeError – config is not of valid type. The expected type is one registered as part of the ModelFamily.

Classes

class fairseq2.models.hg.HuggingFaceConfig(data: Mapping[str, object], kls_name: str, arch: str | Sequence[str])

Bases: object

Represents the configuration of a Hugging Face Transformers model.

This class is part of the HuggingFaceConverter interface which converts fairseq2 models to their Hugging Face equivalents.

data: Mapping[str, object]

Configuration data.

Each key in this mapping must correspond to an attribute of the actual configuration class in Hugging Face Transformers.

kls_name: str

Name of the configuration class in Hugging Face Transformers. For instance, Qwen3Config or LlamaConfig.

arch: str | Sequence[str]

Architecture(s) of the model as defined in Hugging Face Transformers. For instance, Qwen3ForCausalLM, LlamaForCausalLM.

Functions

fairseq2.models.hg.get_hugging_face_converter(family_name: str) → HuggingFaceConverter

Returns the HuggingFaceConverter of the specified model family.

Raises:

NotSupportedError – The model family does not support Hugging Face conversion.

fairseq2.models.hg.save_hugging_face_model(save_dir: Path, state_dict: dict[str, object], config: HuggingFaceConfig) → None

Saves the state dict and configuration of a Hugging Face Transformers model to the specified directory.

Raises:

• TypeError – config.kls_name does not correspond to the expected PretrainedConfig subclass of the Hugging Face model.

• TypeError – state_dict contains non-tensor values which is not supported in Safetensors format.

• ValueError – A key in config does not have a corresponding attribute in Hugging Face model configuration class.

• OSError – The state dict or configuration cannot be saved to the file system.