Ir para o conteúdo

Component: Training Job (TrainingLocalModel)

Responsibility

Implementation of the local training algorithm executed by FederatedClientService inside the client's Docker container. It is the only piece of code the researcher needs to implement to integrate a new experiment into the framework.

Implementation

Interface br.ufma.lsdi.experiment.sdk.TrainingLocalModel
HAR experiment br.ufma.lsdi.research.har.HarTrainingLocalModel
ECG experiment br.ufma.lsdi.research.ecg.Ecg5000TrainingLocalModel

TrainingLocalModel interface

public interface TrainingLocalModel {

    /** Declares the algorithm and its supported targets. Validated before data access. */
    default MlAlgorithmSpec algorithmSpec() {
        return MlAlgorithmCatalog.CUSTOM_JAVA_TRAINING_JOB;
    }

    /**
     * Executes local training.
     *
     * @param context  round metadata, authorized data view, hyperparameters
     * @return result with the update, metrics, profile, and convergence history
     */
    TrainingResult execute(TrainingContext context) throws TrainingException;
}

Mandatory contract for execute()

  1. Read data exclusively from context.authorizedDataView() — never open dataset.csv directly.
  2. Write output files exclusively to context.outputPath().
  3. Return a TrainingResult with the correct hash and norm.
  4. Never connect to the network or external services.
  5. Never return an empty vector or one containing NaN/Inf.

Implemented algorithms

1. ExampleTrainingLocalModel — DT (Industrial Digital Twins)

Numerical summary of industrial equipment sensors (temperature, vibration, pressure). Synthetic algorithm for validating the framework.

Algorithm: weighted average of features → vector of 3 doubles
Dataset:   temperature, vibration, and pressure observations per equipment unit
Target:    failure_next_24h (binary classification)
Update:    vector of 3 doubles (normalized averages)
Metric:    simulated_f1_score (synthetic — not evaluated externally)

2. HarTrainingLocalModel — HAR (Human Activity Recognition)

MLP trained with backpropagation for human activity classification using the 561 features of the UCI HAR Dataset.

Architecture: MLP 561 → 256 → 128 → 6
Optimizer:    Adam (β₁=0.9, β₂=0.999, ε=1e-8)
Regularization: FedProx (μ=0.01), L2 weight decay, Dropout, Gradient Clipping
Early stopping: patience=3 rounds without improvement (Δ < 0.001)
Dataset:      UCI HAR training split by subject (350–700 windows/subject)
Targets:      WALKING, WALKING_UPSTAIRS, WALKING_DOWNSTAIRS, SITTING, STANDING, LAYING
Update:       full MLP weight vector (≈ 185,474 doubles)
Metric:       train_accuracy per epoch + perClassAccuracy

Hyperparameters via RoundConfig.hyperparameters():

Parameter Default value Description
epochs 10 Training epochs per round
learning_rate 0.001 Adam learning rate
mu 0.01 FedProx strength (0 = pure FedAvg)
dropout_rate 0.3 Dropout on the hidden layer
l2_lambda 1e-4 L2 weight decay
gradient_clip_norm 1.0 Maximum gradient norm
early_stopping_patience 3 Epochs without improvement before stopping

3. Ecg5000TrainingLocalModel — ECG5000 (Anomaly Detection)

MLP Autoencoder for anomaly detection in cardiac signals. Applies mandatory Differential Privacy (sensitive health data, LGPD Art. 5, II).

Architecture: Autoencoder 140→64→32→16→32→64→140 (23,388 parameters)
Optimizer:    Adam + FedProx (μ=0.01) + L2 weight decay (λ=1e-4)
Training:     normal samples only (ecgClass == 1)
Anomaly:      reconstruction MSE > adaptive threshold (mean + 2.5·std)
Dataset:      ECG5000 TRAIN split partitioned across 5 clients (~100 samples/client)
Metric:       reconstruction_loss (average MSE over normal samples)

