企业官网建设流程全解析

简介：LeaguePredictor 是一套面向电子竞技数据分析初学者与实战开发者的 Python 胜率预测项目，围绕英雄联盟历史对局构建从数据处理到模型部署的完整链路，适合用来练习监督学习分类任务、特征工程与模型评估。压缩包共 24 个文件，以 22 个 Python 脚本为主，另含 .gitignore 与说明文本，整体约 31KB；代码按数据预处理、特征构建、游戏数据生成、分类器训练与测试等模块组织，并配有配置文件与多组测试脚本，便于按目录理解项目结构、复现实验流程和排查运行问题。已有 236 人学习或下载。项目覆盖战队与选手信息清洗、KDA 与经济等特征提取、逻辑回归/随机森林等模型选择、交叉验证调参及准确率等指标评估，能帮助读者掌握一套可迁移的电竞预测建模方案，并据此开展自己的赛事分析或课程实践。

1. 排位打到 25 分钟，这局到底几成赢面

排位打到第 25 分钟，人头 12 比 9，经济领先 4200，龙区视野也压着对面，可屏幕上不会告诉你这局赢面到底几成。LeaguePredictor 补的就是这一块：喂进一局对局在某个时间点的快照——双方经济、等级、推塔数、大小龙、视野得分——它回一个 0 到 1 的胜率数字。整个项目是 Python 写的端到端链路，采集、清洗、特征工程、模型训练、推理服务一条龙，不是甩一个 notebook 出来让人自己拼。适合两类人：想完整跑通一个结构化数据机器学习项目的新手，以及手里已经攒了自己的对局数据、想快速搭一套局势预测服务的开发者。它不复刻任何官方模型，价值在于把「快照到概率」这条工程链路摊开给你看。

2. 整体架构与技术选型：一个 Python 单机项目的分层

2.1 输入输出定义：一局快照进，一个概率出

这个项目最容易被误解的一点，是它不做「赛前 BP 预测」，也不做「整局复盘评分」。它预测的是条件概率：给定第 t 分钟的局面状态，蓝方最终赢下这局的概率。这个定义决定了后面所有工程细节——采样时间点怎么选、标签怎么打、特征怎么构造。

输入是一份结构化快照，我把它定成一个扁平的 JSON，字段尽量贴近对局数据接口能直接给到的东西：

{ "match_id": "M-0001", "minute": 22, "blue": {"kills": 12, "gold": 41200, "towers": 5, "dragons": 2, "heralds": 1, "barons": 0, "vision": 58, "avg_level": 13.4}, "red": {"kills": 9, "gold": 37000, "towers": 3, "dragons": 1, "heralds": 0, "barons": 0, "vision": 41, "avg_level": 12.9} }

输出只有一个字段：{"win_prob": 0.71}。选蓝方视角是刻意的约定，因为对局数据里天然有blue_win这个布尔标签，不用额外做对称增强；如果两边视角都想支持，推理服务里把输入做一次镜像交换再跑一遍就行，不需要训练两个模型。

这里有个设计取舍值得说清楚：为什么不直接预测「最终经济差」或者「推塔数」这种回归目标？因为胜率是二分类，评估指标（AUC、LogLoss、校准曲线）成熟且解释成本低，业务方看到 0.71 能直接理解，看到「预计领先 8300 经济」还得再脑补一步。

2.2 技术栈选型：为什么是 pandas 加 LightGBM 加 FastAPI

技术栈没有花活，全是结构化数据项目里的常规搭配，但每一层都有具体理由。

至于为什么不上深度学习：这类特征维度只有二三十维、样本量在几万到几十万量级，树模型在结构化数据上表现通常不差，而且推理延迟在毫秒级，单机部署不需要 GPU。深度学习在这类问题上大概率是给自己找麻烦——调参周期长、可解释性差、上线后出问题排查起来跟黑匣子一样。

2.3 目录结构：从 data 到 serve 的六层

LeaguePredictor/ ├── data/ │ ├── raw/ # 采集下来的原始对局 JSON，按天分文件 │ ├── interim/ # 展开后的宽表 parquet │ └── processed/ # 训练用特征矩阵与标签 ├── conf/ │ └── config.yaml # 采样时间点、特征开关、模型超参 ├── src/ │ ├── collect/ # 数据采集与落库 │ ├── features/ # 特征工程 │ ├── train/ # 训练、评估、模型导出 │ └── serve/ # 推理服务与前端静态页 ├── models/ # 序列化模型 + 特征列表 + 训练元信息 ├── notebooks/ # 探索性分析，不进生产链路 ├── tests/ # 特征函数与服务接口的单测 ├── requirements.txt └── Makefile # make collect / make train / make serve

data/这三层划分是整个项目最值得抄的部分。raw只放原始响应，永远不改；interim是展开成宽表之后、还没做特征变换的中间态；processed才是可以直接喂模型的矩阵。血泪经验是：很多项目把清洗逻辑写在 notebook 里，数据只存一份，改一次特征就得重采一次数据，来回折腾几次之后你根本不知道当前这份数据是哪版脚本产出的。分层存下来，重跑特征只要几分钟。

Makefile看起来是小东西，但它把make collect、make train、make serve三个入口固定住了，新人拉下来不用问「先跑哪个脚本」。

3. 数据链路与特征工程：把原始响应压成二十几维特征

3.1 采集与落库：从对局接口到本地原始文件

采集脚本的核心诉求只有两个：不把接口打挂，不丢数据。频率限制、超时重试、失败落盘这三件事必须做全，否则跑一晚上拿到一堆半截数据，第二天还得重来。

# src/collect/fetch_matches.py import os, json, time, pathlib import requests from tenacity import retry, stop_after_attempt, wait_exponential API_BASE = os.environ["MATCH_API_BASE"] # 对局数据服务基地址 API_KEY = os.environ["MATCH_API_KEY"] OUT_DIR = pathlib.Path("data/raw") OUT_DIR.mkdir(parents=True, exist_ok=True) @retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, max=30)) def fetch_one(match_id: str) -> dict: """拉取单场对局详情，失败按指数退避重试，最多 5 次""" resp = requests.get( f"{API_BASE}/matches/{match_id}", headers={"Authorization": f"Bearer {API_KEY}"}, timeout=8, ) if resp.status_code == 429: # 被限流，抛出去让 tenacity 退避 raise RuntimeError("rate limited") resp.raise_for_status() return resp.json() def fetch_batch(match_ids, out_path: pathlib.Path, sleep=1.2): """逐场拉取并追加写入 jsonl，中途挂了也能续跑""" done = set() if out_path.exists(): # 断点续传：已采过的跳过 with out_path.open() as f: done = {json.loads(line)["match_id"] for line in f} with out_path.open("a") as f: for mid in match_ids: if mid in done: continue try: detail = fetch_one(mid) except Exception as exc: # 单场失败不影响整批 print(f"[skip] {mid}: {exc}") continue f.write(json.dumps({"match_id": mid, "detail": detail}, ensure_ascii=False) + "\n") f.flush() # 立刻落盘，别等缓冲 time.sleep(sleep) # 主动降速，比被限流强

fetch_one里的429分支是特意单独处理的：直接把限流异常抛给 tenacity，让它按指数退避等 1、2、4、8 秒再试，比在循环里写死time.sleep更稳。fetch_batch的断点续传靠的是每次启动重读一遍已有文件、把match_id收进集合，几百 MB 的文件读一次也就几秒，比维护一个额外的状态文件省事。

OUT_DIR下面按天分文件是个小技巧：20240112.jsonl这种命名，出问题的时候能精确删掉某一天重采，不用全量重跑。

3.2 特征构造：差值、比率与时间归一化

原始字段有六十多个，但真正有信息量的没那么多。特征工程这一步的目标是把「两个阵营各自的绝对值」转成「双方对比的相对量」，因为模型真正关心的是差距，不是绝对值。

