Newshot 仓库文件导航
fraud-decision-lab
一个厂商中立的研究基准，用于比较专用 AI 决策模型与传统机器学习在支付欺诈排序上的表现。它把相同的交易发送给 TypeSafe Jev、OpenAI Decisions、Cloudflare Clef / Clef-flash 以及一个结构化输出 LLM，然后衡量每一个在分析师复核队列顶部排序出多少已标注欺诈，与 XGBoost 基线对比，以及成本和延迟如何。
欺诈团队只能复核一小部分交易。有用的问题不是“这个模型聪明吗？”而是“如果分析师只能复核前 1%，谁的排序抓到最多欺诈，成本是多少？”这个 lab 在配置好的已标注表格数据集上探索这一点。它默认离线运行，并保存预测和实验元数据以供本地验证。
由 Smart Mobile House 构建和维护——面向企业的安全 AI 实施。
比较内容
| 模型 | 如何为交易评分 | 运行位置 |
|---|---|---|
| XGBoost | 监督式梯度提升树，在已标注历史上训练 | 本地 |
| Rules | 透明的手写风险评分 | 本地 |
| TypeSafe Jev | 零样本决策模型（System One API） | 通过 API |
| OpenAI Decisions | 零样本决策端点 | 通过 API |
| Cloudflare Clef / Clef-flash | Workers AI 上的零样本决策模型 | 通过 API |
| 结构化输出 LLM | 一个被强制输出严格 JSON 分数的通用 LLM | 通过 API |
模型使用相同的已配置特征 schema。API 提供方通过各提供方特定的格式接收共享的欺诈问题和字段描述；数值载荷四舍五入到四位小数。Rules 和 XGBoost 使用原始 dataframe 值，XGBoost 从已标注的训练历史中学习。这些是有意为之的差异，而不是完全相同的模型输入。
指标包括平均精度（已标注 PR-AUC）、前 1% 和前 5% 的 recall、前 1% 的 precision 和欺诈数量，以及相对于 XGBoost 的配对 bootstrap 差异。只有当评估 10,000 个案例时，前 1% 才是 100 个案例。运行摘要区分最终完成与更早的尝试；API 成本根据用量和带日期的价格快照计算，而不是发票。
快速开始
不需要 API 密钥、不需要下载数据集，也不需要付费调用。
git clone https://github.com/SmartMobileHouse/fraud-decision-lab
cd fraud-decision-lab
uv sync --frozen # install pinned dependencies (Python 3.12)
uv run fraudlab doctor # check your setup; prints no secrets
用一条命令查看它运行（约 5 秒，离线）：
make demo # rules + XGBoost on the bundled synthetic data -> outputs/demo-report.html
或者仅使用 Docker / Podman：
make docker
container=$(docker create --network none fraud-decision-lab demo)
docker start --attach "$container"
mkdir -p outputs
docker cp "$container:/app/outputs/." outputs/
docker rm "$container"
报告保存到 outputs/demo-report.html。复制输出可在 Docker 和 Podman VM 中使用，而无需共享宿主机项目目录。绑定挂载要求引擎能够访问宿主机路径，并且容器用户可以写入该路径；外部驱动器不会自动与每个 VM 共享。
然后在捆绑的合成数据上运行离线基准并构建报告：
uv run fraudlab run -d configs/datasets/synthetic.yaml --providers rules,xgboost
uv run fraudlab report --run-id <run_id printed above> --out outputs/report.html
实时提供方需要 API 密钥、--allow-external-requests 和 --max-cost-usd 支出估算；参见 uv run fraudlab run --help。该估算不是提供方强制执行的计费上限：token 化、重试和不确定的计费都可能导致差异。也要使用提供方侧可用的支出控制。
配置
AI 决策 API 与 XGBoost 在欺诈分诊中的开放基准测试
实际运行提供方时，会从本地 .env 文件（已被 gitignore）读取凭据。复制模板，只填写你想运行的提供方：
cp .env.example .env && chmod 600 .env
| 变量 | 提供方 |
|---|---|
| TYPESAFE_API_KEY | TypeSafe Jev |
| OPENAI_API_KEY | OpenAI Decisions 和结构化输出 LLM |
| CLOUDFLARE_ACCOUNT_ID , CLOUDFLARE_API_TOKEN | Cloudflare Clef / Clef-flash（Workers AI Read + Edit） |
参考适配器请求 jev-1.14.0、gpt-6-luna（Decisions 和 LLM）、@cf/cloudflare/clef 和 @cf/cloudflare/clef-flash。报告的标识符不会冻结提供方的服务器实现；OpenAI 和 Cloudflare 的标识符不是不可变的执行快照。结构化输出 LLM 使用 reasoning effort none、64 token 输出限制和严格 JSON score。未显式发送的采样参数是由提供方控制的默认值。欺诈问题位于 configs/questions-v1.json；src/fraudlab/providers/ 中的适配器定义了请求特定的封装器。
只捆绑项目原始合成数据。请自行将第三方数据集下载到 data/external/（见 DATA_LICENSES.md）；fraudlab doctor 会显示它发现的内容。
IEEE-CIS Fraud Detection
此仓库包含对 IEEE-CIS Fraud Detection 数据集的可选支持。
该数据集不随本项目分发。用户必须自行从 Kaggle 获取，并遵守原始竞赛规则，包括对商业使用的限制。
基准测试实现与数据集分开提供。
随附的 IEEE-CIS 配置仅限本地（external_processing_allowed: false）。发布被单独禁用（publication_allowed: false）：这包括聚合结果、图表、缓存输出和报告，均待独立权利审查。API 处理许可不是发布许可。随附的 ULB 配置允许在 ODbL/DbCL 许可证下并注明出处发布聚合结果（见 DATA_LICENSES.md）。不要仅仅为了绕过报告拒绝而启用发布。
开发
uv sync --frozen
make check # ruff, mypy, pytest (offline), license check, gitleaks secret scan
make format # auto-fix lint and formatting
make docker # build the offline image
make help # list all targets
没有托管 CI：每次推送前运行 make check。测试绝不能访问网络；调用真实付费 API 的测试被标记为 live，并且默认从不运行。见 CONTRIBUTING.md。
结果
当前源码分发不包含任何基准测试结果文件。较旧的 Git 历史包含结果文本和截图，因此改变原始私有仓库的可见性并不是仅源码发布。见 RELEASE.md 以获取不包含该历史、可供审查的源码快照。
运行 make demo 以获得合成离线示例。fraudlab report 和 fraudlab export-report-data 需要已获准发布的数据集；它们不作出法律认定。未获准数据集的结果仍为本地运行产物。仅源码发布不提供对历史付费实验的公开 Level 3 验证。保留的研究主张需要单独审查的预测证据和出处。
注意事项与限制
- 零样本 vs 有监督。XGBoost 从带标签的历史中学习；AI 模型对每笔交易都是冷启动。这是有意为之，报告也如此说明。
- 数据集真实性。合成历史字段和标签是生成的信号，不是观测到的卡片历史或经验证的银行结果。ULB 的匿名化组件限制了零样本模型的语义解释。重复的特征向量可能跨越按时间顺序的划分；仅相同向量本身不能证明重复交易。未声称进行实体无关评估。
AI 决策 API 与 XGBoost 用于欺诈分诊的开放基准测试
- 不确定性。置信区间在固定类别计数的条件下对交易进行重采样。它们以已保存的预测为条件，并忽略客户/日期聚类、提供商重跑变异性和未来分布漂移。单次保存的运行无法建立稳定、通用的供应商排名。
- 不是生产级欺诈系统。欺诈分数不是校准后的概率，也不是阻止卡片或账户的决定。分析师必须审查案例；假阳性和假阴性带来不同的运营成本。
- 数据权利归你所有。MIT 仅覆盖本项目的代码及其合成数据，绝不覆盖第三方数据集。某些数据集（例如 IEEE-CIS）不得发送到外部 API；实验室通过配置阻止这种做法。
- 隐私与被操纵的输入。获批的实时运行会将配置字段传输给提供商。在发送真实记录前，确认数据权利、保留条款和隐私控制。交易文本可能包含提示注入；针对对抗性输入的鲁棒性尚未得到证明。模型不执行金融操作。运行日志支持研究检查，不用于监管认证或完整的生产审计轨迹。
- 提供商会变化。模型、价格和 API 会变动；每个结果都与其运行日期和清单绑定。
- 可复现性。fraudlab replay 会根据已保存的标签和预测检查受支持的已保存运行指标。它不会认证提供商的执行、核实发票，或恢复缺失的历史负载测试调用。旧版运行可能具有不完整的来源信息，不能安全地作为新实验恢复。重新训练 XGBoost 在另一个操作系统或 CPU 上可能得到略有不同的数字；每次运行都会记录其平台。
- 平台与设置。固定版本的项目面向 macOS 和 Linux 上的 Python 3.12。依赖安装和 Docker 构建除非已缓存，否则需要下载。镜像标签和系统软件包仓库是可变的；Dockerfile 不是逐位冻结的镜像配方。
- 本项目是独立项目，与 TypeSafe、OpenAI、Cloudflare、Kaggle 或数据集所有者无关联，也未获其认可。
许可证
MIT © Smart Mobile House
Smart Mobile House 名称是 Smart Mobile House 的商标，且不依 MIT 许可授权。生成的报告仍受数据集、提供商及其他适用权利约束；代码许可证不授予发布许可。