train-llm-from-scratch 딥다이브
— 내 GPU 한 장으로 밑바닥부터 LLM 만들기

1프로젝트 한줄 요약

이 레포가 무엇을 하는 물건인가.

조금 더 풀어볼게요. LLM (Large Language Model, 대규모 언어 모델)은 ChatGPT처럼 다음에 올 단어를 계속 예측하며 문장을 만들어내는 인공지능입니다. 이 레포는 그 LLM의 핵심 뼈대인 Transformer를 from scratch(밑바닥부터), 즉 남이 만든 모델 클래스를 가져다 쓰지 않고 PyTorch의 기본 텐서 연산만으로 처음부터 조립합니다.

저자(Fareed Khan)는 먼저 셰익스피어 텍스트로 230만 파라미터 모델을 만들어 봤지만 출력이 횡설수설했고, "구조를 더 단순하게 + 데이터는 더 다양하게" 바꿔보니 1,300만 파라미터부터 비로소 맞춤법과 문장 부호가 맞는 글이 나오기 시작했다고 합니다. 그 경험을 그대로 코드와 글로 정리한 게 이 저장소예요.

2왜 주목받는가

트렌딩 이유 · 비슷한 자료 대비 강점.

"나만의 LLM 만들기" 글은 인터넷에 차고 넘칩니다. 그런데 대부분은 허깅페이스 라이브러리의 model = AutoModel.from_pretrained("gpt2") 한 줄로 이미 다 만들어진 모델을 불러올 뿐, 그 안에서 무슨 일이 일어나는지는 가려져 있죠. 이 레포가 뜨는 이유는 정확히 그 반대를 하기 때문입니다 — 어텐션 한 줄, MLP 한 줄까지 전부 직접 보여주고, README가 사실상 한 편의 친절한 강의 노트입니다.

또 하나의 매력은 현실적인 교훈을 솔직하게 담은 점입니다. 저자는 "무조건 크게 만들면 좋아진다"는 환상을 깹니다. 깊이가 얕은 채로 20억 파라미터로 키웠더니 오히려 데이터를 통째로 외워버리는 overfitting(과적합)이 나고, 짧고 단순한 맥락에선 1,300만 모델이 더 말이 되는 글을 쓰더라는 거죠. "작지만 한 가지 일을 잘하는 모델"의 가능성을 보여줍니다.

3기술 스택 전체 지도

학습 파이프라인을 떠받치는 도구들 한눈에.

이 프로젝트는 화면(프론트엔드)이나 서버가 없는 순수 머신러닝 학습 코드입니다. 그래서 스택도 "데이터를 어떻게 가져와 → 어떻게 숫자로 바꿔 → 어떻게 학습하나"의 한 줄기로 구성돼요.

4아키텍처 심화 분석

데이터 한 조각이 들어가서 "다음 단어 예측"이 나오기까지.

먼저 숲(전체 그림)부터 봅니다. 이 프로젝트는 크게 두 단계예요. ① 텍스트를 숫자로 바꿔 통(HDF5)에 담는 데이터 파이프라인, ② 그 숫자를 먹여 모델을 학습시키는 Transformer. 아래 그림은 그 전체 여정입니다.

이제 나무(흐름 한 줄기)를 손으로 따라가 봅시다. 토큰 한 배치가 들어가 loss(오답 점수) 하나가 나오기까지의 해피 패스입니다. 핵심 줄만 짚을게요.

① 입력 준비 — get_batch_iterator가 HDF5에서 토큰을 뭉텅이로 꺼내, 입력 xb와 "한 칸 뒤로 민" 정답 yb를 만듭니다. 모델의 과제는 늘 "지금까지를 보고 바로 다음 토큰 맞히기"예요.

xb = random_samples[:, :context_length]      # 입력: 0 ~ T-1번째 토큰
yb = random_samples[:, 1:context_length+1]   # 정답: 1 ~ T번째 (한 칸 밀림)

② 임베딩 — 토큰 ID를 의미 벡터로 바꾸는 token_embed와, "몇 번째 자리인가"를 알려주는 position_embed를 더합니다. 어텐션은 순서 감각이 없어서 위치 정보를 따로 주입해야 하거든요.

x = self.token_embed(idx) + self.position_embed(pos_idxs[:T])

③ Block을 N번 통과 — 핵심입니다. 각 블록은 똑같은 두 동작을 반복해요. 먼저 Multi-Head Attention으로 "이 단어가 다른 어떤 단어를 봐야 하나"를 계산하고, 그 다음 MLP로 정보를 더 가공합니다. 둘 다 잔차 연결(원본을 더해 돌려줌)로 감싸죠.

