nndl/llm-beginner レビュー：6つの演習で大模型と智能体を手書きする教材
《大模型与智能体》电子书与 6 个编程任务：Transformer、mini-GPT、SFT/DPO、RAG、工具调用与编程智能体。
ひと目でわかる
- これは何？
- 復旦大学の邱錫鵬氏による電子書『大模型与智能体』と、Transformerから编程智能体まで段階的に進む6つの演習課題をまとめたリポジトリ。演習の骨格は用意されているが、実装コードは学習者が src/ に書く前提であり、製品に組み込むためのライブラリではない。
- 誰に向いている？
- 採用を検討すべきなのは、Transformer の数式は知っているが attention の mask や RoPE、KV cache を自分の手で書いたことがないエンジニアと、社内教育のカリキュラムとして LLM 周辺の実装力を底上げしたいチームである。逆に、動くチャットボットや RAG サービスを今週中に立ち上げたい人には向かない。
- 商用利用できる？
- できます。MIT は寛容なライセンスで、著作権表示とライセンス表示を残せば、使用・改変・販売が可能です。
- 今もメンテナンスされている？
- されています。最後のコミットは 10 日前です。
- 何の言語で書かれている？
- 主に Python です（GitHub の言語統計による）。
回答はプロジェクトの GitHub データ（最終同期：2026年9月15日）と当サイトの分析に基づくもので、法的助言ではありません。
オープンソース詳細解説
このリポジトリが埋めようとしている穴
LLM の解説記事は大量にあるが、その多くは API の呼び出し方か、逆に論文の要約で終わる。nndl/llm-beginner が狙うのはその中間で、attention のスケーリング、mask の種類、RoPE の回転行列、KV cache のメモリと計算の交換といった部品を自分で書き、その後でフレームワークの実装と見比べる。対象読者は README が明示している通り「Python と深層学習の基礎」を持つ人であり、シリーズの他教材を先に終える必要はないと書かれている。電子書は 17 章構成で、共用基礎、大模型、智能体、边界与未来の4部からなる。PDF は出版前の電子稿としてリリース book-pdf で配布されており、書稿は出版準備段階にあるため内容は改訂ごとに更新される。つまり読者は完成品ではなく、改訂中のテキストと、解答のない演習を同時に受け取ることになる。
6つの課題は何をどこまで書かせるか
課題は Transformer、mini-GPT、SFT/DPO、RAG、工具调用、编程智能体の順に並び、README の表ではそれぞれ 2 週、3 週、2〜3 週、2 週、2 週、5〜6 週という目安が添えられている。合計すると、フルタイムの学習者が半年近くをこの一本に充てる想定のボリュームである。各課題は「まず手書き、次にフレームワークと対照」という同じ型を取る。たとえば課題2では BPE トークナイザを tiktoken や sentencepiece なしで書き、decoder-only モデルに RoPE を組み込み、KV cache と greedy / top-k / top-p / temperature のサンプリングを実装する。課題1と実践書 v2 の注意力機制の章は意図的に重複させてあると README は説明しており、独立した読者のために基礎を敷き直す設計だと読み取れる。課題6だけが 5〜6 週と突出して長いのは、コードを編集しテストを走らせて反復するエージェントを扱うためで、ここが事実上の到達点になっている。
download.py と eval/run.py が担う役割
6つのタスクディレクトリは同じ構造を持つ。requirements.txt、data/download.py、eval/run.py、eval/tutor_prompt.md の4点セットだ。学習者は src/ の下に実装を書き、それを自検スクリプトが import して評価する。この関係が本リポジトリの設計上の要である。eval/run.py は各タスクの README にある「実現約定」表のクラス名と関数シグネチャに従って import するため、名前や引数を変えると採点されない。README は「照着写才能被正确评分」と明記している。データ側はタスクごとに異なり、課題1は ChnSentiCorp の中日感情分類、課題2は --dataset poetry|tinystories|skypile で切り替え、既定は唐詩の poetry、課題3は Qwen2.5-0.5B を取得し MOSS と DPO データの入手方法を案内、課題4は --skip-models を付けると PDF のみを取得して gold_qa を検証、課題6は --with-swebench で SWE-bench Lite のサンプルメタデータを追加取得する。
自検の三状態をどう読むか
eval/run.py は項目ごとに結果を表示し、eval/result.json に構造化して書き出す。この JSON は常に UTF-8 で、提出物に添付できる。状態は [通過]、[スキップ]、[失敗] の3つで、README がわざわざ説明を割いているのは [スキップ] の扱いだ。モデルや ckpt、データが欠けているときに返る状態であり、エラーではない。つまり初回実行で大量の [スキップ] が出るのは正常で、download.py を走らせて前提を埋めれば再実行で [通過] か [失敗] に変わる。[失敗] の側は error か具体的な指標が result.json に残るので、そこから修正に入る。ただし自検が確認するのは attention の数値的正しさ、再現率、タスク成功率といった「契約を満たしているか」の下限であり、各タスク README の「実験」節にある比較やアブレーションの代わりにはならないと README 自身が断っている。学習の効果を測りたいなら、自検が通った後に head 数や層数を振る実験を自分で回す必要がある。
環境構築でつまずく箇所
Python は 3.10 以上、推奨は 3.11 か 3.12。依存はタスクごとに独立しているので pip install -r task-1-transformer/requirements.txt のように個別に入れる。共通環境でもタスクごとの venv でもよい。中国国内から Hugging Face に到達しにくい場合、README は先にミラーを設定してからダウンロードする手順を示している。export HF_ENDPOINT=https://hf-mirror.com を設定し、Windows PowerShell では $env:HF_ENDPOINT = "https://hf-mirror.com" と書く。download スクリプトも欠落時にこの設定を促す。HF に全く到達できない場合は、多くのデータとモデルを ModelScope に切り替えられる。具体的な案内は各 download.py の末尾にある。見落としやすい制約が一つある。eval/run.py はリポジトリ直下の _eval_harness.py に依存しており、これは6タスク共通の実行シェルである。タスクディレクトリだけをリポジトリ外にコピーすると自検が import に失敗する。課題ごとに環境を分けるのは構わないが、ディレクトリを切り離すのは避けたい。
nanoGPT と何が違うのか
課題2は nanoGPT を参考資料の筆頭に挙げ、実践書 v2 の nanoGPT 章を拡張する位置づけだと説明している。差分は具体的で、BPE、RoPE、KV cache の3点が追加される。nanoGPT は絶対位置埋め込みを使い、KV cache は実装せず説明に留めると README は書いている。本リポジトリは RoPE の回転行列とその外挿性、KV cache のメモリと計算の交換を手で書かせる。学習の観点では、nanoGPT が「動く最小構成を一気に読む」教材なのに対し、こちらは部品ごとに立ち止まって契約を満たす教材である。ただし nanoGPT には学習済みチェックポイントや再現手順が同梱されているのに対し、本リポジトリの src/ は空であり、正解コードは提供されない。詰まったときに参照できるのは参考論文、各タスクの README、そして eval/tutor_prompt.md を Claude や Qwen、DeepSeek に貼って得るコードレビューだけである。解答が欲しい人にはこの差は大きい。
解答がないこととライセンスの境界
実装コードを学習者自身が src/ に書く設計は、写経で満足してしまうのを防ぐ一方で、行き詰まったときの逃げ道を用意しない。自検が [失敗] を返し続け、tutor_prompt.md によるレビューでも原因が特定できない場合、参考論文とフレームワーク実装を突き合わせる以外に手がない。これは教材として意図的な選択だろうが、独学の継続率には効いてくる。ライセンスは MIT で、リポジトリ全体に適用される。電子書の PDF も同じリポジトリのリリースとして配布されているが、書稿は出版準備段階にあり、出版後の扱いが MIT のままだとは本記事の材料からは判断できない。教材を社内研修に組み込む場合、コード部分は MIT の条件に従えばよいが、PDF の再配布や改変については出版社との関係を別途確認する必要がある。ここは法的助言ではなく、確認すべき論点の指摘である。
どんなチームが手を出すべきか
向いているのは、推論基盤や評価パイプラインを内製したいチームが、その前に部品の挙動を体で覚えておきたい場合だ。attention の mask を間違えると何が起きるか、KV cache を入れるとメモリがどう動くかを一度自分で書いておけば、後でフレームワークの不具合を疑う順序が変わる。課題5と6は ReAct ループやツール呼び出しのエラー回復、テストを回して反復するエージェントを扱うので、エージェント設計の当たりを付ける目的にも使える。向かないのは、今週中に動くデモが必要な人、正解コードを読んで最短で理解したい人、GPU を確保できないが課題2の正式訓練まで進めたい人である。最後のケースでは poetry の約49KB で pipeline だけ通し、TinyStories 以降は保留する判断になる。着手前に確認するのは、自分の環境で eval/run.py が [スキップ] を返す条件をどこまで潰せるか、そして各タスクの「実現約定」のシグネチャを自分の設計として受け入れられるか。この2つが噛み合わなければ、6つの課題はどれも途中で止まる。
編集部の結論
採用を検討すべきなのは、Transformer の数式は知っているが attention の mask や RoPE、KV cache を自分の手で書いたことがないエンジニアと、社内教育のカリキュラムとして LLM 周辺の実装力を底上げしたいチームである。逆に、動くチャットボットや RAG サービスを今週中に立ち上げたい人には向かない。最初に確認すべきは、各タスクの README「実現約定」に並ぶクラス名と関数シグネチャが自分の想定する設計と噛み合うか、そして eval/run.py が [通過] ではなく [スキップ] を返す前提条件（モデル重み、ckpt、データ）を自分の環境でどこまで満たせるかである。この2点を確かめずに始めると、数週間かけて書いたコードが自検の契約から外れていることに最後まで気づかない。
コミュニティノート