ballinprestige/ml-engineering-portfolio
GitHub: ballinprestige/ml-engineering-portfolio
一组聚焦生产环境 ML 工程实践的可复现演示，解决模型从离线到线上部署过程中的验证泄漏、概率失准、特征冗余和数据漂移等核心问题。
Stars: 0 | Forks: 0
# ML 工程作品集 — Kyle Reynolds
面向生产的机器学习：探讨那些决定一个
在离线状态下表现良好的模型，是否能在实际线上环境中经受住考验的技术。每个演示都很小巧、
独立、确定性运行、基于合成数据，并能复现一张图表 —
并且每个演示的核心结果都通过 CI 中的测试进行了强制验证。
**重点关注领域：** 防泄漏验证 · 概率校准 · SHAP 驱动的
特征选择 · 漂移监控 · 可复现的 ML pipeline。
## 目录
- [生产 pipeline（架构）](#production-pipeline-architecture)
- [1 · 防泄漏时间序列验证](#1--leakage-safe-time-series-validation)
- [2 · 概率校准](#2--probability-calibration)
- [3 · SHAP 驱动的特征选择](#3--shap-driven-feature-selection)
- [4 · 特征漂移检测](#4--feature-drift-detection)
- [Notebook 演示](#notebook-walkthrough)
- [运行指南](#run-it)
## 生产 pipeline（架构）
演示背后的模式 — 各个部分如何在真实的、持续
重训练的系统中组合在一起：
```
flowchart LR
A["Real-time data sources
APIs and feeds"] --> B["Event-driven
feature engineering"] B --> C[("Parquet feature store
PostgreSQL")] C --> D["Daily training
gradient-boosted ensemble"] D --> E["Probability
calibration"] E --> F["Walk-forward backtest
and leakage audit"] F --> G{"Promotion gate
schema / shadow / rollback"} G --> H["Live serving"] H --> I["Drift and
data-health monitoring"] I --> B ``` ## 1 · 防泄漏时间序列验证 随机的 K-fold 交叉验证会在时间序列数据上悄然泄漏未来信息：打乱操作会将各个时期的样本放入训练集中，导致模型 在它已经见过的条件下进行评分。Walk-forward 验证始终 基于过去进行训练，并在未来数据上进行测试 — 这与模型实际部署的方式完全一致。 在存在机制转换的数据上（信号随时间从一个特征转移到另一个特征）， 随机 K-fold 报告了更高、过于乐观的分数： | 验证方案 | ROC AUC | |---|---| | 随机 K-fold（打乱） | **0.814** | | Walk-forward（时间感知） | **0.788** | | **泄漏导致的乐观偏差** | **+0.026** |  → [`src/walk_forward_validation.py`](src/walk_forward_validation.py) ## 2 · 概率校准 一个模型可能排序能力很好，但输出的概率却不可信 — 当它输出 0.9 时，实际正确的概率可能只有 70%。在留出集上进行等温校准 可以在不改变排序（AUC 不变）的情况下修复概率*尺度*， 从而改善 Brier 分数： | 指标 | 未校准 | 等温校准 | |---|---|---| | Brier 分数（越低越好） | 0.0697 | **0.0625** | | ROC AUC | 0.962 | 0.962 |  → [`src/probability_calibration.py`](src/probability_calibration.py) ## 3 · SHAP 驱动的特征选择 高维模型包含冗余和噪声特征，这些特征会增加方差 却不提供信号。根据平均绝对 SHAP 值对特征进行排序，并仅保留 前 k 个特征，可以在将模型缩小 **4 倍** 的同时保持性能： | 保留特征数 | ROC AUC | |---|---| | 前 8 个 | 0.962 | | 前 10 个 | 0.976 | | **全部 40 个** | 0.975 |   → [`src/shap_feature_selection.py`](src/shap_feature_selection.py) ## 4 · 特征漂移检测 当线上数据分布相对于 训练数据发生漂移时，部署的模型会默默退化。人口稳定性指数（PSI）和 Kolmogorov–Smirnov 检验可以标记出 *哪些*特征发生了偏移 — 这里均值偏移和尺度变化触发了 警报阈值，而稳定的特征则保持在零附近： | 特征 | PSI | 状态 | |---|---|---| | feature_0（均值偏移） | 1.26 | **警报** | | feature_2（尺度变化） | 0.37 | **警报** | | feature_4（中度偏移） | 0.24 | 观察 | | 稳定的特征 | < 0.01 | 正常 |  → [`src/drift_detection.py`](src/drift_detection.py) ## Notebook 演示 包含所有四个演示和内联结果的叙述版本： [`notebooks/portfolio_walkthrough.ipynb`](notebooks/portfolio_walkthrough.ipynb) ## 运行指南 ``` pip install -r requirements.txt python run_all.py # run all four demos, regenerate every figure # 开发 pip install -r requirements-dev.txt pytest -q # each demo's headline result is asserted here ruff check src tests ``` 结果是确定性的（固定随机种子）；CI 会在每次 推送时运行测试和所有演示。 ## 关于 我是一名自学的机器学习工程师，设计并运营着 一套端到端的生产级 ML 系统 — 包括实时数据摄取、大规模特征 工程、GPU 加速的梯度提升集成、校准、 walk-forward 回测，以及带有监控和 回滚机制的自动化每日重训练。这个仓库将这些核心方法提炼为小巧、可复现的 示例。 **技术栈：** Python · scikit-learn · XGBoost · SHAP · SciPy · pandas · NumPy · matplotlib 📫 kyleandgeorgi@gmail.com
APIs and feeds"] --> B["Event-driven
feature engineering"] B --> C[("Parquet feature store
PostgreSQL")] C --> D["Daily training
gradient-boosted ensemble"] D --> E["Probability
calibration"] E --> F["Walk-forward backtest
and leakage audit"] F --> G{"Promotion gate
schema / shadow / rollback"} G --> H["Live serving"] H --> I["Drift and
data-health monitoring"] I --> B ``` ## 1 · 防泄漏时间序列验证 随机的 K-fold 交叉验证会在时间序列数据上悄然泄漏未来信息：打乱操作会将各个时期的样本放入训练集中，导致模型 在它已经见过的条件下进行评分。Walk-forward 验证始终 基于过去进行训练，并在未来数据上进行测试 — 这与模型实际部署的方式完全一致。 在存在机制转换的数据上（信号随时间从一个特征转移到另一个特征）， 随机 K-fold 报告了更高、过于乐观的分数： | 验证方案 | ROC AUC | |---|---| | 随机 K-fold（打乱） | **0.814** | | Walk-forward（时间感知） | **0.788** | | **泄漏导致的乐观偏差** | **+0.026** |  → [`src/walk_forward_validation.py`](src/walk_forward_validation.py) ## 2 · 概率校准 一个模型可能排序能力很好，但输出的概率却不可信 — 当它输出 0.9 时，实际正确的概率可能只有 70%。在留出集上进行等温校准 可以在不改变排序（AUC 不变）的情况下修复概率*尺度*， 从而改善 Brier 分数： | 指标 | 未校准 | 等温校准 | |---|---|---| | Brier 分数（越低越好） | 0.0697 | **0.0625** | | ROC AUC | 0.962 | 0.962 |  → [`src/probability_calibration.py`](src/probability_calibration.py) ## 3 · SHAP 驱动的特征选择 高维模型包含冗余和噪声特征，这些特征会增加方差 却不提供信号。根据平均绝对 SHAP 值对特征进行排序，并仅保留 前 k 个特征，可以在将模型缩小 **4 倍** 的同时保持性能： | 保留特征数 | ROC AUC | |---|---| | 前 8 个 | 0.962 | | 前 10 个 | 0.976 | | **全部 40 个** | 0.975 |   → [`src/shap_feature_selection.py`](src/shap_feature_selection.py) ## 4 · 特征漂移检测 当线上数据分布相对于 训练数据发生漂移时，部署的模型会默默退化。人口稳定性指数（PSI）和 Kolmogorov–Smirnov 检验可以标记出 *哪些*特征发生了偏移 — 这里均值偏移和尺度变化触发了 警报阈值，而稳定的特征则保持在零附近： | 特征 | PSI | 状态 | |---|---|---| | feature_0（均值偏移） | 1.26 | **警报** | | feature_2（尺度变化） | 0.37 | **警报** | | feature_4（中度偏移） | 0.24 | 观察 | | 稳定的特征 | < 0.01 | 正常 |  → [`src/drift_detection.py`](src/drift_detection.py) ## Notebook 演示 包含所有四个演示和内联结果的叙述版本： [`notebooks/portfolio_walkthrough.ipynb`](notebooks/portfolio_walkthrough.ipynb) ## 运行指南 ``` pip install -r requirements.txt python run_all.py # run all four demos, regenerate every figure # 开发 pip install -r requirements-dev.txt pytest -q # each demo's headline result is asserted here ruff check src tests ``` 结果是确定性的（固定随机种子）；CI 会在每次 推送时运行测试和所有演示。 ## 关于 我是一名自学的机器学习工程师，设计并运营着 一套端到端的生产级 ML 系统 — 包括实时数据摄取、大规模特征 工程、GPU 加速的梯度提升集成、校准、 walk-forward 回测，以及带有监控和 回滚机制的自动化每日重训练。这个仓库将这些核心方法提炼为小巧、可复现的 示例。 **技术栈：** Python · scikit-learn · XGBoost · SHAP · SciPy · pandas · NumPy · matplotlib 📫 kyleandgeorgi@gmail.com
标签：Apex, MLOps, 数据漂移检测, 机器学习, 模型评估, 特征工程, 逆向工具