Differential Privacy (DP-SGD — Abadi et al., CCS 2016):

Step 1 — L2 clip:        w ← w × min(1, C / ‖w‖₂)
Step 2 — Gaussian noise: w ← w + N(0, σ²·C²·I)
DP parameter (research.xml <orchestration><privacy>) Federated value Note
clippingNorm (C) 1.0 L2 clipping bound
noiseMultiplier (σ) 0.5 Calibrated in research.xml (BL-301); note legacy apps (DockerEcgClientApp / Ecg5000MultiRoundExperimentApp) still use 1.1

Since BL-081, Differential Privacy is not applied inside Ecg5000TrainingLocalModel: FederatedClientService applies DataComponent.applyDifferentialPrivacyIfConfigured(...) (DifferentialPrivacyMath.clipAndNoise) centrally after validating the raw update hash and before uploading local_update.bin.


TrainingContext — training inputs

public record TrainingContext(
    String               experimentId,
    String               contractVersion,
    long                 roundId,
    Path                 authorizedDataView,    // CSV generated by AuthorizedTrainingViewWriter
    Path                 outputPath,            // where to write outputs
    Path                 globalModelPath,       // previous model weights (FedProx)
    Map<String,String>   hyperparameters,       // epochs, lr, mu, dropout, ...
    PrivacyPolicy        privacyPolicy,         // dp_enabled, clip_norm, noise_multiplier
    StudyDesign          studyDesign,
    AggregationPolicy    aggregationPolicy,
    TimeWindow            dataWindow
)

TrainingResult — training outputs

public record TrainingResult(
    Path               localUpdatePath,    // "local_update.bin"
    Path               metricsPath,        // "metrics.json"
    Path               dataProfilePath,    // "data_profile.json"
    String             updateHash,         // sha256 of local_update.bin
    double             updateNorm,         // L2 norm of the vector
    TrainingStatus     status,             // SUCCESS | FAILED | PREFLIGHT_FAILED | COMPLETED_NOT_SUBMITTED | UPDATE_SUBMITTED
    int                sampleCount,
    int                positiveCount,
    double             localMetric,        // e.g., train_accuracy = 0.8312
    String             localMetricName,    // "train_accuracy", "reconstruction_loss"
    List<EpochPoint>   trainingHistory,    // per-epoch convergence
    Map<String,Double> perClassAccuracy    // HAR: {"WALKING": 0.92, "SITTING": 0.87}
)

EpochPoint:

public record EpochPoint(int epoch, double loss, double accuracy, double gradientNorm) {}


Output files (written to outputPath)

File Content
local_update.bin CSV weight vector, e.g.: 0.012,−0.034,0.891,...
metrics.json {"round_id":1,"loss":0.42,"train_accuracy":0.83,"sample_count":350,"update_norm":312.45}
data_profile.json {"sample_count":350,"positive_count":0}

Validation by FederatedClientService

After execute(), the framework validates:

Check Condition
Non-empty vector updateVector.length > 0
All finite !Double.isNaN(v) && !Double.isInfinite(v)
Consistent norm |declared - calculated| ≤ 1e-6
Consistent hash sha256(file) == result.updateHash()
Consistent counts sampleCount within the authorized profile

Any mismatch → ErrorCode.UPDATE_REJECTED.


Mandatory rules

  • Never open data/{clientId}/{experimentId}/dataset.csv directly — use context.authorizedDataView().
  • Never write files outside context.outputPath().
  • Never connect to the network or external services during training.
  • Declare MlAlgorithmSpec with supported targets (JVM_SERVER, ANDROID_JAVA, etc.).
  • Produce a non-empty, finite update vector with a correct hash and norm.
  • When convergence history is available, propagate trainingHistory for diagnostics in the monitor.
  • Sensitive health experiments (such as ECG5000) must configure <orchestration><privacy> in research.xml so FederatedClientService applies DataComponent.applyDifferentialPrivacyIfConfigured(...) before upload.