模型需启动时全局加载、uvicorn必须用--workers、Pydantic校验不可省略;否则上线当日必出问题。

模型不能在每次请求里加载,uvicorn 不加 --workers 就别想扛住并发,Pydantic 校验不是可选项——这三件事做错一个,服务上线当天就会出问题。
模型必须启动时全局加载,别放 @app.post 里
常见错误是把 joblib.load("model.pkl") 或 torch.load("model.pth") 写在路由函数内部。结果每个请求都触发一次磁盘读取+反序列化+显存分配,小模型延迟翻倍,大模型直接 OOM。
- 正确做法:在
main.py顶层或models.py中实例化一次,作为模块级变量复用 - 若需异步预热(如加载 tokenizer、预分配 CUDA cache),改用
lifespan事件,而非已弃用的on_event("startup") - 加载后建议打日志:
logger.info(f"Model loaded in {elapsed:.2f}s, size: {size_mb:.1f} MB"),方便压测时定位瓶颈
uvicorn 启动必须设 --workers,否则单核排队等死
默认 uvicorn app:app 是单 worker + 单线程,哪怕模型本身支持 GPU 并行,HTTP 层也卡在一条流水线上。实测 sklearn 模型 QPS 不到 5,PyTorch 模型更可能因 GIL 锁死。
- 生产必须加
--workers N,N 推荐设为 CPU 物理核心数(非超线程数),例如 8 核机器用--workers 8 - 禁用
--reload:开发时方便,但会重复触发模型加载,且无法与--workers共存 - 补充关键参数:
--timeout-keep-alive 5防长连接堆积,--limit-concurrency 100控制瞬时请求数,避免突发流量冲垮显存
输入必须用 Pydantic 强校验,别信任何 request.json()
前端传个 {"features": null} 或 {"features": ["a", "b"]},模型直接抛 ValueError,500 响应暴露堆栈,还可能泄露本地路径。这不是健壮性问题,是安全红线。
Python 环境工具专业版功能概述Python 环境工具专业版是一项面向实际任务的技能。它将相关步骤、工具调用和结果整理方式集中到统一流程中,帮助使用者更快完成目标并减少重复操作。核心要点使用时应结合输入条件选择合适的执行方式,核对必要参数、依赖环境与输出内容,并按原始要求处理异常情况。该技能适合需要稳定复用相关能力的场景,可作为自动化工作流的一部分,也便于后续检查、调整和扩展。执行完成后建议检查结果是否符合预期,并保留必要记录。使用与执行同时注意输入完整性、执行条件和输出可用性。从功能定位来看,该技能
立即学习“Python免费学习笔记(深入)”;
- 定义
InputSchema显式约束字段类型、长度、数值范围,例如:features: list[float] = Field(..., min_items=4, max_items=4) - 用
@app.post("/predict", response_model=OutputSchema)同时校验出入参结构,FastAPI 自动生成 OpenAPI 文档和 Swagger 示例 - 图像/音频等二进制数据走
UploadFile,别手动读await request.body(),否则丢失文件名、MIME 类型,且无法流式处理
错误要分层捕获,模型异常绝不能透出 500
模型推理失败原因五花八门:sklearn.exceptions.NotFittedError、torch.cuda.OutOfMemoryError、预处理时 KeyError……全扔 500 给调用方,下游根本没法区分是数据问题还是服务宕机。
- 核心预测逻辑外层套
try/except,按异常类型映射 HTTP 状态码:数据问题用422 Unprocessable Entity,资源不足用503 Service Unavailable - 响应体只返回业务语义化信息,例如:
{"detail": "输入特征维度应为4,实际收到3"},不带 traceback - 完整错误日志写入文件(非 stdout),并记录请求 ID、时间戳、输入摘要,方便事后回溯
最常被忽略的是模型与框架的阻塞边界:FastAPI 再快,model.predict() 是同步 CPU 密集操作,它不会因为你用了 async def 就自动变快。真要提升吞吐,得靠 --workers 拆进程,而不是幻想异步能解决一切。


















