How Deep Learning Computes

nano-vLLM 만들어보기

이 경로는 vLLM을 읽기만 하지 않고, 작은 버전의 serving engine을 직접 만드는 경로입니다.

목표는 production vLLM을 복제하는 것이 아닙니다. 먼저 한 파일짜리 naive loop를 만들고, 그 다음 request state, scheduler, prefill/decode split, continuous batching, paged KV cache, model runner boundary, prefix cache, sampling params, tiny Transformer runner를 하나씩 추가합니다.

각 단계의 코드는 labs/nano-vllm/versions/ 아래에 snapshot으로 남깁니다. 중복 코드는 의도적입니다. 독자가 이전 버전을 잃지 않고, 매 카드에서 정확히 무엇이 바뀌었는지 확인하게 만드는 것이 목표입니다.

이 path가 끝나면 다음 질문에 답할 수 있어야 합니다.

다음 GPU step에 어떤 request와 token을 태울 것인가?
그 token의 KV cache는 어디에 쓸 것인가?
완료된 token은 어떻게 request state와 output stream에 반영되는가?
  1. 추론 엔진의 세 층 — vLLM과 SGLang 같은 LLM 추론 엔진을 API, scheduler core, GPU worker로 나누어 이해한다.
  2. nano-vLLM Minimal Architecture — 작은 serving engine을 API, engine core, worker 세 층으로 나누고 최소 구현 범위를 정한다.
  3. nano-vLLM Snapshot Code Strategy — 최종 코드만 만들지 않고 단계별 실행 가능한 snapshot을 남기는 이유와 디렉토리 구조를 정한다.
  4. v00 Naive Generate Loop — request object, scheduler, KV cache 없이 한 prompt에서 token을 반복 생성하는 가장 작은 loop를 만든다.
  5. v01 Request State — prompt, generated tokens, max_tokens를 `Sequence` 객체로 묶어 engine이 다룰 request 상태를 만든다.
  6. v02 Engine Step Loop — `add_request`, `step`, `generate`를 가진 작은 `LLMEngine`을 만들고 request lifecycle을 드러낸다.
  7. v03 Prefill / Decode Split — prompt를 처리하는 prefill과 다음 token을 생성하는 decode를 분리해 serving engine의 핵심 축을 만든다.
  8. v04 Continuous Batching — waiting/running queue와 scheduler를 추가해 여러 request의 decode step을 batch로 묶는다.
  9. v05 Paged KV Cache — `BlockManager`와 `block_table`을 추가해 request별 KV cache 위치를 page 단위로 관리한다.
  10. v06 ModelRunner Split — scheduler와 model execution을 분리하고 `prepare_prefill`, `prepare_decode`, `run` contract를 만든다.
  11. v07 Prefix Cache — shared prefix를 가진 request들이 완성된 KV block을 재사용하도록 block hash와 ref count를 추가한다.
  12. v08 Sampling Params — logits를 token으로 바꾸는 sampling layer를 분리하고 temperature, top-k, deterministic seed를 추가한다.
  13. v09 Tiny Transformer Runner — toy token rule을 제거하고 작은 PyTorch Transformer에서 logits를 받아 sampling하는 runner로 바꾼다.
  14. v10 Original Mapping Report — 실습 snapshot 전체를 원본 nano-vLLM의 파일과 역할에 대응시키는 읽기 리포트를 작성한다.
  15. nano-vLLM Original Code Map — 실습 snapshot에서 만든 개념을 원본 nano-vLLM의 파일과 함수에 대응시킨다.