memily0/fraud-detection-ml-system

# ML 欺诈检测系统 Проект end-to-end ML/backend для оценки вероятности мошеннической транзакции. Репroducible проект по обнаружению мошенничества с pipeline обучения, общей инженерией признаков для обучения и инференса, FastAPI API, демо дашбордом и настройкой Docker для локального запуска. ## 概述 | Пункт | Детали | | --- | --- | | Задача | Бинарная классификация для обнаружения мошенничества | | Набор данных | `data/creditcard.csv` | | Модель | `RandomForestClassifier` | | API | FastAPI (`/predict`, `/health`) | | Дашборд | Статический веб-интерфейс на `/dashboard/` | | Docker | `Dockerfile` + `docker-compose.yml` | Финальная serving-модель: `RandomForestClassifier`, выбранная через поэтапное сравнение моделей с базовым single-split, стратифицированной кросс-валидацией и настройкой порогов. **Финальная serving-модель:** `RandomForestClassifier`, выбранная через поэтапное сравнение моделей. ## 技术栈 - Python - pandas - NumPy - scikit-learn - CatBoost - joblib - FastAPI - Pydantic - Uvicorn - Docker ## 项目组件 ## 项目组件 / 项目包含内容 - воспроизводимый pipeline обучения из `data/creditcard.csv` (воспроизводимый pipeline обучения) - общая инженерия признаков для обучения и инференса (единая логика признаков для train и inference) - serving-модель RandomForest для скоринга мошенничества (основная модель для скоринга fraud) - CatBoost сохранён как базовый кандидат для сравнения моделей (CatBoost сохранён как сильный baseline-кандидат) - оценка на стратифицированной выборке test - сервис FastAPI для предсказаний - простой дашборд для ручных проверок инференса - настройка Docker для локального демо-запуска ## 指标 Основные метрики текущей serving-модели на тестовой выборке: **Ниже — основные метрики текущей serving-модели на test split.** | Метрика | Значение | | --- | ---: | | PR-AUC | 0.876845 | | ROC-AUC | 0.967647 | | F2 | 0.788913 | | Precision | 0.961039 | | Recall | 0.755102 | | Порог | 0.50 | Это метрики по умолчанию при `threshold = 0.5` из основного train/test pipeline. Настроенный рабочий порог для финальной `RandomForestClassifier` указан отдельно в разделе **Выбор модели** и в настоящее время равен `0.2`. Почему эти метрики важны / Почему эти метрики важны: - `PR-AUC` более информативен, чем accuracy для этого набора данных из-за сильного дисбаланса классов. (`PR-AUC` важнее accuracy из-за сильного дисбаланса классов.) - `Recall` важен, потому что пропуск мошеннических транзакций обходится дорого. (`Recall` важен, потому что пропуск fraud-операции дорогой.) - `F2` дает больший вес recall, что лучше подходит для задачи обнаружения мошенничества, чем симметричная метрика. (`F2` сильнее акцентирует recall.) ## 快速启动 Минимальный локальный流程: ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt python scripts/train_model.py uvicorn app.main:app --reload ``` После запуска: - Дашборд: `http://localhost:8000/dashboard/` - Проверка здоровья: `http://localhost:8000/health` - Документация API: `http://localhost:8000/docs` ## 任务上下文 Проект рассматривает обнаружение мошенничества как задачу бинарной классификации: для каждой транзакции модель предсказывает вероятность того, что она принадлежит классу мошенничества. Набор данных содержит: - `Time` - `Amount` - `V1` ... `V28` - `Class` как целевая метка Почему задача нетривиальна: - набор данных сильно несбалансирован, мошеннические транзакции составляют очень малую долю; - API работает с преобразованным пространством признаков из набора данных, а не с исходными бизнес-полями транзакций; - из-за дисбаланса высокая accuracy не обязательно означает, что модель полезна. ## ML 流水线 Текущий pipeline: 1. Загрузка данных из `data/creditcard.csv` 2. Построение финального набора признаков 3. Разделение данных на train/test с использованием стратификации 4. Обучение `RandomForestClassifier` 5. Оценка на тестовой выборке 6. Сохранение обученной модели в `models/random_forest_fraud_model.joblib` 7. Загрузка сохранённой модели в FastAPI и использование в `/predict` Серверный артефакт — это сериализованный sklearn `Pipeline`. Он включает как обученный `RandomForestClassifier`, так и предварительную обработку, необходимую для инференса, включая one-hot кодирование для `time_bin`. Текущие параметры модели: - `n_estimators=200` - `class_weight='balanced'` - `n_jobs=-1` - `random_state=42` ## 模型选择 / 最终模型如何选择 Этот проект использует подход, основанный на процессе, для выбора модели. **Выбор модели здесь сделан как отдельный осознанный процесс, а не как разовое решение по одному запуску.** Выбор модели в этом проекте был выполнен поэтапно, а не интуитивно. 1. Был использован **базовый single-split benchmark** в качестве быстрого предварительного базового сравнения. 2. Основным процедурным методом выбора модели стал **стратифицированный кросс-валидационный benchmark**. 3. В качестве основного метода выбора модели использовался `mean PR-AUC` по фолдам CV, так как класс мошенничества сильно несбалансирован. 4. После предварительного отбора кандидатов была выполнена **настройка порогов** отдельно на валидационной выборке с использованием `F2`. 5. На основе этого процесса была выбрана `RandomForestClassifier` в качестве финальной serving-модели. Сводка выбора модели / Кратко: - single-split benchmark сохранён как быстрый baseline для сравнения; - CV benchmark является основным источником выбора модели; - `CatBoostClassifier` остаётся в репозитории как сильный кандидат но не как финальная serving-модель. - single-split benchmark сохранён как быстрый baseline; - CV benchmark используется как основной этап выбора модели; - `CatBoostClassifier` остался в проекте как сильный кандидат, но не как финальная serving-модель. Сводка кросс-валидационного benchmark: | Модель | mean PR-AUC | std PR-AUC | mean ROC-AUC | std ROC-AUC | | --- | ---: | ---: | ---: | ---: | | RandomForestClassifier | 0.855822 | 0.024644 | 0.954049 | 0.010747 | | CatBoostClassifier | 0.811840 | 0.038346 | 0.981338 | 0.001592 | | LogisticRegression | 0.760740 | 0.014065 | 0.977431 | 0.007064 | Настройка порогов для shortlisted моделей: | Модель | Порог | Precision | Recall | F2 | | --- | ---: | ---: | ---: | ---: | | RandomForestClassifier | 0.2 | 0.924731 | 0.877551 | 0.886598 | | CatBoostClassifier | 0.9 | 0.833333 | 0.867347 | 0.860324 | Этот анализ порогов намеренно отделён от выбора модели: - выбор модели основывается на кросс-валидационном `mean PR-AUC`; - выбор рабочего порога основывается на `F2` для shortlisted моделей на отдельной валидационной выборке; - для финальной serving-модели настроенный рабочий порог равен `0.2`, в то время как основные метрики обучения выше всё ещё reported при умолчательном `0.5`. ## 特征工程 / 特征构建 Модель использует 33 признака. Базовые признаки: - `Time` - `Amount` - `V1` ... `V28` Производные признаки: - `hour` — извлечён из `Time` для захвата паттернов времени суток - `log_amount` — `log1p(Amount)` для уменьшения влияния длиннохвостого распределения суммы - `time_bin` — категориальный временной интервал: `night`, `morning`, `afternoon`, `evening` Важный момент / Важный момент: - та же самая логика инженерии признаков используется как для обучения, так и для инференса, поэтому нет несоответствия train/inference. - одна и та же логика признаков используется и при обучении, и при инференсе, поэтому нет train/inference mismatch. ## API ### `GET /` Перенаправление на дашборд: - `http://localhost:8000/` -> `http://localhost:8000/dashboard/` ### `GET /health` Возвращает статус сервиса: ``` { "status": "ok" } ``` ### `POST /predict` Принимает одну транзакцию в формате признаков набора данных и возвращает вероятность мошенничества. Пример ответа: ``` { "fraud_proba": 0.39 } ```

