happy-llm 딥다이브
— 토큰 하나의 예측에서 도구를 배우는 AI까지

1프로젝트 한줄 요약

happy-llm은 텍스트를 숫자로 바꾸는 순간부터, 그 숫자로 다음 단어를 예측하고, 학습한 모델에 검색과 도구를 붙이는 순간까지 연결하는 공개 교육 자료입니다. 중국어 원문 교재와 Python 실습 코드가 함께 있으며, 영어 README도 있습니다.

이 저장소의 학습 목표는 모델을 호출하는 데서 멈추지 않고, 어떤 데이터가 어떤 손실을 통해 모델을 바꾸는지 설명하는 것입니다.

5장의 k_model.py에는 Attention, RoPE, RMSNorm, MLP, 생성 루프가 직접 구현되어 있습니다. 6장에서는 같은 작업을 Trainer와 DeepSpeed에 맡깁니다. 두 구현을 비교하면 학습 프레임워크가 대신 해 주는 일을 구체적으로 이해할 수 있습니다.

이 글을 읽고 답할 수 있어야 할 질문

• 입력 토큰과 정답 토큰을 왜 한 칸씩 어긋나게 만들까요?
• 질문과 답변을 모두 입력하면서, 답변에만 학습 신호를 줄 수 있을까요?
• 문서 검색은 모델의 가중치를 바꾸는 작업일까요?
• 도구가 출력한 문장과 모델이 생성한 문장을 왜 구분해야 할까요?

주요 출발점: 5장 모델 구현, 5장 데이터셋 구현.

2왜 주목받는가

2026-10-23 GitHub Trending의 Jupyter Notebook 일간 3위로 선정되었고, GitHub 기준 스타는 34,523개입니다. 이 순위는 관심의 신호이며, 특정 날짜의 상승 원인이나 교육 효과까지 입증하는 수치는 아닙니다. 관심을 끌 만한 이유는 교육 내용과 소스의 연결에서 찾을 수 있습니다.

2-1. 공식을 읽고 바로 구현을 찾을 수 있다

Attention을 공부했다면 2장의 docs/chapter2/code/transformer.py로, LLaMA 계열의 Decoder를 공부했다면 5장의 k_model.py로 이동할 수 있습니다. 이름만 소개하는 대신 정규화, 위치 정보, 가중치 공유와 같은 부품을 실제 코드에서 만납니다.

README는 LLaMA2를 직접 구현한다고 소개합니다. 소스에서는 모델 이름이 Tiny-K인 교육용 구현을 확인할 수 있습니다. 공식 LLaMA2 가중치를 재현했다는 뜻으로 읽기보다, LLaMA 계열의 핵심 구조를 작은 모델로 학습한다고 이해하는 편이 정확합니다.

2-2. 모델을 만든 다음에 무엇을 하는지도 다룬다

5장은 모델과 학습 루프, 6장은 프레임워크를 사용하는 학습, 7장은 RAG와 도구 호출, 8장은 GRPO·OPD·Search-R1·ReTool을 다룹니다. 특히 8장은 도구를 사용하는 행동이 어떻게 학습 데이터가 되는지까지 연결합니다.

각 장의 구현을 비교하면, 가중치를 바꾸는 학습과 입력에 정보를 더하는 응용의 차이가 선명해집니다.

비교 참고 자료: nanoGPT 공식 저장소, Transformers Trainer 공식 안내, happy-llm README.

2-3. 넓은 교재와 완제품은 평가 기준이 다르다

3기술 스택 전체 지도

일반 웹 서비스의 백엔드·프론트엔드 분리와는 구성이 다릅니다. 계산과 데이터 처리는 Python 스크립트가 맡고, 교재는 정적 문서로 제공됩니다. 사용자와 대화하는 웹 화면은 7장 Agent의 Streamlit 예제에 한정됩니다.

3-1. 백엔드·모델·데이터 처리

출처는 각각 docs/chapter2/code/requirements.txt, docs/chapter5/code/requirements.txt, docs/chapter6/code/requirements.txt, docs/chapter7/RAG/requirements.txt, docs/chapter8/requirements.txt입니다. 표의 숫자는 설치 결과가 아니라 커밋 1e0b3a1에 기록된 의존성 선언입니다.

3-2. 프론트엔드·교재 화면

7장 Agent 의존성에는 RAG와 같은 openai==1.88.0, numpy==2.3.0 외에 wikipedia==1.4.0이 있습니다. React·Vue 앱이나 FastAPI 서비스의 구성으로 해석하면 실제 구조와 어긋납니다.

3-3. 인프라·실행·배포 구성

