model-card

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Sports Model Card

体育模型卡片（Sports Model Card）

Outcome

成果（Outcome）

Create a versioned operating contract tied to user-owned model, data, metrics, feature, and validation artifacts. A model card describes an already evaluated model: what it is for, how it was tested, where it fails, and when to retrain or retire it.

A card is not a marketing page, experiment history, or substitute for evidence. Use

experiment-log

for the sequence of trials and

results-reporting

for the human-readable story of a particular evaluation.

创建一份与用户所有的模型、数据、指标、特征和验证工件绑定的版本化操作契约。模型卡片用于描述已完成评估的模型：其用途、测试方式、失效场景以及重新训练或退役的时机。

模型卡片并非营销页面、实验历史记录，也不能替代实证依据。实验序列请使用

experiment-log

，特定评估的可读性报告请使用

results-reporting

。

When to use this skill

何时使用此技能

Use it when:

a model has stable held-out evidence worth keeping;
promoting an accepted experiment into a named version;
preparing a model for reuse, handoff, review, or publication;
updating the documentation for a new immutable model version;
the user asks to document, freeze, or share a sports model.

Do not create a polished card to imply maturity that the model has not earned. If validation, a baseline, or decision-time legality is unknown, state that explicitly and mark the model unapproved for operational use.

适用于以下场景：

模型拥有值得留存的稳定留存验证证据；
将已通过的实验升级为命名版本；
为模型复用、交接、评审或发布做准备；
为新的不可变模型版本更新文档；
用户要求记录、冻结或共享体育模型。

请勿为尚未达到成熟度的模型制作精美的卡片以伪装成熟度。若验证、基准模型或决策时间的合法性未知，请明确说明并标记该模型未获准投入运营使用。

Required evidence

必备证据

stable model name and version;
owner, reviewers, creation date, and next review date;
intended users, decisions, and prohibited uses;
sport, competition, population, grain, target, and decision time;
data provenance, window, filters, exclusions, and immutable snapshot;
feature definitions and availability timing;
named naive and strong simple baselines;
validation design, fold boundaries, and metric definitions;
aggregate and fold-level results on identical held-out populations;
calibration, leakage, fairness, stability, and slice findings as applicable;
serialized model, environment information, and reproduction instructions;
monitoring, retraining, and retirement criteria.

Use

unknown

not tested

, or

not applicable

when truthful. Never fill a gap with an inferred value or a generic promise.

稳定的模型名称和版本；
所有者、评审者、创建日期及下次评审日期；
预期用户、决策场景及禁止用途；
运动项目、赛事、受众群体、粒度（grain）、目标及决策时间；
数据来源、时间范围、筛选条件、排除规则及不可变快照；
特征定义及可用时间节点；
已命名的朴素基准和强简单基准；
验证设计、折叠边界（fold boundaries）及指标定义；
在相同留存群体上的聚合结果和折叠层级结果；
适用情况下的校准（calibration）、数据泄露（leakage）、公平性、稳定性及切片分析结果；
序列化模型、环境信息及复现说明；
监控、重新训练及退役标准。

若信息未知，请使用

unknown

、

not tested

或

not applicable

如实标注。切勿用推断值或通用承诺填补空白。

Required sections

必备章节

Identity, ownership, status, and version
Intended use, users, decisions, and prohibited uses
Target, grain, prediction timestamp, horizon, and output semantics
Data sources, window, population, exclusions, and snapshot
Feature families, transformations, and time-safety rules
Baselines and candidate family
Validation design, fold construction, and metric definitions
Results with uncertainty, fold variation, slices, and calibration
Known limitations, failure modes, and misuse risks
Monitoring, retraining, review, and retirement rules
Artifact manifest, dependencies, and reproduction instructions
Approval history and linked experiments

For a fill-in structure, read

references/card_template.md

. Before defining monitoring or retirement rules, read

references/kill_conditions.md

and adapt the examples to the actual decision and metric.

身份信息、所有权、状态及版本
预期用途、用户、决策场景及禁止用途
目标、粒度、预测时间戳、时间范围（horizon）及输出语义
数据源、时间范围、受众群体、排除规则及快照
特征家族、转换规则及时间安全规则
基准模型及候选模型家族
验证设计、折叠构建及指标定义
包含不确定性、折叠差异、切片及校准的结果
已知局限性、失效模式及误用风险
监控、重新训练、评审及退役规则
工件清单、依赖项及复现说明
审批历史及关联实验