注意dragon_diff这类「累积型资源」不能简单相减就完事——一条风龙和一条火龙的价值不一样。如果数据源里有龙的类型字段，常见做法是按类型加权，权重从历史数据里统计「拿到该龙之后 5 分钟内的经济增量」得到，而不是拍脑袋定。

# src/features/build_features.py import pandas as pd DIFF_FIELDS = ["gold", "kills", "towers", "dragons", "heralds", "barons"] def build_features(df: pd.DataFrame) -> pd.DataFrame: """df 每行是一个快照，blue_* / red_* 为原始字段""" out = pd.DataFrame(index=df.index) out["minute"] = df["minute"].astype("int16") for f in DIFF_FIELDS: out[f"{f}_diff"] = df[f"blue_{f}"] - df[f"red_{f}"] # 时间归一化：同样 3000 经济差，10 分钟和 30 分钟意义完全不同 out["gold_diff_pm"] = out["gold_diff"] / out["minute"].clip(lower=1) # 比率型特征，加 1 平滑避免除零 out["vision_ratio"] = (df["blue_vision"] + 1) / (df["red_vision"] + 1) out["level_diff"] = df["blue_avg_level"] - df["red_avg_level"] # 时间衰减：越往后期，同样的经济差翻盘概率越低 out["gold_diff_x_min"] = out["gold_diff"] * (out["minute"] / 30.0) return out def add_label(df: pd.DataFrame) -> pd.DataFrame: """标签只取一场对局的最终结果，同一场所有快照共享""" df = df.copy() df["label"] = df["blue_win"].astype("int8") return df

gold_diff_x_min这个交叉特征是整个特征集里贡献最大的几个之一。道理很简单：10 分钟领先 3000 经济和 30 分钟领先 3000 经济，前者是优势，后者只是没崩。树模型理论上能自己学出这种交互，但显式给一个交叉项能明显缩短训练轮数，也方便后面做特征重要性分析时讲故事。

add_label里的注释是重点：标签来自对局最终结果，同一场比赛的每一个时间点快照都共享同一个标签。这一点直接引出下一节的坑。

3.3 数据泄漏：最容易被忽略的 AUC 虚高来源

第一版跑出来 AUC 0.987，我当时还挺得意，上线之后实际对局里给出的概率几乎全是 0.95 以上或者 0.05 以下，中间地带一片空白。回头查了两天才发现是三处泄漏叠在一起。

第一处，把final_gold、total_towers这类「结算字段」当成了特征。这些字段在赛后详情里跟实时快照混在同一个响应里，字段名又长得很像，df.filter(like="gold")一把梭就全捞进来了。

第二处，随机切分训练集和验证集。同一场比赛的 10 分钟、20 分钟、30 分钟三个快照被随机打散，训练集里见过这场的 20 分钟，验证集里考这场的 25 分钟，模型只要记住「这场比赛蓝方赢了」就能答对。正确的做法是按match_id分组切分：

# src/train/split.py from sklearn.model_selection import GroupShuffleSplit def split_by_match(df, test_size=0.2, seed=42): """按 match_id 分组切分，杜绝同一场比赛跨集合""" gss = GroupShuffleSplit(n_splits=1, test_size=test_size, random_state=seed) train_idx, valid_idx = next(gss.split(df, groups=df["match_id"])) return df.iloc[train_idx], df.iloc[valid_idx]

第三处更隐蔽：特征里包含了「本分钟之后」的信息。比如barons字段在某些数据源里统计的是全场累计，而不是截至当前分钟的累计。这种字段必须自己按时间戳重新累加，不能直接用接口给的聚合值。

改完这三处，AUC 从 0.987 掉到 0.83 左右。这个数字才是可信的——它跟你拿肉眼判断一局 25 分钟领先 5k 的胜率大致吻合。

4. 模型训练与推理服务：LightGBM 主模型加逻辑回归基线

4.1 训练脚本：早停、类别权重与特征列表导出

