两年前帮一个做体育数据分析的小团队重构他们的预测脚本，对方一开始的要求很朴素：把历史比赛数据喂给模型，算出每场比赛的胜负概率，再套个网页界面能点就行。我当时图省事，直接用一个梯度提升模型单打独斗，交叉验证的 Log Loss 看着还行，可等到用往届杯赛做时间外回测，结果立刻露馅——同一批数据换个随机种子重训，同一场比赛的胜率能从 48% 跳到 56%，这种幅度足够把一个看起来靠谱的结论彻底推翻。后来把模型换成集成结构，加上概率校准，情况才稳住。这篇文章就围绕基于 Ensemble 的杯赛赛事预测这件事展开，讲清楚集成到底在什么环节起了作用、数据管道该怎么搭才不泄漏、概率为什么要校准，以及最后怎么用 Streamlit 把它包装成一个能交互、能解释、不会自己骗自己的应用。适合已经会用 Python 做建模、想把模型往前端推一步的读者，也适合刚入门、想避开几个经典坑的朋友。
1. 单模型做赛事预测最要命的问题不在准确率
1.1 足球比赛的信噪比低到超出多数人的直觉
做结构化数据建模的人转过来做赛事预测，第一反应往往是"特征工程做好，模型调优，准确率冲上 65% 不难"。真跑起来就会发现不是这么回事。一场足球比赛的有效样本量极小：90 分钟内进球数通常是个位数，决定结果的关键事件（一次门柱、一次误判、一张红牌）本质上接近随机。哪怕两支球队实力差距明显，强队的胜率在真实分布里也很少超过 70%，三分类任务里理论上的准确率天花板大概就落在 55% 到 62% 这个区间。
这个先验很重要，因为它决定了你对模型表现的预期。如果你的回测跑出 75% 的准确率，不要高兴，先怀疑数据泄漏。我见过不止一次这种情况，最后查出来都是把赛后统计（全场射门数、控球率、角球数）错当成赛前特征用了。这些字段在赛后是确定的，在赛前根本不存在，模型学到的是"射门多的队更容易赢"这种废话，回测漂亮，实盘无意义。
所以在这一类任务里，优化的目标从来不是把准确率从 58% 拉到 60%，而是让输出概率的可靠性和稳定性提升。一场比赛你告诉用户主队胜率 52%，那就得意味着在历史上一大批类似情形的比赛里，主队真的赢了一半多一点。这个是校准问题，后面第 4 节单独讲。
1.2 方差才是单模型的主要失分来源
我把单模型的问题拆成两块看：偏差和方差。偏差来自模型假设，逻辑回归只能画线性的决策边界，对"两队 Elo 差在 50 分以内、且主队休息天数少 3 天"这种交互效应天然无能为力；树模型能捕捉交互，但单棵树方差大，靠 bagging 压下来一部分，仍然对特征扰动敏感。方差则来自训练数据本身的随机性——几百到几千条历史比赛记录，随机划分一次训练集和验证集，模型的结论就可能漂移。
集成学习在这个场景的收益，主要来自方差压缩，而不是偏差修正。这一点很多人会误解，以为上了集成就能"更准"。实际测下来，软投票或者 stacking 相比最好的那个基模型，准确率提升通常在 1 到 2 个百分点之间，有时候甚至持平；但 Log Loss 和 Brier Score 的改善明显得多，同一场比赛的概率输出在不同随机种子下的波动从 5 到 8 个百分点收到 1 到 2 个百分点。对下游应用来说，这个稳定性比准确率重要得多。
| 方案 | 三分类准确率 | Log Loss | Brier Score | 种子间概率波动 |
|---|---|---|---|---|
| 逻辑回归（多项） | 0.54 到 0.56 | 1.02 左右 | 0.62 左右 | 小 |
| 单棵梯度提升 | 0.55 到 0.58 | 0.98 左右 | 0.60 左右 | 大，5 到 8 个点 |
| 随机森林（500 棵） | 0.55 到 0.57 | 0.99 左右 | 0.60 左右 | 中 |
| 软投票集成 | 0.56 到 0.58 | 0.96 左右 | 0.58 左右 | 小 |
| Stacking（LR 元学习器） | 0.56 到 0.59 | 0.94 左右 | 0.56 左右 | 小 |
| Stacking + 校准 | 0.56 到 0.59 | 0.91 左右 | 0.54 左右 | 小 |
表里的数值是量级示意，具体数字取决于数据覆盖的赛事范围、特征质量和时间跨度，不要当基准线照抄。但它反映的规律是稳的：集成的价值主要写在概率质量相关的指标上。
1.3 这个项目到底要交付什么
把交付物定义清楚，能省掉后面大量的返工。我给这个项目定的边界是三条：
第一，一个可复现的训练管道。从原始比赛记录到最终模型文件，中间每一步都能重跑，随机种子固定，特征生成逻辑不依赖任何手工干预。这是后面能不能做归因分析、能不能做版本对比的前提。
第二，一个概率输出接口。输入是两支球队的标识和比赛上下文（是否中立场、日期、赛程密度），输出是三分类概率加一个置信度提示。不做"必胜推荐"这类表述，只输出概率分布和模型的不确定性。
第三，一个 Streamlit 前端。让不懂代码的人也能点选参数、看到概率、看到关键特征对结果的贡献方向，而不是只有一个干巴巴的数字。
明确不做的部分同样重要：不做实时赔率接入，不做自动化投注决策，不做基于社交媒体的情绪特征。这三样都会把项目拖进一个既难验证又难解释的泥潭。
2. 数据管道：从原始比分到能训练的样本矩阵
2.1 原始记录的清洗顺序不能乱
原始数据通常是"一行一场比赛"的结构，字段包括比赛日期、主队标识、客队标识、主队进球、客队进球、赛事阶段、是否中立场等。看着简单，清洗顺序搞错就会埋雷。
我的处理顺序固定为：去重 → 按日期升序排序 → 队伍标识归一化 → 缺失值处理 → 类型转换。队伍标识归一化这一步最容易低估，同一支球队在不同数据源里可能有全称、缩写、带地区前缀的写法，甚至同一届赛事内因为翻译差异出现两种写法。如果不先统一，后面按队伍分组算滚动特征时，同一支队会被拆成两个实体，近 5 场状态直接算错。
TEAM_ALIAS = { "某队全称": "TEAM_A", "某队缩写": "TEAM_A", "另一队全称": "TEAM_B", } def normalize_team(name: str) -> str: key = name.strip().replace(" ", "") return TEAM_ALIAS.get(key, key)别名表一定要单独维护成一个可编辑的文件，不要硬编码在脚本里。赛事开始前经常会有临时调整，硬编码意味着每次都要改代码、重新走一遍发布流程，麻烦且容易出错。
缺失值处理按字段性质分开对待。比分字段缺失的记录直接丢弃，因为没有标签；比赛上下文字段（比如是否中立场）缺失可以按赛事阶段推断——小组赛通常有主场，淘汰赛多在中立场地；特征类的原始字段缺失，用"该队历史均值"填补比用全局均值合理，但要在特征里加一个缺失标记列，让模型知道这个值是补的。
2.2 滚动特征必须做成长表再合并
这是我在这个项目里踩得最深的一个坑。很多人会直接在主客队宽表上这样写：
df["home_goals_l5"] = ( df.groupby("home_team")["home_goals"] .transform(lambda s: s.shift(1).rolling(5, min_periods=2).mean()) )这段代码逻辑上没错，但它只统计了这支球队作为主队时的进球，客场比赛的进球完全没算进去。结果就是"近 5 场场均进球"这个特征实际含义变成了"近 5 个主场的场均进球"，样本量砍半，淘汰赛阶段球队主客场交替时数值剧烈跳变。
正确做法是把宽表转成"每队每场一行"的长表，统一计算滚动统计，再分别 merge 回主队侧和客队侧。
import pandas as pd def to_long(df: pd.DataFrame) -> pd.DataFrame: home = df[["match_id", "date", "home_team", "home_goals", "away_goals"]].copy() home.columns = ["match_id", "date", "team", "goals_for", "goals_against"] home["is_home"] = 1 away = df[["match_id", "date", "away_team", "away_goals", "home_goals"]].copy() away.columns = ["match_id", "date", "team", "goals_for", "goals_against"] away["is_home"] = 0 long = pd.concat([home, away], ignore_index=True).sort_values(["team", "date"]) return long def add_rolling(long: pd.DataFrame, windows=(5, 10)) -> pd.DataFrame: g = long.groupby("team", group_keys=False) for w in windows: long[f"gf_l{w}"] = g["goals_for"].transform( lambda s: s.shift(1).rolling(w, min_periods=max(2, w // 2)).mean() ) long[f"ga_l{w}"] = g["goals_against"].transform( lambda s: s.shift(1).rolling(w, min_periods=max(2, w // 2)).mean() ) return longshift(1)是必须的，没有它当场比赛的结果就混进了特征，这是最典型的标签泄漏。min_periods设成窗口的一半而不是窗口全长，是为了让赛事开局阶段也有可用特征，否则前几轮全是 NaN，白白浪费样本。代价是前几场的滚动值不太稳，这个可以在特征里加一个"历史样本数"列交给模型自己判断。
2.3 Elo 分与赛程上下文
Elo 是这类任务里性价比最高的特征，一个数字就编码了球队的长期实力，还自带时间衰减。更新公式很简单：
def update_elo(ra: float, rb: float, score_a: float, k: float = 20.0): ea = 1.0 / (1.0 + 10 ** ((rb - ra) / 400.0)) ra_new = ra + k * (score_a - ea) rb_new = rb + k * ((1.0 - score_a) - (1.0 - ea)) return ra_new, rb_newscore_a取 1、0.5、0 分别对应主胜、平、客胜。三个参数值得调：
k控制更新幅度。常规赛事 20 合适，重大赛事可以提到 30 到 40，让模型对大赛状态变化更敏感。但k太大，Elo 会跟着单场爆冷剧烈摆动，反而失真。- 初始值统一设 1500，杯赛新军没有历史数据时就直接用这个值，配合一个"Elo 数据可信度"特征（该队历史比赛场次）一起喂给模型。
- 主场优势可以通过给主队加一个固定偏移量来体现，通常 60 到 100 分。中立场比赛这个偏移量置零，这个处理比让模型自己去学"是否中立场"的二元特征更稳，因为中立场样本本来就少。
赛程上下文特征里，"休息天数"比想象中管用。杯赛赛程密集，小组赛三天一场是常态，淘汰赛阶段还可能出现加时赛。计算方式是该队上一场比赛日期到本场日期的天数差，第一次出现在赛事里就填一个中位数。另外还可以加"近 14 天比赛场次"，作为赛程密度代理。
| 特征组 | 代表字段 | 处理要点 |
|---|---|---|
| 长期实力 | Elo 分及差值 | 逐场滚动更新，禁止用全量数据一次性算 |
| 近期状态 | 近 5 / 10 场进失球均值、胜率 | 长表计算，shift(1) 防泄漏 |
| 进攻效率 | 近 5 场射正率、进球转化率 | 缺失用队内历史均值补，加缺失标记 |
| 赛程 | 休息天数、近 14 天场次 | 首次出场填中位数 |
| 交手 | 近 3 次交手结果 | 样本极少，只做辅助特征 |
| 上下文 | 是否中立场、赛事阶段 | 独热编码，阶段做有序编码 |
2.4 标签构造与时间切分
标签做成三分类最直接：主胜、平局、客胜。也有人把平局单独拆出来做二阶段模型（先判是否分胜负，再判胜负），我试过，效果不如直接三分类加校准稳，因为平局在杯赛淘汰赛阶段会被加时和点球抹掉，样本定义本身就模糊。处理办法是：小组赛阶段平局保留为一个类别，淘汰赛阶段的比赛只计入 90 分钟结果，加时和点球的胜负不计入标签。
切分绝对不能随机。按比赛日期做时间切分，训练集用早期比赛，验证集用近期比赛，测试集用最近一届赛事。更严谨一点的做法是按赛事分组做 GroupKFold，确保同一届比赛不会同时出现在训练和验证里。
from sklearn.model_selection import GroupKFold gkf = GroupKFold(n_splits=5) for tr_idx, va_idx in gkf.split(X, y, groups=df["tournament_id"]): ...分组切分的一个副作用是验证集上的表现会比随机切分难看不少，这是好事——它更接近真实使用场景。如果你发现分组切分和随机切分的指标差距超过 15%，几乎可以确定存在跨赛事的特征泄漏，值得停下来查。
3. 投票、Bagging、Stacking 在这个场景怎么选
3.1 软投票是成本最低的起点
投票集成最简单，几个基模型各出一份概率，加权平均。关键点是用软投票不要用硬投票。硬投票是每个模型投一票，最后数票数；这对三分类任务很不友好，因为平局和客胜的概率分布经常很接近，硬投票会把这个信息抹掉，输出的还是离散的类别，拿不到概率。
软投票的实现就是加权平均概率：
proba = sum(w * m.predict_proba(X) for m, w in zip(models, weights)) proba = proba / sum(weights)权重怎么定？不要拍脑袋。我的做法是用验证集上的 Log Loss 反推，权重取1 / logloss_i，再归一化。这样表现差的模型自动降权，不用手工调。但要给权重设个下限，比如不低于 0.1，否则一个在验证集上偶然表现特别好的模型会吃掉全部权重，退化成单模型。
软投票的优势是可控、可解释、训练成本低；劣势是它假设各基模型的误差相互独立，而实际上逻辑回归和树模型在同一批特征上犯的错是相关的，收益会被打折。所以软投票更适合作为基线，先跑通再往上叠。
3.2 Bagging 和 Boosting 在低信噪比数据上的分化
随机森林属于 Bagging 路线，靠对样本和特征双重采样降低方差。在赛事预测这种噪声占比很高的数据上，它的表现往往比预期好，因为 bagging 天然抗噪。参数上我一般设n_estimators=500、max_depth=8、min_samples_leaf=20，叶子节点样本数不能太小，否则每棵树都在记住噪声。
梯度提升系列（XGBoost、LightGBM）属于 Boosting 路线，靠逐步拟合残差降低偏差。它的上限更高，但对参数和噪声都敏感得多。在只有几千条样本的场景下，我踩过的坑基本都是"树太深、学习率太大、正则太弱"这三件套：
max_depth控制在 3 到 5。超过 6，验证集立刻开始掉。learning_rate用 0.03 到 0.08，配合n_estimators400 到 800，用早停决定实际轮数。min_child_samples（LightGBM）或者min_child_weight（XGBoost）要放大，30 到 50 起步。subsample和colsample_bytree都压到 0.7 到 0.85，强制每轮看不同的数据子集。reg_lambda给到 1 到 5，这个正则项在样本少的时候非常关键。
from lightgbm import LGBMClassifier from xgboost import XGBClassifier lgbm = LGBMClassifier( n_estimators=600, learning_rate=0.05, num_leaves=15, min_child_samples=40, subsample=0.8, colsample_bytree=0.8, reg_lambda=2.0, objective="multiclass", num_class=3, random_state=42, n_jobs=-1, ) xgb = XGBClassifier( n_estimators=500, learning_rate=0.05, max_depth=4, min_child_weight=8, subsample=0.8, colsample_bytree=0.8, reg_lambda=2.0, objective="multi:softprob", num_class=3, random_state=42, n_jobs=-1, )一个实操细节：LightGBM 在这么小的数据量上，num_leaves建议直接压到 15 以内，不要用默认的 31。默认值是为万级以上样本设计的，用在这里等于让模型自由生长。
3.3 Stacking 的元学习器宁简勿繁
Stacking 的思路是让基模型在训练集上做 K 折交叉，把每折的袋外预测概率作为元特征，再训练一个元学习器。这一步的关键在于必须用袋外预测，不能直接用基模型在训练集上的预测——后者是过拟合的，元学习器会学到"哪个模型在训练集上更自信"这种无用信息。
from sklearn.ensemble import StackingClassifier, RandomForestClassifier from sklearn.linear_model import LogisticRegression from sklearn.pipeline import make_pipeline from sklearn.preprocessing import StandardScaler base_estimators = [ ("lr", make_pipeline(StandardScaler(), LogisticRegression(max_iter=2000, C=0.5))), ("rf", RandomForestClassifier( n_estimators=500, max_depth=8, min_samples_leaf=20, random_state=42, n_jobs=-1)), ("lgbm", lgbm), ("xgb", xgb), ] stack = StackingClassifier( estimators=base_estimators, final_estimator=LogisticRegression(max_iter=1000, C=1.0), cv=5, stack_method="predict_proba", passthrough=False, n_jobs=-1, )元学习器我固定用逻辑回归，理由有三条。第一，元特征维度很低（4 个基模型 × 3 个类别 = 12 维），复杂模型没有发挥空间，只会过拟合。第二，逻辑回归的输出天然是概率，配合后面的校准环节衔接顺畅。第三，它的系数可以直接看出来哪个基模型贡献大，调试时非常有用——我有一次发现某个基模型的权重接近零，追下去发现是它的特征顺序和数据管道不一致，属于静默故障，如果换成树模型当元学习器就查不出来了。
passthrough设成 False，也就是不把原始特征透传给元学习器。开着它会让元学习器有机会重新学习原始特征，绕过了基模型的集成意义，在样本量小的时候几乎必然过拟合。
cv=5在几千条样本上是合适的。样本再少就得降到 3，否则每折的训练集太小，袋外预测本身就不稳，元特征噪声大，反而不如简单平均。
4. 概率校准：让输出的"胜率"真的能当概率看
4.1 未校准的分类器输出不是概率
集成模型输出的predict_proba，严格来说只是一个排序分数，不是校准过的概率。梯度提升类模型尤其明显，因为它的损失函数优化的是分类边界，不是概率的似然。表现出来就是：模型说 60% 胜率的那些比赛，实际胜率可能只有 50%；或者说 90% 的那些，实际只有 75%。这种系统性偏移在赛事预测里很致命，因为用户看到的第一个数字就是这个百分比。
判断有没有校准问题，画一张可靠性图（reliability diagram）最快。把预测概率分箱，横轴是预测均值，纵轴是实际频率，理想情况是一条 45 度对角线。如果曲线整体在对角线下方，说明模型过度自信；在上方说明过度保守。
import numpy as np from sklearn.calibration import calibration_curve def reliability(y_true_bin, y_prob, n_bins=10): frac_pos, mean_pred = calibration_curve( y_true_bin, y_prob, n_bins=n_bins, strategy="quantile" ) return mean_pred, frac_pos对三分类任务，要一类一类地做 one-vs-rest 分析。常见的现象是主胜这一类校准得还行，平局这一类严重欠自信——因为平局样本少，模型倾向于给低概率。这个偏差会传导到最终决策上。
4.2 校准方法的选择：Platt 还是 Isotonic
两个主流选项。Platt scaling 用一个逻辑函数去拟合预测分数和实际频率的关系，参数只有两个，样本需求少，不容易过拟合，但它假设校准曲线是 S 形，如果真实关系不是这个形状就会被压扁。Isotonic regression 是单调分段常数拟合，灵活度高，但需要更多样本，样本不够时会阶梯化得厉害，出现概率跳变。
我的经验规则是：校准集样本量在 1000 以上用 Isotonic，低于 1000 用 Platt。赛事预测的训练样本通常在这个边界附近，所以两个都试一遍，用验证集的 Brier Score 决定。
from sklearn.calibration import CalibratedClassifierCV calibrated = CalibratedClassifierCV( estimator=stack, method="isotonic", cv=5, ) calibrated.fit(X_train, y_train)这里有个版本兼容的坑要提醒。老版本 sklearn 支持cv="prefit"，让你先训练好模型再单独校准；新版本改成用FrozenEstimator包装：
from sklearn.frozen import FrozenEstimator calibrated = CalibratedClassifierCV( estimator=FrozenEstimator(stack), method="isotonic", ) calibrated.fit(X_calib, y_calib)FrozenEstimator的路径在不同版本里变过几次，跑之前先python -c "import sklearn; print(sklearn.__version__)"确认一下，别直接抄网上老代码。
校准集必须和训练集分开。用cv=5让 sklearn 内部切分是最省事的做法，但要注意它切的是随机的 K 折，跟前面按赛事分组的逻辑不一致。更严谨的做法是手工切一个时间靠后的校准集，用FrozenEstimator单独校准。
4.3 用什么指标判断校准有没有生效
准确率在这里完全没用，它对概率偏移不敏感。要看三个指标：
| 指标 | 含义 | 优化方向 |
|---|---|---|
| Log Loss | 概率预测的对数似然 | 越小越好，对过度自信惩罚重 |
| Brier Score | 概率与真实标签的均方误差 | 越小越好，直观且可分解 |
| ECE（期望校准误差） | 分箱后预测均值与实际频率的加权差 | 越小越好，直接衡量校准质量 |
Brier Score 有个好处是可以分解成可靠性、分辨力和不确定性三部分，能看出模型到底是"分得开但没校准"还是"校准了但分不开"。我一般把分解结果打印出来看一眼，如果分辨力那一项很低，说明特征本身的信息量不够，再怎么调校准也是白搭。
from sklearn.metrics import log_loss, brier_score_loss import numpy as np def evaluate(y_true, proba): ll = log_loss(y_true, proba, labels=[0, 1, 2]) brier = np.mean([ brier_score_loss((y_true == k).astype(int), proba[:, k]) for k in range(3) ]) return {"log_loss": round(ll, 4), "brier": round(brier, 4)}校准之后预期 Log Loss 下降 0.02 到 0.05，Brier 下降 0.01 到 0.03。如果校准后指标反而变差，八成是校准集太小或者和训练集分布不一致（比如校准集全是小组赛，测试集全是淘汰赛），检查一下切分逻辑。
5. Streamlit 前端：把模型包成不会误导人的产品
5.1 页面结构按"输入—输出—解释"三段走
Streamlit 最大的诱惑是让人把整个页面堆成一个长条形，控件、图表、表格从上到下排一溜，用户滚到下面已经忘了上面选的是什么。我的页面固定分三段，用st.tabs或者侧边栏组织：
侧边栏放全局配置——选择赛事阶段、选择两支球队、是否中立场、比赛日期。主区域分三个 tab：概率预测、特征贡献、历史表现。
import streamlit as st st.set_page_config(page_title="赛事概率预测", layout="wide") with st.sidebar: st.subheader("比赛设置") home_team = st.selectbox("主队", team_options, index=0) away_team = st.selectbox("客队", team_options, index=1) neutral = st.checkbox("中立场", value=True) stage = st.selectbox("赛事阶段", ["小组赛", "十六强", "八强", "半决赛", "决赛"]) match_date = st.date_input("比赛日期") if home_team == away_team: st.warning("主客队不能相同") st.stop()st.stop()这个用法值得记住。Streamlit 的执行模型是每次交互都从头重跑整个脚本，如果不提前中断，后面的模型推理会拿着非法输入跑出莫名其妙的结果。所有输入校验都应该在脚本靠前的位置做完，用st.stop()挡住。
主区域的结果展示，我坚持"概率 + 区间 + 置信提示"三件套，而不是只给一个百分比。做法是用 bootstrap 在验证集上重采样，得到三分类概率的分布，取 5% 和 95% 分位数作为区间。
col1, col2, col3 = st.columns(3) col1.metric("主胜", f"{p_home:.1%}", help=f"区间 {lo_home:.1%} 至 {hi_home:.1%}") col2.metric("平局", f"{p_draw:.1%}", help=f"区间 {lo_draw:.1%} 至 {hi_draw:.1%}") col3.metric("客胜", f"{p_away:.1%}", help=f"区间 {lo_away:.1%} 至 {hi_away:.1%}")用help参数把区间藏进悬浮提示，既不占版面，又让想深入的用户能查到。加区间这件事看着小，实际效果很明显——它天然告诉用户"这是个估计，不是结论"，能挡掉大量"你上次说 60% 结果输了"的质疑。
5.2 缓存分两类，混用会出怪问题
Streamlit 的缓存分st.cache_data和st.cache_resource，很多人图省事全用前者，然后在模型对象上踩坑。区别是：
st.cache_data缓存的是可序列化的数据，每次调用返回一个副本。适合 DataFrame、字典、数组这类东西。st.cache_resource缓存的是全局共享的对象，返回同一个实例。适合模型、数据库连接、tokenizer。
模型必须用cache_resource。用cache_data的话，每次页面重跑都会尝试深拷贝模型对象，轻则慢，重则因为某些模型内部持有不可序列化的句柄直接报错。
import pickle import pandas as pd import streamlit as st @st.cache_resource(show_spinner=False) def load_model(path: str): with open(path, "rb") as f: return pickle.load(f) @st.cache_data(ttl=1800, show_spinner=False) def load_features(path: str) -> pd.DataFrame: return pd.read_parquet(path)ttl参数也别忽略。特征数据如果会随着新比赛结果更新，设一个 30 分钟到 1 小时的过期时间；不设的话进程不重启就永远是旧数据，容易在演示时出现"刚更新完数据页面还是老的"这种尴尬。
还有一个性能细节：特征计算（尤其是滚动特征）如果放在页面脚本里直接跑，每次交互都要重算几千行，响应会明显卡顿。正确做法是离线算好落盘，页面只做查表和推理，页面里只保留"给定两队 + 上下文 → 组装特征向量"这一步。
5.3 交互设计上最容易犯的三个错
第一个错：滑杆的默认值随意设。用st.slider调参的时候，默认值如果不落在数据实际分布的中心，用户第一次看到的结果就是异常的。比如"休息天数"滑杆默认给 7 天，但杯赛期间多数球队休息 3 到 4 天，那初始预测天然偏向休息充分的一方，用户会误以为模型有偏差。默认值取训练集的中位数，这是最基本的要求。
第二个错：只给结论不给解释。用户看到"主胜 41%"，第一反应是"为什么这么低"。这时候需要有特征贡献视图。集成模型没法直接给 SHAP 之外的单样本解释，用 SHAP 的 TreeExplainer 对树模型基模型算一遍，取前 8 个特征做横向条形图，正负分色。这一步的计算量在单样本上很小，可以放进页面实时算。
第三个错：球队选择没做互斥校验。上面代码里那段st.stop()就是干这个的。除此之外还要校验：所选球队是否在本届赛事里有足够的历史数据（少于 3 场的话特征基本靠补，要给用户明示），所选日期是否晚于该队上一场比赛日期（早于的话休息天数是负数，特征直接崩）。
这些校验加起来大概二十行代码，但能把 90% 的"页面报错"类问题挡在门外。
6. 踩坑记录与上线前的自检清单
6.1 数据泄漏的三种隐蔽形态
第一种是前面提过的赛后字段当赛前特征。这类问题在字段名上很难看出来，因为数据表里"射门数"和"Elo 分"混在一起。我的处理办法是给每个特征维护一个元数据表，标注数据可得时间点（开赛前 / 赛后），建模时只允许选开赛前的。这个表看起来是额外工作量，但它是唯一能系统性防住这类错误的手段。
第二种是滚动统计没做时间对齐。比如用rolling(5).mean()但忘了shift(1)，或者先算完全量数据的标准化参数再切分训练集。后者的典型表现是：训练集用了全量均值方差做 StandardScaler，而全量里包含了测试期的比赛，等于测试集的信息漏进了训练。正确做法是把 scaler 放进 Pipeline，让它只在训练折上 fit。
第三种最隐蔽，是球队实力特征用了未来信息。Elo 分的更新是逐场的，如果你用最终版 Elo 表去 merge 历史比赛，那每场比赛用的都是"这支球队打到赛事结束时的实力"，等于提前知道了结果。Elo 必须在训练管道内部逐场滚动生成，生成完再拼特征，不能拿一份现成的最终表去查。
检测泄漏有个笨办法但很有效：故意把标签打乱，重训一遍。如果模型在打乱标签的数据上还能跑出明显高于随机的准确率（比如三分类跑到 45% 以上），说明特征里有泄漏，因为正常情况打乱标签后模型应该退化到 33% 附近。
6.2 模型漂移和重训练触发条件
杯赛的一个特点是时间跨度短、球队状态变化快。四年前的数据对当下的参考价值有限，全部堆进训练集会稀释近期信号。我的做法是给样本加时间衰减权重，越近的比赛权重越高：
import numpy as np def time_decay_weight(dates, ref_date, half_life_days=540): age = (ref_date - dates).dt.days.values return 0.5 ** (age / half_life_days)半衰期设 540 天（约一年半）是我试出来的平衡点。设成 365 天，样本量掉太快，模型不稳；设成 1080 天，近期状态的影响被淹没。
重训练的触发条件定三条：赛事进入淘汰赛阶段时重训一次（样本分布变了）；累计新增比赛超过 30 场时重训；线上预测的 Log Loss 滑动平均连续 5 场超过基线 10% 时告警。第三条需要用线上反馈回填，所以要提前把预测结果和实际结果都落库。
6.3 上线前的检查清单
下面这些是我每次上线前逐条过的，每一条都对应过一次真实故障：
| 检查项 | 具体动作 | 不合格的后果 |
|---|---|---|
| 特征顺序一致 | 比对训练与推理的特征列名和顺序 | 静默错位，预测全乱但不报错 |
| 缺失值兜底 | 构造一个全 NaN 输入跑推理 | 页面直接 500 |
| 类别映射 | 检查标签编码映射是否硬编码一致 | 主胜显示成客胜 |
| 校准有效性 | 在校准集上复算 Brier 与 ECE | 概率系统性偏移 |
| 缓存命中 | 连续点击三次同一按钮看响应时间 | 模型被反复加载，卡顿 |
| 极值输入 | 输入两支从没交过手的球队 | 特征全填默认值，结果无意义但页面正常 |
| 版本锁定 | requirements 固定小版本号 | 换个环境装出来的结果不一致 |
倒数第二条特别值得说。两支没有交手记录的球队，交手特征全是缺失，如果兜底策略是填 0，模型会把"0 次交手"理解成某种真实状态，输出一个看起来正常但毫无依据的概率。正确做法是检测到关键特征缺失比例超过阈值时，在页面上明确提示"该对阵历史数据不足，结果仅供参考"，而不是默默给个数字。
特征顺序那一条也是老坑。sklearn 的模型对象本身不记列名，传入的 DataFrame 列顺序变了，它会安静地按位置取值，预测结果照样输出，只是全错了。解决办法是在 Pipeline 前面加一个记录列顺序的包装，或者在推理入口强制X[FEATURE_COLS]做重排，两行代码的事。
最后再分享一个小技巧：把整个推理链路的中间结果（组装后的特征向量、各基模型的概率、校准后的概率）都打印到日志里，只在参数加一个开关控制。赛事期间排查问题，光看最终输出根本定位不到是哪一环出的偏差，有中间结果就能一眼看出是特征组装错了还是模型本身有问题。这套日志我加过一次之后，同类问题的排查时间从半天缩短到十分钟以内。
