fun-rec: a Chinese-language recommender systems textbook that runs from item CF to OneRec

The gap fun-rec is trying to fill: a Chinese-language path from recall to generative recommendation

Most recommender systems material available in Chinese is either a translated survey paper or a competition write-up that assumes you already know the pipeline. fun-rec (subtitled 深度推荐算法实践, the wheat book) is positioned as the missing middle: a systematic textbook that starts at collaborative filtering and ends at Scaling Law architectures and diffusion-based recommendation. The README frames the scope as 从级联架构到生成式范式, the evolution from cascaded architectures to the generative paradigm, and splits the book into two halves accordingly.

The intended reader is stated plainly: someone with a machine learning foundation who wants to master both the core principles and the engineering practice of recommendation algorithms. That is a narrower audience than a general Python tutorial. If you have never trained a model or read a paper on matrix factorization, chapter 2 will move faster than you can follow. If you have shipped a ranking model and want to understand why HSTU exists, the second half is the part that is hard to find elsewhere in Chinese.

What the two halves actually contain, chapter by chapter

The first half, 上篇：级联架构, is the classical pipeline. Chapter 1 is an overview. Chapter 2 covers candidate recall in three families: collaborative filtering (item CF, user CF, matrix factorization), vector recall (I2I and U2I), and sequence recall (user interest representation, full-interest modeling with streaming indexes). Chapter 3 is preference prediction: memorization versus generalization, second-order and higher-order feature crossing, sequence modeling with local activation attention and interest evolution, multi-objective modeling, and multi-scenario modeling with multi-tower structures and dynamic weighting. Chapter 4 is re-ranking for diversity: greedy methods (maximal marginal relevance, determinantal point processes) and personalized re-ranking (Transformer-based and permutation-based models).

The second half, 下篇：生成式范式, is where the book departs from most tutorials. Chapter 5 covers generative foundations: the shift from discriminative to generative modeling, Transformer and Diffusion as architectural bases, the three-stage LLM pipeline, and tokenization for recommendation including end-to-end discretization and industrial schemes. Chapter 6 is Scaling Law exploration through HSTU and hardware-aware unified architectures. Chapter 7 is end-to-end generative modeling: OneRec V1 and V2, OneSug query completion, OneSearch item retrieval, EGA unified bidding, GPR pretraining for ad generation. Chapter 8 is reasoning models: PLUM, OneRec-Think, RecZero and RecOne. Chapter 9 is diffusion: DiffuASR, Diff-MSR, AsymDiffRec, DMSG. Chapter 10 is a production system build covering offline pipeline, online flow, front end and deployment.

The mechanism is a book plus a code repository, not an installable package

There is no pip install here. The README describes the project as a book (本书) with an online reading address at datawhalechina.github.io/fun-rec, and the repository is organized around chapters rather than around a single importable module. The topics list includes tensorflow, deep-learning and tianchi-competition, which suggests the code accompanying the chapters is written against TensorFlow and competition-style datasets, but the README does not enumerate a requirements.txt, a setup.py, or a documented entry point. I cannot confirm from the supplied material what the exact run command for any chapter is, or whether each chapter ships runnable code at all.

That matters for how you use it. Treat fun-rec as a reading-first resource where code is illustrative and tied to a specific chapter's narrative, not as a framework you wire into a service. The production chapter (chapter 10) is described as covering system architecture, offline pipeline, online flow, front end and deployment, which reads like a walkthrough of a reference design rather than a deployable artifact. The README gives no installation instructions, no configuration keys, and no environment specification, so any claim about how to get it running would be invented.

The constraint the README states up front: no pull requests while the book is in flux

The most operationally important line in the README is a blockquote: the project is still under development, code and content update frequently, and pull requests are not currently accepted. Feedback goes through GitHub Issues instead. For a reader this is fine. For anyone planning to fork and extend it, or to build a course on top of a frozen snapshot, it is a real constraint: the ground under chapter 5 through 9 is explicitly moving.

The repository metadata supports that reading. The last push recorded is 2026-06-27, and no releases have been retrieved. There is no versioned tag to pin against. If you cite a chapter in internal training material, cite it with a commit hash rather than a URL, because the online book at datawhalechina.github.io/fun-rec will change. The README also notes that the WeChat group QR code expires after seven days and directs readers to add a contact with the note Fun-Rec, which tells you the community channel is chat-based rather than a forum with searchable threads. The knowledge planet (知识星球) is described as the place where content is archived, and there are older videos on Bilibili linked from the README.