训练脚本我坚持写两个模型：逻辑回归当基线，LightGBM 当主力。基线的作用不是刷分，是给一个「不做任何非线性变换能到多少」的下限参考。如果 LightGBM 只比逻辑回归高 0.01 的 AUC，那说明特征本身信息量有限，该回去补特征而不是调参。

# src/train/train_lgbm.py import json, joblib, pathlib import lightgbm as lgb from sklearn.metrics import roc_auc_score, log_loss from src.features.build_features import build_features, add_label from src.train.split import split_by_match FEATURES = ["minute", "gold_diff", "gold_diff_pm", "kill_diff", "tower_diff", "dragon_diff", "herald_diff", "baron_diff", "vision_ratio", "level_diff", "gold_diff_x_min"] def train(df, out_dir="models"): df = add_label(df) train_df, valid_df = split_by_match(df) X_tr, y_tr = train_df[FEATURES], train_df["label"] X_va, y_va = valid_df[FEATURES], valid_df["label"] dtrain = lgb.Dataset(X_tr, y_tr) dvalid = lgb.Dataset(X_va, y_va, reference=dtrain) params = { "objective": "binary", "metric": ["auc", "binary_logloss"], "learning_rate": 0.05, "num_leaves": 63, "min_data_in_leaf": 200, # 防止在少数对局上过拟合 "feature_fraction": 0.85, "bagging_fraction": 0.8, "bagging_freq": 1, "verbosity": -1, } booster = lgb.train( params, dtrain, num_boost_round=2000, valid_sets=[dvalid], callbacks=[lgb.early_stopping(100), lgb.log_evaluation(200)], ) prob = booster.predict(X_va, num_iteration=booster.best_iteration) print(f"AUC={roc_auc_score(y_va, prob):.4f} LogLoss={log_loss(y_va, prob):.4f}") path = pathlib.Path(out_dir); path.mkdir(exist_ok=True) joblib.dump(booster, path / "lgbm.pkl") # 特征列表必须一起存，否则上线时字段顺序对不上，概率会静默出错 (path / "features.json").write_text(json.dumps(FEATURES), encoding="utf-8") return booster

几个参数值得单独说。min_data_in_leaf=200是防过拟合的第一道闸，样本量小的时候这个值往上调，能让树别切得太碎。early_stopping(100)的意思是验证集指标连续 100 轮不涨就停，配合num_boost_round=2000的上限，实际通常在两三百轮就停了。

features.json这一行是上线后救过命的：模型文件和特征列表必须成对存在。有一次我改了特征顺序，模型没重训，服务读进去的列顺序跟训练时不一致，LightGBM 不会报错，会默默算出完全错误的概率，排查了半天才定位到。从那以后我把「特征列表跟模型一起 dump」写进了所有类似项目。

4.2 评估：AUC 之外还要看校准

AUC 只关心排序，不关心概率数值本身准不准。可这个项目的输出是要展示给人看的 0.71，如果模型说 0.71 但实际胜率是 0.55，那就是误导。

# src/train/evaluate.py import numpy as np from sklearn.calibration import calibration_curve from sklearn.metrics import brier_score_loss def calibration_report(y_true, y_prob, n_bins=10): """按概率分桶，看每一桶的预测均值与真实胜率差多少""" frac_pos, mean_pred = calibration_curve(y_true, y_prob, n_bins=n_bins) for mp, fp in zip(mean_pred, frac_pos): print(f"预测均值 {mp:.3f} -> 实际胜率 {fp:.3f} -> 偏差 {fp - mp:+.3f}") print(f"Brier={brier_score_loss(y_true, y_prob):.4f}") # 越小越好

跑完一般会发现两个问题：两端（0.1 以下、0.9 以上）样本少、波动大；中间段系统性偏高。系统性偏高的典型修法是加一层等渗回归或者 Platt 缩放，在验证集上拟合、在测试集上验证，别在同一份数据上又拟合又评估。

另一个必须做的切片评估是按minute分组看 AUC。10 分钟的快照 AUC 往往只有 0.65 左右，30 分钟能到 0.9 以上——这符合直觉，但不看这个分布你就不知道模型在哪个阶段最不可靠，前端展示时也没法加「该阶段预测置信度较低」的提示。

