必须在写第一行路由代码前就处理好模型加载、输入规整和并发配置：模型需顶层或lifespan一次性加载并存为全局变量；Pydantic须显式声明字段顺序并转二维数组；Uvicorn必须设--workers且锁死sklearn版本。
能跑不等于能用——FastAPI 启动后模型加载失败、高并发下响应卡死、输入格式错导致 ValueError: Expected 2D array，这三类问题占线上故障的 80% 以上。必须在写第一行路由代码前就处理好模型加载、输入规整和并发配置。
模型不能在 @app.post 里加载
每次请求都执行 joblib.load("model.pkl")，会导致内存持续上涨、首次响应超 5 秒、多 worker 下模型重复加载甚至崩溃。
- 正确做法：在
main.py顶层或lifespan中一次性加载，存为全局变量 - 若用 pipeline（含 scaler + clf），必须用
joblib.load()加载整个对象，别分开 load - 路径务必用绝对路径或基于
__file__构造，避免部署时因工作目录变化导致FileNotFoundError - 加日志确认加载成功：
logger.info(f"Loaded model with {model.n_estimators} trees")
Pydantic 输入校验必须覆盖 shape 和字段顺序
前端传 {"sepal_length": 5.1, "sepal_width": 3.5}，但模型训练时列顺序是 ["sepal_length", "sepal_width", "petal_length", "petal_width"]，直接转 list(dict.values()) 会错乱。
- 定义
BaseModel显式声明字段名和顺序，例如：class IrisInput(BaseModel): sepal_length: float; sepal_width: float; petal_length: float; petal_width: float - 进模型前强制转二维：
np.array([request.sepal_length, request.sepal_width, ...]).reshape(1, -1) - 数值范围用
Field(gt=0, lt=10)校验，防异常值直接进模型引发 NaN 输出 - 别依赖
request.dict().values()，字典键顺序在 Python 3.7+ 虽保证插入序，但易被重构破坏
Uvicorn 启动参数不调，--workers 就是摆设
默认单 worker 模式下，哪怕 CPU 有 8 核，所有请求也排队等一个模型实例——sklearn 推理本质是同步阻塞，async 不解决这个问题。
立即学习“Python免费学习笔记（深入）”；
- 生产必须加
--workers N，N 通常设为os.cpu_count()或其 1.5 倍（如 4 核机器设--workers 6） - 禁用
--reload：开发时方便，但会触发多次模型加载，且无法用于生产 - 加
--timeout-keep-alive 5防长连接堆积，加--limit-concurrency 100控制瞬时并发数 - 启动命令示例：
uvicorn app.main:app --workers 4 --host 0.0.0.0 --port 8000 --timeout-keep-alive 5
最容易被忽略的是模型版本与 sklearn 版本强绑定——joblib.load() 在 sklearn 1.4.2 训练的模型，用 1.5.0 加载大概率报 AttributeError 或预测结果错乱。上线前必须锁死 scikit-learn==1.4.2 并验证 predict 结果一致性。
