Từ Jupyter Notebook Đến FastAPI: Hành Trình Đưa Mô Hình ML Lên Sản Xuất

Lê Lân

16/07/2025

Hướng Dẫn Triển Khai Mô Hình Machine Learning Từ Notebook Đến Ứng Dụng Thực Tế Với FastAPI

Mở Đầu

Bạn đã bao giờ tự hỏi làm thế nào để kết nối giữa các thí nghiệm machine learning (ML) trong môi trường nghiên cứu với ứng dụng thực tế chưa? Rất nhiều lần tôi đã dành hàng ngày để tối ưu hóa mô hình ML mà cuối cùng lại nhận ra triển khai vào sản xuất lại là một thử thách hoàn toàn khác biệt.

Trong bài viết này, tôi sẽ chia sẻ về dự án dự đoán churn khách hàng, đánh dấu hành trình đầy đủ của vòng đời ML - từ bước khám phá dữ liệu ban đầu trong Jupyter Notebook đến xây dựng dịch vụ FastAPI sẵn sàng xử lý dữ liệu khách hàng thực tế. Qua đó, bạn sẽ nhận thấy mô hình ML chỉ thực sự giá trị khi được phục vụ bởi một hệ thống hạ tầng hiệu quả, đáng tin cậy và dễ bảo trì.

Nội dung chính bao gồm:

Khó khăn chuyển đổi từ nghiên cứu sang sản xuất

Kiến trúc pipeline tùy chỉnh để đảm bảo tái sử dụng

Giải pháp xử lý dữ liệu mất cân bằng đặc thù trong churn prediction

Triển khai API sản xuất bằng FastAPI

Lưu trữ dữ liệu người dùng và dự đoán bền vững

Phương pháp serial hóa mô hình với cloudpickle

Bài học kinh nghiệm và tổng kết

Thách Thức Chuyển Đổi Từ Notebook Đến Ứng Dụng Thực Tế

Quá Trình Phát Triển ML Tiêu Chuẩn

Giai đoạn nghiên cứu: Khám phá dữ liệu, kỹ thuật tạo đặc trưng, huấn luyện mô hình trong notebook.

Giai đoạn đánh giá: Cross-validation, tìm kiếm siêu tham số, lựa chọn mô hình tối ưu.

Khoảng cách sản xuất: Nơi nhiều dự án thất bại vì thiếu hạ tầng triển khai thực tế.

Khoảng Cách Thiếu Hiểu Biết

Phần lớn thành công trong nghiên cứu lại gặp bế tắc do thiếu:

Lớp API phục vụ mô hình

Kiểm tra và xác thực dữ liệu đầu vào

Xử lý lỗi và bảo trì hệ thống

Khả năng mở rộng và vận hành liên tục

Kiến Trúc Pipeline Tùy Chỉnh Cho Hệ Thống ML Sản Xuất

Giới Thiệu Custom Transformers

Một pipeline chuẩn mực không thể thiếu những bước tiền xử lý đặc thù để bảo đảm tính nhất quán và tránh rò rỉ dữ liệu.

from sklearn.base import BaseEstimator, TransformerMixin
from sklearn.compose import ColumnTransformer
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import OneHotEncoder
import pandas as pd

class DurationTransform(BaseEstimator, TransformerMixin):
    def fit(self, X, y=None):
        return self
    def transform(self, X):
        if isinstance(X, pd.DataFrame):
            db = X.copy()
        else:
            db = pd.DataFrame(X, columns=["transactiondate", "membershipexpiredate"])
        db["transactiondate"] = pd.to_datetime(db["transactiondate"])
        db["membershipexpiredate"] = pd.to_datetime(db["membershipexpiredate"])
        result = (db["membershipexpiredate"] - db["transactiondate"]).dt.days
        return result.values.reshape(-1, 1)

genencoding = ColumnTransformer(
    [("gender", OneHotEncoder(), [1])],
    remainder='passthrough'
)

substime = ColumnTransformer(
    [("durationindays", DurationTransform(), [8, 9])],
    remainder='passthrough'
)

pipe = Pipeline([
    ('genencoding', genencoding),
    ('substime', substime),
])