• 패키지 관리: 장별 requirements.txt 6개. 루트 pyproject.toml·package.json·Cargo.toml·go.mod는 없습니다.
• 학습 실행: 5장은 argparse 기반 스크립트, 6장은 pretrain.sh·finetune.sh와 DeepSpeed JSON 설정을 사용합니다.
• 정적 문서: docs/.nojekyll과 docs/index.html이 있고, README는 GitHub Pages 읽기 주소를 안내합니다.
• 자동화: .github/ISSUE_TEMPLATE/은 있으나 이 커밋에 .github/workflows/, Dockerfile, 통합 테스트·빌드 설정은 없습니다.
• 8장 외부 의존성: deepseek-search는 Git 커밋 6215c8db…을 지정합니다. 원격 모델 연산은 PyTRIO 서비스에 의존합니다.

공통 환경 하나를 만드는 것보다, 배우려는 장의 의존성과 실행 전제를 먼저 확인하는 것이 재현의 출발점입니다.

환경 안내는 2~7장에 Python 3.10·3.11을 권장하고, 8장에는 Python 3.13을 사용한다고 명시합니다. 6장 본문이 설명하는 peft는 6장 의존성 파일에 없습니다. 본문의 LoRA 예제를 따라갈 때 추가 의존성 확인이 필요합니다.

근거: 장별 문서·의존성, 문서 사이트 구성.

4아키텍처 심화 분석

각 장은 서로 다른 실행 예제입니다. 5장에서 만든 체크포인트가 7·8장에 자동으로 연결되는 통합 제품은 아닙니다. 아래 구조도에서 실선은 각 예제 안의 흐름이고, 장 사이의 연결은 공부 순서를 뜻합니다.

[1~4장: NLP / Attention / 모델 계열 / 학습 원리]
                         |
                         v
[5장: 직접 구현]     JSONL 문장 / 대화
                         |
                 Tokenizer + Dataset
                         |
               X / Y / loss_mask 생성
                         |
               Transformer.forward()
                         |
           토큰별 손실 --> 역전파 --> Adam(사전학습) / AdamW(SFT)
                         |
                    .pth 체크포인트

[6장: 프레임워크]    데이터 --> Trainer --> DeepSpeed ZeRO-2

[7장: 응용 예제]     문서 --> 임베딩 --> 검색 --> LLM 답변
                    질문 --> 도구 선택 --> Python 함수 --> 답변

[8장: Agentic RL]    로컬: 문제 / 도구 환경 / 보상 / 궤적 정렬
                         |                       ^
                         v                       |
                    PyTRIO 원격 학습·샘플링 서비스
                    LoRA / forward_backward / optim_step

4-1. 설계 ① 작은 모듈 조합과 설정 분리

docs/chapter5/code/k_model.py는 ModelConfig → Transformer → DecoderLayer → Attention·MLP 구조입니다. ModelConfig는 Transformers의 PretrainedConfig를, Transformer는 PreTrainedModel을 상속합니다. 직접 구현한 내부 연산을 기존 생태계의 설정·출력 형식에 연결하는 설계입니다.

입력 ID [B, T]
    |
    v
Embedding [B, T, 1024]
    |
    +-- 18개 DecoderLayer -----------------------+
    | RMSNorm --> Attention --> 입력과 더하기       |
    | RMSNorm --> 게이트형 MLP --> 다시 더하기      |
    +-------------------------------------------+
    |
최종 RMSNorm --> 출력 투영 --> logits [B, T, 6144]
                                       학습 시

RMSNorm과 잔차 연결: DecoderLayer.forward()는 정규화한 입력을 Attention에 넣은 다음 원래 입력과 더합니다. 이어 MLP에도 같은 구조를 적용합니다. 더하기 경로가 정보를 보존하고, 정규화가 각 블록의 입력 크기를 조절합니다.

# DecoderLayer.forward()의 흐름을 간추린 표현
h = x + attention(attention_norm(x), freqs_cos, freqs_sin)
out = h + feed_forward(ffn_norm(h))

RoPE와 GQA: precompute_freqs_cis()가 회전에 사용할 값을 만들고, apply_rotary_emb()가 Q와 K에 적용합니다. repeat_kv()는 K/V 머리를 Q 머리 수에 맞춥니다. 학습 설정에서 머리 하나의 폭은 1024 / 16 = 64, 반복 수는 16 / 8 = 2입니다.

게이트형 MLP: MLP.forward()는 F.silu(w1(x)) * w3(x)를 w2에 넣습니다. 한 갈래가 변환한 정보에 다른 갈래가 문을 여닫는 형태입니다. multiple_of=64에 맞춘 중간 폭은 이 설정에서 2,752입니다.

