tiny-vllm：用 C++ 與 CUDA 從零打造推論引擎的教學專案

它填補的是理解斷層，不是部署缺口

讀 vLLM 的原始碼來學推論引擎，門檻很高。它的程式碼為了生產環境的效能與相容性做了大量工程取捨，讀者很容易在範本展開與平台分支裡迷路。tiny-vllm 針對的正是這個斷層：README 開頭寫明這是 vLLM 的「younger and smaller sibling」，目標是「derive the ideas and maths from scratch」，也就是把機制與數學重新推導一次，而不是叫你去讀一份已經優化到看不出原貌的實作。

它的對象有兩類。第一類是想搞清楚 KV cache、continuous batching、PagedAttention 到底怎麼運作的工程師，這些人可能已經會用 vLLM 或 TensorRT-LLM 佈署服務，但對底層資料流只有模糊印象。第二類是講師，README 直接寫「if you are a lecturer, feel welcome to use it as a teaching resource at your university」，所以課程編排是有意識地為教學設計的。

反過來說，如果你的問題是「我的服務要怎麼撐住每秒幾百個請求」，這個專案幫不上忙。它解決的是認知問題，不是容量問題。

從 Safetensors 到 PagedAttention 的完整鏈路

README 用一份勾選清單交代了引擎涵蓋的範圍，這份清單同時也是它的架構說明。最底層是從 Safetensors 載入真實模型權重，指定模型為 Llama 3.2 1B Instruct。往上是完整的 LLM 前向傳播，分成 prefill 與 decode 兩個階段，並且強調「all computation with CUDA kernels」，也就是矩陣乘法之外的算子也自己寫，不是全部丟給 cuBLAS。

中間層是記憶體管理。KV cache 解決的是自迴歸解碼時重複計算歷史 token 的問題，而 Paged KV cache 進一步把快取切成頁來管理，對應到 PagedAttention 這個機制。批次處理則有兩個階段：先做 static batching，再做 continuous batching，後者讓新請求可以在其他請求還在解碼時插入，而不是等整批跑完。

注意力計算是另一條線。專案實作了 FlashAttention 式的 online softmax，README 引用華盛頓大學 CSE599m 的課程講義作為推導來源；PagedAttention 則引用 arXiv 上的論文編號 2309.06180。這兩個引用透露出作者的做法：先把論文與課程材料攤開，再用 CUDA 把它們寫出來。

值得注意的是目錄結構本身就是教學順序。從 floating point 與 bfloat16 的取捨、GPU 與 CPU 記憶體差異、單一 token 推論、tokenization、embeddings 開始，接著是 RMSNorm 與 CUDA 的平行縮減、RoPE、殘差連接、cublasGemmEx、column-major 轉 row-major 的轉置技巧，然後才進入 prefill 與 decode 的區分。這個順序意味著讀者不會在還不認識 bfloat16 的時候就被丟進 attention kernel。

建置前提與你真正需要準備的東西

README 沒有提供安裝指令或 CMake 範例，這是要先講清楚的。它給的是課程大綱與原始碼，不是 quickstart。因此「怎麼跑起來」這個問題，只能從它列出的前置條件反推。

技術前提一節被列在目錄中，但提供的摘要沒有展開內容。可以確定的是，你需要能編譯 C++ 與 CUDA 的工具鏈，以及一張支援 bfloat16 的 NVIDIA GPU，因為 README 有專門一節討論「How floating-point numbers work and why we use bfloat16」。如果你的 GPU 世代較舊、不支援 bfloat16，這條路徑會直接卡住。

模型權重方面，你需要自行取得 Llama 3.2 1B Instruct 的 Safetensors 檔案。專案本身不附權重，而 Llama 系列模型有各自的授權條款，與專案的 Apache-2.0 是兩回事。

依賴方面，目錄中出現 cublasGemmEx，代表會用到 cuBLAS。這通常隨 CUDA Toolkit 一起提供，但具體版本要求摘要中沒有交代。實際動手前，建議先確認 CUDA Toolkit 版本、GPU 的 compute capability，以及專案目錄中是否附有建置腳本或 CMakeLists.txt，再決定要不要投入。這些都無法從現有材料確認，只能說它們是必須先查證的項目。

單模型、單機、以理解為優先的設計邊界

最明顯的限制是模型支援範圍。README 只提到 Llama 3.2 1B Instruct 一個模型，勾選清單的第一項就是載入它。這代表架構中的維度、層數、GQA 的頭數比例等，很可能都針對這個模型寫死或至少是圍繞它設計的。想換成 7B、70B 或不同架構的模型，需要自己動手改，而課程並不會帶你走這一段。

第二個限制是規模。1B 參數的模型在單張 GPU 上跑得動，所以專案不需要處理張量平行、管線平行或跨節點通訊。這些在生產級引擎中是核心議題，在這裡完全缺席。你不會從 tiny-vllm 學到多卡推論怎麼切。