如需填空式结构，请阅读

references/card_template.md

。在定义监控或退役规则前，请阅读

references/kill_conditions.md

并根据实际决策和指标调整示例。

Workflow

工作流程

Confirm that the candidate met the predeclared acceptance rule on held-out data. If not, document it as experimental or abandoned rather than approved.
Verify the model version and immutable artifact identifiers.
Copy factual fields from experiment, data, feature, leakage, calibration, and validation artifacts; do not reconstruct them from memory.
State intended use narrowly and list explicit prohibited uses.
Describe data coverage, exclusions, label construction, and populations not represented by evaluation.
Document each feature family and prove availability at decision time.
Present candidate and baselines on identical folds and rows.
Summarize the primary metric first, then uncertainty, calibration, stability, and error slices.
Convert known failure modes into checkable monitoring and kill conditions.
Record exact artifact paths and reproduction instructions supplied by the user or environment.
Have a second reviewer trace every quantitative and operational claim.
Freeze the version; future substantive changes create a new card.

确认候选模型在留存数据上符合预先声明的验收规则。若未符合，请将其记录为实验性或已废弃模型，而非已批准模型。
验证模型版本及不可变工件标识符。
从实验、数据、特征、数据泄露、校准及验证工件中复制事实性字段；切勿凭记忆重构。
精准描述预期用途，并列出明确的禁止用途。
描述数据覆盖范围、排除规则、标签构建方式及未被评估覆盖的受众群体。
记录每个特征家族，并证明其在决策时间点可用。
在相同折叠和行上展示候选模型与基准模型的对比。
先总结主要指标，再说明不确定性、校准、稳定性及错误切片。
将已知失效模式转换为可检查的监控和终止条件。
记录用户或环境提供的精确工件路径及复现说明。
由第二位评审者追踪每一项量化和运营声明。
冻结版本；未来的实质性变更需创建新卡片。

Status and freeze rules

状态与冻结规则

Event	Card action
First candidate meeting the charter	create version `v1` and mark evaluated
Feature definition or target changes	new major or minor version; new card
Data window or source snapshot changes	new version and fresh validation
Hyperparameter change	new version linked to the originating experiment
Editorial correction only	revise in place with dated correction note
Kill condition fires	mark retired or abandoned; preserve prior evidence
Reproduction no longer works	mark non-reproducible until repaired and reviewed

Freeze only when data snapshot, feature set, configuration, serialized model, and validation results are immutable. Never silently edit a frozen card to make history look better.

事件	卡片操作
首个符合章程的候选模型	创建版本 `v1` 并标记为已评估
特征定义或目标变更	新的主版本或次版本；创建新卡片
数据时间范围或源快照变更	新版本及全新验证
超参数变更	新版本关联至源实验
仅编辑性修正	原地修订并添加日期修正说明
终止条件触发	标记为已退役或已废弃；保留原有证据
复现失败	标记为不可复现，直至修复并通过评审

仅当数据快照、特征集、配置、序列化模型及验证结果均不可变时，方可冻结版本。切勿悄悄编辑已冻结的卡片以美化历史记录。

Result presentation

结果呈现

Claim	Required evidence in the card
Better win probabilities	log-loss or Brier versus baseline on same folds
Useful probability levels	calibration curve/table and calibration error context
Better margin prediction	MAE or RMSE versus constant/simple rating baseline
Stable team ranking	out-of-time rank utility and rank stability
General across seasons	per-season results, not aggregate mean alone
General across populations	evaluated slice results and coverage statement

State metric direction. “0.681 versus 0.693” is incomplete unless the card says lower log-loss is better, gives sample size, and identifies the held-out period.

声明	卡片中需包含的必备证据
更优获胜概率	相同折叠上与基准模型对比的log-loss或Brier值
有用的概率水平	校准曲线/表格及校准误差上下文
更优分差预测	与常量/简单评分基准对比的MAE或RMSE值
稳定的团队排名	跨时间的排名效用及排名稳定性
跨赛季通用性	分赛季结果，而非仅聚合均值
跨群体通用性	已评估的切片结果及覆盖范围说明

需说明指标方向。“0.681 vs 0.693”表述不完整，卡片需补充说明log-loss越低越好、样本量及留存周期。

Monitoring and kill conditions