Lý do quan trọng: Sử dụng custom transformer giúp tái sử dụng chính xác logic feature engineering trong cả huấn luyện và vận hành, phòng tránh rò rỉ dữ liệu và đảm bảo tái hiện kết quả mô hình.

Xử Lý Dữ Liệu Mất Cân Bằng Trong Dự Đoán Churn

Vấn Đề

Tỷ lệ churn thấp (~10-15%) so với khách hàng duy trì cao (~85-90%)

Mô hình có thể thiên vị dự đoán do tập dữ liệu mất cân bằng

Giải Pháp Undersampling

from sklearn.utils import resample

zeros = dbtrain[dbtrain['ischurn'] == 0]  # 9,354 non-churners
ones = dbtrain[dbtrain['ischurn'] == 1]   # 646 churners

zeros_undersampled = resample(zeros,
                              replace=False,
                              n_samples=len(ones),
                              random_state=42)

dbtrain_balanced = pd.concat([zeros_undersampled, ones])
dbtrain_balanced = dbtrain_balanced.sample(frac=1, random_state=42).reset_index(drop=True)

Kết Quả

Nhóm khách hàng	Số lượng	Tác động đến mô hình
Churners	646	Đảm bảo mô hình không bỏ sót khách hàng rời đi
Không churners	646	Cân bằng giúp mô hình chính xác hơn

Xây Dựng API Sản Xuất Với FastAPI

Thiết Kế Ứng Dụng

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Optional
from datetime import date
import pandas as pd

app = FastAPI(
    title="Customer Churn Prediction",
    description="Production-ready ML API for customer churn prediction",
    version="1.0.0"
)

class DataVal(BaseModel):
    userid: Optional[int] = None
    city: int
    gender: str
    registeredvia: int
    paymentmethodid: int
    paymentplandays: int
    actualamountpaid: int
    isautorenew: int
    transactiondate: date
    membershipexpiredate: date

@app.post("/predict")
def predict(
    city: int,
    gender: str,
    registeredvia: int,
    paymentmethodid: int,
    paymentplandays: int,
    actualamountpaid: int,
    isautorenew: int,
    transactiondate: date,
    membershipexpiredate: date,
    userid: Optional[int] = None
):
    data = DataVal(
        userid=userid,
        city=city,
        gender=gender,
        registeredvia=registeredvia,
        paymentmethodid=paymentmethodid,
        paymentplandays=paymentplandays,
        actualamountpaid=actualamountpaid,
        isautorenew=isautorenew,
        transactiondate=transactiondate,
        membershipexpiredate=membershipexpiredate
    )
    # Continue with validation, transformation and prediction

Điểm Nổi Bật

Tự động tạo tài liệu API tương tác tại /docs

Xác thực dữ liệu với Pydantic, giúp giảm thiểu lỗi dữ liệu nhập

Xử lý lỗi tinh tế với thông báo rõ ràng cho người dùng

Quản lý người dùng tự động tạo ID nếu chưa có

FastAPI giúp rút ngắn thời gian phát triển, tăng hiệu quả vận hành nhờ các tính năng chuẩn bị sẵn.

Lưu Trữ Dữ Liệu Và Quản Lý Người Dùng

Quản Lý ID Người Dùng và Lưu Kết Quả

import json
import os

def valid_user(user: int):
    if pd.isna(user):
        with open("data/users.json", "r") as f:
            data = json.load(f)
        max_user = max(data)
        user = max_user + 1
        data.append(int(user))
        with open("data/users.json", "w") as f:
            json.dump(data, f, indent=2)
        return user
    else:
        with open("data/users.json", "r") as f:
            data = json.load(f)
        if user not in data:
            data.append(int(user))
            with open("data/users.json", "w") as f:
                json.dump(data, f, indent=2)
        return user

def save_prediction(result: dict):
    json_path = "data/userdata.json"
    if os.path.exists(json_path):
        with open(json_path, "r") as f:
            json_file = json.load(f)
    else:
        json_file = {}
    json_file.update(result)
    with open(json_path, "w") as f:
        json.dump(json_file, f, indent=2)

Việc lưu trữ phiên bản dữ liệu người dùng và dự đoán không chỉ hỗ trợ audit mà còn giúp kiểm soát truy xuất dữ liệu phục vụ tuân thủ như GDPR.

