vllm 딥다이브
— GPU의 빈자리를 줄이는 LLM 서빙의 설계

1프로젝트 한줄 요약

vLLM은 학습된 모델의 가중치를 불러와 텍스트 등을 생성하고, 그 계산을 서버 자원에 맞춰 배분하는 시스템입니다. Python에서 LLM.generate()를 부르는 라이브러리로도, vllm serve로 실행하는 API 서버로도 쓸 수 있습니다. 이 저장소에서 배울 핵심은 모델의 정답을 바꾸는 법보다, 같은 모델로 더 많은 요청을 효율적으로 처리하는 법입니다.

1-1. 입력부터 출력까지 여섯 단계

1. 사용자가 문자열이나 대화 메시지를 보냅니다.
2. 렌더러와 토크나이저가 모델이 이해하는 토큰 ID로 바꿉니다.
3. 스케줄러가 이번 반복에서 계산할 요청과 토큰 수를 고릅니다.
4. KV 캐시 관리자가 필요한 블록을 확보합니다.
5. 실행기가 모델을 계산하고, 샘플러가 다음 토큰을 선택합니다.
6. 출력 처리기가 토큰을 문자열로 복원하고 호출자에게 전달합니다.

첫 진입점은 vllm/entrypoints/llm.py의 LLM.generate()입니다. 공식 예제 examples/basic/offline_inference/basic.py도 LLM과 SamplingParams를 사용합니다. 아래는 같은 API를 작은 모델에 적용한 학습용 예시입니다.

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-0.6B", max_model_len=2048)
params = SamplingParams(temperature=0.0, max_tokens=64)
outputs = llm.generate(["KV 캐시를 쉬운 비유로 설명해 줘."], params)

for output in outputs:
    print(output.outputs[0].text)

SamplingParams는 출력 길이와 토큰 선택 규칙을 담습니다. 위 코드는 준비된 추론 환경에서 사용하는 예시이며, 생성 문장과 실행 속도는 모델·장치·설정에 따라 달라집니다. 오프라인 추론은 HTTP 서버 없이 함수로 결과를 받는 방식입니다.

2왜 주목받는가

2-1. 주간 트렌딩 순위와 기술적 배경을 구분하기

vLLM은 2026-10-23 분석 기준 GitHub Trending Python Weekly #14로 선정된 저장소입니다. 스타 95,202개와 포크 23,834개는 넓은 관심과 활용의 신호입니다. 다만 그 숫자만으로 이번 주의 유입 원인을 특정할 수는 없습니다. 다음 세 가지는 현재 기능과 소스 구조에서 읽을 수 있는 주목할 만한 기술적 이유입니다.

• 메모리 효율: 길이가 다른 요청의 KV 캐시를 블록 단위로 관리해 큰 연속 공간을 미리 잡는 부담을 줄입니다.
• 연속 배칭: 생성이 끝난 요청을 빼고 새 요청을 받아 GPU의 다음 반복에 참여시킵니다.
• 통합된 서빙 계층: 모델 로딩, HTTP API, 관측 지표, 여러 장치의 실행 경로가 한 체계로 연결됩니다.

큰 모델의 서빙에서는 계산을 빠르게 하는 일과, 계산할 요청을 잘 모으고 메모리를 덜 낭비하는 일이 함께 중요합니다. 커밋 f4edf9f의 제목은 Intel XPU의 커널·샘플러 단위 테스트 활성화입니다. 이는 장치별 실행 경로를 검증하는 개발이 진행 중이라는 사례이며, 주간 트렌딩의 직접 원인이라는 뜻은 아닙니다.

2-2. 비교할 때는 공통 기능보다 선택의 초점을 보기

비교 근거는 llama.cpp 공식 저장소와 NVIDIA의 TensorRT LLM 소개입니다. TensorRT LLM도 in-flight batching과 paged KV cache를 지원합니다. 따라서 이 개념들을 vLLM만의 독점 기능으로 외우면 안 됩니다.

2-3. 초기 성능 수치를 현재의 보장으로 읽지 않기

2023년 공식 소개 글은 특정 GPU·모델·데이터 조건에서 Hugging Face Transformers와 TGI 대비 높은 처리량을 보고했습니다. 그 결과는 PagedAttention의 배경을 이해하는 자료입니다. 2026년의 모든 모델에서 같은 배수가 나온다는 근거로 사용할 수는 없습니다.