监控与终止条件

Conditions must be observable, bounded, and connected to a response. Good forms include:

primary metric loses to the locked baseline for two consecutive review windows;
calibration error exceeds a specified threshold for a minimum sample size;
a required field's missingness or schema changes invalidate a feature family;
a leakage audit becomes unresolved or fails;
a rule, schedule, roster, or measurement regime changes beyond evaluated scope;
population coverage moves outside the documented range;
reproduction fails from the pinned artifacts and supported environment.

For each trigger, record owner, check cadence, minimum evidence, grace period, and action: investigate, retrain, restrict, roll back, or retire. Avoid conditions such as “when performance feels bad.”

条件必须可观测、有边界且关联响应动作。规范示例包括：

连续两个评审周期内主要指标劣于锁定的基准模型；
校准误差超过指定阈值且达到最小样本量；
必填字段缺失或 schema 变更导致某特征家族失效；
数据泄露审计未解决或失败；
规则、赛程、名单或测量机制变更超出评估范围；
群体覆盖范围超出文档记录的范围；
基于固定工件及支持环境无法复现模型。

针对每个触发条件，记录所有者、检查频率、最小证据要求、宽限期及动作：调查、重新训练、限制使用、回滚或退役。避免“当性能不佳时”这类模糊条件。

Sports-specific caveats

体育领域特定注意事项

State whether the model scores games, team-games, player-games, possessions, plays, or pitches. A doubled team-game panel is not game-level independence.
Define treatment of ties, overtime, postseason events, neutral venues, and canceled or incomplete contests.
Document schedule-strength, expansion, rule-era, roster, and source changes that may limit transport across seasons.
Pre-event models must state the exact cutoff and how late injury, lineup, starter, weather, or market information is handled.
Team or player identifiers must be stable across relocations and name changes.
If probabilities drive decisions, document calibration and any threshold or utility assumptions; accuracy alone is insufficient.

需说明模型是为比赛、球队-比赛、球员-比赛、控球、回合还是投球打分。双倍的球队-比赛面板并非比赛级别的独立数据。
定义平局、加时赛、季后赛、中立场地及取消或未完成赛事的处理方式。
记录赛程强度、球队扩张、规则时代、名单及数据源变更等可能限制跨赛季迁移的因素。
赛前模型需明确说明精确的截止时间，以及晚到的伤病、阵容、首发、天气或市场信息的处理方式。
球队或球员标识符需在球队搬迁及更名后保持稳定。
若概率驱动决策，需记录校准情况及任何阈值或效用假设；仅准确率不足以支撑决策。

Hard constraints and integrity rules

硬约束与完整性规则

Never describe training metrics as expected performance.
Never omit the baseline, decision time, grain, or primary metric.
Never claim generality beyond evaluated sports, seasons, and populations.
Never publish a card without artifact locations, an owner, and review date.
Never leave retirement criteria implicit.
Never hide leakage, validation, or calibration status.
Never describe exploration as production-ready.
Never list a reproduction command that does not match the represented version.
Never overwrite a frozen model history with a better-looking later result.
If required evidence is unavailable, state the operational consequence.

切勿将训练指标描述为预期性能。
切勿遗漏基准模型、决策时间、粒度或主要指标。
切勿声称超出已评估的运动项目、赛季及群体的通用性。
切勿在未提供工件位置、所有者及评审日期的情况下发布卡片。
切勿将退役标准隐含化。
切勿隐瞒数据泄露、验证或校准状态。
切勿将探索性模型描述为可投入生产使用。
切勿列出与所示版本不匹配的复现命令。
切勿用后期更优的结果覆盖已冻结的模型历史。
若必备证据不可用，请说明运营影响。

Anti-patterns

反模式

“Works well” with no metric, baseline, period, or denominator;
a card written before any ordered held-out evaluation exists;
one aggregate score with losing folds omitted;
NFL wording, assumptions, or commands copied into another sport's card;
kill conditions that cannot be computed;
a feature list without as-of availability;
a generic “bias reviewed” statement with no slice, definition, or result;
a model filename that cannot be connected to its data and configuration.

仅称“效果良好”，未提供指标、基准模型、周期或分母；
在有序留存评估完成前编写卡片；
仅展示聚合分数，省略表现不佳的折叠；
将NFL的表述、假设或命令复制到其他运动项目的卡片中；
无法计算的终止条件；
未标注可用时间的特征列表；
仅泛泛称“已审核偏差”，未提供切片、定义或结果；
无法关联至对应数据和配置的模型文件名。

