---

name: training description: "Route for SSD Keras model building, compilation, training, and fine-tuning." metadata: disco-role: operating disable-model-invocation: true license: Apache 2.0

Training

Use this route when the task is about building a trainable SSD model, loading pretrained weights, compiling the loss, wiring the encoder, or running a fitting loop.

What this route covers

• building SSD300, SSD512, or SSD7-style trainable models
• loading pretrained VGG or SSD weights by name
• compiling with SSDLoss
• creating SSDInputEncoder instances that match the model anchors
• fitting on VOC, CSV, or synthetic data batches
• adapting classifier weights when the class count changes
• using the SSD7 template as a starting point for alternate backbones

What this route excludes

• dataset parsing details and augmentation internals
• decoding predictions
• VOC / COCO evaluation

Send those tasks to data-preparation or inference-evaluation.

First things to check

1. Open references/model-architecture.md to confirm the model / encoder / loss contract.
2. Open references/workflows.md for the notebook-derived training sequence.
3. Open references/compatibility.md if the old TensorFlow / Keras stack is not importing.
4. Run scripts/smoke.py for a tiny synthetic model / encoder / train-step check.

Typical training workflow

1. Pick the model family

• ssd_300 is the canonical path and matches the main Pascal VOC / COCO notebook recipes.
• ssd_512 uses the same design at a larger input size.
• build_model is the smaller SSD7 template and is the best smoke path or custom-backbone starting point.

2. Match the anchor settings

The model builder and the encoder must agree on:

• scales
• aspect ratios
• steps
• offsets
• variances
• coordinate convention
• coordinate normalization

If these drift apart, the model will build but the targets or decoded boxes will be wrong.

3. Load pretrained weights carefully

• Use load_weights(..., by_name=True) when the source weights were saved with a different head shape.
• If the source and target class counts differ, adapt the classifier weights with sample_tensors before loading them.
• The weight-sampling tutorial is the right reference when you are reusing a pretrained detector with a new class list.

4. Compile and fit

• Use SSDLoss.compute_loss as the model loss.
• Keep the optimizer settings consistent with the notebook recipe when you need to reproduce the historical results.
• Feed the model from DataGenerator through the data-preparation route.
• Keep an eye on early training instability: OOM and NaN are the two common failure modes.

5. Save and resume

• Save the whole model when you need to reload custom layers later.
• If you resume training, keep the loss, encoder, and model config exactly aligned with the original run.

Fine-tuning / transfer learning

When the class set changes, do not edit the pretrained weights by hand.

Instead:

1. Inspect the source classifier kernel and bias shapes.
2. Select the classes to keep.
3. Use sample_tensors to sub-sample or up-sample the classifier tensors consistently.
4. Load the adapted weights into the new model head.

Useful source objects

• ssd_300
• ssd_512
• build_model
• SSDLoss
• SSDInputEncoder
• sample_tensors
• AnchorBoxes
• L2Normalization
• DecodeDetections
• DecodeDetectionsFast

Script path

• scripts/smoke.py — builds a small model, encodes a synthetic batch, runs one training step, and exercises the weight-sampling utility.

Quick decision guide

• Need the canonical VOC / COCO recipe? Start with ssd_300.
• Need a faster smoke path or a custom backbone template? Start with build_model.
• Need to change the class count on pretrained weights? Stay in this route and use sample_tensors before loading the new head.