3기술 스택 전체 지도

pyproject.toml은 Python 배포와 빌드의 출발점입니다. dependencies가 dynamic으로 선언되어 있어 의존성 전체가 이 파일 안에 나열되지는 않습니다. setup.py의 get_requirements()가 대상 장치에 맞는 requirements/cuda.txt·requirements/cpu.txt·requirements/xpu.txt 등을 읽습니다.

3-1. 백엔드와 모델 실행 계층

vLLM은 Python으로 계산 순서를 정하지만, 실제 텐서 연산은 PyTorch와 장치별 커널에 맡기는 여러 계층의 시스템입니다. vllm/model_executor/models/llama.py의 LlamaAttention.forward()를 보면 Q·K·V 투영, 회전 위치 임베딩, Attention 호출이 연결됩니다. Hugging Face 가중치와 호환되는 자체 추론용 모델 구현이므로, 단순히 외부 모델의 생성 함수를 감싼 구조보다 깊습니다.

3-2. 프런트엔드: 여기서는 HTTP 요청을 받는 계층

이 저장소에서 프런트엔드라는 말은 주로 추론 엔진 앞의 API 처리 계층을 가리킵니다. 루트에는 package.json이 없으며 React나 Vue 기반의 일반 사용자용 웹 화면을 주 구성요소로 두지 않습니다. 따라서 웹 UI를 찾기보다 라우터·렌더러·토크나이저·스트리밍 처리를 읽는 편이 목적에 맞습니다.

rust/README.md는 Rust 프런트엔드를 실험적이며 기능이 완전하지 않은 대안으로 명시합니다. VLLM_USE_RUST_FRONTEND=1로 선택하는 경로도 Python 엔진과 ZMQ 경계를 통해 통신합니다. Rust가 존재한다고 Python 추론 엔진 전체가 Rust로 교체되었다고 해석하면 안 됩니다.

3-3. 인프라와 빌드: Python 패키지 안에 네이티브 산출물 넣기

docker/Dockerfile은 rust-build, csrc-build, extensions-build, build 등을 나눕니다. 서버 이미지인 vllm-openai 단계의 진입점은 ["vllm", "serve"]입니다. 컴파일 도구가 필요한 단계와 실제 서버 실행 단계를 나누는 컨테이너 설계를 배울 수 있습니다.

3-4. CI도 장치별로 설계되어 있다

.github/workflows/pre-commit.yml은 Python 3.12에서 저장소 전체 정적 검사를 수행하도록 구성합니다. 하드웨어 테스트는 .buildkite/ci_config.yaml의 .buildkite/image_build/·.buildkite/test_areas/·.buildkite/hardware_tests/ 경로로 나뉩니다. 공통 의존성이나 csrc/ 변경은 넓은 테스트를 실행하는 패턴에 포함됩니다.

.buildkite/intel_jobs/samplers_intel.yaml에는 VLLM_TEST_DEVICE=xpu와 VLLM_XPU_USE_SAMPLER_KERNEL=1이 등장합니다. 같은 샘플링 동작도 장치 경로를 실제로 선택해야 검증된다는 의미입니다. 테스트 명령이 있다는 사실과 특정 실행에서 테스트가 통과했다는 사실은 구분해야 합니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조도

아래는 일반적인 Python 온라인 서빙 경로를 단순화한 그림입니다. 실제 프로세스 수와 실행기는 병렬화·장치·실행 설정에 따라 달라집니다. Rust 프런트엔드를 선택하는 경우에는 그림 맨 위의 API 처리 계층이 달라집니다.

vllm/entrypoints/openai/chat_completion/api_router.py의 create_chat_completion()은 처리 결과의 종류에 따라 JSON 응답이나 text/event-stream 응답을 반환합니다. OpenAIServingChat._create_chat_completion()은 render_chat_request()로 입력을 준비한 뒤 engine_client.generate()를 호출합니다.

4-2. 반복의 중심: EngineCore.step()

vllm/v1/engine/core.py의 EngineCore.step()은 스케줄링·실행·결과 반영을 한 반복으로 묶습니다. 아래는 핵심 호출 순서를 보존하고 계측·문법 처리 등을 생략한 학습용 축약입니다.

# vllm/v1/engine/core.py: EngineCore.step()의 흐름
scheduler_output = self.scheduler.schedule(self._should_throttle_prefills())
future = self.model_executor.execute_model(scheduler_output, non_block=True)
grammar_output = self.scheduler.get_grammar_bitmask(scheduler_output)
model_output = future.result()

# 실행 경로에 따라 샘플링이 별도 호출일 수 있음
if model_output is None:
    model_output = self.model_executor.sample_tokens(grammar_output)

self._process_aborts_queue()
outputs = self.scheduler.update_from_output(scheduler_output, model_output)

non_block=True라고 지정해도 곧바로 모든 결과가 준비되는 것은 아닙니다. 이 경로에서는 future.result()로 결과를 기다립니다. 별도의 step_with_batch_queue()도 있으므로 이 축약을 모든 실행 모드의 유일한 시간표로 이해하면 안 됩니다.

4-3. 설계 패턴 ① 비동기 스트림과 프로세스 경계

vllm/v1/engine/async_llm.py의 AsyncLLM.generate()는 add_request()로 요청을 등록하고 요청별 수집기에서 결과를 꺼내 yield합니다. 별도의 출력 처리 루프가 엔진 결과를 요청별 수집기에 전달합니다. API 요청을 받는 속도와 GPU가 토큰을 만드는 속도를 연결하는 구조입니다.

# AsyncLLM.generate()의 핵심 구조를 줄인 예시
q = await self.add_request(request_id, prompt, sampling_params)
finished = False
while not finished:
    out = q.get_nowait() or await q.get()
    finished = out.finished
    yield out

# 원본은 취소·오류 분기와 종료 표지도 별도로 처리함

이 함수의 asyncio.CancelledError·GeneratorExit 처리에서는 등록된 요청을 abort()합니다. 연결이 끊어진 사용자를 위해 계속 GPU를 쓰지 않도록, 전송 계층의 취소를 엔진의 작업 정리와 연결합니다. 다른 비동기 서버에서도 유용한 자원 수명 관리 패턴입니다.

4-4. 설계 패턴 ② 토큰 예산으로 통합한 스케줄링

vllm/v1/core/sched/scheduler.py의 Scheduler.schedule()은 각 요청의 num_computed_tokens를 필요한 토큰 수에 가까워지도록 진행시킵니다. 함수 주석도 스케줄러 내부에서 prefill과 decode를 별개 단계로 고정하지 않는다고 설명합니다. 이 관점으로 긴 입력의 분할 처리와 추측 토큰 검증을 같은 예산 체계에 담습니다.

# 실행 중인 요청을 배분하는 부분의 축약
num_new_tokens = (
    request.num_tokens_with_spec
    + request.num_output_placeholders
    - request.num_computed_tokens
)
num_new_tokens = min(num_new_tokens, token_budget, input_budget - draft_slots)
# 원본에는 긴 입력 제한, 모델 길이 제한, 인코더 예산 등이 추가됨
new_blocks = self.kv_cache_manager.allocate_slots(request, num_new_tokens)
# 성공한 요청의 배분을 반영하는 단계
token_budget -= num_new_tokens

작은 예: 한 반복의 예산을 8토큰이라고 가정해 봅시다. 실행 중인 A와 B가 각각 다음 1토큰을 계산한다면 6토큰이 남습니다. 긴 입력을 가진 C는 그 6토큰만 먼저 계산하고 나머지를 뒤로 넘길 수 있습니다. 이는 개념 예시이며 실제 배분에는 캐시, 인코더, 우선순위와 장치 제약이 함께 작용합니다.

블록 확보에 실패하면 실행 중인 요청을 선점하는 분기가 있습니다. Scheduler._preempt_request()는 블록을 정리하고 상태를 PREEMPTED로 바꾼 뒤 num_computed_tokens=0으로 되돌려 대기열에 넣습니다. 다시 계산할 비용이 생길 수 있으므로 선점을 많이 한다고 효율적인 것은 아닙니다.

4-5. 설계 패턴 ③ 블록 풀과 내용 기반 캐시 재사용

