---
tags: [nanochat, eval, generative]
阶段: 08-评测Eval
难度: ★★★
created: 2026-10-22
related: "[[评测方法论]], [[ARC与MMLU]], [[如何解读指标]], [[工具调用与Python沙箱]]"
---

# GSM8K与HumanEval

## 定义

**生成式评测**（generative evaluation）指先让模型采样出完整回答，再由解析器或外部执行器判定正确性的评测方式。nanochat 用它评测两个任务：GSM8K（小学数学应用题，按最终数值判定）与 HumanEval（Python 函数补全，按单元测试执行结果判定）。

符号与术语定义如下。

- **GSM8K**：约 8.5k 道小学应用题，参考答案含推理过程，最终答案写在 `####` 之后；训练用 `train` 切分，评测用 `test` 切分（约 1,319 题）。
- **HumanEval**：164 道手写 Python 编程题；每题给出函数签名与文档字符串作为 `prompt`，给出标准实现 `canonical_solution`、入口函数名 `entry_point` 与单元测试代码 `test`。
- **补全**（completion）：模型在提示之后生成的 token 序列，评测时只取提示之后的片段。
- **`####` 标记**：GSM8K 参考答案中最终数值的起始标记；正则 `#### (\-?[0-9\.\,]+)` 抽取其后的数值字符串。
- **精确匹配**（exact match）：抽取出的预测数值字符串与参考答案数值字符串逐字符相等。
- **`check` 函数**：HumanEval 测试代码中的校验入口，调用 `check(entry_point)` 即运行该题全部断言。
- **沙箱**：`nanochat/execution.py` 的 `execute_code`，在子进程中执行生成的程序并施加时间与内存限制。
- **pass@$k$**：每题采样 $k$ 个解，至少一个通过即该题通过，再对题目求平均。
- **`any(outcomes)`**：`scripts/chat_eval.py` 的判定语句，等价于「本题 $k$ 个解中至少一个通过」。
- **`temperature`**：采样温度；为 0 时退化为 argmax（贪心），大于 0 时按 softmax 分布采样。
- **`top_k`**：采样前只保留 logits 最大的 $k$ 个 token；温度为 0 时不生效。
- **`max_new_tokens`**：单次生成的最大 token 数，达到上限即截断。

## 为什么重要

categorical 评测回答不了两类问题。第一类是数值推理：GSM8K 的答案是一个数，模型需要多步算术才能得到，只比较单个 token 的 logits 无法表达计算过程。第二类是程序正确性：HumanEval 要求补全的函数在给定输入上满足断言，只有真正执行才能判断，任何基于文本相似度的判分都会把「看起来对但运行报错」的实现判为正确。

生成式评测还承担两个工程职责。GSM8K 的 `train` 切分是 SFT 与 RL 的训练数据，SFT 用 `<<表达式=结果>>` 教模型发起计算器工具调用，RL 用 `test` 切分的精确匹配作为 reward 并报告 pass@k；因此 GSM8K 的评测代码与训练代码共享同一套答案抽取函数，评测口径直接决定 reward 信号。HumanEval 则是仓库中唯一需要真正执行模型输出的评测，它把 `nanochat/execution.py` 的沙箱行为（超时、内存、环境清理）变成了分数的一部分。

代价是分数不再只反映模型能力。生成式评测的每一次失败都可能来自四个环节：模型没有生成正确答案、生成被长度截断、答案抽取失败、执行环境拒绝。任一环节失败都会使该题不得分，因此总通过率不高于任一环节的通过率；排查一个低分必须逐环节定位。这是本篇的主要工程内容。

在「懂原理、能复现、懂工程」中，本篇偏「能复现」：判分规则本身很短，但要让同一模型在不同机器上得到同一分数，必须固定生成长度、温度、提示渲染、沙箱参数与数据集顺序。

## 原理与推导

### 1. 生成式评测循环

`scripts/chat_eval.py` 的 `run_generative_eval` 逐题循环，每题生成 `num_samples` 个解。