x = x + self.attn(self.ln1(x))   # 어텐션 + 잔차(원본 더하기)
x = x + self.mlp(self.ln2(x))    # MLP + 잔차

④ 예측과 채점 — 마지막 lm_head가 각 자리마다 "다음에 올 토큰별 점수(logits)"를 5만여 개 뱉고, cross_entropy가 정답 yb와 비교해 loss 하나로 요약합니다. 이 loss를 줄이는 방향으로 가중치를 조금씩 미는 게 학습이에요.

곁가지(평가 루프, 학습률 감쇠, 부분 저장 등)는 여기선 접어둡니다 — 일의 95%는 위 네 단계가 합니다.

참고로 멀티헤드 어텐션은 단순히 어텐션을 여러 개 병렬로 돌리는 구조입니다. 각 "헤드"가 서로 다른 관계(문법·의미·거리 등)를 따로 보고, 결과를 옆으로 이어 붙여요.

5디렉토리 구조 해부

어떤 폴더가 무슨 일을 하나.

구조가 아주 단정합니다. 모델 부품은 src/models/, 실행 스크립트는 scripts/, 설정값은 config/ 한 곳에 모여 있어 길을 잃을 일이 없어요. ※ 아래 트리는 2026-06-02 작성 시점(프리트레인 범위)을 기준으로 하며, 현재 레포에는 SFT·DPO·PPO·GRPO 등 포스트트레이닝 파이프라인 스크립트(train_sft.py·train_dpo.py·train_ppo.py·train_grpo.py 등)와 configs/ 디렉토리가 추가로 포함되어 있습니다.

6학습 포인트 (기술별)

이 레포에서 진짜로 배워 갈 것 + 어디를 보면 되는지.

k = self.key(x); q = self.query(x)            # 키·쿼리 만들기
attn = q @ k.transpose(-2,-1) / math.sqrt(C)  # 점수 = 쿼리·키 내적
attn = attn.masked_fill(tril==0, float('-inf'))# 미래 가리기(코절 마스크)
attn = F.softmax(attn, dim=-1)                # 점수 → 확률
out  = attn @ self.value(x)                   # 확률로 밸류 가중합

text = data['text'] + "<|endoftext|>"          # 글 끝 표시 토큰 추가
encoded = enc.encode(text, allowed_special={'<|endoftext|>'})
dataset.resize(dataset.shape[0] + len(encoded), axis=0)  # 통 늘리고
dataset[start:end] = encoded                  # 이어 담기

_, loss = model(xb, yb)        # 1) 예측 + loss
optimizer.zero_grad(set_to_none=True)  # 2) 이전 기울기 비우기
loss.backward()                # 3) 역전파(기울기 계산)
optimizer.step()               # 4) 가중치 한 걸음 갱신

logits = self(idx[:, -context_length:])[0][:, -1, :]  # 마지막 자리 예측
probs = F.softmax(logits, dim=-1)
idx_next = torch.multinomial(probs, num_samples=1)    # 확률대로 한 개 뽑기
idx = torch.cat((idx, idx_next), dim=1)               # 뒤에 붙이고 반복

7하드웨어 / 시스템 요구사항

돌리려면 무엇이 필요한가 — 특히 GPU.

이 프로젝트의 가장 현실적인 제약은 GPU 메모리입니다. 1,300만 파라미터 모델은 거의 모든 게이밍/무료 GPU에서 돌지만, 20억 파라미터는 24GB 이상급에서만 가능합니다. README가 친절하게 GPU별 표를 제공해요.

8직접 해볼 수 있는 실습 과제

손에 익히는 단계 — 쉬운 것부터 차례로.

python scripts/data_download.py --train_max 1   # 데이터 1개만
python scripts/data_preprocess.py --max_data 1000
python scripts/train_transformer.py
python scripts/generate_text.py --model_path models/your_model.pth --input_text hi

9관련 기술 심화 학습 로드맵

한 주씩 따라가는 4주 계획.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: FareedKhan-dev/train-llm-from-scratch
• 핵심 논문: Attention is All You Need (Vaswani et al., 2017)
• 학습 데이터: The Pile (uncopyrighted) on HuggingFace
• 토크나이저: openai/tiktoken
• 비교 학습용: karpathy/nanoGPT — 같은 목적의 대표 레포