Happy-LLM: A Free Chinese Tutorial That Builds a 215M LLaMA2 From Scratch

What Happy-LLM Actually Is

Happy-LLM is a systematic tutorial, not a software library. It is a collection of Jupyter notebooks and markdown documents that teach large language model theory and practice, organized into eight chapters plus an extra blog section. The target reader is someone who has basic Python skills and some familiarity with deep learning, but who has never built a language model from scratch. The project explicitly positions itself as a follow-up to Datawhale's self-llm guide, which covers how to use existing models. Happy-LLM goes one level deeper: it explains how a model is constructed and trained. The repository includes a downloadable 215M-parameter LLaMA2 base model and a supervised fine-tuned version, both hosted on ModelScope, so you can inspect or run a real model without training it yourself. This is a learning resource with a concrete artifact, which is rare among tutorials.

How the Content Is Structured

The course is split into two halves. Chapters 1 through 4 cover theory: NLP basics, the Transformer architecture, pretrained language model families, and the definition and training strategy of large language models. Chapter 2 includes a hand-built Transformer implementation, and Chapter 5 moves to building a LLaMA2 in PyTorch, including training a tokenizer and pretraining a small model. Chapter 6 introduces the Transformers framework for more efficient training, covering pretraining, supervised fine-tuning, and LoRA/QLoRA. Chapter 7 covers evaluation, RAG, and agents. Chapter 8 focuses on Agentic RL methods: GRPO, OPD, Search-R1, and ReTool. The structure is linear but the README says you can read selectively. The extra chapter is a collection of contributed blog posts on topics like fine-tuning small models, multimodal concatenation, and generation methods. That mix of formal chapters and informal blogs gives readers both a curriculum and a window into current practice.

Getting It Running: Environment and Dependencies

To reproduce the code, you start with the learning and environment preparation document, which the README says contains chapter-specific dependency lists and hardware advice. The key instruction is to use a separate Python environment for each chapter to avoid version conflicts. This is a practical choice because the code moves from plain PyTorch in Chapter 5 to the Transformers framework in Chapter 6, and those libraries may have different dependency requirements. The README does not give a single install command; you have to read the per-chapter documents. The repository provides PDF and PPT versions of the tutorial, which can be downloaded from the releases page. The PDF includes a Datawhale watermark to deter resale, which tells you the authors expect the document to circulate. The 215M models are available on ModelScope, and there is a ModelScope Space for interactive testing of the SFT model. That means you can try the model without local GPU resources, but training it yourself will likely require a GPU with sufficient memory, though the exact requirement is not stated in the README.

The 215M LLaMA2: A Concrete Learning Artifact

Chapter 5 is the centerpiece: you implement a LLaMA2 model from scratch in PyTorch, train a tokenizer, and pretrain a small language model. The repository provides two pretrained checkpoints on ModelScope: a base model and an SFT model, both 215M parameters. The SFT model is also available in a ModelScope Space, so you can chat with it in a browser. This artifact is what separates Happy-LLM from purely theoretical textbooks. You are not just reading about attention; you can see the model that came out of the tutorial's code. The download links are explicit, and the release notes for v1.0.2 mention a PPT release, indicating the project is actively maintained.

Limitations: Language, License, and Scope

The most obvious limitation is that the entire tutorial is in Chinese. There is an English README (README_en.md). That excludes a large portion of the global developer audience. The license is CC BY-NC-SA 4.0, which is a non-commercial license. That means you cannot use the material in a paid course or a commercial product without permission. The README explicitly says the PDF is watermarked to prevent resale, which confirms the authors' intent. Another limitation is that the scope is educational, not production. The 215M model is for learning, not for deployment. Chapter 8 covers Agentic RL, but the README points to a separate repository, agentic-rl-lab, for more algorithms and training code. So if you want to go beyond the tutorial's coverage, you have to switch projects. The project is also notebook-based, which is fine for learning but not a substitute for a training framework like Axolotl or Lit-GPT.

Alternatives: How Happy-LLM Differs

The closest alternative is the Hugging Face course, which covers Transformer usage and fine-tuning with the Transformers library, but it does not build a model from scratch. Happy-LLM's Chapter 5 does exactly that: it implements LLaMA2 in PyTorch, which is a different pedagogical approach. Another alternative is Andrej Karpathy's nanoGPT, which is a minimal GPT implementation in PyTorch. nanoGPT is more code-focused, with less theoretical explanation, and it targets GPT, not LLaMA2. Happy-LLM provides a broader curriculum, including RAG and Agentic RL, which nanoGPT does not. For Chinese readers, there is also Li Mu's 'Hands-On Deep Learning' (Dive into Deep Learning), which covers Transformer but not LLM training workflows like LoRA. Happy-LLM's unique angle is the combination of a full course and a trainable small model, all in Chinese, with a community-driven extra chapter. The choice depends on whether you want theory with a guided project or a minimal codebase to experiment with.

Maintenance, Community, and Upgrade Cost

The repository is active. The last push was August 8, 2026, while the latest release v1.0.2 is from January 29, 2026. The project has two named maintainers, both Datawhale members, and a list of extra chapter contributors. The README invites contributions, with a PR guideline for the extra blog section. The maintenance model is community-driven, which means content quality varies across the extra chapter. The upgrade cost for a learner is low: you read the docs and run the notebooks. The main cost is environment setup, because each chapter may require a different Python environment. The project does not have a packaging system or a CLI, so there is no version upgrade path in the software sense. You simply pull the latest repository state or download the latest PDF release. The release notes indicate a PPT release.

Editorial conclusion

Adopt Happy-LLM if you are a Chinese-speaking student, researcher, or hobbyist who wants a structured, free path from NLP basics to training a small LLaMA2, and who can accept a non-commercial license. Do not adopt it if you need English material, commercial use rights, or a production-grade training framework. Before committing, verify that your hardware meets the requirements in the environment preparation chapter, and check the release PDF for the latest content. The repository is maintained, with a release as recent as January 2026, but the license is CC BY-NC-SA 4.0, which prohibits commercial redistribution, so confirm that fits your use case.

Frequently asked questions

Official sources

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