Skip to main content
Glama
agent-risk-ai

agent-risk-ai

by faanogueira

🏦 人工智能风险代理(Agent Risk AI)— ML + MCP 服务器

Python XGBoost scikit--learn Optuna SHAP MCP Tests License

人工智能风险代理:您通过 MCP 的自主信用情报和风险分析师。 一个信用卡违约预测模型,经过严格的 方法论训练(分层交叉验证、Optuna 贝叶斯调参、优化阈值、SHAP 可解释性), 并作为 MCP 服务器 暴露——可直接通过 Claude Desktop/Code 和 AI 代理以自然语言查询。


📌 为什么这个项目不同于“只训练一个模型”

大多数作品集项目止步于训练模型并展示带有指标的 .ipynb。 本项目更进一步:模型被封装在一个 MCP 服务器(模型上下文协议)中,提供 6 个业务工具, 这意味着任何兼容的 LLM 主机(Claude Desktop、Claude Code)都可以用自然语言查询模型, 无需编写代码:

🗣️ “这个客户的违约风险如何:年龄 46,收入 R$107,934,信用评分 544,之前有 2 次违约?” 🤖 → 调用 predict_default → 返回概率、类别和 SHAP 解释。

这正是风险/数据团队中正在出现的模式——希望将生产模型“融入对话”,而不是放在静态仪表板后面。


Related MCP server: Credit Risk Copilot

🗂️ 业务问题

45,528 名信用卡客户的数据集,包含人口统计、收入和信用行为变量。目标:credit_card_default(二分类), 真实不平衡率为 8.1% 的违约——这是典型的信用风险场景,其中朴素准确率是一个误导性指标。

训练行数

45,528

违约率

8.12%(不平衡)

原始变量

17(+ customer_id、name)

特征工程后变量

30


🏗️ 系统如何工作(简单架构)

该项目将原始信用数据转化为可操作、可审计的决策,供 AI 代理通过 4 个集成阶段 使用:

flowchart LR
    A["📁 1. Dados Brutos<br/><b>train.csv / test.csv</b>"] --> B["🧹 2. Limpeza & Features<br/><b>DTI, Limite, Flags</b>"]
    B --> C["🤖 3. Cérebro Preditivo<br/><b>XGBoost + Optuna + SHAP</b>"]
    C --> D["🔌 4. Servidor MCP<br/><b>6 Ferramentas de Negócio</b>"]
    D --> E["💬 5. Agente de IA<br/><b>Claude / Cursor / LLMs</b>"]

4 步流程:

  1. 📁 1. 处理与金融智能(data_processing.py / feature_engineering.py)

    • 移除敏感数据(PII)并处理数据集中的异常(如退休人员哨兵值)。

    • 创建真实金融指标:债务收入比(DTI)、信用额度利用率 和 人均收入。

  2. 🤖 2. 机器学习流水线(pipeline.py / train.py)

    • 以密封方式(无数据泄漏)执行转换(缺失值填充、独热编码和缩放)。

    • 通过 Optuna(25 次试验) 在 5 折交叉验证中训练和调优 XGBoost,校准最优决策阈值($F_1 = 0.875$)。

  3. 🧠 3. 可解释性与审计(inference.py / evaluate.py)

    • 持久化获胜模型和 SHAP TreeExplainer,以实时分解哪些变量增加或降低每个客户的风险。

  4. 🔌 4. MCP 代理层(mcp_server/server.py)

    • 暴露 6 个现成工具,使任何 AI 助手或代理(Claude Desktop、Claude Code 等)能够用自然语言查询模型、模拟场景和评估整个投资组合。


🔬 领域驱动的特征工程

而不是“把所有东西都扔给 XGBoost”,每个派生特征都有明确的信用风险理由:

特征

业务逻辑

debt_to_income_ratio(DTI)

年收入中有多少用于偿还债务——承保的经典支柱

credit_limit_to_income_ratio

相对于还款能力授予的杠杆

credit_utilization_frac × prev_defaults

交互:对于已有违约记录的人,高额度使用率影响更大

income_per_family_member

人均可用收入,而非仅名义收入

employment_tenure_ratio

相对于年龄的就业稳定性

risk_flags_sum

已观察到的风险标志总和(先前违约、近期违约、使用率 > 80%)

is_retired_or_unemployed

对 no_of_days_employed 中发现的哨兵值(约 365,243 天)的显式标志,该值实际上标记退休/失业人员——将其视为数字字面量会扭曲模型


