gappy401/quant-risk-mlops
GitHub: gappy401/quant-risk-mlops
开源MLOps平台，用于信用违约概率评分。
Stars: 0 | Forks: 0
# 量化风险 MLOps
一个开源、可移植的**MLOps平台**，用于消费者信用**违约概率（PD）**评分。模型经过训练、门控、注册，在实时API和批量作业后提供服务，监控漂移，通过版本化的管道实现可重复性，然后容器化并在Kubernetes上运行，实现自动扩展。
一个云无关的构建。计划一个Azure原生兄弟（Databricks、ADF、ADLS、Azure ML）。
## 从上到下如何工作
1. **数据合约**（`schema.py`）。一个版本化的Pandera模式在摄取时验证原始贷款数据，并关闭失败，因此坏数据在成为后来的无声错误预测之前就被拒绝在门外。
2. **摄取**（`data/load.py`，`data/generate.py`）。如果存在，则读取真实的Lending Club文件，否则生成一个与模式忠实的合成数据，并带有漂移旋钮进行测试。一切都在合约中通过验证。
3. **特征**（`features/transforms.py`）。一个无状态的函数将验证后的数据转换为模型准备好的特征。它被训练和提供方导入，因此两者不能偏离。
4. **训练**（`models/train.py`，`models/evaluate.py`）。训练一个scikit learn管道，在排名指标（AUC、Gini、KS）上评分，将一切记录到MLflow中，包括数据哈希和模式版本，只有当它通过AUC门控时才注册模型。
5. **实时服务**（`serving/api.py`）。一个FastAPI服务通过名称从注册表中加载模型，一次评分一个请求，由边缘的Pydantic合约保护。
6. **批量服务**（`models/predict.py`）。相同的模型按计划对整个群体进行评分，这是夜间预测模式。
7. **监控**（`monitoring/`）。PSI和KS漂移检测将实时数据与训练基线进行比较，对结果进行分层，并将警报扇出到Slack和Prometheus。
8. **可重复性**（`dvc.yaml`，`params.yaml`）。DVC将生成、训练和监控连接到一个管道，该管道只重新运行更改的内容。
9. **容器化**（`docker/`）。一个精简的镜像提供API服务，一个Compose堆栈在MLflow服务器旁边运行它，以便模型通过网络加载。
10. **Kubernetes**（`k8s/`）。API作为部署在服务后面运行，具有存活和就绪探测，以及一个自动扩展器，在负载下将其从2个扩展到10个Pod。
## 架构
```
raw loans (real CSV or synthetic)
| schema.py validates at ingest (fail closed)
v
labeled data -> build_features() -> model ready features
| (shared by train and serve)
+-----------------+-------------------+
v v v
TRAIN SERVE MONITOR
train.py api.py drift.py
MLflow + gate FastAPI PSI / KS -> Slack / Prometheus
| predict.py (batch) |
+-------- model registry --------------+
|
reproduced by DVC: generate -> train -> monitor
shipped by Docker, run on Kubernetes with autoscaling
```
## 快速入门
```
# 1. 隔离环境，然后安装包 + 开发工具
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
# 2. 测试
pytest
# 3. 训练（MLflow 注册 + 偏差基线，受控）
python -m quant_risk.models.train
mlflow ui --backend-store-uri sqlite:///mlflow.db # http://localhost:5000
# 4. 实时服务
uvicorn quant_risk.serving.api:app --port 8000 # http://localhost:8000/docs
# 5. 批量评分
python -m quant_risk.models.predict --n 20000
# 6. 偏差监控（强制警报）
python -m quant_risk.monitoring.run_monitor --drift 1.2
# 7. 可重复的管道
dvc repro
dvc metrics show
# 8. 容器化
docker build -t credit-pd-api -f docker/Dockerfile.api .
docker compose -f docker/docker-compose.yml up -d
# 9. Kubernetes
kubectl apply -f k8s/mlflow.yaml
kubectl apply -f k8s/api.yaml
kubectl apply -f k8s/hpa.yaml
```
将真实的Lending Club CSV文件放入`data/raw/`，一切从合成数据切换到真实数据，无需更改代码。
## 项目结构
```
quant-risk-mlops/
├── pyproject.toml installable package + tool config
├── requirements-serve.txt lean serving dependencies (for the image)
├── dvc.yaml / params.yaml reproducible pipeline + tracked knobs
├── conf/config.yaml runtime settings (seed, paths, MLflow)
├── src/quant_risk/
│ ├── schema.py the data contract
│ ├── config.py central configuration
│ ├── data/ generate.py, load.py
│ ├── features/transforms.py shared feature engineering
│ ├── models/ evaluate.py, train.py, predict.py
│ ├── serving/ schema.py, api.py
│ └── monitoring/ drift.py, alerts.py, run_monitor.py
├── tests/ 14 tests (contract, parity, metrics, api, drift)
├── docker/ Dockerfile.api, docker-compose.yml
├── k8s/ mlflow.yaml, api.yaml, hpa.yaml, loadgen.yaml
└── docs/ per technology deep dives
```
## 状态
| 层 | 状态 |
|---|---|
| 数据合约、配置、摄取 | 构建 |
| 共享特征、训练、注册、AUC门控 | 构建 |
| 测试套件（14个测试） | 构建 |
| 实时API + 批量评分 | 构建 |
| 漂移监控 + Slack / Prometheus警报 | 构建 |
| 可重复性管道（DVC） | 构建 |
| Docker镜像 + Compose堆栈 | 构建 |
| Kubernetes部署、服务、探测、自动扩展 | 构建 |
| CI、Spark / Kafka扩展、Airflow、S3、Azure原生兄弟 | 路线图 |
## 设计原则
1. 保护边界，而不是模型。合约在摄取时验证原始数据，并关闭失败。
2. 在确切的一个地方计算特征。一个共享的函数使训练和提供方偏斜成为不可能。
3. 模型是一个贬值的资产。监控是一个一等特性。
4. 可重复性是不可或缺的。种子、数据哈希、模式版本和DVC管道。
5. 将平台与有效负载分开。模型是可交换的，平台不是。
## 文档
每个技术的深入探讨都活生生地存在于`docs/`中。每一页都涵盖了该技术是什么，它做什么，命令和基本语法，它如何适应此项目以及它在哪里发挥作用，以及链接到官方文档。
1. Kubernetes：[docs/kubernetes.md](docs/kubernetes.md)
2. Docker：[docs/docker.md](docs/docker.md)
3. MLflow：[docs/mlflow.md](docs/mlflow.md)
4. DVC：docs/dvc.md（计划中）
5. 监控、PSI和KS：docs/monitoring.md（计划中）
计划中的跨切面笔记：为什么需要一个隔离的虚拟环境，如何端到端强制执行可重复性，如何故意使技术可交换（模型、数据源、编排器）以及为什么，以及通过`.gitignore`（数据、MLflow存储、本地工件）与提交（代码、管道定义、`dvc.lock`、指标）有意识地保留在版本控制之外的内容。
## 技术栈
Python、pandas、numpy、scipy。Pandera用于数据合约。scikit learn用于模型。MLflow用于跟踪和注册。FastAPI、Pydantic和uvicorn用于服务。PSI和KS，可选的Evidently用于漂移。Slack和Prometheus用于警报。DVC用于管道。Docker和Kubernetes用于打包和服务。pytest和ruff用于质量。
## 路线图
CI与GitHub Actions（ruff、pytest、推送到时的镜像构建）、PySpark奖牌ETL和Kafka流评分器以实现扩展、Airflow夜间批量DAG、S3原始数据存储，以及Azure原生兄弟项目。
标签：ADF, ADLS, Apex, AUC, AV绕过, Azure, Azure ML, Databricks, DVC, FastAPI, Gini, KS指标, MLflow, MLOps, NIDS, Pandera, Pydantic, Scikit-learn, Slack, 信用评分, 可重复性, 子域名突变, 安全可观测性, 实时API, 容器化, 批处理作业, 数据工程, 数据验证, 机器学习, 概率预测, 模型监控, 模型训练, 模型部署, 漂移检测, 版本控制, 特征工程, 自动扩展, 自定义请求头, 请求拦截, 逆向工具