Harmon/vinbigdata-cxr-kaggle-pipeline

Fork 0

Files

T

Harmon ccb5b45666 feat: add VinBigData CXR Kaggle pipeline notebooks

2026-04-27 08:38:33 +08:00

14 KiB

Raw Permalink Blame History

VinBigData 项目说明

1. 文档目的

本文档用于说明本仓库中 VinBigData Chest X-ray Abnormalities Detection Kaggle 比赛项目的目标、组成、运行链路和复现注意事项。

该仓库本质上是一个 以 Kaggle Notebook 为中心的比赛归档项目，重点在于提交策略验证，而不是可直接安装和运行的标准工程包。因此，本文档的定位是：

说明项目主线与各 notebook 的职责
记录关键输入、输出和依赖关系
为后续回看、迁移或局部复现提供导航

2. 项目概述

2.1 比赛任务

比赛输入为胸部 X-ray 影像，输出为 Kaggle 要求的 PredictionString，每 6 个值表示一条预测：

class_id score x_min y_min x_max y_max

其中：

0 到 13 表示 14 类胸片异常
14 表示 No finding

因此，该任务不仅是目标检测任务，还包含明显的图像级正常/异常判别需求。仓库中的方案围绕这一点构建，核心并非单一模型，而是以下组合：

14 类异常检测
normal / abnormal 二分类
No finding 的规则化后处理
多个 submission 的结果级融合

2.2 仓库定位

从当前文件内容看，该项目的主要价值不在于“训练脚本工程化”，而在于保留一套完整的比赛思路：

检测模型负责输出异常框
二分类模型负责判断整图是否更接近正常
后处理阶段决定保留框、追加 class 14，或直接替换为 No finding
在此基础上尝试进一步 ensemble

3. 仓库文件说明

文件	作用	说明
`yolov5-chest-512.ipynb`	主流程 notebook	包含数据整理、fold 划分、YOLO 标签生成、检测推理、图像级分类辅助后处理
`vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb`	纯检测推理	使用训练好的 YOLOv5 权重生成检测结果并导出 `submission.csv`
`vinbigdata-2-class-classifier-complete-pipeline.ipynb`	二分类完整流程	训练 normal / abnormal 分类器，并导出 `valid_pred.csv`、`test_pred.csv`
`ensembling-approach.ipynb`	submission 级融合	对多个检测 submission 做启发式融合与平均
`ensemble-of-best-public-notebooks.ipynb`	轻量后处理	对已有 submission 再应用一次 2-class filter
`VINBIGDATA_REVIEW.md`	项目说明文档	当前文档

4. 方案架构

4.1 总体流程

该项目可以概括为以下流水线：

使用检测模型生成 14 类异常框
使用二分类模型估计图像为 normal 的概率
根据 normal 概率对检测结果做后处理
必要时对多个 submission 再进行融合

可简化表示为：

Detection -> 2-class probability -> Post-process No finding -> Ensemble

为了便于快速把握整体关系，下面补充三张结构图，分别对应总体流水线、各 notebook 职责，以及后处理决策逻辑。

总体流水线

flowchart LR
    A[官方比赛数据<br/>train.csv / test dicom] --> B[图像预处理数据集<br/>256 / 512 / 1024 PNG]
    B --> C[yolov5-chest-512.ipynb<br/>主检测流程]
    A --> C
    B --> D[vinbigdata-2-class-classifier-complete-pipeline.ipynb<br/>normal / abnormal 二分类]
    A --> D

    C --> E[14 类异常检测结果]
    D --> F[test_pred.csv / valid_pred.csv<br/>整图 normal 概率]

    E --> G[后处理逻辑<br/>Keep / Add / Replace]
    F --> G
    G --> H[submission.csv]

    H --> I[ensemble-of-best-public-notebooks.ipynb<br/>轻量 2-class 再过滤]
    F --> I
    I --> J[postprocessed submission.csv]

    H --> K[ensembling-approach.ipynb<br/>多 submission 融合]
    J --> K
    K --> L[final submission.csv]

Notebook 职责图

