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
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?
30
2
1
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.
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 ifnot 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)
3072
3168
9312
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".
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?
Multiplies the stream by it
Adds it to the stream, so earlier information is kept
Replaces the stream with it
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?
Neither: it is a LayerNorm
Both: every matrix reads and writes
A writer: its 32 outputs are added to the stream
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
defpack(state):
header, chunks, at = {}, [], 0for 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)
defunpack(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()))
96
24
3
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
defpack(state):
header, chunks, at = {}, [], 0for 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)
defread_tensor(blob, name):
returnNone
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")
exceptExceptionas 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?
No: any change to a weight breaks the file's header
Only if the model is rebuilt with a larger width
Yes: the names and shapes are unchanged, and only values differ
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.
11DistillationTrain a small model to imitate a large one.35 min
12Tuning 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
13QuantizationStore weights in fewer bits to run models cheaply.35 min
23Copying 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
24Why 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
25Why 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
26Why 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
32Weight-space programming: what it is, and what has been shownFreeOptionalA 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
33Anatomy of a checkpointOptionalA 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
34Reading weights without running the modelOptionalSingular values, and an attention head's token-to-token circuit, read from the matrices alone and then checked against a measurement.35 min
35Writing weights by handOptionalSet 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
36Edits are deltas: task vectors, patches and hashesOptionalSubtract 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
37Merging modelsOptionalAverage 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
38Low-rank editsOptionalCut 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
39Directions: steer the run or edit the weightsOptionalFind 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
40Editing one factOptionalA 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
41The editor's harnessOptionalWhat 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
42An LLM reads a network's weightsOptionalSix 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
43An LLM fixes a model's weightsOptionalFind 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
44An LLM writes a network's weightsOptionalFive 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
45Did it work? Testing an editOptionalReview 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
46The published edit, on a real modelOptionalRead 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
47Safety, licenses and provenanceOptionalBefore 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
48Capstone: ship a custom modelOptionalSet 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
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.
See the course →
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