mma-prediction

MMA Fight Prediction 是一个 Python 研究与服务项目，用于预测 UFC 比赛的胜者、获胜方式和结束回合。它结合了 Elo 评分系统、梯度提升（XGBoost）集成、多任务神经网络集成，以及两者等权重融合的部署评分器。每个候选模型都通过 2018-2026 年的扩展窗口前向走步（walk-forward）评估进行评判，胜出的评分器在融合平均后，使用在预留数据上拟合的温度（temperature）进行校准。 可复现的流水线 快速启动会创建一个虚拟环境，安装带有开发扩展（dev extras）的包，然后依次运行四个脚本：download_data.py（将 Kaggle UFC 数据集下载到 data/raw/ 中）、make_dataset.py（将清洗后的 parquet 放入 data/processed/ 中）、build_ratings.py（调整并构建 Elo 评分），最后运行 pytest。Streamlit 应用（streamlit run app.py）允许用户选择任意两名选手，并返回带有不确定性的获胜概率、获胜方式和结束回合倾向，以及主要贡献因素的分解。该项目记录的一个目标是实现整个流水线逐字节（byte-for-byte）的可复现性。 特征工程与泄漏控制 特征由 src/mma/feature_blocks.py 中的命名块（base、external、trajectory、notice、context、opponent_adjusted）组装而成，生成一个大约包含 1.1 万场比赛和 87 列的表格。特征是在按时间顺序的累加器中构建的，因此每个值都严格属于赛前数据，并使用截断不变性（truncation-invariance）测试来检查是否没有任何特征能够“预见未来”。这些特征块根据预先注册的准确率标准进行衡量：其中一个（external，涵盖 UFC 之前的职业生涯数据）独自通过了该标准，而其他特征块要么仅作为融合评分表格的一部分发布，要么根本不发布。该项目记录了在每个角落（per-corner）缺失标记中发现的选择泄漏（selection leak），该泄漏已从两个模型矩阵中移除，但保留在用于评估切片的表格中。为了防止泄漏，有几列被明确排除在模型输入之外，并且一个来源边车（provenance sidecar）文件记录了每一行是来自主要来源还是次要来源。 数据源 记录是通过合并一个维护中的 Kaggle 镜像（主要且经过对账的数据源）和 Greco1899/scrape_ufc_stats CSV 发布版（严格用作数据，通过 HTTPS 获取，不包含任何受 GPL 许可的代码）而组装的。对于重合的比赛，以主要数据源的行优先；合并以两个数据源之间的胜者一致性为门槛，并且是容错（fail-soft）的，在不一致时会降级为仅使用主要数据源的构建并发出警告。该仓库报告了围绕此合并的来源、完整性检查和回归防护。 自动更新与前瞻性评估 每周一次的 GitHub Action 会刷新数据集并重新构建产物，然后自动提交它们。未来的 UFC 赛事会在发生前进行预测并提交到 git，并在事后进行评分，从而提供前瞻性的业绩记录，而非仅有回顾性的报告。针对被拒绝特征块的测试框架报告和预先注册的实验决策文件会提交在 models/walkforward/ 下，以便保留负面结果。 该项目使用 Python (3.10+) 编写，并在 MIT 许可证下发布。设计和阶段计划文档位于 docs/ 下。