tokenspeed 딥다이브
— GPU를 기다리게 하지 않는 추론 엔진의 설계

1프로젝트 한줄 요약

TokenSpeed는 공개 LLM의 가중치를 불러와 여러 사용자의 생성 요청을 처리하는 추론·서빙 엔진입니다. 모델의 지식을 새로 학습시키는 것이 주목적은 아닙니다. 같은 모델로도 요청을 묶는 방법, 캐시를 보관하는 방법, GPU 연산을 호출하는 방법에 따라 응답 속도와 처리량이 달라집니다.

이 저장소의 핵심은 모델 계산을 빠르게 만드는 일과, 그 계산이 멈추지 않도록 준비하는 일을 함께 설계한다는 점입니다. Python만 읽어도 입구를 이해할 수 있지만, 중요한 결정은 C++과 GPU용 DSL까지 이어집니다.

1-1. 답변 생성에는 성격이 다른 두 구간이 있다

1-2. 사용자에게 보이는 명령과 내부 구조

python/pyproject.toml은 tokenspeed와 ts를 같은 CLI 진입점에 등록합니다. python/tokenspeed/cli/serve_smg.py의 설명에 따르면 ts serve는 SMG 게이트웨이와 gRPC 엔진을 함께 기동하고, --headless는 외부 프론트엔드가 연결할 엔진만 기동합니다.

# 공식 시작 가이드의 실행 형태를 읽는 예시
tokenspeed serve openai/gpt-oss-20b \
  --host 127.0.0.1 \
  --port 8000 \
  --tensor-parallel-size 1

# 모델 이름 → 가중치·토크나이저 선택
# host·port → 서비스 접점, tensor-parallel-size → 연산 분할 폭

이 명령은 사용 형태를 보여 주는 예시입니다. 실제 기동에는 지원 가속기와 설치 환경, 모델 파일이 필요합니다. 먼저 AsyncLLM.generate_request()가 요청을 받고, 스케줄러 계획과 GPU 실행을 거쳐 응답을 내보내는 흐름부터 이해해 봅시다.

2왜 주목받는가

2-1. 에이전트 작업은 한 번의 질문으로 끝나지 않는다

코딩 에이전트는 코드와 도구 결과를 읽고, 답을 생성하고, 다시 도구 결과를 받는 과정을 반복합니다. 대화가 길어질수록 입력이 커지고 공통 접두부가 늘어나므로 캐시 재사용과 응답 지연이 중요해집니다. TokenSpeed의 README는 이런 에이전트 작업 부하를 주된 대상으로 밝힙니다.

저장소에도 이를 구체화한 실험이 있습니다. test/agentic_benchmark/Qwen3.8-Flash-Next/README.md는 첫 프롬프트를 최대 50,000토큰, 이후 사용자 입력 증가를 최대 800토큰으로 조정하고, 동시성 1·2·4·8·16·32에서 각각 측정합니다. 각 턴의 출력은 ignore_eos=true로 500토큰을 생성하도록 설정합니다.

이 실험은 대화를 재생하는 서빙 벤치마크입니다. 문서도 생성된 도구 호출을 실제 실행하지 않는다고 명시합니다. 따라서 이 수치를 에이전트의 문제 해결률이나 실제 개발 업무의 완료 시간으로 해석하면 안 됩니다.

2-2. 화제의 근거와 해석의 범위

이런 개발 방향은 트렌딩을 이해하는 배경입니다. 각 요인이 스타 증가에 얼마나 영향을 주었는지는 공개 코드만으로 알 수 없습니다. README의 “빛의 속도”라는 표현도 물리적 보장이 아니라 프로젝트의 성능 지향을 나타내는 문구입니다.

2-3. 경쟁 제품과 비교할 때 볼 축

비교 근거는 vLLM 공식 개요와 TensorRT-LLM 공식 Attention 문서입니다. 배칭·양자화·캐시가 TokenSpeed만의 기능인 것은 아닙니다. 위 표는 설계와 학습 관점의 비교입니다.

추론 엔진의 우열은 이름표가 아니라 같은 모델·정밀도·하드웨어·입출력 길이·동시성에서 비교해야 합니다. README의 “TensorRT-LLM 수준 성능, vLLM 수준 사용성”은 프로젝트가 내세우는 목표로 읽어야 합니다.