Licence: CC BY-NC-SA 4.0, which rules out commercial reuse

The README ends with a Creative Commons licence badge and a link: CC BY-NC-SA 4.0, attribution, non-commercial, share-alike. The licence identifier is stated explicitly in the README, and the repository metadata supplied does not list a separate licence field, so the README text is the source to trust here.

The practical consequences, stated as facts rather than legal advice: the NonCommercial clause means you cannot fold the text into a paid course or a commercial product without separate permission. The ShareAlike clause means derivatives must carry the same licence. Attribution is required. If you are an engineer reading this on your own time to learn, none of that interferes. If you are a company considering adapting chapters into internal onboarding material, the NC clause is the one to have a lawyer look at, because internal corporate training sits in a grey area that this review cannot resolve. I am not giving legal advice, and the README does not address corporate use.

Where fun-rec is the wrong tool

Three cases stand out. First, if you need a working recommender this week, fun-rec will not give it to you. There is no documented install path, no API surface, and the README does not promise a runnable baseline. A library such as Microsoft's recommenders package or a framework like RecBole is designed for that job: you install it, configure a model by name, and train on your own data. fun-rec is the opposite shape, a narrative that explains why the models exist.

Second, if you do not read Chinese, the value collapses. The README links to a README_en.md, but the chapter list and the book itself are presented in Chinese, and the README does not state that an English edition of the full text exists. The English README appears to be a repository description file, not a translation of the ten chapters.

Third, if you want stable, citable, versioned reference material, the no-PR, in-development status is a poor fit. A published textbook with an ISBN has a fixed edition. fun-rec has a master branch and a moving online book. That is a reasonable trade for currency in a fast-moving subfield like generative recommendation, and a bad trade for a syllabus that must not change mid-semester.

How it compares to RecBole in approach

RecBole is the obvious reference point because it occupies the same subject area with the opposite delivery model. RecBole is a Python library: you install it, select a model from a registry of implemented algorithms, point it at a dataset in a supported format, and run training and evaluation through a configuration file. Its output is metrics and checkpoints. fun-rec's output is understanding: prose that explains why item CF fails on long-tail items, how interest evolution modeling differs from local activation attention, and what problem OneRec-V2 was built to solve.

The difference in maintenance shape follows from that. A library carries an API compatibility burden and must keep its model implementations correct against a test suite. A book carries a correctness burden on its explanations and a currency burden on its coverage. fun-rec's decision to stop accepting PRs while chapters are in flux is a book-shaped decision: it avoids merge conflicts across chapters that reference each other. RecBole could not make the same call without freezing its API. Neither approach is better in the abstract. If you are choosing, the question is whether you need to run something or understand something, and fun-rec answers only the second.

Maintenance cost and what to verify before you invest time

The cost of following fun-rec is reading time plus the risk of churn. The README states that code and content update frequently, so a chapter you read in March may be rewritten by June. There is no changelog in the supplied material, no release notes, and no versioned snapshot, so you cannot diff what changed between two readings except by watching the repository. The community channels are a WeChat group and a knowledge planet, both of which are chat-shaped and not indexed by search engines, which makes it harder to check whether a question has already been answered.

Before committing, verify three things against the live repository rather than this description. Open the online book and check that the ten chapters listed in the README are actually present and not stubs. Look at whether the code directories contain runnable scripts or only notebooks, since the README does not say. And check the licence file in the repository root against the CC BY-NC-SA 4.0 badge in the README, because the metadata supplied here lists the licence as unknown while the README states it explicitly. If the code directories turn out to be sparse, fun-rec is still worth reading as a survey of the generative recommendation literature in Chinese, but it is not a practice environment.

Editorial conclusion

Adopt fun-rec if you read Chinese and want a single structured path from item-based collaborative filtering to HSTU and OneRec, with a production-system chapter at the end. Do not adopt it if you need an importable Python package, English-only material, or a stable API to build on: the README states the project is under active development, updates are frequent, and pull requests are not being accepted. Before committing study time, open the online book at datawhalechina.github.io/fun-rec, check the chapter list against the README, and confirm that the code directories under the repository match the chapters you care about, because the README itself carries no installation or run instructions.

Official sources

1. datawhalechina/fun-rec on GitHub
2. Issues
3. README