PyTorch Stack

Overview

The hyperion.torch package contains:

• low-level layers and layer blocks

• neural architectures (narchs)

• top-level models

• data pipelines, samplers, trainers, schedulers

• third-party model wrappers in hyperion.torch.tpm

Core model abstractions

All torch models derive from:

class hyperion.torch.HyperTorchModel(*args: Any, **kwargs: Any)

Base class for PyTorch models and neural network architectures.

registry: Dict[str, Type[HyperTorchModel]] = {'TorchModel': <class 'hyperion.torch.hyper_torch_model.TorchModel'>}

classmethod __init_subclass__(**kwargs: Any) → None

Register subclasses by class name for dynamic loading.

Parameters:

**kwargs – Additional subclass initialization options.

__init__(bias_weight_decay: float | None = None)

Initialize model-level training controls.

Parameters:

bias_weight_decay – Optional decay value for bias/1D parameter group.

get_config(no_class_name: bool = False) → Dict[str, Any]

Return a serializable configuration dictionary.

Parameters:

no_class_name – If True, omit class_name from the config.

Returns:

Configuration dictionary used to reconstruct the model.

copy() → HyperTorchModel

Return a deep copy of this model.

Returns:

A deep-copied model instance.

clone() → HyperTorchModel

Return a deep copy of this model (alias of copy).

Returns:

A deep-copied model instance.

trainable_parameters(recurse: bool = True) → Iterator[torch.nn.Parameter]

Yield parameters with requires_grad=True.

Parameters:

recurse – Whether to recurse into submodules.

Returns:

Iterator of trainable parameters.

non_trainable_parameters(recurse: bool = True) → Iterator[torch.nn.Parameter]

Yield parameters with requires_grad=False.

Parameters:

recurse – Whether to recurse into submodules.

Returns:

Iterator of non-trainable parameters.

trainable_named_parameters(recurse: bool = True) → Iterator[Tuple[str, torch.nn.Parameter]]

Yield (name, parameter) pairs for trainable parameters.

Parameters:

recurse – Whether to recurse into submodules.

Returns:

Iterator of named trainable parameters.

non_trainable_named_parameters(recurse: bool = True) → Iterator[Tuple[str, torch.nn.Parameter]]

Yield (name, parameter) pairs for non-trainable parameters.

Parameters:

recurse – Whether to recurse into submodules.

Returns:

Iterator of named non-trainable parameters.

parameter_summary(verbose: bool = False) → Tuple[int, int, int, int, int]

Return parameter and buffer counts.

Parameters:

verbose – If True, log a summary line.

Returns:

Tuple (total, trainable, non_trainable_plus_buffers, non_trainable, buffers).

print_parameter_list() → None

Log names of trainable, non-trainable, and buffer tensors.

has_param_groups() → bool

Return whether model exposes custom optimizer parameter groups.

Returns:

True if bias_weight_decay is enabled.

trainable_param_groups() → List[Dict[str, Any]]

Build optimizer parameter groups for trainable parameters.

Returns:

Optimizer parameter-group dictionaries.

freeze() → None

Disable gradients for all parameters.

unfreeze() → None

Enable gradients for all parameters.

has_batchnorms() → bool

Return True if the model contains any batch-normalization layer.

Returns:

True when any batchnorm module is found.

change_dropouts(dropout_rate: float) → None

Set dropout probability on dropout and RNN modules.

Parameters:

dropout_rate – New dropout rate.

property train_mode: str

full or frozen.

Returns:

Active train mode string.

Type:

Current train mode

set_train_mode(mode: str) → None

Switch model between full-train and frozen-parameter modes.

Parameters:

mode – Target mode (full or frozen).

_train(train_mode: str) → None

Apply PyTorch train/eval state for a custom train mode.

Parameters:

train_mode – Mode to apply (full or frozen).

train(mode: bool = True) → HyperTorchModel

Override nn.Module.train to honor self.train_mode.

Parameters:

mode – If False, force eval mode.

Returns:

self.

static valid_train_modes() → List[str]

Return the list of supported train modes.

Returns:

Supported train-mode names.

save(file_path: str | Path) → None

Save model config and state dictionary to disk.

Parameters:

file_path – Destination checkpoint path.

static _load_cfg_state_dict(file_path: str | Path | None = None, cfg: Dict[str, Any] | None = None, state_dict: Dict[str, torch.Tensor] | None = None) → Tuple[Dict[str, Any], Dict[str, torch.Tensor] | None]