vllm/v1/core/kv_cache_manager.py의 KVCacheManager는 요청별 캐시 배치와 슬롯 확보를 조율하고, vllm/v1/core/block_pool.py의 BlockPool은 실제 블록 메타데이터의 할당·반납·캐시 퇴거를 관리합니다. 큰 메모리 문제를 여러 작은 블록의 수명 관리로 바꾸는 설계입니다.

vllm/v1/core/kv_cache_utils.py의 KVCacheBlock에는 block_id, ref_cnt, block_hash, 자유 블록 연결 정보가 있습니다. BlockPool.get_new_blocks()는 자유 큐에서 블록을 꺼내 참조 수를 늘리고, free_blocks()는 참조 수를 줄여 0이 된 블록을 재사용 대상으로 돌립니다. 반납된 캐시 블록이 곧바로 지워지는 것은 아닙니다.

접두사 캐시는 단순히 문자열 몇 글자가 같은지 비교하지 않습니다. hash_block_tokens()는 이전 블록의 해시, 현재 토큰 ID 묶음, 추가 키를 함께 해시합니다. 앞 문맥이 달라지면 같은 토큰 묶음이라도 다른 계산 상태가 되기 때문입니다.

# vllm/v1/core/kv_cache_utils.py: hash_block_tokens()
curr_block_token_ids_tuple = tuple(curr_block_token_ids)
return BlockHash(
    hash_function((parent_block_hash, curr_block_token_ids_tuple, extra_keys))
)

KVCacheManager.get_computed_blocks()는 가장 긴 캐시 적중 구간을 찾습니다. 이 함수는 다음 토큰의 점수를 얻기 위해 마지막 토큰을 다시 계산하도록 최대 적중 길이를 request.num_tokens - 1로 제한합니다. 블록 정렬 제약 때문에 한 토큰보다 많은 부분을 다시 계산할 수도 있다는 주석도 있습니다.

해시 기본값은 CacheConfig.prefix_caching_hash_algo="sha256"입니다. generate_block_hash_extra_keys()에서는 LoRA·멀티모달 입력 등 추가 문맥을 고려합니다. 따라서 같은 화면상의 문장이라고 언제나 캐시가 공유된다고 단정하면 안 됩니다.

KV 캐시 최적화의 핵심은 기억할 내용을 바꾸는 것이 아니라, 같은 중간 상태를 안전하게 공유하고 필요한 공간만 확보하는 것입니다. 고전적인 PagedAttention의 블록 관리 아이디어와, 현재 선택 가능한 FlashAttention·FlashInfer 등의 실제 계산 백엔드는 구분해서 이해하세요. 모든 모델이 같은 캐시 형식이나 같은 커널을 쓰는 것은 아닙니다.

4-6. 설계 패턴 ④ 인터페이스로 분리한 실행 전략

vllm/v1/executor/abstract.py의 Executor.get_class()는 distributed_executor_backend 값에 따라 실행기를 고릅니다. uni는 UniProcExecutor, mp는 MultiprocExecutor, ray는 RayExecutorV2로 이어집니다. 스케줄러가 직접 모든 장치 실행 방식을 구현하지 않게 만드는 전략 선택 구조입니다.

GPU 쪽에서는 vllm/v1/worker/gpu_worker.py의 Worker.execute_model()과 vllm/v1/worker/gpu/model_runner.py의 GPUModelRunner.execute_model()을 따라가면 됩니다. 별도 지정이 없고 Triton·기능 지원 조건을 만족하면 V2 실행기가 선택되며, 조건에 따라 vllm/v1/worker/gpu_model_runner.py의 V1 구현으로 전환됩니다. 처음부터 커널 전체를 읽기보다 입력으로 받은 스케줄 결과가 어떤 텐서와 블록 테이블로 바뀌는지 추적하세요. 제어 정책과 계산 구현을 분리하는 이유가 드러납니다.

5디렉토리 구조 해부

트리 맨 위의 vllm/은 저장소를 나타내는 표기이고, 그 안의 vllm/이 Python 패키지입니다. 실제 파일 경로는 vllm/v1/engine/core.py처럼 저장소 루트 기준으로 읽으면 됩니다. v1은 엔진 계층의 이름이며 설치 패키지의 릴리스 번호와는 별개입니다.

