# FraudTgnStream

**Repository Path**: songcoder_1_0/FraudTgnStream

## Basic Information

- **Project Name**: FraudTgnStream
- **Description**: 本研究提出一种基于简化时序图神经网络（TGN）的流式反欺诈决策引擎。通过摒弃传统图网络中的复杂消息传递机制，采用门控循环单元（GRU）作为核心时序状态维护模块，将动态内存机制简化为 GRU 隐藏状态，实现了高效的在线增量学习与状态更新。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-19
- **Last Updated**: 2026-03-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

下面是一份**完善版中文 README**，从环境配置到启动 App、演示与排错，开箱即用。你可以将本内容保存为项目根目录下的 `README.md`。

---

# 流式反欺诈决策引擎（简化 TGN）

基于**动态时序图**思想（简化版 TGN）的在线反欺诈 Demo：

* **Python + FastAPI** 后端，**原生 Web 前端**（HTML/CSS/JS + Chart.js）。
* 支持**前端本地仿真流**：无需 WebSocket、无需第二个终端。
* **训练脚本**生成权重，服务端按事件时间顺序增量更新状态。
* 前端提供**实时评分流**、**KPI（近 1 分钟平均风险/拒绝率/审核率/样本量）**、**折线/柱状图**、**一键导出 CSV**。
* 代码量与依赖控制在“比赛 Demo”等级，**完整可跑**、易于改造。

---

## 目录结构

```
fraud-tgn-stream/
├─ README.md
├─ requirements.txt
├─ train.py                       # 训练入口（含早停/保存最佳/学习率调度）
├─ simulate_and_stream.py         # 旧版 WebSocket 仿真（现已不必使用）
└─ app/
   ├─ __init__.py
   ├─ config.py                   # 阈值与模型路径配置
   ├─ api/
   │  ├─ __init__.py
   │  ├─ schemas.py
   │  └─ serve.py                 # FastAPI 服务（托管 /static 前端）
   ├─ data/
   │  ├─ __init__.py
   │  ├─ generator.py             # 仿真数据生成
   │  └─ dataset.py               # 训练集包装
   ├─ models/
   │  ├─ __init__.py
   │  └─ tgn_simplified.py        # 简化版 TGN 模型（增量状态）
   ├─ utils/
   │  ├─ __init__.py
   │  ├─ training.py              # 训练循环
   │  └─ metrics.py               # AUC/AP 评估（已修复局部导入问题）
   └─ web/
      ├─ index.html               # 极简深色前端（含 KPI/图表/导出 CSV）
      ├─ styles.css               # 统一风格 & 图表容器限高（已修复）
      ├─ app.js                   # 前端本地仿真 + 调用 /score
      └─ favicon.svg              # 可选图标
```

---

## 环境要求

* **Python 3.9 ~ 3.11**（建议 3.10）
* Windows / Linux / macOS 均可
* 可选：NVIDIA CUDA + PyTorch GPU（自动检测；没有也可 CPU 运行）
* 端口 **8000** 可用（可改）

---

## 快速上手

### 方式一：使用 Conda（推荐 Windows / 多环境管理）

```powershell
# 1) 创建并激活环境
conda create -n tgn python=3.10 -y
conda activate tgn

# 2) 安装依赖
pip install -r requirements.txt
# 如需 GPU，请按 PyTorch 官方指引安装相应 cuda 版本的 torch
# 例如：pip install torch==2.3.1+cu121 torchvision --index-url https://download.pytorch.org/whl/cu121

# 3) 训练（生成 checkpoint/model.pt 与 meta.json）
python train.py --n_users 2000 --n_merchants 600 --days 7 --epochs 20 --patience 5

# 4) 启动服务
uvicorn app.api.serve:app --reload --port 8000

# 5) 打开浏览器访问
# http://127.0.0.1:8000/
```

### 方式二：使用 Python venv（跨平台通用）

```bash
# 1) 创建并激活虚拟环境
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 2) 安装依赖
pip install -r requirements.txt

# 3) 训练
python train.py --n_users 2000 --n_merchants 600 --days 7 --epochs 20 --patience 5

# 4) 启动服务
uvicorn app.api.serve:app --reload --port 8000

# 5) 浏览器访问
# http://127.0.0.1:8000/
```