```python
for i in range(ddp_rank, num_problems, ddp_world_size):
    conversation = task_object[i]
    encoded_prompt = tokenizer.render_for_completion(conversation)
    results, _ = engine.generate_batch(
        encoded_prompt, num_samples=num_samples,
        max_tokens=max_new_tokens, temperature=temperature, top_k=top_k)
    prefix_length = len(encoded_prompt)
    completions = [tokenizer.decode(result_tokens[prefix_length:]) for result_tokens in results]
    outcomes = [task_object.evaluate(conversation, completion) for completion in completions]
    passed = any(outcomes)
```

四个细节决定了分数的含义。第一，提示用 `render_for_completion` 渲染：它删除最后一条 assistant 消息并追加 `<|assistant_start|>`，因此模型从 assistant 起始位置开始生成，生成结果不含提示本身。第二，`prefix_length` 是提示的 token 数，解码时切掉这一段；`Engine.generate_batch` 返回的序列包含提示 token，不去掉会把提示文本混进答案。第三，`any(outcomes)` 把 $k$ 个解合并成一个布尔值，因此统计单位是「题」而不是「解」。第四，各 rank 只处理自己的题目，最后把 `num_passed` 与 `total` 分别 `all_reduce` 求和。

生成由 `Engine` 完成：先做一次 batch 1 的预填充，把 KV 缓存复制成 `num_samples` 行，再逐 token 解码；终止条件是采样到 `<|assistant_end|>` 或 `<|bos|>`，或达到 `max_tokens`。温度与 top-k 在 `sample_next_token` 中处理：温度为 0 时直接 `argmax`，否则按 `top_k` 截断后 softmax 采样。

### 2. GSM8K：数据、格式与答案抽取

GSM8K 的参考答案同时包含推理与最终答案：

```text
Weng earns $12 an hour for babysitting. Yesterday, she just did 50 minutes of babysitting.
Weng earns 12/60 = $<<12/60=0.2>>0.2 per minute.
Working 50 minutes, she earned 0.2 x 50 = $<<0.2*50=10>>10.
#### 10
```

`tasks/gsm8k.py` 构造训练对话时把 `<<表达式=结果>>` 拆成工具调用与工具输出两类片段：

```python
parts = re.split(r'(<<[^>]+>>)', answer)
for part in parts:
    if part.startswith('<<') and part.endswith('>>'):
        inner = part[2:-2]
        expr, result = inner.rsplit('=', 1)
        assistant_message_parts.append({"type": "python", "text": expr})
        assistant_message_parts.append({"type": "python_output", "text": result})
    else:
        assistant_message_parts.append({"type": "text", "text": part})
```

这些片段在 `render_conversation` 中分别被 `<|python_start|>`、`<|output_start|>` 等特殊 token 包裹，`python_output` 的 mask 为 0（不由模型监督，推理时由计算器填入）。这一格式是 06 阶段的内容，本篇只强调它决定了模型在评测时的输出形态：模型应当先发起工具调用，再在推理末尾写出 `#### 数值`。

评测端只做字符串抽取与比较：

```python
GSM_RE = re.compile(r"#### (\-?[0-9\.\,]+)")

def extract_answer(completion):
    match = GSM_RE.search(completion)
    if match:
        match_str = match.group(1).strip().replace(",", "")
        return match_str
    return None

ref_num = extract_answer(last_text_part)   # 参考答案最后一段文本中的数值
pred_num = extract_answer(assistant_response)
is_correct = int(pred_num == ref_num)
```

四个性质由此确定。第一，只认 `####` 之后的第一个数值，`####` 之前的中间结果不参与判定。第二，抽取后删除千位分隔逗号，因此 `1,000` 与 `1000` 相等。第三，比较是字符串比较，`10` 与 `10.0` 不相等，`10` 与 ` 10` 在抽取时已 `strip`，相等。第四，正则只匹配紧跟在 `####` 后的数字、小数点与逗号序列：数字之后的分数、百分号或单位被忽略（例如 `#### 3/4` 抽取为 `3`，`#### 10 dollars` 抽取为 `10`），数字之前的货币符号或百分号会使匹配失败（`#### $10` 返回 `None`），因此这类答案即使语义正确也会判错。

`evaluate` 还依赖一个结构假设：`assistant_message['content'][-1]['text']` 是包含最终答案的那一段。GSM8K 的参考答案总以文本结尾，因此该假设成立；若换成以工具输出结尾的数据，参考答案会被错误地解析为 `None`。

### 3. HumanEval：补全与程序拼接

