4. 模型加载与推理接口设计

在生产环境中，异常交易检测模型需要以稳定、高效的方式对外提供推理能力。本章聚焦于已训练模型的加载、统一预测接口的设计以及输入输出数据格式的规范化，确保模型能够无缝集成到微服务、批处理或实时流处理管道中。

4.1 模型加载策略

模型加载是推理服务的起点。根据部署场景（离线批处理 vs. 在线实时），加载策略有所不同。下表对比了三种常见加载方式：

以下代码展示了使用 joblib 实现启动时一次性加载的典型模式：

import joblib
import os

class FraudModelLoader:
    """异常交易检测模型加载器，支持本地文件与远程存储路径。"""

    def __init__(self, model_path: str, version: str = "v1"):
        self.model_path = model_path
        self.version = version
        self._model = None

    def load(self) -> None:
        """加载模型文件到内存。若文件不存在则抛出 FileNotFoundError。"""
        if not os.path.exists(self.model_path):
            raise FileNotFoundError(f"模型文件未找到: {self.model_path}")
        self._model = joblib.load(self.model_path)
        print(f"[{self.version}] 模型加载完成，路径: {self.model_path}")

    @property
    def model(self):
        if self._model is None:
            raise RuntimeError("模型尚未加载，请先调用 load() 方法。")
        return self._model

4.2 统一 predict() 接口设计

统一的 predict() 接口是模型推理的核心抽象。它屏蔽了底层模型类型（XGBoost、LightGBM、神经网络等）的差异，对外暴露一致的调用方式。接口设计应包含以下要素：

• 输入校验：检查字段完整性、数据类型与取值范围。
• 特征工程：执行与训练时一致的预处理（缺失值填充、标准化、编码等）。
• 模型推理：调用加载好的模型进行预测。
• 结果后处理：将模型原始输出（如概率、分数）转换为业务可读的标签与置信度。
• 异常处理：捕获推理过程中的异常，返回结构化的错误信息。

下面是一个标准化的 predict() 接口实现示例：

import pandas as pd
import numpy as np
from typing import Dict, List, Union

class FraudPredictor:
    """异常交易检测预测器，封装特征工程与模型推理。"""

    def __init__(self, model_loader: FraudModelLoader, feature_columns: List[str]):
        self.model_loader = model_loader
        self.feature_columns = feature_columns

    def predict(self, data: Union[Dict, List[Dict]]) -> Dict:
        """
        统一预测接口。

        参数:
            data: 单条交易字典或交易字典列表。

        返回:
            包含 'predictions'、'probabilities'、'errors' 的字典。
        """
        # 1. 输入标准化
        if isinstance(data, dict):
            data = [data]

        # 2. 转换为 DataFrame 并进行特征校验
        try:
            df = pd.DataFrame(data)
            missing_cols = set(self.feature_columns) - set(df.columns)
            if missing_cols:
                raise ValueError(f"缺少必要特征列: {missing_cols}")
            df = df[self.feature_columns]
        except Exception as e:
            return {"predictions": [], "probabilities": [], "errors": [str(e)]}

        # 3. 特征预处理（此处为简化示例，实际应包含标准化、编码等）
        df.fillna(0, inplace=True)

        # 4. 模型推理
        try:
            model = self.model_loader.model
            raw_probs = model.predict_proba(df)[:, 1]  # 取正类概率
            raw_preds = (raw_probs >= 0.5).astype(int)
        except Exception as e:
            return {"predictions": [], "probabilities": [], "errors": [f"推理失败: {str(e)}"]}

        # 5. 结果后处理
        predictions = [int(p) for p in raw_preds]
        probabilities = [round(float(p), 4) for p in raw_probs]

        return {
            "predictions": predictions,
            "probabilities": probabilities,
            "errors": []
        }

4.3 输入输出数据格式规范

为了确保接口的通用性与可维护性，必须对输入输出格式进行严格定义。推荐使用 JSON 作为序列化格式，并遵循以下规范：

以下是一个完整的请求与响应示例：

// 请求示例（单条交易）
{
  "transaction_id": "txn_20250321_001",
  "features": {
    "amount": 12500.00,
    "hour_of_day": 23,
    "is_weekend": 1,
    "merchant_category": "electronics",
    "distance_from_home_km": 450.5
  },
  "timestamp": "2025-03-21T23:15:30Z"
}

// 响应示例
{
  "transaction_id": "txn_20250321_001",
  "prediction": 1,
  "probability": 0.9234,
  "error": null
}

4.4 推理接口架构总览

下图展示了从请求到达、模型加载、特征处理到结果返回的完整推理链路：

4.5 接口版本管理与兼容性

随着业务发展，模型特征或输出格式可能发生变化。建议在接口路径或请求头中引入版本号，实现平滑过渡：

• URI 版本化：/api/v1/predict、/api/v2/predict
• 请求头版本化：Accept-Version: v2
• 模型版本与接口版本解耦：同一接口版本可支持多个模型版本，通过配置切换

版本兼容性检查清单：