SuperModelingFactory

风控建模工厂 —— 一套面向信用评分卡开发与模型管理的完整 Python 工具链。

📖 在线文档 · 安装、快速上手、API 参考、用户指南一应俱全。

安装

pip install supermodelingfactory

macOS 用户额外需要安装 OpenMP 运行时（lightgbm 依赖）：

brew install libomp

支持的环境：Python 3.10 / 3.11 / 3.12 / 3.13，平台 macOS arm64 / Linux x86_64 / Windows x86_64。

详见 INSTALL.md。

许可证

本项目采用 Business Source License 1.1，Change Date 为 2030-06-24。之前：

✅ 允许：个人学习、学术研究、内部评估、原型、教学
❌ 不允许：任何生产 / 商业 / 营收性使用

2030-06-24 后自动转为 Apache 2.0。商业授权请联系作者。

项目现在以源码形式打包和分发；wheel 与 sdist 均包含 Python 源码，不再通过 Cython 隐藏核心模块实现。

项目概述

SuperModelingFactory 整合了信贷风控建模全流程所需的三大能力：

子项目	功能定位	核心能力
Modeling_Tool	建模引擎	数据分箱、WOE 编码、特征分析、模型训练与评估、样本管理
ExcelMaster	报告引擎	程序化 Excel 工作簿生成，支持图表、条件格式、光标流式写入
Report	报告模板	模型性能报告、WOE 图批量导出、多模型对比报告

项目结构

SuperModelingFactory/
├── Modeling_Tool/          # 核心建模工具包
│   ├── Core/               #   基础设施：分箱、ODPS、工具函数、加密
│   ├── WOE/                #   WOE 编码：分箱、变换、映射、可视化
│   ├── Feature/            #   特征分析：分布偏移、PSI、相关性过滤
│   ├── Model/              #   模型训练：LR、LightGBM、XGBoost、变量选择
│   ├── Eval/               #   模型评估：Gains 表、ROC/KS、性能汇总
│   ├── Sample/             #   样本管理：切分、分层、拒绝推断、分布适配
│   ├── Explainability/     #   模型解释：SHAP、LIME、PDP、ICE、ALE、Owen
│   ├── Pipeline/           #   一键流水线：特征验收、信用建模、拒绝推断等
│   └── UAT/                #   线上线下分数一致性校验
├── ExcelMaster/            # Excel 报告引擎
│   ├── ExcelFormatTool.py  #   格式定义（50+ 预设单元格格式）
│   ├── ExcelMaster.py      #   核心引擎（光标流式写入、图表、条件格式）
│   ├── Template.py         #   分析报告模板（PVA、Bivar、GridSearch 等）
│   └── Utility.py          #   工具函数（颜色、路径、PSI 报表处理等）
└── Report/                 # 模型评估报告模板
    └── Report_Tool.py      #   性能报告、WOE 绘图、多模型对比

安装

依赖

# 核心依赖
pip install pandas numpy scipy scikit-learn

# 建模引擎
pip install lightgbm xgboost joblib

# Excel 报告
pip install xlsxwriter openpyxl Pillow matplotlib seaborn

# 可选
pip install pyodps          # 阿里云 MaxCompute 连接
pip install imbalanced-learn # SMOTE 采样
pip install tqdm             # 进度条

使用

git clone <repo-url>
cd SuperModelingFactory
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

快速开始

典型风控建模流程

from Modeling_Tool import (
    # 分箱
    Binning, super_binning,
    # WOE 编码
    WOE_Master,
    # 特征分析
    VarExtractionInsights, CorrelationFilter, PSICalculator,
    # 模型训练
    GradientBoostingModel, LRMaster,
    # 模型评估
    GainsTableCalculator, PerformanceEvaluator,
    # 样本管理
    SampleSplitter, RejectInferrer
)

# 1. 样本切分
splitter = SampleSplitter(test_size=0.3, random_state=42, stratify=True)
train_df, test_df = splitter.split_df(data, target='is_bad')

# 2. WOE 分箱与编码
woe_master = WOE_Master(train_data=train_df, varlist=feature_cols, dep='is_bad')
woe_master.fit(nbins=10, equal_freq=True)
train_woe = woe_master.transform(train_df)
test_woe = woe_master.transform(test_df)

# 3. 特征筛选
psi_calc = PSICalculator(buckets=10)
psi_result = psi_calc.calculate(expected_df=train_df, current_data=test_df, varlist=feature_cols)

corr_filter = CorrelationFilter(data=train_woe, dep='is_bad')
keep_vars = corr_filter.remove_highly_correlated(feature_cols)

# 4. 模型训练
model = GradientBoostingModel('lgb', params={'n_estimators': 100, 'learning_rate': 0.1})
model.fit(train_woe[keep_vars], train_woe['is_bad'], test_woe[keep_vars], test_woe['is_bad'])

# 5. 模型评估
evaluator = PerformanceEvaluator(tgt_name='is_bad', model=model.model, feature_cols=keep_vars)
evaluator.add_dataset('train', train_woe).add_dataset('test', test_woe)
perf_result = evaluator.evaluate()

使用 ExcelMaster 生成报告

from ExcelMaster.ExcelMaster import ExcelMaster

em = ExcelMaster('model_report.xlsx')
ws = em.add_worksheet('Performance')