Resolve config/state_dict from args or a checkpoint file.

Parameters:

• file_path – Optional checkpoint path.

• cfg – Optional pre-loaded model config.

• state_dict – Optional pre-loaded state dict.

Returns:

Tuple (cfg, state_dict) with class_name removed from config.

classmethod load(file_path: str | Path | None = None, cfg: Dict[str, Any] | None = None, state_dict: Dict[str, torch.Tensor] | None = None) → HyperTorchModel

Instantiate model from config and optionally load weights.

Parameters:

• file_path – Optional checkpoint path.

• cfg – Optional model config.

• state_dict – Optional model weights.

Returns:

Instantiated model.

get_reg_loss() → int

Return regularization loss contribution for this model.

Returns:

Regularization loss term.

get_loss() → int

Return auxiliary loss contribution for this model.

Returns:

Auxiliary loss term.

property device: torch.device

Return unique device shared by parameters and buffers.

Returns:

Device where all parameters and buffers reside.

static _remove_module_prefix(state_dict: Dict[str, torch.Tensor]) → Dict[str, torch.Tensor]

Remove leading module. prefixes from state-dict keys.

Parameters:

state_dict – State dict to normalize.

Returns:

Normalized state dict.

static _fix_xvector_cfg(cfg: Dict[str, Any]) → Dict[str, Any]

Normalize legacy XVector config keys to current names.

Parameters:

cfg – Model config dictionary.

Returns:

Updated config dictionary.

static _fix_hf_wav2xvector(cfg: Dict[str, Any], state_dict: Dict[str, torch.Tensor]) → Tuple[Dict[str, Any], Dict[str, torch.Tensor]]

Migrate legacy HF wav2xvector fusion config and checkpoint layout.

Parameters:

• cfg – Model config dictionary.

• state_dict – Model checkpoint weights.

Returns:

Updated (cfg, state_dict).

static _fix_resnet_qvector_cfg(cfg: Dict[str, Any]) → Dict[str, Any]

Drop deprecated ResNetQVector config keys.

Parameters:

cfg – Model config dictionary.

Returns:

Updated config dictionary.

static _fix_model_compatibility(class_obj: Type[HyperTorchModel], cfg: Dict[str, Any], state_dict: Dict[str, torch.Tensor]) → Tuple[Dict[str, Any], Dict[str, torch.Tensor]]

Apply compatibility fixes for deprecated model formats.

Parameters:

• class_obj – Model class to instantiate.

• cfg – Configuration dictionary.

• state_dict – Serialized model weights.

Returns:

Updated (cfg, state_dict).

static _is_hf_path(file_path: Path) → bool

Return True for HF-style org/repo/file paths.

Parameters:

file_path – Path to validate.

Returns:

True if path shape matches expected HF format.

static _get_from_hf(file_path: Path, cache_dir: str | Path = None, local_dir: str | Path = None) → str

Download a file from Hugging Face Hub and return its local path.

Parameters:

• file_path – HF-style path org/repo/file.

• cache_dir – Optional HF cache directory.

• local_dir – Optional local download directory.

Returns:

Local filesystem path to downloaded file.

static _try_to_get_from_hf(file_path: Path, cache_dir: str | Path = None, local_dir: str | Path = None) → Path

Resolve local file path, downloading from HF Hub when needed.

Parameters:

• file_path – Local path or prefixed HF path.

• cache_dir – Optional HF cache directory.

• local_dir – Optional local download directory.

Returns:

Resolved local path.

static _bootstrap_registry() → None

Import common torch subpackages so subclasses register themselves.

HyperTorchModel.registry is populated when subclass definitions are imported. CLI scripts often import only HyperTorchModel and call auto_load, so we need a lazy import step before class lookup.

static _find_module_for_class_name(class_name: str) → str | None

Find module path for class name by scanning torch source files.

Parameters:

class_name – Target class name.

Returns:

Dotted module path if found, otherwise None.

static auto_load(file_path: str | Path, model_name: str | None = None, extra_objs: Dict[str, Type[HyperTorchModel]] | None = None, map_location: Callable[[torch.Tensor, str], torch.Tensor] | torch.device | str | Dict[str, str] | None = None, cache_dir: str | Path = None, local_dir: str | Path = None) → HyperTorchModel

Load model from checkpoint with dynamic class resolution.

Parameters:

• file_path – Local path or HF-style path.