tests/는 Python 2,227개 파일·779,412줄, vllm/ 패키지는 Python 2,929개 파일·1,136,955줄입니다. 주석·빈줄을 포함한 물리적 줄 수이므로 이를 테스트 커버리지나 품질 점수로 환산하면 안 됩니다. 처음 읽을 때는 구현 하나와 그 구현의 테스트를 짝지어 선택하는 편이 효과적입니다.

6학습 포인트 (기술별)

6-1. Python 타입과 데이터 계약

Scheduler.schedule()의 반환형은 SchedulerOutput입니다. 스케줄러가 텐서를 직접 계산하지 않고 “어떤 요청의 몇 토큰을 계산할지”를 자료 구조로 전달한다는 점에 주목하세요. vllm/v1/core/sched/output.py와 vllm/v1/outputs.py를 나란히 읽으면 실행 전 계획과 실행 후 결과가 서로 다른 계약이라는 사실이 보입니다.

실습 아이디어: 두 자료형에서 요청 ID·토큰 수·새 블록 정보를 찾아 표로 옮기세요. 그다음 필드 하나가 빠지면 어느 계층이 다음 작업을 할 수 없게 되는지 설명해 보세요.

6-2. 비동기 Python과 요청 수명

AsyncLLM.generate()는 비동기 생성기로 결과를 여러 번 반환합니다. 등록 → 대기 → 여러 번 출력 → 종료와, 등록 → 취소 → 정리의 두 경로를 구분해 읽으세요. 정상 경로만 빠른 서버보다 실패한 요청의 자원까지 회수하는 서버가 운영에서 더 예측 가능합니다.

실습 아이디어: 요청 하나의 상태를 종이에 그린 뒤 CancelledError가 어느 위치에서 발생해도 정리할 수집기와 엔진 요청이 무엇인지 표시하세요.

6-3. 자료 구조와 메모리 관리

KVCacheBlock의 참조 수와 자유 큐는 객체 풀의 구체적인 사례입니다. 블록이 “요청에 사용 중”인지, “재사용 가능한 캐시”인지, “새 내용으로 덮어써도 되는 공간”인지 구분하는 기준을 찾아보세요. 해시 인덱스에 남아 있다는 사실과 사용 중이라는 사실은 같지 않습니다.

실습 아이디어: 블록 세 개를 두 요청이 나누어 쓰는 상황을 만들고, 할당·공유·반납할 때마다 ref_cnt와 자유 큐를 손으로 갱신하세요.

6-4. PyTorch와 병렬화된 모델 계층

vllm/model_executor/models/llama.py에는 QKVParallelLinear, RowParallelLinear, RMSNorm 등이 나타납니다. 일반적인 신경망 레이어에 장치 분할과 추론 최적화가 어떻게 결합되는지 볼 수 있습니다. LlamaAttention.forward()의 Q·K·V 분리부터 읽으면 수식과 코드의 대응이 비교적 분명합니다.

실습 아이디어: 헤드 수를 8개, tensor parallel 크기를 2라고 가정해 각 장치가 담당하는 query 헤드를 그려 보세요. KV 헤드는 개수가 작을 때 복제될 수 있으므로 모든 텐서가 동일하게 반으로 나뉜다고 가정하지 마세요.

6-5. 시스템 관측과 실험 설계

이 이름들은 vllm/v1/metrics/loggers.py에서 확인할 수 있습니다. 평균만 보지 말고 p50·p95 같은 백분위수를 함께 비교하세요. 첫 실행의 모델 로딩·컴파일·그래프 준비 시간과 준비가 끝난 뒤의 요청 지연도 구분해야 합니다.

6-6. 테스트에서 설계 의도를 역으로 읽기

tests/v1/core/test_scheduler.py의 test_preempt_during_execution()은 블록 크기 16, 블록 수 11, 토큰 예산 100 같은 작은 조건으로 선점 상황을 구성합니다. 블록 0이 null 블록으로 예약되어 실제 가용 블록은 10개라는 주석까지 읽어야 계산이 맞습니다. 거대한 모델 없이도 스케줄러의 경계 조건을 설명하는 좋은 독서 자료입니다.

tests/v1/core/test_prefix_caching.py에는 pytest.mark.cpu_test가 있고, .buildkite/test_areas/misc.yaml도 CPU 테스트와 그 외 테스트를 나눕니다. 다만 CPU 표시가 있다고 의존성 설치 없이 모든 테스트가 독립 실행된다는 뜻은 아닙니다.

