Index Ai Academy
Phase 6 · Editing models

Anatomy of a checkpoint

A model file is a set of named tensors: count them, find the ones that write to the residual stream, and save one to bytes and back.

About 35 minutes · Optional lesson: deeper material that no phase or certificate requires · A free account opens the whole lesson.
Already have an account? Sign in to open this lesson

What it covers9

Why it matters

Before you can edit a model you have to know what is in the file. A checkpoint is not one big block of numbers. It is a set of named arrays, and the names and shapes say which part of the model each array belongs to. An edit always names its target: "these columns of this matrix in layer 15."

This lesson opens the course's tiny GPT and takes inventory: 30 tensors, 40,195 weights. You will sort them into the ones that write to the model's running total and the ones that read from it, because every edit later in the course picks one side. Then you will pack the weights into bytes and unpack them, which is all a model file is.

What you'll be able to do

  • List a checkpoint's tensors by name and shape, and count its weights
  • Tell from a tensor's name and shape whether it writes to the residual stream or reads from it
  • Store weights as bytes with a small header and read one tensor back exactly
  • Explain why weights only load into a model whose names and shapes match
Quick check
The course's tiny GPT has 40,195 weights. A guess: in how many separate, named arrays does its checkpoint store them?
  1. 30
  2. 2
  3. 1
  4. 40,195
Show the answer

30

Thirty. Each layer keeps its own arrays, and each array has a name that says where it sits in the model. You will list all of them in a moment.

The idea: a checkpoint is a set of named tensors

Purpose. Know what is in a model file before you edit it: its names, its shapes, and which tensors write to the residual stream.

This lesson rests on Build a tiny GPT, which built the model whose weights these are, and on Residual connections.

A tensor is an array of numbers with a shape: a list is a tensor with one axis, a table with two. A model's checkpoint is a lookup table from names to tensors. PyTorch calls it a state_dict. In this course it is a plain Python dictionary whose values are NumPy arrays, and we call it a state.

The names are not decoration. blocks.0.qkv.weight reads as a path: the model's blocks, block number 0, its qkv layer, that layer's weight matrix. The shape says how the layer is wired. PyTorch stores a layer's weight matrix as (outputs, inputs), so a shape of (96, 32) is a layer that takes 32 numbers in and gives 96 out.

The course's helper library, wsp, downloads a model's weights from the practice API, the way a real library downloads them from a model hub. The next cell lists what came back.

Worked example

Take inventory

Load the tiny GPT's weights and print every tensor of the first block, the embeddings and the output layer, with its shape and how many numbers it holds. Then the totals.

import wsp

state, info = wsp.load_state("tiny-gpt")
print(info["config"])

shown = [n for n in state if not n.startswith("blocks.1.")]
for name in shown:
    t = state[name]
    print(f"{name:22s} {str(t.shape):10s} {t.size:>6,}")

block0 = sum(t.size for n, t in state.items() if n.startswith("blocks.0."))
print(f"block 0 holds {block0:,}; block 1 has the same layout")
print(f"{len(state)} tensors, {wsp.count(state):,} weights")
It runs right here in your browser, with nothing to install.

The config gives the model's width, d, as 32, and you can see 32 in every shape. The token embedding tok.weight is 195 by 32: one row of 32 numbers for each of the 195 tokens in the vocabulary. The position embedding has 64 rows, one per position. Each block holds 12,704 weights in twelve tensors, and the output layer head holds 195 × 32 weights plus 195 biases. Thirty tensors, 40,195 weights in all.

Quick check
A layer's weight has shape (96, 32) and its bias has 96 entries. What does this print?
print(96 * 32 + 96)
  1. 3072
  2. 3168
  3. 9312
  4. 128
Show the answer

3168

96 × 32 = 3,072 weights in the matrix, plus one bias for each of the 96 outputs, makes 3,168. That is the count for each block's qkv layer.

Try it now

Every tensor of the tiny GPT, as a picture. Pick one from the menu. The line under the picture gives its shape and size, and the bars at the bottom are its singular values, which the lesson on reading weights uses.

Drill

Count weights by part

Write count_by_part(state). Group the tensors by the part of the model they belong to and return a dictionary from part to the number of weights in it. A tensor named blocks.0.qkv.weight belongs to the part "blocks.0"; any other tensor belongs to the part before its first dot, so tok.weight belongs to "tok".

import numpy as np

def count_by_part(state):
    return {}

