AdaptiveTrainingSystem 딥다이브
— HuggingFace로 '완성된 모델'을 내려받는 대신, 토크나이저부터 CUDA 커널까지 LLM 학습 전 과정을 밑바닥부터 짓는 '1인 제철소'

MatN23/AdaptiveTrainingSystem. 요즘 대부분은 HuggingFace에서 '다 구워진 모델'을 내려받아 미세조정만 합니다. 이 프로젝트는 정반대로, 트랜스포머 LLM을 밑바닥부터(토크나이저 → 모델 구조 → 학습 루프 → GPU 커널 → C++ 추론 엔진) 직접 만드는 PyTorch 프레임워크입니다. 특히 Mixture-of-Experts(MoE)·Mixture-of-Depths(MoD) 같은 희소(sparse) 구조를 지원하고, 남들은 PyTorch 기본 연산에 맡기는 부분까지 손으로 짠 CUDA·Apple Metal 커널로 가속합니다. 게다가 학습 중 손실 곡선을 감시하며 스스로 개입하는 자율 오케스트레이터까지 들어 있습니다. 별 21개의 1인 개발 프로젝트라 '대규모 검증된 도구'는 아니지만, 현대 LLM의 내부와 GPU 성능 엔지니어링을 한 저장소에서 통째로 공부하기에는 보기 드물게 알찬 교본입니다. (저장소: MatN23/AdaptiveTrainingSystem · 언어 Python(+CUDA/Metal/C++) · PyTorch + DeepSpeed/FSDP/ColossalAI · Apache-2.0 · ★21 · TrendShift 라이브 멘션 #62135)

1프로젝트 한줄 요약

"완성차를 사 오는 대신, 엔진 피스톤까지 직접 깎아 차를 만드는 1인 공장."

좀 더 구체적으로, 저장소의 실제 코드는 모두 Src/Main_Scripts/ 아래에 있습니다. 작성자(덴마크 개발자 Matias Nielsen, 1인) 본인 코드는 파이썬 약 3.2만 줄 + GPU 커널 약 5천 줄 규모이고, 모델 전체 구조가 들어 있는 core/model.py 한 파일만 2,710줄입니다. 학습 루프(trainer.py)는 4,321줄, 자율 오케스트레이터(orchestrator.py)는 2,503줄로, "README만 화려한 빈 껍데기"가 아니라 실제로 동작하는 구현이 핵심입니다(78개의 pytest 테스트도 포함).

이 문서가 파고드는 건 "어떻게 설치하나"가 아니라 그 안의 설계입니다 — "MoE 라우팅을 CUDA로 가속하면서 어떻게 역전파(미분)를 안 깨뜨렸나", "왜 RMSNorm은 fp32로 계산하나", "백엔드 3종(DeepSpeed·FSDP·ColossalAI)을 어떻게 하나의 인터페이스로 갈아끼우나", "학습을 스스로 감시하는 오케스트레이터는 무엇을 보나". 현대 LLM 내부와 GPU 프로그래밍을 동시에 공부하려는 사람에게 작지만 밀도 높은 실전 교본입니다.

2왜 주목받는가 (그리고 솔직한 주의점)

"래퍼(wrapper)가 아니라 진짜 구현"이라는 점, 그리고 1인 프로젝트라 과장도 섞여 있다는 점.

비슷한 'LLM 학습 코드'는 많지만, 이 저장소가 라이브 멘션을 타고 화제가 된 이유는 대부분이 흉내만 내는 어려운 부분을 실제로 짜 놨기 때문입니다. 다섯 가지로 정리하면:

① API 래퍼가 아니라 '완성 스택'

README가 스스로 못 박습니다 — "이건 모델 동물원(model zoo)이나 API 래퍼가 아니라, 커스텀 CUDA 커널을 갖춘 완전한 학습 시스템이다." 토크나이저, 모델, MoE 라우팅, 손실 함수, 분산 학습, 추론까지 한 저장소 안에서 손으로 이어집니다.

② 손으로 짠 GPU 커널 (진짜 차별점)

대부분의 취미·학습용 프레임워크는 GPU 연산을 PyTorch에 떠넘깁니다. 이 프로젝트는 .cu(CUDA)·.metal(애플) 소스를 실제로 포함하고, 실행 시점에 nvcc로 컴파일해서 RMSNorm·RoPE·SwiGLU·MoE 라우팅을 가속합니다(안 되면 PyTorch로 자동 우회). moe_cuda_ops.cu 1,207줄, transformer_ops.cu 981줄 — "커널을 직접 짠다"는 말이 빈말이 아닙니다.

③ MoE + MoD 하이브리드

MoE(전문가 혼합)는 비교적 흔하지만, 여기에 2024년 DeepMind의 MoD(깊이 혼합)까지 결합해 한 모델에서 학습 가능하게 한 오픈 구현은 드뭅니다. "어떤 전문가에게 보낼까"와 "이 층을 아예 건너뛸까"를 동시에 학습합니다.

④ 애플 실리콘(Metal/MPS) 지원

대부분의 학습 프레임워크가 NVIDIA 전용인데, 이 프로젝트는 M1~M4 맥에서도 MoE 학습·추론이 되도록 Metal 셰이더와 MPS 경로를 따로 갖췄습니다.

⑤ 정직한 벤치마크

BENCHMARKS.md가 측정 환경을 NVIDIA T4 1장으로 명시하고, A100/H100 같은 대형 GPU 수치는 "검증되지 않음 … 구조적 추정치일 뿐"이라고 스스로 라벨을 붙입니다. 과대광고가 흔한 분야에서 이런 자기 고지는 드문 신뢰 신호입니다.

다른 도구와의 비교

3기술 스택 전체 지도

한 저장소 안에 파이썬·CUDA·Metal·C++가 공존한다. 각 층이 무엇을 담당하는지 펼쳐 보자.

이 프로젝트는 웹 서비스가 아니라 '모델 학습 엔진'이라, 보통의 백엔드/프론트엔드 구분 대신 ① 모델·학습 코어(파이썬) ② GPU 가속(CUDA/Metal) ③ 분산·인프라로 나누어 보는 게 자연스럽습니다.

언어 구성

① 모델·학습 코어 (핵심 파이썬 의존성)

② 분산 학습 · 성능

③ 양자화 · 데이터 · 관측

④ 빌드 · 인프라

네이티브 커널은 실행 시점에 컴파일됩니다. cuda_kernels.py가 현재 GPU의 SM 아키텍처를 감지해 nvcc를 호출하고, 만들어진 .so를 ctypes로 불러옵니다(이게 핵심 트릭, §4·§6에서 자세히). 그 밖에 Dockerfile.backend(python:3.10-slim, Flask 헬스체크 포트 5001), docker-compose.dev.yml(Jupyter 8888 포함), makefile, GitHub Actions CI(test.yml)가 있습니다.

4아키텍처 심화 분석

설정(config) 객체 하나가 모델 → 학습 루프 → GPU 커널 → 분산 백엔드를 타고 흐른다.

전체 구조의 핵심은 "설정이 모든 걸 결정하고, 무거운 계산은 손코딩 커널로 내려가되, 실패하면 항상 PyTorch로 우회한다"입니다. 실제 코드(Src/Main_Scripts/)의 흐름을 그림으로 보면:

핵심 설계 패턴 5가지

① 3단 가속 폴백 (fast path + safe fallback)

가장 자주 등장하는 패턴입니다. 모든 가속 연산(RMSNorm·RoPE·SwiGLU·MoE 라우팅)은 통합 백엔드 → 직접 CUDA/Metal → PyTorch 순으로 시도하고, 각 단계를 try/except로 감쌉니다. "빠른 길이 막히면 느려도 확실한 길로 자동 우회"라, 어떤 하드웨어에서도 일단 돌아가게 만드는 실전적 안전장치입니다.

def forward(self, x):
    input_dtype = x.dtype
    if USE_UNIFIED_BACKEND and self._impl is not None:
        try: return self._impl(x)            # 1순위: 통합 백엔드
        except Exception: pass
    if self._cuda_impl is not None and x.is_cuda:
        try: return self._cuda_impl(x)       # 2순위: 직접 CUDA
        except Exception: pass
    x_normed = self._norm_pytorch(x)         # 3순위: PyTorch 우회(내부 fp32)
    if self.elementwise_affine:
        x_normed = x_normed * self.weight.float()
    return x_normed.to(input_dtype)

core/model.py RMSNorm.forward (약 L311) — 같은 모양의 폴백이 모델 전반에 반복됩니다.

② 백엔드 전략 패턴 (Strategy)

backend/backend_deepspeed.py·backend_fsdp.py·backend_colossalai.py가 동일한 표면(인터페이스)을 제공하고, 오케스트레이터가 use_deepspeed() 같은 플래그로 하나를 고릅니다. "큰 모델을 어떻게 여러 GPU에 쪼갤까"라는 어려운 문제를 직접 재구현하지 않고 검증된 라이브러리에 위임하되, 갈아끼우기 쉽게 추상화한 영리한 선택입니다.

③ 자율 제어 루프 (orchestrator)

training/orchestrator.py(2,503줄)는 학습을 지켜보는 '관제탑'입니다. 백그라운드 스레드 monitoring_loop()가 돌면서:

"학습이 발산하면 멈추거나 학습률을 낮추고, 전문가가 놀고 있으면 가지치기한다" — 이런 피드백 컨트롤러를 직접 만드는 법을 통째로 공부할 수 있는 부분입니다.

④ 런타임 커널 JIT 컴파일

커널을 미리 빌드해 두는 게 아니라, 처음 쓰는 순간 현재 GPU에 맞춰 nvcc로 컴파일합니다. torch.cuda.get_device_properties로 SM 아키텍처(예: sm_75)를 알아내 컴파일 옵션을 맞추죠(§6에 코드).

⑤ 수치 안정성 규율

저정밀(fp16/bf16) 학습에서 터지기 쉬운 부분을 의도적으로 고정밀로 계산합니다. RMSNorm은 fp32로 계산한 뒤 원래 타입으로 되돌리고, RoPE의 cos/sin 테이블은 fp64로 만들어 캐시합니다. "어디서 정밀도를 지켜야 학습이 안 터지는가"의 좋은 예시입니다.

5디렉토리 구조 해부

진짜 코드는 전부 Src/Main_Scripts/ 아래. 그 안을 역할별로 펼쳐 본다.

읽는 순서를 추천하자면: ① config/config_manager.py(무엇을 만드는지) → ② core/model.py(모델이 어떻게 생겼는지) → ③ training/trainer.py(어떻게 학습하는지) → ④ core/moe_cuda_ops.cu(GPU에서 실제로 어떻게 도는지) 순입니다. ColossalAI/ 폴더는 외부 코드이니 처음엔 건너뛰세요.

6학습 포인트 (기술별)

이 저장소의 진짜 가치는 "현대 LLM 내부 + GPU 성능 엔지니어링"을 한곳에서 코드로 볼 수 있다는 것.

① 트랜스포머 내부를 밑바닥부터 — core/model.py

요즘 LLM의 표준 부품들이 한 파일에 다 구현돼 있습니다. 읽을 위치까지 적어 두면: RMSNorm(L260), RotaryEmbedding/RoPE(L366), DenseGroupedQueryAttention/GQA(L613), SwiGLUExpert(L1006), TransformerBlock(L1578). LayerNorm 대신 RMSNorm, 절대 위치 임베딩 대신 RoPE, 모든 헤드가 KV를 따로 갖는 대신 GQA로 공유 — "왜 요즘 모델은 이렇게 바뀌었나"를 코드로 체득하기 좋습니다.

② Mixture-of-Experts — 라우팅을 CUDA로 가속하되 미분을 안 깨뜨리기

MoEFFNLayer(L1068)는 top-k 게이팅, 온도(temperature) 스케일링, capacity factor, 그리고 전문가에게 일이 골고루 가도록 하는 보조 부하분산 손실(auxiliary load-balancing loss)을 모두 구현합니다. 가장 영리한 부분은 "CUDA로 top-k를 빠르게 고르되, 미분은 PyTorch로 흐르게" 한 점입니다:

if self.use_cuda_ops and MoECUDAOps is not None and x.is_cuda:
    try:
        top_k_indices, cuda_probs = MoECUDAOps.topk_gating(
            gate_logits, self.top_k,
            temperature=self.routing_temperature, use_cuda=True)
        # 인덱스는 CUDA가 고르고, 확률은 PyTorch로 다시 계산 →
        top_k_logits = torch.gather(scaled_logits, -1, top_k_indices)
        top_k_probs  = F.softmax(top_k_logits, dim=-1)  # 게이트로 가는 미분 경로 유지
    except Exception as e:
        top_k_indices, top_k_probs = self._pytorch_routing(gate_logits)
else:
    top_k_indices, top_k_probs = self._pytorch_routing(gate_logits)

커널은 "누구를 뽑을지"(인덱스)만 빠르게 정하고, 실제 확률은 F.softmax로 다시 계산해 역전파가 라우터 가중치까지 흐르게 합니다. "선택은 가속하되 학습은 안 깨뜨린다" — MoE를 직접 짤 때 가장 헷갈리는 지점의 모범답안입니다.

③ Mixture-of-Depths — 쉬운 토큰은 층을 건너뛰기

MoDRouter(L907)와 DenseSwiGLUWithMoD(L1362)는 토큰별로 "이 층을 거칠지/건너뛸지"를 학습합니다. capacity_factor를 낮출수록 더 많이 건너뛰어 FLOPs가 줄어듭니다. MoE(가로로 전문가 나눔)와 MoD(세로로 층 건너뜀)를 같이 쓰는 흔치 않은 조합을 실제 코드로 볼 수 있습니다.

④ CUDA 커널 프로그래밍 — core/moe_cuda_ops.cu

여기가 이 저장소의 백미입니다. GPU 한 워프(32 스레드) 안에서 레지스터만으로 최댓값을 구하는 워프 셔플 리덕션, 정렬 없이 top-k를 뽑는 바이토닉 정렬, 한 번에 4개 float를 읽는 float4 벡터화 같은 실전 기법이 들어 있습니다:

// 워프 셔플로 32개 값의 최댓값을 동기화 없이 구하기
__device__ __forceinline__ float warp_reduce_max(float val) {
    for (int offset = WARP_SIZE/2; offset > 0; offset >>= 1)
        val = fmaxf(val, __shfl_xor_sync(FULL_MASK, val, offset));
    return val;
}
// 각 레인이 자기 몫의 float4를 로드 → 메모리 대역폭 최대화
const float4 *logits_vec = reinterpret_cast<const float4 *>(token_logits);
// __launch_bounds__(256, 4): T4(SM당 1024스레드)에 맞춘 점유율 튜닝

그리고 SwiGLU 활성화는 이렇게 한 줄짜리 커널로 융합합니다(빠른 __expf intrinsic 사용):

__global__ void __launch_bounds__(256)
swiglu_kernel_simple_fp32(const float* __restrict__ gate,
                          const float* __restrict__ up,
                          float* __restrict__ output, const int n) {
    const int idx = blockIdx.x * blockDim.x + threadIdx.x;
    if (idx >= n) return;
    float silu_u = up[idx] / (1.0f + __expf(-up[idx]));  // SiLU
    output[idx] = gate[idx] * silu_u;                    // gate로 곱셈
}

CUDA를 처음 보더라도, "스레드 인덱스 계산 → 범위 체크 → 자기 원소 처리"라는 기본 골격과 __restrict__·__launch_bounds__ 같은 최적화 힌트를 실제 맥락에서 익힐 수 있습니다.

⑤ 런타임 커널 컴파일 — training/cuda_kernels.py

커널을 미리 빌드하지 않고, 현재 GPU 아키텍처를 감지해 nvcc를 그 자리에서 호출합니다. "C 소스를 파이썬에서 컴파일해 불러오는" 패턴을 통째로 보여 줍니다:

prop = torch.cuda.get_device_properties(0)
sm   = f"sm_{prop.major}{prop.minor}"          # 예: sm_75 (T4)
arch = f"compute_{prop.major}{prop.minor}"
cmd = ["nvcc", "-O3", "-shared", "-fPIC", "--use_fast_math",
       f"--generate-code=arch={arch},code={sm}",
       "-o", _SO_FILE, _CU_FILE]
subprocess.run(cmd, capture_output=True, text=True, timeout=180)
# 만들어진 .so는 ctypes로 로드

⑥ 분산 학습 백엔드 3종 비교 — backend/

같은 인터페이스 뒤에서 DeepSpeed(ZeRO 1~3·오프로딩), FSDP, ColossalAI를 갈아끼울 수 있습니다. "큰 모델을 여러 GPU에 어떻게 쪼개나(ZeRO가 옵티마이저 상태·그래디언트·파라미터를 단계별로 분산)"를 세 방식으로 비교 학습하기에 좋습니다.

⑦ 컴퓨트 최적 학습량 — training/chinchilla_scaler.py

Chinchilla 법칙(모델 크기 대비 최적 토큰 수)을 코드로 구현합니다. ConvergenceDetector(정체·발산 감지), ComputeEfficiencyTracker(토큰당 FLOPs)로 "지금 더 학습할 가치가 있나"를 판단합니다.

⑧ 파이썬 밖으로 — C++ 추론 런타임 moe_inference_runtime/

학습된 MoE 모델을 파이썬 없이 C++로 서빙하는 별도 엔진입니다(runtime.cpp + CPU/CUDA/MPS 백엔드). "학습 코드와 추론 코드는 분리된다"는 실무 패턴을 보여 줍니다.

⑨ ML 코드 테스트 — Src/tests/

78개 pytest가 있습니다 — test_chinchilla.py(9개), test_checkpointing.py(7개), test_adaptive_logic.py(7개), test_e2e.py. "확률적이라 테스트가 어렵다는" ML 코드를 어떻게 검증하는지 참고할 만합니다.

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

"300B 파라미터"라는 말에 겁먹지 말 것 — 작은 설정은 평범한 GPU에서도 돈다.

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

읽기만 하면 금방 잊는다. 난이도별로 손을 움직여 보자.

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

이 저장소를 '교과서'로 삼아 6주간 현대 LLM 학습을 정복하는 코스.

10핵심 키워드 사전

이 문서·저장소에 나온 용어를 한 줄씩 정리. 모르면 여기로 돌아오기.

11참고 링크

원본 저장소와, 각 개념을 더 깊이 팔 때의 출발점.