Python部署Scikit-learn模型为FastAPI微服务

将Scikit-learn模型部署为FastAPI微服务，听起来步骤简单，但实际落地时暗藏诸多陷阱；踩过坑的人，都深有体会。

先梳理几个核心判断：模型加载不稳定、数据格式不匹配、输入校验不全面、启动配置不周全，这四件事但凡有一项没处理好，线上服务说崩就崩。问题往往不在于模型精度不足，而是服务本身扛不住压力。下面把几个关键环节逐一拆解，全是干货，没有废话。

模型加载：别用pickle，改用joblib

Scikit-learn官方早已给出明确建议——使用joblib来保存和加载模型。尤其是RandomForestClassifier、LogisticRegression这类内部包含大量NumPy数组的对象，joblib在序列化效率和兼容性上都明显优于pickle。

有些开发者在不同环境间复制模型时，图省事直接用pickle.load()，结果冷不丁抛出ModuleNotFoundError: No module named 'sklearn.ensemble._forest'。这其实不是模型本身的问题，而是pickle在跨环境时对模块路径的依赖过于脆弱。

实际操作中，务必记住以下三点：

• 训练完成后，统一使用joblib.dump(model, "model.joblib")保存模型；
• FastAPI服务启动时，在main.py顶层全局加载一次模型，例如model = joblib.load("model.joblib")，避免每次请求都重新读取磁盘；
• 部署环境的scikit-learn版本，必须与训练环境严格保持一致。最稳妥的方法是用pip freeze > requirements.txt锁定所有依赖版本。

请求体：维度不对，模型不予理睬

你猜怎么着？很多人在这一步就栽了跟头。

Scikit-learn的predict()和predict_proba()方法，要求输入必须是二维数组——哪怕只预测一个样本，也得是[[1.0, 2.0, 3.0]]这种形式。但FastAPI默认将JSON解析成Python的list/dict，如果前端传来一维数组，比如{"features": [5.1, 3.5, 1.4, 0.2]}，模型直接报错：ValueError: Expected 2D array, got 1D array instead。

解决方案其实很简单：

• 在Pydantic模型中，用List[float]表示单个样本，再在外层封装成List[List[float]]，强制要求二维结构；
• 更推荐的做法是直接定义成class PredictionRequest(BaseModel): features: List[List[float]]，让前端从一开始就传对格式；
• 如果前端实在只能传一维，那就后端手动转换成np.array([request.features])，别指望模型能自动广播。

预测路径：校验不到位，出问题是迟早的事

用户传过来的数据，质量参差不齐。NaN、inf、非数值字段、特征数量不对——这些情况如果不在预测路径里提前拦截，模型会直接抛出异常，导致整个请求处理流程中断，FastAPI只能返回一个干巴巴的500错误。调试起来，令人头大。

值得强调的是，校验这件事绝对不能偷懒。以下几步必须做到：

• 用np.array(request.features, dtype=np.float64)做强制类型转换，如果转换失败，捕获ValueError并返回422状态码，附带清晰的错误说明；
• 检查数据维度：if X.shape[1] != expected_n_features:，一旦发现特征数量不匹配，直接告知用户期望的输入维度；
• 过滤掉存在NaN或inf的数据：if not np.isfinite(X).all():，拒绝该批次请求，防止模型内部运算出现异常；
• 把整个预测逻辑包裹在try/except里，避免未捕获的异常导致worker崩溃。

这些校验听起来琐碎，但线上出问题时，往往就卡在这里——不是模型不准，而是数据格式没兜住。

启动配置：开发和生产，两套不同逻辑

本地开发和生产部署的启动方式，差别非常大。

开发时，加上reload=True，方便热重载：uvicorn.run("main:app", reload=True, host="0.0.0.0", port=8000)。但到了生产环境，这套配置就不够用了。

生产部署必须考虑并发能力。建议直接用命令行启动：uvicorn main:app --workers 4 --host 0.0.0.0 --port 8000，其中--workers的数量建议设置为CPU核数或略高。如果服务部署在容器里，这种方式也更方便进程管理和零停机更新。

另外，不要在代码里硬写if __name__ == "__main__":启动逻辑，改用命令行方式，更灵活，也更符合容器化部署的规范。

模型输入校验和worker配置，这两块最容易在前期被忽略。但上线之后，一旦流量涨起来，出问题的往往就是它们——要么格式不对导致请求被拒，要么并发一上来worker排队超时。说到底，模型本身只是服务的一部分，让它稳定、安全地跑起来，才是真正的工程能力。