从数据采集、特征工程到机器学习预测 + LLM 深度分析，完整的数据闭环。正值2026世界杯激战正酣，这套系统也许能给你带来不一样的看球视角。
2026年美加墨世界杯正在火热进行中，全世界的目光都聚焦在绿茵场上。作为一名技术爱好者，我一直在思考：能否用数据和模型去“理解”足球比赛的走势？经过一段时间的摸索，我把自己的成果整理开源了——一套足球比赛智能预测系统，它不依赖玄学，而是基于历史数据、机器学习和大语言模型，尝试给出可解释的比赛分析。
项目地址：github.com/ai7zym/ai-f… star 交流）
⚠️ 免责声明：本项目仅供技术研究和数据分析学习，不构成任何决策建议。预测结果存在不确定性，请理性看待。
一、这套系统能做什么？
简单说，这是一个从数据同步到模型预测再到LLM分析的完整后端系统：
· 自动从足球数据API拉取联赛、球队、球员、积分榜、赛程、实时比分等信息，存入MySQL
· 基于XGBoost模型预测胜平负、大小球和进球期望
· 使用泊松分布生成Top 3参考比分
· 调用DeepSeek大模型综合球队背景和模型输出，生成接近分析师风格的文字报告
· 提供REST API和命令行工具，方便接入前端、机器人或自动化脚本
· 支持赛后复盘回填，用于统计模型命中情况
目前基于已有数据的测试中，胜负方向的预测准确率约80%，比分方向的准确率约60%（数据截至2026年6月15日，含世界杯小组赛已完赛数据，仅限学术统计）。
二、为什么选在现在开源？
2026年世界杯是一个绝佳的试验场。本届世界杯小组赛阶段已经进行了大量比赛，这套系统恰好完成了全部小组赛的数据整理和模型回测。你可以直接用项目提供的SQL数据快速启动，然后针对剩余淘汰赛进行预测分析，或者复盘已经结束的比赛——看看模型“猜”对了哪些冷门，又在哪些强强对话中失手。这是一次将数据科学应用于真实大型赛事的完整实践。
三、技术栈
层级 技术
后端框架 FastAPI + Uvicorn
数据库 MySQL + SQLAlchemy + Alembic
机器学习 XGBoost, scikit-learn, pandas, numpy
比分建模 泊松分布 (Poisson)
大模型 DeepSeek API
任务调度 内置调度器 + 手动触发
日志 Loguru
命令行 Typer + Rich
整个项目采用模块化设计，后端服务、预测逻辑、模型训练、同步工具分离，便于按需使用和二次开发。
四、核心设计思路
- 完整的数据闭环
从上游API拉取原始数据 → 存入MySQL → 特征工程生成特征 → 模型训练 → 在线预测 → 赛后回填命中结果。每一场比赛的数据流转清晰可追溯。
- 多模型组合
· XGBoost：输出胜平负概率、大小球概率、主客队预期进球数
· 泊松分布：基于预期进球生成比分概率分布，提取Top 3比分
· DeepSeek LLM：接收模型输出的概率、球队近期状态、联赛背景等信息，生成连贯的分析文本，让预测结果更具解释性
- 模型回退机制
优先使用联赛专属模型（如英超单独训练），若不存在则回退到赛事组模型（如世界杯），最后回退到全局模型。保证覆盖尽可能多的比赛。
- 调度与自动化
支持定时同步赛程、积分榜、球员数据，也支持手动触发单次同步。自动预测任务会按配置扫描未预测的比赛并生成结果，完赛后自动回填命中情况。
五、快速上手指南
方式一：直接使用已提供的SQL数据（推荐）
如果你想快速体验预测功能，可以获取截止到2026年6月15日的完整数据库SQL导出文件（包含世界杯小组赛所有数据，体积较大，未放入GitHub，可联系作者获取）。
git clone https://github.com/ai7zym/api-football.git
cd api-football/backend
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # Linux/Mac
# 或 .venv\Scripts\activate (Windows)
# 安装依赖
pip install -r requirements.txt
# 创建数据库并导入SQL
mysql -u root -p -e "CREATE DATABASE football CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql -u root -p football < dump-football-api-202606151047.sql
# 配置环境变量
cp .env.example .env
# 编辑 .env 填入数据库密码、API Key等
# 启动服务
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
启动后访问 http://127.0.0.1:8000/docs 查看自动生成的API文档。
方式二：从零开始初始化数据
如果没有现成SQL，可以先执行数据库迁移，然后按顺序触发同步接口：
cd backend
alembic upgrade head
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
依次调用：
curl -X POST http://127.0.0.1:8000/api/scheduler/leagues/sync
curl -X POST http://127.0.0.1:8000/api/scheduler/teams/sync
curl -X POST http://127.0.0.1:8000/api/scheduler/fixtures/sync
# ... 其他同步任务
注意：你需要申请API-Football的访问权限，并在.env中配置API_FOOTBALL_KEY。
六、API使用示例
查询指定日期的比赛列表
curl "http://127.0.0.1:8000/api/fixtures?date=2026-06-13&page=1&page_size=20"
触发单场比赛预测
curl -X POST http://127.0.0.1:8000/api/predict/123456
返回结果包含四个主要部分：
字段 说明
basic 比赛基本信息（球队、联赛、时间、状态）
xgb 模型输出：胜平负概率、大小球概率、预期进球、Top3比分
llm 大模型分析：胜负推荐、比分推荐、让球推荐、深度文本分析
result 完赛后回填的真实比分和命中情况
批量查询预测结果
curl "http://127.0.0.1:8000/api/predictions?date=2026-06-13&category=worldcup&page=1&page_size=20"
支持按日期、联赛、比赛分类筛选。
七、命令行工具
除了API，项目还提供了几个实用的CLI工具：
命令 功能
python tools/manual_predict.py 交互式手动预测，适合调试单场比赛
python tools/batch_predict.py 批量预测，可指定日期范围
python prediction/train.py 重新训练模型（需自行准备特征数据）
python prediction/features.py 生成特征宽表
这些工具都使用Rich库美化了输出，在终端里运行体验很好。
八、项目结构解读
api-football/
├── backend/
│ ├── main.py # FastAPI入口
│ ├── requirements.txt
│ ├── .env.example
│ ├── app/
│ │ ├── api/ # REST API路由
│ │ ├── core/ # 配置、日志
│ │ ├── db/ # 数据库会话
│ │ ├── models/ # ORM模型
│ │ ├── schemas/ # 请求/响应结构
│ │ └── services/ # 同步、调度、预测核心服务
│ ├── prediction/ # 模型与预测逻辑
│ │ ├── models/ # 已训练的模型文件
│ │ ├── features.py
│ │ ├── predict.py
│ │ └── train.py
│ └── tools/ # 命令行辅助工具
├── .gitignore
└── README.md
如果你想修改特征工程、替换模型或调整调度策略，都可以在对应模块中找到清晰的入口。
九、效果示例：预测2026世界杯某场小组赛
假设我们调用预测接口分析一场世界杯小组赛（例如：阿根廷 vs 尼日利亚），模型返回的结果大致如下（示例）：
XGBoost输出：
主胜概率52%，平局25%，客胜23%
大小球倾向：小球（≤2.5球）概率68%
预期进球：主队1.8，客队0.9
泊松分布Top 3比分：
2-0（12.3%），1-0（11.5%），2-1（9.8%）
DeepSeek分析（摘要）：
“阿根廷队在中前场控制力上占据明显优势，近期梅西状态火热；尼日利亚防守反击有一定威胁但整体实力存在差距。模型预期阿根廷净胜1-2球，推荐方向：主胜。”
实际比赛结束后，系统可以通过赛后回填接口自动记录真实比分与预测的命中情况，用于后续分析和模型调优。
十、已知局限与后续计划
当前局限
· 模型依赖上游数据API的稳定性和完整性
· 特征工程主要基于近期状态、主客场表现、积分榜、历史交锋等，未引入球员身价、伤病、天气等细粒度数据
· 泊松分布假设进球之间相互独立，与实际比赛有一定偏差
· LLM分析会增加响应时间，且需要有效的API Key
后续计划
· 支持更多联赛（尤其是世界杯参赛队所在联赛）的专属模型训练
· 引入实时数据作为特征（仅用于学术研究）
· 优化特征缓存，减少重复计算
· 提供Docker Compose一键启动方案
· 增加模型版本管理和A/B测试能力
十一、常见问题
Q：预测失败返回400？
A：请检查对应比赛是否有完整的数据（球队、积分榜、近期战绩），以及联赛是否处于启用状态。可以查看日志定位具体缺失的特征。
Q：LLM分析不生效？
A：确认.env中配置了DEEPSEEK_API_KEY和正确的DEEPSEEK_BASE_URL，并且网络可以访问该API。
Q：为什么GitHub上没有SQL文件？
A：原始SQL导出文件体积较大（数百MB），不适合直接放入Git仓库。需要完整数据的可以联系作者获取，后续也会在Release中提供压缩包。
Q：可以用于商业项目吗？
A：目前仓库未声明具体开源许可证，建议商用前先与作者沟通确认授权方式。
写在最后
2026世界杯正在上演无数精彩瞬间，而数据的魅力在于它能让我们从另一个维度理解比赛。这个项目是我在学习数据工程和机器学习过程中的一个综合性实践——从API数据同步、数据库设计、特征构建到模型训练、LLM集成，涵盖了后端开发的多个方面。
如果你也在做类似方向的项目，或者想基于真实的世界杯数据练手，欢迎star、fork或提出改进建议。希望这个项目能为你提供一些参考。
GitHub地址： github.com/ai7zym/api-…
数据截止时间： 2026年6月15日（世界杯小组赛全部数据已整理完毕）
再次强调：本项目仅限技术研究与学习，请勿用于任何违反法律法规的用途。预测结果仅供参考，风险自负。
如果这篇文章对你有帮助，欢迎点赞、收藏、转发，让更多技术同好看到这个项目。我会持续维护和更新，也期待你的反馈和贡献！
