Backend installation and support

This page describes the source API on main. Use the source-checkout tab in the installation guide for these extras and portable workflows.

Choose a backend for the components you plan to use. Select it before importing Keras, and use separate processes when switching.

Use the tensorflow extra for Keras models and TensorFlow-specific data and training paths; use litert when you also need conversion.

import os
os.environ["KERAS_BACKEND"] = "tensorflow"
import keras

Python 3.12–3.13 is covered by the CI matrix.

Use the torch extra for the portable components below. TensorFlow is not required for those paths.

import os
os.environ["KERAS_BACKEND"] = "torch"
import keras

Python 3.12–3.14 is covered by the CI matrix. LiteRT export needs the TensorFlow backend: rebuild a Torch-trained model from its params and weights in a process started with KERAS_BACKEND=tensorflow (see Export and quantization).

Match the capability to your workflow

Capability	TensorFlow	PyTorch	Start here
TCN construction	Tested	Tested	First model
Portable metrics, EMA quantization	Tested	Tested subset	Metrics
Normalization1D, FirFilter, RandomGaussianNoise1D	Tested	Tested	Signal preprocessing
Masked-autoencoder training	Tested	Tested	Reconstruction guide
Grain record pipelines (`helia-edge[grain]`)	`to_tf_dataset`	`to_torch_loader`	Input pipelines
Generator-to-dataset helpers	`tf.data`	No Torch adapter	Input pipelines
Contrastive training	TensorFlow path	Not supported	Training guide
LiteRT conversion and FLOP counting	TensorFlow path	Not supported	Export guide

Support is component-specific. This table does not certify every architecture, precision, compiled/distributed configuration or export format. The preprocessing contracts describe additional shape, dtype and compilation boundaries.

Install your environment

Choose source or release installation and optional extras.

Explore preprocessing contracts

Check alignment, random state and transform-specific behavior.

Optional dependencies and compatibility with older installs

Base installations provide file and logging helpers without Keras. Plotting and S3 require plotting and aws respectively; S3 model URLs also need aws. Patch extraction does not need plotting, but PatchLayer2D.show_patched_image does.

Backend extras retain h5py for Keras serialization. Applications importing plotting, AWS or h5py directly should declare those dependencies themselves. litert includes TensorFlow conversion and the LiteRT runtime. metal must be combined with tensorflow; compatibility has not been validated for the recorded baseline.

Recorded environment and reproducibility limits

The recorded baseline is Linux CPU, Python 3.12.5, Keras 3.15.1, TensorFlow 2.21.0 or Torch 2.14.0+cpu, and LiteRT 2.2.0. To reproduce the CPU Torch environment, install torch==2.14.0 from https://download.pytorch.org/whl/cpu before installing the Torch extra.

The TensorFlow dependency marker excludes Python 3.14 even when its extra is selected. Use Python 3.12–3.13 for TensorFlow or LiteRT. Other platforms, GPU builds and different dependency resolutions need their own validation.

Loading saved custom objects

Lazy imports no longer register all custom Keras classes as a side effect of import helia_edge. The EDGE model loader registers supported objects explicitly:

from helia_edge.models import load_model
model = load_model('model.keras')

Use Keras directly or check serialization limits

For direct Keras loading, import the custom classes used by the model, or register supported EDGE classes before loading:

import helia_edge
helia_edge.register_keras_serializables()
import keras
model = keras.saving.load_model('model.keras')

Registration initializes the selected backend. It does not enable unsafe loading or make TensorFlow-only custom layers usable on Torch. Fresh-process round trips cover an EDGE EMA quantizer on both backends and legacy normalization on TF.

Validation

What the automated checks cover

CI includes a base-only lane and separate backend environments. Import checks assert the opposite framework is absent. TF runs its applicable suite, including float and int8 conversion; Torch runs the portable subset and custom-object reloads. Separate backend-free environments exercise AWS and plotting, followed by combined backend checks for S3 model loading and patch visualization. CPU tests set CUDA_VISIBLE_DEVICES=-1 so installed GPU drivers cannot affect the CPU export path. Preprocessing uses the public Keras augmentation hierarchy with CPU TensorFlow and Torch coverage; see the migration guide for training, dtype, shape and compilation limits.

Masked-autoencoder training

See Masked-autoencoder training for the reconstruction contract, native optimization loops and backend parity boundaries.