拆解ml-ssd核心架构:eval.py、benchmark.py与livecodebench_utils.py三大模块如何协作

原创2026-10-27 21:24:571,633 阅读

拆解ml-ssd核心架构:eval.py、benchmark.py与livecodebench_utils.py三大模块如何协作

ml-ssd 是 Apple 开源的 Simple Self-Distillation(简单自蒸馏)代码生成项目,通过「采样 → 微调 → 解码」三步法显著提升大模型的编程能力,全程无需奖励模型、验证器、教师模型或强化学习。项目的评测工具链位于 evaluation/ 目录,由 eval.py、benchmark.py 与 livecodebench_utils.py 三大模块协作完成 LiveCodeBench v6 基准测试。下面带你逐层拆解它们的分工与衔接。

ml-ssd自蒸馏代码生成评测:Sample采样、Fine-tune微调、Decode解码三步流程及LiveCodeBench V6评测结果

项目背景:三步走自蒸馏法

ml-ssd 复现了论文 Embarrassingly Simple Self-Distillation Improves Code Generation 的方法,核心只有三个动作:

步骤 说明
Sample 用冻结的模型在非 1 的温度下采样生成代码
Fine-tune 直接在未验证的原始输出上,用标准交叉熵做 SFT 微调
Decode 推理时使用单独调优的温度解码

从上图可以看到,SSD 方法在 LiveCodeBench V6 上整体 pass@1 提升 +12.9 ~ +14.2,且增益在 Hard 难度上更明显(+15.3)。那么问题来了:这套结果是如何被稳定、可复现地测出来的?答案就在评测目录的三大模块里。

评测目录结构一览

仓库结构非常精简,评测相关代码集中在 evaluation/ 下(依赖定义见 pyproject.toml):

文件 角色定位
evaluation/eval.py 🚪 CLI 入口,负责参数解析与流程调度
evaluation/benchmark.py 🧪 LiveCodeBench v6 评测的完整编排
evaluation/livecodebench_utils.py ⚙️ 代码执行、安全护栏与 pass@k 统计工具

三者关系可以概括为一句话:eval.py 是指挥官,benchmark.py 是编排者,livecodebench_utils.py 是底层执行引擎。

模块一:eval.py —— 一键启动评测的 CLI 入口

eval.py 是整个评测流程的起点,做四件事:

  1. 解析命令行参数 —— --model(HuggingFace 模型 ID)、--tensor_parallel_size(GPU 数量)、--n_repeat(每题采样次数)、--sampling_params(采样参数)等,见 eval.py#L20-L36
  2. 解析采样参数串 —— parse_sampling_params() 将 "temperature=0.6,top_p=0.95,top_k=20,min_p=0.0" 这样的字符串安全地转成类型正确的字典,并校验非法键名,见 eval.py#L39-L61
  3. 加载模型并运行 —— 用 vLLM 的 LLM 加载模型,然后 import LiveCodeBenchV6 实例化评测器并调用 benchmark.run()
  4. 保存并打印结果 —— save_results() 将指标与完整配置写入带时间戳的 JSON 文件,最后按 pass@1/5/10/16/20/32 打印汇总表格,见 eval.py#L64-L72

它本身不做任何题目逻辑,把复杂工作全部委托给 benchmark 模块——这是典型的「入口层」设计。

模块二:benchmark.py —— LiveCodeBench v6 的评测编排

