Textbooks Are All You Need

In plain words

The paper asks whether a small language model can learn to write Python if its training text is much better, rather than much bigger. The authors build a model with 1.3 billion parameters, which is tiny next to the competition, and train it on a curated mix: code from the web that a classifier judged useful for learning, plus textbook-style lessons and practice problems written by another language model.

The idea is that a good textbook teaches clearly, stays self-contained and covers a balanced set of topics, while a random pile of code files does not. The model first learns from the textbook-like material and then gets a short round of practice exercises that teach it to finish functions from their descriptions.

The result is a small model that scores well on two standard Python-writing tests. The numbers come from the authors and depend on their own evaluation setup, so treat them as the authors' claims. Because the training data was partly generated by a larger model, the paper also checks whether the good scores come from memorised test-like material.

TL;DR

• phi-1 is a 1.3B decoder-only Transformer for Python, trained on a small, filtered and synthetic corpus §2 tab. 1.
• Training has two stages: pretraining on CodeTextbook (about 7B tokens), then fine-tuning on CodeExercises (under 200M tokens) §2.
• Author-reported: 50.6% pass@1 on HumanEval and 55.5% on MBPP [abstract] tab. 1.
• Data quality, not size, is the central claim; the paper's ablations are small (350M-parameter models) and mostly narrow.
• No official code is linked; the training recipe is only partly specified (see Pitfalls).

Problem

Code models were mostly scaled up, with large amounts of raw code from repositories and web sources. The authors argue that these sources are noisy: many snippets are not self-contained, many are boilerplate, algorithmic logic is often buried, and topics are unevenly covered §2. They ask whether a small model trained on carefully chosen data can match or beat larger models trained on much more data §1 tab. 1. The paper assumes that HumanEval-style function-from-docstring tasks are the target §1.

Method

Data pipeline. The authors build three datasets §2:

1. Filtered code-language data (about 6B tokens). Start with the Python subset of the deduplicated The Stack and StackOverflow, which together hold over 35M files or samples and over 35B tokens §2.1. GPT-4 rates the educational value of about 100k samples, using a prompt that asks it to "determine its educational value for a student whose goal is to learn basic coding concepts" §2.1. A random forest is trained on those ratings, using the output embedding of a pretrained CodeGen-Mono model as features; the forest then scores the full pool §2.1. The score threshold used to keep files is not stated.
2. Synthetic textbooks (under 1B tokens). GPT-3.5 writes Python textbooks that mix prose with code snippets. Diversity comes from constraints on topic and target audience §2.2. The paper shows an example chapter §2.2.
3. CodeExercises (under 180M tokens; about 880K exercises). GPT-3.5 writes exercises: each one is a function docstring that a model must complete, with a reference solution §2.2 fig. 2. Diversity is elicited by constraining the function names §2.2. The authors decontaminate this set against HumanEval §2.2 §5.

Architecture §2.3. A decoder-only Transformer that uses FlashAttention multi-head attention. Attention and MLP run in parallel within each block, as in CodeGen, PaLM and GPT-NeoX §2.3. Rotary position embeddings with a rotary dimension of 32 are used §2.3. The tokenizer is the one from codegen-350M-mono §2.3. Fill-in-the-middle and multi-query attention are deliberately not used §2.3.

Training §2.3. Next-token prediction on 2048-token windows. Documents are concatenated into one array with an end-of-text token between files. Training uses fp16, AdamW, a linear-warmup then linear-decay schedule, and attention and residual dropout of 0.1 §2.3. Pretraining produces phi-1-base; fine-tuning on CodeExercises produces phi-1 §2.3.

Small comparison model. phi-1-small has 350M parameters and the same pipeline §1 §2.3.

Filtering effect at 350M §2.1 fig. 1. Training on unfiltered Stack and StackOverflow saturates at 12.19% HumanEval after 96k steps (about 200B tokens). Training on the filtered subset reaches 17.68% after 36k steps. Adding the synthetic textbooks reaches 20.12% (the value in fig. 1).

Fine-tuning effects §3. The authors report qualitative gains beyond the exercise distribution: better handling of instructions with logical relationships §3.1, and better use of external libraries such as plotting and other packages §3.2 fig. 2. These are demonstrations on selected prompts, not benchmark results.

