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

人工智能风险代理：您通过 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: CreddyMCP

🗂️ 业务问题

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

🏗️ 系统如何工作（简单架构）

该项目将原始信用数据转化为可操作、可审计的决策，供 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”，每个派生特征都有明确的信用风险理由：

🧪 方法论与统计严谨性

• 仅在训练集上学习的 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 折分层交叉验证）

2. 留出集性能指标（冠军模型）

3. 留出集详细混淆矩阵

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}|$）

📈 可视化产物位于 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 个业务工具

服务器使用的风险区间：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