nvflare.app_opt.pt.recipes.fedavg_he module

class FedAvgRecipeWithHE(*, name: str = 'fedavg_he', model: Any | dict[str, Any] | None = None, initial_ckpt: str | None = None, min_clients: int, num_rounds: int = 2, train_script: str, train_args: str = '', aggregator: Aggregator | None = None, aggregator_data_kind: DataKind | None = DataKind.WEIGHTS, launch_external_process: bool = False, command: str = 'python3 -u', server_expected_format: ExchangeFormat = ExchangeFormat.NUMPY, params_transfer_type: TransferType = TransferType.FULL, encrypt_layers: List[str] | str | None = None, server_memory_gc_rounds: int = 1, client_memory_gc_rounds: int = 0, cuda_empty_cache: bool = False)[source]

Bases: Recipe

A recipe for implementing Federated Averaging (FedAvg) with Homomorphic Encryption (HE) in NVFlare.

FedAvg is a fundamental federated learning algorithm that aggregates model updates from multiple clients by computing a weighted average based on the amount of local training data. This recipe adds homomorphic encryption to preserve privacy during federated learning by allowing computations on encrypted data.

The recipe configures: - A federated job with initial model (optional) - Scatter-and-gather controller for coordinating training rounds - HE-enabled weighted aggregator for combining encrypted client model updates - HE shareable generator for converting between Shareable and Learnable objects - HE model encryptor/decryptor filters on the client side - HE model serialization filter on the server side - Script runners for client-side training execution

Important

TenSEAL context files must be generated before running this recipe: - server_context.tenseal for the server startup folder - client_context.tenseal for each client startup folder

Use NVFlare provisioning with nvflare.lighter.impl.he.HEBuilder so these context files are generated automatically into startup kits.

Example project config: examples/advanced/cifar10/pt/cifar10-real-world/workspaces/secure_project.yml

SimEnv is not supported for this HE recipe. Use ProdEnv or PocEnv with provisioned startup kits.

For provisioning details, see: https://nvflare.readthedocs.io/en/2.7/programming_guide/provisioning_system.html

Parameters:

  • name – Name of the federated learning job. Defaults to “fedavg”.

  • model – Initial model to start federated training with. Can be: - nn.Module instance - Dict config: {“class_path”: “module.ClassName”, “args”: {“param”: value}} - None: no initial model

  • initial_ckpt – Path to a pre-trained checkpoint file. Can be: - Relative path: file will be bundled into the job’s custom/ directory. - Absolute path: treated as a server-side path, used as-is at runtime. Note: PyTorch requires model when using initial_ckpt (for architecture).

  • min_clients – Minimum number of clients required to start a training round.

  • num_rounds – Number of federated training rounds to execute. Defaults to 2.

  • train_script – Path to the training script that will be executed on each client.

  • train_args – Command line arguments to pass to the training script.

  • aggregator – Aggregator for combining client updates. If None, uses HEInTimeAccumulateWeightedAggregator with aggregator_data_kind.

  • aggregator_data_kind – Data kind to use for the aggregator. Defaults to DataKind.WEIGHTS.

  • launch_external_process (bool) – Whether to launch the script in external process. Defaults to False.

  • command (str) – If launch_external_process=True, command to run script (prepended to script). Defaults to “python3”.

  • server_expected_format (str) – What format to exchange the parameters between server and client.

  • params_transfer_type (str) – How to transfer the parameters. FULL means the whole model parameters are sent.

  • TransferType.FULL. (DIFF means that only the difference is sent. Defaults to)

  • encrypt_layers – if not specified (None), all layers are being encrypted; if list of variable/layer names, only specified variables are encrypted; if string containing regular expression (e.g. “conv”), only matched variables are being encrypted.

  • server_memory_gc_rounds – Run memory cleanup (gc.collect + malloc_trim) every N rounds on server. Set to 0 to disable. Defaults to 1 (every round).

Example

```python recipe = FedAvgRecipeWithHE(

name=”my_fedavg_he_job”, model=pretrained_model, min_clients=2, num_rounds=10, train_script=”client.py”, train_args=”–epochs 5 –batch_size 32”

)

Note

This recipe implements FedAvg with homomorphic encryption (HE) using TenSEAL library. HE allows computations to be performed on encrypted data, preserving client privacy.

The following HE components are configured: - Server side: HEModelShareableGenerator, HEInTimeAccumulateWeightedAggregator, HEModelSerializeFilter - Client side: HEModelDecryptor (for incoming data), HEModelEncryptor (for outgoing results)

Model updates are aggregated using weighted averaging based on the number of training samples provided by each client, with encryption/decryption handled transparently.

If you want to use a custom aggregator, you can pass it in the aggregator parameter. The custom aggregator should support HE operations or be a subclass of HEInTimeAccumulateWeightedAggregator.

This is base class of a recipe. Recipes are implemented by jobs. A concrete recipe must provide the job for recipe implementation.

param job:

the job that implements the recipe.

process_env(env: ExecEnv)[source]

Process environment-specific configuration.

Subclasses can override to add environment-specific processing. Script validation is handled by each ExecEnv subclass in deploy().