Một repo MIT gói trọn 4 tầng hệ thống recommender công nghiệp thành FastAPI service

TL;DR

GitHub user 1-dr-eam (ChendiLiu) vừa release RecommenderSystem — một recsys công nghiệp đủ 4 tầng recall → rough rank → fine rank → rerank, đóng gói thành FastAPI microservice, MIT license, 125★. Gộp đủ UserCF, ItemCF, two-tower, LightGCN, three-tower, multi-objective DCN, MMR + CLIP, Faiss IVFxPQy trong một codebase đọc được end-to-end. Data là synthetic nên không dùng cho research, nhưng là blueprint học việc / prototype cực tốt.

Kiến trúc full-link recall, rough rank, fine rank, rerank với Faiss và FastAPI

What's new

Hầu hết repo recsys OSS chỉ dừng ở 2 tầng (retrieval + ranking). Repo này đi đủ 4 tầng công nghiệp như YouTube, Xiaohongshu hay TikTok đang chạy, được tác giả phát triển theo 4 iteration lớn từ 2026.3.20 đến 2026.4.16.

v1.0 (3.20): Pipeline đầu tiên — 5 kênh recall, MLP rough/fine, CLIP + MMR rerank.
v2.0 (3.27): Thêm LightGCN (thành 6 kênh recall), fine rank lên multi-objective DCN, tối ưu memory khi xử lý CLIP big-data.
v3.0 (4.2): Tích hợp Faiss với index IVFxPQy, hyperparameter search, chốt data flow offline-online.
v4.0 (4.10): Đóng gói FastAPI (interface/main.py), kiến trúc DB-backed offline-online, xuất DDL SQL.
v4.1 (4.16): Endpoint /fine_tuning cho phép retrain trực tuyến theo cửa sổ thời gian + exception handling.

Why it matters

Repo OSS phổ biến như TensorFlow Recommenders hay LightFM thường chỉ mô hình hoá retrieval + ranking. Tầng rough ranking và rerank gần như luôn được "giấu" trong closed-source infrastructure của các công ty lớn. Việc một repo MIT nhỏ gọn phơi bày cả 4 tầng — và còn cover cold-start bằng 2 kênh riêng — là tài liệu quý cho:

Kỹ sư đang ôn interview MLE / recsys.
Team nhỏ cần prototype feed content kiểu Xiaohongshu hoặc e-commerce personalized.
Người học đang theo course RecSys của Wang Shusen trên bilibili (nguồn tham khảo chính của tác giả).

Technical facts

6 kênh recall

UserCF & ItemCF — collaborative filtering classic, dựa trên ma trận tương đồng.
Two-tower neural — user tower + item tower, embedding truy vấn qua Faiss.
LightGCN — recall dựa trên graph convolution, bổ sung ở v2.0.
Keyword + category — xử lý item cold-start.
Content-feature clustering — cold-start thứ hai, dùng đặc trưng nội dung.

Ranking stack

Tầng	Model	Neural net	Vai trò
Rough rank	Three-tower	MLP fusion	Chấm điểm hàng ngàn item, cắt top vài trăm
Fine rank	Multi-objective DCN	Cross + deep network	Chấm chính xác, KHÔNG cắt
Rerank	MMR + CLIP	Cosine image+text embedding	Thêm diversity vào danh sách cuối

Three-tower là lựa chọn khôn ngoan — nằm giữa two-tower (late fusion, nhanh nhưng thiếu tương tác user-item) và full front-fusion (chính xác nhưng đắt), phù hợp đúng vai trò rough ranking. Fine rank dùng DCN-V2 để học feature interaction có bounded degree.

Infra serving

Faiss với IVFxPQy index — chứa embedding two-tower và LightGCN tính offline.
MySQL cho user/item/interaction data (có DDL sẵn trong /sql).
FastAPI + uvicorn cho lớp HTTP.
PyTorch cu126 cho training (GPU path).
Three-tower item embedding không đẩy vào Faiss được (do cần front-fusion), nên dùng memory/cache.

API endpoints

POST /recommend
{ "user_id": "u123", "hour": 21, "is_weekend": true, "is_holiday": false }
→ { "status": "success", "recommendations": ["i42", "i19", ...], "request_id": "uuid" }

POST /fine_tuning
{ "start_time": "2026-04-01T00:00:00", "end_time": "2026-04-15T00:00:00" }
→ { "status": "success", "message": "..." }

Comparison

Đặc điểm	RecommenderSystem (repo này)	TF-Recommenders / LightFM	Industry (YouTube, Xiaohongshu)
Số tầng	4 đủ	2 (retrieval + ranking)	4+
Kênh recall	6	1–2	10+
Fine rank	Multi-objective DCN	MLP single-objective	DCN-V2, DIN, SIM
Diversity	MMR + CLIP	Hiếm khi có	MMR / DPP / learned
Cold-start	2 kênh riêng	Thường thiếu	Pipeline riêng
Serving	FastAPI + Faiss + MySQL	Jupyter / Flask	Custom C++ infra

Use cases

Học nghề: đọc một repo là cover UserCF, ItemCF, two-tower, LightGCN, DCN, MMR, Faiss — hiệu suất tự học cao.
Prototype team nhỏ: bootstrap một content feed / e-commerce recsys với diversity built-in.
Interview MLE / recsys: bài tập mẫu cover gần trọn syllabus RecSys.
Reference architecture: cho team engineer đang hỏi "cái gì nên để trong Faiss, cái gì cần memory, cái gì tính offline".

Limitations & pricing

MIT license cho cả code lẫn pretrained weights trong /model_weights — dùng free thương mại được. Nhưng cần lưu ý:

Dataset AI-synthesized — chỉ metadata sách là thật, còn lại user và interaction đều giả. Tác giả nói rõ không dùng được cho research nghiêm túc, chỉ để stress-test pipeline.
Không có p50/p99 latency benchmark công bố (tác giả chỉ nói "response speed is good").
Không có Dockerfile, không có auth layer trên FastAPI — deploy production cần tự bổ sung.
Mặc định MySQL; đổi DB phải thay driver trong database.py.
Single contributor, chưa có CI.

What's next

Chưa có roadmap công khai, nhưng các gaps rõ ràng để đóng góp: Dockerfile, latency benchmark thật, dataset thay thế (MovieLens / Amazon Reviews), multi-GPU training, auth/rate-limit cho endpoint. Với tốc độ 4 iteration trong ~4 tuần, tác giả có vẻ active.

Nguồn: GitHub 1-dr-eam/RecommenderSystem, DCN V2 paper, OpenAI CLIP.