예를 들어 test/ci/perf/qwen3.8-flash-next-nvfp4-tp4ep4-evalscope-agentic.yaml은 사용자당 속도와 GPU당 출력 처리량의 단위를 구분합니다. perf_reference는 기존 측정 결과를 바탕으로 정한 CI 비교 기준값입니다.

3기술 스택 전체 지도

3-1. 백엔드: Python으로 연결하고 C++로 일정을 정한다

openai>=2.24.1도 의존성에 있습니다. 이것이 OpenAI 원격 API 호출을 필수로 뜻하지는 않습니다. 이 프로젝트의 중심은 모델 가중치를 직접 실행하는 서빙입니다. 패키지 이름만으로 데이터 흐름을 추정하지 말고 호출부를 따라가야 합니다.

3-2. C++ 확장과 GPU 커널: 같은 버전 번호로 묶이지 않는다

표의 NVIDIA DSL 의존성도 tokenspeed-kernel/python/requirements/cuda.txt에서 확인할 수 있습니다. tokenspeed-kernel/python/requirements/cuda-thirdparty.txt에는 tokenspeed-deepep==2.1.0.post20260810, tokenspeed-deepgemm==2.8.0.post20260924, tokenspeed-mla==2.0.4 등이 별도로 선언됩니다.

파일명이 thirdparty라고 해서 선택 의존성은 아닙니다. tokenspeed-kernel/python/setup.py의 설명과 요구사항 결합 로직은 두 파일을 설치 메타데이터에 함께 반영합니다. ROCm 쪽은 tokenspeed-kernel/python/requirements/rocm.txt에서 Torch 버전을 고정하지 않으며, tokenspeed-kernel/python/requirements/rocm-thirdparty.txt에는 Petit용 triton==3.8.0이 있습니다.

3-3. 프론트엔드: 추론용 대시보드 대신 문서 사이트

docs/package.json은 bun@1.3.0과 vitepress ^1.6.3을 선언합니다. docs/.vitepress/config.mts는 기본 경로 /tokenspeed/, 로컬 문서 검색, 가이드·레시피 메뉴를 설정합니다. 이 구성은 문서를 빌드하는 프론트엔드이며, 별도의 React 채팅 제품을 뜻하지 않습니다.

커밋 1ed2de1의 TypeScript 계열 코드는 .mts 설정 1개·85줄입니다. 작은 설정 파일에서 Bun·VitePress가 보인다고 추론 런타임이 Node.js 서버라고 결론 내리면 안 됩니다.

3-4. 인프라·빌드: 컨테이너 태그와 실제 설치값을 구별하기

• docker/Dockerfile.nvidia: 기반 태그는 cu130-torch-2.14.0-flashinfer-0.6.18, MAX_JOBS=16, CUDA_ARCH_LIST="9.0a 10.0a". 이후 소스 패키지 설치가 의존성을 다시 반영합니다.
• docker/Dockerfile.amd: 기반 태그는 rocm7.2.4-pytorch-2.13.0-gfx950지만, 뒤에서 torch==2.14.0·torchvision==0.29.0을 설치합니다.
• .github/workflows/scheduler-cpp-test.yml: Ubuntu, Python 3.12, CMake·Ninja로 C++ 테스트를 빌드합니다. CMake가 고정한 GoogleTest는 v1.14.0입니다.
• .github/workflows/docs.yml: Bun 1.3.0으로 bun.lock을 고정 설치하고 VitePress 결과를 GitHub Pages에 배포합니다.
• .pre-commit-config.yaml: Black 26.3.1, isort 8.0.1, clang-format v18.1.8 등 코드 형식을 고정합니다.

버전은 패키지 선언, 가속기별 요구사항, 컨테이너 설치 단계를 함께 읽어야 실제 의미가 드러납니다. 특히 기반 이미지 이름에 적힌 FlashInfer 0.6.18과 현재 CUDA 요구사항의 0.7.2를 같은 값으로 적으면 부정확합니다.

4아키텍처 심화 분석

4-1. 시스템 전체 그림

아래는 ts serve의 대표 경로를 단순화한 구조입니다. 게이트웨이와 gRPC 서빙 구현 일부는 의존 패키지에 있고, 이 저장소는 기동 조합과 런타임을 제공합니다. 직접 ZMQ 연결이나 분리 서빙 같은 선택 경로까지 전부 그린 그림은 아닙니다.

