将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排队超时。说到底，模型本身只是服务的一部分，让它稳定、安全地跑起来，才是真正的工程能力。
