arushiranjan/agentic-aml-analyzer
GitHub: arushiranjan/agentic-aml-analyzer
基于 AI 智能体的反洗钱可疑活动检测系统，支持上传交易数据并通过自然语言进行动态风险分析与可解释报告生成。
Stars: 0 | Forks: 0
# AI 驱动的可疑活动检测智能体 (AML)
一个用于反洗钱 (AML) 可疑活动检测的 **Agentic AI** 系统。上传银行交易 CSV 文件，然后提出自然语言问题——一个单一的规划智能体会决定每个问题实际需要哪些分析工具，并仅运行这些工具，而不是采用固定的顺序流水线。
## 目录
1. [项目概述](#project-overview)
2. [架构](#architecture)
3. [文件夹结构](#folder-structure)
4. [安装与配置](#setup--installation)
5. [环境变量](#environment-variables)
6. [如何获取 OpenAI API Key](#how-to-obtain-an-openai-api-key)
7. [运行后端](#running-the-backend)
8. [运行前端](#running-the-frontend)
9. [使用示例数据集运行](#running-with-the-sample-dataset)
10. [智能体工作原理](#how-the-agent-works)
11. [规则工作原理](#how-the-rules-work)
12. [ML 模型工作原理](#how-the-ml-model-works)
13. [风险评分工作原理](#how-risk-scoring-works)
14. [API 参考](#api-reference)
15. [截图](#screenshots)
16. [未来改进](#future-improvements)
## 项目概述
银行每天会产生数以百万计的交易。合规分析师需要提出临时性的问题，比如*“查找可疑客户”*或*“显示分层模式”*，而不必每次都等待数据科学家编写新脚本。
本项目是位于六个专业工具（EDA、特征工程、规则引擎、ML 异常检测、风险评分、解释生成器）前方的**单一智能规划智能体**。该智能体会读取问题，决定哪些工具相关，仅执行这些工具，并返回可解释的答案——而不是机械生成的固定报告。
## 架构
```
User
│
▼
Streamlit Dashboard (frontend/app.py)
│ HTTP
▼
FastAPI (backend/main.py)
│
▼
AI Planner Agent (agent/planner.py) -- decides WHICH tools to run
│
▼
Tool Executor (tools/executor.py) -- runs ONLY those tools, in dependency order
│
├── EDA Tool (tools/eda_tool.py)
├── Feature Engineering Tool (tools/feature_engineering.py)
├── Rule Engine (tools/rule_engine.py)
├── ML Anomaly Detection (tools/ml_tool.py)
├── Risk Scoring (tools/risk_scoring.py)
└── Explanation Generator (tools/explanation_tool.py)
│
▼
Response (JSON) → rendered by Streamlit
```
完整技术文档：[`docs/architecture.md`](docs/architecture.md)。
## 文件夹结构
```
project/
├── README.md
├── requirements.txt
├── .env.example
├── backend/
│ ├── __init__.py
│ └── main.py # FastAPI app + endpoints
├── frontend/
│ └── app.py # Streamlit multi-page dashboard
├── agent/
│ ├── __init__.py
│ ├── planner.py # THE planning agent (LLM + JSON plan)
│ └── intent_rules.py # Keyword fallback when LLM is unavailable
├── tools/
│ ├── __init__.py
│ ├── executor.py # Runs only the requested tools, in order
│ ├── eda_tool.py
│ ├── feature_engineering.py
│ ├── rule_engine.py
│ ├── ml_tool.py
│ ├── risk_scoring.py
│ └── explanation_tool.py
├── utils/
│ ├── __init__.py
│ ├── llm_client.py # Swappable LLM provider wrapper
│ └── data_loader.py # CSV validation + in-memory dataset store
├── data/ # (scratch space for cached artifacts)
├── models/ # (scratch space for persisted models, if added)
├── docs/
│ └── architecture.md
├── sample_data/
│ ├── generate_sample_data.py # Regenerates the synthetic dataset
│ └── transactions.csv # Ready-to-use sample dataset
└── tests/
├── __init__.py
└── test_pipeline.py
```
## 安装与配置
**要求：** Python 3.11+
```
# 克隆 / 解压项目，然后 cd 进入该项目
cd aml-agent
# 创建 virtual environment
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.example .env
# 然后打开 .env 并粘贴你的 OpenAI key（可选 — 见下文）
```
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|--------------------|----------|-------------------------|------------------------------------------------|
| `OPENAI_API_KEY` | 否 | (空) | 启用基于 LLM 的规划和解释功能。 |
| `OPENAI_MODEL` | 否 | `gpt-4.1` | 任何支持 chat-completion 的 OpenAI 模型。 |
| `BACKEND_URL` | 否 | `http://localhost:8000`| 供 Streamlit 前端访问 API 使用。 |
**即使没有 `OPENAI_API_KEY`**，系统依然可以端到端运行：规划器会回退到确定性的关键词匹配（`agent/intent_rules.py`），解释工具会回退到基于模板的摘要（`tools/explanation_tool.py`）。这是有意设计的，确保即使在无法连接 OpenAI 的情况下，该项目也始终可用于演示。
## 如何获取 OpenAI API Key
1. 访问 创建账户（或登录）。
2. 导航至 。
3. 点击 **“Create new secret key”**，为其命名（例如 `aml-hackathon`），并立即复制——它仅会显示一次。
4. 如果尚未操作，请在 **Settings → Billing** 下添加账单信息（几美元的额度足以应对黑客松演示）。
5. 将密钥粘贴到您的 `.env` 文件中，格式为 `OPENAI_API_KEY=sk-...`。
## 运行后端
```
cd backend
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
- API 文档：
- 健康检查： `GET http://localhost:8000/health`
## 运行前端
在第二个终端中（激活相同的虚拟环境）：
```
cd frontend
streamlit run app.py
```
这将在 打开仪表板。请确保后端已首先运行——侧边栏的 **Settings → Check backend health** 按钮可确认连接状态。
## 使用示例数据集运行
一个现成的合成数据集包含了**故意注入的可疑模式**（拆分交易、分层、循环转账、休眠后激活、高频交易、大额异常、异常收款人数量），位于 `sample_data/transactions.csv`。随时可以使用以下命令重新生成它：
```
python sample_data/generate_sample_data.py
```
演示步骤：
1. 按上述步骤启动后端 + 前端。
2. 在 **Upload Dataset** 页面上传 `sample_data/transactions.csv`。
3. 进入 **Dashboard** → 点击 **Run Full Risk Pipeline**。
4. 在 **Chat** 页面尝试输入：*“查找可疑客户”*、*“显示拆分交易”*、*“解释客户 C901”*、*“平均交易金额”*。
5. 在 **Network Graph** 中，查询 `C910` 并设置 2 跳，查看注入的循环转账环（`C910 → C911 → C912 → C910`）。
## 智能体工作原理
`agent/planner.py` 是本系统中的**单一**规划智能体（这是设计使然——没有多智能体编排）。对于每个用户查询，它会：
1. 在 JSON 模式下将查询和工具目录发送给 LLM。
2. 解析返回的计划：`intent`、`tools`、`filters`、`customer_id`、`reasoning`。
3. 验证每个工具名称是否真实存在（丢弃幻觉产生的工具名称）。
4. 如果 LLM 不可用或返回无效的 JSON，则回退到 `agent/intent_rules.py`（一个确定性的关键词匹配器），因此智能体绝不会完全崩溃。
接着，`tools/executor.py` 会使用任何缺失的先决工具扩展该计划（例如 `risk_score` 需要 `rules` + `ml`，而这又需要 `features`），并**仅**执行解析出的该链条——这正是使系统具有动态性而非固定顺序流水线的原因。询问 *“平均交易金额”* 仅运行 EDA 工具；询问 *“查找可疑客户”* 会运行完整的 features → rules → ML → risk → explanation 链条。
## 规则工作原理
`tools/rule_engine.py` 实现了九条确定性的、可解释的 AML 规则，每条规则都会返回一个 `(customer_id, score, reason)` 的命中结果：
| 规则 | 信号 |
|---|---|
| 拆分交易 | 多笔金额刚好低于报告阈值 (₹10,000) 的交易 |
| 多笔小额转账 | 大量低价值转账 |
| 高频交易 | 任意 1 小时窗口内交易次数过多 |
| 快速 P2P | 30 分钟窗口内（滑动窗口）有多个不同的收款人 |
| 分层 | 2 小时内收入资金被转发给不同的另一方 |
| 休眠 → 激活 | 活动间隔 ≥30 天后突然爆发 |
| 循环转账 | 使用 NetworkX `simple_cycles` 检测到的图谱环 (A→B→...→A) |
| 大额异常 | 远高于客户自身历史平均水平的交易 (z-score) |
| 异常收款人数量 | 受款人数量远高于典型客户 |
所有阈值都是在 `rule_engine.py` 顶部定义的命名常量，便于根据不同司法管辖区进行调整。
## ML 模型工作原理
`tools/ml_tool.py` 会在 `tools/feature_engineering.py` 生成的每个客户的特征表（交易频率、滚动总和/平均值、速度、唯一受益人、拆分交易比例等）上拟合一个 scikit-learn 的 **Isolation Forest**。模型的 `decision_function` 输出被反转并进行了 min-max 归一化，映射到 `[0, 1]` 范围内的 `ml_score`（1 = 最异常），从而能够捕捉到不匹配任何手写规则的模式。
## 风险评分工作原理
`tools/risk_scoring.py` 结合了每个客户的两个信号：
```
final_score = 0.6 * rule_score + 0.4 * ml_score
```
| final_score | 标签 |
|---|---|
| ≥ 0.65 | **高** |
| 0.35 – 0.64 | **中** |
| < 0.35 | **低** |
然后，`tools/explanation_tool.py` 会将标记出的顶级客户的规则命中情况和分数转化为通俗易懂的解释和建议（如果可用则由 LLM 生成，否则基于模板生成）。
## API 参考
| 方法 | 路径 | 描述 |
|---|---|---|
| `GET` | `/health` | 健康检查 |
| `POST` | `/upload` | 上传交易 CSV（multipart 表单，字段名为 `file`） |
| `POST` | `/chat` | `{query, dataset_id}` → 智能体计划 + 工具结果 |
| `POST` | `/eda` | 绕过规划器的直接 EDA 调用 |
| `POST` | `/risk-report` | 运行完整的 features→rules→ml→risk→explanation 流水线 |
| `GET` | `/customer/{customer_id}` | 单个客户的全面深入分析 |
| `GET` | `/graph/{customer_id}` | 单个客户周围的交易图谱（节点/边） |
后端运行后，可在 `/docs` 查看完整的交互式文档。
## 截图
## 未来改进
- 将数据集和风险报告持久化到真实的数据库 中，而不是存储在内存中。
- 为合规分析师添加身份验证/授权机制。
- 在 Chat 页面支持流式传输 LLM 响应。
- 添加基于标记的 SAR（可疑活动报告）结果训练的监督学习模型，以补充无监督的 Isolation Forest。
- 通过 Settings 页面添加可配置的规则阈值，而不是使用源代码中的常量。
- 针对超大交易量进行批处理/异步处理（为 `pandas` 提供 Dask/Spark 后端）。
- 针对拆分交易阈值增加多币种标准化支持。
标签：DLL 劫持, Kubernetes, 人工智能, 反洗钱, 大语言模型, 异常检测, 特权检测, 用户模式Hook绕过, 逆向工具, 金融风控