Skip to main content

Configuring a branch

A branch is one federation: one model architecture, one aggregation algorithm, and the settings that govern how rounds run. This page is for the person setting that up — typically a data scientist or federation operator. It explains the choices you make and what they do.

You configure a branch when you create it (in the dashboard or via the API), and you can update it later. Configuration has two parts: the aggregation service and its settings, and an optional free-form model configuration you can push to every participant.

Runs and aggregations​

Two terms that are easy to confuse:

  • A run is a whole training session on the branch. It has a run number and a status you control: start, pause, or stop. Stopping and starting again begins a new run number.
  • An aggregation is a single averaging round within a run. It fires automatically each time enough participants have uploaded their weights, and produces one aggregated result that every participant is notified to download.

So one run contains many aggregations. Leaves only upload successfully while the run status is start; otherwise file_upload reports the run is blocked (or waits, if you configured wait_for_run=True).

The aggregation service​

Choose the algorithm that combines everyone's uploads. Set it as the current field in the branch's service config. Three services are available:

average — federated averaging (recommended)​

The standard federated-averaging algorithm (FedAvg). Each participant's layers are scaled by their weighting, summed, and divided by the total weighting — a weighted mean. This is the right default for almost all use cases.

aggregated_layer_N = Σ(weightingᵢ × layer_Nᵢ) / Σ(weightingᵢ)

maml — meta-learning aggregation (advanced)​

A meta-learning variant that computes the weighted average and then applies a meta-update step relative to the previous round's aggregate. It is intended for meta-learning / fast-adaptation setups and is more specialised than average. If you are unsure which to pick, use average.

note

maml branches require a meta_learning_rate value in the service config. If you are evaluating maml for a real project, contact us so we can advise on the current behaviour and tuning.

per-field — per-field aggregation (federated analytics)​

Combines each named field of the upload with its own operation — sum, min, max, must_match and others — rather than averaging model layers. This is the service for federated analytics: computing statistics across every site's data without training a model, typically to establish the federation-wide constants you normalise against before training starts.

It behaves differently from the other two in one important way. average and maml know what to do the moment they are selected; per-field cannot, because only you know how each of your fields should be combined. So the branch discovers your field names from the first uploads, and then waits for you to assign an operation to each one — and to save it.

A per-field branch will not aggregate until you assign and save

Every field present in an upload must have an operation, and there are deliberately no defaults for fields the platform did not name itself. Until you assign them, rounds are refused — by design, naming the fields that need a decision. And choosing an operation in the settings page is not the same as saving it.

The whole flow, and the step people lose work to, is on Per-field aggregation. Read it before you set a branch to per-field.

The service is spelled exactly per-field, and its assignment map lives under field_primitives in the service config.

Branch settings​

These fields live in the branch's service config. All are required when creating the branch (there are no silent defaults — omitting one is rejected).

SettingTypeMeaning
currentstringThe aggregation service: "average", "maml" or "per-field".
files_per_aggregationintegerHow many uploaded files must arrive before one aggregation fires. Must be > 0 and at most 1000.
input_expiry_time_sinteger (seconds)How long uploaded input files are retained before expiring.
results_expiry_time_sinteger (seconds)How long aggregated result files are retained before expiring.
meta_learning_ratenumbermaml only — required and non-zero for the maml service; ignored for average.
field_primitivesobjectper-field only — a map of field name to operation. It may be empty when you create the branch, because you will not know your field names yet; it must cover every uploaded field before the branch can aggregate. See Per-field aggregation.

files_per_aggregation — how a round is triggered​

This is the most important setting to get right. An aggregation fires as soon as this many files have been uploaded for the branch. For a federation of 5 leaves that should each contribute once per round, set it to 5: the platform waits for all five uploads, averages them, and notifies everyone.

  • Set it too high (more than the number of active leaves) and aggregations will never fire.
  • Set it too low and a round completes before everyone has contributed.

Expiry settings​

input_expiry_time_s and results_expiry_time_s control how long files live in BranchKey storage. Shorter expiries reduce storage footprint; make them long enough that every participant has time to upload inputs and download results within a round.

Model configuration (pushing settings to participants)​

A branch can carry an optional model_config object — a free-form block of settings that is stored by the platform and served back to every leaf via client.get_branch_config(). BranchKey does not interpret it; it is a channel for the branch owner to distribute model hyperparameters so that every participant builds an identical model.

A common convention is a sklearn_params sub-object:

config = client.get_branch_config()
model_config = config.get("model_config", {})
sklearn_params = model_config.get("sklearn_params", {})
# use sklearn_params to construct your local model identically to every other leaf

Because it is free-form, the exact keys are entirely up to your client code — there is no platform-enforced schema. Agree the structure across your team and read it the same way in every leaf.

How weighting fits in​

Each leaf attaches a weighting to its upload (see Extracting & reloading weights). The aggregation service uses it as the weight in the weighted average above. Setting it to each leaf's number of training samples gives larger datasets proportionally more influence — the standard FedAvg behaviour. Only relative magnitudes matter.

A per-field analytics payload carries no weighting, and does not need one: where a sample-weighted mean is wanted, summing each site's count and total already counts every record once. See Federated analytics, by hand.

See also​