좋은 소스 독서는 함수 이름을 외우는 일이 아니라, 입력·출력·자원 소유자·실패 시 정리 규칙을 설명할 수 있게 되는 일입니다. 이 네 가지를 한 장에 정리하면 처음 보는 분산 시스템도 훨씬 덜 막막해집니다.

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

7-1. 코드 읽기와 모델 실행에 필요한 것을 구분하기

Python 패키지가 지원하는 전체 버전 범위와 특정 장치 wheel이 제공되는 범위는 같지 않습니다. 장치 이름 하나만 확인하지 말고 OS·Python·PyTorch·드라이버·커널의 조합을 확인하세요. 기본 CUDA 패키지 하나가 모든 GPU와 CPU 환경을 동시에 해결하지는 않습니다.

7-2. 메모리는 가중치와 KV 캐시를 더해 생각하기

가중치 메모리의 거친 하한은 파라미터 수 × 파라미터당 바이트입니다. 예를 들어 70억 파라미터를 2바이트로 저장하면 약 14GB, 즉 약 13.0GiB입니다. 이는 가중치만의 계산입니다. 실행 중간 텐서, 그래프, 통신 버퍼, KV 캐시와 할당 여유가 추가됩니다.

# 일반적인 decoder의 full attention, 단일 요청에 대한 근사식
KV 바이트 ≈ 2 × 레이어 수 × KV 헤드 수 × 헤드 차원
             × 저장 토큰 수 × 원소당 바이트

# 예시: 32층, KV 헤드 8개, 차원 128, 4096토큰, 2바이트
2 × 32 × 8 × 128 × 4096 × 2 = 536,870,912바이트
                           = 512MiB

이 예시에서 서로 캐시를 공유하지 않는 요청 8개라면 KV 데이터만 약 4GiB입니다. 실제 사용량은 블록 단위 반올림, 병렬화, 자료형과 모델 구조에 따라 달라집니다. sliding window, MLA, Mamba 같은 구조에는 위 공식을 그대로 적용할 수 없습니다.

7-3. 현재 기본값을 그대로 운영 정답으로 외우지 않기

vllm/config/cache.py의 gpu_memory_utilization 기본값은 0.92입니다. 이는 모델 실행기에 사용할 장치 메모리 비율이며 KV 캐시만의 비율이나 GPU 연산 사용률이 아닙니다. Worker.determine_available_memory()는 프로파일링으로 캐시에 쓸 수 있는 메모리를 계산합니다. kv_cache_memory_bytes를 직접 지정하는 경로는 이 비율 설정을 따르지 않는다고 명시합니다.

CacheConfig.DEFAULT_BLOCK_SIZE=16은 출발점이며 최종 블록 크기는 백엔드 제약의 영향을 받습니다. SchedulerConfig의 2,048토큰·128시퀀스 기본값도 테스트 편의를 위한 값이라는 주석이 있습니다. 실제 실행 기본값은 vllm/engine/arg_utils.py에서 사용 맥락·장치·모델에 맞춰 조정됩니다.

어떤 모델이 실행되는지는 파라미터 수 하나가 아니라 정밀도·문맥 길이·동시 요청 수·커널·장치 메모리의 조합으로 결정됩니다. 디스크에는 가중치와 다운로드 캐시가, 시스템 RAM에는 로딩·전처리·CPU 경로용 공간이 필요합니다. 모든 모델에 통하는 단일 최소 VRAM·RAM 수치를 제시하기 어려운 이유입니다.

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

과제 1은 GPU와 설치 없이 할 수 있습니다. 과제 2~5는 7절의 장치별 설치 조건을 만족하는 별도 학습 환경을 전제로 합니다. 실행 예시는 기본 Python 프런트엔드와 작은 생성 모델을 기준으로 하며, 학습 결과에는 패키지 버전·모델 revision·장치·정밀도·길이 설정을 함께 기록하세요.

vllm serve Qwen/Qwen3-0.6B \
  --host 127.0.0.1 --port 8000 \
  --served-model-name study-model \
  --max-model-len 2048 \
  --max-num-seqs 8 --max-num-batched-tokens 2048 \
  --gpu-memory-utilization 0.80

curl -N http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "study-model",
    "messages": [{"role": "user", "content": "캐시의 역할을 설명해 줘."}],
    "max_tokens": 128,
    "stream": true
  }'