HumanEval 的一道题由四段组成：`prompt`（函数签名与文档字符串）、`canonical_solution`（标准实现）、`test`（断言与 `check` 函数）、`entry_point`（函数名）。模型只看到 `prompt`，需要补全函数体。

```python
prompt = row['prompt']                       # 例如 def has_close_elements(...):
solution = row['canonical_solution']         # 正确实现
entry_point = row['entry_point']             # 例如 has_close_elements
test = row['test']                           # def check(candidate): ...
complete_solution = f"{prompt}\n{solution}"
```

判分时把四段代码拼接成一个可执行程序：从提示中抽取 import，接上模型补全的代码，接上测试代码，最后调用 `check(entry_point)`。

```python
imports = extract_imports(conversation['messages'][0]['content'])
completion_code = extract_program(completion)
program = (
    imports
    + "\n\n"
    + completion_code
    + "\n\n"
    + conversation['test']
    + "\n"
    + f"check({conversation['entry_point']})"
)
result = execute_code(program)
success = result.success
```

`extract_imports` 只扫描提示开头连续的 `import` 与 `from` 行，遇到第一个既非 import 也非注释的行就停止。原因是 HumanEval 的提示把依赖写在函数定义之前；若 import 出现在函数之后，抽取会漏掉。模型若在补全中自带 import，则不会被重复抽取，但会原样进入 `completion_code`，因此仍可运行。

`extract_program` 处理两种输出形态：

```python
pattern = r'```(?:python)?\s*\n(.*?)\n```'
matches = re.findall(pattern, completion, re.DOTALL)
if matches:
    return matches[0].strip()    # 只取第一个代码块
return completion.strip()        # 没有代码块则整段当作代码
```

若模型输出多个代码块（例如先给示例再给实现），只有第一个被使用；若代码块没有闭合围栏，正则不匹配，整段文本（含解释）被当作代码送入解释器，通常直接语法错误。

### 4. 沙箱的边界与对通过率的影响

`nanochat/execution.py` 的 `execute_code` 在子进程中运行程序：默认 `timeout=5.0`、`maximum_memory_bytes=256*1024*1024`。子进程先执行一段 guard，再 `exec` 编译后的用户代码。

```python
resource.setrlimit(resource.RLIMIT_AS, (maximum_memory_bytes, maximum_memory_bytes))
resource.setrlimit(resource.RLIMIT_DATA, (maximum_memory_bytes, maximum_memory_bytes))
resource.setrlimit(resource.RLIMIT_STACK, (maximum_memory_bytes, maximum_memory_bytes))
subprocess.Popen = None
```

guard 还禁用 `os.system`、`os.kill`、`shutil.rmtree`、`os.fork` 等函数，关闭 `faulthandler`，清空 `exit`、`quit`、`help`，并把 `ipdb`、`joblib`、`resource`、`psutil`、`tkinter` 置为 `None`。父进程用 `subprocess.run([sys.executable, "-c", program], cwd=tmpdir, env={"PATH": "/usr/bin:/bin"}, stdin=DEVNULL, capture_output=True, timeout=timeout)` 执行，超时则杀死子进程并返回 `success=False, timeout=True`；内存超限表现为 `MemoryError`，`memory_exceeded` 由 `stderr` 中是否含 `"MemoryError"` 判定；正常退出码为 0 时 `success=True`。

这套机制对通过率有三条可观察的影响。第一，时间复杂度高的正确解会在 5 秒处被杀，尤其是双重循环的 $O(n^2)$ 实现；`tests/test_execution.py` 用无限循环验证了子进程会被及时杀死。第二，单次分配超过 256 MB 的实现会失败，测试用例用 1 GB 的 `bytearray` 验证了这一点。第三，环境被清理为只有 `PATH`，读取自定义环境变量的代码会失败，标准库与已安装的第三方包仍可导入。

沙箱不是安全边界。docstring 明确列出未覆盖项：不阻止网络访问、`ctypes` 等动态特性可绕过限制、没有内核级隔离（无 seccomp、无容器）。因此它适合评测生成代码，不适合执行不可信的对抗代码。

### 5. pass@k 与 `any()` 口径