第三個限制是量化。勾選清單中沒有出現任何量化相關項目，沒有 GPTQ、AWQ、FP8 或 INT8。對照之下，vLLM 這類引擎的量化支援是它能在有限顯存上服務大模型的主要原因之一。

還有一個容易被忽略的點：專案沒有發布任何 release。首頁顯示 recent releases 為空，最後推送時間是 2026 年 8 月，仍在維護中。這意味著沒有版本化的穩定介面，你如果基於它做二次開發，得自己承擔上游變動的成本。當教材用沒問題，當依賴用就要多想一下。

與 vLLM 的差別不只在體積

把 tiny-vllm 和 vLLM 放在一起比，最直覺的答案是「一個小一個大」，但真正的差別在優化目標。vLLM 的每一個設計決策都要回答「這樣能不能在生產流量下更省顯存、更高吞吐」，因此它必須處理排程器、請求生命週期、多模型與 LoRA 適配器、分散式執行、量化核心，以及跨越多種 GPU 世代的相容性。這些複雜度是為了服務真實負載而長出來的。

tiny-vllm 的決策標準不同。它要回答的是「這個機制能不能被講清楚、能不能被讀者自己寫出來」。所以它保留了 PagedAttention 與 continuous batching 這兩個最能體現 vLLM 設計思想的機制，卻不做排程器與量化。這是刻意的取捨，不是完成度不足。

如果你的目的是選一個引擎來跑服務，這個比較的結論很直接：選 vLLM。如果你的目的是搞懂 vLLM 為什麼要這樣設計，那麼直接讀 vLLM 反而效率低，因為你會在工程細節裡看不到主線。tiny-vllm 的價值就在這裡，它把主線抽出來，讓你自己走一遍。

另一個可以對照的方向是純 Python 的教學實作，例如用 PyTorch 寫一個迷你 GPT。差別在於那些專案通常不會碰 CUDA kernel、不會實作 PagedAttention、也不會處理 continuous batching，因為 PyTorch 把這些都藏在算子後面。tiny-vllm 的選擇是把算子打開來寫，代價是你必須先懂 CUDA 的執行模型與記憶體階層。

授權與後續維護的實際成本

專案採用 Apache-2.0，這是寬鬆授權，允許修改與再散布，也包含專利授權條款。如果你打算把課程材料或原始碼放進自己的教學專案，這個授權相對友善。但要注意兩件事。

第一，模型權重不是專案的一部分。Llama 3.2 有 Meta 自己的授權條款，與 Apache-2.0 無關。你從 Hugging Face 取得權重時，適用的是那份條款，不是這份。第二，README 中引用的 FlashAttention 講義與 PagedAttention 論文各有自己的版權，引用它們的推導是一回事，複製它們的內容是另一回事。

維護成本方面，這個專案沒有 release，也沒有檢索到版本標籤。這代表升級路徑是跟著 main 分支走。對教材用途來說這問題不大，你可以在某個時間點把程式碼固定下來。對想把它當函式庫用的團隊來說，這是一個實質風險：上游一改，你的建置就可能斷。

CUDA 生態本身也在變。新的 GPU 架構會帶來新的指令與記憶體特性，專案若要跟上就得改寫 kernel。目前沒有 release 節奏可供判斷作者打算跟得多緊，這只能觀察後續提交。

先驗證這三件事再決定投入

決定要不要花時間之前，有三件事是可以先確認的，而且都不需要真的把專案跑起來。

第一，打開倉庫目錄，確認有沒有 CMakeLists.txt 或 Makefile，以及它們要求的 CUDA 版本。README 摘要中沒有提到建置系統，這是最大的未知數。如果建置腳本缺失或只支援特定 CUDA 版本，你的環境可能要花不少時間對齊。

第二，確認你的 GPU 是否支援 bfloat16。這不是可選項，因為 README 把 bfloat16 當成基礎前提來講，整個數值路徑都建立在它上面。

第三，讀一遍課程目錄，特別是 Prefill vs decode、Why KV cache exists、Continuous batching、Paged Attention 這幾節的順序。如果你已經熟悉這些概念，這個專案對你的邊際價值會低很多；如果你在這些地方卡過，那它的編排正好對症。

這三項確認完，你大概就知道自己該不該開始。tiny-vllm 不是一個等你來用的工具，它是一條等你來走的路。

編輯結論

如果你要的是理解 vLLM 內部機制、或需要一份能在大學課堂上帶學生動手寫 CUDA kernel 的教材，tiny-vllm 的課程結構與配套原始碼值得投入時間。如果你要的是能上線服務、支援多模型或需要量化與分散式推論的引擎，這個專案不是那個東西，README 本身只承諾 Llama 3.2 1B Instruct 這一個模型。動手前先確認三件事：你的 GPU 是否支援 bfloat16、Safetensors 權重檔從哪裡取得、以及建置系統與 CUDA 版本在你的環境能否通過。

官方來源

1. Issues
2. jmaczan/tiny-vllm on GitHub
3. License: Apache-2.0
4. README