AsyncLLM.generate_request()는 입력 검증, 배치 정규화, 토큰화와 응답 대기를 조합합니다. _send_one_request()는 rid_to_state에 요청 상태를 저장하고 스케줄러 쪽으로 메시지를 보냅니다. EngineCoreClient는 요청 송신·응답 수신·부하 스냅샷 수신 소켓을 소유합니다.

python/tokenspeed/runtime/engine/core_client.py에서는 호출 이름이 send_pyobj()여도 실제 소켓을 IpcSender·AsyncIpcReceiver로 감쌉니다. 기본 전송 형식은 MessagePack이며, 환경 변수 TOKENSPEED_USE_PICKLE_IPC=1을 설정하면 요청·응답 전송이 pickle로 바뀝니다. 함수 이름만으로 전송 형식을 판단하면 이 차이를 놓칩니다.

4-2. 패턴 ① 제어와 실행을 나누고, 계획으로 연결한다

python/tokenspeed/runtime/engine/event_loop.py의 EventLoop.event_loop()는 요청을 받고, 캐시 완료 이벤트를 반영하고, C++ 스케줄러에서 다음 계획을 얻습니다. 실제 모델 연산은 DeviceHandle 뒤의 실행 계층으로 넘깁니다.

tokenspeed-scheduler/csrc/scheduler/scheduler.cpp의 Scheduler::NextExecutionPlan()은 실행할 요청만 고르는 함수가 아닙니다. 모델 배치와 함께 페이지 초기화·복사, 저장·복원, 원격 처리 작업도 계획에 담습니다. Python에 노출되는 이름은 tokenspeed-scheduler/bindings/python_module.cpp의 next_execution_plan입니다.

# EventLoop.event_loop()를 이해하기 위한 의사 코드
while 서비스가_동작함:
    새_요청을_받는다()
    캐시_완료를_스케줄러에_반영한다()
    plan = scheduler.next_execution_plan()
    pending = device.execute(plan, 준비한_입력, cache_ops=장치_캐시_작업)
    완료된_결과를_반영한다()
    스케줄러에_상태_변화를_알린다()

4-3. 패턴 ② 상태에 자원을 넣어 수명주기를 드러낸다

tokenspeed-scheduler/csrc/fsm/states.h는 요청 상태를 std::variant로 표현합니다. Submitted, Prefilling, Decoding, Finishing, Finished 외에 원격 처리·저장소 대기·회수와 복원 상태도 포함합니다.

tokenspeed-scheduler/csrc/fsm/forward_states.h의 ForwardResources는 요청 슬롯, 블록 테이블, 캐시 진행 정보, results_in_flight를 한 묶음으로 가집니다. tokenspeed-scheduler/csrc/fsm/forward_events.cpp는 std::move(state.resources)로 다음 상태에 이 묶음을 전달합니다.

// forward_events.cpp의 ReleaseEvent 본문 핵심 발췌
Finished ReleaseEvent::operator()(Finishing&& state) {
    _assert(coordinator_ != nullptr, "ReleaseEvent requires a cache coordinator");
    _assert(state.resources.results_in_flight == 0,
            "a request is released only once its forwards have landed");
    FreeRequest(*coordinator_, state.resources.block_tables);
    return Finished{};
}

논리적으로 답이 끝나는 시점과 메모리를 다시 빌려줄 수 있는 시점은 다를 수 있습니다. 위 검사는 그 차이를 직접 보여 줍니다. 타입은 상태와 자원 묶음의 형태를 제한하고, 실행 중 결과 수 같은 시간 조건은 런타임 검사로 확인합니다.

README는 타입 시스템을 통한 안전성을 강조합니다. 소스는 여기에 참조 수, 완료 통지, _assert도 결합합니다. 따라서 “모든 비동기 메모리 오류를 컴파일 때 막는다”는 식으로 확대 해석하지 않아야 합니다.

4-4. 패턴 ③ FIFO 제출과 완료 반영을 분리해 CPU·GPU를 겹친다

python/tokenspeed/runtime/execution/forward_thread.py의 ForwardThread는 queue.SimpleQueue와 소비 스레드를 사용합니다. submit_forward()는 작업과 Future를 큐에 넣고 즉시 반환합니다. 작업 중 예외는 future.set_exception()으로 결과를 기다리는 쪽에 전달합니다.