flowchart TD
    A[yolov5-chest-512.ipynb] --> A1[读取比赛数据]
    A --> A2[MultilabelStratifiedKFold 分 fold]
    A --> A3[生成 YOLO 标签]
    A --> A4[调用检测模型推理]
    A --> A5[结合整图分类做后处理]
    A --> A6[导出 submission.csv]

    B[vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb] --> B1[加载 best.pt]
    B --> B2[运行 detect.py]
    B --> B3[YOLO 坐标转回比赛格式]
    B --> B4[纯检测 baseline submission]

    C[vinbigdata-2-class-classifier-complete-pipeline.ipynb] --> C1[构造 normal / abnormal 标签]
    C --> C2[StratifiedKFold 训练]
    C --> C3[导出 valid_pred.csv]
    C --> C4[导出 test_pred.csv]
    C --> C5[按阈值修正检测 submission]

    D[ensemble-of-best-public-notebooks.ipynb] --> D1[读取已有 submission]
    D --> D2[读取 2-class 概率]
    D --> D3[Keep / Add / Replace]

    E[ensembling-approach.ipynb] --> E1[读取多个 submission]
    E --> E2[按图片拆分 PredictionString]
    E --> E3[top-n 保留]
    E --> E4[同类框平均融合]

后处理决策图

flowchart TD
    A[输入: 一张图的检测结果 + class0 概率] --> B{normal 概率阈值}
    B -->|p < low_threshold| C[Keep<br/>保留检测结果]
    B -->|low_threshold <= p < high_threshold| D[Add<br/>保留检测结果并追加 class 14]
    B -->|p >= high_threshold| E[Replace<br/>替换为 14 1 0 0 1 1]

4.2 检测主线

yolov5-chest-512.ipynb 是最接近“总控台”的 notebook。根据 notebook 中保留的代码，其主线包括：

读取官方比赛数据与预处理后的 PNG 数据
将原始标注缩放到训练尺寸
使用 MultilabelStratifiedKFold 划分 5-fold
生成 YOLO 训练目录及标签文件
以 512 尺度作为主要检测输入
调用 YOLOv5 detect.py 做推理
结合图像级分类结果生成最终 submission.csv

需要说明的是，该 notebook 中保留了部分历史实验痕迹，例如 EfficientDet / EfficientNet 相关配置、硬编码阈值和样本过滤列表。它更像比赛过程中的工作 notebook，而不是整理后的单一职责脚本。

4.3 二分类补偿分支

vinbigdata-2-class-classifier-complete-pipeline.ipynb 负责训练整图二分类器，用于回答“这张图是否正常”。

其主要配置和行为包括：

输入图像目录：vinbigdata-chest-xray-resized-png-256x256
默认 backbone：resnet18
5-fold StratifiedKFold
训练轮数：epoch=15
调度器：CosineAnnealingWarmRestarts
支持 mixup、label_smoothing、EMA
输出：
- valid_pred.csv
- test_pred.csv

该分支不负责检测框位置，只输出 normal / abnormal 概率，供后处理阶段使用。

4.4 后处理策略

当前仓库中的后处理逻辑高度一致，核心思想为：

若 normal 概率较低，则保留检测结果
若 normal 概率处于中间区间，则保留检测结果并追加 class 14
若 normal 概率较高，则直接替换为 14 1 0 0 1 1

在 vinbigdata-2-class-classifier-complete-pipeline.ipynb 中，保存下来的阈值示例为：

low_threshold = 0.0
high_threshold = 0.976

在 ensemble-of-best-public-notebooks.ipynb 中，轻量后处理版本使用：

low_threshold = 0.0
high_threshold = 0.90

这说明项目后期的主要增分手段之一，是利用二分类模型修正检测器在正常样本上的误报。

4.5 多模型融合

ensembling-approach.ipynb 不是模型层面的联合训练，而是 submission 级别 的结果融合。

它的做法是：

读取多个模型导出的 PredictionString
将每个 submission 拆分成按图像组织的预测字典
每个模型仅保留 top-n 预测，默认 n=3
找出相同类别的重复预测
对重复类别的分数和框坐标做平均
重新拼接为新的 submission.csv

该方法更接近启发式 averaging，而不是标准训练期融合。

5. 各 Notebook 的正式说明