`run_chat_eval` 的默认参数是 `num_samples=1`、`temperature=0.0`、`max_new_tokens=512`、`top_k=50`。此时 `any(outcomes)` 等价于单次结果，报告的是 pass@1。当命令行传入 `-n k` 时，每题生成 $k$ 个样本，报告的是「至少一个通过」的比例，即

$$
\widehat{\text{pass@}k}_{\text{naive}}=\frac{1}{N}\sum_{i=1}^{N}\mathbb{1}\left[\exists\,j\le k:\ y_{ij}\ \text{通过}\right].
$$

这不是 HumanEval 原论文的无偏估计量 $1-\binom{n-c}{k}/\binom{n}{k}$；它只使用前 $k$ 个样本，且随采样顺序变化。`scripts/chat_rl.py` 把它推广到 $k=1,\dots,B$：对每题取前 $k$ 个样本做逻辑或，再对题目求平均，并在 wandb 中记录每个 $k$ 的曲线。

两套评测的协议不同，不能混报。`chat_eval` 用温度 0、最大 512 token；RL 的 `run_gsm8k_eval` 用温度 1.0、最大 256 token、`num_samples=device_batch_size`、每题上限 `--eval-examples=400`。同一模型在两个协议下的 pass@k 不可直接比较，`ChatCORE` 中的 GSM8K 与 HumanEval 分数只对应前者。

$k$ 的选择是方差与成本的权衡。$k$ 增大时「至少一个通过」的概率单调上升，但样本高度相关，方差不会按 $1/k$ 下降；同时每题生成 $k$ 个解使评测时间近似乘 $k$。报告 pass@k 时必须同时写出 $k$、温度、最大生成长度与题数。

### 6. 为什么 HumanEval 被注明「misnomer」

`tasks/humaneval.py` 的模块 docstring 写道：

```text
Btw this dataset is a misnomer and has nothing to do with humans.
It is a coding benchmark.
```

README 的文件结构注释同样写 `humaneval.py    # Misnomer; Simple Python coding task`。两点原因。第一，字面上的 human 指题目由人类编写（相对自动生成），不表示评测人类水平，也不表示有人工评分环节。第二，nanochat 的实现只运行 164 道题的一次补全，没有多语言、没有隐藏测试、没有人工评审；它测的是 Python 函数补全的执行通过率，与「human evaluation」无关。

这个标注的工程意义是防止误读成绩单：HumanEval 的 5% 不表示「模型达到人类程序员水平的 5%」，只表示 164 道题中有约 8 道通过。样本量小，置信区间宽，单次比较的意义有限。

### 在 nanochat 中的落地

第一处是 `tasks/gsm8k.py` 的 `extract_answer` 与 `evaluate`。评测与 RL reward 共用同一函数，因此修改抽取规则会同时改变 ChatCORE 与训练信号；`reward` 只是把 `evaluate` 的整数结果转成浮点，没有额外塑形。

第二处是 `tasks/humaneval.py` 的 `evaluate`。它把 `extract_imports`、`extract_program`、`execute_code` 三步串起来，任一环节失败都返回 `False`，没有部分分。

第三处是 `scripts/chat_eval.py` 的 `run_generative_eval`。它逐题调用 `generate_batch`，把生成、解码、判分、聚合放在一个循环里；`num_problems` 与 `max_problems` 控制题数，`ddp` 控制分片。

第四处是 `scripts/chat_rl.py` 的 `run_gsm8k_eval` 与 `passk` 计算。它为训练提供 reward 与 pass@k 曲线，温度 1.0 的采样同时用于训练 rollout 与评测，因此训练曲线中的 pass@k 不能与 ChatCORE 的 GSM8K 直接对比。

第五处是 `nanochat/execution.py`。它只有 134 行，却决定了 HumanEval 的全部通过条件：超时、内存、环境、工作目录、stdio。修改其中任一默认值都会改变历史分数。

## 关键直觉

> [!tip] 生成式分数是「生成、解析、执行」三级串联的通过率
> 一道题通过，必须模型生成正确内容、解析器抽取出正确答案、执行环境接受这段程序；三个条件同时成立才计 1，因此整体通过率不超过任一级的通过率。这解释了为什么同一模型在不同 `max_new_tokens`、不同代码块格式、不同沙箱参数下分数不同，也解释了为什么低分不能直接归因于「模型不会」。与严格定义的关系：pass@k 定义在「题」上而不是「解」上，`any()` 把 $k$ 次独立判定折叠为一次布尔判定，于是分数只反映至少一次成功的概率。