python/tokenspeed/runtime/execution/types.py의 PendingExecution.result()는 먼저 Future를 기다리고, 이어 ModelExecutionResult.sync()로 GPU→CPU 복사 완료 이벤트를 기다립니다. “스레드가 커널 호출을 끝냈다”와 “CPU가 결과를 읽어도 된다”를 별도로 확인하는 셈입니다.

EventLoop의 in_flight_depth=0은 같은 반복에서 결과를 반영하고, 1은 다음 작업을 제출한 뒤 이전 결과를 반영합니다. 파이프라인 병렬에서는 pp_size가 깊이가 됩니다. _dispatch_depends_on_pending_commit()는 먼저 결과 반영이 필요한 경우를 모읍니다.

비동기는 기다림을 없애는 기술이 아니라, 정확성이 허용하는 시점까지 기다림을 옮기는 기술입니다. 결과를 너무 일찍 읽는 오류와 너무 일찍 기다려 병렬성을 잃는 문제를 함께 다뤄야 합니다.

4-5. 패턴 ④ 공용 연산 계약과 등록된 구현을 분리한다

tokenspeed-kernel/python/tokenspeed_kernel/registry.py의 register_kernel()은 연산 종류, 실행 모드, 형식 서명, 하드웨어 능력, 특성, 우선순위를 등록합니다. tokenspeed-kernel/python/tokenspeed_kernel/selection.py의 select_kernel()은 조건에 맞는 후보를 고르고 결과를 캐시합니다.

solution=은 특정 구현 계열로 후보를 좁히면서 호환성 검사를 유지합니다. 반면 override=는 하드웨어·형식·특성 매칭을 건너뛰는 강제 선택이며, 필수 기능 검사는 남습니다. 두 인자를 같은 “백엔드 선택 옵션”으로 뭉뚱그리면 중요한 차이를 놓칩니다.

4-6. 커밋 1ed2de1에서 배우는 최적화: 계산식보다 이동과 실행 단위를 바꾸기

python/tokenspeed/runtime/models/kimi_k3.py의 KimiLinearKDA._project_qkvfab()는 합쳐 계산한 투영 결과에서 mixed_qkv = output[:, : 3 * proj_local]로 뷰를 만듭니다. 이 지점에서 .contiguous()로 별도 복사하지 않습니다. 후속 KDA 연산이 뷰의 행 간격을 처리할 수 있어야 가능한 선택입니다. 아래의 토큰 그룹 양자화 함수는 연속 텐서만 받으므로 입력 조건을 구별해야 합니다.

tokenspeed-kernel/python/tokenspeed_kernel/ops/quantization/triton.py의 _fp8_token_group_quantize()는 그룹별 FP8 양자화를 여러 그룹씩 타일로 묶어 실행합니다.

# 실제 분기 조건 발췌: padded_elements = groups * block
if padded_elements < 1 << 14 or block >= 1024:
    groups_per_program = 1
elif padded_elements < 7 << 18:
    groups_per_program = 1024 // block
else:
    groups_per_program = 8192 // block

block=128, 큰 입력이라면 프로그램 하나가 64그룹을 처리합니다. [4096, 7168] 입력은 그룹 크기 128일 때 229,376그룹이고, 64개씩 묶으면 3,584개 프로그램이 됩니다. 이는 실행 단위 개수의 계산이지 64배 속도 향상의 측정값이 아닙니다.

이 커널의 groups는 런타임 인자이고 GROUPS_PER_PROGRAM은 컴파일 때 정해집니다. 서빙 전에는 block이 1024보다 작은 경우 같은 서명에 필요한 세 타일을 warmup()으로 미리 컴파일합니다. 목표는 작업 분할 개선과 함께 서빙 도중 새로운 크기 때문에 컴파일이 끼어드는 일을 줄이는 것입니다.

5디렉토리 구조 해부

5-1. 코드 규모는 “전체”와 “부품”을 나눠 본다

표의 아래 네 행은 영역별 Python·C/C++·CUDA 합계입니다. 위의 언어별 합계와 겹치므로 다시 더하지 않습니다.