Serial Hóa Mô Hình Với Cloudpickle

Lý Do Chọn Cloudpickle

Hỗ trợ lưu các pipeline phức tạp với custom transformers

Đáng tin cậy hơn pickle truyền thống

Ví Dụ Lưu Và Tải Mô Hình

import cloudpickle

# Lưu mô hình và pipeline
with open("model/model.pickle", "wb") as f:
    cloudpickle.dump(adaboost_model, f)

with open("model/pipe.pickle", "wb") as f:
    cloudpickle.dump(pipe, f)

# Tải mô hình và pipeline trong môi trường sản xuất
with open("model/model.pickle", "rb") as f:
    model = cloudpickle.load(f)

with open("model/pipe.pickle", "rb") as f:
    pipe = cloudpickle.load(f)

Tổng Quan Kiến Trúc Hệ Thống

┌─────────────────────┐   ┌─────────────────────┐   ┌─────────────────────┐
│    Jupyter Notebook │ ─▶ │      FastAPI Service│ ─▶ │    Production Setup │
│  • Data Exploration │    │  • REST API         │    │ • Load Balancer     │
│  • Model Training   │    │  • Data Validation  │    │ • Auto-scaling      │
│  • Pipeline Dev     │    │  • Error Handling   │    │ • Monitoring        │
└─────────────────────┘   └─────────────────────┘   └─────────────────────┘
         │                        │                          │
         ▼                        ▼                          ▼
┌────────────────┐       ┌─────────────────┐        ┌─────────────────┐
│ Custom         │       │ Pydantic Models │        │ JSON Storage &  │
│ Transformers   │       │ (Input Validation) │      │ User Management │
└────────────────┘       └─────────────────┘        └─────────────────┘

Kết Quả Và Hiệu Suất

Mô Hình	Độ chính xác	Tình trạng sản xuất
AdaBoost	89.08%	✅ Sản xuất chính
Random Forest	87.39%	✅ Dự phòng
Decision Tree	88.24%	✅ Dễ giải thích
Voting Classifier	82.35%	✅ Mô hình tập hợp

Bài Học Kinh Nghiệm

Hạ tầng quan trọng hơn bạn nghĩ: Mô hình chính xác cao vô dụng nếu hệ thống không ổn định.

Xác thực dữ liệu không thể thương lượng: Giảm thiểu lỗi và tối ưu thời gian debug bằng Pydantic.

Custom transformers là chìa khóa: Giúp bảo đảm nhất quán dữ liệu, tránh rò rỉ.

Quản lý người dùng rất quan trọng: Theo dõi, xác thực và tuân thủ luật pháp.

Xử lý lỗi tinh tế: Giữ hệ thống đáng tin cậy và dễ bảo trì.

Công nghệ sử dụng: FastAPI, Python 3.8+, scikit-learn, pandas, numpy, Pydantic, cloudpickle, JSON Storage.

Kết Luận

Việc phát triển một API ML chất lượng sản xuất đòi hỏi nhiều hơn là chỉ làm ra mô hình tốt. Cần có một hệ thống hạ tầng vững chắc với:

Thiết kế API và xử lý lỗi chuẩn mực

Đảm bảo dữ liệu chính xác, ổn định

Cải thiện trải nghiệm người dùng và tài liệu rõ ràng

Tích hợp logic nghiệp vụ liên quan đến quản lý người dùng và tuân thủ

Mấu chốt: Mô hình ML hiệu quả chỉ là một phần, chất lượng của hệ thống cung cấp mô hình mới quyết định sự thành công trong thực tế.

Bạn đã từng trải nghiệm gì khi triển khai ML vào sản xuất? Hãy chia sẻ thách thức và giải pháp của bạn dưới phần bình luận!

Tham Khảo

FastAPI Documentation

Pedregosa et al., 2011. Scikit-learn: Machine Learning in Python

Cloudpickle GitHub Repository

Géron, A. (2019). Hands-On Machine Learning with Scikit-Learn and TensorFlow, O’Reilly.

Pydantic Documentation

Chollet, F. (2018). Deep Learning with Python, Manning Publications.

June 1, 2024