Keras API

Keras API#

The keras_api module provides an API that you can use to train your model with differential privacy in Keras. Currently, only the DP-SGD algorithm is supported. It works the following way: first you create a Keras model, then you wrap it with the make_private() function passing essential parameters for DP training. make_private preserves the same interface that a usual Keras model has, so use it as you would use a regular Keras model. For example, call fit() to train it and obtain a DP model. Refer to the API Reference section below to see the meaning of each DP parameter.

Example Usage#

This section demonstrates how to integrate the Keras API into a typical Keras training workflow.

The example below enables poisson_sampling_in_fit and passes training data to fit() as per-example arrays. In that setup, the DP Keras wrapper draws Poisson-sampled batches internally from those arrays.

examples/keras_api_example.py#
 1  (x_train, y_train), (x_test, y_test) = load_data()
 2  batch_size = 512
 3  train_size = (len(x_train) // batch_size) * batch_size
 4  x_train, y_train = x_train[:train_size], y_train[:train_size]
 5  keras.utils.set_random_seed(0)
 6  model = get_model()
 7
 8  epsilon = 1.1
 9  delta = 1e-5
10  epochs = 5
11  dp = True
12  clipping_norm = 1.0
13
14  if dp:
15    params = keras_api.DPKerasConfig(
16        epsilon=epsilon,
17        delta=delta,
18        clipping_norm=clipping_norm,
19        batch_size=batch_size,
20        train_steps=epochs * (train_size // batch_size),
21        train_size=train_size,
22        poisson_sampling_in_fit=True,
23        seed=0,
24        gradient_accumulation_steps=1,
25    )
26    model = keras_api.make_private(model, params)
27    print(
28        f"DP training:{epsilon=} {delta=} {clipping_norm=} {batch_size=} "
29        f"{epochs=} {train_size=}"
30    )
31    # This example opts into internal Poisson sampling from the per-example
32    # arrays passed to fit().
33  else:
34    print("Non-DP training")
35  model.compile(
36      loss="categorical_crossentropy",
37      optimizer="adam",
38      metrics=["accuracy"],
39  )
40  fit_kwargs = dict(
41      x=x_train,
42      y=y_train,
43      epochs=epochs,
44      validation_data=(x_test, y_test),
45  )
46  if not dp:
47    fit_kwargs["batch_size"] = batch_size
48  history = model.fit(**fit_kwargs)

API Reference#

API for adding DP-SGD to a Keras model.

Example Usage:

import os
os.environ["KERAS_BACKEND"] = "jax"
import keras
from jax_privacy import keras_api

model = keras.Sequential([
    keras.Input(shape=(1,)),
    keras.layers.Dense(1),
])
params = keras_api.DPKerasConfig(
    epsilon=1.0,
    delta=1e-5,
    clipping_norm=1.0,
    batch_size=8,
    gradient_accumulation_steps=1,
    train_steps=10,
    train_size=80,
    noise_multiplier=1.0,
)
private_model = keras_api.make_private(model, params)
private_model.get_noise_multiplier()
class jax_privacy.keras_api.DPKerasConfig(epsilon, delta, clipping_norm, batch_size, gradient_accumulation_steps, train_steps, train_size, poisson_sampling_in_fit=False, noise_multiplier=None, rescale_to_unit_norm=True, microbatch_size=None, seed=None)[source]

Bases: object

Parameters for adding DP-SGD to a Keras model.

Variables:
  • epsilon – The epsilon that defines the differential-privacy budget. It should be in (0; +infinity) range. 0 means perfect privacy guarantee (not achievable in practice due to infinite noise), +infinity means no privacy guarantee. A commonly used value is ln(3) (smaller value more noise). You should set this value before training and only based on the privacy guarantees you have to achieve. You should not increase the epsilon only because of poor model performance.

  • delta – The delta that defines the differential-privacy budget. The value of it means the probability of full disclosure, no-privacy. It should be in (0, 1] and be as small as possible (e.g. 1e-5, smaller value more noise). You should set this value before training and only based on the privacy guarantees you have to achieve. You should not increase the delta only because of poor model performance.

  • clipping_norm – The clipping norm for the per-example gradients.

  • batch_size – The batch size used by the DP optimizer. When poisson_sampling_in_fit=True, this is the expected batch size of the internal Poisson sampler. Otherwise it must match the batch size supplied to fit().

  • gradient_accumulation_steps – The number of gradient accumulation steps. This is the number of batches to accumulate before adding noise and performing an optimizer step. 1 means that there is no gradient accumulation, each optimizer step is performed after a single batch. This parameter defines the effective batch size = (physical) batch_size * gradient_accumulation_steps, i.e. the real accumulated batch size used for the model update. Usually DP training provides better accuracy with larger effective batch size, therefore it is recommended to set gradient_accumulation_steps to a value larger than 1. In many cases, you won’t be able to set the physical batch size to a large enough value due to memory constraints, therefore gradient accumulation technique is very useful during DP training.

  • train_steps – The number of training steps (optimizer update steps). If you try to train the model for more steps, it will fail. Because one optimizer update consumes gradient_accumulation_steps batches, this is the number of optimizer updates, not the number of (micro-)batches. If you train by epochs, then it is epochs * (train_size // effective_batch_size), where effective_batch_size = batch_size * gradient_accumulation_steps (this reduces to epochs * (train_size // batch_size) only when gradient_accumulation_steps == 1). If you train while the dataset iterator is not over, then it is the number of optimizer updates the iterator produces, i.e. its (micro-)batch length // gradient_accumulation_steps.

  • train_size – The number of training examples in the dataset. If you repeat the examples in your dataset iterator, it should be the number of training examples in the original dataset before repeating.

  • poisson_sampling_in_fit – Whether fit() should internally resample random-access array inputs using Poisson sampling. Leave this as False for backwards-compatible behavior or when the user supplies a dataset iterator that already handles sampling.

  • noise_multiplier – The noise multiplier for the gradients. If None (recommended), the noise multiplier will be automatically calculated based on epsilon, delta, effective_batch_size, train_steps and train_size. The noise added to the average of gradients per total batch is normal with mean 0 and stddev = noise_multiplier * clipping_norm / effective_batch_size.

  • rescale_to_unit_norm – Whether to rescale the gradients to unit norm. Simplifies learning-rate tuning, see https://arxiv.org/abs/2204.13650.

  • seed – The seed for the random number generator. If None, a random seed is used. It must be an int64. Useful for reproducibility.

  • microbatch_size – The size of each microbatch. The device batch size will be split up into microbatches of this size and processed sequentially on the forward/backward pass. By setting microbatch_size=batch_size, the forward/backward pass is performed once on the entire batch using jax.vmap(). By setting microbatch_size=1, the forward/backward pass is performed on each batch element individually, with the gradients accumulated sequentially using jax.lax.scan(). Setting to batch_size gives the largest degree of parallelism, while setting to 1 gives the least memory consumption. Any value in between can be used to trade-off memory consumption vs. parallel computation. This parameter is similar to gradient_accumulation_steps, but it works fully inside of device memory under a single jitted function, while gradient_accumulation_steps operates outside of the jit boundary. The default value is None, which means that no microbatching is used, and is equivalent to microbatch_size=batch_size.

property effective_batch_size: int

The effective batch size which is used for the model update.

It equals batch_size * gradient_accumulation_steps.

update_with_calibrated_noise_multiplier()[source]

Calculates the noise multiplier for the given DP training parameters.

Return type:

DPKerasConfig

Returns:

A copy (new instance) of DPKerasConfig with the noise multiplier set to the calibrated value.

jax_privacy.keras_api.make_private(model, params)[source]

Adds DP-SGD training to a Keras model without modifying its API.

This function mutates model in place, installs the DP-SGD hooks, and returns the same model instance. When params.poisson_sampling_in_fit is enabled, the wrapped fit() path expects random-access per-example arrays or pytrees of arrays so it can perform Poisson sampling internally.

Parameters:
  • model (Model) – The Keras model to add DP-SGD training to.

  • params (DPKerasConfig) – The DPKerasConfig parameters for DP-SGD training.

Return type:

Model

Returns:

The input model with overloaded methods for DP-SGD training.