拆解ml-ssd核心架构:eval.py、benchmark.py与livecodebench_utils.py三大模块如何协作
拆解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 复现了论文 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 是整个评测流程的起点,做四件事:
- 解析命令行参数 ——
--model(HuggingFace 模型 ID)、--tensor_parallel_size(GPU 数量)、--n_repeat(每题采样次数)、--sampling_params(采样参数)等,见 eval.py#L20-L36 - 解析采样参数串 ——
parse_sampling_params()将"temperature=0.6,top_p=0.95,top_k=20,min_p=0.0"这样的字符串安全地转成类型正确的字典,并校验非法键名,见 eval.py#L39-L61 - 加载模型并运行 —— 用 vLLM 的
LLM加载模型,然后import LiveCodeBenchV6实例化评测器并调用benchmark.run() - 保存并打印结果 ——
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
三大模块协作全流程
把三块拼起来,一次完整评测的旅程是这样的:
- CLI 启动:
eval.py解析参数、解析--sampling_params - 加载模型:vLLM 构建
LLM实例 +AutoTokenizer - 加载题库:
LiveCodeBenchV6.run()→load_questions()(含私有测试用例解码) - 批量生成:
generate()逐轮调用llm.generate(),每题产出n_repeat份候选代码 - 并行判题:
evaluate()→check_correctness()→ 工具层的lcb_run()子进程执行测试 - 指标统计:
compute_metrics_from_results()输出总体与分难度的 pass@k - 结果落盘:
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 报表的完整链路,也为社区复现自蒸馏代码生成实验提供了可参考的轻量级评测范式。
