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.

Recipe parameters, including train_args, become part of the generated job definition and must never contain actual secret values. Read secrets from site environment variables or mounted files; references are supported only where documented in nvflare.recipe.secrets.

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. When a custom aggregator declares expected_data_kind, the declaration must match. 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. DIFF enables automatic difference calculation for full-model client results. A client’s FLModel.params_type remains authoritative. Defaults to TransferType.FULL.

  • 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.

Security contract – no secrets in recipe parameters:

Recipe parameters (train_args, task_args, eval_args, per_site_config, config overrides, dicts passed to add_client_config/add_server_config, exec params, etc.) can be written in clear text into generated job configuration. These parameters and their nested values must never contain actual passwords, API keys, tokens, private keys, or other credentials. Instead, read secrets from site environment variables or mounted secret files inside your code, or pass a placeholder created with nvflare.recipe.secrets.secret_ref() or nvflare.recipe.secrets.secret_file_ref() at a supported runtime boundary. See nvflare.recipe.secrets for the supported parameter locations.

Before export or run, recipes scan their parameters with heuristics and emit nvflare.recipe.secrets.PotentialSecretWarning when a value looks like an actual secret. The scan is best-effort: absence of a warning does not prove a parameter is safe to share.

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().