이 저장소가 대체 무엇인가.
딥러닝 책은 "모델(신경망)"을 가르친다. 하지만 실제 세계에서 AI는 데이터 파이프라인·GPU 클러스터·메모리·네트워크·전력·비용·안정성이라는 시스템 위에서 돌아간다. cs249r_book은 바로 이 "모델 바깥의 모든 것"을 다룬다. 데이터 엔지니어링부터 모델 압축, 하드웨어 가속기, 분산 학습, 추론 서빙, 지속가능성(전력)까지.
그리고 저장소를 열어보면 놀란다 — 이건 책 파일 하나가 아니라 거대한 monorepo(단일 저장소)다. 교과서 2권, "직접 만드는 PyTorch"(TinyTorch), 브라우저에서 바로 돌아가는 실습 랩, 아두이노/라즈베리파이 하드웨어 키트, 인프라 병목 시뮬레이터, 강의 슬라이드, 강사용 커리큘럼, AI 독서 튜터가 서로 상호참조하며 한 곳에 들어 있다.
y = f(x) 같은 수학 함수(신경망)를 말하고, 시스템은 그 모델이 실제로 데이터를 받아 학습하고 서비스로 응답하기까지 필요한 전체 인프라 — 데이터 수집·저장, 학습 클러스터, 가속기 하드웨어, 서빙 서버, 모니터링, 비용/전력 관리 — 를 말한다. 이 책의 핵심 주장: 요즘 AI가 실패하는 곳은 대개 "모델"이 아니라 "시스템"이다.수많은 딥러닝 교재 대비 장점 · 트렌딩 이유.
딥러닝 무료 교재는 넘쳐난다(밑바닥부터 시작하는 딥러닝, d2l.ai, fast.ai…). 그런데 cs249r_book이 하버드 + MIT Press 조합으로 특별히 주목받는 이유는 "모델이 아니라 시스템을 가르치는 거의 유일한 정규 교과서"라는 위치 때문이다. 대부분의 책이 "역전파를 어떻게 구현하나"에서 멈출 때, 이 책은 "그 모델을 8-GPU 서버, 나아가 수천 대 클러스터에서 어떻게 굴리나"로 나아간다.
| 기준 | 딥러닝 입문서 (d2l, fast.ai) | MLOps 실무서 | cs249r_book |
|---|---|---|---|
| 초점 | 모델 · 알고리즘 | 배포 도구 레시피 | ✓ 시스템 공학 원리(물리·정량 추론) |
| 범위 | 학습까지 | 파이프라인 도구 | 데이터→학습→압축→하드웨어→분산→서빙→전력 |
| 스케일 | 단일 GPU | 클라우드 위주 | ✓ 단일 머신(1권) → 분산 클러스터(2권) |
| 실습 환경 | Colab 노트북 | 제각각 | ✓ 브라우저 WASM 랩 + 하드웨어 키트 |
| 프레임워크 직접 구현 | 일부 | 없음 | ✓ TinyTorch(20개 모듈로 나만의 PyTorch) |
| 출판 | 일부 종이책 | 상용 | ✓ MIT Press 2026 + 완전 무료 온라인 |
| 다포맷 | 웹/PDF | — | ✓ 웹 + PDF + EPUB + Beamer 슬라이드 |
| 부가 도구 | — | — | ✓ AI 튜터·인프라 시뮬레이터·인터뷰 문제은행 |
캐글에서 정확도 99%를 찍은 모델이 실서비스에 올리면 응답이 느리고, GPU 비용이 폭발하고, 트래픽이 몰리면 죽는다. 원인은 모델이 아니라 메모리 대역폭, 데이터 이동 비용, 배치 전략, 하드웨어 특성, 전력 예산 같은 "시스템" 요인이다. 이 책은 이런 "물리적 제약(constraints)이 아키텍처를 결정한다"는 관점 — 빛의 속도, 열역학, 메모리 이동 비용 — 을 처음부터 훈련시킨다.
내용도 내용이지만, 개발자들이 이 저장소에 몰리는 또 다른 이유는 "책을 소프트웨어처럼 엔지니어링한 방식" 때문이다. 63개의 GitHub Actions 워크플로우, 75개 이상의 커스텀 문서 린트 검사(수식 표기·단위·용어 일관성 자동 검증), 재현 가능한 Docker 빌드, 자체 CLI(binder) — 기술 문서를 이렇게까지 엔지니어링한 사례는 드물다.
"책 한 권"인데 왜 이렇게 많은 기술이 들어갈까.
일반적인 책은 워드나 LaTeX로 쓴다. 그런데 cs249r_book은 실행 가능한 코드 · 웹사이트 · PDF · 슬라이드 · 대화형 실습을 하나의 원본에서 뽑아내야 하므로, 사실상 웹 서비스급 기술 스택을 갖고 있다. 크게 세 층으로 나눠 보자.
| 기술 | 역할 |
|---|---|
| Quarto | 핵심 출판 엔진. .qmd(Quarto Markdown) 원본 하나에서 HTML 웹사이트·PDF·EPUB·Beamer 슬라이드를 동시에 뽑는다. |
| Jupyter (engine) | 책 안의 {python} 코드 블록을 렌더링 시점에 실제로 실행해 그래프·표를 생성. 책의 그림이 "진짜 계산 결과"다. |
| LaTeX / TeX Live | PDF와 Beamer 슬라이드의 조판. 전체 TeX Live를 설치해야 해서 빌드가 무겁다. |
| Lua 필터 | Pandoc/Quarto 확장. inject_quizzes.lua(퀴즈 삽입), sidenote.lua(옆주), dropcap.lua(첫 글자 장식) 등 책 고유 조판 로직. |
| R (reticulate/knitr) | 일부 챕터의 통계 그림을 ggplot2로 그린다. 파이썬과 R이 한 문서 안에서 협업. |
| 기술 | 역할 |
|---|---|
| Python (mlsysbook 패키지) | 모든 자동화의 중심 언어. 빌드·린트·서지 검증·번역·릴리스 스크립트. |
binder CLI | 이 프로젝트의 심장. build·preview·validate·format·bib 검증을 한 명령으로. pre-commit과 CI가 모두 같은 ./book/binder를 호출 → "단일 진실원". |
| 커스텀 린트 75개+ | 수식 표기(× 스타일), 단위, 통화, 백분율, MIT Press 용어, 상호참조 무결성까지 자동 검사. "문서 CI". |
| Rich | CLI의 예쁜 터미널 출력. |
| pytest · black · mypy · flake8 · bandit | 파이썬 코드 품질(테스트 커버리지 80%+ 강제, 엄격 타입 검사, 보안 스캔). |
| Vale · codespell · yamllint | 산문 스타일·오탈자·YAML 문법 린트. |
| 기술 | 역할 |
|---|---|
| GitHub Actions (워크플로우 63개) | 컴포넌트마다 validate-dev → preview-dev → publish-live 3단 생명주기. 링크 부패 감시, 비주얼 스모크 테스트(puppeteer)까지. |
| Docker (Ubuntu 22.04) | Quarto+TeX Live+R+Python을 미리 설치한 빌드 이미지. 매 CI마다 30~45분 걸릴 셋업을 컨테이너로 고정. |
| GitHub Pages + Cloudflare | gh-pages 브랜치의 vol1/·vol2/로 배포하고, Cloudflare가 앞단 CDN·캐시. |
| Marimo + WebAssembly | 실습 랩을 설치 없이 브라우저에서 실행(WASM으로 파이썬을 브라우저에서 구동). |
| 기여자 자동화 봇 | all-contributors, 뉴스레터(Buttondown) 동기화, 다국어 README 표 자동 생성. |
".qmd 원본 하나"가 어떻게 웹사이트·PDF·슬라이드로 갈라지나.
이 프로젝트의 아키텍처를 이해하는 핵심은 "단일 원본(single source) → 다중 포맷(multi-format)"이다. 저자는 같은 내용을 웹용·PDF용·EPUB용으로 세 번 쓰지 않는다. .qmd 파일 하나를 쓰면, 빌드 시스템이 포맷별 설정을 조합해 여러 결과물을 뽑는다.
이 책에는 _quarto.yml이라는 단일 설정 파일이 없다. 대신 book/quarto/config/에 포맷×볼륨 조합별 설정이 흩어져 있고(_quarto-html-vol1.yml, _quarto-pdf-vol2.yml …), 공통 조각은 shared/{base,html,pdf,epub,vol1,vol2}/로 쪼개 두었다. 빌드할 때 필요한 조각을 레고처럼 조합한다. "웹 1권 빌드"면 base + html + vol1 조각을 합치는 식.
피자 주문서 하나에 "도우·소스·토핑"을 매번 새로 쓰지 않고, 공통 도우 레시피는 따로 두고 "오늘은 도우+토마토소스+페퍼로니" 하고 조립하는 것과 같다. 웹/PDF/EPUB이라는 서로 다른 피자를 같은 재료 창고에서 조립한다.
binder CLI)개발자가 직접 quarto render를 치지 않는다. 대신 항상 ./book/binder build, ./book/binder validate를 친다. 중요한 건 pre-commit 훅과 CI가 모두 똑같은 binder를 호출한다는 점이다. 즉 "내 컴퓨터에서 통과한 검사 = CI에서 도는 검사"가 보장된다. 로컬과 CI의 동작 불일치라는 흔한 고통을 원천 차단한 설계다.
보통 책은 사람이 눈으로 교정한다. 이 책은 75개 이상의 자동 검사가 돈다. 예를 들어 "곱셈 기호는 x가 아니라 ×로", "단위와 숫자 사이 공백 규칙", "본문의 상호참조가 실제로 존재하는가"(존재하지 않는 ?@fig-xxx 링크가 하나라도 있으면 빌드 실패). 문서 품질을 코드 CI처럼 강제한다.
441MB monorepo — 무엇이 어디에 있나.
내용(ML 시스템)을 배우려면 book/quarto/contents/vol1/의 챕터들을 순서대로. "이 저장소가 어떻게 만들어졌나"(빌드·자동화)를 배우려면 book/cli/(CLI 설계)와 .github/workflows/(CI 설계)를 뜯어보는 게 압축적이다.
이 저장소에서 실제로 무엇을 배울 수 있는가 — 두 갈래.
이 저장소는 (A) 책 내용 = ML 시스템 지식과 (B) 저장소 구조 = 문서 엔지니어링이라는 두 가지를 동시에 준다. 둘 다 짚는다.
책은 헤네시 & 패터슨(컴퓨터 구조 교과서의 전설)의 방식을 따라 1권=단일 머신, 2권=분산/대규모로 나뉜다.
| 파트 | 챕터 | 배우는 것 |
|---|---|---|
| 기초 | ML Systems / ML Workflow / Data Engineering | 시스템 관점, 워크플로우, 데이터 파이프라인 |
| 개발 | NN 연산 / NN 아키텍처 / 프레임워크 / 학습 | 신경망이 하드웨어에서 실제로 계산되는 방식 |
| 최적화 | 데이터 선택 / 모델 압축 / 하드웨어 가속 / 벤치마킹 | 양자화·프루닝, 가속기(GPU/TPU), 성능 측정 |
| 배포 | 모델 서빙 / MLOps / 책임 있는 공학 | 서빙 인프라, 운영 자동화, 윤리·안전 |
| 파트 | 챕터 | 배우는 것 |
|---|---|---|
| The Fleet | 컴퓨트 인프라 / 네트워크 패브릭 / 데이터 스토리지 | 대규모 클러스터의 하드웨어·네트워크 토대 |
| 분산 ML | 분산 학습 / 집합통신 / 결함 허용 / 플릿 오케스트레이션 | 수천 GPU에 학습을 쪼개고 장애를 버티는 법 |
| 대규모 배포 | 성능 엔지니어링 / 추론 / 엣지 인텔리전스 / 대규모 운영 | 지연·처리량 최적화, 엣지 디바이스 추론 |
| 책임 있는 플릿 | 보안·프라이버시 / 견고한 AI / 지속가능 AI / 책임 AI | 보안, 강건성, 전력·탄소, 거버넌스 |
| 기술 | 배울 것 |
|---|---|
| Quarto 다포맷 출판 | 원본 하나로 웹·PDF·EPUB·슬라이드를 뽑는 "single source" 설계. 기술 블로그·사내 문서에 그대로 응용 가능. |
| 설정 조합(config composition) | 거대한 설정을 조각내고 조립하는 법. 대규모 프로젝트 설정 관리의 정석. |
| 단일 자동화 CLI | pre-commit과 CI가 같은 명령을 쓰게 해 "로컬≠CI" 문제를 없애는 패턴. |
| 문서 CI / 커스텀 린트 | 산문·수식·용어까지 자동 검사하는 법. 팀 문서 품질 관리에 직접 적용. |
| 재현 가능한 Docker 빌드 | 무거운 툴체인을 컨테이너로 고정해 "내 컴퓨터에선 됐는데"를 없애는 법. |
| WASM 브라우저 실행 | Marimo로 설치 없이 브라우저에서 파이썬 실습을 제공하는 최신 기법. |
이 저장소는 "요리책"이면서 동시에 "그 요리책을 인쇄·번역·배포하는 출판사 시스템 전체"를 공개한 셈이다. 요리(ML 시스템)를 배우러 왔다가, 출판사 운영법(문서 엔지니어링)까지 덤으로 배운다.
그냥 읽기 vs 직접 빌드하기 — 요구가 하늘과 땅.
| 목적 | 요구사항 |
|---|---|
| 그냥 읽기 (권장) | 웹브라우저만. mlsysbook.ai 접속이면 끝. 설치 0. |
| 실습 랩 돌리기 | 브라우저(Marimo/WASM). 파이썬 설치 불필요 — 브라우저 안에서 실행. |
| 하드웨어 키트 | Arduino Nano 33 BLE / Seeed / Raspberry Pi 등 실물 보드(선택). |
| TinyTorch 실습 | 로컬 Python 3.10+ 환경. |
| 책 직접 빌드 | 무겁다: Quarto + 전체 TeX Live + R + Python + (권장) Docker. 첫 셋업 30~45분. 그래서 공식 Docker 이미지를 제공한다. |
전체 빌드는 LaTeX·R·Python 툴체인이 다 필요해 환경 구성만으로 지친다. 학습이 목적이면 웹사이트로 읽는 게 정답이다. 빌드는 "이 프로젝트의 엔지니어링을 공부하고 싶을 때" 공식 Docker 이미지로 접근하자.
난이도별 5개 — 읽기만 하지 말고 손을 움직여보자.
웹사이트에서 1권 첫 챕터를 읽고, 본문 곳곳의 Self-Check Question 콜아웃을 스스로 풀어본다. "모델과 시스템의 차이"를 자기 말로 3문장 정리하면 성공.
labs/의 실습 하나를 브라우저에서(설치 없이) 끝까지 돌려본다. 파라미터를 바꿔가며 결과가 어떻게 변하는지 관찰 — "WASM으로 파이썬이 브라우저에서 도는" 경험 자체가 배울 거리.
tinytorch/의 초반 모듈(텐서·autograd 기초)을 직접 채워 "나만의 미니 PyTorch"를 만든다. 역전파가 블랙박스가 아니게 되는 순간을 경험한다.
book/cli/commands/validate.py와 .github/workflows/book-*.yml을 읽고, "커밋 → 검증 → 프리뷰 → 배포"가 어떻게 연결되는지 다이어그램으로 그려본다. 커스텀 린트 검사 하나를 골라 로직을 설명해보자.
이 저장소의 아이디어를 훔쳐, 내 블로그/사내 문서 저장소에 pre-commit + 간단한 링크·용어 린트를 붙여본다. Quarto 다포맷 출판을 작은 규모로 재현해보면 이해가 완성된다.
이 책을 축으로 6주 학습 계획.
| 주차 | 학습 내용 | 산출물 |
|---|---|---|
| 1주차 | 1권 기초 파트(ML Systems·Workflow·Data Engineering) 정독. "모델 vs 시스템" 관점 장착. | D·A·M 개념도 1장 |
| 2주차 | 1권 개발 파트(NN 연산·프레임워크·학습). TinyTorch 모듈 1~5 병행 구현. | 미니 autograd 동작 |
| 3주차 | 1권 최적화 파트(모델 압축·하드웨어 가속·벤치마킹). 양자화/프루닝 실습 랩. | 모델 크기 축소 리포트 |
| 4주차 | 1권 배포 파트(서빙·MLOps·책임 공학) + mlsysim으로 병목 시뮬레이션. | 서빙 지연 분석 |
| 5주차 | 2권 The Fleet + 분산 ML(분산 학습·집합통신·결함 허용). 대규모 관점 확장. | 분산 학습 개념 정리 |
| 6주차 | 2권 대규모 배포 + 책임 있는 플릿(보안·지속가능·책임 AI). 엔지니어링 관점으로 binder/CI 분석. | 문서 CI 이식 실습 |
이 책이 하드웨어(메모리 계층·병렬성)를 자주 짚기 때문에, 컴퓨터 구조 기초가 있으면 훨씬 잘 읽힌다. 반대로 이 책으로 "구조가 왜 AI에서 중요한지" 동기부여를 얻고 구조 공부로 넘어가는 것도 좋은 순서다.
이 저장소를 읽을 때 자주 나오는 용어.
.qmd)에 코드를 섞어 쓰면 실행 결과와 함께 HTML·PDF·슬라이드 등으로 렌더링해준다. R Markdown의 후계 격.{python}, {r})을 담는다.mlperf-edu는 그 교육용 버전.더 깊이 파고들 자료.
| 자료 | 링크 · 설명 |
|---|---|
| GitHub 저장소 | github.com/harvard-edge/cs249r_book — 소스 전체 |
| 공식 웹사이트 | mlsysbook.ai — 책을 온라인으로 읽기(무료) |
| Quarto 공식 | quarto.org — 다포맷 출판 시스템 문서 |
| Marimo | marimo.io — 반응형 파이썬 노트북 |
| MLCommons / MLPerf | mlcommons.org — ML 벤치마크 표준 |
| 비교 학습서 | d2l.ai — "Dive into Deep Learning"(모델 중심 대비용) |