집계는 .git/을 제외한 물리적 줄 수이며, 빈 줄·주석·라이선스 문구·테스트·동봉한 외부 코드를 포함합니다. C/C++·CUDA는 .c/.cc/.cpp/.h/.hpp/.cu/.cuh, Python은 .py/.pyi를 대상으로 셌습니다.

Python 중 thirdparty/ 안에 있는 코드만 221파일·105,960줄입니다. Python에는 GPU용 DSL도 포함됩니다. 주 언어가 Python이라고 해서 100만 줄 모두가 HTTP 처리나 CPU 처리인 것은 아닙니다.

5-2. 처음이라면 이 순서로 읽기

1. docs/design/event-loop.md로 제어와 실행의 경계를 파악한다.
2. python/tokenspeed/runtime/engine/async_llm.py의 generate_request()에서 송신 경로를 따라간다.
3. python/tokenspeed/runtime/engine/event_loop.py의 event_loop()에서 계획과 완료 반영을 찾는다.
4. tokenspeed-scheduler/csrc/fsm/forward_events.cpp에서 상태와 자원의 이동을 읽는다.
5. tokenspeed-kernel/python/tokenspeed_kernel/selection.py에서 관심 있는 연산으로 들어간다.

거대한 모델 구현을 처음부터 읽기보다 요청·계획·실행·완료의 경계를 하나씩 연결하면 전체 구조를 이해하기 쉽습니다.

6학습 포인트 (기술별)

6-1. Python 비동기: 코루틴과 작업 스레드는 다르다

AsyncLLM.generate_request()의 async for는 응답이 생길 때마다 소비자에게 넘깁니다. 반면 ForwardThread는 GPU 작업 제출을 담당하는 별도 스레드입니다. async라는 문법 자체가 GPU 계산을 병렬화해 주지는 않습니다.

배울 것: 코루틴은 대기 시간을 다른 일에 양보하고, 큐·Future는 생산자와 소비자의 책임을 연결합니다. 실습 아이디어: test/runtime/test_forward_thread.py에서 FIFO 순서, 예외 전달, 느린 작업 중에도 제출이 막히지 않는다는 세 테스트를 읽고 각각의 실패 상황을 글로 써 봅니다.

6-2. C++20: enum 플래그 대신 상태별 자료형

std::variant는 “현재 상태가 여러 후보 중 정확히 하나”임을 나타냅니다. HoldsForwardResources라는 concept는 특정 상태가 필요한 자원 묶음을 갖는지 표현합니다. “finished인데 running도 true” 같은 조합을 플래그 여러 개로 만들지 않는 설계입니다.

배울 것: 값의 범위뿐 아니라 유효한 상태 조합을 타입으로 표현하기. 실습 아이디어: 파일 업로드 상태를 대기·수신·검증·완료로 나누고, 임시 파일 핸들을 어느 상태가 소유해야 하는지 표로 그려 봅니다.

6-3. 메모리 계층: 같은 “캐시 크기”에도 단위가 있다

docs/design/cache-concepts.md는 접두부 식별 단위인 prefix_granularity, 이력 블록의 논리 토큰 범위인 block_granularity, 실제 저장 단위인 CacheBlock, 커널의 페이지 크기를 분리합니다. 서버의 기본 prefix_granularity는 64토큰입니다.

여기에 전체 이력, 슬라이딩 윈도, 순환 상태라는 세 캐시 종류가 있습니다. 순환 상태 그룹은 일반 KV 이력과 달리 “토큰 행을 담은 페이지”로 선언하지 않습니다. 모든 Attention 상태를 단일 KV 배열로 취급하면 하이브리드 모델을 설명하기 어렵습니다.

실습 아이디어: tokenspeed-scheduler/tests/cpp/test_kv_cache_lifecycle.cpp에서 전체 이력과 슬라이딩 윈도의 블록 테이블이 어떻게 달라지는지 읽습니다. 특히 슬라이딩 윈도 뒤쪽에 남는 실제 블록과 앞쪽의 0번 자리 표시자를 구분해 봅니다.

6-4. GPU DSL·양자화: 수치 표현과 실행 배치를 따로 이해하기

FP8은 수를 적은 비트로 담아 저장·이동 비용을 줄이는 표현입니다. _fp8_token_group_quantize_kernel()은 그룹별 최댓값으로 scale을 구하고 입력을 나눠 변환합니다. 여러 그룹을 한 프로그램에 배치해도 각 그룹의 계산은 독립적입니다.