5.1 `yolov5-chest-512.ipynb`

用途：

项目主流程梳理
训练前数据准备
YOLO 标签生成
检测结果读取与后处理
结合图像级分类器生成最终提交

关键实现：

split_df(...)
- 使用 MultilabelStratifiedKFold 做检测任务分层划分
Preprocess_wbf(...)
- 对训练标注做 WBF 风格整理
create_file(...)
- 生成 YOLO 所需目录结构和标签文件
Predict_process.fit(...)
- 读取 YOLO 检测结果
- 执行 NMS
- 调用 EfficientnetCus 进行整图分类
- 根据分类概率决定最终 PredictionString

说明：

notebook 中提供了 YOLOv5 训练命令示例，但训练命令本身是注释状态
检测推理阶段调用的是外部 best.pt
部分阈值和过滤列表属于比赛调参产物，保留了明显经验化特征

5.2 `vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb`

用途：

以最小流程生成纯检测提交

关键行为：

读取已训练好的 best.pt
调用 detect.py
使用 img=640、conf=0.15、iou=0.4
保存 txt 和置信度
将 YOLO 输出转换回比赛要求的原图坐标
对无检测框图像填充 14 1 0 0 1 1

适用场景：

快速恢复纯检测 baseline
对比二分类后处理前后的差异

5.3 `vinbigdata-2-class-classifier-complete-pipeline.ipynb`

用途：

训练二分类器
导出验证集和测试集概率
演示如何将 2-class 结果作用到检测 submission

关键行为：

数据标签定义为：
- 无异常标注 -> normal
- 有异常标注 -> abnormal
使用 StratifiedKFold 保持 normal / abnormal 比例
导出：
- valid_pred.csv
- test_pred.csv
支持最后一步 2-class filter 后处理

适用场景：

单独复现 normal / abnormal 分支
为现有检测 submission 追加后处理信号

5.4 `ensembling-approach.ipynb`

用途：

对多个已有 submission 做结果融合

关键行为：

按图像读取多个 PredictionString
对每个模型保留高置信度 top-n 结果
对重复类别做概率和框坐标平均
导出新的融合 submission

适用场景：

比较不同检测方案或不同公开 notebook 的互补性

5.5 `ensemble-of-best-public-notebooks.ipynb`

用途：

对已有 submission 快速再施加一层 2-class filter

关键行为：

读取检测 submission
读取 2-class 预测 csv
按阈值执行 Keep / Add / Replace
导出新的 submission.csv

适用场景：

不重新训练模型，只做最后一步规则修正

6. 输入、输出与依赖

6.1 运行环境

该项目基于 Kaggle Notebook 环境编写，当前仓库 不包含完整可离线执行的依赖清单和脚本封装。大部分 notebook 默认假设以下前提成立：

运行环境为 Kaggle
数据、模型权重和外部代码位于 ../input/...
图像已提前转换为 PNG 或已存在预处理版本

6.2 主要外部输入

从 notebook 中能确认的主要依赖包括：

官方比赛数据：
- vinbigdata-chest-xray-abnormalities-detection
预处理图像数据：
- vinbigdata-chest-xray-resized-png-256x256
- vinbigdata-chest-xray-resized-png-1024x1024
- vinbigdata-512-image-dataset 或同类 512 PNG 数据
测试元数据：
- vinbigdata-testmeta/test_meta.csv
2-class 预测结果：
- vinbigdata-2class-prediction/2-cls test pred.csv
- 或 vinbigdata2classpred/test_pred.csv
外部模型/代码：
- yolov5
- 已训练检测权重 best.pt
- 二分类模型权重

6.3 主要输出

Notebook	主要输出
`yolov5-chest-512.ipynb`	`submission.csv`，YOLO 标签目录
`vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb`	`submission.csv`
`vinbigdata-2-class-classifier-complete-pipeline.ipynb`	`valid_pred.csv`、`test_pred.csv`、后处理后的 `submission.csv`
`ensembling-approach.ipynb`	融合后的 `submission.csv`
`ensemble-of-best-public-notebooks.ipynb`	追加 2-class filter 后的 `submission.csv`

7. 推荐阅读顺序

