Principle:AUTOMATIC1111 Stable diffusion webui Merged model saving
| Knowledge Sources | |
|---|---|
| Domains | Model Serialization, Checkpoint Merging, Model Registry |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
Merged model saving is the process of serializing a merged state dictionary to disk in a chosen format and registering the resulting checkpoint file in the application's model discovery system.
Description
After weight interpolation produces a final state dictionary, it must be persisted to disk and made available for inference. Merged model saving encompasses two distinct concerns: the serialization format and the post-save registration.
Serialization formats:
Safetensors is a modern tensor serialization format designed for safety and speed. Unlike Python's pickle-based formats, safetensors does not execute arbitrary code during deserialization, eliminating a class of security vulnerabilities. It stores tensors in a flat binary layout with a JSON header containing metadata, enabling fast random access and memory mapping. The format supports an optional metadata dictionary embedded in the header, which is used to store merge recipes and model provenance.
Pickle-based checkpoints (.ckpt) use PyTorch's torch.save, which relies on Python's pickle protocol. While widely compatible with older tools and workflows, this format is vulnerable to arbitrary code execution attacks because pickle can encode executable Python objects. The format does not natively support metadata headers.
Post-save registration: After writing the checkpoint file, the model registry must be refreshed so the new checkpoint appears in UI dropdowns and can be loaded for inference. This involves scanning the model directories, constructing CheckpointInfo objects for any new files, and computing their hashes. The shorthash is computed immediately for the newly created model so it can be identified.
Usage
Use merged model saving when:
- Completing a merge operation: The final step of any checkpoint merge is saving and registering the result.
- Choosing between security and compatibility: Prefer safetensors for new workflows (security, speed, metadata support). Use .ckpt only for backward compatibility with tools that do not support safetensors.
- Embedding provenance: When saving as safetensors, embed merge recipe metadata so downstream users can trace the model's lineage.
- Making merged models immediately available: The registration step ensures the merged model appears in model selection UI without requiring an application restart.
Theoretical Basis
Safetensors Format Structure
A safetensors file has the following binary layout:
[8 bytes: header_size (uint64 LE)]
[header_size bytes: JSON header]
[remaining bytes: tensor data]
The JSON header maps tensor names to their data type, shape, and byte offset ranges within the data section:
{
"__metadata__": {"format": "pt", "sd_merge_recipe": "..."},
"model.diffusion_model.input_blocks.0.0.weight": {
"dtype": "F16",
"shape": [320, 4, 3, 3],
"data_offsets": [0, 23040]
},
...
}
Key properties:
- Safety: No executable code in the format; deserialization cannot trigger arbitrary operations.
- Speed: Memory-mapped access allows loading individual tensors without reading the entire file.
- Metadata: The
__metadata__key stores arbitrary string key-value pairs.
Pickle-Based Checkpoint Format
PyTorch's torch.save serializes Python objects using the pickle protocol:
torch.save(state_dict, filepath)
# Equivalent to: pickle.dump(state_dict, file, protocol=2)
# with special handling for tensor storage
The resulting file contains:
- Pickled Python object graph (the dict structure)
- Tensor storage data (raw bytes, potentially ZIP-compressed)
Security risk: Pickle can encode arbitrary Python class instantiations. A malicious .ckpt file can execute code when loaded via torch.load.
Model Registry Refresh
After saving, the registry refresh follows this pattern:
1. Clear existing checkpoints_list and checkpoint_aliases
2. Scan model directories for .ckpt and .safetensors files
3. For each file:
a. Create CheckpointInfo(filename)
b. Call checkpoint_info.register() to populate aliases
4. For the newly created model:
a. Locate it in checkpoints_list by filename
b. Call calculate_shorthash() to compute SHA-256
This ensures the new model is immediately selectable in the UI and identifiable by its hash.
Output Filename Generation
The output filename is constructed from several components:
filename = custom_name OR auto_generated_name
filename += ".inpainting" if result_is_inpainting_model
filename += ".instruct-pix2pix" if result_is_instruct_pix2pix_model
filename += "." + checkpoint_format # "safetensors" or "ckpt"
output_path = os.path.join(ckpt_dir, filename)
Auto-generated names encode the merge recipe:
- Weighted sum:
"0.7(modelA) + 0.3(modelB).safetensors" - Add difference:
"modelA + 1.0(modelB - modelC).safetensors"