가중치 공유: self.tok_embeddings.weight = self.output.weight로 입력 임베딩과 출력층이 같은 파라미터를 사용합니다. 블록과 공유 임베딩의 크기를 합산하면 학습 구성은 215,127,040개, 약 215M 파라미터입니다. 이는 소스의 행렬 크기로 계산한 값입니다.

Attention은 PyTorch에 scaled_dot_product_attention이 있으면 그 API를 사용하고, 없으면 점수 행렬·미래 가림·softmax를 직접 계산합니다. 소스의 self.flash는 API 존재 여부로 결정되며 ModelConfig.flash_attn 값을 읽지 않습니다.

따라서 flash_attn=True라는 설정만으로 특정 FlashAttention 커널 사용을 확정할 수 없습니다. 실제 백엔드는 장치와 자료형 등의 조건에도 좌우됩니다. 참고: PyTorch 2.7 SDPA 공식 문서.

생성 쪽도 경계가 명확합니다. Transformer.generate()는 마지막 위치의 점수로 다음 토큰을 선택해 입력 뒤에 붙이고 반복합니다. 모델에 넣는 문맥은 최근 max_seq_len 토큰으로 제한하며, K/V cache는 구현하지 않습니다. 학습용으로 읽기 쉬운 대신 빠른 추론 서버의 최적화는 별도 주제입니다.

소스: k_model.py, ddp_pretrain.py.

4-2. 설계 ② 입력과 학습 책임을 마스크로 분리

PretrainDataset와 SFTDataset은 JSONL 파일의 줄별 바이트 위치를 미리 저장합니다. 샘플을 요청하면 seek()로 해당 줄을 읽습니다. 전체 텍스트를 메모리에 보관하지 않는 대신 초기 전체 스캔과 줄 수에 비례하는 위치 목록은 필요합니다.

두 Dataset 모두 토큰 배열을 만든 다음 X=input_id[:-1], Y=input_id[1:]로 나눕니다. 모델이 현재 위치에서 다음 토큰을 예측하도록 정답을 맞추는 과정입니다.

# 설명용 토큰 ID. 실제 문장에 대한 분절 결과는 아닙니다.
전체 토큰     [3, 21, 52, 9, 4]
X: 입력       [3, 21, 52, 9]
Y: 다음 정답  [21, 52, 9, 4]
                 ^
# X의 첫 위치를 읽고 Y의 첫 위치를 맞힙니다.

SFTDataset.generate_loss_mask()는 <|im_start|>assistant\n의 토큰열 뒤에서 첫 EOS를 찾으면, 답변 시작부터 그 EOS까지 1을 표시합니다. 사용자 질문은 모델이 볼 수 있지만, 질문 토큰은 손실 계산에서 제외합니다.

대화          [사용자 머리말 | 질문 | 답변 머리말 | 답변 | EOS | PAD]
입력에 포함   [     O      |  O   |      O      |  O   |  O  |  O ]
이동 전 mask  [     0      |  0   |      0      |  1   |  1  |  0 ]

주의: 위 표는 한 칸 이동 전입니다. loss_mask도 Y와 함께 한 칸 이동합니다.
      Dataset의 loss_mask와 모델 내부 ignore_index는 별개입니다.

Transformer.forward()는 reduction='none'으로 토큰별 교차 엔트로피를 반환하고, train_epoch()가 마스크를 곱해 평균을 냅니다. 모델 계산과 어떤 위치를 채점할지 정하는 정책이 분리되어 있습니다.

# ddp_pretrain.py / ddp_sft_full.py의 핵심 식
out = model(X, Y)
loss = out.last_loss / args.accumulation_steps
loss_mask = loss_mask.view(-1)
loss = torch.sum(loss * loss_mask) / loss_mask.sum()

다만 5장 학습 루프의 호출은 model(X, Y)이며 attention_mask를 넘기지 않습니다. 오른쪽 패딩과 미래 토큰 가림 때문에 유효 위치는 뒤의 패딩을 보지 않지만, 일반적인 양방향 모델·왼쪽 패딩까지 같은 논리를 적용하면 안 됩니다.

소스: dataset.py, Tokenizer 설정.

4-3. 설계 ③ 검색·모델·도구를 인터페이스로 연결

7장 RAG의 VectorStore는 EmbeddingModel 객체를 받아 벡터를 만들고 질문을 검색합니다. BaseEmbeddings.get_embedding()라는 경계가 있으므로, 임베딩 공급자를 바꿔도 검색 흐름을 유지하는 방식으로 확장할 수 있습니다.

docs = ReadFiles('./data').get_content(600, 150)
        | 문서 조각
        v
vector = VectorStore(docs)
embedding = OpenAIEmbedding()
vector.get_vector(EmbeddingModel=embedding)
        | 문서 벡터 + 원문
        v