Evaluation uses HumanEval and MBPP pass@1 §1 tab. 1, a GPT-4-graded test on 50 new problems §4 tab. 2, and a pruning study that removes CodeExercises items similar to HumanEval §5 tab. 3.

# Data pipeline  [§2.1] [§2.2]
# Input:  Python samples from The Stack and StackOverflow (35M, 35B tokens)
# Output: filtered corpus (~6B tokens), textbooks (<1B), exercises (<180M)

def filter_web_code(samples, rated_subset, gpt4_ratings):
    # Train a classifier on GPT-4 quality ratings of about 100k samples  [§2.1]
    # Features are CodeGen-Mono embeddings  [§2.1]
    classifier = fit_random_forest(
        embed_codegen(rated_subset),
        gpt4_ratings,
    )
    # Keep samples the classifier rates as educational; threshold not stated  [§2.1]
    return [s for s in samples if classifier.keeps(s)]


def generate_textbooks(topics, audiences, llm):
    # Constrain each chapter by topic and target audience  [§2.2]
    # Prompt wording and sampling settings are not published  [§6] [§1]
    for topic, audience in topics_and_audiences(topics, audiences):
        yield llm(textbook_prompt(topic, audience))


def generate_exercises(function_names, llm):
    # One docstring plus reference solution per function name  [§2.2]
    # Function names are the diversity lever  [§2.2]
    for name in function_names:
        yield llm(exercise_prompt(name))

# Pretraining on CodeTextbook, then fine-tuning on CodeExercises  [§2.3]
# Shapes: batch (1024, 2048) tokens per step during pretraining

def pretrain(model, textbook_tokens):
    # Run to 36,000 steps but keep the checkpoint at step 24,000  [§2.3]
    for step in range(24_000):
        batch = next_batch(textbook_tokens, batch=1024, length=2048)
        loss = next_token_loss(model, batch)
        # AdamW, peak lr 1e-3, 750 warmup steps, weight decay 0.1  [§2.3]
        update(model, loss, lr=lr_at(step))
    return model


def finetune(base_model, exercise_tokens):
    # Batch 256, peak lr 1e-4, 50 warmup steps, weight decay 0.01  [§2.3]
    for step in range(6_000):
        batch = next_batch(exercise_tokens, batch=256, length=2048)
        loss = next_token_loss(base_model, batch)
        update(base_model, loss, lr=lr_at(step))
        # Checkpoint every 1000 steps; the paper keeps the best one  [§2.3]
        save_if_best(base_model, step)
    return best_checkpoint()

Key equations: none; the paper has no numbered equations. The similarity measures are described in words: L2 distance on CodeGen-Mono 350M embeddings, and an edit distance between abstract syntax trees, reported as a match rate τ §5.2.

Hyperparameters

Results

Author-reported. Setup: HumanEval and MBPP pass@1 for a 1.3B model trained on about 7B tokens plus 180M fine-tuning tokens on 8 × A100 §2.3 tab. 1. Baseline numbers come from each model's own report ("self-reported whenever available") tab. 1. The evaluation decoding setup (sampling, temperature, number of samples) is not stated.

Main table, reproduced from tab. 1. The paper's 1.3B model is in the last row; the other rows are the authors' comparison.

tab. 1. The authors note that phi-1 beats every listed model except GPT-4 on both benchmarks, and that WizardCoder is higher on HumanEval but lower on MBPP tab. 1.

