Repository navigation
Read cover images and model info embedded in safetensors headers - #1803
Open
deepratna-awale wants to merge 4 commits into
Open
deepratna-awale wants to merge 4 commits into
deepratna-awale wants to merge 4 commits into
Conversation
Models can carry their cover image inside the safetensors header metadata (cover_count and cover_1 ... cover_N, base64 JPEG), so the preview survives moving, renaming or sharing the file without its loose .preview image. When indexing, safetensors models that have no preview image file are checked for an embedded cover_1. It is written once to a cache folder in the temp directory, named by its SHA-256, and used as the model's preview in the Checkpoint Manager, the Inference model pickers and prompt completion. A loose preview image always takes priority, the model file is never modified, and results are cached per file size and modification time so unchanged files are not re-read on later index refreshes. Fixes LykosAI#1800
Read the rest of the LoRA-Container metadata and the common ModelSpec and kohya-ss keys while indexing safetensors models: - cm_info: used as the model's connected model info when there is no .cm-info.json next to the model. - modelspec.thumbnail: used as the preview when there is no cover_1. - modelspec.architecture / ss_base_model_version: the base model, for models without one in their connected model info. Shown on the Checkpoint Manager card and used by its base model filter and sort, the Inference model pickers and LoRA base model filtering. - modelspec.trigger_phrase: trigger words for models without any, shown and copyable in the Checkpoint Manager and Inference. - model_sha256_original: when a CivitAI lookup by file hash finds nothing, metadata import retries with the original file hash, so models whose header was edited after download can still be matched. Embedded images (cover_N, modelspec.thumbnail) are shown as a short placeholder in the View Metadata dialog instead of their base64 text.
…l picker The Checkpoint Manager card's trigger words line and the model picker dialog's base model badge still read ConnectedModelInfo directly, so trigger words and base models from the safetensors header were missing there.
deepratna-awale
marked this pull request as ready for review
November 19, 2026 01:17
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #1800
Problem
Stability Matrix only takes a local model's preview image and details from loose files next to the model (
NAME.preview.jpeg,NAME.cm-info.json). A model that carries them inside its safetensors header, in the LoRA-Container format described in the issue, shows no image and no details in the Checkpoint Manager, so they are lost as soon as the model is moved, renamed or shared without its sidecar files.The same header often has other useful metadata that the app ignores today: the base model and trigger words that ModelSpec and kohya-ss training write.
Changes
Reading the header
SafetensorEmbeddedInforeads, from a safetensors file's__metadata__:cover_1(LoRA-Container), ormodelspec.thumbnailif there is nocover_1. Following the spec, a file withoutcover_counthas no covers,cover_Npast the count is ignored, and adata:image/...;base64,prefix is accepted.GetCover(metadata, n)can read gallery covers too.cm_info, the embedded copy of.cm-info.json.modelspec.architecture, falling back toss_base_model_version, mapped to the CivitAI base model names the app already uses. Only unambiguous architectures are mapped: SD 1.5, SDXL 1.0, SD 3, SD 3.5 Medium/Large, Flux.1 D and Flux.1 S. Kohya'sflux1andsd_v2are left unmapped because they don't say which variant.modelspec.trigger_phrase.model_sha256_original.SafetensorMetadata: header reading moved into an internalReadMetadataDictionaryAsync(now cancellable) that both use.ParseAsyncbehaves as before.Model index
.safetensorsmodels missing a preview image or a.cm-info.jsonhave their header read once:<temp>/StabilityMatrix/Cache/EmbeddedCovers/<sha256>.jpeg|png(the same temp cache root the image loader uses) and used only when there is no preview image file.cm_infobecomes the model'sConnectedModelInfoonly when there is no.cm-info.json.EmbeddedBaseModel/EmbeddedTrainedWords.ImportedAttruncation was moved into a helper so the embeddedcm_infogets it too.Where it shows up
LocalModelFilegetsGetDisplayPreviewImageFullPath(),DisplayBaseModelandDisplayTrainedWords(String). These prefer the sidecar data and fall back to the embedded data.PreviewImageFullPathGlobalfalls back to the embedded cover.ModelCompatChecker) and the base-model-based workflow and prompt hints useDisplayBaseModel/DisplayTrainedWords.cover_Nandmodelspec.thumbnailshow as(embedded image, N KB)instead of their base64 text.CivitAI lookup
model_sha256_originalfrom the header.ModelFinder.RemoteFindModelnow matches the returned file by BLAKE3 or SHA256.Everything is read-only. The model file is never modified. Rename, delete, move and the metadata editor still work only with the loose preview image file (
GetPreviewImageFullPathis unchanged), so the cached cover is never copied or moved next to the model.Screenshots
Rendered headless with the real Checkpoint Manager page and View Metadata dialog. The models folder holds five real LoRAs, with no sidecar files next to them:
niji_gloss,cb_lora_anima-000050,barska_ilxlandtosskant_ilxl: LoRAs downloaded from CivitAI whose trainers embedded amodelspec.thumbnail. The two_ilxlfiles carry ModelSpec's default SDXL thumbnail and kohya'sss_base_model_version. The two Anima LoRAs also havemodelspec.trigger_phrase.chaoslandscape: the LoRA-Container sample from the format's repository, linked in the issue, with six embedded covers and acm_info.Checkpoint Manager, before
Checkpoint Manager, after. Embedded covers and thumbnails, trigger words from
cm_infoor ModelSpec, and the base model badge where the architecture maps to one (Anima isn't in the mapping, so those two have no badge).View Metadata for
niji_gloss, before / afterTesting
SafetensorEmbeddedInfoTests: reading a LoRA-Container file (cover,cm_info, original hash, base model), a file without metadata, gallery covers andcover_countbounds, data URI prefixes, missingcover_count, invalid base64, themodelspec.thumbnailfallback and its priority, the base model mapping table, trigger phrase splitting, invalid original hashes and invalidcm_infoJSON.SafetensorMetadataTests: embedded images are shown as placeholders.LocalModelFileTests: the sidecar preview, base model and trigger words take priority over embedded ones, and the embedded ones are used when the sidecar has none.MetadataImportServiceTests: a model not found by its BLAKE3 hash is found bymodel_sha256_originaland its.cm-info.jsonis written.ModelIndexService.RefreshIndex()twice against a temp models folder with an embedded-cover-and-cm_infoLoRA, a ModelSpec-only LoRA and a LoRA with both a sidecar and an embeddedcm_info. Each got the expected preview, name, base model and trigger words, the sidecar won where present, and the second refresh served from the cache.main, using a throwaway UI test that isn't part of the PR. This caught two bindings that still readConnectedModelInfodirectly: the card's trigger words line and the model picker dialog's base model badge. Both are fixed.StabilityMatrix.Tests: all passed except theTestLicenseUrl/TestPreviewImageUrichecks, which need outbound network access that my test environment blocks (unrelated to this change).StabilityMatrix.UITests: 8/8 passed.