Worked examples

示例

Pre-game team-win probability

赛前球队获胜概率

text

Identity: home_form_logit_v3
Status: evaluated; not approved for wagering
Purpose: Estimate pre-event P(team wins) from venue and shifted form
Grain: team-game; paired rows share one contest
Decision time: scheduled start, before event-day updates
Data: completed regular-season games, 2018-2024; immutable Parquet snapshot
Validation: season walk-forward; primary metric log-loss
Baseline: constant training-fold prevalence
Result: report mean and every held-out season on identical rows
Leakage: checked; all rolling features shifted before aggregation
Limit: no injury or lineup model; cold start in early season
Kill: retire after two eligible seasons worse than baseline log-loss
Artifacts: data snapshot, feature manifest, fold metrics, predictions, model file

text

Identity: home_form_logit_v3
Status: evaluated; not approved for wagering
Purpose: Estimate pre-event P(team wins) from venue and shifted form
Grain: team-game; paired rows share one contest
Decision time: scheduled start, before event-day updates
Data: completed regular-season games, 2018-2024; immutable Parquet snapshot
Validation: season walk-forward; primary metric log-loss
Baseline: constant training-fold prevalence
Result: report mean and every held-out season on identical rows
Leakage: checked; all rolling features shifted before aggregation
Limit: no injury or lineup model; cold start in early season
Kill: retire after two eligible seasons worse than baseline log-loss
Artifacts: data snapshot, feature manifest, fold metrics, predictions, model file

Margin model with incomplete calibration scope

校准范围不完整的分差模型

text

Identity: pregame_margin_ridge_v1
Purpose: Predict home-team final margin before lineup lock
Primary metric: MAE versus historical-mean and simple-rating baselines
Calibration: not applicable to point predictions; interval coverage not tested
Status: experimental until prediction-interval coverage is evaluated

The second example does not manufacture a calibration claim; it states the missing uncertainty check and constrains status accordingly.

text

Identity: pregame_margin_ridge_v1
Purpose: Predict home-team final margin before lineup lock
Primary metric: MAE versus historical-mean and simple-rating baselines
Calibration: not applicable to point predictions; interval coverage not tested
Status: experimental until prediction-interval coverage is evaluated

第二个示例未编造校准声明；它明确指出缺失的不确定性检查，并相应限制了模型状态。

Helper

辅助工具

bash

python <path-to-model-card>/scripts/write_card_stub.py \
  --name home-form-logit \
  --version v1 \
  --grain team-game \
  --out data/model_card.md

Fill the generated user-owned Markdown file from verified artifacts. The helper creates structure only; it does not validate performance or approve the model.

bash

python <path-to-model-card>/scripts/write_card_stub.py \
  --name home-form-logit \
  --version v1 \
  --grain team-game \
  --out data/model_card.md

从已验证的工件中填充生成的用户所有Markdown文件。该辅助工具仅创建结构；不验证性能或批准模型。

Output contract

输出契约

A complete card has:

every required section present;
baseline and primary metric beside candidate results;
aggregate, fold-level, and applicable slice evidence;
decision time and time-safety status;
explicit leakage and calibration status;
concrete monitoring, retraining, and kill conditions;
linked experiments and immutable artifact identifiers;
exact reproduction instructions;
version status, owner, reviewers, and next review date.

完整的卡片需包含：

所有必备章节；
候选模型结果旁标注基准模型及主要指标；
聚合、折叠层级及适用的切片证据；
决策时间及时间安全状态；
明确的数据泄露及校准状态；
具体的监控、重新训练及终止条件；
关联实验及不可变工件标识符；
精确的复现说明；
版本状态、所有者、评审者及下次评审日期。

Resources

资源

```
references/card_template.md
```
— read when drafting the full card section by section.
```
references/kill_conditions.md
```
— read when converting failure modes into measurable monitoring and retirement rules.
```
scripts/write_card_stub.py
```
— portable model-card scaffold writer.

```
references/card_template.md
```
— 逐节编写完整卡片时阅读。
```
references/kill_conditions.md
```
— 将失效模式转换为可测量的监控和退役规则时阅读。
```
scripts/write_card_stub.py
```
— 可移植的模型卡片脚手架生成器。