## 例子与代码

### 1. GSM8K 的判分手算

设参考答案最后一段为 `#### 10`，三个模型输出的抽取结果分别为 `10`、`10.0`、`1,000`。

```python
import re
GSM_RE = re.compile(r"#### (\-?[0-9\.\,]+)")

def extract_answer(completion):
    match = GSM_RE.search(completion)
    if match:
        return match.group(1).strip().replace(",", "")
    return None

ref = extract_answer("Work ... #### 10")          # '10'
for completion in ["... so the answer is #### 10",
                   "... so the answer is #### 10.0",
                   "... so the answer is #### 1,000"]:
    pred = extract_answer(completion)
    print(repr(pred), pred == ref)
# 预期：'10' True
# 预期：'10.0' False
# 预期：'1000' False
```

若两段文本都没有 `####`，`extract_answer` 都返回 `None`，`None == None` 为 `True`，该题会被判为正确。GSM8K 的参考答案不会出现这种情况，但若把同一函数用于其他数据集，这是一个真实的 footgun。

### 2. HumanEval 的程序拼接

```python
prompt = '''from typing import List

def has_close_elements(numbers: List[float], threshold: float) -> bool:
    """ Check if any two numbers are closer than threshold. """
'''
test = '''def check(candidate):
    assert candidate([1.0, 2.0, 3.9, 4.0], 0.3) == False
    assert candidate([1.0, 2.0, 2.1], 0.3) == True
'''
fence = "`" * 3   # 避免在本代码块内直接写出三反引号，否则会提前闭合外层围栏
completion = "\n".join([
    fence + "python",
    "def has_close_elements(numbers, threshold):",
    "    for i in range(len(numbers)):",
    "        for j in range(i + 1, len(numbers)):",
    "            if abs(numbers[i] - numbers[j]) < threshold:",
    "                return True",
    "    return False",
    fence,
])
import re
block = re.findall(r'```(?:python)?\s*\n(.*?)\n```', completion, re.DOTALL)
completion_code = block[0].strip()
imports = "from typing import List"
program = (imports + "\n\n" + completion_code + "\n\n" + test + "\n"
           + "check(has_close_elements)")
print(program)
```

拼接结果的最后一行是 `check(has_close_elements)`，运行它即执行两条断言。这段实现是 $O(n^2)$，在 164 道题的小输入下通常能在 5 秒内完成；若输入规模增大，超时会把它判为失败。

`extract_program` 的 `.strip()` 还有一个可检验的副作用：它去掉代码块首行的缩进。若补全只写函数体（首行是缩进的 `for`），该行会被顶到第 0 列，拼接后的程序出现 `IndentationError` 或引用了未定义的变量；若补全重复一遍函数签名，则不受影响。因此在这一实现下，重复签名的补全比只补函数体更容易通过。

### 3. HumanEval 判分流程（伪代码）

```text
输入：conversation，包含 prompt、test、entry_point；completion，模型生成的文本
1. imports ← 从 conversation.messages[0].content 的起始连续 import 行
2. code ← 若 completion 含围栏代码块则取第一个，否则取整段并 strip
3. program ← imports + 空行 + code + 空行 + test + 换行 + "check(" + entry_point + ")"
4. result ← execute_code(program, timeout=5.0, maximum_memory_bytes=256MB)
5. 返回 result.success（子进程退出码为 0）
```

### 4. 运行两项评测

```bash
# 全量 5 任务；GSM8K 与 HumanEval 各生成 1 个解，温度 0
OMP_NUM_THREADS=1 torchrun --standalone --nproc_per_node=8 -m scripts.chat_eval -- \
    -i sft -a 'GSM8K|HumanEval' | tee chat_eval_gen.log

# 单独看 HumanEval，增大生成长度以观察截断是否影响通过率
python -m scripts.chat_eval -i sft -a HumanEval -m 768 -x 164

