模型从Notebook迁移到生产API，必须保留完整流水线

很多人在Notebook里训练出个不错的准确率就高兴了，但那只是个.ipynb文件，前端没法用，业务analyst看不懂，更别说直接集成到产品里了。所以我从电信用户流失预测模型入手，把整个预测流程从实验环境迁到生产环境，用FastAPI封装成API，让本地死掉的模型变了活。

关键就在这：不能只保存模型权重，必须连预处理流水线一起打包。

前言：为什么Notebook里的模型没法直接用

一个Notebook里的模型，背后可是一连串的数据清洗、特征工程、编码编码等操作。你如果只保存了训练好的模型参数，到了API那边接收原始JSON，还得手动写一遍缩放、One-Hot编码等逻辑，那样不仅容易出错，还容易出幻觉性错误。

所以我的思路是：把整个pipeline（预处理+模型）一起保存，部署时只需要加载这个文件，接进来的数据就能被原样处理，预测输出也能还原成Yes/No标签。

第一步：从数据到可部署模型

在正式写API之前，Notebook里的整个处理流程必须闭环，否则部署时因为数据格式不一致，直接就崩了。

如何确保数据清洗逻辑在生产环境一致？

1. 数据清洗与对齐

处理了7000多条客户数据，主要解决列名空格问题、类型错误（比如数值列被误识为字符串）。这些问题如果不处理，在推理阶段模型直接就挂了。

1. 特征工程与标准化

对tenure这种数值列做缩放，对Contract这类变量做One-Hot编码。

1. 模型选择与持久化

对比逻辑回归、KNN、随机森林，选了最好的那一个。用joblib把整个pipeline加上label encoder一起保存。

如果没有这个pipeline整体保存，你在API端就得写一遍又一遍缩放和编码逻辑，那不仅麻烦，还容易出错。

第二步：FastAPI构建预测接口

为什么选FastAPI？因为它自带Pydantic校验，能强制要求请求体符合定义好的格式，省去写一堆if-else校验数据的麻烦。

为什么选择FastAPI来部署这个预测模型？

import joblib
from fastapi import FastAPI
from pydantic import BaseModel
import pandas as pd

labels = joblib.load('../models/target_labels.joblib')
model = joblib.load('../models/ml_pipeline.joblib')

app = FastAPI(
    title="Customer Churn Prediction API",
    description="Predict whether a customer will churn based on their usage patterns"
)

## API如何处理缺失字段或格式错误的请求？

class CustomerData(BaseModel):
    gender: str
    tenure: int
    Contract: str
    MonthlyCharges: float
    # 其他必要字段...

@app.post("/predict")
async def predict_churn(data: CustomerData):
    input_df = pd.DataFrame([data.dict()])
    prediction = model.predict(input_df)
    result = labels.inverse_transform(prediction)[0]
    return {"churn_prediction": result}

第三步：部署实战复盘

部署前如何验证模型pipeline的完整性？

这次部署最大的感悟是：一个能用的API依赖的是一个完整的、可复现的artifact文件，而不是一段训练代码。如果API端在构建pd.DataFrame的时候漏掉了一个字段，或者字段顺序不对，joblib加载的模型就会报一个非常难懂的维度错误，查起来烦得要死。

所以建议部署前，用一个小规模的JSON样本在本地模拟一次predict过程，确认pipeline能正确处理输入数据，输出的标签映射也没问题，再去写FastAPI路由逻辑。

这样不仅能提前暴露问题，还能避免在生产环境里因为格式不一致导致的沉默性失败。