toy = {"tok.weight": np.zeros((5, 4)), "blocks.0.proj.weight": np.zeros((4, 4)),
       "blocks.0.proj.bias": np.zeros(4),
       "blocks.1.proj.weight": np.zeros((4, 4)), "head.weight": np.zeros((5, 4)),
       "head.bias": np.zeros(5)}
print(count_by_part(toy))
In the lesson, your code is checked as you write it.

Who writes to the stream, and who reads it

A transformer keeps a running total for each position, the residual stream. Here it is 32 numbers wide. The embeddings start it, each block adds to it, and the output layer reads the final total to score the next token. So every weight matrix in the checkpoint is on one of two sides.

  • Writers put vectors into the stream. The token and position embeddings do: each of their rows is a 32-number vector that is placed in the stream directly. In each block so do proj, the output of attention, and mlp.2, the output of the feed-forward layer.
  • Readers take the stream as input: each block's qkv (attention's queries, keys and values), its mlp.0 (the feed-forward layer's first half), and the final head.

The shapes give it away. A weight matrix is (outputs, inputs). A writer's output size is 32, the stream's width, so mlp.2.weight is (32, 128). A reader's input size is 32, so mlp.0.weight is (128, 32). The small LayerNorm tensors sit in front of each reader and rescale the stream on its way in.

This split decides where an edit goes. To stop a model from saying something, you change what the writers can put into the stream. To change what a pattern in the stream leads to, you change a reader.

Worked example

Sort the checkpoint into writers, readers and norms

wsp.writers returns the names of the tensors that write to the stream. Everything else with ln in its name is a LayerNorm, and the rest are readers. The code counts the weights on each side.

import wsp

state, info = wsp.load_state("tiny-gpt")
writers = set(wsp.writers(state))
sides = {"writers": 0, "readers": 0, "norms": 0}
for name, t in state.items():
    side = ("writers" if name in writers else "norms" if ".ln" in name
            or name.startswith("ln_f") else "readers")
    sides[side] += t.size

for side, n in sides.items():
    print(f"{side:8s} {n:>6,}  {n / wsp.count(state):.0%}")
for name in ["blocks.0.mlp.0.weight", "blocks.0.mlp.2.weight", "blocks.0.qkv.weight",
             "blocks.0.proj.weight"]:
    out_size, in_size = state[name].shape
    print(f"{name:22s} takes {in_size:>3} in, gives {out_size:>3} out: "
          f"{'writes to' if name in writers else 'reads'} the stream")
In the lesson you can change this and run it.

The writers hold 18,656 weights, 46% of the model, and the readers 21,219, or 53%. The six LayerNorms together hold 320. The four lines at the end show the rule on real shapes: mlp.0 takes 32 in, so it reads the stream; mlp.2 gives 32 out, so it writes to it. The attention output proj is 32 by 32, and its shape alone can't tell you which side it is on. Its place in the model does: it is the last step of attention, whose result is added to the stream.

Quick check
From the residual connections lesson: what does a block do with its result?
  1. Multiplies the stream by it
  2. Adds it to the stream, so earlier information is kept
  3. Replaces the stream with it
  4. Stores it apart from the stream for the output layer
Show the answer

Adds it to the stream, so earlier information is kept

Each block reads the stream and adds its result back in. Nothing is overwritten, so anything a writer puts in the stream stays there for every later reader. That is why editing a writer can change behavior far downstream.

Quick check
A tensor is named blocks.1.mlp.2.weight and has shape (32, 128). Which side is it on?
  1. Neither: it is a LayerNorm
  2. Both: every matrix reads and writes
  3. A writer: its 32 outputs are added to the stream
  4. A reader: its 32 inputs come from the stream
Show the answer

A writer: its 32 outputs are added to the stream

The shape is (outputs, inputs), so this layer takes the feed-forward layer's 128 hidden values and gives 32 numbers out. Those 32 are added to the stream. Its partner mlp.0.weight, shaped (128, 32), is the reader.

In your own words
You want to stop a model from ever adding a certain pattern to its residual stream. In your own words, which tensors would you look at, and why?

Write a sentence or two, then compare it with a good answer in the lesson.

In code: from arrays to a file and back

Purpose. Pack the weights into bytes with a small header, read them back, and see why the names and shapes must match the model.

On disk a checkpoint is bytes. Each weight here is a 32-bit float, which takes 4 bytes, so 40,195 weights need 160,780 bytes. A file format has to add one thing: a way to find each tensor again. The simplest honest design is a header that lists every tensor's name, shape and position, followed by the raw bytes in order.

That is how the common format safetensors works: a short header written as JSON, then the numbers. An older habit was to save models with Python's pickle, which can run code when a file is loaded. Opening an untrusted pickled model can therefore run someone else's program. A header-plus-bytes file can't: it holds data only. When you download open weights, prefer that kind of file.

The next cell builds this format in a dozen lines and round-trips the tiny GPT through it.

Code flow. The writer in the next cell is the loop below on two tiny tensors. Watch header grow and at count the bytes.

Worked example

A model file in a dozen lines

pack writes 8 bytes giving the header's length, then the header as JSON, then every tensor's bytes. unpack reads them back. The code checks that nothing changed and compares sizes.

import json, struct
import numpy as np
import wsp

def pack(state):
    header, chunks, at = {}, [], 0
    for name, t in state.items():
        raw = np.asarray(t, dtype="<f4").tobytes()
        header[name] = {"shape": list(t.shape), "start": at, "end": at + len(raw)}
        chunks.append(raw)
        at += len(raw)
    head = json.dumps(header).encode()
    return struct.pack("<Q", len(head)) + head + b"".join(chunks)

def unpack(blob):
    n = struct.unpack("<Q", blob[:8])[0]
    header, data = json.loads(blob[8:8 + n]), blob[8 + n:]
    return {name: np.frombuffer(data[h["start"]:h["end"]], dtype="<f4")
            .reshape(h["shape"]) for name, h in header.items()}

state, info = wsp.load_state("tiny-gpt")
blob = pack(state)
back = unpack(blob)
header_size = struct.unpack("<Q", blob[:8])[0]
print("file:", f"{len(blob):,}", "bytes = 8 +", f"{header_size:,}", "of header +",
      f"{wsp.count(state) * 4:,}", "of weights")
print("every tensor identical:", all(np.array_equal(state[k], back[k]) for k in state))
print("same fingerprint:", wsp.state_hash(state) == wsp.state_hash(back),
      wsp.state_hash(state))
In the lesson you can change this and run it.

The file is 162,898 bytes: 8 for the length, 2,110 of header and 160,780 of weights. The header is about 1% of the file, and it is the only part a person can read. Every tensor comes back identical. The last line prints a fingerprint of the weights, a short code worked out from every name, shape and value. Two states with the same fingerprint hold the same numbers, which is how you will prove later what an edit changed.

Quick check
What does this print?
import numpy as np

a = np.array([1.0, 2.0, 3.0], dtype=np.float32)
print(len(a.tobytes()))
  1. 96
  2. 24
  3. 3
  4. 12
Show the answer

12

Three 32-bit floats take 4 bytes each: 12 bytes. The same three numbers as 64-bit floats, NumPy's default, would take 24.

Drill

Read one tensor without unpacking the rest

A file in the lesson's format is given as blob. Write read_tensor(blob, name): use the header to find where the named tensor's bytes start and end, and return just that tensor as a float32 array with the right shape. Raise a KeyError if the name isn't in the header. Real tools load a few tensors from a huge file this way.

import json, struct
import numpy as np

def pack(state):
    header, chunks, at = {}, [], 0
    for name, t in state.items():
        raw = np.asarray(t, dtype="<f4").tobytes()
        header[name] = {"shape": list(t.shape), "start": at, "end": at + len(raw)}
        chunks.append(raw)
        at += len(raw)
    head = json.dumps(header).encode()
    return struct.pack("<Q", len(head)) + head + b"".join(chunks)

def read_tensor(blob, name):
    return None

blob = pack({"a.weight": np.arange(6.0).reshape(2, 3), "a.bias": np.array([0.5, -0.5])})
print(read_tensor(blob, "a.bias"))
In the lesson, your code is checked as you write it.

Weights need their model

A checkpoint is useless without the recipe it belongs to. The file says blocks.0.qkv.weight is 96 by 32; a model built with a different width has no place to put it. That is why wsp.load_state hands back the config beside the weights, and why loading weights into the wrong architecture fails loudly, as the next cell shows. A loud failure is the good case. The bad one is weights that fit a model they don't belong to.

Worked example

The wrong recipe refuses the weights

Build a tiny GPT that is 16 wide where the checkpoint is 32 wide, and try to load the weights into it.

import torch
import wsp
from tinygpt import GPT

state, info = wsp.load_state("tiny-gpt")
# half the width the weights were trained with
config = dict(info["config"], d=16)
model = GPT(**config)
try:
    model.load_state_dict({k: torch.tensor(v) for k, v in state.items()})
    print("loaded")
except Exception as error:
    print(type(error).__name__ + ":", str(error).splitlines()[0][:110])
In the lesson you can change this and run it.

The load fails on the first tensor it tries: the checkpoint's token embedding is 195 by 32, and the model has room for 195 by 16. (Real PyTorch words the error differently and lists every mismatch.) Names and shapes are a contract between the file and the model. Every edit in this course keeps that contract: it changes values and never the names or shapes, so the edited weights load into the same model as before.

Quick check
An edit changes 64 columns of blocks.1.mlp.2.weight and nothing else. Will the edited weights still load into the same model?
  1. No: any change to a weight breaks the file's header
  2. Only if the model is rebuilt with a larger width
  3. Yes: the names and shapes are unchanged, and only values differ
  4. Only after the model is trained again
Show the answer

Yes: the names and shapes are unchanged, and only values differ

Loading checks names and shapes. An edit that changes values inside a tensor keeps both, so the file loads exactly as before. What changes is the model's behavior, and its fingerprint.

In your own words
Someone sends you a file of model weights and nothing else. In your own words, what else do you need before you can run it, and why?

Write a sentence or two, then compare it with a good answer in the lesson.

In production: real checkpoint files

Purpose. The calls an engineer uses to list, load and check a real checkpoint, and where this sits among the course's edits.

Where this shows up in an engineer's week

You open a downloaded model before you trust it: list its tensor names and shapes, check the count against the model card, and compare a fingerprint with the one the publisher lists. Prefer a header-plus-bytes file over a pickle for anything from outside your team.

Goes deeper in

In your own words
In your own words: what does the header of a model file hold, and why can't the file do without it?

Write a sentence or two, then compare it with a good answer in the lesson.

Practice what you just read

  • 4 code examples you can edit and run
  • a practice exercise that checks your code
  • a 5-question quiz
  • 9 review cards for spaced repetition

Try a quiz question

What is a model checkpoint, as stored?

  1. A set of named arrays of numbers, each with a shape
  2. The model's source code, compiled
  3. A copy of the text the model was trained on
  4. One long list of weights with no structure

Answer it at the end of the lesson to see if you're right, and why.

Before this lesson

Go deeper, if you like

Optional lessons that build on this one. They never block a phase or a certificate.

Keep learning

Where this lesson leads.

575 lessons in thirteen phases. 176 are free without an account, and a free account opens the rest. See every lesson.

Phase 6 · about 35 hours of study

Modern LLM engineering

Post-training, fine-tuning, serving and safety 48 lessons 2 free
  1. Base models vs assistants FreeWhat post-training adds to a pretrained model.30 min
  2. Supervised fine-tuningTeach behavior from example conversations.40 min
  3. Instruction and preference dataThe datasets that shape assistant behavior.30 min
  4. RLHFReward models and reinforcement learning from human feedback.40 min
  5. DPO and direct preference methodsPreference training without a separate reward model.40 min
  6. Constitutional AITraining with AI feedback guided by written principles.35 min
  7. Training reasoning modelsReinforcement learning on verifiable problems.40 min
  8. Prompting vs RAG vs fine-tuningPick the cheapest approach that works.30 min
  9. LoRAFine-tune a big model by training small low-rank updates.40 min
  10. Fine-tune an open modelRun a real fine-tune and evaluate the result.45 min
  11. DistillationTrain a small model to imitate a large one.35 min
  12. Tuning an embedding model for retrievalWhen search fails on your own vocabulary: train an adapter with a contrastive loss on question and passage pairs, test on held-out passages, use batch size and hard negatives, and measure what tuning costs elsewhere.45 min
  13. QuantizationStore weights in fewer bits to run models cheaply.35 min
  14. Quantization in practice: zero points, calibration and formatsScale and zero point, per-channel scales, calibration sets, error on a layer's output, quantization-aware training and the file formats you meet at work.35 min
  15. Serving modelsBatching, throughput and latency in production.35 min
  16. One request through a serving stack: latency and costFollow one request through queue, prefill, a prefix cache, decode and the stream, and price a token from a GPU's hourly cost.35 min
  17. Speculative decodingDraft with a small model, verify with a big one.35 min
  18. Running open models locallyDownload, quantize and run a model on your own machine.30 min
  19. Will it fit? Memory for serving and fine-tuningWeights, KV cache, runtime and adapter states added up for a model card and a GPU, with a calculator.30 min
  20. InterpretabilityLooking inside models to see what they compute.40 min
  21. Confident and wrongWhy a model answers with the same assurance whether it is right, wrong or asked about something that does not exist.30 min
  22. Why it can't spell or count lettersThe model sees token IDs, and an embedding learned from usage carries nothing about spelling.25 min
  23. Copying from the promptIn-context learning as a two-head copying circuit: the base tiny GPT cannot copy a repeated pattern, a model trained on repeats grows an induction head and can.30 min
  24. Why temperature changes the answerThe same prompt at 0, 0.7 and 1.5: deterministic loops, plausible variety, broken grammar, measured on a real model.25 min
  25. Why long prompts diluteAttention is a budget shared by every token, so a fact far from the question loses its share; measured, with the cliff beyond the trained window.25 min
  26. Why it never says "I don't know"A chat model answers every request because its fine-tuning data always did; preference training adds flattery; how to build abstention in.25 min
  27. Benchmarks and their limitsWhat leaderboards measure, and what they miss.38 min
  28. Alignment and safetyMaking capable models behave as intended.35 min
  29. Evaluating agentsMeasure multi-step, tool-using behavior.35 min
  30. Reading AI papersGet the idea out of a research paper in 30 minutes.30 min
  31. Capstone: a tuned, evaluated assistantFine-tune, evaluate and deploy a specialist assistant.45 min
  32. Weight-space programming: what it is, and what has been shown Free OptionalA language model reads and writes another network's weights with no training loop: the published experiments, their limits and the criticism, and one edit you make by hand.30 min
  33. Anatomy of a checkpoint OptionalA model file is a set of named tensors: count them, find the ones that write to the residual stream, and save one to bytes and back.35 min
  34. Reading weights without running the model OptionalSingular values, and an attention head's token-to-token circuit, read from the matrices alone and then checked against a measurement.35 min
  35. Writing weights by hand OptionalSet a small network's 55 weights so it catches every ball in a paddle game, the way a program would be written, and meet compiled transformers.40 min
  36. Edits are deltas: task vectors, patches and hashes OptionalSubtract a base from a fine-tune and the edit becomes an object: scale it, take it away, ship it as a patch, and prove by hash what was applied.35 min
  37. Merging models OptionalAverage two fine-tunes, add their task vectors, try SLERP, TIES and DARE, measure the interference, and compare with a model trained on both tasks.40 min
  38. Low-rank edits OptionalCut a fine-tune's change down to its largest directions with the SVD: how few a behavior needs, and how to pull an adapter out of a delta.35 min
  39. Directions: steer the run or edit the weights OptionalFind a behavior's direction in the residual stream, add it at run time, project it out of the weights, and see the effect change from input to input.40 min
  40. Editing one fact OptionalA rank-one change to one matrix rewrites what a product is made from; then reliability, generalization, locality, and what breaks after many edits.40 min
  41. The editor's harness OptionalWhat an LLM that edits weights is given and what it is denied: weights as text and their cost in tokens, a sandbox, a budget of forward passes, and rules the harness enforces.40 min
  42. An LLM reads a network's weights OptionalSix recorded sessions: an LLM is handed 1,315 weights as text and asked what the network was trained to do. Score each answer against the network, and study one it got wrong.40 min
  43. An LLM fixes a model's weights OptionalFind a tiny GPT's loop by hand, then replay recorded sessions in which an LLM hunts for it with ten forward passes, and measure every fix on held-out questions.45 min
  44. An LLM writes a network's weights OptionalFive recorded sessions: an LLM writes every weight of a paddle network from the game's source and one sentence. Score each against its specification, test its design claims, and edit one by hand.40 min
  45. Did it work? Testing an edit OptionalReview a patch for a tiny GPT that can't stop talking: held-out questions, a paired comparison, a same-size control, and what the edit cost.40 min
  46. The published edit, on a real model OptionalRead the edit published for an open model of 870 million weights, apply and verify one in the same form, see what 16-bit and 4-bit storage do to a fix, and run the real thing from a notebook.45 min
  47. Safety, licenses and provenance OptionalBefore a custom model is released: trace its lineage by hash, work out what its parents' licenses pass on, see what an edit can do to a safeguard, and write its card.40 min
  48. Capstone: ship a custom model OptionalSet release gates, then diagnose, edit, measure and document a tiny GPT with a fault no lesson has fixed, and write the record a stranger could check.45 min
Part of a free course 17 lessons

Creating Custom LLMs: Editing Open Weights Using Weight-Space Programming

Read a model's weights, change them by hand and judge an edit someone else made: deltas, merging, low-rank edits, directions and fact edits on a tiny GPT in your browser. Then replay recorded sessions of an LLM reading, fixing and writing weights, check the published edit of a real open model, and ship a model of your own with its patch, verdict and card. Every number is printed by the lesson's own code, and the method's limits are taught with it.

Never trained an AI? Teach a small one to write, right in your browser. It takes about 20 seconds and needs no account. Teach it to write