# RL 阶段的 pass@k（温度 1.0，最大 256 token）
python -m scripts.chat_rl --run=dummy --eval-examples=400
```

第三条命令的 `--run=dummy` 关闭 wandb 日志；实际训练时应给出真实 run 名，否则 pass@k 曲线不会保存。

## 易错点

> [!warning] 六个可检验的错误
> 1. 把生成结果整体送去判分。`generate_batch` 返回的序列包含提示 token，必须用 `prefix_length` 切掉；否则 `####` 之前的提示文本可能被误当作生成内容。
> 2. 认为 `max_new_tokens=512` 足够。GSM8K 的推理加工具调用可能超过该长度，截断后没有 `####`，抽取返回 `None`，会被判错；HumanEval 的长实现同样会被截断在半行。
> 3. 用数值比较替代字符串比较。仓库的实现是字符串相等，`10` 与 `10.0` 不等；若自行改成浮点比较，会得到与仓库不同的分数，且无法与历史结果对比。
> 4. 忽略 `None == None`。两段文本都抽取失败时相等，该题被判为正确；用同一函数评测其他数据集或参考答案缺 `####` 时会静默产生假阳性。
> 5. 把 RL 的 pass@k 与 ChatCORE 的 GSM8K 并列。前者温度 1.0、最大 256 token、`any()` 口径；后者温度 0、最大 512 token、`num_samples=1`。协议不同，不可比。
> 6. 认为沙箱提供了安全隔离。它不阻止网络访问，也挡不住 `ctypes`，只能防误操作；把不可信代码送入 `execute_code` 不是可接受的做法。

## 关联笔记

- 前置 [[评测方法论]]：生成式与 categorical 的分工、ChatCORE 基线与聚合公式。
- 对照 [[ARC与MMLU]]：同一模型在不生成文本时的判分方式，与本篇的生成式路径形成对照。
- 前置 [[多选与工具使用数据]]：GSM8K 的 `<<>>` 注释如何变成 SFT 的工具调用片段。
- 后续 [[如何解读指标]]：$n=164$ 的小样本置信区间、pass@k 的 $k$ 选择与方差。
- 后续 [[生成report成绩单]]：两项任务的准确率如何进入成绩单并在缺测时标注。
- 跨库 [[模型评估矩阵]]：代码基准的测试覆盖问题与污染检测；本篇只讲 nanochat 的判分实现。相关执行边界见 [[工具调用与Python沙箱]]。

## 达标检测

- [ ] 能写出 GSM8K 的抽取正则，并说明它接受哪些字符、拒绝哪些字符。
- [ ] 能解释 `10`、`10.0`、`1,000` 三个输出在仓库实现下是否与参考答案 `10` 相等。
- [ ] 能复述 `run_generative_eval` 中 `prefix_length` 的作用与 `any(outcomes)` 的统计单位。
- [ ] 能按顺序写出 HumanEval 程序的四段拼接，并说明 `imports` 只从提示开头抽取的原因。
- [ ] 能说明 `extract_program` 在「无围栏」「多代码块」「围栏未闭合」三种输入下的行为。
- [ ] 能列出沙箱的四个限制（超时、内存、环境、工作目录）并各给出一个会因此失败的正确实现。
- [ ] 能写出 naive pass@k 的公式，并说明它与无偏估计量的差别以及 RL 评测所用的温度。
- [ ] 能解释 HumanEval 为何被标注为 misnomer，并说明该标注对成绩单解读的影响。

## 参考来源

- Cobbe 等, *Training Verifiers to Solve Math Word Problems*（2110.14168）—— 对应 GSM8K 的数据规模、切分与 `####` 答案格式。
- Chen 等, *Evaluating Large Language Models Trained on Code*（2107.03374）—— 对应 HumanEval 的 164 题构造、程序补全协议与 pass@k 无偏估计量。
- Karpathy, *nanochat* `tasks/gsm8k.py`（commit 92d63d4）—— 对应 `<<>>` 片段解析、`####` 抽取与精确匹配判分。
- Karpathy, *nanochat* `tasks/humaneval.py`（commit 92d63d4）—— 对应 `extract_imports`、`extract_program`、程序拼接与 misnomer 注释。
- Karpathy, *nanochat* `nanochat/execution.py`（commit 92d63d4）—— 对应沙箱的超时、内存限制、环境清理与成功判据。
- Karpathy, *nanochat* `scripts/chat_eval.py`、`scripts/chat_rl.py`（commit 92d63d4）—— 对应生成式评测循环、`any()` 口径与 RL 的 pass@k 计算。
