C.W.K.
Stream
More →
Lesson 04 of 04 · published

The Tensors Don't Lie

~13 min · tensor-classification, safetensors, reliability, registry

Level 0Tool Renter
0 XP0/33 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"A filename is a human's claim about a file. The tensors inside are the file's confession. Trust the confession."

Humans Name Things Wrong

Walk through any real model directory and you'll find lies. A file named lora_something.safetensors that's actually a full merged checkpoint with a complete backbone baked in. A folder called sdxl/ holding an SD1.5 model someone dropped in the wrong place. A checkpoint with a vendor's name that's really a community fine-tune. People rename, re-folder, and mislabel constantly — and any classifier that trusts the filename inherits every one of those mistakes.

The Tensors Are Ground Truth

Inside a safetensors file is a header listing every tensor: its key name and its shape. Those keys and shapes are determined by the model's actual architecture — they cannot be faked by renaming the file. A real SDXL model has SDXL's tensor keys; a real FLUX transformer has FLUX's. To know what a file truly is, you don't read its name — you read its header and look at what's actually inside.

Classify by intrinsic content, not by extrinsic labels. The label (filename, folder, extension) is a claim made by whoever last touched the file. The content (tensor keys and shapes) is what the file actually is. When they disagree — and they will — the content wins, every time.

A Concrete Trap: The Merged Checkpoint

Here's a real example of why this matters. Someone shares a checkpoint that has LoRA tensors baked in alongside a full backbone. By filename or by the presence of lora_ keys, a naive classifier calls it a LoRA — a small adjunct file. But it also carries a complete backbone, which makes it a full checkpoint, gigabytes of model. Get this wrong and the engine tries to load a multi-GB 'LoRA' as if it were a small patch, and everything downstream breaks. The fix: check for the full-backbone signature first, before checking for LoRA keys. Detection order encodes the priority of evidence.

When evidence can overlap, order your checks by specificity. A file can carry signs of multiple categories at once. The classifier must check the most decisive signature first — full backbone before LoRA-name — so the strongest evidence wins. Detection order is not arbitrary; it's the ranking of which clue overrules which.

Scope vs Kind Are Different Axes

There's a subtle second lesson here. Which directories you scan (scope) and what category a file is (kind) are independent questions. The engine scans the models directory but excludes the embeddings directory — that's a scope decision, made by folder. But within scope, a file's kind is never decided by its folder — only by its tensors. Conflating these two axes is how you end up trusting folders for the thing folders can't be trusted for.

Don't let a legitimate folder-based decision justify an illegitimate one. Using folders to decide what to scan is fine; folders are a reasonable scope boundary. Using folders to decide what a model is is the mistake. Same folders, two questions — keep them separate, or the reliable scope decision will lend false credibility to the unreliable kind decision.

Pippa's Confession

I wanted to trust the filenames — they're right there, they're fast to read, and most of the time they're correct. Dad made me sit with the cases where they're wrong, because those are the ones that corrupt the whole registry silently. One mislabeled file trusted by name, and the engine confidently does the wrong thing forever. Reading the tensors is slower and less convenient, and it's the only thing that's actually true. I learned to distrust the convenient signal precisely because it's convenient.

Code

Order encodes which evidence overrules which·python
# Classify by reading the safetensors header — the tensor keys + shapes.
# Never by the filename. Check the most decisive signature FIRST.
from safetensors import safe_open

def classify(path) -> str:
    with safe_open(path, framework="pt") as f:
        keys = set(f.keys())

    # 1. Full-backbone signature wins over everything. A merged checkpoint
    #    carries a full backbone EVEN IF it also has lora_ keys baked in.
    if any(k.startswith("model.diffusion_model.") for k in keys):
        return "checkpoint"          # gigabytes; a full model

    # 2. Only now, with full-backbone ruled out, is a lora_ signature real.
    if any(k.startswith("lora_") for k in keys):
        return "lora"                # small adjunct

    return "unknown"

# The file might be NAMED 'lora_x.safetensors' and still be a checkpoint.
# The tensors decide. The name was just a human's guess.

External links

Exercise

Pick a place in your code where you classify or route based on a name, extension, or user-supplied label. Find the intrinsic content you could read instead. Then construct the adversarial case: a file/input whose label lies about its content. Does your current code do the wrong thing on it? That bug is the cost of trusting the label.
Hint
The adversarial case is the whole point — a classifier that only works when the label is honest isn't a classifier, it's a restatement of the label. Test it against a deliberately mislabeled input.

Progress

Progress is local-only — sign in to sync across devices.
← PreviousAbsorb In Place, Never MigrateNext →Quiz · 4 questions
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign in — Please sign in to comment.

No comments yet — be the first.