7.1 理解项目主线

建议顺序：

VINBIGDATA_REVIEW.md
yolov5-chest-512.ipynb
vinbigdata-2-class-classifier-complete-pipeline.ipynb

目标：

先理解最终提交的构成方式
再理解检测和二分类分别提供什么信号

7.2 只恢复纯检测 baseline

建议优先阅读：

vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb
yolov5-chest-512.ipynb 中的检测后处理部分

7.3 只恢复后处理与提分思路

建议优先阅读：

vinbigdata-2-class-classifier-complete-pipeline.ipynb
ensemble-of-best-public-notebooks.ipynb
ensembling-approach.ipynb

8. 复现注意事项

8.1 本仓库不是完整的本地工程

当前仓库仅保留 notebook 与说明文档，没有：

独立的 requirements.txt
统一的训练入口脚本
完整的本地路径配置
明确的最终线上提交版本记录

因此，仓库更适合做以下用途：

回顾比赛策略
迁移部分 notebook 逻辑
抽取后处理与 ensemble 思路

不适合直接视为“一键复现实验”的标准工程。

8.2 路径和参数存在 Kaggle 绑定

多数 notebook 直接写死了 ../input/... 路径，说明原始运行环境依赖 Kaggle Dataset / Notebook Output。若迁移到本地，需要自行重建：

原始数据目录
预处理 PNG 目录
测试元数据
模型权重目录
YOLOv5 代码目录

8.3 存在比赛期经验化规则

项目中保留了较多比赛调参痕迹，例如：

list_remove
image_remove
类别特定阈值
No finding 的分段规则

这些逻辑对理解历史提交有价值，但不应直接视为可泛化的医学影像检测最佳实践。

8.4 最终最佳提交版本无法仅凭仓库唯一确认

从当前仓库可以清楚恢复整体方案，但无法仅凭现有文件 100% 唯一确认最终线上提交是哪一个 notebook 产物或哪个 ensemble 版本。原因包括：

缺少 leaderboard 版本记录
缺少 commit 级说明
仓库中同时保留了多条尝试路线

9. 结论

本项目的核心不是单一检测模型，而是一套围绕 VinBigData 比赛构建的提交工程：

用检测模型识别 14 类异常
用二分类模型判断 normal / abnormal
用后处理规则显式处理 No finding
视情况再对多个 submission 进行融合

如果只保留一个最值得回看的文件，应优先查看 yolov5-chest-512.ipynb；如果要理解本项目为什么能进一步提分，应重点查看 vinbigdata-2-class-classifier-complete-pipeline.ipynb 中的 2-class filter 流程。

14 KiB Raw Permalink Blame History Unescape Escape

VinBigData 项目说明

1. 文档目的

2. 项目概述

2.1 比赛任务

2.2 仓库定位

3. 仓库文件说明

4. 方案架构

4.1 总体流程

4.2 检测主线

4.3 二分类补偿分支

4.4 后处理策略

4.5 多模型融合

5. 各 Notebook 的正式说明

5.1 yolov5-chest-512.ipynb

5.2 vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb

5.3 vinbigdata-2-class-classifier-complete-pipeline.ipynb

5.4 ensembling-approach.ipynb

5.5 ensemble-of-best-public-notebooks.ipynb

6. 输入、输出与依赖

6.1 运行环境

6.2 主要外部输入

6.3 主要输出

7. 推荐阅读顺序

7.1 理解项目主线

7.2 只恢复纯检测 baseline

7.3 只恢复后处理与提分思路

8. 复现注意事项

8.1 本仓库不是完整的本地工程

8.2 路径和参数存在 Kaggle 绑定

8.3 存在比赛期经验化规则

8.4 最终最佳提交版本无法仅凭仓库唯一确认

9. 结论

14 KiB

Raw Permalink Blame History

5.1 `yolov5-chest-512.ipynb`

5.2 `vinbigdata-cxr-ad-yolov5-14-class-infer.ipynb`

5.3 `vinbigdata-2-class-classifier-complete-pipeline.ipynb`

5.4 `ensembling-approach.ipynb`

5.5 `ensemble-of-best-public-notebooks.ipynb`