Live synthetic demo · Release 0.2.2 · Case study
GraphShield-Fraud 是一个面向图算法、风控与反欺诈岗位的时序图风险识别项目。它以交易为节点、资金关联为边，在严格时间切分下比较非图基线与因果 GraphSAGE，并同时交付离线调查工件与事件级在线风险演示。
项目已经完成可复现的 toy 闭环、真实 Elliptic v1 时序评测和 synthetic event replay。Toy 在线结果只证明因果状态、幂等、接口、延迟采样和界面可运行；正式模型数字仍只来自官方 Kaggle ellipticco/elliptic-data-set 的固定协议报告。
当前公开包为 0.2.2；真实 Elliptic 聚合结果沿用不可改写的 v0.2.1 冻结证据。
项目仓库：nikashen/GraphShield-Fraud
招聘方快速入口：一页式案例 · 简历与面试材料 · 公开边界
Chrome 1440×1000 的 deterministic toy 工作台。背景风险队列、弹窗输入、评分结果和 replay 全部来自生成数据；真实 Elliptic 只通过下方聚合报告展示，不发布行级特征、标签、 预测或图切片。截图来源与 SHA-256 见 截图清单。
| 招聘方可快速核验的结论 | 冻结证据 |
|---|---|
| 强树基线不能省略 | HGB Test PR-AUC 0.6650，GraphSAGE 为 0.3783 |
| 极低误报工作点比 ROC-AUC 更接近风控约束 | HGB 在 FPR ≤ 1% 时 Recall 0.5928 |
| 平均指标会掩盖时间漂移 | Test 表现从 timestep 43 起明显回落 |
Windows PowerShell：
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[serve]"
.\.venv\Scripts\graphshield.exe serve --port 8060macOS / Linux：
python3.11 -m venv .venv
.venv/bin/python -m pip install -e ".[serve]"
.venv/bin/graphshield serve --port 8060浏览器打开 http://127.0.0.1:8060/?online=1。使用 sample event 执行评分、幂等重试、
toy replay 与 reset。未传 --artifact 时服务始终使用内存 toy，不训练模型、不下载真实
数据，也不会自动读取本地 Elliptic 工件；显式传入缺失或损坏的 artifact 仍会 fail-closed。
- 严格 Elliptic CSV loader：保留
unknown为图上下文，不把未知标签伪装成负样本。 - SHA-256/文件大小 manifest、路径逃逸防护、重复节点/边端点/特征维度审计。
- Train/Validation/Test 按 timestep 切分，累计上下文只读到当前 cutoff。
- 每条 GraphSAGE 消息满足
source_timestep <= receiver_timestep，阻断未来节点向历史节点传递信息。 - 类别平衡 Logistic Regression、HistGradientBoosting 与纯 PyTorch Temporal GraphSAGE。
- PR-AUC、ROC-AUC、固定低 FPR Recall、Top-K、Brier、ECE、时间窗口稳定性。
- 成本敏感阈值只在 Validation 选择，Test 不参与模型或阈值选择。
- FastAPI 风险查询、风险队列、搜索、1/2 跳历史子图、时间线、关联交易与解释面板。
POST /api/score/POST /api/events事件级评分：先评分后提交，支持请求幂等、代数令牌、迟到拒绝、容量和 payload 上限。- 进程内因果图状态：账户/设备复用、速度、出入度、有界 1/2 跳历史邻居，未来事件不会改变早期分数。
POST /api/online/reset使用 reset ID + 期望状态版本执行 CAS；安全重试不会误删 reset 后的新事件，便于重复面试演示。- Synthetic replay 输出 p50/p95/p99、本机吞吐、结果/状态 SHA-256；明确不是生产 SLA 或线上收益。
- GitHub Actions 在 toy 数据上自动执行完整测试、在线回放、wheel 构建和隔离安装检查。
Elliptic CSV / deterministic toy
|
v
checksum manifest + data audit
|
v
chronological cumulative graph views
Train cutoff -> Validation cutoff -> Test cutoff
|
+-------------------------+
| |
tabular baselines causal Temporal GraphSAGE
| |
+------------+------------+
v
Validation model ranking + cost threshold
|
v
one-pass Test evaluation and stability
|
v
strict JSON artifact -> FastAPI -> investigation console
synthetic event stream -> validate -> score on prior state -> commit
| |
+-> reason codes +-> live console / replay report
完整数据边界见 DATA_PROTOCOL.md，在线契约见 ONLINE_PROTOCOL.md，模块职责见 ARCHITECTURE.md。
固定协议为 Train timestep 1-29、Validation 30-39、Test 40-49，seed 17。Validation 同时负责模型排序和成本阈值选择，Test 不参与调参。
| Model | Val PR-AUC | Test PR-AUC | Test ROC-AUC | Recall at FPR <= 1% | Brier | ECE |
|---|---|---|---|---|---|---|
| Balanced Logistic Regression | 0.4058 | 0.1566 | 0.8169 | 0.0047 | 0.3645 | 0.3994 |
| HistGradientBoosting | 0.9756 | 0.6650 | 0.8823 | 0.5928 | 0.0353 | 0.0414 |
| Causal Temporal GraphSAGE | 0.6509 | 0.3783 | 0.8139 | 0.2421 | 0.0546 | 0.0477 |
Validation 选择 HistGradientBoosting。它在冻结阈值 0.3357 下对 Test 产生 739 个告警，Precision 0.5304、Recall 0.6164。当前 GraphSAGE 没有超过强树基线，因此项目结论是“强基线与时间漂移审计”，不是 GNN 优越性。
Test 的窗口表现从 timestep 43 起明显下降；完整逐窗口数字、来源哈希和边界见 聚合报告 与 机器可读报告。GraphSAGE 在三模型运行和隔离复跑中的模型证据 payload 完全一致，见 复现检查。
在提交 adeb69b33a9ae2c76fd7ad588f1c81185df4dc3d 的干净工作区上，512 个 toy 事件逐条执行 score_event，预热 32 个事件后得到 p50 1.9878 ms、p95 3.3367 ms、p99 3.6731 ms、约 517.831 events/s；产生 38 个演示告警。因果前缀、迟到拒绝、幂等重试和结果/状态 SHA-256 均通过，见 在线回放报告。这些数字是本机单进程 synthetic 诊断，不是生产 SLA、真实欺诈率或业务收益。
Python 要求 3.10-3.12。Windows 参考环境已验证 Python 3.10.16、NumPy 1.26.4、scikit-learn 1.5.1、PyTorch 2.6.0+cu118、FastAPI 0.136.3。
Set-Location <path-to-GraphShield-Fraud>
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -U pip
.\.venv\Scripts\python.exe -m pip install -e ".[dev,serve]"
# 生成三份 Elliptic 形状的 toy CSV、训练三种模型并导出调查工件。
.\.venv\Scripts\graphshield.exe smoke --output-dir artifacts\demo
# 启动风险调查台。
.\.venv\Scripts\graphshield.exe serve `
--artifact artifacts\demo\report.json `
--host 127.0.0.1 `
--port 8060
# 生成可复现的本机 synthetic replay 证据。
.\.venv\Scripts\graphshield.exe replay `
--count 512 `
--warmup 32 `
--output reports\online_replay_toy.json浏览器打开 http://127.0.0.1:8060；使用 http://127.0.0.1:8060/?online=1 可直接打开实时检测面板。也可以直接运行 start_demo.ps1。
调查台支持搜索、风险队列、1/2 跳历史图、缩放拖动、时间线、关联交易、事件提交、幂等重试和 toy replay。离线分数与在线 toy 状态彼此独立；真实 Elliptic 行级工件只保留在本地。
390 px 移动端保持单列输入；提交后可继续查看风险结果：
离线调查视图仍保留冻结工件的历史图与解释面板：
仓库不再分发第三方原始数据。将数据放到本地目录：
data/elliptic/
elliptic_txs_features.csv
elliptic_txs_edgelist.csv
elliptic_txs_classes.csv
manifest.json # 推荐，包含来源、版本、许可和 SHA-256
先审计，再运行实验：
graphshield audit `
--data-dir data\elliptic `
--train-end 29 `
--validation-end 39 `
--test-end 49 `
--output artifacts\elliptic\audit.json
graphshield run `
--data-dir data\elliptic `
--train-end 29 `
--validation-end 39 `
--test-end 49 `
--models all `
--graphsage-epochs 200 `
--output artifacts\elliptic\report.json上述 29/39/49 是本仓库固定的可复现 60/20/20 协议，不被描述为唯一官方切分，也不与不同协议的论文数字直接横比。任何简历数字都必须同时携带数据来源、manifest、切分边界、seed、完整报告和 claim boundary。
| 能力 | 当前状态 | 可否用于简历数字 |
|---|---|---|
| 数据协议、未来泄漏审计、模型与指标单测 | 已完成 | 可描述工程能力 |
| Toy 三模型训练、API 和浏览器演示 | 已完成 | 只能演示，不能引用 toy 指标 |
| 真实 Elliptic 固定协议评测 | 已完成，Run 32f361645b85b65b |
可携带协议和边界引用 |
| 事件级在线适配、因果状态、幂等与本机 replay | 已完成，synthetic/local | 可描述工程能力；延迟不可写成生产 SLA |
| 生产实时拦截、线上收益、真实欺诈率 | 未验证 | 不可声称 |
简历写法与三分钟面试演示见 RESUME_PROJECT_ZH.md。
$env:PYTHONPATH = (Resolve-Path .\src).Path
python -m pytest -q
python -m graphshield smoke --output-dir artifacts\smoke
python -m graphshield replay --count 128 --warmup 8 `
--output artifacts\verification\online_replay_toy.json当前回归为 118/118 PASS。测试覆盖数据清单与路径安全、CSV 异常、时间切分、未来边、未知标签、两类基线、GraphSAGE 因果消息、低 FPR/Top-K/校准/阈值、在线因果状态、请求幂等、reset CAS/安全重试、并发版本冲突、迟到/容量/payload 边界、replay 哈希、CLI、API、公开截图、Pages 和作品集事实契约。
项目参考 Elliptic、GraphSAGE、GAT、TGN 等论文的公开思想，并使用 PyTorch、scikit-learn、FastAPI 等成熟基础库；核心数据协议、纯 PyTorch GraphSAGE、评测、工件和调查台均在本仓库实现，不复制完整开源反欺诈项目。详见 OPEN_SOURCE_REFERENCES.md 与 THIRD_PARTY_NOTICES.md。
仓库原创代码采用 MIT License。第三方数据和依赖遵循各自许可，MIT 不覆盖 Elliptic 数据。