vector.persist() --> storage/doecment.json / storage/vectors.json
        |
질문 --> vector.query(question, embedding, k=1)
        --> 검색된 원문 --> OpenAIChat 인스턴스의 chat()

VectorStore.query()는 모든 벡터와 코사인 유사도를 구한 뒤 NumPy로 정렬합니다. 임베딩 차원을 D, 문서 수를 N이라 하면 유사도 계산은 대략 O(ND), 전체 정렬은 O(N log N)입니다. HNSW 같은 근사 검색 인덱스나 전용 벡터 DB를 사용하지 않습니다.

persist()의 파일명은 실제로 doecment.json입니다. 철자가 어색해도 load_vector()가 같은 이름을 사용하므로, 한쪽만 이름을 바꾸면 기존 저장물을 읽지 못합니다.

예제 임베딩 모델은 BAAI/bge-m3, 응답 모델은 Qwen/Qwen2.5-32B-Instruct입니다. OpenAI 클래스는 API 형식의 호환 클라이언트로 쓰이며, 환경변수 OPENAI_BASE_URL이 실제 서비스 주소를 정합니다.

Agent는 도구를 별도 Python 함수로 등록합니다. function_to_json()은 함수 서명과 타입 힌트를 JSON 도구 스키마로 바꾸고, Agent.handle_tool_call()은 함수명을 tool_map에서 찾아 호출합니다. 모델이 함수의 실행 결과를 꾸며 내는 대신, 실제 도구 결과를 메시지에 넣는 구조입니다.

Agent.get_completion()은 첫 응답의 도구 요청들을 실행한 뒤 모델을 한 번 더 호출합니다. 반복 루프는 없으므로 두 번째 응답이 또 도구를 요청하는 복잡한 다단계 작업은 추가 구현이 필요합니다.

소스: VectorBase.py, Agent 핵심 구현, 도구 스키마 변환.

4-4. 설계 ④ 원격 정책 학습과 로컬 환경의 분리

8장에서는 로컬 Python 코드가 문제·보상·도구 결과를 관리하고, PyTRIO 클라이언트로 원격 샘플링과 LoRA 업데이트를 요청합니다. ServiceClient.create_lora_training_client(), forward_backward(), optim_step()이 두 영역의 경계입니다. 서비스 이용 방법은 PyTRIO 공식 빠른 시작을 참고하세요.

GRPO 동기 예제의 run_rollout_group()는 같은 문제에 답을 여러 개 생성합니다. grade_answer()는 마지막 \boxed{...}에서 꺼낸 답과 기준 답을 간단히 정규화한 뒤 문자열이 같으면 1, 아니면 0을 줍니다. 이 코드의 advantage는 보상에서 그룹 평균을 뺀 값입니다. 표준편차로 나누는 형태는 여기에 구현되어 있지 않습니다.

# 이 예제의 그룹 상대 신호를 손으로 계산
보상        = [1, 0, 1, 0]
그룹 평균   = 0.5
advantage   = [0.5, -0.5, 0.5, -0.5]

# 모두 맞거나 모두 틀리면 상대적 차이가 없습니다.
보상        = [1, 1, 1, 1]
advantage   = [0, 0, 0, 0]  # 이 그룹은 학습 데이터에서 건너뜀

OPD는 다른 신호를 만듭니다. completion_teacher_logprobs()가 학생이 실제 생성한 토큰열을 교사에게 채점하게 하고, student_logprob - teacher_logprob의 음수에 계수를 곱해 advantage로 사용합니다. 정답 문자열을 베끼는 학습과 토큰별 확률을 비교하는 학습의 차이를 볼 수 있습니다.

Search-R1과 ReTool은 이를 여러 파일로 나눕니다. protocol.py가 도구 호출 형식, rollout.py가 행동 궤적, reward.py가 채점, train.py가 업데이트를 맡습니다. 검색·코드 실행 같은 환경만 바꾸면서 같은 큰 구조를 유지합니다.

ReTool의 build_datum()는 여러 턴을 이어 붙일 때 이전 궤적이 다음 입력의 접두부인지 검사합니다. 도구가 준 관측 토큰은 입력에 남기되 advantage를 0으로 둡니다. 모델이 직접 생성한 토큰에 학습 책임을 주기 위한 장치입니다.

모델이 참고한 정보와 모델이 직접 선택한 행동을 구분하는 일이, SFT와 Agent 강화학습을 이어 주는 핵심입니다.

구체적으로 ReTool은 훈련 입력 길이 최대 8192토큰, micro-batch당 최대 샘플 32개, 패딩 포함 토큰 예산 64,000을 둡니다. PPO 비율 제한은 0.8과 1.28입니다. 알고리즘뿐 아니라 길이가 다른 궤적을 묶는 비용도 학습할 수 있습니다.

