笔记本上能跑的模型,到客户服务器上未必能加载
scikit-learn 不支持跨版本加载模型,所以要锁定环境、用 skops 保存,再交付 FastAPI 容器。
要点速览
- scikit-learn 不支持加载用其他版本训练的模型,因此服务环境必须锁定与训练时相同的包和版本。
- 绝不要加载来源不可信的 pickle 文件。skops.io 只加载已被信任的类型。
- 用 exec 形式的 CMD 将 FastAPI 容器化。在 Kubernetes 上每个容器只跑一个 Uvicorn 进程,副本交给集群管理。
scikit-learn 文档里有一句话,每个 FDE 都应该烂熟于心:用其他版本 scikit-learn 训练的模型,没有任何受支持的加载方式。模型在你的笔记本上运行完美,客户服务器上装的却是另一个版本。这时,没有什么能保证模型加载得了;就算加载成功,也不能保证它行为正确。
这正是数据科学家和前线部署工程师(FDE)的差别。前者交出一个模型文件;后者交出一个能在客户基础设施上运行的服务:环境已锁定,制品是安全的,启动流程客户的运维团队也看得懂。
本指南用一个刻意做小的例子走完整条路径:用 scikit-learn 训练鸢尾花分类器,用 FastAPI 封装,再打包成容器。例子简单,是为了让你把精力放在真正困难的部分:把模型从笔记本上带出去。
要做出什么,需要准备什么?
最终产物是一个 Docker 镜像,对外提供 POST /predict 端点,接收四个数值特征,返回预测标签。你需要 Python、Docker,以及 scikit-learn、skops、fastapi 和 uvicorn 这几个包。如果之后想用 PyTorch 重做一遍,注意其最新稳定版要求 Python 3.10 及以上,所以一开始就选 Python 3.10 或更高版本,两条路线可以共用同一个基础环境。
所有操作都在一个专为本项目新建的干净 virtualenv 中完成,原因在第 3 步会说明。
python -m venv .venv
source .venv/bin/activate
pip install scikit-learn skops fastapi uvicorn
推荐的目录结构:根目录放 train.py,app/main.py 放 API,model/ 放制品,另有 requirements.txt 和 Dockerfile。
第 1 步:训练一个 pipeline,而不是一堆零散的 notebook 单元格
IBM 把训练描述为:选择模型、收集和准备数据、选定超参数、计算损失、优化参数,最后做评估。在 scikit-learn 中,最干净的做法是把数据预处理和模型打包进同一个 pipeline,这样 API 就不必自己重写一遍缩放步骤。
# train.py — 简化示例
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression
import skops.io as sio
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(
X, y, test_size=0.2, random_state=42)
model = make_pipeline(StandardScaler(), LogisticRegression(max_iter=1000))
model.fit(X_train, y_train)
print("准确率:", model.score(X_test, y_test))
sio.dump(model, "model/model.skops")
检查:运行 python train.py,应看到打印出的准确率,并生成 model/model.skops。只保存模型、漏掉 scaler 是经典错误:API 收到的是原始数据,会给出错误预测,却不报任何错。
第 2 步:为什么不用 pickle?
scikit-learn 文档说得很直白:绝不要加载来源不可信的 pickle 文件,就像绝不运行来源不可信的代码一样。在客户现场,这条建议非常实际。一个制品到达服务器之前,可能经过共享盘、存储桶,或者好几个人的邮件。
skops.io 不使用 pickle,只加载类型和函数引用均受信任的文件,信任来源可以是默认设置,也可以由用户指定。加载前,先列出尚未受信任的类型,逐行亲自阅读;审查完毕后,再把这份清单写入一个随模型一起交付的文件:
# review_types.py — 简化示例
from pathlib import Path
import skops.io as sio
unknown = sio.get_untrusted_types(file="model/model.skops")
print(unknown) # 信任之前逐行仔细阅读
# 审查完上面的清单后,才运行下面这一行
Path("model/trusted_types.txt").write_text("\n".join(unknown))
上面的代码为演示做了简化,请对照已安装的 skops 版本核对函数签名。关键在于,信任清单必须是你亲眼审查过的,而不是为了跑通流程直接透传。trusted_types.txt 会成为制品的一部分:任何审查模型的人都能看到你选择信任了什么。
第 3 步:写 API 之前先锁定环境
scikit-learn 文档要求服务环境与训练环境拥有相同的包和相同的版本。所以训练完成后立即记录版本,趁你还确切知道模型是由什么环境产出的:
python -c "import sklearn; print(sklearn.__version__)"
pip freeze > requirements.txt
要在开头新建的干净 virtualenv 里运行 pip freeze,而不是在机器共用的 Python 环境里。否则 requirements.txt 会把你为其他项目装过的所有库都带进来,镜像变得臃肿,客户团队也很难看出模型真正需要什么。
检查:打开 requirements.txt,找到一行带具体版本号的 scikit-learn==。清单中应只包含上面安装的包及其依赖。如果看到没有版本号的 scikit-learn,或者是 >=,就等于给本文开头描述的那种故障留了门。
第 4 步:用 FastAPI 封装模型
API 只该做三件事:启动时加载一次模型,校验输入,调用 predict。信任清单从第 2 步审查过的文件中读取。如果清单为空,而模型文件里又有默认不受信任的类型,服务一启动就会加载失败。
# app/main.py — 简化示例
from pathlib import Path
from fastapi import FastAPI
from pydantic import BaseModel
import skops.io as sio
# 第 2 步中审查过的类型
TRUSTED = Path("model/trusted_types.txt").read_text().split()
model = sio.load("model/model.skops", trusted=TRUSTED)
app = FastAPI()
class Features(BaseModel):
values: list[float]
@app.post("/predict")
def predict(f: Features):
pred = model.predict([f.values])
return {"prediction": int(pred[0])}
用 uvicorn app.main:app --port 8000 启动试试,然后调用:
curl -X POST localhost:8000/predict \
-H "Content-Type: application/json" \
-d '{"values": [5.1, 3.5, 1.4, 0.2]}'
检查:应返回带 prediction 字段的 JSON。再试着只发三个数而不是四个,看 API 如何反应。在客户现场,格式错误的数据是家常便饭,错误信息长什么样要提前想好。
第 5 步:容器化,让客户能复现
FastAPI 出于安全性、可复现性和简洁性的考虑推荐使用容器。其文档里有两个细节值得一开始就做对:先复制 requirements.txt,以利用分层缓存;CMD 始终使用 exec 形式,这样 FastAPI 能优雅退出,lifespan 事件也会触发。
FROM python:3.11
WORKDIR /code
COPY ./requirements.txt /code/requirements.txt
RUN pip install --no-cache-dir -r /code/requirements.txt
COPY ./app /code/app
COPY ./model /code/model
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "80"]
第一行的 Python 镜像应与训练时的版本一致。model/ 目录里同时有 model.skops 和 trusted_types.txt。构建并运行:
docker build -t iris-api .
docker run -p 8000:80 iris-api
检查:重复第 4 步的 curl 命令,结果必须完全相同。如果不同,说明容器内的环境已经偏离了训练环境。
在现场让你白费一天的错误
一个容易犯的错误是用 shell 形式写 CMD,例如 CMD uvicorn app.main:app。FastAPI 文档强调应始终使用 exec 形式,这样应用才能优雅退出,lifespan 事件才会触发。不用 exec 形式,恰恰在 Kubernetes 或运维团队停止容器的那一刻,你就失去了这个保证。
第二个错误是在 Kubernetes 上运行的容器里塞进多个 Uvicorn worker。FastAPI 文档建议,当集群已负责副本管理时,每个容器只跑一个 Uvicorn 进程:让集群去扩展 Pod 数量,而不是在容器内部扩展。
最后一个错误是升级某个库后在笔记本上重新训练,然后只把新模型文件发给客户。模型和镜像必须始终成对交付,并且来自同一次构建。
这项技能在客户那里如何体现?
第一次技术会议上,该问的不是“用哪个模型”,而是“服务将在哪里运行”。如果客户在几台虚拟机上跑 Docker,第 5 步的镜像几乎就够用了。如果对方已经有 Kubernetes,就准备单进程容器,并问清平台团队如何扩容。
如果客户已经在运行 Kubernetes,值得考虑 KServe:它是面向预测式和生成式模型的分布式推理平台,也是 CNCF 孵化项目。对于 PyTorch 模型,PyTorch 官网介绍了用于从 eager 模式转向 graph 模式的 TorchScript,以及用于缩短上线路径的 TorchServe。
无论选择哪个平台,锁定版本、把制品当作代码对待,这两条原则都不变。
阅读 FDE 岗位描述时,留意“deploy into customer environments”“on-prem”或“Kubernetes”这类字眼。它们说明这个岗位恰好需要本指南中的整条技能链。简历上不要写“懂机器学习”,而要写你把模型打包成容器中的 API、锁定了环境、用更安全的格式替代了 pickle,并附上包含 Dockerfile 的仓库链接。
准确的模型帮你赢下演示;在客户服务器上一次就能启动的镜像,才让客户再次找你。
这篇文章对你有帮助吗?
感谢你的反馈!