🚀 Mini-RecSys：跳過筆記本，直達生產環境！端到端推薦系統 MLOps 實戰範本

🚀 Mini-RecSys：跳過筆記本，直達生產環境！端到端推薦系統 MLOps 實戰範本

厭倦了只有演算法理論的教學？想知道推薦模型如何「真正」上線服務嗎？

我們打造了 Mini-RecSys 專案，一個教學導向、可重現、可部署的端到端推薦系統範例。這個專案不僅示範了 Popularity Baseline 的實作，更提供了將模型從資料前處理、離線訓練、評估，到**線上服務化（FastAPI, Docker, CI）**的完整、規範化 MLOps Pipeline。

• 您可以透過以下 GitHub 連結檢閱本專案的原始碼：https://github.com/BpsEason/mini-recsys.git

它完美適用於工作坊教材、企業內訓，或任何想將機器學習模型帶入生產環境的開發者。

💎 專案核心價值：生產級架構的五大支柱

Mini-RecSys 的設計理念，是模擬一個高標準的數據工程專案：

1. 結構化與 MLOps 分層：

   • 設計：清晰劃分 Data / Source / Models / Tests 四大工程區塊。

   • 核心：src 目錄精細拆分 preprocess (資料切分)、train (模型訓練)、eval (離線評估) 和 serving (線上 API)，嚴格實踐 MLOps 規範。

2. 魯棒性與自動化 (CI/CD)：

   • 提供 setup.sh 腳本一鍵跑通完整示範流程。

   • 內建 GitHub Actions (ci.yml) 範例，示範如何在 CI 中建立小型 Fixture (模擬資料/模型) 並執行單元測試，確保程式碼品質。

3. 容器化部署：提供 Dockerfile 與 docker-compose.yml。只需一行指令即可在隔離環境中建置、啟動服務，完全模擬生產級部署情境。

4. 現代化 API 服務：採用 FastAPI 框架，實現高性能的 RESTful API。

   • 合約保障：利用 Pydantic 進行強型別輸入驗證，並自動生成 /docs API 文件。

   • 服務健康：內建 /healthz 端點，提供服務狀態和模型載入情況。

5. 極致的教學友善：所有 Python 程式檔均內含詳盡的正體中文教學註解與 Lab 提示，讓學習者能快速理解程式碼背後的意圖與設計邏輯。

---

🚀 快速啟動：五分鐘跑通整個 Pipeline

只需在 repo 根目錄下執行以下步驟（建議使用 Python 3.11 虛擬環境）：

1. 一鍵環境建置與依賴安裝：

   Bash

   python -m venv venv && source venv/bin/activate
   pip install -r requirements.txt
   

2. 資料處理與 Baseline 訓練：

   • 切分資料（若 MovieLens 原始檔不存在，會自動使用 Tiny Fixture）：

     python -m src.preprocess.split --method loo

   • 訓練人氣模型 (Popularity Baseline)：

     python -m src.train.train_popularity

3. 啟動 API 服務：

   • 開發模式：uvicorn src.serving.app:app --reload

   • API 文件： http://localhost:8000/docs

💡 開發用一鍵示範： 權限設置後，執行 ./setup.sh，直接跑通從資料到 API 啟動的所有流程。

---

📚 教學模組與課程大綱（教師 Rubric）

Mini-RecSys 的架構設計使其可以直接對應六大教學模組，適用於 2 小時到 12 小時的工作坊：

模組	主題焦點	關鍵技術與產出
I	專案導覽與啟動	熟悉專案結構，成功呼叫 /recommend。
II	資料切分與評估	理解 Leave-One-Out (LOO)，產出 train.csv/test.csv。
III	Baseline 實作	訓練並序列化 Popularity Model，儲存 metadata。
IV	離線評估	實作 Precision@K / Recall@K，撰寫實驗報告。
V	演算法擴充	(選作) 實作 Item-based k-NN 或 Matrix Factorization。
VI	部署、測試與 CI	理解模型載入機制，通過單元測試與 CI 自動化。

🏆 延伸挑戰：從教學到進階實務

1. 模型個性化：使用 surprise.KNNBasic 實作 Item-based k-NN，並比較 Precision@10 指標。

2. 排序強化：在 src/eval/metrics.py 中加入 NDCG@10，並解釋其在排序中的意義。

3. 高並發支持：加入 /batch_recommend 端點，以支援多使用者 ID 的批次查詢。

4. 工程進階：使用 FAISS 加速相似度檢索，或導入 MLflow 進行實驗追蹤與模型版本管理。

我們邀請所有對 MLOps 和推薦系統感興趣的開發者，立即探索這個專案，將您的 ML 技能從筆記本提升至生產環境！