소스: GRPO 동기 예제, OPD 동기 예제, ReTool 학습 데이터 구성.

5디렉토리 구조 해부

happy-llm/
|-- README.md / README_en.md     소개와 장별 이동 경로
|-- LICENSE.txt                 CC BY-NC-SA 4.0 본문
|-- docs/
|   |-- index.html              Docsify 문서 사이트
|   |-- _sidebar.md             교재 탐색 메뉴
|   |-- chapter1/               NLP 기초
|   |-- chapter2/code/          transformer.py
|   |-- chapter3/               사전학습 모델의 계열
|   |-- chapter4/               LLM과 학습 전략
|   |-- chapter5/code/
|   |   |-- k_model.py          직접 만든 Decoder 언어 모델
|   |   |-- dataset.py          사전학습·SFT 샘플과 마스크
|   |   |-- train_tokenizer.py  BPE 학습
|   |   |-- tokenizer_k/        어휘·특수 토큰·대화 형식
|   |   |-- ddp_pretrain.py     사전학습 루프
|   |   |-- ddp_sft_full.py     전체 파라미터 SFT
|   |   |-- model_sample.py     생성 예제
|   |   `-- export_model.py     모델 내보내기
|   |-- chapter6/code/          Trainer / DeepSpeed / Notebook
|   |-- chapter7/
|   |   |-- RAG/                문서 분할·벡터·검색·생성
|   |   `-- Agent/              도구 등록·호출·Streamlit UI
|   |-- chapter8/
|   |   |-- grpo/               동기·비동기 그룹 상대 학습
|   |   |-- opd/                동기·비동기 정책 증류
|   |   |-- search-r1/          검색 환경을 사용하는 RL
|   |   `-- retool/             코드 실행 환경을 사용하는 RL
|   `-- images/                 장별 교재 그림
|-- Extra-Chapter/              생성·작은 모델·멀티모달 등 보충 글
|-- images/                     저장소 소개 이미지
`-- .github/ISSUE_TEMPLATE/     오류 제보 양식

5-1. 처음에는 세 파일만 연결해 읽는다

1. docs/chapter5/code/dataset.py에서 반환값 X, Y, loss_mask를 확인합니다.
2. docs/chapter5/code/k_model.py의 Transformer.forward()에서 그 값이 무엇을 예측하는지 읽습니다.
3. docs/chapter5/code/ddp_pretrain.py의 train_epoch()에서 손실이 어떻게 역전파되는지 연결합니다.

파일을 위에서 아래로 모두 읽는 것보다, 한 샘플이 이 세 파일 사이를 어떻게 이동하는지 따라가면 함수의 존재 이유를 이해하기 쉽습니다. 그다음 Attention과 MLP의 내부로 들어가세요.

5-2. 코드 규모를 읽는 올바른 단위

집계 범위는 커밋 1e0b3a1의 파일이며 .git은 제외합니다. 전체 214개 파일은 약 31.2MB이고 이미지·Tokenizer 데이터도 포함합니다. Python 줄 수와 Notebook 코드 셀 줄 수는 서로 다른 집계 방식이므로 엄밀한 생산 코드량 비교에 쓰지는 마세요.

8장 Python은 22개 파일·7,537줄로 전체 Python 분량의 약 66%입니다. GitHub의 주 언어 표시는 Jupyter Notebook이지만, 현재 학습 경로의 상당 부분은 독립 Python 파일을 읽는 작업입니다.

5장은 Python 8개·1,937줄, 6장은 Python 4개·543줄입니다. 코드가 짧은 5장으로 학습 루프를 익히고, 파일이 더 잘게 나뉜 8장으로 확장하면 구조를 놓치기 어렵습니다.

6학습 포인트 (기술별)

6-1. Python과 데이터 입출력: 큰 파일을 조금씩 다루기

read_texts_from_jsonl()는 한 줄씩 JSON을 해석하고 text 필드를 yield합니다. 깨진 JSON이나 누락 필드는 보고한 뒤 건너뜁니다. Dataset은 줄 위치를 미리 모은 뒤 샘플 하나씩 읽습니다. 모두 입력 전체를 한 번에 리스트로 들고 있는 방식과 비교하기 좋습니다.

실습 아이디어: JSONL 5줄 중 1줄을 잘못된 JSON으로, 다른 1줄을 text 없는 객체로 만들어 처리 정책을 설계하세요. 잘못된 데이터를 건너뛰면 원래 줄 번호와 학습 샘플 번호가 달라진다는 점도 기록합니다.

6-2. Tokenizer: 텍스트 표현 자체도 설계 대상이다

train_tokenizer.py는 NFKC 정규화, ByteLevel 분절·복원, BPE 학습을 조합합니다. 함수의 기본 vocab_size는 8,192지만, main()은 6,144를 명시해 호출합니다. 동봉된 tokenizer_k/tokenizer.json의 어휘 수도 6,144입니다. 기본 인자와 실제 호출 설정을 구별해야 하는 사례입니다.

실습 아이디어: 한국어 조사, 영문 약어, 숫자, 이모지가 섞인 문장 10개를 준비하고 토큰 수·복원 결과·특수 토큰을 비교하세요. 어휘 수를 줄이면 출력층은 작아지지만 같은 문장의 토큰 수는 늘 수 있습니다.

6-3. PyTorch: 수식보다 먼저 모양을 보존하기

Attention.forward()에서 Q는 [B,T,16,64], K/V는 [B,T,8,64]가 됩니다. K/V를 반복하고 머리 축을 앞으로 옮겨 Attention을 계산한 뒤 다시 합칩니다. view·transpose·contiguous가 왜 필요한지 한 흐름에서 배울 수 있습니다.

실습 아이디어: B=2, T=4인 경우의 각 중간 모양을 표에 적으세요. 머리 수를 바꿀 때 dim의 나눗셈과 RoPE의 짝수 차원 조건을 함께 확인합니다. 단순히 전체 파라미터 수만 맞춘다고 유효한 설정이 되는 것은 아닙니다.

6-4. 학습 루프: 작은 배치 여러 번을 묶는 이유

5장의 기본값은 batch size 64, 누적 8회, 학습률 2e-4, gradient clipping 1.0입니다. 완전한 배치 기준으로 optimizer 한 번 갱신 전 샘플 512개를 처리합니다. DataParallel에서는 64가 장치마다 별도로 생기는 배치가 아니라 분할되는 전체 배치입니다.

get_lr()는 warmup과 cosine decay를 구현하지만 기본 warmup_iters=0입니다. 기능이 있다고 기본 실행에서도 활성화되는 것은 아닙니다. 또한 epoch 마지막에 누적 횟수를 채우지 못한 나머지를 처리하는 별도 업데이트 분기는 보이지 않습니다.

실습 아이디어: 10개 micro-batch를 4회씩 누적한다고 가정하고 optimizer 갱신 시점을 표시하세요. 끝의 2개를 버릴지, 따로 평균을 조정해 갱신할지 정책을 정해 봅니다.

6-5. Trainer·DeepSpeed: 프레임워크가 대신 관리하는 것

6장 docs/chapter6/code/pretrain.py의 main()은 인자를 dataclass로 파싱하고, 데이터를 토큰화·분할한 뒤 Trainer에 전달합니다. config_name이면 새 가중치를 초기화하고, model_name_or_path이면 기존 가중치를 읽습니다. 같은 모델 구조라도 출발점이 달라지는 분기입니다.

ds_config_zero2.json의 zero_optimization.stage=2는 optimizer 상태와 gradient를 분할하는 단계입니다. 가중치까지 분할하는 ZeRO-3와 다릅니다. 이 설정의 offload_optimizer.device는 none이므로 CPU offload가 켜졌다고 읽으면 안 됩니다. 단계의 의미는 DeepSpeed 공식 ZeRO 안내로 보완하세요.

실습 아이디어: 5장에서 수동으로 하는 작업을 6장에서 누가 맡는지 대응표를 만드세요. 데이터 배치, 역전파, 누적, 저장, 재시작을 각각 찾아보면 추상화가 무엇을 감추는지 보입니다.

6-6. RAG: 검색 결과를 먼저 평가하기

RAG 예제는 ReadFiles.get_content(max_token_len=600, cover_content=150)으로 문서를 나누고, query(k=1) 결과 한 조각을 답변에 넣습니다. 문서 분할은 cl100k_base로 길이를 세지만, 실제 임베딩 모델은 bge-m3입니다. 길이 측정용 Tokenizer와 모델 Tokenizer가 다를 수 있음을 기억해야 합니다.

또한 겹치는 내용을 가져오는 일부 분기는 문자열 뒤쪽을 슬라이스합니다. cover_content=150을 모든 경우에 정확한 150토큰 겹침이라고 단정하지 말고, 반환되는 조각을 확인하세요.

실습 아이디어: 정답 근거 문서를 미리 정한 질문 10개를 만들고, LLM 답변 전에 검색 상위 결과에 근거가 있는지 표시하세요. 검색 실패와 답변 생성 실패를 따로 세면 개선할 부품을 찾기 쉽습니다.

6-7. Agent·강화학습: 도구 실행과 행동 학습을 구분하기

7장의 Agent는 이미 학습된 모델에 도구 목록을 주고 결과를 돌려줍니다. 8장은 생성 궤적을 보상으로 평가해 파라미터를 갱신합니다. 함수 호출이 존재한다는 사실만으로 강화학습을 하고 있다고 볼 수는 없습니다.

실습 아이디어: assistant → tool → assistant 기록을 만들고, 어느 토큰이 모델의 선택이고 어느 토큰이 외부 결과인지 색으로 나눠 보세요. retool/train.py의 build_datum()가 그 경계를 숫자 배열로 보존합니다.

새 기술을 배울 때마다 입력 형식, 출력 형식, 실패 조건을 한 장에 정리하면 라이브러리가 바뀌어도 이해가 남습니다.

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

학습 가능 여부는 모델 가중치 크기만으로 결정되지 않으며, 배치·문맥·gradient·optimizer 상태까지 함께 계산해야 합니다.

7-1. 215M 모델의 메모리를 손으로 추정하기

# 십진 GB 기준의 대략적인 크기. 실행 시 최대 사용량은 아닙니다.
파라미터 수               215,127,040
FP32 가중치               파라미터 수 × 4 bytes ≈ 0.86 GB
BF16 가중치               파라미터 수 × 2 bytes ≈ 0.43 GB
FP32 가중치 + gradient
  + Adam의 두 상태        파라미터 수 × 16 bytes ≈ 3.44 GB

여기에 활성값, 임시 연산 버퍼, CUDA 비용 등이 더해집니다.

5장 학습 스크립트는 기본 FP32 파라미터를 만들고 GPU에서 autocast를 사용합니다. --dtype bfloat16은 docs/chapter5/code/ddp_sft_full.py에서는 autocast 자료형에 반영되지만, docs/chapter5/code/ddp_pretrain.py의 autocast()에는 자료형이 전달되지 않습니다. 이 인자만으로 모든 학습 메모리가 숫자당 2바이트가 된다고 계산하면 안 됩니다. GPU의 BF16 지원 여부도 확인해야 합니다.

메모리가 부족하면 먼저 배치와 문맥 길이를 줄여 원인을 나누세요. gradient accumulation은 작은 배치를 여러 번 처리하는 방법이지만, 파라미터와 optimizer 상태 자체를 작게 만들지는 않습니다.

7-2. 저장 공간과 네트워크

저장소 파일 자체는 약 31.2MB이지만, 학습 데이터와 모델 가중치는 별도입니다. 다운로드·토큰화 캐시·체크포인트가 쌓이면 필요한 디스크는 크게 늘어납니다. 5장의 기본 예시는 seq_monkey_datawhale.jsonl과 BelleGroup_sft.jsonl을 가리킵니다.

RAG의 순수 벡터 저장량은 대략 문서 수 × 차원 × 숫자당 바이트 수입니다. 예를 들어 10,000조각·1,024차원·FP32라고 가정하면 약 41MB입니다. 예제처럼 JSON과 Python 리스트를 사용하면 문자열·객체 비용이 추가되므로 실제 메모리는 이보다 큽니다.

7장 RAG는 OPENAI_API_KEY와 OPENAI_BASE_URL을 읽습니다. CPU에서 화면을 띄운다는 것과 모델 추론도 로컬에서 한다는 것은 다른 조건입니다. 8장은 실험 기록을 꺼도 원격 학습 호출은 남습니다.

7-3. 운영체제와 예시 설정의 경계

5장 장치 선택은 CUDA가 있으면 cuda:0, 없으면 cpu를 택합니다. Apple Silicon의 mps를 자동 선택하는 분기는 없습니다. Mac GPU 활용은 장치 선택과 연산 호환성을 별도로 조정해야 합니다.

6장 Shell 파일은 CUDA_VISIBLE_DEVICES=0,1을 단독 대입하고 다음 명령을 실행합니다. 셸 환경에 따라 이 값이 자식 프로세스에 전달되지 않을 수 있으므로, export 또는 명령 앞의 환경변수 지정으로 의도를 명확하게 만드는 점검이 필요합니다.

근거: ReTool 코드 실행기, 6장 실행 예제. 하드웨어 표는 저장소 환경 안내와 소스의 전제를 정리한 것으로, 장치별 속도나 최소 VRAM을 보증하는 측정표가 아닙니다.

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

첫 세 과제는 모델 API나 대규모 데이터 없이 시작할 수 있습니다. 아래 코드는 동작 원리를 확인하기 위한 작은 예제입니다. 전체 학습은 장별 환경과 데이터 형식을 먼저 이해한 뒤 진행하세요.

tokens = [3, 11, 22, 4, 4]
valid = [1, 1, 1, 1, 0]
x, y = tokens[:-1], tokens[1:]
mask = valid[1:]
print(list(zip(x, y, mask)))
# 기대: [(3, 11, 1), (11, 22, 1), (22, 4, 1), (4, 4, 0)]

from math import sqrt

def cosine(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    norm = sqrt(sum(x * x for x in a)) * sqrt(sum(y * y for y in b))
    return dot / norm if norm else 0.0

query = [1, 0]
vectors = [[1, 0], [0.8, 0.2], [0, 1]]
ranked = sorted(enumerate(vectors), key=lambda p: cosine(query, p[1]), reverse=True)
print([index for index, _ in ranked])
# 기대: [0, 1, 2]

실습의 완료 기준은 명령이 종료되는 것이 아니라, 입력·정답·마스크가 의도한 학습 문제를 표현한다고 설명할 수 있는 것입니다.

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

Python의 함수·클래스·리스트에 익숙한 초보자를 위한 8주 학습 예시입니다. 주당 학습 시간과 수학 배경에 따라 늘려도 됩니다. 원격 학습은 마지막 선택 과제로 두고, 앞부분은 작은 데이터와 코드 읽기로 진행할 수 있습니다.

9-1. 막힐 때 돌아갈 기초

• 모양을 놓쳤다면: 행렬의 행·열, 축 바꾸기, broadcasting부터 복습합니다. 처음부터 미분 수식 전체를 외울 필요는 없습니다.
• 손실이 이해되지 않으면: 정답 한 토큰에 부여한 확률을 높이는 문제로 줄여 생각합니다. 그다음 gradient가 어느 가중치로 전달되는지 연결합니다.
• Trainer가 막연하면: 5장의 backward → step → zero_grad 순서로 돌아가 각 작업의 주체를 찾습니다.
• 강화학습이 어렵다면: 먼저 같은 문제의 네 답변에 0·1점을 매기고 평균을 빼 보세요. 이후 토큰마다 같은 advantage가 어떻게 들어가는지 읽습니다.

9-2. 목표에 따른 후속 경로

모델 연구: 5장의 폭·깊이·어휘 크기를 각각 바꾸는 실험 설계를 해 보세요. 비교할 때 데이터·토큰 수·평가 질문을 고정해야 무엇이 효과를 냈는지 알 수 있습니다.

응용 개발: 7장에서 검색 품질, 도구 입력 검증, 사용자별 대화 상태를 보완하세요. 특히 web_demo.py는 Agent를 st.cache_resource로 캐시하지만 Agent 내부에 메시지 목록이 있으므로, 여러 사용자 환경에서는 세션별 상태 분리를 검토해야 합니다.

학습 인프라: 6장의 ZeRO 설정과 8장의 micro-batch 묶기를 비교하세요. 하나는 여러 장치의 학습 상태를, 다른 하나는 길이가 다른 샘플의 실행 비용을 다룹니다.

다음 주제로 넘어가는 기준은 읽은 페이지 수보다, 현재 단계의 데이터 계약과 실패 조건을 설명할 수 있는지에 두세요.

10핵심 키워드 사전

용어를 외우기보다 dataset.py의 반환값, forward()의 출력, build_datum()의 배열 중 어디에 해당하는지 연결해 보세요.

11참고 링크

11-1. 프로젝트와 직접 읽을 소스

• happy-llm 공식 저장소 — 소개, 장별 안내, 공개 모델 링크.
• 공식 온라인 교재 — 중국어 원문을 장 순서대로 읽는 웹사이트.
• 2장 Transformer 구현 — Attention과 Encoder·Decoder 기초.
• 5장 직접 구현·데이터·학습 코드 — 본문의 주요 코드 읽기 출발점.
• 6장 Trainer·DeepSpeed 예제 — 프레임워크로 넘어가는 다리.
• 7장 RAG·Agent — 검색과 도구 실행을 분리해 읽기.
• 8장 Agentic RL — GRPO·OPD·환경 기반 학습.
• 보충 학습 글 — 작은 모델, 생성 방법, 멀티모달 등 후속 주제.

11-2. 관련 기술의 공식 문서

• PyTorch 2.7 SDPA — Attention 마스크, dropout, 백엔드 선택 조건.
• Transformers 4.44.0 Trainer — 5장 의존성 버전과 같은 시기의 학습 인터페이스.
• DeepSpeed ZeRO — 단계별로 무엇을 분할하는지 확인.
• PyTRIO 공식 빠른 시작 — 계정·샘플링·LoRA 학습 클라이언트의 관계.
• nanoGPT 공식 저장소 — 간결한 GPT 구현·학습 루프와 비교.

현재 상태 (2026-10-23 확인)