# 커널 계산의 의사 코드. bit8_max는 자료형의 최대 유한값이다.
scale = max(max(abs(group)), 1e-10) / bit8_max
quantized = clamp(group / scale, bit8_min, bit8_max).to(torch.float8_e4m3fn)
복원한_근삿값 = quantized.float() * scale

배울 것: 양자화 오차와 타일링 성능은 서로 다른 검증 대상입니다. 실습 아이디어: tokenspeed-kernel/test/ops/test_fp8_quantization_block.py에서 블록 경계 크기, 블록별 scale, 복원 오차를 어떻게 검사하는지 찾습니다. 이 파일의 블록 양자화 테스트를 토큰 그룹 커널의 성능 측정으로 혼동하지 않습니다.

6-5. CUDA Graph: 매번 새로 만들지 않고 내용을 갱신하기

docs/design/unified_path.md는 일반 실행과 그래프 재생이 동일한 refresh_decode_metadata() 경로를 사용한다고 설명합니다. 그래프 재생에서는 준비한 버퍼의 내용을 갱신한 뒤 기록된 실행을 재사용합니다.

그래프에 담는 배치 크기의 상한과 실제 처리 가능한 배치 크기의 상한도 분리합니다. 기록 범위를 넘는 decode는 같은 메타데이터 갱신 경로로 일반 실행을 합니다. 실습 아이디어: 문서에서 max_capture_bs와 max_decode_bs가 다른 이유를 찾아 설명합니다.

6-6. 검증 설계: 정확도·지연·컴파일 횟수를 함께 보기

test/ci/README.md는 서버를 기동하는 CI가 기본적으로 TOKENSPEED_JIT_COMPILE_CHECK=error를 사용한다고 명시합니다. 요청마다 바뀌는 값을 컴파일 상수로 넣어 서빙 중 재컴파일을 반복하는 문제도 실패로 취급합니다.

성능 최적화의 완료 조건에는 출력의 정확성뿐 아니라 대기·재컴파일·자원 회수의 동작도 포함됩니다. 정답만 같고 지연이 간헐적으로 튀는 변경을 놓치지 않는 관점입니다.

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

7-1. “몇 GB면 되나요?”에는 모델과 대화 길이가 필요하다

저장소 전체에 공통으로 적용할 VRAM 최솟값은 없습니다. 필요한 메모리는 대략 가중치 + KV·순환 상태 + 연산 작업 공간 + 그래프·통신 버퍼입니다. 여기에 동시 요청 수와 최대 문맥 길이가 영향을 줍니다.

# 가중치만 보는 교육용 근사식. 실제 설치 요구량은 아니다.
가중치_바이트 ≈ 전체_매개변수_수 * 매개변수당_비트 / 8

7B 모델을 BF16으로 저장: 7,000,000,000 * 16 / 8 ≈ 14 GB
7B 모델을 4비트로 저장: 7,000,000,000 *  4 / 8 ≈ 3.5 GB

# scale·메타데이터·일부 고정밀 가중치·런타임 버퍼는 별도다.

MoE 모델의 “토큰당 활성 매개변수”가 작아도 전체 전문가 가중치의 저장 비용이 사라지지는 않습니다. 397B-A17B 같은 이름에서 17B만 메모리에 들어간다고 계산하면 안 됩니다.

7-2. 일반적인 KV 캐시의 증가량을 계산해 보기

# 일반적인 비압축 MHA/GQA의 KV 데이터만 계산하는 근사식
KV_바이트 ≈ 2 * 레이어_수 * KV_헤드_수 * 헤드_차원
             * 저장_토큰_수 * 원소당_바이트

# 가상의 설정: 32층, KV 헤드 8개, 차원 128, 4096토큰, BF16
2 * 32 * 8 * 128 * 4096 * 2 = 536,870,912바이트
                           = 요청당 512 MiB

동일 조건의 요청 8개면 KV 데이터만 약 4 GiB입니다. 접두부 공유, 분할 저장, 여유 공간 등은 따로 고려해야 합니다. 이 식은 MLA 압축 캐시나 KDA의 순환 상태에 그대로 적용할 수 없습니다.