# 流式写入 DataFrame
em.write_dataframe(ws, perf_result, title='模型性能汇总', titleformat='BLUE_H2')
em.insert_image(ws, 'roc_curve.png', figScale=(600, 400))

em.close_workbook()

架构设计

依赖方向

                    ┌─────────┐
                    │  Core   │  (基础设施，无跨包依赖)
                    └────┬────┘
           ┌─────────┬───┼───────┬─────────┐
           ▼         ▼   ▼       ▼         ▼
         WOE      Model  Eval  Feature   Sample
           │         │              │        │
           └─────────┴──────────────┴────────
                (均单向依赖 Core，模块间延迟导入)

Core 是所有子包的基础，不依赖任何其他子包
其他子包之间通过延迟导入（函数体内 import）避免循环依赖
顶层 Modeling_Tool/__init__.py 提供精选的统一 API

命名规范

所有公开 API 通过 __init__.py 导出，使用方只需 from Modeling_Tool import ...
类名采用 PascalCase，函数名采用 snake_case
以 _ 开头的函数/方法为内部实现，不对外暴露

持续集成

本仓库的 GitHub Actions(.github/workflows/tests.yml)会在 push 到 main 与 PR 上自动跑 pytest,矩阵为:

Python:3.11、3.12
依赖矩阵:
- legacy — numpy<2 + scipy<1.13 + lightgbm<4
- modern — numpy>=2 + scipy>=1.13 + lightgbm>=4
共同约束:pandas>=2.0,<2.3(等 issue #2 修复后放宽)

测试用例托管在独立仓库 SuperModelingFactory_pytest(私有),workflow 通过 secrets.PYTEST_REPO_TOKEN 跨仓 clone。

配置 PAT(只需做一次)

进入 GitHub Settings · Tokens (classic) 生成新 token,scope 勾选 repo(只读访问私有仓库即可)
进入本仓库 Settings → Secrets and variables → Actions → New repository secret
Name: PYTEST_REPO_TOKEN,Value: 粘贴 token

如改用 Fine-grained PAT,需将其授权访问 SuperModelingFactory_pytest 仓库的 Contents: Read 权限。

版本

Version: 0.8.2
Author: Jingkai Sun

许可证

本项目采用 Business Source License 1.1（Change Date 2030-06-24）。详见文首许可证一节与 LICENSE 全文。

Metadata

Release files for SuperModelingFactory 0.8.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for SuperModelingFactory 0.8.2
File	Size	Uploaded
supermodelingfactory-0.8.2.tar.gz	17.0 MB	Sep 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for SuperModelingFactory 0.8.2
File	Interpreter	ABI	Platform	Reset
supermodelingfactory-0.8.2-py3-none-any.whl 17.1 MB Sep 18, 2026	Python 3	none	any	Details

Total release size: 34.0 MB

Release files / supermodelingfactory-0.8.2.tar.gz

Download URL	supermodelingfactory-0.8.2.tar.gz
Size	17.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`9270cc4ec47526aec8efbf7bb688ff43a4b73baf2458239bbbbc8856ba7367e8`
BLAKE2b-256 checksum How to use checksums	`affe268168d3d1e0745e9941596fb405b9d781feb8a6914c149eba6331fe5bf4`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Kyle-J-Sun/SuperModelingFactory
Publishing commit: github.com/Kyle-J-Sun/SuperModelingFactory/tree/7f159fdbc2e2f8a04ff1fb3d77c15df761546d38

Workflow

Publishing configuration: github.com/Kyle-J-Sun/SuperModelingFactory/blob/7f159fdbc2e2f8a04ff1fb3d77c15df761546d38/.github/workflows/build.yml
Publishing logs: github.com/Kyle-J-Sun/SuperModelingFactory/actions/runs/35310492333/attempts/1

Artifact

Subject: supermodelingfactory-0.8.2.tar.gz
SHA-256 checksum: 9270cc4ec47526aec8efbf7bb688ff43a4b73baf2458239bbbbc8856ba7367e8 Verifying attestations

Release files / supermodelingfactory-0.8.2-py3-none-any.whl

Download URL	supermodelingfactory-0.8.2-py3-none-any.whl
Size	17.1 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`80ce19261593e7d69dcfd7b5bd044831d70ce0b93526d95fa6ff85ab2b38f0f4`
BLAKE2b-256 checksum How to use checksums	`0596ba4dddd45846abb2496931aee70d728dc644bba6f5081855e86af6f1d631`
Upload date	Sep 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Kyle-J-Sun/SuperModelingFactory
Publishing commit: github.com/Kyle-J-Sun/SuperModelingFactory/tree/7f159fdbc2e2f8a04ff1fb3d77c15df761546d38

Workflow

Publishing configuration: github.com/Kyle-J-Sun/SuperModelingFactory/blob/7f159fdbc2e2f8a04ff1fb3d77c15df761546d38/.github/workflows/build.yml
Publishing logs: github.com/Kyle-J-Sun/SuperModelingFactory/actions/runs/35310492333/attempts/1

Artifact

Subject: supermodelingfactory-0.8.2-py3-none-any.whl
SHA-256 checksum: 80ce19261593e7d69dcfd7b5bd044831d70ce0b93526d95fa6ff85ab2b38f0f4 Verifying attestations