tiny-llm を読む: MLX で Qwen3 推論系を自作する 4 週間コースの設計と限界
learn LLM inference system on Apple Silicon for systems engineers: build a tiny vLLM + Qwen
ひと目でわかる
- これは何？
- tiny-llm は、Apple Silicon 上の MLX だけを使い、Qwen3 の推論経路を配列演算からサービング機構まで自作させる教材である。読んで終わりの解説書ではなく、tiny_llm パッケージに自分で実装を書き、tiny_llm_ref とテストで突き合わせる形式になっている。
- 誰に向いている？
- CUDA マシンを用意せず、1 台の Apple Silicon 上で attention からページド KV、連続バッチングまでを自分の手で書きながら確かめたいシステム系エンジニアには向いている。逆に、動く推論サーバーを短期間で立てたい人、MLX 以外のランタイムを前提にしている人には合わない。
- 商用利用できる？
- できます。Apache-2.0 は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。直近 1 日以内に新しいコミットがあります。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
tiny-llm が埋めようとしている穴は「推論サーバーの中身が読めない」こと
vLLM のような推論サーバーは、量子化された重みの読み出し、KV キャッシュの配置、バッチの組み方、スケジューラの判断が積み重なって動いている。個々の要素は論文やブログで説明されていても、それらが 1 本の経路として繋がったコードを最初から最後まで読める機会は少ない。tiny-llm はこの隙間を狙った教材で、README は自らを CMU の Needle プロジェクトの LLM サービング版と位置づけている。Needle が自動微分の仕組みを自作させるのに対し、こちらは Qwen3 の重みを読み込み、トークンを logits に変え、テキストを生成する経路を自作させる。想定読者はシステム系エンジニアで、対象は推論の実行経路そのものだ。モデルを学習させたい人や、プロンプト設計に関心がある人を対象にした教材ではない。
MLX を正解オラクルとして残す、という中心的な設計判断
この教材の一番おもしろい判断は、高水準のニューラルネット層を使わないことにある。土台は MLX の配列と MLX 拡張ランタイムで、章で扱う演算子は、対応する最適化済み MLX 演算を呼ぶのではなく、Python、C++、Metal のいずれかで自分で実装する。では正しさをどう確かめるのか。MLX 側の実装を正解オラクル兼性能ベースラインとして残し、自作した演算子の出力と突き合わせる。学習者は最適化された実装を消すのではなく、隣に置いて比較する。この構成の利点は、間違った実装が「動いた風」に見えないことだ。欠点は、MLX の意味論を先に理解していないと、自作側のバグと MLX 側の期待値の読み違いを切り分けるのが難しい点にある。MLX に不慣れな読者は、Week 1 の行列演算の章で思ったより時間を使う可能性がある。
4 週間の学習経路: matmul からコーディングエージェントまで
Week 1 は From Matmul to Text と題され、mlx.core の配列演算だけを使って attention、RoPE、GQA、RMSNorm、MLP、サンプリング、自己回帰ループを組み上げる。Week 2 は A Step Closer to vLLM で、KV キャッシュを追加し、同期の取れた MLX ベースラインを確立したうえで、最適化の採否を揃えたベンチマークで決めていく。経路は量子化デコード matvec から融合カーネル、タイル化 prefill、必要と測定された箇所での split-K へ進む。Week 3 は Build a Mini vLLM で、連続バッチングとチャンク単位の受け入れを導入し、ページド KV をサービングの正準レイアウトにする。decode attention と FlashAttention がページを直接読むようになり、スケジューラが毎ステップ密な履歴を再構築しなくて済む、という説明になっている。Week 4 は Build a Coding Agent で、範囲を限定して検証するエージェントループから始まり、小さなワークスペースに接続する。Week 4 は 1 日ずつレビュー済みのチェックポイントを公開する方式で、Day 1 から Day 9 が学習者に公開されている。
動かすまで: pdm と check-installation
導入手順は README に具体的に書かれている。まず pdm install -v で依存を入れる。次に pdm run check-installation で既存チェックアウトの環境を検証する。Week 1 のテストだけを走らせたい場合は pdm run test-refsol -- -- -k week_1 という形になる。実装を書く場所は tiny_llm パッケージで、tiny_llm_ref はテストとベンチマーク付録が使う参照解である。章の順序は book/src/SUMMARY.md に列挙されており、本文は skyzh.github.io/tiny-llm で公開されている。環境構築の章は setup.html にある。Week 4 のループを動かす前に、README は Week 4 の overview を読むことと、秘密情報を置かない使い捨てワークスペースを使うことを求めている。Day 3 はファイル内容をモデルに送り、承認後にファイルを変更し、設定済みのコマンドを 1 つだけ実行できる。この「1 つだけ」という制約は、エージェントの権限を狭める設計として意図的に置かれている。
Week 4 は推論の教材ではなく、エージェント設計の教材になっている
Week 4 の各日は、推論カーネルの話から離れてエージェントの状態管理を扱う。Day 4 はツール観測の境界をチェックポイントし、スクリプト化されたモデルの偽キャッシュメタデータとともに保存し、完了済みの編集やコマンドを再生せずに新しいモデルを復元する。Day 5 はモデルに見えるトランスクリプト上で古い完了済み効果を圧縮しつつ、正確なレシート側には完全なアクション、結果、変更された成果物を保持する。Day 6 は完全な観測のチェックポイントを検査し、可視のオペレータ指示を 1 つ追加し、完了済み効果を再生せずに新しいモデルを再開する。Day 7 は宣言された最終状態、ファイル、結果、レシートの事実から 1 回の完了済み実行を評価し、隠れた推論やトランスクリプトの正確な形は採点しない。Day 8 は 1 つの実トークナイザ / KV チェックポイントを、異なるステアリングを与えた効果分離済みの 2 つの継続で再利用し、Day 7 のハーネスで両方を評価し、完了済み効果を巻き戻したふりをせずに明示的に 1 つを選ぶ。Day 9 はサイズの大きいツール結果のバイト列をモデルのプロンプトの外に保存し、境界付きの identity/digest/head-tail 観測を見せ、既存のループを通じて 1 つの明示的なバイト範囲を取得させる。ここで扱われるのは、コンテキストの圧縮、チェックポイントと再開、分岐の評価といった、実際のコーディングエージェントを作るときに効いてくる論点である。
未完であることを roadmap が正直に示している
roadmap 表は Code、Test、Doc、Audit の 4 列で進捗を追っている。Week 1 の 7 章は 4 列すべてが完了している。Week 2 以降は Code、Test、Doc が揃っていても Audit 列が未了の章が並ぶ。Audit は公開済みコース内容に対する Chi 個人の編集パスであり、コードやテストの準備状況とは独立だと README は明記している。Week 3.6 の MoE と 3.7 の Speculative Decoding は optional 扱いだ。Week 4 は 1 日ずつ公開されており、Day 1 から Day 9 が利用可能という状態で、コース全体が完成しているわけではない。教材として採用するなら、この未了の範囲を前提に計画を立てる必要がある。Week 2 の最適化の章を学習の中心に据えたい読者は、編集レビューがまだ入っていない章を読むことになる。
向かないケースと、代わりに何を使うか
この教材は推論サーバーを動かすためのものではない。Qwen3-4B をローカルで走らせたいだけなら、MLX 自体にモデル実行の手段があり、tiny-llm を経由する理由は薄い。CUDA 前提の環境で学習したい場合も、この教材は Apple Silicon の共有メモリ空間と Metal カーネルへの直接アクセスを前提にしているため、そのままでは噛み合わない。同じ「LLM 推論の中身を自作させる」という目的でも、CMU の Needle は自動微分の仕組みを対象にしており、扱う領域が違う。Needle が学習と逆伝播の経路を組ませるのに対し、tiny-llm は推論時のメモリトラフィック、カーネル占有率、KV キャッシュの伸び、バッチング、リクエストスケジューリングを数式と結びつける方向に振っている。どちらを選ぶかは、微分を書きたいのか、サービングを書きたいのかで決まる。
ライセンスと維持コストの見積もり
ライセンスは Apache-2.0 で、リポジトリはアーカイブされておらず、最終 push は 2026-09-09 となっている。リリースは取得できておらず、バージョン番号で固定して追う形の依存先ではない。Week 4 が 1 日ずつ公開される運用であることからも、内容が継続的に追加される前提で読むべき教材だと言える。参照解 tiny_llm_ref とテストが同じリポジトリにあるため、自分の実装が壊れたときの切り分けはしやすい。一方で、依存は pdm 管理であり、MLX のバージョンに追随する必要がある。学習を中断して数か月後に再開する場合、pdm install -v が通るかどうかを最初に確かめることになる。Apache-2.0 は商用利用や改変を許すが、教材の文章やコードを自組織の研修に取り込む際の表示義務や帰属の扱いは、自組織の法務判断による。ここでは法的助言はしない。
編集部の結論
CUDA マシンを用意せず、1 台の Apple Silicon 上で attention からページド KV、連続バッチングまでを自分の手で書きながら確かめたいシステム系エンジニアには向いている。逆に、動く推論サーバーを短期間で立てたい人、MLX 以外のランタイムを前提にしている人には合わない。着手前に確認すべきは、book/src/SUMMARY.md の章順と roadmap 表の Audit 列で、Week 2 以降は Code / Test / Doc が揃っていても編集レビューが未了の章が残る。まず pdm install -v と pdm run check-installation を通し、pdm run test-refsol -- -- -k week_1 が自分の環境で完走するかを最初の判断材料にするとよい。
コミュニティノート