bhupesh-debug/Bank-liquidity-Stress-Simulator

# 银行流动性压力模拟器与早期预警系统 [](https://python.org) [](https://mlflow.org) [](https://banks.data.fdic.gov) [](LICENSE) ## 解决的问题 中型银行的流动性人工监控依赖基于电子表格的比率分析，由分析师按季度审查。这存在以下问题：速度慢（每家机构60分钟以上）、滞后性（使用当前季度数据来标记当前季度问题）、以及分析师之间的一致性差。 本系统预测哪些银行**在未来6个月内（2个季度）**可能突破110%流动性覆盖率（LCR）早期预警阈值，从而在监管红线被突破前实现主动干预。 **回测的业务影响（基于2022–2023年保留集）：** - 提前6个月捕捉到**83%**的高风险银行（当LCR降至110%以下时） - 相比简单阈值规则，误报率降低**41%** - 通过预先按违约概率对机构排序，将分析师审查时间缩短约60% - SHAP解释识别出推动每家银行风险的资产负债表因素 ## 工作原理 ``` FDIC BankFind API (quarterly call reports) │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Feature Pipeline (src/features.py) │ │ │ │ ① LCR Proxy HQLA / Stressed Outflows (Basel III rates) │ │ ② Deposit Stability Insured %, foreign %, CD concentration │ │ ③ Trend Signals QoQ change, consecutive declines, 4Q avg │ │ ④ Stress Scenarios LCR under mild / moderate / severe shock │ │ ⑤ Peer Comparison Z-score vs. peer-group median │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ XGBoost Classifier (trained on 2010–2019, tested on 2022–23) │ │ Target: LCR < 110% in next 2 quarters? (binary) │ │ Class imbalance handled via scale_pos_weight (no resampling) │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Output Layer │ │ • Breach probability per institution │ │ • SHAP waterfall: top risk drivers per bank │ │ • Stress dashboard: slider-adjustable macro scenarios │ │ • FastAPI endpoint for single-institution queries │ │ • Automated risk report PDF (simulates senior mgmt deliverable│ └─────────────────────────────────────────────────────────────────┘ ``` ## 结果 | 模型 | AUC-ROC | 召回率（捕获违约） | 精确率 | 误报率 | |---|---|---|---|---| | 多数类基准 | 0.50 | 0% | — | 0% | | 基于规则（LCR < 115%） | 0.61 | 61% | 38% | 22% | | 逻辑回归 | 0.72 | 69% | 44% | 18% | | **XGBoost（最终）** | **0.84** | **83%** | **61%** | **13%** | **按全局重要性排序的前5个特征（平均|SHAP|值）：** 1. `consecutive_lcr_declines` — 趋势恶化比绝对水平更重要 2. `lcr_severe_stress` — 在2倍流出率下的压力LCR 3. `uninsured_deposit_exposure` — 未存款是最大的潜在流出 4. `wholesale_funding_ratio` — 短期批发资金波动性 5. `lcr_peer_zscore` — 低于同业水平放大了风险信号 ## 数据 **来源：** FDIC BankFind Suite API（公开，无需认证） - 端点：`https://banks.data.fdic.gov/api/financials` - 覆盖范围：约5,000家美国银行控股公司，按季度数据，2010–2023 - 字段：来自FFIEC 031/041报告呼叫报表的18个资产负债表项目 **数据范围：** 总资产≥ 1亿美元（社区银行门槛）的银行。 排除低于1亿美元的资产机构——LCR要求不适用于该门槛以下，且其资产负债表构成在结构上不同。 **隐私与伦理：** 所有数据均为公开的监管披露。不涉及个人/消费者数据。 不涉及GDPR/CCPA问题。FDIC服务条款允许研究与衍生使用。 **版本控制：** 原始CSV通过DVC跟踪（`data/raw/fdic_financials_*.csv.dvc`）。 通过检出已标记的数据版本即可复现任何实验。 ## 特征工程 特征分为5个基于巴塞尔III的类别。每个类别都有关于*为何*能预测LCR压力的文档化假设——而不仅仅是衡量什么。 ### 1 — 流动性构成 捕捉资产负债表结构：高质量流动性资产与总资产比率、贷款与存款比率、高质量流动性资产第一层纯度。 **假设：** 高贷款集中度且低HQLA比率的银行缺乏缓冲以吸收流出，具有结构性脆弱性，与当前状况无关。 ### 2 — 存款组合稳定性 受保存款比率、外国存款集中度、未存款暴露、存单集中度。 **假设：** 存款组合决定了在巴塞尔III压力假设下适用的流出率。 一家40%为外国存款的银行，其建模流出率在结构上高于一家90%为零售存款的银行。 ### 3 — 趋势与动量 季度LCR变化、连续下降次数、4季度滚动平均、存款增长率。 **假设：** LCR趋势下降是领先指标，独立于绝对水平。 一家LCR为130%但每季度下降8个百分点的银行，比一家稳定在115%的银行风险更高。 ### 4 — 压力情景敏感度 在温和（1.3×）、中等（1.6×）和严重（2.0×）流出乘数下重新计算LCR。 **假设：** 压力LCR揭示了基准LCR未发现的脆弱性。 一家基准LCR看似舒适但严重压力LCR迅速恶化的银行，是监管关注对象。 ### 5 — 同业相对定位 与同业组中位数的Z分数、同业LCR百分位、批发资金与同业中位数的比率。 **假设：** 低于同业中位数的LCR表明系统性相对风险。监管机构按同业组评估银行——即使绝对LCR超过100%，在规模层级中处于第10百分位的银行也值得审查。 完整的实现（包括每个函数的文档字符串、巴塞尔III引用和流出率来源）请参见 `src/features.py`，涵盖12 CFR第249部分 / 联邦储备LCR规则。 ## 模型开发 ### 为何选择XGBoost 在选定XGBoost之前，评估了三类模型： | 模型 | AUC-ROC | 可解释性 | 训练时间 | 被拒绝/选用的原因 | |---|---|---|---|---| | 逻辑回归 | 0.72 | 高（系数） | 快 | 无法捕捉非线性特征交互 | | 随机森林 | 0.81 | 中等（SHAP可用） | 中等 | 略逊于XGBoost，且调参更复杂 | | 神经网络（MLP） | 0.80 | 低（SHAP近似） | 慢 | 无可解释性优势；5,000行样本量较小 | | **XGBoost** | **0.84** | **高（TreeSHAP精确）** | **快** | **最佳召回率 + 精确的SHAP解释** | XGBoost也是银行和监管机构进行表格化金融风险建模的行业标准；选择它传递了领域认知。 ### 时间分割的合理性 ``` 2010 ─────────────── 2019 │ 2020 ──── 2021 │ 2022 ─── 2023 TRAIN VALIDATION TEST (pre-COVID baseline) (COVID stress) (post-COVID) ``` 验证集涵盖COVID（2020–2021），因为这是调节压力敏感度的区间。 测试集涵盖后COVID（2022–2023）——不同的宏观环境——以验证泛化能力。 随机分割会使2022年的模式渗入训练集，使测试指标虚高约8个AUC点。 ### 类别不平衡处理 LCR违约事件罕见（约占观测值的8%）。我们未使用SMOTE或欠采样（这会扰乱时间顺序），而是使用XGBoost的 `scale_pos_weight` 参数。 这相当于成本敏感学习——它告诉模型假阴性的代价高于假阳性，符合流动性监控工具的监管风险偏好。 ## 项目结构 ``` lcr-stress-system/ ├── src/ │ ├── ingest.py # FDIC BankFind API data pull │ ├── features.py # Feature pipeline (5 categories, 31 features) │ ├── train.py # Training: temporal split → baselines → XGBoost → MLflow │ ├── predict.py # Inference: single institution or batch │ └── api.py # FastAPI endpoint ├── app/ │ └── streamlit_app.py # Dashboard: risk rankings + scenario sliders + SHAP ├── data/ │ ├── raw/ # FDIC CSVs (tracked by DVC) │ └── features/ # Processed feature matrices (tracked by DVC) ├── models/ # Serialized models (MLflow artifacts) ├── notebooks/ │ └── 01_eda.ipynb # Exploratory analysis of FDIC data ├── tests/ │ ├── test_features.py # Unit tests: feature computation │ ├── test_split.py # Asserts temporal split never leaks future data │ └── test_api.py # Integration tests for FastAPI endpoint ├── configs/ │ └── config.yaml # All parameters (no hardcoded values in code) ├── docs/ │ ├── model_card.md # Intended use, limitations, regulatory context │ └── regulatory_framing.md # How project maps to Basel III / Fed LCR Rule ├── Dockerfile ├── requirements.txt ├── dvc.yaml # DVC pipeline definition └── README.md ``` ## 快速开始 **前提条件：** Python 3.10+，Docker（可选用于部署） ``` # 克隆并安装 git clone https://github.com/bhupeshdimri/lcr-stress-system.git cd lcr-stress-system pip install -r requirements.txt # 拉取数据（FDIC API — 免费，无需认证） python src/ingest.py --start 20100101 --end 20231231 --min-assets 100000 # 构建特征 python src/features.py # 训练模型（跟踪至 MLflow） python src/train.py # 启动仪表板 streamlit run app/streamlit_app.py # 或：查询 API uvicorn src.api:app --reload # → POST http://localhost:8000/predict 附带银行 cert_id + 季度 ``` **运行测试：** ``` pytest tests/ -v ``` **Docker：** ``` docker build -t lcr-stress-system . docker run -p 8501:8501 lcr-stress-system ``` ## API `POST /predict` ``` { "cert_id": 12345, "report_date": "2023-09-30", "scenario": "moderate" } ``` 响应： ``` { "cert_id": 12345, "bank_name": "Example Community Bank", "breach_probability": 0.71, "risk_tier": "HIGH", "lcr_proxy": 108.4, "lcr_stressed_moderate": 89.2, "top_risk_drivers": [ {"feature": "consecutive_lcr_declines", "shap_value": 0.18, "direction": "increases_risk"}, {"feature": "uninsured_deposit_exposure", "shap_value": 0.14, "direction": "increases_risk"}, {"feature": "insured_deposit_ratio", "shap_value": -0.09, "direction": "reduces_risk"} ], "recommendation": "Escalate for analyst review. LCR trend declining 3 consecutive quarters." } ``` 完整的API文档在 `/docs`（Swagger UI）自动生成。 ## 监管背景 本项目建模的巴塞尔III流动性覆盖率（LCR）定义如下： - **BCBS 238**（巴塞尔III：流动性覆盖率与流动性风险监控工具） - **12 CFR Part 249**（联邦储备LCR规则——美国实施） - **联邦储备SR 10-6（健全流动性风险管理指引） 110%早期预警阈值反映了常见的监管实践——将银行标记在监管红线之上10个百分点，以留出干预提前时间。 详见 `docs/regulatory_framing.md`，了解模型特征与具体巴塞尔III要求之间的完整映射。 ## 局限性与未来工作 **当前局限性：** - LCR代理使用行业平均流出率，而非银行特定的监管LCR（不公开） - 季度FDIC数据限制了提前期——季度内的流动性恶化无法捕捉 - 同业分组使用资产规模区间；更精确的分组可使用联邦储备LISCC监管计划分类 **未来计划：** - 使用每周H.8联邦储备数据（商业银行资产）进行季度内早期预警 - NSFR代理特征（更长周期的结构性流动性，补充LCR） - 存款beta建模以根据利率环境调整流出率 - 按美联储LCR监管模板生成监管报告 ## 作者 **Bhupesh Chandra Dimri** | 布鲁克林，纽约 | 通过2029年12月的F-1 STEM OPT 佩斯大学会计分析与数据技术硕士（2025） 拥有10年在美国银行运营、流动性风险与财务分析经验，曾任职于Genpact [LinkedIn](https://linkedin.com/in/bhupeshdimri) | bhupeshchandra.dimri@pace.edu

标签：2022, 2023, 60%效率提升, Apex, ASM汇编, FDIC, Kubernetes, LCR, MLflow, Python, SHAP解释, Streamlit, 公开数据, 分析师效率, 压力测试, 回测, 季度报告, 宏观情景, 异常检测, 数据仪表盘, 无后门, 早期预警系统, 时间序列, 机器学习, 流动性覆盖率, 特征工程, 电子表格替代, 监管合规, 自动化告警, 访问控制, 请求拦截, 逆向工具, 银行数据, 银行监管, 银行风险识别, 预测模型