Пример тела запроса

``` { "Time": 0.0, "Amount": 149.62, "V1": -1.3598071336738, "V2": -0.0727811733098497, "V3": 2.53634673796914, "V4": 1.37815522427443, "V5": -0.338320769942518, "V6": 0.462387777762292, "V7": 0.239598554061257, "V8": 0.0986979012610507, "V9": 0.363786969611213, "V10": 0.0907941719789316, "V11": -0.551599533260813, "V12": -0.617800855762348, "V13": -0.991389847235408, "V14": -0.311169353699879, "V15": 1.46817697209427, "V16": -0.470400525259478, "V17": 0.207971241929242, "V18": 0.0257905801985591, "V19": 0.403992960255733, "V20": 0.251412098239705, "V21": -0.018306777944153, "V22": 0.277837575558899, "V23": -0.110473910188767, "V24": 0.0669280749146731, "V25": 0.128539358273528, "V26": -0.189114843888824, "V27": 0.133558376740387, "V28": -0.0210530534538215 } ```

Примечания: - API ожидает ту же схему признаков, что и набор данных; - это полезно для демонстрации ML pipeline, но не является реальным публичным интерфейсом для сервиса antifraud в продакшене. ## 仪表板 В репозитории включён простой веб-интерфейс на `/dashboard/`. Он позволяет: - вручную вводить признаки транзакции; - загружать пример транзакции; - отправлять запрос в `/predict`; - просматривать возвращаемую вероятность мошенничества в лёгком интерфейсе. Этот дашборд предназначен для демонстрации и ручной проверки инференса, а не для аналитики или операционной работы. ## 项目结构 ``` fraud-detection-ml-system/ ├── README.md ├── Dockerfile ├── docker-compose.yml ├── requirements.txt ├── app/ │ ├── main.py │ └── utils.py ├── dashboard/ │ ├── index.html │ ├── app.js │ └── styles.css ├── data/ │ └── creditcard.csv ├── models/ │ ├── catboost_fraud_model.cbm │ └── random_forest_fraud_model.joblib ├── scripts/ │ ├── compare_models.py │ ├── compare_models_cv.py │ └── train_model.py └── src/ ├── features/ │ └── fraud_features.py ├── inference/ │ └── predict.py ├── models/ │ └── model_utils.py ├── training/ │ ├── compare_models.py │ ├── compare_models_cv.py │ └── train.py └── utils/ └── metrics.py ``` Ключевые файлы: - `src/features/fraud_features.py` — совместная инженерия признаков - `src/training/train.py` — обучение, разделение, оценка, сохранение модели - `src/training/compare_models.py` — базовый benchmark single-split - `src/training/compare_models_cv.py` — выбор модели на основе кросс-валидации и настройка порогов - `scripts/train_model.py` — CLI для запуска обучения модели - `app/main.py` — FastAPI приложение и эндпоинты - `models/random_forest_fraud_model.joblib` — основной артефакт serving как сериализованный sklearn pipeline - `models/catboost_fraud_model.cbm` — сохранённый базовый кандидат ## 本地运行 1. Создайте и активируйте виртуальное окружение: ``` python3 -m venv .venv source .venv/bin/activate ``` 2. Установите зависимости: ``` pip install -r requirements.txt ``` 3. Убедитесь, что набор данных доступен по пути `data/creditcard.csv` 4. Обучите модель: ``` python scripts/train_model.py ``` Необязательные аргументы: ``` python scripts/train_model.py \ --data-path data/creditcard.csv \ --model-path models/random_forest_fraud_model.joblib \ --test-size 0.2 \ --random-state 42 \ --threshold 0.5 ``` 5. Запустите API: ``` uvicorn app.main:app --reload ``` ## 使用 Docker 运行 Перед использованием Docker модель должна уже существовать в `models/random_forest_fraud_model.joblib`, так как контейнер запускает API с готовым артефактом модели. Сборка и запуск: ``` docker compose up --build ``` После запуска: - `http://localhost:8000/dashboard/` - `http://localhost:8000/health` - `http://localhost:8000/docs` Текущие ограничения Docker: - эта настройка предназначена для локального демо-использования и всё равно копирует в контейнер и `models/`, и `data/`; ## 限制 / 限制 - это учебный / демонстрационный проект, а не развертывание в продакшене; - API ожидает признаки набора данных в стиле PCA `V1` ... `V28`, а не исходные поля транзакций; - основные метрики обучения всё ещё reported на основе одного стратифицированного train/test split; - проект включает кросс-валидационный benchmark и настройку порогов, но не повторяющуюся кросс-валидацию, вложенную валидацию или поиск гиперпараметров; - нет отслеживания экспериментов; - пока нет автоматических тестов для pipeline обучения или API; - нет production-логирования, мониторинга или настройки развёртывания; - дашборд намеренно лёгкий и не является полным аналитическим инструментом; - выбор модели более надёжен, чем раньше, но всё ещё не подкреплён полноценным рабоч процессом управления экспериментами. ## 未来改进 - настройка порогов на основе бизнес-взвешивания; - тесты для инженерии признаков, обучения и `/predict` - конфигурация/настройки для параметров модели и pipeline - базовое логирование API и отчёты об ошибках - более богатые объяснения в дашборде - сохранённый отчёт о метриках и краткая карточка модели ## 项目展示的技能 / 项目表明了什么 - табличный ML для несбалансированной классификации - воспроизводимый pipeline обучения - осознанный выбор модели через benchmark + CV + настройка порогов - совместная инженерия признаков для обучения и инференса - сервис FastAPI для инференса модели - упаковка проекта в Docker - представление ML-проекта end-to-end для портфолио и собеседований - работа с табличными данными и сильным дисбалансом классов - воспроизводимый pipeline обучения - осознанный выбор модели через benchmark + CV + threshold tuning - согласование train и inference - ML-serving через FastAPI - упаковка проекта в Docker

标签：Apex, AV绕过, CatBoost, Docker, docker-compose, FastAPI, joblib, NumPy, pandas, Python, scikit-learn, Uvicorn, Web API, 二分类, 交叉验证, 信用评分卡, 健康检查, 分层抽样, 反欺诈系统, 可复现管道, 安全监控, 安全防御评估, 无后门, 本地演示, 机器学习, 模型比较, 模型选择, 欺诈检测, 特征工程, 生产部署, 端到端, 请求拦截, 逆向工具, 金融风控, 阈值调优, 静态仪表盘, 预测接口