benchmark.py 定义了核心类 LiveCodeBenchV6(benchmark.py#L55-L59),围绕2025 年 2 月至 5 月的竞赛题(通过 filter_by_contest_date 过滤)展开,其 run() 方法就是三步走:

  • load_questions():从 HuggingFace 数据集加载题库,按日期过滤后分片并行解码私有测试用例(base64 + zlib + pickle),避免大数据量拼接溢出,见 benchmark.py#L363-L383
  • generate():为每道题构建 prompt(区分"标准输入型"与"函数签名型"两种模板),每题采样 n_repeat 次(每次递增随机种子),并用正则 has_code() 从回复中提取 ```python 代码块,见 benchmark.py#L91-L131
  • evaluate():按采样轮次分组,用 32 线程的 ThreadPoolExecutor 并行判题,再按 总体 和 难度(Easy/Medium/Hard) 分别计算 pass@k,k 值会随 n_repeat 自动裁剪,见 benchmark.py#L237-L355

判题时每个用例超时设为 6 秒;若提取不到代码,直接判为失败并记录原因,保证每道题都有可解释的评测记录。

模块三:livecodebench_utils.py —— 安全的代码执行引擎

livecodebench_utils.py 是最底层的执行与统计工具,也是三大模块中最"硬核"的部分:

  • 可靠性护栏 reliability_guard():执行模型生成的代码前,先禁用 os.kill、os.system、subprocess.Popen、shutil.rmtree 等破坏性函数,防止 fork 炸弹、杀进程、删文件等行为,见 livecodebench_utils.py#L198-L266。需要强调的是:它是"护栏"而非安全沙箱,生产环境仍建议配合隔离容器使用
  • stdin/stdout 模拟:Capturing、MockStdinWithBuffer 等类让函数可以像真实运行一样读取 sys.stdin(含 buffer 字节流)并捕获输出
  • AST 级代码变换:clean_if_name() 剥离 if __name__ == "__main__": 包裹,make_function() 把代码主体包进 wrapped_function() 以便受控调用,compile_code() 自动识别 LeetCode 风格的 class Solution
  • 双测试模式:run_test_func() 处理函数调用型测试,run_test_std() 处理标准输入/输出型测试,二者共用带 Decimal 精度回退的字符串比较逻辑,避免浮点格式差异导致误判
  • 超时控制 lcb_run():用多子进程执行测试,超时即 kill 并补齐超时失败记录,见 livecodebench_utils.py#L702-L715
  • pass@k 无偏估计:estimate_pass_at_k() 基于公式 1 - C(n-c, k) / C(n, k) 估算从 n 个采样中抽 k 个至少一个正确的概率,compute_metrics_from_results() 汇总为最终指标,见 livecodebench_utils.py#L718-L767

三大模块协作全流程

把三块拼起来,一次完整评测的旅程是这样的:

  1. CLI 启动:eval.py 解析参数、解析 --sampling_params
  2. 加载模型:vLLM 构建 LLM 实例 + AutoTokenizer
  3. 加载题库:LiveCodeBenchV6.run() → load_questions()(含私有测试用例解码)
  4. 批量生成:generate() 逐轮调用 llm.generate(),每题产出 n_repeat 份候选代码
  5. 并行判题:evaluate() → check_correctness() → 工具层的 lcb_run() 子进程执行测试
  6. 指标统计:compute_metrics_from_results() 输出总体与分难度的 pass@k
  7. 结果落盘:save_results() 写入 JSON,终端打印汇总表

数据单向流动、职责边界清晰——这正是这套评测代码易于阅读和复现的原因。

最快上手:5 分钟跑通 ml-ssd 评测

环境安装与运行命令如下(依赖见 pyproject.toml,Python 3.11):

git clone https://gitcode.com/gh_mirrors/ml/ml-ssd
cd ml-ssd
uv sync --group evaluation
source .venv/bin/activate
python evaluation/eval.py \
    --model <hf_model_name> \
    --tensor_parallel_size 4 \
    --max_tokens 65536 \
    --n_repeat 10 \
    --sampling_params "temperature=0.9,top_p=0.8,top_k=20" \
    --output_path ./results/

💡 采样参数仅为示例,请以模型卡推荐的参数为准(详见 README.md)。

关键文件速查表

文件路径 核心内容
evaluation/eval.py CLI 入口、参数解析、结果保存
evaluation/benchmark.py LiveCodeBenchV6 类:加载、生成、并行评测
evaluation/livecodebench_utils.py 安全护栏、代码执行、pass@k 统计
pyproject.toml 依赖与环境定义
README.md 方法说明与评测命令

总结

ml-ssd 的评测架构麻雀虽小五脏俱全:eval.py 管"怎么跑",benchmark.py 管"跑什么",livecodebench_utils.py 管"怎么判"。三者以清晰的单向依赖串联起从模型加载到 pass@k 报表的完整链路,也为社区复现自蒸馏代码生成实验提供了可参考的轻量级评测范式。

登录后查看全文
ml-ssd