ml-ssd快速上手:从clone到跑通首次评估,5分钟搞定环境搭建
ml-ssd快速上手:从clone到跑通首次评估,5分钟搞定环境搭建
ml-ssd 是 Apple 开源的 Simple Self-Distillation(简称 SSD)代码生成工具包:不需要强化学习、不需要奖励模型、不需要教师模型,只靠「采样 → 微调 → 解码」三步简单流程就能提升大模型的代码生成能力。本文将带你从零开始,完成 ml-ssd 环境搭建,并跑通在 LiveCodeBench v6 基准上的首次评估,整个过程只需一条安装命令和一条评估命令。
一、环境要求:先检查这3件事
在开始之前,请确认本地环境满足以下条件:
| 依赖 | 要求 | 说明 |
|---|---|---|
| Python | 3.11.13(版本锁定) |
见 pyproject.toml,版本被严格固定 |
| uv | 最新稳定版 | 用于快速创建虚拟环境并安装依赖 |
| GPU | 支持 CUDA 的显卡 | 评估依赖 vllm==0.11.0 进行推理,显存建议 ≥ 24GB |
核心依赖包括 torch==2.8.0、transformers==4.57.1、datasets 和评估组专用的 vllm、scipy,全部由 uv sync 一键搞定,无需手动安装。
二、一键安装:clone仓库并同步依赖
打开终端,执行以下三条命令即可完成 ml-ssd 环境搭建:
git clone https://gitcode.com/gh_mirrors/ml/ml-ssd
cd ml-ssd
uv sync --group evaluation
uv sync会在项目根目录自动创建.venv虚拟环境,并按 pyproject.toml 中声明的版本锁定安装所有依赖;--group evaluation会额外安装评估所需的vllm等依赖组,这一步不能省,否则评估脚本无法运行。
三、1分钟看懂SSD方法:为什么它「简单得令人尴尬」
如图所示,SSD 全流程只有三步:
- Sample(采样):让冻结的模型以非1的温度采样生成代码,扩大输出分布;
- Fine-tune(微调):直接对模型自己的原始输出做标准交叉熵 SFT,不验证、不筛选;
- Decode(解码):评估时用单独调优的温度解码。
官方给出的成绩:相比基座模型,pass@1 相对提升约 +30%,且方法可以泛化到 Instruct / Thinking 等多种模型形态(图中 Llama 8B、Qwen 系列均有稳定增益)。这正是它「Embarrassingly Simple」的底气——No RL · No Verifier · No Teacher · No Rewards。
四、跑通首次评估:一条命令生成 pass@k 报告
激活虚拟环境后,用下面的命令即可启动 LiveCodeBench v6 评估(参数示例来自官方 README):
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/
📌 参数速查表(定义见 evaluation/eval.py):
| 参数 | 作用 | 默认值 |
|---|---|---|
--model |
HuggingFace 模型 ID | 必填 |
--tensor_parallel_size |
vLLM 使用的 GPU 数量 | 1 |
--max_tokens |
单条回答最大生成长度 | 32768 |
--n_repeat |
每题采样次数,用于计算 pass@k | 20 |
--sampling_params |
采样参数,key=value 逗号分隔 |
temperature=0.6,top_p=0.95,top_k=20,min_p=0.0 |
--seed |
随机种子列表 | 0,1234,1234,1234 |
--output_path |
结果输出目录 | ./results |
运行完成后,你会得到两样东西:
- JSON 结果文件:按模型名自动分目录保存在
--output_path下,含时间戳,方便对比多次实验; - pass@k 汇总:终端打印 pass@1、pass@5、pass@10 等总体指标,以及按难度(Medium / Hard)细分的得分。
💡 小贴士:首次验证流程时,把 --n_repeat 调小(如 2~5)可以大幅缩短等待时间;采样参数请以所用模型的 HuggingFace 模型卡推荐值为准。
五、仓库结构导览:5分钟熟悉全部文件
整个仓库非常轻量,核心文件一目了然:
├── evaluation/
│ ├── eval.py # CLI 入口点
│ ├── benchmark.py # LiveCodeBench v6 实现
│ └── livecodebench_utils.py # 代码执行工具
├── figures/
│ └── fig_teaser.png
├── pyproject.toml
└── README.md
- 评估入口:evaluation/eval.py —— 解析参数、加载 vLLM 模型并打印报告
- 基准实现:evaluation/benchmark.py —— 加载 2025 年 2–5 月竞赛题,生成并判题
- 判题工具:evaluation/livecodebench_utils.py —— 沙箱执行模型代码并比对测试用例
- 贡献指南:CONTRIBUTING.md
六、常见问题(FAQ)
Q1:提示 Python 版本不匹配怎么办?
项目锁定了 Python 3.11.13,请确认 uv 能自动拉取该版本,或手动安装后再执行 uv sync --group evaluation。
Q2:没有 4 张 GPU,能跑吗?
能。把 --tensor_parallel_size 设为 1(单卡),并优先选择 SSD-4B 这类小模型即可;30B-A3B 模型对显存要求更高。
Q3:模型从哪里下载?
官方已发布 SSD-4B-Instruct、SSD-4B-Thinking、SSD-30B-A3B-Instruct 等模型 checkpoint,--model 直接填 HuggingFace 上的模型 ID 即可,无需在本地手动下载权重文件。
Q4:评估时间很长,正常吗?
正常。评估会对每题采样 n_repeat 次并执行判题,n_repeat 越大结果越稳定但耗时越长,建议先用小值验证链路。
七、写在最后
至此,你已经完成了 ml-ssd 快速上手 的全部流程:✅ clone 仓库 → ✅ uv sync --group evaluation 一键装环境 → ✅ 一条命令跑通 LiveCodeBench v6 首次评估。
下一步推荐:
- 用不同的
temperature对比解码温度对 pass@1 的影响,复现论文中 Decode 阶段的增益; - 关注仓库 News 区的 数据生成 pipeline 更新,即可自行复现 Sample + Fine-tune 的完整 SSD 流程;
- 阅读 README.md 中的引用信息,规范引用该工作。
简单,就是它最大的竞争力——这正是 Self-Distillation 改进代码生成的魅力所在。