4.3 推理服务：FastAPI 封装与启动时加载

服务层要做的事很朴素：校验输入、补默认值、调模型、返回概率。Pydantic 模型在这里不只是校验，它还兼了接口文档的职责，前端同学直接看/docs就能对接。

# src/serve/app.py import json, pathlib, joblib from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field from src.features.build_features import build_features import pandas as pd app = FastAPI(title="LeaguePredictor") class SideStats(BaseModel): kills: int = 0 gold: int = 0 towers: int = 0 dragons: int = 0 heralds: int = 0 barons: int = 0 vision: int = 0 avg_level: float = 1.0 class Snapshot(BaseModel): minute: int = Field(ge=1, le=90) # 约束范围，脏数据挡在门外 blue: SideStats red: SideStats STATE = {} @app.on_event("startup") def load_model(): """启动时一次性加载，避免首个请求等两三秒""" mdir = pathlib.Path("models") STATE["model"] = joblib.load(mdir / "lgbm.pkl") STATE["features"] = json.loads((mdir / "features.json").read_text()) @app.get("/healthz") def health(): return {"ok": "model" in STATE} @app.post("/predict") def predict(snap: Snapshot): if "model" not in STATE: raise HTTPException(503, "model not loaded") row = {"minute": snap.minute} for side in ("blue", "red"): for k, v in getattr(snap, side).dict().items(): row[f"{side}_{k}"] = v feats = build_features(pd.DataFrame([row]))[STATE["features"]] prob = float(STATE["model"].predict(feats)[0]) return {"win_prob": round(prob, 4)}

build_features在服务端被复用了，这是刻意的设计：训练和推理必须走同一个特征函数，否则训练时算gold_diff_pm用的是clip(lower=1)，推理时忘了加，1 分钟的快照就会除出天文数字。把特征构造抽成一个纯函数、两边都 import，是避免线上线下不一致最省心的办法。

SideStats的每个字段都给了默认值而不是强制必填，是因为前端早期版本可能只传经济和人头。缺字段填 0 在「经济差」这种差值特征上语义是对的（没数据就是没领先），但在avg_level上就不对——所以那里默认 1.0 而不是 0。这个细节不注意，模型会把「字段没传」理解成「等级为零」，概率直接偏到一边去。

5. 避坑与常见问题排查：五条让我返工的记录

5.1 AUC 0.98 但线上全是极端值

现象：离线评估 AUC 高得离谱，线上返回的概率几乎全在 0.95 以上或 0.05 以下，中间地带没有样本。

原因：训练时混入了结算字段（最终经济、总推塔数），加上随机切分让同一场比赛的不同快照跨了训练集和验证集。模型实际上是在背答案。

解决：特征白名单化，只允许显式列出的字段进入特征矩阵，禁止用filter(like=...)批量捞列；切分改成GroupShuffleSplit按match_id分组。改完之后 AUC 掉到 0.83，但线上概率分布正常了。

5.2 模型在低分段对局上系统性偏高

现象：整体 AUC 尚可，但拿低分段对局单独评估时，模型给优势方的概率明显偏高，翻盘局几乎全判错。

原因：采集样本时按「最近对局」拉取，高分段玩家对局多、被采到的概率大，训练集里高分段占比远高于真实分布。高分段滚雪球能力强，领先之后被翻的概率低，模型就把这个规律学成了通用规律。

解决：按分段分层采样，让各分段的样本量大致均衡；评估时也按分段切片看指标，而不是只看一个总分。如果产品只服务某个分段，那就干脆只训那个分段的数据，别贪多。

5.3 服务启动后第一个请求要等三秒

现象：/predict第一个请求耗时 3 秒多，后面就正常了，监控上看着像偶发超时。

原因：模型在请求处理函数里懒加载，joblib.load加上 LightGBM 初始化在第一次调用时才发生。

