📚 课程目录第4章模型序列化与保存

4、模型序列化与保存：使用 Pickle/Joblib 保存训练好的模型，模型文件结构说明

在信用评分模型的开发与部署链路中，训练完成的模型仅存在于内存中，一旦进程终止，所有参数与结构将丢失。模型序列化（Serialization）是将内存中的模型对象转换为可持久化存储的字节流的过程；反序列化（Deserialization）则是从字节流恢复模型对象的过程。本章将详细讲解使用 Pickle 与 Joblib 两种主流工具保存信用评分模型的方法，并剖析模型文件的标准结构。

4.1 序列化工具选型：Pickle vs Joblib

Python 生态中，pickle 是内置的序列化模块，而 joblib 是专门针对大数据对象（如 NumPy 数组、Scikit-learn 模型）优化的序列化库。对于信用评分模型，通常包含大规模的特征矩阵、树结构或线性权重，joblib 在 I/O 性能与压缩效率上更具优势。

对比维度	Pickle	Joblib
序列化协议	Python 内置协议（0-5）	基于 Pickle 的优化协议
大数据对象处理	逐字节序列化，内存占用高	自动分块处理，内存效率高
压缩支持	需手动包装 `gzip`	内置 `compress` 参数
加载速度	较慢（尤其大模型）	快 2-5 倍（利用内存映射）
跨版本兼容性	需指定 `protocol`	与 Pickle 协议版本一致
推荐场景	小模型、通用对象	信用评分模型、Pipeline 对象

工程建议：在信用评分 API 项目中，统一使用 joblib 进行模型保存与加载。它不仅性能更优，且对包含 StandardScaler、OneHotEncoder 等预处理步骤的 Pipeline 对象支持更稳定。

4.2 模型保存与加载标准流程

以下代码展示了使用 joblib 保存一个完整的信用评分 Pipeline（包含特征工程与评分卡模型）的标准操作：

import joblib
from sklearn.pipeline import Pipeline
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import LogisticRegression

# 构建信用评分 Pipeline
credit_pipeline = Pipeline([
    ('scaler', StandardScaler()),
    ('classifier', LogisticRegression(C=0.1, class_weight='balanced'))
])

# 假设 X_train, y_train 已准备好
# credit_pipeline.fit(X_train, y_train)

# 保存模型到文件
model_path = './models/credit_score_model_v1.pkl'
joblib.dump(credit_pipeline, model_path, compress=3)

# 加载模型
loaded_pipeline = joblib.load(model_path)

# 使用加载的模型进行预测
# predictions = loaded_pipeline.predict(X_new)

版本兼容性警告：使用 joblib 或 pickle 保存的模型文件与 Python 版本、Scikit-learn 版本强相关。在生产环境中，模型训练环境与推理环境的 Python 及依赖库版本必须保持一致，否则反序列化可能失败或产生不可预知的预测偏差。

4.3 模型文件结构说明

一个典型的信用评分模型文件（.pkl 或 .joblib）并非单一对象，而是包含多个组件的复合结构。下图展示了模型文件内部的逻辑层次：

4.4 模型文件元数据扩展

在生产级信用评分 API 中，仅保存模型参数是不够的。推荐在模型文件中附加元数据（Metadata），以便于版本追溯、特征校验与监控。以下是一种推荐的元数据扩展方案：

import joblib
import json
from datetime import datetime

# 模型对象
model = credit_pipeline

# 元数据字典
metadata = {
    'model_name': 'credit_score_v1',
    'version': '1.0.0',
    'training_date': datetime.now().isoformat(),
    'feature_names': ['age', 'income', 'loan_amount', 'credit_history_length'],
    'target_definition': '0=good, 1=bad',
    'performance_metrics': {
        'auc_roc': 0.82,
        'ks_statistic': 0.45
    },
    'framework_version': {
        'sklearn': '1.2.2',
        'python': '3.9.16'
    }
}

# 打包保存
model_package = {
    'metadata': metadata,
    'model': model
}

joblib.dump(model_package, './models/credit_score_v1.0.0.pkl', compress=3)

# 加载时分离元数据与模型
loaded_package = joblib.load('./models/credit_score_v1.0.0.pkl')
loaded_metadata = loaded_package['metadata']
loaded_model = loaded_package['model']

最佳实践：将元数据与模型对象打包在同一个文件中，可以避免额外的配置文件管理。在 API 启动时，先读取元数据校验版本与特征一致性，再加载模型进行推理，形成完整的自描述模型文件。

4.5 模型文件目录结构规范

在信用评分 API 项目中，建议采用以下目录结构管理多个版本的模型文件：

models/
├── credit_score_v1.0.0.pkl          # 初始版本
├── credit_score_v1.1.0.pkl          # 特征工程优化版本
├── credit_score_v2.0.0.pkl          # 算法升级版本
├── staging/
│   ├── credit_score_v2.1.0_beta.pkl # 预发布版本
│   └── credit_score_v2.1.0_rc.pkl   # 候选版本
└── archive/
    ├── credit_score_v0.9.0.pkl      # 历史版本归档
    └── credit_score_v1.0.0.pkl      # 已退役版本

目录/文件	用途	保留策略
`models/` 根目录	存放当前生产环境使用的模型文件	仅保留最近 2 个稳定版本
`staging/`	存放待测试、待评审的预发布模型	评审通过后移入根目录，失败则删除
`archive/`	存放历史版本，用于回滚与审计	按时间戳保留，至少保留 6 个月

安全提醒：模型文件可能包含训练数据的统计信息（如均值、分位数），在部分场景下存在数据泄露风险。切勿将模型文件上传到公开代码仓库或未授权的存储位置。建议对模型文件进行哈希校验（如 SHA256），并在加载时验证完整性。

4.6 序列化常见问题与避坑指南

版本不匹配：训练环境使用 Scikit-learn 1.2，推理环境使用 1.0，加载模型时可能抛出 AttributeError。解决方案：使用 Docker 容器固化环境，或在模型元数据中记录依赖版本。
大模型加载慢：包含大量树模型的集成方法（如 XGBoost、RandomForest）文件体积可达数百 MB。解决方案：使用 joblib 的 compress 参数，或采用 pickle 的 protocol=4 提升效率。
自定义类序列化失败：如果 Pipeline 中包含自定义 Transformer，需确保自定义类在加载环境中可导入。解决方案：将自定义类封装为独立模块，并在加载前导入。
文件损坏：磁盘故障或传输中断导致模型文件损坏。解决方案：保存时同时生成校验文件（如 .sha256），加载时校验。

通过本章的学习，你应该能够根据信用评分项目的实际需求，选择合适的序列化工具，构建结构清晰的模型文件，并建立规范的版本管理流程。这为后续的 API 发布与在线推理链路奠定了可靠的基础。