🧪 方法论与统计严谨性

  • 仅在训练集上学习的 Winsorization(99.5 百分位)并重新应用于测试/留出集——无数据泄漏。

  • 单一 sklearn 流水线(ColumnTransformer + 模型)——缺失值填充和编码在交叉验证的每一折中重新计算,而不是在整个数据集上只计算一次(常见错误会人为夸大指标)。

  • 选择指标:PR-AUC(平均精度),而非 ROC-AUC 或准确率——对于 8% 的正类发生率,这是正确的选择。

  • 15% 的留出集在 Optuna 调参期间从未见过——以下最终指标是真实泛化,而非对搜索过程的过拟合。

  • 决策阈值重新校准,在留出集的精确率-召回率曲线上最大化 F1(0.875),而不是盲目使用 0.5——当正类稀有时至关重要。

  • 通过 SHAP TreeExplainer 进行可解释性——MCP 服务器的每个预测都可以逐因子审计(与信用监管合规相关)。


📊 结果与性能指标

以下所有指标均在**留出集(6,830 名客户)**上计算,该集合在 Optuna 超参数搜索期间完全隔离:

1. 模型比较(5 折分层交叉验证)

模型

PR-AUC(5 折 CV)

相对基线的提升

逻辑回归(平衡线性基线)

0.9454

—

随机森林(400 个估计器,平衡子采样)

0.9484

+0.30%

XGBoost + Optuna(25 次贝叶斯 TPE 试验)

0.9546

+0.92%


2. 留出集性能指标(冠军模型)

统计与业务指标

值

实际解释

ROC-AUC

0.9960

几乎完美的全局区分能力,区分好客户和坏客户。

PR-AUC(平均精度)

0.9625

不平衡数据的优先指标(相对于 8.12% 的随机基线)。

基尼系数(信用)

0.9920

$2 \times \text{ROC-AUC} - 1$ — 出色的风险分离能力。

全局准确率

98.14%

在 6,830 名客户中正确预测 6,703 个。

精确率(Precision / VPP)

96.52%

每 100 个被分类为违约的客户中,96.5 个确实违约。

召回率 / 灵敏度

80.00%

捕获 每 10 个真实违约者中的 8 个,避免信用损失。

特异度(TNR)

99.75%

保留 99.75% 的好客户,确保健康授信。

误报率(FPR)

0.25%

在 6,275 个分析客户中,仅 16 个健康客户被误拒。

F1 分数

0.8749

精确率和召回率之间的最优调和平衡。

优化决策阈值

0.875

通过 PR 曲线校准的阈值(相对于天真的 0.5 截断)。


3. 留出集详细混淆矩阵

实际 \ 预测

正常(0)

违约(1)

实际总计

信用业务影响

实际正常(0)

6,259 (TN)

16 (FP)

6,275

最小摩擦: 仅 16 个好客户被不当拒绝(FPR = 0.25%)。

实际违约(1)

111 (FN)

444 (TP)

555

避免损失: 成功阻止 444 起违约(召回率 = 80.00%)。

预测总计

6,370

460

6,830

发出风险警报时的命中率: 精确率 96.52%。


4. 获胜超参数(Optuna — 25 次试验)

{
  "n_estimators": 500,
  "max_depth": 4,
  "learning_rate": 0.0121,
  "subsample": 0.7244,
  "colsample_bytree": 0.7301,
  "min_child_weight": 8,
  "gamma": 3.1878,
  "reg_lambda": 3.5388,
  "reg_alpha": 0.0774,
  "scale_pos_weight": 11.3164
}

5. 可审计的前 10 大风险因素(平均 $|\text{SHAP}|$)

排名

特征

平均 $|\text{SHAP}|$

风险依据

1º

credit_score

3,3044

主导因素:信用局的历史评分。

2º

credit_limit_used(%)

1,8558

循环授信额度的使用程度。

3º

credit_utilization_frac

0,6122

信用额度使用率的十进制小数。

4º

risk_flags_sum

0,1516

既有风险标志的加权总和。

5º

prev_defaults

0,1167

既往违约发生的次数。

6º

yearly_debt_payments

0,0445

每年用于还款的财务负担。

7º

no_of_days_employed

0,0382

就业稳定性及在当前岗位的任职时间。

8º

gender_F

0,0339

用于审计监控的人口统计类别。

9º