vllm bench serve \
  --backend openai --endpoint /v1/completions \
  --model study-model --tokenizer Qwen/Qwen3-0.6B \
  --dataset-name random \
  --random-input-len 128 --random-output-len 64 \
  --num-prompts 40 --request-rate 4 \
  --metric-percentiles 50,95 --ignore-eos

성능 실습의 결과물은 빠르다는 감상이 아니라, 조건을 고정한 표와 그 차이를 설명하는 가설이어야 합니다. 캐시·배치·유입률을 한꺼번에 바꾸면 어떤 설정이 영향을 주었는지 알기 어렵습니다. 한 번에 한 축을 바꾸고 예외와 실패도 기록하세요.

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

첫 목표는 거대한 엔진을 다시 만드는 것이 아니라, 각 계층의 책임을 설명하고 작은 실험으로 설계 이유를 확인하는 것입니다. GPU가 없다면 1~4주와 7~8주의 설계·소스 과제부터 진행할 수 있습니다.

9-1. 그다음에는 관심에 따라 가지를 고르기

• 백엔드 개발: ASGI·요청 취소·대기열 제한·Prometheus 지표를 묶어 작은 생성 API를 설계합니다.
• 시스템 개발: 블록 풀의 참조 수와 캐시 퇴거 정책을 작은 독립 모형으로 구현하고 불변 조건을 확인합니다.
• ML 시스템: PyTorch 텐서 형태·양자화·Attention 백엔드 선택을 연결해 어떤 제약이 속도를 결정하는지 분석합니다.
• 분산 인프라: 병렬화 종류마다 분할되는 대상과 통신 비용, 실패 시 복구할 상태를 정리합니다.

10핵심 키워드 사전

이 단어들은 서로 연결됩니다. 연속 배칭을 많이 활용하려면 충분한 KV 공간이 필요하고, 캐시와 양자화로 공간을 아껴도 장치 간 통신이나 긴 대기열이 새 병목이 될 수 있습니다. 한 기능 이름보다 전체 실행 흐름을 기준으로 이해하세요.

11참고 링크

11-1. 공식 자료와 관련 기술

• vLLM 공식 저장소 — 개요·이슈·기여 안내
• vLLM 공식 문서 — 설치·모델·기능·CLI 설명. 최신 문서는 계속 바뀝니다.
• v0.32.0 릴리스 — 안정 릴리스의 배포 범위 확인
• PagedAttention 논문 — 가상 메모리의 아이디어를 KV 캐시에 적용한 배경
• 2023년 vLLM 공식 소개 — 초기 설계와 당시의 벤치마크 조건
• PyTorch 공식 저장소 — 텐서·컴파일·분산 실행을 더 깊이 읽을 출발점
• FlashInfer 공식 저장소 — 추론용 GPU 커널 생태계
• llama.cpp 공식 저장소 · TensorRT LLM 공식 소개 — 다른 추론 엔진과 설계 초점 비교

11-2. 커밋 f4edf9f에서 바로 읽을 파일

• pyproject.toml · requirements/common.txt · requirements/cuda.txt — 패키지와 의존성 선언
• 채팅 API 라우터 · AsyncLLM — 요청 진입과 결과 스트림
• EngineCore · Scheduler — 반복과 토큰 배분
• KVCacheManager · BlockPool · 캐시 블록·해시 — 메모리 관리의 세 층
• LLaMA 모델 구현 · Executor 인터페이스 — 모델 계층과 실행 전략
• 캐시 설정 · 엔진 인자 조립 — 기본값이 최종 설정이 되는 과정
• 스케줄러 테스트 · 실제 지표 정의 — 경계 조건과 관측
• Dockerfile · Rust 프런트엔드 안내 · Buildkite 구성 — 배포와 검증의 경계

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

코드 규모는 커밋 f4edf9f의 Git 추적 파일을 확장자별로 나누고 각 파일의 줄바꿈 문자 수를 합산한 물리적 줄 수입니다. 주석·빈줄·테스트 fixture·추적된 외부 코드가 포함되며, 순수 구현량이나 실행 성능을 뜻하지 않습니다. 전체 커밋 수·기여자별 비중은 이 규모 표의 집계 대상에 포함하지 않습니다.