When would you use Keras save_weights instead of saving the whole model?

## Two files, two contracts A `.keras` archive answers "rebuild this model". A weights file answers "here are the numbers". The second is only meaningful next to code that produces the same variables in the same shapes. `model.save_weights(filepath)` in Keras 3 insists the filename end in `.weights.h5`; anything else raises. The file is HDF5 containing the model's variable values, keyed by their position in the layer tree. ## Why loading needs a built model `model.load_weights(path)` does not create layers. It walks the existing model and assigns saved values into variables that are already there. A Sequential or Functional model built with an input shape already has its variables, so loading works right after construction. A subclassed model creates its variables lazily on the first `build()` or the first forward pass, so this fails: ``` model = MyModel() model.load_weights("ckpt.weights.h5") # nothing to load into ``` Call `model.build(input_shape)` or run one batch through it first. The error is about a structure or variable mismatch, and the cause is almost always "the model was not built", not "the file is bad". `load_weights` also accepts `skip_mismatch=True`, which skips layers whose weight count or shapes do not line up instead of raising. That is the transfer-learning switch: load a backbone's weights into a model whose head has a different number of classes and let the head stay randomly initialized. Use it deliberately - with it on, a wholesale mismatch loads almost nothing and trains silently from noise. ## When each one wins Weights-only is the better fit when: - The architecture lives in versioned source you always have. Then the archive's config adds nothing. - You have custom layers and do not want to make them serializable yet. A weights file never re-instantiates a class, so registration and get_config do not enter the picture. - You want frequent, cheap in-run checkpoints and will restart from the same script. - You are doing partial or cross-model loading, where skip_mismatch matters. Whole-model `.keras` is the better fit when: - Someone else, or some other process, must load the model without your training script. - You want optimizer state for resuming. - The artifact has to outlive the repository revision that built it. ## The failure mode to name in an interview The dangerous case is a weights file whose architecture code has drifted: someone changes a layer width, some shapes still match, `skip_mismatch=True` is set from an old copy-paste, and the model loads partially. Nothing raises; evaluation is merely bad. Guard it by keeping weights files next to the exact code revision that wrote them, by logging how many layers were actually restored, or by preferring `.keras` for anything you will not reload within the hour.