Happy-LLM: a free Chinese LLM course that builds a LLaMA2 model from scratch

What Happy-LLM actually solves for a Python reader

The README frames the project as a follow-up for people who finished Datawhale's self-llm guide and wanted the layer underneath it. That framing is precise: self-llm shows you how to run and fine-tune existing models, while Happy-LLM starts from NLP task categories and text representation, moves through attention and the Transformer, and only then reaches large models. The intended reader is a university student, a researcher or an enthusiast with Python experience and some deep learning background. If you can already read a PyTorch module and know what a token is, you are inside the target audience.

The deliverable is not a package you import. It is eight chapters of Markdown plus notebooks, a PDF build, and a pair of 215M checkpoints published on ModelScope. The stated goal is that you implement a complete LLaMA2 yourself, then take it through pretraining and supervised fine-tuning. That is a different promise from a framework: the value is in the code you write along the way, not in an artifact you deploy.

How the course is structured, from Transformer to Agentic RL

Chapters 1 through 4 are theory. Chapter 1 covers NLP history and task classification; chapter 2 covers attention, encoder-decoder design and a hands-on Transformer build; chapter 3 compares encoder-only, encoder-decoder and decoder-only pretrained language models; chapter 4 defines large models, their training strategies and emergent abilities. Chapters 5 through 8 are practice. Chapter 5 is the centerpiece: implement LLaMA2, train a tokenizer, pretrain a small LLM. Chapter 6 redoes training through the Transformers framework with pretraining, SFT and LoRA/QLoRA. Chapter 7 covers evaluation, RAG and agents. Chapter 8 covers GRPO, OPD, Search-R1 and ReTool.

The dependency layout matters more than the table of contents. The README states that dependencies are split by chapter and that different chapters should use separate Python environments to reduce version conflicts. That is an honest admission that the notebooks were written at different times against different library versions. Budget for several virtual environments, not one. The README also points readers to the chapter 6 practice notes and the environment preparation page before reproducing any code, and notes that chapter 8's algorithms and training code are followed more actively in a separate repository, agentic-rl-lab.

Installing Happy-LLM and running your first chapter

There is no pip package. The repository is a collection of Markdown documents and notebooks, so installation means cloning it and preparing an environment per chapter. Start by getting the files:

git clone https://github.com/datawhalechina/happy-llm.git
cd happy-llm

Before running anything, read the environment preparation document the README points to. It contains the per-chapter dependency and hardware guidance, and it is the only place the project describes what each chapter needs:

ls docs/学习与环境准备.md
docs/chapter6/readme.md

The repository layout separates the book from the code: docs/ holds the chapters, Extra-Chapter/ holds community blog posts, and images/ holds figures. Chapter 5 is the one to open first if your goal is to build rather than read, since the README lists it as implementing LLaMA2, training a tokenizer and pretraining a small LLM. The pretrained and fine-tuned 215M checkpoints are hosted on ModelScope under kmno4zx/happy-llm-215M-base and kmno4zx/happy-llm-215M-sft, and the README also links a ModelScope Studio demo for the SFT model. The README does not document a single unified install command, a requirements.txt at the repository root, or a supported Python version, so treat the environment page as the source of truth and expect to resolve versions yourself.

Where Happy-LLM stops being the right tool

The clearest limitation is that this is a teaching artifact. The checkpoints are 215M parameters, which is small by design: it is a size you can pretrain and fine-tune without a cluster, and the README's hardware guidance lives in the environment document rather than in a claim of scale. If you need a model that performs well on real tasks, the chapter 5 output is a learning milestone, not a production candidate.

The second limitation is the dependency split. Running chapters in one environment is explicitly discouraged, which means a reader who wants to move from chapter 5 to chapter 8 will be rebuilding environments rather than continuing in place. The third is maintenance surface. The last push to the repository was on 2026-01-29, and the README itself states that chapter 8's subject matter is followed more actively in the separate agentic-rl-lab repository. For the newest Agentic RL algorithms, the book is the slower of the two sources. The README also does not document rollback, a changelog beyond the release tags, or a deprecation policy for the notebooks.

Happy-LLM versus self-llm and the LLM Cookbook route

The README positions Happy-LLM directly against Datawhale's own self-llm guide, and the difference is the direction of travel. Self-llm starts from models that already exist and shows how to run and adapt them; Happy-LLM starts from NLP fundamentals and builds upward until you have written a LLaMA2 and trained it. If your question is how do I fine-tune this downloaded checkpoint, self-llm answers it sooner. If your question is why does this checkpoint have this architecture, Happy-LLM is the one that gets there.

The other route people arrive by is the LLM Cookbook style of material, which is organized around recipes for using an API or a hosted model. That is a different contract: you learn the interface, not the internals. Happy-LLM asks you to own a tokenizer and a training loop before it shows you RAG and agents in chapter 7. The trade-off is time. A reader who wants a working retrieval pipeline this week will find chapters 1 through 4 to be prerequisites they did not ask for.

Licence terms and the cost of keeping up

The README states the work is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International. The repository's LICENSE.txt is present at the top level, and the GitHub metadata reports the licence as NOASSERTION, meaning the platform does not map it to a standard identifier. For a reader, the practical points are the non-commercial clause and the share-alike clause: reuse in commercial training material is not covered by the stated terms, and derivative teaching material carries the same licence. This is a description of what the project says, not legal advice; if you plan to build on the text commercially, have someone qualified read the licence.

Upgrade cost is low in the sense that there is nothing to upgrade. There is no dependency you pin in your own project, only notebooks you run. The cost is in re-reading: the release history shows v1.0.0 as a PDF in June 2025, v1.0.1 in July 2025 and v1.0.2 with PPT materials in January 2026, so revisions arrive as new document versions rather than patches. If you fork the notebooks to teach from, you inherit the job of tracking those revisions yourself.

Editorial conclusion

Adopt Happy-LLM if you already write Python and want to see a LLaMA2 assembled, pretrained and fine-tuned rather than imported. Skip it if you need a maintained training framework or a production serving stack, since the repository is a book with notebooks and its last push was on 2026-01-29. Before committing, open docs/学习与环境准备.md, confirm the per-chapter dependency split, and check whether the 215M ModelScope checkpoints match the chapter you intend to reproduce.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes