---
tags: [nanochat, eval, reporting]
阶段: 08-评测Eval
难度: ★★☆
created: 2026-10-22
related: "[[评测方法论]], [[GSM8K与HumanEval]], [[如何解读指标]], [[实验记录模板]]"
---

# 生成report成绩单

## 定义

**成绩单**（scorecard）指把一次训练的评测产物与训练元数据汇总成一张可复算的 Markdown 表：每个单元格都标注来源脚本、采集命令与缺失时的处理方式，使他人能够只凭这张表重跑评测或核对数字。成绩单不是新指标，它不引入任何计算，只做汇总与标注。

符号与术语定义如下。

- **产物**（artifact）：脚本写出的可持久化结果，包括 CSV、日志、JSON 与 checkpoint 元数据。
- **CORE CSV**：`scripts/base_eval.py` 在 `--eval=core` 时写出的分任务表，路径为 `{base_dir}/base_eval/{model_slug}.csv`。
- **`model_slug`**：CSV 文件名，格式 `base_model_{step:06d}`，例如 step 16704 对应 `base_model_016704.csv`。
- **聊天日志**：`scripts/chat_eval.py` 的 stdout 重定向文件；该脚本不写文件，只能通过管道或 `tee` 留存。
- **推理 JSON**：`scripts/infer_bench.py` 打印在 stdout 最后一行的单行 JSON。
- **元数据**（`meta_*.json`）：训练脚本保存的检查点元数据，含 `model_config`、`val_bpb`、`loop_state.total_training_time`。
- **run summary**：wandb 对一次 run 的汇总，包含被记录指标的最后一个值。
- **TTFT**：time to first token，从开始生成到第一个 token 的时间。
- **TPOT**：time per output token，解码阶段每生成一个 token 的中位耗时。
- **MBU**：模型带宽利用率，解码阶段实际搬移字节数与峰值带宽之比。
- **可复算性**：给定同一检查点与同一命令，任一单元格的数值可以重现。

## 为什么重要

评测数字天然分散在四处：CORE 在本地 CSV，ChatCORE 只在终端输出，推理性能在另一条命令的 JSON，训练成本在 checkpoint 元数据。若不做汇总，三类后果随之出现。

第一，跨 run 比较失去统一口径。两次训练可能用了不同的 `--max-per-task`、不同的评测精度、不同的 chat 任务子集；只把两行数字并排，无法判断差异来自模型还是协议。第二，缺失被静默填成零。`chat_eval` 在任务不全时不打印 ChatCORE，若汇总脚本默认缺失为 0，成绩单会把「未测」写成「0.0000」，读者无法区分。第三，数字无法回溯。leaderboard 的每一行都带 commit、日期与命令，成绩单若没有同样的字段，就无法回答「这个 CORE 是在哪个 commit 上、用什么数据、跑了几张卡得到的」。

成绩单还承担交接职责。本库 10 阶段的实验记录与 [[实验记录模板]] 需要一组固定字段；成绩单是这些字段的取值来源，而不是另起一套格式。因此本阶段把「字段—来源—命令」的对应关系写成表，任何新增字段都必须先能回答它来自哪条命令。

在三个维度中，本篇完全属于「懂工程」：没有新公式，只有产物格式、解析边界与缺失标注。

## 原理与推导

### 1. 仓库现状：没有 `report.py`

当前快照（commit 92d63d4）中不存在 `scripts/report.py`，也不存在任何名为 report 的脚本。README 的文件结构只列出九个脚本：`base_eval.py`、`base_train.py`、`chat_cli.py`、`chat_eval.py`、`chat_rl.py`、`chat_sft.py`、`infer_bench.py`、`tok_eval.py`、`tok_train.py`。成绩单是由三类评测产物与训练元数据拼接出来的，不是某条命令的直接输出。

这一现状的后果是：成绩单的生成方式必须由使用者自己维护。仓库把「评测」与「汇总」分开，评测脚本各自只写自己那一种格式，汇总逻辑留给下游；好处是每个脚本保持最小、可单独运行，代价是跨 run 比较没有官方工具。本篇给出的脚本是对这一空缺的补充，而不是对仓库已有文件的描述。

因此任何文档都不应写「运行 `python -m scripts.report` 生成成绩单」。当前可执行的只有三条评测命令，加上读取 checkpoint 元数据。

### 2. 源一：`base_eval` 的 CORE CSV

`scripts/base_eval.py` 的 `evaluate_core` 返回三个字段：`results`（每任务原始准确率）、`centered_results`（每任务中心化值）、`core_metric`（22 项均值）。只有 `--eval` 包含 `core` 时才会执行；写文件只在 `ddp_rank == 0` 时发生。

```python
output_csv_path = os.path.join(base_dir, "base_eval", f"{model_slug}.csv")
os.makedirs(os.path.dirname(output_csv_path), exist_ok=True)
with open(output_csv_path, 'w', encoding='utf-8', newline='') as f:
    f.write(f"{'Task':<35}, {'Accuracy':<10}, {'Centered':<10}\n")
    for label in core_results["results"]:
        acc = core_results["results"][label]
        centered = core_results["centered_results"][label]
        f.write(f"{label:<35}, {acc:<10.6f}, {centered:<10.6f}\n")
    f.write(f"{'CORE':<35}, {'':<10}, {core_results['core_metric']:<10.6f}\n")
```

格式有三个必须处理的细节。第一，表头与数据行都在逗号后带一个空格，字段宽度分别固定为 35、10、10 字符，解析时必须 `strip`。第二，`CORE` 行的 `Accuracy` 列是空字符串（十格空白），因此不能对该列无条件 `float`。第三，任务数由 eval bundle 的 `core.yaml` 决定，仓库快照不含 bundle，文档中的「22 项」是论文与 notebook 的口径，实际行数以 CSV 为准。

该文件还有第二个消费者：`dev/estimate_gpt3_core.ipynb` 的 `parse_csv` 读取同格式的 GPT-2 CSV，并以 `results['CORE']['centered']` 取总分。这说明三列结构是跨版本的稳定接口，解析器应尽量宽松而不是假设固定行数。

### 3. 源二：`chat_eval` 的 stdout

`scripts/chat_eval.py` 不写文件。它按任务打印两类行：

```text
==================================================
Final: 200/2376 (8.42%)
ARC-Easy accuracy: 8.42%
```

`Final` 行由 `run_categorical_eval` 或 `run_generative_eval` 打印，给出该任务通过数与总数；任务名与准确率由主循环打印。只有 5 个任务全部出现在 `results` 中时才计算并打印 ChatCORE：

```python
all_tasks_were_evaluated = all(task_name in results for task_name in all_tasks)
if all_tasks_were_evaluated:
    # 逐任务中心化与累加的完整循环见 `scripts/chat_eval.py` 的 `all_tasks_were_evaluated` 分支
    print0(f"ChatCORE metric: {chatcore_metric:.4f}")
```

因此成绩单必须区分三种状态：5 个任务全测且打印 ChatCORE；任务不全、ChatCORE 未打印；任务全测但 stdout 被截断。第二种状态不能补 0，只能写「未测」。为了留存 stdout，推荐在命令末尾加 `| tee chat_eval_sft.log`；`torchrun` 的多 rank 输出会混在一起，但 `print0` 保证汇总行只来自 rank 0。

### 4. 源三：`infer_bench` 的末行 JSON

`scripts/infer_bench.py` 同时输出人类可读卡片与机器可读 JSON，JSON 固定在 stdout 最后一行：

```python
print(json.dumps(payload))
```

`payload` 的字段可分四组。模型与硬件：`source`、`step`、`model_config`、`gpu`、`num_params`、`param_dtypes`、`weight_bytes`、`peak_bandwidth_bytes_per_sec`、`peak_flops_per_sec`、`total_vram_bytes`。KV 与上下文：`kv_bytes_per_token`、`kv_read_bytes_per_step`、`context_mid`、`prompt_tokens`、`decode_tokens`。预填充：`prefill` 的 `tok_per_sec`、`mfu_percent`、`time_sec`。批扫描：`sweep` 数组，每项含 `batch_size`、`ttft_sec`、`tpot_sec`、`tok_per_sec`、`mbu_percent`、`mfu_percent`、`peak_vram_bytes`、`decode_steps`。

三个使用约束。第一，脚本断言 `device_type == "cuda"` 且 `ddp_world_size == 1`，多卡或非 CUDA 会直接失败。第二，提示长度被截断到 `sequence_len - decode_tokens`，截断时会打印提示，成绩单若引用 `prompt_tokens` 必须同时记录这一截断。第三，`weight_bytes` 按参数存储 dtype 计算，fp8 与 bf16 检查点的该字段不同，跨 dtype 比较 MBU 时要注意分母。

### 5. 源四：`meta_*.json`

`nanochat/checkpoint_manager.py` 的 `save_checkpoint` 在 `rank == 0` 时写出 `meta_{step:06d}.json`。`base_train.py` 写入的字段包括：

```python
{
    "step": step,
    "val_bpb": val_bpb,
    "model_config": model_config_kwargs,
    "user_config": user_config,
    "device_batch_size": args.device_batch_size,
    "max_seq_len": args.max_seq_len,
    "total_batch_size": total_batch_size,
    "loop_state": {"min_val_bpb": min_val_bpb, "total_training_time": total_training_time},
}
```

成绩单从中取三类信息：模型规格（`n_layer`、`n_embd`、`n_head`、`n_kv_head`、`sequence_len`、`vocab_size`、`window_pattern`）、质量参照（`val_bpb`、`min_val_bpb`）、成本（`total_training_time` 秒）。`user_config` 保存训练命令行参数，是复现实验的关键字段，但它不包含评测参数，评测参数必须单独记录。

`chat_sft.py` 保存的元数据结构类似，但 `val_bpb` 是 SFT 验证集的 bpb，与 base 的 bpb 不可比；成绩单必须标注来源模型阶段。

### 6. wandb 与本地 CSV 的关系

三个训练脚本的 wandb 项目名分别是 `nanochat`（base）、`nanochat-sft`（SFT）、`nanochat-rl`（RL），run 名由 `--run` 给出；`--run=dummy` 时使用 `DummyWandb`，不联网记录。被记录的键包括：

| 脚本 | 键 | 含义 |
|---|---|---|
| `base_train.py` | `val/bpb` | 验证集 bpb，每 `--eval-every` 步 |
| `base_train.py` | `core_metric` | 训练期 CORE，每 `--core-metric-every` 步 |
| `base_train.py` | `centered_results` | 22 项中心化值的字典 |
| `chat_sft.py` | `chatcore_metric`、`chatcore_cat` | ChatCORE 与 3 个 categorical 任务的均值 |
| `chat_sft.py` | `chatcore/<task>` | 每个任务的准确率 |
| `chat_rl.py` | `pass@1` 至 `pass@B` | GSM8K 的 pass@k |

wandb 与本地 CSV 的分工是：CSV 是 `base_eval.py` 的产物，只在显式运行该脚本且启用 `--eval=core` 时生成；wandb 是训练过程的记录，训练期的 CORE 通常用 `--core-metric-max-per-task=500` 的快速估计，不是全量结果。因此不能用 wandb 的 `core_metric` 代替 CSV 的 CORE 行。leaderboard 报告的 `core_metric`、`total_training_time`、`val_bpb` 来自 run summary，但排行榜要求的是最终全量 CORE；两者同名不同源，这是最容易混淆的一处。

wandb 的另一个限制是它保存的是时间序列与汇总，不保存评测协议。若 run 的 `--core-metric-max-per-task` 被改过，历史曲线就会混入不同口径的点；成绩单必须写明最终数字取自哪次显式评测，而不是曲线上的最后一个点。

### 7. 成绩单的字段设计

字段按六个小节组织，每节只回答一个问题。

| 小节 | 字段 | 来源 | 缺失时 |
|---|---|---|---|
| 模型信息 | 标签、step、深度、宽度、头数、上下文、词表、窗口模式 | `meta_*.json` | 写「未记录」并注明缺少 meta |
| 预训练质量 | CORE、22 项分项、val bpb、train bpb | CORE CSV 与 `base_eval` stdout | CORE 缺失时整节标「未测」 |
| 对话质量 | ChatCORE、5 个任务准确率 | `chat_eval` stdout | 任务不全时写「未测」，不补 0 |
| 推理性能 | TTFT、TPOT、tok/s、MBU、VRAM、prefill tok/s | `infer_bench` 末行 JSON | 未运行则整节标「未测」 |
| 成本 | 训练墙钟、GPU 小时、节点单价、估算成本 | `meta_*.json` 与外部单价 | 缺 `total_training_time` 时只报小时数 |
| 复现信息 | commit、数据 shard 数、GPU 型号、评测命令 | 手工填写 | 缺任一项则该行标「未记录」 |

成本口径容易出错：README 中「8×H100 约 24 美元/小时」指节点价，`total_training_time` 是训练迭代的墙钟秒数（不含评测与日志）。因此估算成本 $=(\text{秒}/3600)\times\text{节点价}$，GPU 小时 $=8\times(\text{秒}/3600)$。把节点价当成单卡价再乘 8，会得到 8 倍偏高的成本。

### 8. 汇总脚本的结构

脚本只依赖标准库，四个解析函数对应四类产物，一个渲染函数生成 Markdown。设计上有三个取舍。

第一，读取一律用 `utf-8-sig`。Windows 上用 PowerShell 重定向的日志常带 BOM，`utf-8` 会在第一行抛 `JSONDecodeError`；`utf-8-sig` 同时兼容有 BOM 与无 BOM。第二，CSV 用 `csv.reader` 而不是 `split(",")`，避免任务名含逗号时错列；解析后逐格 `strip`，并跳过表头与空行。第三，缺失产物用 `None` 表示，渲染时写「未测」，不写 0；ChatCORE 未打印时同理。

脚本已在合成产物上验证：用 `base_eval` 的格式字符串生成 CSV、用 `chat_eval` 的输出行生成日志、用 `infer_bench` 的字段结构生成 JSON，运行后得到含五个小节的 Markdown，成本一节在 `total_training_time=10949.46713`、节点价 24 时给出 73.00 美元。

### 在 nanochat 中的落地

第一处是 `scripts/base_eval.py` 的 CSV 写入。它是本阶段唯一由脚本持久化的评测产物，路径与文件名由 `model_slug` 决定；改动 `model_slug` 会使下游脚本找不到文件。

第二处是 `scripts/chat_eval.py` 的打印格式。任务行的 `X accuracy: Y%` 与总分行的 `ChatCORE metric: Z` 是日志解析的契约；改动格式会破坏所有下游解析器。

第三处是 `scripts/infer_bench.py` 的末行 JSON。它承诺「最后一行是合法 JSON」，因此解析器应从后向前找第一个 `{` 开头的行，而不是假设行号。

第四处是 `nanochat/checkpoint_manager.py` 的 `save_checkpoint`。`meta_{step:06d}.json` 与 `model_{step:06d}.pt` 同目录，成绩单通过目录名推断模型标签，通过 step 关联 CSV。

## 关键直觉

> [!tip] 成绩单是「数字到命令」的映射，而不是一组新的数字
> 每个单元格都必须能回答三个问题：这个数由哪个脚本产生、用了什么参数、缺失时如何标注。三个问题答不全，数字就不可复算。这解释了为什么成绩单要保留评测命令与 commit，也解释了为什么「未测」不能写成 0：0 是一个有效测量值，而「未测」表示该维度的证据不存在。与严格定义的关系：定义中的「可复算性」要求同一检查点加同一命令能重现数值，因此成绩单的最小完备集是检查点标识、命令、产物路径与数值四者，缺一不可。

## 例子与代码

### 1. 完整汇总脚本

以下脚本保存为任意路径后可直接运行，输入为四条命令的产物。

```python
#!/usr/bin/env python3
"""把三类评测产物汇总成一张 Markdown 成绩单。

输入（全部由 nanochat 现有脚本产生，仓库当前 master 没有 report.py）：
  --core    ~/.cache/nanochat/base_eval/base_model_{step:06d}.csv   （scripts/base_eval.py）
  --chat    chat_eval 的 stdout 重定向文件                        （scripts/chat_eval.py）
  --infer   infer_bench 的 stdout 重定向文件（取最后一行 JSON）    （scripts/infer_bench.py）
  --meta    <checkpoint_dir>/meta_{step:06d}.json                    （训练时保存）
输出：Markdown，写到 --out 或 stdout。
"""
import argparse
import csv
import json
import re
from pathlib import Path

CHAT_ACC_RE = re.compile(r"^(\S+) accuracy: ([0-9.]+)%$", re.MULTILINE)
CHATCORE_RE = re.compile(r"ChatCORE metric: (-?[0-9.]+)")
BASELINES = {"ARC-Easy": 0.25, "ARC-Challenge": 0.25, "MMLU": 0.25,
             "GSM8K": 0.0, "HumanEval": 0.0}


def parse_core_csv(path):
    """返回 ([(task, accuracy, centered), ...], core)。跳过表头与 CORE 行。"""
    rows, core = [], None
    with open(path, encoding="utf-8-sig", newline="") as f:
        for parts in csv.reader(f):
            cells = [c.strip() for c in parts]
            if len(cells) < 3 or cells[0] in ("", "Task"):
                continue
            if cells[0] == "CORE":
                core = float(cells[2])
                continue
            rows.append((cells[0], float(cells[1]), float(cells[2])))
    return rows, core


def parse_chat_log(path):
    """返回 ({任务: 准确率}, ChatCORE 或 None)。"""
    text = Path(path).read_text(encoding="utf-8-sig")
    accs = {m.group(1): float(m.group(2)) / 100.0 for m in CHAT_ACC_RE.finditer(text)}
    m = CHATCORE_RE.search(text)
    return accs, (float(m.group(1)) if m else None)


def parse_infer_bench(path):
    """infer_bench 把机器可读结果打印在 stdout 的最后一行。"""
    for line in reversed(Path(path).read_text(encoding="utf-8-sig").splitlines()):
        line = line.strip()
        if line.startswith("{") and line.endswith("}"):
            return json.loads(line)
    raise ValueError("没有在 infer_bench 输出中找到 JSON 行")


def centered(acc, baseline):
    return (acc - baseline) / (1.0 - baseline)


def build_markdown(core_rows, core, chat_accs, chatcore, infer, meta, node_cost_per_hour):
    cfg = meta.get("model_config", {})
    loop = meta.get("loop_state", {})
    secs = loop.get("total_training_time")
    hours = secs / 3600.0 if secs else None
    cost = hours * node_cost_per_hour if hours is not None else None
    lines = []
    lines.append("# 成绩单")
    lines.append("")
    lines.append("## 1. 模型信息")
    lines.append("")
    lines.append("| 项 | 值 | 来源 |")
    lines.append("|---|---|---|")
    lines.append(f"| 模型标签 | {meta.get('model_tag', '未记录')} | 目录名 |")
    lines.append(f"| 步数 | {meta.get('step')} | meta.json |")
    lines.append(f"| 深度 n_layer | {cfg.get('n_layer')} | meta.json |")
    lines.append(f"| 宽度 n_embd | {cfg.get('n_embd')} | meta.json |")
    lines.append(f"| 注意力头 n_head / n_kv_head | {cfg.get('n_head')} / {cfg.get('n_kv_head')} | meta.json |")
    lines.append(f"| 上下文 sequence_len | {cfg.get('sequence_len')} | meta.json |")
    lines.append(f"| 词表 | {cfg.get('vocab_size')} | meta.json |")
    lines.append(f"| 窗口模式 | {cfg.get('window_pattern')} | meta.json |")
    lines.append("")
    lines.append("## 2. CORE（base 模型）")
    lines.append("")
    lines.append("| 任务 | Accuracy | Centered |")
    lines.append("|---|---|---|")
    for task, acc, cent in core_rows:
        lines.append(f"| {task} | {acc:.6f} | {cent:.6f} |")
    lines.append(f"| CORE | - | {core:.6f} |")
    lines.append("")
    lines.append("## 3. ChatCORE（chat 模型）")
    lines.append("")
    lines.append("| 任务 | 准确率 | 基线 | Centered |")
    lines.append("|---|---|---|---|")
    for task, base in BASELINES.items():
        acc = chat_accs.get(task)
        if acc is None:
            lines.append(f"| {task} | 未测 | {base:.2f} | - |")
        else:
            lines.append(f"| {task} | {acc:.4f} | {base:.2f} | {centered(acc, base):.4f} |")
    lines.append(f"| ChatCORE | - | - | {chatcore:.4f} |" if chatcore is not None
                 else "| ChatCORE | - | - | 未测 |")
    lines.append("")
    lines.append("## 4. 推理性能（infer_bench）")
    lines.append("")
    if infer:
        prefill = infer.get("prefill", {})
        lines.append("| 项 | 值 |")
        lines.append("|---|---|")
        lines.append(f"| GPU | {infer.get('gpu')} |")
        lines.append(f"| 参数量 | {infer.get('num_params'):,} |")
        lines.append(f"| 权重字节 | {infer.get('weight_bytes'):,} |")
        lines.append(f"| KV 每 token 字节 | {infer.get('kv_bytes_per_token'):,} |")
        lines.append(f"| prefill tok/s | {prefill.get('tok_per_sec'):,.1f} |")
        lines.append(f"| prefill MFU % | {prefill.get('mfu_percent'):.2f} |")
        lines.append("")
        lines.append("| batch | TTFT ms | TPOT ms | tok/s | MBU % | MFU % | VRAM GiB |")
        lines.append("|---|---|---|---|---|---|---|")
        for point in infer.get("sweep", []):
            lines.append(
                f"| {point['batch_size']} | {point['ttft_sec'] * 1e3:.1f} | "
                f"{point['tpot_sec'] * 1e3:.2f} | {point['tok_per_sec']:,.0f} | "
                f"{point['mbu_percent']:.1f} | {point['mfu_percent']:.2f} | "
                f"{point['peak_vram_bytes'] / 2**30:.2f} |")
    else:
        lines.append("未测。")
    lines.append("")
    lines.append("## 5. 成本")
    lines.append("")
    lines.append("| 项 | 值 |")
    lines.append("|---|---|")
    lines.append(f"| 训练墙钟（秒） | {secs:.1f} |" if secs is not None else "| 训练墙钟（秒） | 未记录 |")
    lines.append(f"| GPU 小时（8 卡） | {8 * hours:.2f} |" if hours is not None else "| GPU 小时（8 卡） | 未记录 |")
    lines.append(f"| 节点单价（美元/小时） | {node_cost_per_hour:.2f} |")
    lines.append(f"| 估算成本（美元） | {cost:.2f} |" if cost is not None else "| 估算成本（美元） | 未记录 |")
    lines.append("")
    return "\n".join(lines)


def main():
    parser = argparse.ArgumentParser(description="汇总 nanochat 评测产物为 Markdown 成绩单")
    parser.add_argument("--core", required=True)
    parser.add_argument("--chat", default=None)
    parser.add_argument("--infer", default=None)
    parser.add_argument("--meta", required=True)
    parser.add_argument("--out", default=None)
    parser.add_argument("--node-cost-per-hour", type=float, default=24.0)
    args = parser.parse_args()

    core_rows, core = parse_core_csv(args.core)
    chat_accs, chatcore = ({}, None)
    if args.chat:
        chat_accs, chatcore = parse_chat_log(args.chat)
    infer = parse_infer_bench(args.infer) if args.infer else None
    meta = json.loads(Path(args.meta).read_text(encoding="utf-8-sig"))
    meta["model_tag"] = Path(args.meta).resolve().parent.name
    md = build_markdown(core_rows, core, chat_accs, chatcore, infer, meta, args.node_cost_per_hour)
    if args.out:
        Path(args.out).write_text(md, encoding="utf-8")
    else:
        print(md)


if __name__ == "__main__":
    main()
```

### 2. 采集三条命令的产物

```bash
# base：CSV 自动落盘，stdout 只需看 bpb
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.base_eval -- \
    --model-tag=d24 --eval=core,bpb | tee base_eval.log

# chat：日志必须自己留存
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- \
    -i sft -a 'ARC-Easy|ARC-Challenge|MMLU|GSM8K|HumanEval' | tee chat_eval_sft.log

# 推理：末行 JSON 在 infer_bench.log 的最后一行
python -m scripts.infer_bench -i sft -g d24 | tee infer_bench.log

# 汇总：路径中的 step 与 CSV、meta 文件名一致
python make_report.py \
    --core ~/.cache/nanochat/base_eval/base_model_016704.csv \
    --chat chat_eval_sft.log \
    --infer infer_bench.log \
    --meta ~/.cache/nanochat/base_checkpoints/d24_jan29/meta_016704.json \
    --node-cost-per-hour 24 \
    --out scorecard.md
```

### 3. 成绩单模板

下表以 leaderboard Run 1 的真实数值填充已知项，未知项标注「未测」而不是填 0。Run 1 使用 d24、commit `348fbb3`、2026-01-29，CORE 0.25851，val bpb 0.74833，训练墙钟 10949 秒。

```markdown
# 成绩单 · d24_jan29

### 1. 模型信息
| 项 | 值 |
|---|---|
| 模型标签 | d24_jan29 |
| 步数 | 16704 |
| 深度 / 宽度 | 24 / 1536 |
| 注意力头 | 12（GQA 下 n_kv_head 同为 12） |
| 上下文 / 词表 | 2048 / 32768 |
| commit | 348fbb3 |

### 2. 预训练质量
| 项 | 值 | 来源 |
|---|---|---|
| CORE | 0.25851 | base_eval CSV 的 CORE 行 |
| val bpb | 0.74833 | meta.json |
| 训练墙钟 | 10949 秒（3.04 小时） | meta.json 的 loop_state |

### 3. 对话质量
| 任务 | 准确率 | 基线 | 状态 |
|---|---|---|---|
| ARC-Easy | 未测 | 0.25 | 需运行 chat_eval |
| ARC-Challenge | 未测 | 0.25 | 需运行 chat_eval |
| MMLU | 未测 | 0.25 | 需运行 chat_eval |
| GSM8K | 未测 | 0.00 | 需运行 chat_eval |
| HumanEval | 未测 | 0.00 | 需运行 chat_eval |
| ChatCORE | 未测 | - | 5 任务全测后才打印 |

### 4. 推理性能
未测。需运行 infer_bench 并取末行 JSON。

### 5. 成本
| 项 | 值 |
|---|---|
| 节点单价 | 24 美元/小时（8×H100） |
| 估算成本 | 3.04 × 24 ≈ 73 美元 |
```

该模板的作用是固定栏目与缺失标注方式，不是固定数值。填入真实数据时，每个单元格都应能追溯到 `--core`、`--chat`、`--infer`、`--meta` 四个参数之一。

## 易错点

> [!warning] 六个可检验的错误
> 1. 把 `scripts/report.py` 写成仓库现有文件。当前 master 没有该脚本，成绩单只能由三类评测产物与训练元数据汇总；文档中出现该命令即属事实错误。
> 2. 用 `split(",")` 直接解析 CSV 且不 `strip`。字段宽度固定，未去除空格会让任务名与任务键对不上；`CORE` 行的空 `Accuracy` 列还会触发 `ValueError`。
> 3. 用训练期 wandb 的 `core_metric` 代替 `base_eval` 的 CORE 行。训练期常用 `--core-metric-max-per-task=500` 的快速估计，与全量 CSV 不是同一口径。
> 4. 把未打印的 ChatCORE 写成 0。任务不全时脚本不打印总分，0 是一个有效测量值，会造成「测得随机水平」的错误结论。
> 5. 解析 `infer_bench` 的整段 stdout。机器可读结果只在最后一行；按行号或按表格解析会在字段增减时失败。
> 6. 成本把节点价当单卡价。README 的 24 美元/小时是 8×H100 节点价，成本等于小时数乘节点价，不能再乘 8。

## 关联笔记

- 前置 [[评测方法论]]：五个指标的定义、聚合方式与产物位置。
- 前置 [[ARC与MMLU]]：前三个任务的 categorical 准确率与 ChatCORE 基线。
- 前置 [[GSM8K与HumanEval]]：后两个任务的生成式准确率与 pass@k 口径。
- 后续 [[如何解读指标]]：成绩单上各数字的可信度、方差与冲突。
- 后续 [[实验记录模板]]：成绩单字段如何进入实验记录。
- 跨库 [[成本-延迟-质量权衡]]：把 CORE、ChatCORE 与 MBU 放进同一决策框架的通用方法。

## 达标检测

- [ ] 能说明当前仓库为什么没有 `report.py`，并列出成绩单的四类数据来源。
- [ ] 能写出 CORE CSV 的表头、三列宽度与 `CORE` 行的空列特征。
- [ ] 能说明 `chat_eval` 在什么条件下不打印 ChatCORE，以及成绩单应如何标注。
- [ ] 能从 `infer_bench` 的末行 JSON 中取出 `ttft_sec`、`tpot_sec`、`mbu_percent` 并解释各自含义。
- [ ] 能说出 `meta_*.json` 中进入成绩单的三个字段，并说明 `total_training_time` 的定义。
- [ ] 能解释 wandb 的 `core_metric` 与 CSV 的 CORE 行为何可能不同。
- [ ] 能运行汇总脚本，用合成产物生成含五个小节的 Markdown，并验证成本一节为 73.00 美元。
- [ ] 能指出成绩单中哪些单元格在缺产物时必须写「未测」，并说明理由。

## 参考来源

- Karpathy, *nanochat* README（commit 92d63d4），Time-to-GPT-2 Leaderboard 与 File structure —— 对应成绩单字段、Run 1 数值与「没有 report 脚本」的事实。
- Karpathy, *nanochat* `dev/LEADERBOARD.md`（commit 92d63d4），Run 1 至 Run 6 —— 对应 `core_metric`、`total_training_time`、`val_bpb` 的采集方式与成本口径。
- Karpathy, *nanochat* `scripts/base_eval.py`（commit 92d63d4）—— 对应 CORE CSV 的写入格式与路径。
- Karpathy, *nanochat* `scripts/chat_eval.py`（commit 92d63d4）—— 对应 ChatCORE 的打印条件与任务行格式。
- Karpathy, *nanochat* `scripts/infer_bench.py`（commit 92d63d4）—— 对应末行 JSON 的字段、`prefill` 与 `sweep` 结构。
- Karpathy, *nanochat* `nanochat/checkpoint_manager.py` 与 `scripts/base_train.py`（commit 92d63d4）—— 对应 `meta_*.json` 的保存位置与字段。