Hopper 가이드는 CUDA Toolkit 12.9를 쓰면서 Torch는 2.14.0+cu126을 사용하는 특수 조합도 설명합니다. 툴킷 버전, Torch가 묶은 런타임 버전, 드라이버 버전을 하나의 숫자로 취급하지 않는 습관을 들이세요.

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

# 저장소 루트에서 소스 텍스트만 검색하는 명령
rg -n 'generate_request|_send_one_request|_wait_one_response' \
  python/tokenspeed/runtime/engine/async_llm.py
rg -n 'next_execution_plan|_device.execute|advance_scheduler' \
  python/tokenspeed/runtime/engine/event_loop.py

실행하지 않고도 데이터 흐름·자원 수명·메모리 예산·최적화 가설을 검증하는 훈련을 할 수 있습니다. 먼저 이 다섯 결과물을 만들면, 나중에 GPU를 사용할 때 무엇을 측정할지 훨씬 명확해집니다.

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

Python 함수와 리스트를 읽을 수 있다면 1주차부터 시작할 수 있습니다. C++ 템플릿이나 GPU 프로그래밍을 전부 익힌 뒤 읽으려 하지 말고, 각 주차의 질문에 답하는 데 필요한 문법부터 보충합니다.

3주차의 C++ 문법이 어렵다면 상태 전이 테스트에서 입력과 기대 결과를 먼저 읽어도 좋습니다. 5주차에는 FP8 수치 오차와 GPU 실행 단위의 변화를 각각 설명할 수 있는지 확인합니다.

9-1. 관심 분야에 따라 다음 단계를 고른다

• 백엔드 개발: 입력 검증, 취소, 응답 스트리밍, 상태별 오류 전달을 더 읽습니다. “클라이언트가 끊겼는데 GPU 작업은 이미 제출됐다면?”이라는 질문으로 확장해 보세요.
• 시스템 개발: 캐시 배정·참조 수·전송 완료를 따라갑니다. 요청 종료와 물리 자원 반환이 다른 시점을 테스트가 어떻게 다루는지 봅니다.
• GPU 최적화: 한 연산을 골라 기준 구현, 등록 조건, 특화 구현, 수치 테스트, 측정 도구를 한 묶음으로 읽습니다.
• ML 인프라 운영: 모델 레시피, 정밀도, 병렬 분할, 문맥 길이, 동시성, CI 기준값을 연결해 읽습니다.

10핵심 키워드 사전

11참고 링크

11-1. 공식 저장소·문서

• TokenSpeed 공식 저장소 — 개요, 공개 발표, 프로젝트 안내
• TokenSpeed 공식 문서 — 시작 가이드·서버 설정·모델 레시피
• 커밋 기준 시작 가이드 — CUDA·ROCm 환경과 RDNA4 예제
• 이벤트 루프 설계 — 제어·실행 경계, 완료 반영, 동기화 규칙
• 캐시 개념 설계 — 토큰 단위와 물리 저장, 캐시 종류의 구분
• 통합 decode 경로 — 일반 실행·그래프 재생의 공통 계약

11-2. 핵심 코드로 바로 가기

• 런타임 의존성 · CUDA 의존성 — 버전 표의 근거
• AsyncLLM · EngineCoreClient — 접수·상태·IPC
• EventLoop · PendingExecution — 계획·제출·완료
• C++ 요청 상태 · 상태 전이 — 자원 수명과 반환 조건
• 커널 등록 · 커널 선택 — 조건 검사와 휴리스틱
• Triton 양자화 · Kimi K3 모델 — 타일링·stride 사례
• 실행 스레드 테스트 · KV 수명주기 테스트 — 설계 계약을 읽는 예시
• 대화 벤치마크 조건 · CI 작업 명세 안내 — 측정 조건과 검사 범위

11-3. 관련 기술을 더 읽으려면

• vLLM 공식 문서 — 배칭·캐시·서빙 기능 비교의 기준
• TensorRT-LLM Attention 문서 — 진행 중 배칭·청크 입력·KV 캐시 설명
• PagedAttention 원논문 — 블록 단위 KV 메모리 관리의 배경
• PyTorch 공식 문서 — 텐서·CUDA·자료형을 보충하는 출발점
• Triton 공식 문서 — GPU 프로그램과 타일 연산 기초
• Nanobind 공식 문서 — C++과 Python을 연결하는 방법

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