luxury-lakehouse/football2vec-statsbomb-wyscout

Football2Vec v2嵌入向量数据集（基于StatsBomb和Wyscout数据）是一个包含足球运动员128维嵌入向量的数据集。这些嵌入向量由Football2Vec v2模型生成，该模型是一个带有对抗竞争去偏的Transformer编码器。数据集基于约3,000场StatsBomb和约1,900场Wyscout的公开比赛数据训练而成，每个唯一的规范球员对应一行数据，包括球员ID、姓名、嵌入向量、总比赛场次和数据来源。嵌入向量可用于球员相似性搜索、反事实替换分析和角色聚类等任务，但受限于公开数据、训练时间快照和位置无关性。数据集是（Right! Luxury!）Lakehouse足球分析平台的一部分，遵循CC-BY-NC 4.0许可。

---
语言：[英语]
许可证：CC-BY-NC 4.0
任务类别：
- 特征提取（feature-extraction）
标签：
- 体育分析（sports-analytics）
- 足球（soccer/football）
- 球员嵌入向量（player-embeddings）
- Transformer（transformer）
- Football2Vec（football2vec）
- StatsBomb（statsbomb）
- Wyscout（wyscout）
样本量范围：
- 1K<n<10K
配置项：
- 配置名称：default
数据文件：
- 拆分：训练集（train）
- 路径："data/*.parquet"
---

# Football2Vec v2 嵌入向量 —— StatsBomb 与 Wyscout 数据集

本数据集包含由[Football2Vec v2](https://huggingface.co/luxury-lakehouse/football2vec-v2)生成的单球员128维嵌入向量，该模型是一款带有对抗性竞赛去偏的Transformer编码器。模型训练数据包含约3000场StatsBomb公开赛事与约1900场Wyscout公开赛事；本数据集仅包含训练完成后输出的嵌入向量，每位唯一标准球员对应一行数据。

本数据集隶属于（Right! Luxury!）Lakehouse足球分析平台。

## 命名说明

本数据集命名为`football2vec-statsbomb-wyscout`，以兼容历史v1模型仓库的命名规范。v2模型权重存放于[`luxury-lakehouse/football2vec-v2`](https://huggingface.co/luxury-lakehouse/football2vec-v2)；已弃用的legacy v1模型存放于[`luxury-lakehouse/football2vec-statsbomb-wyscout`](https://huggingface.co/luxury-lakehouse/football2vec-statsbomb-wyscout)，仅保留用于可追溯性。本数据集的嵌入向量均来自v2模型，保留仓库名称是为了兼容过往基于该路径读取嵌入向量的下游使用者。

## 快速上手

python
from datasets import load_dataset
import numpy as np

ds = load_dataset("luxury-lakehouse/football2vec-statsbomb-wyscout")
df = ds["train"].to_pandas()
print(f"{len(df):,} 名球员，嵌入维度={len(df.loc[0, 'embedding'])}")

> **交互式探索：** [Hugging Face Spaces 演示](https://huggingface.co/spaces/luxury-lakehouse/soccer-analytics-demo)

## 数据 Schema

| 列名 | 数据类型 | 描述 |
|--------|------|-------------|
| `canonical_player_id` | `Int64` | 跨数据源对齐的标准球员唯一标识符 |
| `player_name` | `string` | 模型训练时记录的球员显示名称 |
| `embedding` | `list<float32>` | Football2Vec v2生成的128维向量 |
| `total_matches` | `Int64` | 该球员在两个数据源中登场的赛事总场次 |
| `data_sources` | `list<string>` | 该球员有登场记录的数据源（`statsbomb`、`wyscout`） |

## Schema 迁移 —— 双列过渡期（2026-04-25 → 2026-07-22）

Lakehouse Kimball迁移的PR 5b（ADR-011）为使用本模型生成嵌入向量的底层Lakehouse数据集市新增了BIGINT类型的代理键`player_key`。**本数据集的载荷内容在PR 5b中未做修改**——Parquet文件仍仅保留`canonical_player_id`字段。计划于2026-07-22发布的PR 8将以向后兼容的方式在数据载荷中新增`player_key`字段，并宣布`canonical_player_id`的弃用计划。

过渡期内推荐的使用者行为：
- **无需任何修改**：继续从本数据集读取`canonical_player_id`字段。
- 若您维护了自定义的`dim_players`克隆表，可提前预计算`player_key = xxhash64(provider || '|' || cast(player_id as string))`，以匹配Lakehouse Kimball规范，为后续的数据载荷变更做好准备。
- 2026-07-22之后，本数据集将至少在一个Hugging Face数据集版本中同时保留两个字段，随后`canonical_player_id`将被弃用。请在此过渡期内按需完成迁移。

若您依赖本数据集并需要在字段删除前获得额外通知，请在[Lakehouse仓库](https://github.com/karsten-s-nielsen/luxury-lakehouse)中提交Issue。

## 训练溯源

- **生产模型**：[`luxury-lakehouse/football2vec-v2`](https://huggingface.co/luxury-lakehouse/football2vec-v2)
- **训练语料**：[`luxury-lakehouse/football2vec-training-data`](https://huggingface.co/datasets/luxury-lakehouse/football2vec-training-data)
- **对抗性去偏**：通过对抗竞赛预测头进行梯度反转（Ganin等人2016年研究），使嵌入向量编码球员的行为特征而非联赛身份
- **发布脚本**：[`scripts/train_football2vec_v2.py`](https://github.com/karsten-s-nielsen/luxury-lakehouse/blob/main/scripts/train_football2vec_v2.py)

## 应用场景

- **球员相似度检索**：基于`embedding`字段的余弦相似度可返回跨联赛的行为相似球员
- **反事实替换分析**（“若球员X加入Y队的进攻回合，会有怎样的表现？”）：可作为下游可视化分析的输入
- **角色聚类**：通过UMAP/PCA降维投影可揭示脱离联赛身份的球员角色原型（v1基线模型倾向于按联赛聚类，v2则无此问题）

## 局限性

- **仅包含公开赛事数据**：商业数据集覆盖了更多联赛与赛季
- **训练时间快照**：仅当v2模型重新训练时，嵌入向量才会更新；两次训练之间新增的球员不会出现在本数据集中
- **无位置信息**：未包含角色标签，下游使用者需自行应用角色分类器

## 许可证

CC-BY-NC 4.0（继承自Wyscout训练数据的许可证）

## 配套资源

| 资源 | 类型 | 描述 |
|----------|------|-------------|
| [Football2Vec v2 模型](https://huggingface.co/luxury-lakehouse/football2vec-v2) | 模型 | 生成本数据集嵌入向量的Transformer编码器 |
| [Football2Vec 训练数据](https://huggingface.co/datasets/luxury-lakehouse/football2vec-training-data) | 数据集 | 上游训练语料 |
| [Football2Vec v1（已弃用）](https://huggingface.co/luxury-lakehouse/football2vec-statsbomb-wyscout) | 模型 | 已被v2取代的传统Doc2Vec模型 |
| [Football2Vec 球员嵌入向量](https://huggingface.co/datasets/luxury-lakehouse/football2vec-player-embeddings) | 数据集 | 多粒度嵌入向量（生涯/赛季/单场） |