fairseq2.models.hub

The model hub provides a unified interface for working with model families in fairseq2. Each model family has its own hub that exposes methods for loading models, creating new instances, listing architectures, and more.

Quick Start

from fairseq2.models.qwen import get_qwen_model_hub

# Get the model hub for Qwen family
hub = get_qwen_model_hub()

# List available architectures
archs = hub.get_archs()
print(f"Available architectures: {archs}")

# Create a new uninitialized model
config = hub.get_arch_config("qwen25_7b")
model = hub.create_new_model(config)

# Load a model from asset card
model = hub.load_model("qwen25_7b")

# Load a model from custom checkpoint
from pathlib import Path
model = hub.load_custom_model(Path("/path/to/checkpoint.pt"), config)

Core Classes

ModelHub

final class fairseq2.models.hub.ModelHub(family, asset_store)[source]

Bases: Generic[ModelT, ModelConfigT]

The main hub class that provides access to all model operations for a specific family.

Key Methods:

  • get_archs() - List available architectures

  • get_arch_config() - Get architecture configuration

  • create_new_model() - Create newly initialized model

  • load_model() - Load model from asset card

  • load_custom_model() - Load model from custom checkpoint

  • iter_cards() - Iterate over available model cards

ModelHubAccessor

final class fairseq2.models.hub.ModelHubAccessor(family_name, kls, config_kls)[source]

Bases: Generic[ModelT, ModelConfigT]

Provides access to model hubs for specific families. Used internally by family-specific hub accessor functions like fairseq2.models.qwen.hub.get_qwen_model_hub().

Global Functions

load_model

fairseq2.models.hub.load_model(card, *, gangs=None, device=None, dtype=None, config=None, mmap=False, progress=True)[source]

The main function for loading models across all families. Automatically determines the appropriate model family from the asset card.

from fairseq2.models.hub import load_model

# Load any model by name
model = load_model("qwen25_7b")
model = load_model("llama3_8b")
model = load_model("mistral_7b")
Return type:

Module

Working with Model Families

Each model family provides its own hub accessor function:

Qwen Models

from fairseq2.models.qwen import get_qwen_model_hub

hub = get_qwen_model_hub()

# Available architectures
archs = hub.get_archs()  # {'qwen25_0.5b', 'qwen25_1.5b', 'qwen25_3b', ...}

# Get configuration for specific architecture
config = hub.get_arch_config("qwen25_7b")

# Create new model
model = hub.create_new_model(config)

LLaMA Models

from fairseq2.models.llama import get_llama_model_hub

hub = get_llama_model_hub()

# List available LLaMA architectures
archs = hub.get_archs()

# Load specific LLaMA model
model = hub.load_model("llama3_8b")

Mistral Models

from fairseq2.models.mistral import get_mistral_model_hub

hub = get_mistral_model_hub()
model = hub.load_model("mistral_7b")

Advanced Usage

Custom Model Loading

Load models from custom checkpoints with specific configurations:

from pathlib import Path
from fairseq2.models.qwen import get_qwen_model_hub

hub = get_qwen_model_hub()

# Get base configuration
config = hub.get_arch_config("qwen25_7b")

# Modify configuration if needed
config.max_seq_len = 32768

# Load from custom checkpoint
checkpoint_path = Path("/path/to/my/checkpoint.pt")
model = hub.load_custom_model(checkpoint_path, config)

Iterating Over Model Cards

Discover all available models in a family:

from fairseq2.models.qwen import get_qwen_model_hub

hub = get_qwen_model_hub()

# List all Qwen model cards
for card in hub.iter_cards():
    print(f"Model: {card.name}")
    print(f"  Architecture: {card.field('model_arch').as_(str)}")
    print(f"  Checkpoint: {card.field('checkpoint').as_(str)}")

Checkpoint Inspection

Iterate over checkpoint tensors without loading the full model:

from pathlib import Path
from fairseq2.models.qwen import get_qwen_model_hub

hub = get_qwen_model_hub()
config = hub.get_arch_config("qwen25_7b")

checkpoint_path = Path("/path/to/checkpoint.pt")

# Inspect checkpoint contents
for name, tensor in hub.iter_checkpoint(checkpoint_path, config):
    print(f"Parameter: {name}, Shape: {tensor.shape}")

Error Handling

Common Exceptions

exception fairseq2.models.hub.ModelNotKnownError(name)[source]

Bases: Exception

Raised when a requested model name is not found in the asset store.

exception fairseq2.models.hub.ModelFamilyNotKnownError(name)[source]

Bases: Exception

Raised when a model family is not registered or available.

exception fairseq2.models.hub.ModelArchitectureNotKnownError(arch)[source]

Bases: Exception

Raised when a requested architecture is not available in the model family.

Example Error Handling

from fairseq2.models.hub import load_model, ModelNotKnownError, ModelArchitectureNotKnownError
from fairseq2.models.qwen import get_qwen_model_hub

try:
    model = load_model("nonexistent_model")
except ModelNotKnownError as e:
    print(f"Model not found: {e.name}")

try:
    hub = get_qwen_model_hub()
    config = hub.get_arch_config("invalid_arch")
except ModelArchitectureNotKnownError as e:
    print(f"Architecture not found: {e.arch}")
    print(f"Available architectures: {hub.get_archs()}")

See Also