AI 原生开放教材

外观

AI 工程从零到一（中文）源码研读·中文原文 ↗原件 ↓仓库 ↗

代码执行评测指标 ​

生成的代码，通过测试才算对。eval harness 必须能把代码抽出来、在不搞崩宿主机的前提下跑起来、并诚实地统计通过率。这节课就来构建这个接口面。

类型： Build 语言： Python 前置要求： 阶段19 Track B 基础、第 70 和 71 课 预计时间： ~90 分钟

学习目标 ​

  • 用与第 70 课后处理规则一致的方式，从自由格式的生成结果里抽出一个代码块。
  • 在一个隔离的子进程里执行候选代码，配上 wall-clock 超时、输出上限、以及 import 黑名单。
  • 把一个任务的得分定义为：所提供的断言字符串里，对候选代码通过的那部分占比。
  • 对那些会从一个模型采样多份生成的任务，计算 pass-at-k。
  • 把 sandbox 崩溃、语法错误、超时都当成一等公民式的失败模式，配上各自不同的、runner 能记录的退出码。
figure
sandbox-runner

为什么要用隔离子进程 ​

内联 exec 是安全和稳定性上的隐患。一段生成出来的 while True: pass 会把 eval 永远卡死。一段生成出来的 import shutil; shutil.rmtree('/')，灾难程度跟字面意思一模一样。修复办法是：每个候选都新起一个全新的 Python 解释器，从 stdin 把代码传进去，把断言结果写到 stdout，超时就杀掉进程。宿主 eval 进程照常运行。

像 HumanEval、MBPP、BigCodeBench、LiveCodeBench 这些真实 eval，全都用子进程 sandbox。有些还在上面叠一层 Docker。我们停在子进程是有原因的：它可移植、它是标准库、它能抓住对教学型 eval 真正重要的那些失败模式。生产部署会再加 seccomp、网络隔离、只读文件系统。关于加固的下一节课在本 Track 之外。

一个 code-exec 任务的形状 ​

一个 code_exec 任务在 targets 里携带断言字符串。runner 从生成结果里抽出一个围栏代码块，围着它搭一个测试 harness，然后跑出结果。

mermaid
flowchart TD
    A[生成文本] -->|extract_code_block| B[代码字符串]
    C[task.targets 断言列表] --> D[构建 runner 脚本]
    B --> D
    D --> E[启动 python 子进程<br/>超时、黑名单、输出上限]
    E -->|stdout JSON| F[逐断言结果]
    E -->|超时| G[结果: timeout]
    E -->|非零退出| H[结果: error]
    F --> I[score = passed / total]
    G --> I
    H --> I

得分是 [0, 1] 里的一个比例。一个带三条断言、其中两条通过的任务得 0.667。无论是什么挂了，runner 都返回同样的形状：子进程的崩溃被映射成一个归一化的错误码，而不是让 Python traceback 冒泡到 harness 上。

黑名单 ​

黑名单是基于 import 的。在运行候选代码之前，runner 脚本会把对危险模块的 import 改写成一个 stub，它会抛出 ImportError("denied")。这份清单刻意保守：os.system、subprocess、socket、requests、urllib、urllib.request、urllib.error、urllib.parse、ctypes、shutil、http.client、asyncio.subprocess。

我们并不假装它是金钟罩。铁了心的对抗性代码可以逃出 Python 里任何进程内 sandbox。黑名单是兜底。真正承重的控制项是 wall-clock 超时和输出上限。

python
DENIED = {
    "os.system": True,
    "subprocess": True,
    "socket": True,
    "shutil": True,
    "requests": True,
    "urllib": True,
    "ctypes": True,
}

我们在候选代码前面加上 import sys 以及一段把 os.system monkey-patch 成抛异常的守卫，以此把它包起来。完整模板在 main.py 里。

Wall-clock 超时 ​

每个子进程默认有三秒 wall-clock 的预算。runner 用 subprocess.run(..., timeout=t)。一旦超时触发，runner 捕获 TimeoutExpired、杀掉进程、给该任务记一个 timeout 退出原因。这个任务得分为零。runner 继续往下走。

超时可以通过 task.metadata.timeout_s 按任务配置。跑得久的单元测试可以要更多；第 70 课的 validator 把这个值上限定为三十秒，保证整个套件有界。

输出上限 ​

子进程可能往 stdout 灌爆数据，耗光宿主内存。runner 把 stdout 流式读进一个缓冲区，一旦累计总量越过 256 KB 就立刻杀掉子进程。结果被记为 exit_code = error，detail 字符串为 "output overflow"。这在实践中常常出现于：生成结果不小心写了一个会打印的死循环。

Pass-at-k ​

pass-at-k 是 HumanEval 一脉所用的无偏估计量。给定每个任务 n 份独立样本、其中 c 份通过，那么从这 n 份里抽 k 份、至少含一份通过解的概率是：

pass_at_k(n, c, k) = 1 - C(n - c, k) / C(n, k)

当 n - c < k 时分子未定义，取值为 1。实现里直接处理了这个边界情况。我们暴露 pass_at_k(n, c, k) 供第 74 课的 leaderboard 层使用。

mermaid
flowchart LR
    A[带 n=10 份样本的任务] --> B[跑每一份样本]
    B --> C[c 份样本通过]
    C --> D[pass_at_1 = c/n]
    C --> E[pass_at_5 = 1 - C n-c, 5 / C n, 5]
    C --> F[pass_at_10 = 1 if c>0 else 0]

退出码 ​

runner 每个任务返回五种结果之一：

  • pass：每条断言都通过。
  • assertion_fail：代码跑起来了，但至少有一条断言没过。
  • syntax_error：代码 import 失败或有 SyntaxError。
  • timeout：wall clock 到期。
  • error：其他任何崩溃，包括命中黑名单和输出溢出（溢出带 detail "output overflow" 现身）。

得分仍是一个比例，退出码是元信息。下游课程可以自行决定：把一次 timeout 算成零，还是算成缺失数据。

这节课不做什么 ​

它不给你一个真正的 sandbox。它不跑来自开放互联网的不可信代码。它不处理像文件 I/O、网络调用这类有状态任务。那些需要容器或 microVM。这节课的重点是这份契约：一个隔离子进程、一份黑名单、一个超时、一个输出上限、一套干净的退出码词表、以及 pass-at-k 的数学。

怎么读代码 ​

main.py 定义了 extract_code、run_candidate、score_code_exec、pass_at_k。子进程 runner 脚本被构建成一个字符串，作为 -c 传给一个全新的 Python 解释器。code/tests/test_exec.py 里的测试对四种退出码、以及对照 HumanEval 风格手算示例的 pass-at-k 都做了演练。

从头到尾读一遍 main.py。runner 模板是承重的那块。盯着断言循环看，直到你能预测出它写回父进程的那个 JSON 信封长什么样。

再进一步 ​

一旦子进程形状跑通，下一个关注点就是可移植性。不同 Python 版本在 Windows 上对 SIGKILL 的处理不一样。最干净的修法是把 runner 放进一个 Docker 镜像里。再往后一步，是把断言字符串换成真正的单元测试文件，让 eval 与生产 CI 的做法对齐。到那一步就别再把断言字符串叫测试了；它们是玩具测试，有的是玩具式的失败模式。