机器学习与深度学习 / 系统课时

构建推理接口

构建推理接口

模型文件准备好之后,还需要一个稳定的服务边界来接收输入、执行预处理并返回预测。本课使用 FastAPI 构建最小可运行接口,确保模型只加载一次、非法请求被拦截,并让响应结构保持明确可验证。

学习目标

  • 定义带长度和数值约束的预测请求与响应模型
  • 在服务启动阶段加载模型,并使用推理模式执行预测
  • 通过 HTTP 请求验证成功响应和接口运行状态

接口需要承担什么

推理接口不应只是把 model(x) 暴露出去。它至少要负责输入校验、张量转换、模型调用、后处理和响应序列化;生产环境还应补充鉴权、限流、日志、指标与超时控制。

推理请求处理链路

完整服务实现

下面的 app.py 使用四维特征输入和三分类线性模型。为了让示例能够独立运行,首次启动时会生成一份固定的演示权重;生产环境应删除自动生成逻辑,并把 MODEL_PATH 指向经过验证的真实模型权重。

python
import math
from contextlib import asynccontextmanager
from pathlib import Path

import torch
from fastapi import FastAPI, Request
from pydantic import BaseModel, Field, field_validator
from torch import nn

MODEL_PATH = Path("classifier-state.pth")

class TinyClassifier(nn.Module):
    def __init__(self) -> None:
        super().__init__()
        self.linear = nn.Linear(4, 3)

    def forward(self, x: torch.Tensor) -> torch.Tensor:
        return self.linear(x)

def create_demo_weights(path: Path) -> None:
    model = TinyClassifier()
    with torch.no_grad():
        model.linear.weight.copy_(
            torch.tensor(
                [
                    [0.5, -0.2, 0.1, 0.0],
                    [-0.1, 0.3, 0.4, -0.2],
                    [0.2, 0.1, -0.3, 0.5],
                ],
                dtype=torch.float32,
            )
        )
        model.linear.bias.copy_(
            torch.tensor([0.1, -0.05, 0.0], dtype=torch.float32)
        )
    torch.save(model.state_dict(), path)

def load_model() -> TinyClassifier:
    if not MODEL_PATH.exists():
        create_demo_weights(MODEL_PATH)

    model = TinyClassifier()
    state_dict = torch.load(
        MODEL_PATH,
        map_location="cpu",
        weights_only=True,
    )
    model.load_state_dict(state_dict)
    model.eval()
    return model

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时加载一次,避免每个请求重复读取模型文件。
    app.state.model = load_model()
    yield
    del app.state.model

app = FastAPI(title="Tiny Classifier API", lifespan=lifespan)

class PredictRequest(BaseModel):
    features: list[float] = Field(min_length=4, max_length=4)

    @field_validator("features")
    @classmethod
    def reject_non_finite(cls, values: list[float]) -> list[float]:
        if not all(math.isfinite(value) for value in values):
            raise ValueError("features must contain finite numbers")
        return values

class PredictResponse(BaseModel):
    class_id: int
    confidence: float
    probabilities: list[float]

@app.get("/health")
def health() -> dict[str, str]:
    return {"status": "ok"}

@app.post("/predict", response_model=PredictResponse)
def predict(payload: PredictRequest, request: Request) -> PredictResponse:
    model: TinyClassifier = request.app.state.model
    inputs = torch.tensor([payload.features], dtype=torch.float32)

    # inference_mode 同时关闭梯度记录和推理中不需要的状态更新。
    with torch.inference_mode():
        logits = model(inputs)
        probabilities = torch.softmax(logits, dim=1)[0]

    class_id = int(torch.argmax(probabilities).item())
    values = [round(float(value), 6) for value in probabilities.tolist()]
    return PredictResponse(
        class_id=class_id,
        confidence=values[class_id],
        probabilities=values,
    )

预期结果:将代码保存为 app.py 后,首次启动会在当前目录创建 classifier-state.pth,随后模型被加载到应用状态中。访问 /health 返回服务状态,访问 /predict 返回类别、置信度和全部类别概率。

启动并发送请求

运行环境需要安装 torch、fastapi、pydantic 和 uvicorn。在 app.py 所在目录启动服务:

bash
uvicorn app:app --host 0.0.0.0 --port 8000

预期输出:

text
INFO:     Started server process [<ID>]
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000

<ID> 为动态进程号,日志格式可能随 Uvicorn 版本略有差异。服务启动后发送预测请求:

bash
curl -X POST "http://127.0.0.1:8000/predict" -H "Content-Type: application/json" -d '{"features":[1.0,0.5,-0.5,2.0]}'

预期状态码为 200,响应体为:

json
{"class_id":2,"confidence":0.656997,"probabilities":[0.254088,0.088915,0.656997]}

校验与部署边界

features 长度不是 4,或包含 NaN、正无穷等非有限值时,请求会在进入模型前被拒绝。这样可以把输入错误与模型故障分开,避免错误数据进入张量计算。

模型在应用生命周期开始时加载一次,请求处理中只读取参数,不修改权重。替换模型文件后必须重启当前进程,或额外实现受控的热更新机制;直接覆盖正在使用的文件并不能让内存模型自动变化。

示例监听 0.0.0.0 是为了便于容器或局域网访问。生产环境不应直接暴露开发服务器,应在反向代理或网关之后配置 HTTPS、鉴权、请求大小限制、并发控制、访问日志和健康检查。

验收检查

  • /health 能稳定返回 {"status":"ok"},并且模型加载失败时服务启动直接失败
  • 合法四维输入返回 200,概率列表长度为 3,且总和接近 1
  • 非法长度和非有限数值不会进入模型推理
  • 连续请求不会重复读取权重文件,也不会产生梯度
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

构建推理接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通