utilization_x_prev_defaults

0,0266

交互项:高使用率叠加历史违约。

10º

occupation_type_Unknown

0,0240

职业未申报/退休人员标志。

📈 可视化产物位于 reports/figures/:

  • roc_curve.png — 带随机基线的 ROC 曲线。

  • precision_recall_curve.png — 与基础患病率对比的精确率-召回率曲线。

  • confusion_matrix.png — 最优阈值下的混淆矩阵。

  • shap_summary.png — 全局可解释性的 Beeswarm 汇总图。

🔒 上述所有指标均可复现,并保存在 models/model_metadata.json 的审计元数据中。


💡 结果解读指南(面向非技术人员和业务人员)

为便于数据科学家、信贷分析师和非技术背景高管之间的沟通,系统的每项输出都具有直接的业务含义:

1. 📈 违约概率(PD)与行动区间

  • 是什么: 客户在未来数月内逾期支付账单超过 90 天的估计概率(0% 至 100%)。

  • 如何根据区间采取行动:

    • 🟢 MUITO_BAIXO(< 5%)和 BAIXO(5% 至 15%): 建议以有竞争力的利率自动批准授信和提升额度。

    • 🟡 MODERADO(15% 至 35%): 临界客户。建议采用保守的初始额度或要求提供收入证明。

    • 🔴 ALTO(35% 至 60%)和 MUITO_ALTO(≥ 60%): 违约风险较高。建议拒绝申请或要求提供担保人/实物抵押。

2. 📊 如何阅读 SHAP 可解释性图表

  • 🔴 指向右侧的条形(正向贡献): 将风险推高的注册或行为因素(例如:评分低、循环额度使用过度、既往违约)。

  • 🟢 指向左侧的条形(负向贡献): 保护客户并将风险拉低的健康因素(例如:多年就业稳定性、高收入、高评分)。

  • 📏 条形长度: 条形越长,该变量对 AI 最终判定越具有决定性。

3. 📉 什么是 What-If 模拟?

  • 可以模拟规则变更的影响或为被拒客户提供指导。例如:"如果您将额度使用率从 73% 降至 30%,您的风险将从 68% 降至 22%,从而可以批准您的信用卡。"

4. 💰 总敞口与组合预期损失

  • 总敞口: 机构承担的总财务规模(已批准信用额度的总和)。

  • 预期损失($PD \times \text{敞口}$): 如果不采取任何行动,机构预计因违约而在统计上损失的金额(以雷亚尔计)。

  • 损失率(%): 坏账准备金(PDD / IFRS 9)的直接计算基础。


🔌 MCP 服务器 — 6 个业务工具

工具

用途

predict_default

单个客户的概率 + 类别 + 风险区间

explain_prediction

评分背后的主要 SHAP 因素(审计/合规)

what_if_analysis

"如果已用额度降至 30% 会怎样?" — 政策模拟

score_portfolio_csv

对磁盘上的整个 CSV 文件进行批量评分

portfolio_risk_summary

预期损失(PD × 敞口)、风险分布、重点客户

get_model_performance

模型技术规格(指标、超参数、特征)

服务器使用的风险区间:MUITO_BAIXO(<5%)· BAIXO(5–15%)· MODERADO(15–35%)· ALTO(35–60%)· MUITO_ALTO(≥60%)。


🌐 浏览器中的 Web 聊天界面(Streamlit)

该项目包含一个基于 Streamlit 构建的完整对话式 Web 界面,用于演示、快速测试以及信贷和承销团队的日常运营使用:

make web
# ou: streamlit run app.py

在浏览器中访问:http://localhost:8501

✨ Web 界面的主要功能:

  • 💬 自然语言聊天: 用葡萄牙语自由提问关于客户、模拟或组合的问题。

  • ⚡ 快速操作(覆盖全部 5 个风险区间): 一键加载每个区间的代表性客户画像:

    • 🟢 1. 极低(<5%): 优质客户(高收入、评分 910、额度使用率 10%)。

    • 🟢 2. 低(5–15%): 健康客户(评分 810、额度使用率 25%、0 次违约)。

    • 🟡 3. 中等(15–35%): 临界客户(评分 580、额度使用率 50%、无逾期)。

    • 🔴 4. 高(35–60%): 警示客户(评分 580、额度使用率 50%、近期 1 次违约)。

    • ⛔ 5. 极高(≥60%): 危急客户(评分 544、额度使用率 73%、2 次违约)。

  • 🛠️ 建议查询面板:

    • 📊 技术规格: 显示验证指标、ROC-AUC、PR-AUC 和准确率。

    • 📁 CSV 组合: 以向量化评分评估整个组合,11,000 名客户仅需 0.7 秒,并计算**预期损失(R$)**和总敞口。

    • 📉 What-If 模拟: 模拟额度下调(30%)、债务清偿或评分提升(+150 分)。

    • 🔬 SHAP 审计: 信贷风险主要驱动因素的排名和条形图。

  • 💡 面向非技术人员的可展开指南: 每个回答都包含教学性图例,解释 SHAP 图表、概率变化和损失准备金的意义。


