GitHub에서 LLM을 다루는 저장소는 넘치지만, GPT의 forward부터 SFT/DPO까지, 각 층을 끝까지 분해해 놓은 프로젝트는 손에 꼽는다. 그중 가장 완성도 높은 사례가 rasbt/LLMs-from-scratch다. 저자는 Lightning AI의 연구 과학자 Sebastian Raschka로, 《Machine Learning with PyTorch and Scikit-Learn》의 저자이기도 하다. 이번 신간 《Build a Large Language Model (From Scratch)》는 Manning에서 출판됐고(ISBN 9781633437166), 이 저장소가 그 책의 공식 코드 저장소다.
이 프로젝트가 푸는 문제
LLM 내부 동작을 제대로 이해하고 싶은 사람이라면 누구나 같은 벽에 부딪힌다.
- HuggingFace 위주의 튜토리얼이 너무 많아서
AutoModelForCausalLM.from_pretrained한 줄이면 끝나지만, 그 안에서 행렬이 실제로 뭘 계산하는지는 알 수 없다. - 논문을 그대로 옮겨적기만 하는 글들이 많고, attention 수식만 베끼고 코드 구현은 건너뛴다.
이 저장소는 더 직관적인 접근을 택한다. PyTorch로 약 400줄 분량의 코드를 작성해서 token embedding → multi-head attention → LayerNorm → pretraining → SFT까지 전 과정을 구현한다. 모든 코드는 Jupyter Notebook으로 정리돼 있으며, 어떤 nn.Module도 추상화 없이 바닥까지 분해돼 있다.
한 바퀴 돌고 나면 최소한 다음 질문에 답할 수 있어야 한다. (1) 왜 d_out % num_heads == 0이어야 하는가, (2) causal mask를 상삼각 행렬로 어떻게 구현하는가, (3) SFT와 pretraining의 loss는 어디서 갈라지는가, (4) DPO의 implicit reward를 reference 모델에서 어떻게 뽑아내는가.
사용 방법
저장소를 clone하면 챕터별 Jupyter Notebook이 순서대로 들어 있다.
ch02_text_data.ipynb— tokenizer + sliding window 데이터셋ch03_coding_attention_mechanisms.ipynb— self-attention 4종 변형ch04_implementing_gpt_model.ipynb— TransformerBlock + GPTModelch05_pretraining_on_unlabeled_data.ipynb— pretrainingch06_finetuning_for_classification.ipynb— 분류 fine-tuningch07_instruction_finetuning.ipynb— SFTch08_aligning_models_with_human_feedback.ipynb— DPO/PPO
각 챕터 끝에는 exercises가 붙고, 정답은 exercise-solutions.ipynb에 있다. 환경 설치는 README가 uv를 권장한다.
가장 빠르게 결과를 보고 싶다면 Colab 무료 GPU에서 ch04_implementing_gpt_model.ipynb를 열고, 124M 파라미터의 GPT-2 스켈레톤 모델을 학습시키면 된다. 몇 시간이면 텍스트를 이어 쓰는 데모가 돌아간다. 전체 챕터를 다 돌리면 대략 일주일 정도 잡으면 된다.
동작 구조
코드 전체는 아래에서 위로 4개 계층으로 나뉜다.
- ch02 — 데이터 계층:
tiktoken으로 BPE tokenization을 처리하고, sliding window으로 긴 텍스트를context_length크기의 학습 샘플로 자른다. - ch03 — Attention 계층: naive self-attention → causal mask 적용 → multi-head →
torch.nn.functional.scaled_dot_product_attention을 쓴 PyTorch 내장 버전까지 단계별로 구현한다. 각 버전에서 동일한 toy 입력을 넣어 출력을 비교한다. - ch04 — 모델 계층:
TransformerBlock(LayerNorm + MHA + FFN + residual 연결 포함)과GPTModel을 구현한다. 설정은 GPT-2 124M과 정확히 일치한다 —d_model=768, n_heads=12, n_layers=12— OpenAI의 공식 가중치를 그대로 로드할 수 있다(ch05). - ch07 + ch08 — 정렬 계층: SFT는 instruction-response 형식 데이터를 사용하고, DPO는 reference 모델과 policy 모델의 log-ratio 차이로부터 implicit reward를 계산한다.
핵심 설계 포인트는 모든 행렬 차원이 GPT_CONFIG_124M이라는 dict에서 일괄 관리된다는 점이다. shape이 맞지 않으면 코드가 아예 실행되지 않으므로, GPT-2 논문의 Table 2와 설정을 1:1로 대조하며 검증하기 쉽다.
아래는 ch04_implementing_gpt_model.ipynb에 있는 MultiHeadAttention의 핵심 부분이다. 30줄도 안 되는 코드에 Q/K/V 분할, scaled dot-product, causal mask, dropout이 모두 들어 있다.
import torch
import torch.nn as nn
class MultiHeadAttention(nn.Module):
def __init__(self, d_in, d_out, context_length, dropout, num_heads, qkv_bias=False):
super().__init__()
assert d_out % num_heads == 0, "d_out must be divisible by num_heads"
self.d_out = d_out
self.num_heads = num_heads
self.head_dim = d_out // num_heads
self.W_query = nn.Linear(d_in, d_out, bias=qkv_bias)
self.W_key = nn.Linear(d_in, d_out, bias=qkv_bias)
self.W_value = nn.Linear(d_in, d_out, bias=qkv_bias)
self.out_proj = nn.Linear(d_out, d_out)
self.dropout = nn.Dropout(dropout)
self.register_buffer(
"mask", torch.triu(torch.ones(context_length, context_length), diagonal=1)
)
def forward(self, x):
b, num_tokens, d_in = x.shape
keys = self.W_key(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
queries = self.W_query(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
values = self.W_value(x).view(b, num_tokens, self.num_heads, self.head_dim).transpose(1, 2)
attn_scores = queries @ keys.transpose(2, 3)
attn_scores.masked_fill_(self.mask.bool()[:num_tokens, :num_tokens], -torch.inf)
attn_weights = torch.softmax(attn_scores / self.head_dim**0.5, dim=-1)
attn_weights = self.dropout(attn_weights)
context_vec = (attn_weights @ values).transpose(1, 2).contiguous().view(b, num_tokens, self.d_out)
return self.out_proj(context_vec)
이 셀을 실행하기 전에 입력 텐서를 준비한다.
x = torch.randn(2, 6, 768) # batch=2, tokens=6, d_model=768
mha = MultiHeadAttention(768, 768, context_length=1024, dropout=0.1, num_heads=12)
mha(x).shape
# torch.Size([2, 6, 768])
shape이 맞게 떨어지면 행렬 분해가 제대로 된 것이다. Q/K/V를 (b, tokens, d_out)에서 (b, tokens, num_heads, head_dim)으로 reshape한 뒤 transpose(1, 2)로 차원을 바꾸는 부분이 multi-head를 병렬로 계산하는 핵심 동작이다. 논문의 그림을 열 번 보는 것보다 이 셀을 한 번 돌려보는 게 낫다.
강점과 한계
좋은 점:
- 추상화를 일절 숨기지 않는다.
nn.TransformerEncoder나AutoModel같은 도움은 없고, 모든 층을 직접 구현한다. - 동반 출판된 책이 Manning에서 나온 만큼 챕터 구조와 편집 품질이 일반 저장소보다 훨씬 엄격하다. 챕터 말미에 "Summary" + "Exercises"라는 표준 학술 포맷이 따라붙는다.
- Qwen3 / DeepSeek 가중치 로드 챕터가 추가돼 최근 흐름을 따라잡았고, LoRA와 KV cache 구현도 함께 들어 있다.
아쉬운 점:
- Jupyter 중심이라 production 라이브러리처럼
pip install해서 바로 호출하는 식으로는 쓸 수 없다.from llms_from_scratch import GPTModel같은 API는 존재하지 않으니, 코드를 직접 옮겨와야 한다. - 124M 모델은 최신 LLM 기준으로 보면 작아서 ChatGPT 수준 결과는 당연히 나오지 않는다. 목적은 교육이다. 이 저장소로 production 모델을 학습하려는 시도는 맞지 않다.
- RLHF/PPO 챕터(ch08)는 pretraining 파트보다 얕다. DPO 코드는 제공되지만 이론적 유도 과정이 간략해서, alignment 엔지니어링을 제대로 하려면 HuggingFace TRL 문서나 Christiano 등 원 논문을 따로 봐야 한다.
직접 돌려본 기록
저장소를 clone한 뒤 ch04의 gpt_train.ipynb를 열어 Colab T4에서 124M 모델을 5k step 학습시켰다. loss가 약 11에서 3.5까지 떨어졌다. "Once upon a time"으로 프롬프트를 넣으니 동화开头를 자연스럽게 이어 썼지만, 내용은 전부 지어낸 이야기였다(124M 모델에서는 정상이다).
ch03 말미의 attention 시각화가 특히 인상적이었다. 1층에서는 인접 토큰끼리 align하는 패턴("the"가 "cat"에 주목하는 식의 국소 의존성)을 학습하고, 깊은 층에서야 장거리 의존성이 나타난다. BERTology 논문의 관찰과도 일치한다. 이 부분은 논문만 봐서는 감이 안 잡히고, attention map을 눈으로 직접 봐야 transformer가 왜 동작하는지 체감된다.
또 하나 흥미로웠던 점은, ch07의 SFT 데이터로 instruction-data.json(Alpaca 스타일)을 사용한다는 것이었다. 데이터 양은 많지 않지만 124M 모델이 instruction format을 익히기에는 충분했고, loss가 pretraining 단계보다 빠르게 떨어져서 2k step이면 안정됐다. 소형 모델 + 고품질 데이터 조합의 전형적인 사례다.
이런 사람에게 권한다
맞는 사람:
- transformer 내부에서 실제로 무슨 계산이 일어나는지 알고 싶은 현업 엔지니어 — 이 저장소를 끝까지 읽으면 어떤 attention 구현이든 코드 리뷰할 수 있다.
- 면접에서 attention 수식을 즉석에서 유도하고 싶은 사람 — 이 저장소가 그 답이다.
- ML 입문을 마치고 LLM 내부로 넘어가는 과도기 단계에 있는 사람. PyTorch 기초는 있지만 LLM 내부는 아직 손대지 않았다면 딱 좋다.
맞지 않는 사람:
- 바로 production급 모델이 필요한 사람 — HuggingFace로 가면 된다.
- 7B 이상 모델 학습을 돌리고 싶은 사람. 이 저장소는 교육용이라 FSDP / ZeRO / tensor parallelism 같은 분산 학습은 다루지 않는다.
- PyTorch 기초가 전혀 없는 사람. 공식 60분 입문 튜토리얼을 먼저 한 바퀴 돌고 오는 편이 좋다.
의존성은 PyTorch + Python이 전부고, 서드파티는 tiktoken / datasets / wandb 세 개뿐이다.