# 笔记本上能跑的模型，到客户服务器上未必能加载

> scikit-learn 不支持跨版本加载模型，所以要锁定环境、用 skops 保存，再交付 FastAPI 容器。

原文: https://fdetimes.net/zh/guides/scikit-learn-model-to-api-customer-infrastructure/

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 步会说明。

```bash
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 就不必自己重写一遍缩放步骤。

```python
# 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，只加载类型和函数引用均受信任的文件，信任来源可以是默认设置，也可以由用户指定。加载前，先列出尚未受信任的类型，逐行亲自阅读；审查完毕后，再把这份清单写入一个随模型一起交付的文件：

```python
# 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 文档要求服务环境与训练环境拥有相同的包和相同的版本。所以训练完成后立即记录版本，趁你还确切知道模型是由什么环境产出的：

```bash
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 步审查过的文件中读取。如果清单为空，而模型文件里又有默认不受信任的类型，服务一启动就会加载失败。

```python
# 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` 启动试试，然后调用：

```bash
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 事件也会触发。

```dockerfile
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`。构建并运行：

```bash
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 的仓库链接。

准确的模型帮你赢下演示；在客户服务器上一次就能启动的镜像，才让客户再次找你。

**本周动手试试:**

- 按文中步骤训练鸢尾花模型，保存为 model.skops，运行 get_untrusted_types，并记录你审查过的类型清单
- 构建 Docker 镜像，用 curl 调用 /predict，然后故意修改 requirements.txt 中的 scikit-learn 版本，看看在哪里出问题
- 在简历上加一行具体内容：“将 scikit-learn 模型打包为容器化的 FastAPI API，锁定版本，用 skops 替代 pickle 保存”

## 信源

- [What is model training?](https://www.ibm.com/think/topics/model-training)

- [What is Scikit-Learn (Sklearn)?](https://www.ibm.com/think/topics/scikit-learn)

- [Model persistence — scikit-learn documentation](https://scikit-learn.org/stable/model_persistence.html)

- [PyTorch Foundation (pytorch.org)](https://pytorch.org/)

- [FastAPI in Containers - Docker](https://fastapi.tiangolo.com/deployment/docker/)

- [kserve/kserve (GitHub)](https://github.com/kserve/kserve)