🔌 选项 2:MCP 服务器(Claude Desktop / Claude Code)

# 1. Instalar dependências
pip install -r requirements.txt --break-system-packages   # ou use um venv

# 2. Treinar o modelo (gera models/*.joblib e model_metadata.json)
python -m src.train

# 3. (Opcional) Gerar os gráficos de avaliação em reports/figures/
python -m src.evaluate

# 4. Rodar os testes
pytest -v

# 5. Subir o servidor MCP (stdio)
python -m mcp_server.server

连接到 Claude Desktop / Claude Code

将 mcp_server/claude_desktop_config.example.json 复制到您客户端的 MCP 配置文件中,并调整绝对路径:

{
  "mcpServers": {
    "agent-risk-ai": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "/caminho/absoluto/para/agent-risk-ai",
      "env": { "PYTHONPATH": "/caminho/absoluto/para/agent-risk-ai" }
    }
  }
}

重启客户端并提问,例如: "使用 agent-risk-ai 服务器,这位客户的风险是多少:..."


📁 项目结构

agent-risk-ai/
├── app.py                       # Interface Web Chat conversacional no navegador (Streamlit)
├── data/raw/                    # train.csv, test.csv, sample_submission.csv
├── src/
│   ├── config.py                 # caminhos, sementes, regras de negócio centralizadas
│   ├── data_processing.py        # limpeza (sentinelas, winsorização, PII)
│   ├── feature_engineering.py    # features de domínio (DTI, utilização, tenure...)
│   ├── pipeline.py                # ColumnTransformer sklearn (sem vazamento)
│   ├── train.py                   # baselines + Optuna + XGBoost + SHAP + persistência
│   ├── evaluate.py                # gera gráficos (ROC, PR, confusão, SHAP)
│   └── inference.py                # camada de predição reutilizada pelo MCP e Web Chat
├── mcp_server/
│   ├── server.py                   # servidor MCP com as 6 ferramentas
│   └── claude_desktop_config.example.json
├── models/                         # modelo treinado + metadados (gerado por train.py)
├── reports/figures/                 # gráficos de avaliação (gerado por evaluate.py)
├── tests/test_pipeline.py            # 7 testes unitários (pytest)
├── requirements.txt
├── Makefile
└── README.md

⚠️ 已知限制与后续步骤

对限制保持透明是严谨数据科学的一部分:

  • LGD 在预期损失计算中假设为 100%(portfolio_risk_summary) 仅为简化处理 — 在生产环境中,该值应来自历史回收数据。

  • 无漂移监控 — 下一步自然是使用特征分布日志对 predict_default 进行随时间变化的监控。

  • 概率校准 未通过 CalibratedClassifierCV 验证 — 概率具有区分能力(适合风险排序),但在绝对尺度上可能 并非完美校准。

  • occupation_type = "Unknown" 是最常见的类别(约占样本的 ~31%), 且与退休/未就业标志重合 — 未来的改进方向是 拆分该类别。


🧠 技术栈

Python 3.12 · pandas · scikit-learn · XGBoost · Optuna(基于 TPE 的贝叶斯调参)· SHAP(可解释性)· matplotlib · pytest · MCP Python SDK


Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides AI agents with quantitative risk tools such as VaR, expected shortfall, GARCH volatility, backtesting, stress testing, tail risk analysis, and credit scoring using synthetic or user-supplied data.
      7
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A natural-language interface to a credit risk database, with SQL guardrails that enforce read-only, allowlisted access to tables and columns.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables users to query financial data and compute credit-risk metrics like Altman Z-Score and loan default probability through natural language.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to run probabilistic portfolio analysis workflows, including input validation, instrument verification, simulation preparation, and approved interactive reporting.
      -