> ⚠️ 如果你使用 GPU：
>
> * 先到 [https://pytorch.org/](https://pytorch.org/) 选择与你本机 CUDA 版本匹配的 `torch` 安装命令；
> * 确认 `python -c "import torch;print(torch.cuda.is_available())"` 返回 `True`。

---

## 配置说明

* 模型与元信息输出位置：`./checkpoint/`

* 重要阈值在 `app/config.py`：

  ```python
  RISK_THRESHOLDS = {
      "approve": 0.30,  # 分数 < 0.30 -> 通过
      "review":  0.65   # 0.30 <= 分数 < 0.65 -> 人工审核，否则拒绝
  }
  ```

  可按业务需要微调。

* 训练常用参数（`train.py`）：

  * `--n_users / --n_merchants / --days`：仿真数据规模与时长
  * `--epochs`：最大轮数（默认 20）
  * `--patience`：早停耐心（默认 3，推荐 3~5）
  * `--lr_step / --lr_gamma`：学习率 StepLR 调度
  * `--embed_dim`：嵌入维度（默认 64）
  * `--batch_size`：批大小（默认 2048）

---

## 使用指南

1. 训练完成后，执行：

   ```bash
   uvicorn app.api.serve:app --reload --port 8000
   ```

2. 打开 `http://127.0.0.1:8000/`，你将看到前端页面：

   * 顶部**速率**：设置仿真速率（每秒事件数，1~20）
   * **开始仿真**：前端本地生成交易事件，逐条调用 `/score`
   * **停止仿真**：暂停仿真
   * **重置状态**：清空前端日志与图表（默认不重置后端）
   * **导出 CSV**：导出本次会话的事件评分日志

3. 左侧卡片：

   * **单笔交易打分**：填入 `user_id / merchant_id / amount / ts`（Unix 秒），点击“打分”
   * 下方显示**风险分**、**决策**与**Top 解释**

4. 中间卡片：

   * **实时评分流**：滚动展示每笔事件的决策与风险分

5. 右侧卡片（核心指标与图表）：

   * **KPI（近 60 秒）**：平均风险分、拒绝率、审核率、样本量
   * **折线图**：最近 120 个点的风险分（自动滚动）
   * **柱状图**：近 60 秒三类决策的数量分布

---

## API 说明

* `POST /score`

  * 请求：

    ```json
    {
      "user_id": 12,
      "merchant_id": 5,
      "amount": 399.0,
      "ts": 1690000123
    }
    ```
  * 返回：

    ```json
    {
      "risk_score": 0.42,
      "decision": "review",
      "reasons": ["高金额","非常规时段"]
    }
    ```

* （可选）`POST /reset`
  如果你需要**后端**也重置模型时序状态，在 `app/api/serve.py` 中加入：

  ```python
  @app.post("/reset")
  async def reset_states():
      MODEL.reset_states()
      return {"ok": True}
  ```

  然后把前端的“重置状态”按钮改为调用 `/reset`（`app/web/app.js` 中已给出可选代码段）。

---

## 常见问题（FAQ / 排错）

1. **静态资源 404（`/styles.css`、`/app.js`）**

   * 我们已将前端资源以**绝对路径**引用：`/static/styles.css`；
   * `serve.py` 中使用：

     ```python
     STATIC_DIR = os.path.join(os.path.dirname(__file__), '..', 'web')
     app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
     ```
   * 启动后访问 `http://127.0.0.1:8000/` 即自动加载，无需手动进 `/static/`。

2. **折线/柱状图高度无限延伸**

   * `styles.css` 已限制图表容器高度（`.chart-card { height: 260px; }`），并让 `canvas { height: 100% !important; }`；
   * 若仍需固定像素，给 `<canvas>` 增加 `height="260"` 即可。

3. **`app/utils/metrics.py` 报错 `UnboundLocalError: local variable 'torch' referenced before assignment`**

   * 该问题已修复（移除了函数内局部 `import torch`），请确保你已使用最新版本的文件。

4. **端口占用 / 启动失败**

   * 修改端口：

     ```bash
     uvicorn app.api.serve:app --reload --port 8080
     ```
   * 或关闭占用 8000 端口的进程。

5. **Torch / CUDA 安装问题**

   * 如果 `torch.cuda.is_available()` 为 `False`，将自动使用 CPU；
   * GPU 加速需与你本机 CUDA 匹配的 `torch` 轮子，请到 PyTorch 官网选择命令安装。

6. **路径中包含中文或空格**

   * 建议将项目放到不含空格/中文的路径下（Windows 某些工具对编码不友好）。

7. **不希望开两个终端 / 不想要 WebSocket**

   * 本方案前端**本地仿真**，无需 WebSocket 与第二终端；
   * 旧脚本 `simulate_and_stream.py` 可以删除或保留作参考。

---

## 调参与优化建议

* 增大数据规模（`--n_users/--n_merchants/--days`）会增加训练时间与内存占用；
* 调小 `--batch_size` + 增大 `--epochs` 并配合早停（`--patience`）更稳定；
* 阈值建议上线前用真实验证集重新校准（`RISK_THRESHOLDS`）；
* 模型增强方向（可选）：完善时间编码、加入静态画像特征、对比学习、双塔结构等。

---

## 许可证与声明

本仓库用于**学习演示与比赛展示**，仿真数据仅为合成数据，不包含任何真实用户信息。
如需商用或接入真实风控系统，请严格遵循数据合规与安全要求，并进行充分的离线/线上评估与应急预案设计。

---

### 一键指令速览（Windows PowerShell）

```powershell
# 新建环境
conda create -n tgn python=3.10 -y
conda activate tgn

# 安装依赖
pip install -r requirements.txt

# 训练（含早停/保存最佳）
python train.py --n_users 2000 --n_merchants 600 --days 7 --epochs 20 --patience 5

# 启动服务
uvicorn app.api.serve:app --reload --port 8000

# 访问
# http://127.0.0.1:8000/
```