Skip to content

Conversation

psychedelicious
Copy link
Collaborator

@psychedelicious psychedelicious commented Sep 18, 2025

Summary

Normalize model file storage to a flat directory structure.

Currently, models were stored in a nested hierarchy of folders like this:

  • <models_dir>/<base>/<type>/model_name.ext for single-file models
  • <models_dir>/<base>/<type>/model_name/**.* for folder models

This has approach has a couple associated unpleasantries:

  • Model names are easily clobbered. For example, maaaany models are called simply model.safetensors. How do we work around that? Well, right now, we throw when a candidate model install would clobber an existing file.
  • Model file storage is tightly coupled to its config attributes. When a model's base or type is changed, we need to move the model files, else the directory hierarchy no longer accurately indicates the model's base and type.
  • It encourages users to fiddle with their model files and implies that users can simply drop models into the appropriate folder and Invoke will be able to use the models - which is not the case.

This PR normalizes/flattens model storage paths, storing each model in its own dir which is named with the model's unique key:

  • <models_dir>/<key>/file_name.ext for single-file models
  • <models_dir>/<key>/**.* for folder models

This neatly addressing those unpleasantries:

  • No chance of clobbering, because keys are UUIDs.
  • No coupling of model base/type to file storage.
  • It's immediately clear that the models_dir is not something you should fiddle with.

This PR includes the simple code change for new model installs and a rather cautious migration to migrate to the new directory structure and update the model records in the DB. It uses SQLite save points and records all file operations, effectively making the DB and FS operations into a single transaction that can be rolled back.

It also removes some now-unused methods in the MM codebase.

Related Issues / Discussions

Numerous issues scattered throughout discord and GH

QA Instructions

First, test the migration with your models_dir at the default setting (e.g. no models_dir in invokeai.yaml):

  • Make a backup of your install dir (e.g. cp -r /path/to/invokeai/ /path/to/invokeai_backup/).
    • You could just back up the databases/ and models/ dirs I suppose.
  • Start up Invoke to run the migration. You'll see log messages as it does its thing.
  • Generate, have a play, nothing should break.
  • Install a model. Should work.
  • Review your install dir; it should look the same except models/ should have a UUID folder for each model in there.

Next, do the same tests, but move models_dir to some other location (e.g. mv /path/to/invokeai/models/ /home/username/models/ and update invokeai.yaml accordingly before starting up the app.

I've tested both scenarios and tested invalid model configs in the DB. Everything working fine for me. We don't expect any generation issues, because we aren't doing anything that Invoke didn't already do. It already can load models from any location; we are just shuffling files around.

Merge Plan

n/a

Checklist

  • The PR has a short but descriptive title, suitable for a changelog
  • Tests added / updated (if applicable)
  • ❗Changes to a redux slice have a corresponding migration
  • Documentation added / updated (if applicable)
  • Updated What's New copy (if doing a release after this PR)

Store models in a flat directory structure. Each model is in a dir named
its unique key (a UUID). Inside that dir is either the model file or the
model dir.
@github-actions github-actions bot added api python PRs that change python files services PRs that change app services python-tests PRs that change python tests labels Sep 18, 2025
@psychedelicious psychedelicious force-pushed the psyche/feat/mm/normalized-model-storage branch from 05f9551 to 5e6b52d Compare September 19, 2025 02:55
@psychedelicious psychedelicious marked this pull request as draft September 19, 2025 11:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
api python PRs that change python files python-tests PRs that change python tests services PRs that change app services
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants