PyTorch API Overview

This page is the curated entry point for Hyperion’s PyTorch stack. The detailed legacy/reference material remains in PyTorch Stack; use this page to locate the supported extension points and their runtime contracts.

Model contract

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.

Trainable models derive from HyperTorchModel and serialize their class configuration with parameters. Inputs, output shape, and mask conventions are model-specific; waveform x-vector wrappers accept waveform batches and expose their expected sample frequency and embedding dimension.

Data and sampling

LegacyAudioDataset reads CSV recording/segment manifests and class CSVs. Samplers determine chunk and batch duration, which is the principal memory control for waveform training. See Train an X-Vector Directly from Waveforms.

Training

The trainer owns checkpointing, logging, AMP, DDP/FSDP policy, gradient accumulation, schedulers, and validation cadence. Configure it through the trainer mapping in a command config; see Run Resumable, Mixed-Precision, and Distributed Training.

Architecture layers

The PyTorch package is intentionally layered:

• layers: primitive operations;

• layer_blocks: reusable compositions;

• narchs: neural architectures;

• models: task-level models;

• trainers and data: training execution.

New task models belong in models and should compose documented architectures/blocks rather than duplicating trainer or data-loader behavior. For the architecture, model, data, sampler, trainer, and factory contracts, see PyTorch Extension Points.

For selecting stable feature frontends, pooling, reusable blocks, and neural architecture families, see PyTorch Layers and Architecture Catalog.

Margin-based classifier heads, training metrics/loggers, and resumable scheduler behavior are documented in PyTorch Training Support.

Experimental model families

Codec/DAC, VITS anonymization, transducer, and q-vector models are experimental. TPM wrappers and adversarial modules are stable but may require external model packages. See Documentation Policy before choosing an extension or deployment target.

Third-party integrations and adversarial robustness

Hugging Face frontends, DNSMOS/UTMOS/VoxProfile evaluators, and the adversarial attack/defense interfaces are stable PyTorch surfaces with external runtime or model-asset requirements. Their contracts and reproducibility requirements are documented in PyTorch Integrations and Robustness.

See also

• PyTorch Stack

• PyTorch Extension Points

• PyTorch Layers and Architecture Catalog

• PyTorch Training Support

• PyTorch Integrations and Robustness

• Train an X-Vector Directly from Waveforms

• Train a Pretrained Wav2Vec2 X-Vector

• Save and Load Models and Backends