解决：挪到@app.on_event("startup")里，进程启动时加载一次，加载失败就让进程起不来（配合健康检查的healthz返回 503），而不是带着半残状态对外服务。同时把模型文件大小纳入发布检查，模型超过一定体积就该考虑裁剪树的数量或者做一次num_iteration截断。

5.4 缺字段填 0 导致概率偏向一方

现象：前端只传了经济和推塔，等级、视野字段缺失，返回的概率稳定偏向蓝方，且跟实际局势对不上。

原因：avg_level默认填 0，level_diff变成blue_level - 0，等于凭空给蓝方加了一个巨大优势。

解决：区分「缺失」和「为零」两种语义。对差值类特征，缺失时用训练集中位数填充；对等级这类不可能为零的字段，Pydantic 里设成必填并给合法下界。更进一步的做法是给每个特征加一个 missing 指示列，让模型自己学缺失模式。

5.5 概率不校准，用户不信

现象：模型说 0.7，实际统计下来这一档的真实胜率只有 0.55，用户反馈「这数字看着不准」。

原因：只看了 AUC，没看校准。LightGBM 在类别不平衡数据上输出的概率天然偏保守或偏激进。

解决：在独立验证集上拟合一层等渗回归做后校准，用 Brier 分数和校准曲线做验收指标。验收通过的标准不是「AUC 更高」，而是「每个概率分桶的预测均值和真实胜率偏差在 0.03 以内」。

6. 二次开发：换成你自己的数据源和胜负定义

拿到这个项目之后最常见的改造诉求，是换成自己手里的数据。项目里所有采集逻辑都收在src/collect/，特征构造收在src/features/build_features.py，模型只认特征矩阵不认原始字段，所以换数据源的实际工作量集中在两处：把新数据源的响应映射成Snapshot结构，以及确认新数据源里每个字段的「时间语义」是截至当前还是全场累计。

我一般会在src/collect/下加一个adapters/目录，一个数据源一个文件，对外只暴露一个to_snapshot(raw) -> dict函数：

# src/collect/adapters/base.py from abc import ABC, abstractmethod class MatchAdapter(ABC): """所有数据源适配器的统一契约""" @abstractmethod def list_matches(self, puuid: str, limit: int = 100) -> list[str]: """返回对局 ID 列表""" @abstractmethod def to_snapshot(self, raw: dict, minute: int) -> dict: """把原始响应转成标准快照结构，字段缺失填 None 而不是 0""" def extract_label(self, raw: dict) -> int: """1 表示蓝方获胜，子类按各自字段覆盖""" return int(raw["blue_win"])

关键在于to_snapshot里缺失字段填None而不是0，把「缺数据」的判断往后推到特征层统一处理。如果适配器里就填 0，后面根本分不清是真的零还是没采到。

第二类改造是改预测目标。有人想预测的不是最终胜负，而是「接下来 5 分钟内是否会被翻盘」，或者「这条大龙该不该打」。这类改造不用动模型代码，只需要在数据层重新打标签：把add_label换成按时间窗口计算的前向标签，然后注意一个坑——窗口标签会让样本量骤减，因为接近对局结束的快照没有「接下来 5 分钟」可言，这些样本必须显式剔除，不能拿最终结果凑数。

验证方法上，我强烈建议做一次时间外推验证：用前 80% 时间段的数据训练，后 20% 时间段的数据验证，而不是随机切。游戏版本会变，玩家整体水平会漂移，随机切分给出的指标往往比真实上线表现乐观。第一次跑时间外推验证的时候，我的 AUC 比随机切分低了将近 0.06，那个落差才是模型上线后要面对的真实世界。

最后说个习惯。从那以后我每次做这类「训练 + 服务」的项目，都在make train之后强制走一遍端到端冒烟：用三五个手写的极端快照（全零、超大经济差、1 分钟）打到/predict上，看返回的概率是不是落在合理区间。这一步能在五分钟内抓出特征顺序错、缺字段填错、模型版本没更新这三类问题，比上线之后被用户截图质疑强得多。希望帮到你。

本文还有配套的精品资源，点击获取