• model_name – State-dict prefix; defaults to model.

• extra_objs – Optional mapping from class names to model classes.

• map_location – torch.load map location.

• cache_dir – Optional HF cache directory.

• local_dir – Optional local download directory.

Returns:

Loaded model instance.

Generic torch model loader:

Neural architecture base class:

Architecture loader:

Layering model

The stack follows this composition flow:

1. hyperion.torch.layers (primitive operations)

2. hyperion.torch.layer_blocks (composite blocks)

3. hyperion.torch.narchs (architectures)

4. hyperion.torch.models (task models)

Layer and block namespaces

layers contains primitive operations such as feature frontends, pooling, normalization, margin heads, and vector quantization. layer_blocks composes those primitives into reusable encoder/decoder and residual building blocks. Their public forward contracts must state tensor layout, valid-length/mask handling, output layout, and train/eval behavior; implementation-private blocks are intentionally not listed as a supported API.

See PyTorch Layers and Architecture Catalog for supported factories and component families, and PyTorch API Contracts for the required forward-contract and device semantics.

Neural architectures

hyperion.torch.narchs includes architecture families used by models, such as ResNet/Res2Net variants, conformer/transformer encoders, ConvNeXt encoders, DAC encoder/decoder, QFormer/Hydra heads, and auxiliary heads.

Use the architecture factories for supported ResNet, TDNN, SpineNet, and related families. NetArch implementations are reusable neural architectures, not end-user task models: their input/output tensor and mask contracts must be preserved by the enclosing model.

See PyTorch Layers and Architecture Catalog and PyTorch API Contracts.

Top-level models

hyperion.torch.models contains end-to-end models used by scripts and trainers, including x-vector, wav2xvector, qvector, DAC, FreeVC, transducer, and VAE-related models.

Stable x-vector and waveform x-vector models are documented through PyTorch API Overview and PyTorch API Contracts. Codec/DAC, VITS/freevc, transducer, and Q-vector model families are experimental and are covered only in Experimental Components.

Data pipeline and samplers

The stable public entry points are AudioDataset, LegacyAudioDataset, HyperSampler, SegSampler, and their factories. Dataset outputs, padded batch layout, length fields, deterministic sampler state, and distributed resume behavior are documented in PyTorch API Contracts.

Detailed sampler documentation:

• Segment Datasets
  • Dataset selection
  • Dataset APIs
• Sequential Samplers
  • Sampler selection
  • Common behavior
  • Core sampler APIs
• Embedding Samplers
  • Sampler selection
  • Available sampler types
  • Basic configuration
  • Embedding sampler APIs

Learning rate and weight decay schedulers

Use LRSchedulerFactory and WDSchedulerFactory through trainer configuration rather than importing scheduler implementations directly. Their state dictionaries belong to a resumable trainer checkpoint and must be loaded with a compatible optimizer/trainer configuration. See PyTorch Training Support.

Training stack

Canonical trainer base classes:

Experimental trainer families (Q-vector, DAC, FreeVC, and VITS anonymization) are intentionally not expanded here as a stable reference. Their current scope and compatibility caveats are recorded in Experimental Components.

Legacy trainer note

LegacyTorchTrainer remains available and is still used for x-vector training flows.

For now, other legacy trainers (for example transducer/VAE/DVAE legacy paths) are intentionally not documented here.

Torch metrics

Torch metric utilities support training-loop aggregation and are distinct from trial-based speaker-verification metrics. Use the latter for EER/DCF reporting; see Metrics and Evaluation API. Training metric/logger and scheduler hook behavior is documented in PyTorch Training Support.

Third-party model wrappers (TPM)

hyperion.torch.tpm is a first-class subsystem for wrappers around external models and toolkits.

Wrapper families:

• hyperion.torch.tpm.hf: Hugging Face wrappers HFWav2Vec2, HFHubert, HFWavLM, WhisperTranscriber.

• hyperion.torch.tpm.dnsmos: DNSMOS speech quality wrapper.

• hyperion.torch.tpm.utmos: UTMOSV2 wrapper.

• hyperion.torch.tpm.usc: VoxProfile evaluators.

Model/checkpoint behavior

These wrappers are designed to download pretrained models/checkpoints automatically when needed.

VoxProfile dependency

VoxProfile wrappers require installing Hyperion with the voxprofile extra:

pip install -e .[voxprofile]

Combined example:

pip install -e .[torch29,voxprofile]