tiny-vllm: C++とCUDAで推論エンジンを書きながら学ぶ教材リポジトリ

LLMの重みファイルを実行可能なサーバーに変える、という出発点

READMEは、学習済みモデルの重みが単なるfloatの集合であり、それ自体は実行できないと説明している。アーキテクチャも設計図にすぎず、実行するには演算を実装したプログラムが必要になる。重みを起動時に読み込み、プロンプトを投げて応答を得るまでのプログラムが推論サーバーであり、tiny-vllmはその最小版を自作する講座として位置づけられている。対象読者は、行列積とドット積の計算がなぜGPUに向くのかを理解しつつ、実際にカーネルを書きたい人である。READMEは「make yourself a hot beverage and let's begin」と述べ、読み物としてではなく手を動かす前提の教材だと明示している。

リポジトリが二重構造になっている理由

このリポジトリは、推論サーバーの完全なソースコードと、エンジンを実装していく過程をなぞる講座という、性格の異なる二つで構成されている。READMEのチェックリストには、SafetensorsからのLlama 3.2 1B Instructの読み込み、prefillとdecodeを含む順伝播、CUDAカーネルによる計算、KVキャッシュ、static batching、continuous batching、FlashAttention系のonline softmax、PagedAttentionが完了済みとして並ぶ。目次はIntroから始まり、Safetensors、bfloat16、GPUとCPUのメモリ、単一トークン推論、トークナイズ、埋め込み、RMSNormと並列リダクション、RoPE、残差接続、cublasGemmEx、列優先から行優先への転置、prefillとdecodeの違い、KVキャッシュの必然性、attention、GQA、SiLU、softmax、causal mask、argmax、FFN、バッファ再利用、static batching、continuous batching、online softmax、PagedAttention、paged KV cache、そしてPagedAttentionのCUDAカーネルへと続く。機能の一覧と目次の順序がほぼ対応しており、読み進める順序がそのまま実装の依存関係になっている。

段階ごとに分割された実装順序

目次の並びを見ると、この講座は単一トークンの推論から始めて、トークナイズ、埋め込み、正規化、位置エンコーディング、注意機構、FFNという順に積み上げ、その後にバッチ処理とメモリ管理へ進む構成だと分かる。CUDAカーネルを書く回が埋め込み、RMSNormと並列リダクション、PagedAttentionの三箇所に置かれている点は設計上の判断だろう。行列積そのものはcublasGemmExに委ね、自前のカーネルはリダクションやメモリ配置が効いてくる箇所に絞っている。バッファ再利用の回がstatic batchingの直前に置かれているのも、連続バッチングを導入する前に確保と解放の考え方を固める順序として筋が通っている。

bfloat16とメモリ配置が講座の前提になっている

READMEには、浮動小数点数の仕組みとbfloat16を使う理由の回、GPUとCPUのメモリの回、そして列優先から行優先への転置トリックの回が独立して置かれている。これは付録ではなく、以降のカーネル実装を読むための前提である。bfloat16を選ぶ理由とメモリ階層の理解を先に置かないと、attentionやKVキャッシュのコードが読めないという判断が読み取れる。列優先から行優先への変換を独立した話題として立てているのも、cublasの呼び出しと自前カーネルの間でレイアウトを合わせる作業が実装上の負担になるためだと考えられる。

ビルドと実行のために確認できること

手元で動かすための具体的な手順、必要なCUDAのバージョン、CMakeなどのビルド設定、モデルの配置先や起動コマンドは、提供されたREADMEの範囲では確認できない。READMEが示しているのは、対象モデルがLlama 3.2 1B Instructで、重みの形式がSafetensorsであり、計算がCUDAカーネルで行われるという三点である。したがって、導入を検討する場合は、リポジトリ内のビルド用ファイルと講座の該当回を直接確認する必要がある。ここで推測でコマンドを書くことは避ける。確認できる事実として言えるのは、Pythonの依存を持ち込まずにC++とCUDAで完結させる構成であり、その分だけGPUドライバとCUDAツールキットの側の前提が重くなるという点だ。

vLLM本体やllama.cppとは何が違うのか

READMEはtiny-vllmをvLLMの「younger and smaller sibling」と表現し、同じPagedAttentionの論文を参照している。違いは機能の網羅性ではなく、目的にある。vLLMは本番で使う推論サーバーとして開発されており、tiny-vllmはエンジンの内部を読者自身が組み立てるための教材である。もう一つの比較対象はllama.cppだろう。llama.cppはGGUF形式の量子化モデルをCPUや多様なバックエンドで動かすことを重視するのに対し、tiny-vllmはSafetensorsのbfloat16重みをCUDAカーネルで扱う経路に絞っている。量子化やマルチGPUへの対応を期待してtiny-vllmを選ぶと、講座の範囲外の作業が増える。逆に、PagedAttentionがどのようにメモリを分割してKVキャッシュを管理するのかをコードレベルで追いたい場合、この絞り込みは利点になる。

講座であることがもたらす制約

対象モデルがLlama 3.2 1B Instructに固定されている点は、最初にぶつかる境界である。READMEのチェックリストはこのモデルの読み込みを明記しており、他のアーキテクチャやサイズのモデルを読み込む経路については言及がない。量子化、テンソル並列、マルチGPU、投機的デコードといった本番サーバーで問われる要素も、チェックリストにも目次にも現れない。また、推論エンジンの性能を測るためのベンチマーク手順や、他の実装との比較数値は提供された資料からは確認できない。性能を主張する記述をこのリポジトリから読み取ることはできないし、すべきでもない。教育目的で書かれたコードは、エラー処理や境界条件の扱いが本番向けよりも薄くなる傾向があり、tiny-vllmがその例外だと示す情報もない。

ライセンスと保守の見取り図

ライセンスはApache-2.0で、特許条項と変更点の表示義務を含む条項が知られている。講座資料とソースコードのどちらにどの条項が及ぶかを判断するのは法務の領域であり、ここで法的助言はしない。保守の面では、リポジトリはアーカイブされておらず、最終更新は2026年8月23日と記録されている。ただしリリースは取得されておらず、バージョン番号に基づく互換性の追跡はできない。CUDAのバージョンアップやcublasGemmExの挙動変更に追随するかどうかは、リポジトリの更新状況を自分で確認するしかない。講座として読む分にはこの不確実性は問題になりにくいが、継続的にビルドし続ける前提で使うなら、固定したCUDA環境を用意しておくほうが安全である。

編集部の結論

導入を検討すべきなのは、CUDAカーネルとLLM推論の内部構造を自分の手で書いて理解したい人、および大学の講義で教材を探している講師である。逆に、本番の推論基盤として使いたい人、量子化やマルチGPU対応を前提にしたい人には向かない。着手前に確認すべきは、対象がLlama 3.2 1B Instructに固定されている点、ビルドに必要なCUDAバージョンとGPUのメモリ量、そしてApache-2.0の下で講義資料とソースコードをどう扱うかである。判断の分かれ目は、これが完成品のサーバーではなく、あえて実装過程を公開した学習用のコードベースだという一点に集約される。

公式情報源

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