Other reported numbers (author-reported; all from the paper's text):

GPT-4-graded test, 50 new problems tab. 2. Scored by GPT-4 on a 0–10 scale, shown here as a percentage.

tab. 2. The ranking matches HumanEval tab. 2 §4.

Decontamination and pruning tab. 3 §5. Pass@1 on HumanEval, split into problems with a close match in CodeExercises ("similar") and problems without one ("non-similar"). Problem counts: 164 in total.

tab. 3. Pruning removes between 42.5K and 354K of the 879.5K CodeExercises problems as τ falls from 0.95 to 0.8 §5.2. The authors conclude that the retrained model still beats StarCoder-Prompted, so the boost is not only contamination §5.

Sizes and compute fig. 1 §2.3. The phi-1 checkpoint is reported after 51B tokens and 770 GPU hours; the 76B-token Stack+ comparison took 1090 GPU hours fig. 1.

Paper vs code

No official code. The arXiv text links no repository or project page. Searching GitHub for "phi-1" under the Microsoft organisation found no phi-1 repository, and searching for the paper title returned only third-party reimplementations, which are not used here. The paper says the model is released for use and evaluation §1, but it names no repository, so nothing from a release is recorded.

Internal inconsistencies in the paper, each with both citations:

• Token count: the introduction gives "8 passes over 7B tokens (slightly over 50B total)" §1. Section 2.3 gives about 8 epochs of CodeTextbook, "little over 50B" tokens, at step 24,000 §2.3. The figure caption says 51B fig. 1. Using the stated batch and window (1024 × 2048 tokens per step) and step 24,000 gives about 50.3B tokens, consistent with the text. The "8 × 7B = 56B" arithmetic in the introduction does not match, so the 7B figure is probably the unique-token count rather than the epoch size.
• The CodeTextbook size: "less than 7B" §2 versus "about 6B filtered plus under 1B synthetic" §2.1 versus "7B" in tab. 1. These agree in order of magnitude but not exactly.

Pitfalls

• Decoding for pass@1 is not stated. Sampling temperature, number of samples per problem and the pass@k estimator are missing tab. 1 §1. Reproducing the 50.6% needs an assumed setup; treat a different setup as a different experiment.
• Checkpoint selection for fine-tuning uses an unstated criterion. The paper keeps "the best checkpoint (saved every 1000 steps)" §2.3 without naming the metric. If it was the HumanEval score, the reported number is optimistic. The paper does not say.
• The LR schedule's decay horizon is not stated. Pretraining runs to 36,000 steps, but the checkpoint is at 24,000 §2.3. The learning rate at step 24,000 depends on the decay end point, which is not given.
• Exercises cannot be regenerated exactly. The authors omit the synthetic generation details "for proprietary reasons" §1. The GPT-3.5 prompts, the topic and audience lists and the function-name lists are not published §2.2. The paper quotes the textbook and exercise examples but not the prompts that produced them.
• The filter is underspecified. The GPT-4 rating prompt is partly quoted §2.1. The random forest hyperparameters, the feature pooling of CodeGen embeddings, and the score threshold that selects the 6B tokens are not stated.
• GPT-3.5 data has a high error rate. The authors say so §6, which means the synthetic textbooks and exercises carry errors that the model still learns from. The paper argues this is tolerable but does not measure its effect.
• Benchmark sample size is small. HumanEval has 164 problems tab. 3. Each problem is worth about 0.61 percentage points (1/164), so 50.6% corresponds to 83 of 164 solved (derived). The 50-problem GPT-4-graded test §4 is smaller still.
• Baseline numbers are self-reported and not run under one setup. The comparison table says so tab. 1. Use the rows as the authors' claims, not as a controlled ranking.
• Decontamination depends on the AST threshold τ. The n-gram check finds 4 HumanEval items with 13-gram overlap, which the authors call false positives §5.1. The embedding and AST analysis needs a τ that is not fixed in advance §5.2. Table 3 shows that the "similar" group changes with τ.
• Dropout is applied only to attention and residual paths. Embedding dropout is not mentioned §2.3.
• Scope limits the claim. The model is Python-only, depends on prompt wording, and degrades on long prompts app. B. The conclusion lists these as limits §6.
• The architecture is conventional, but the data is the change. The paper itself says so: model architecture and training are "fairly conventional" §2. Do not treat the data pipeline as optional when reproducing.
• Figures are described, not reproduced. Figure 1 shows HumanEval pass@1 for 350M and 1.3B models, across two compute budgets (26B and 76B tokens) and three training sets: standard Stack, CodeTextbook, and CodeTextbook with CodeExercises fig. 1. Figure 2 counts the imports among about 880K CodeExercises items; its plotting code was generated by phi-1 fig. 2.

Lineage

• Builds on: TinyStories (Eldan and Li), which showed that data quality can reshape scaling laws §1; The Stack and StackOverflow as the source pool §2.1; CodeGen as the architecture and tokenizer source §2.3.
• Compared against: the models in tab. 1 and tab. 2, including StarCoder and WizardCoder.
• Superseded by: not stated in the paper or in this wiki.