Model Versioning

Overview

Training face models is an iterative process. You might train for thousands of iterations, then realize that the model looked better at an earlier stage — or you want to try different training parameters without losing your current progress. Model versioning solves this by letting you create named snapshots at any point and roll back when needed.

Each snapshot captures the complete model state, including all weights, optimizer state, and training configuration. Restoring a snapshot replaces the current model files entirely, bringing the model back to the exact state it was in when the snapshot was created.

Creating Snapshots

You can create a snapshot at any time, whether training is running or paused. The snapshot captures the current state of all model files in the project.

Snapshot Metadata

Each snapshot stores the following metadata alongside the model files:

Restoring Versions

To restore a previous snapshot, select it in the version list and click Restore. A confirmation dialog shows the snapshot details and warns that the current model will be replaced.

Version Panel Interface

The Version panel displays all snapshots for the current project in a scrollable list. Each snapshot is shown as a card with:

• Name — The label you gave the snapshot, or an auto-generated name for automatic backups
• Iteration badge — Shows the iteration count (e.g., "Iter 50,000")
• Loss values — Source and destination loss at snapshot time
• Timestamp — When the snapshot was created, displayed as a relative time (e.g., "2 hours ago")
• Notes preview — First line of notes, expandable on click
• Actions — Restore and Delete buttons

Storage Management

Each snapshot stores a complete copy of the model files, which can be hundreds of megabytes depending on the model architecture. Over time, snapshots accumulate and consume significant disk space. Manage storage by deleting snapshots you no longer need.

Deleting Snapshots

To delete a snapshot, click the Delete button on the snapshot card. A confirmation dialog ensures you do not accidentally remove important versions. Deleted snapshots cannot be recovered.

Best Practices

• Name snapshots descriptively. Use names like "Before batch size change" or "Best face detail" rather than generic names like "Version 1".
• Add notes with parameter details. Record the training parameters, batch size, learning rate, and any observations in the notes field. This helps you understand what changed between snapshots.
• Snapshot before experiments. Always create a snapshot before changing training parameters, switching architectures, or trying new techniques. This gives you a guaranteed rollback point.
• Review loss values when choosing a restore point. Lower loss values generally indicate a better-trained model, but visual quality does not always correlate directly with loss. Use the training preview alongside loss values to make restore decisions.
• Clean up old snapshots regularly. Delete snapshots from failed experiments or intermediate checkpoints that are no longer useful. Keep the snapshots that represent meaningful states.
• Use the automatic backup. When restoring, the automatic backup of the current state acts as a safety net. Do not delete this backup until you are sure the restored version is what you want.

How It Works Internally

The ModelVersionManager service handles all snapshot operations. Snapshots are stored as timestamped directories within the project folder, each containing a complete copy of the model files and a metadata JSON file.

When creating a snapshot, all model files are copied to the version directory. When restoring, the current model files are backed up (if a backup does not already exist), then the snapshot files are copied back to the model directory. File operations use atomic copy-then-rename where possible to prevent corruption.