1. DeepSeek Harness 是什么DeepSeek Harness 是用于 DeepSeek 系列模型评测与推理的命令行框架通常基于lm-evaluation-harness或官方评估脚本封装而来。它把“模型加载、数据预处理、批量推理、指标计算、结果落盘”整合成统一入口适合以下场景在 MMLU、C-Eval、CMMLU、GSM8K、MATH、HumanEval、MBPP 等基准上复现 DeepSeek 官方结果接入 DeepSeek API、Hugging Face Transformers 权重、vLLM 本地服务等多种后端跑分、压测、选型对比不同模型版本、不同量化精度、不同采样参数。本文假设你使用 DeepSeek 官方评估脚本目录路径和包名如有变化请以deepseek-ai组织下最新 README 为准。2. 环境准备推荐环境项目要求Python3.10 或 3.11操作系统Linux推荐 Ubuntu 20.04/22.04CUDA11.8 或 12.1仅本地权重需要显存根据模型规模DeepSeek-V3/R1 完整权重建议多卡部署先检查环境python--versionnvidia-smi pip--version如果没有独立 Python 环境建议新建虚拟环境python-mvenv .venvsource.venv/bin/activate你也可以创建一个check_env.py脚本一次性自动检查 Python、PyTorch、CUDA 等关键依赖# check_env.pyimportplatformimportsubprocessimportsysdefcheck_python():print([Python])print(f version :{platform.python_version()})print(f implementation :{platform.python_implementation()})print(f executable :{sys.executable})oksys.version_info(3,10)print(f status :{OKifokelseWARN - 推荐使用 Python 3.10 或 3.11})returnokdefcheck_system():print([System])print(f os :{platform.system()}{platform.release()})print(f machine :{platform.machine()})defcheck_nvidia_smi():print([CUDA / Driver])try:outputsubprocess.check_output([nvidia-smi,--query-gpuname,memory.total,driver_version,--formatcsv,noheader],textTrue,stderrsubprocess.DEVNULL,)ifnotoutput.strip():print( 状态 : 未检测到 NVIDIA GPU)returnFalseprint( GPU 信息 :)forlineinoutput.strip().splitlines():print(f{line})returnTrueexceptFileNotFoundError:print( 状态 : 未找到 nvidia-smi请确认已安装 NVIDIA 驱动)returnFalseexceptsubprocess.CalledProcessError:print( 状态 : nvidia-smi 执行失败)returnFalsedefcheck_torch():print([PyTorch])try:importtorchprint(f torch version :{torch.__version__})print(f cuda available :{torch.cuda.is_available()})iftorch.cuda.is_available():print(f cuda version :{torch.version.cuda})print(f device count :{torch.cuda.device_count()})print(f current device :{torch.cuda.current_device()})returnTrueexceptImportError:print( 状态 : 未安装 PyTorch可执行 pip install torch)returnFalsedefcheck_transformers():print([Transformers])try:importtransformersprint(f version :{transformers.__version__})returnTrueexceptImportError:print( 状态 : 未安装 transformers)returnFalsedefmain():print(*60)print(DeepSeek Harness 环境检查)print(*60)results{python:check_python(),nvidia:check_nvidia_smi(),torch:check_torch(),transformers:check_transformers(),}check_system()print(*60)print(检查结果汇总)forname,okinresults.items():print(f{name:14}:{OKifokelse需处理})print(*60)ifnotresults[python]ornotresults[torch]:print(提示请先解决标记为「需处理」的项目再继续安装 DeepSeek Harness。)else:print(基础环境检查通过可以继续安装 DeepSeek Harness。)if__name____main__:main()运行脚本python check_env.py3. 安装 DeepSeek Harness3.1 通过源码安装如果使用官方仓库安装流程通常如下gitclone https://github.com/deepseek-ai/DeepSeek-Harness.gitcdDeepSeek-Harness pipinstall-e.如果仓库中提供了评测依赖清单请一并安装pipinstall-rrequirements-eval.txt3.2 安装可选后端根据你计划使用的推理后端选择安装# 使用 Hugging Face Transformerspipinstalltransformers datasets accelerate# 使用 vLLM 本地推理pipinstallvllm# 使用 OpenAI 兼容接口通常只需 requests 或 openaipipinstallopenai4. 快速开始4.1 通过 DeepSeek API 跑 MMLU先准备 API KeyexportDEEPSEEK_API_KEYsk-你的密钥然后执行python-mdeepseek_harness\--modeldeepseek-chat\--backendopenai\--tasksmmlu\--num-fewshot5\--batch-size84.2 通过 vLLM 加载本地权重如果你的机器已经部署了权重且想用多卡推理可以执行python-mdeepseek_harness\--modeldeepseek-ai/DeepSeek-V3\--backendvllm\--tasksgsm8k,human_eval\--tensor-parallel-size4\--max-model-len8192运行结束后控制台会输出类似下面的结果gsm8k: 0.892 human_eval: 0.7355. 常用命令参数详解常用参数含义如下参数说明--model模型名称或本地路径如deepseek-chat、/data/models/DeepSeek-V3--backend推理后端openai、transformers、vllm等--tasks评测任务多个任务用英文逗号分隔--num-fewshotfew-shot 示例数量一般为 0、5、8--batch-size单次请求批大小API 模式建议 8 到 32--max-gen-toks生成类任务的最大输出 token 数--temperature采样温度评测通常设为 0--output-path结果保存目录--log-level日志级别DEBUG、INFO、WARNING完整帮助可以查看python-mdeepseek_harness--help6. 自定义评测任务除了内置任务你还可以通过 YAML 配置自己的数据集。6.1 编写任务配置创建my_math_qa.yamltask:my_math_qadataset_path:jsondataset_kwargs:data_files:./data/my_math_qa.jsonloutput_type:generate_untilnum_fewshot:0generation_kwargs:max_gen_toks:256temperature:0.0metric_list:-metric:exact_match6.2 准备 JSONL 数据./data/my_math_qa.jsonl每一行如下{question:3 5 等于多少,answer:8}{question:12 乘以 12 等于多少,answer:144}6.3 运行自定义任务python-mdeepseek_harness\--modeldeepseek-chat\--backendopenai\--tasksmy_math_qa\--output-path ./results如果任务名和文件名不同可以在 YAML 里用group或task字段指定真实任务标识。7. 接入不同模型后端7.1 DeepSeek APIexportDEEPSEEK_API_KEYsk-xxxxexportDEEPSEEK_BASE_URLhttps://api.deepseek.compython-mdeepseek_harness\--modeldeepseek-reasoner\--backendopenai\--tasksgsm8k,math\--num-fewshot0deepseek-reasoner适合数学、代码等需要推理的任务deepseek-chat更适合通用问答。7.2 Hugging Face 本地权重python-mdeepseek_harness\--model/data/models/DeepSeek-V3\--backendtransformers\--dtypebfloat16\--device-map auto显存不足时可以降低--batch-size或使用 4 比特/8 比特量化加载。7.3 vLLM OpenAI 兼容服务先启动 vLLM 服务vllm serve deepseek-ai/DeepSeek-V3\--tensor-parallel-size8\--max-model-len8192\--port8000然后在 Harness 中通过 OpenAI 兼容接口调用python-mdeepseek_harness\--modeldeepseek-ai/DeepSeek-V3\--backendopenai\--base-url http://127.0.0.1:8000/v1\--api-key EMPTY\--taskshellaswag,arc_challenge8. 结果解析与日志默认结果会写入类似下面的目录results/ └── deepseek-chat/ └── mmlu/ ├── results.json └── metrics.jsonresults.json中通常包含每个样本的输入、输出、参考答案和是否正确metrics.json中则包含聚合指标。常见指标acc准确率acc_norm归一化准确率更适合选择题exact_match完全匹配常用于数学、代码任务pass1单次采样通过率。查看指标catresults/deepseek-chat/mmlu/metrics.json如果你需要横向对比不同模型或任务可以创建一个visualize_results.py脚本读取metrics.json并生成柱状图或雷达图。先安装可视化依赖pipinstallmatplotlib numpy# visualize_results.pyimportargparseimportjsonfrompathlibimportPathimportmatplotlib.pyplotaspltimportnumpyasnpdefload_metrics(path):读取 metrics.json并摊平为数值指标字典。withopen(path,encodingutf-8)asfile:datajson.load(file)metrics{}forkey,valueindata.items():ifisinstance(value,(int,float)):metrics[key]float(value)elifisinstance(value,dict):forsub_key,sub_valueinvalue.items():ifisinstance(sub_value,(int,float)):metrics[f{key}.{sub_key}]float(sub_value)returnmetricsdefcollect_results(root_dir):递归扫描结果目录收集每个 model/task 的 metrics.json。rootPath(root_dir)rows[]formetrics_pathinsorted(root.rglob(metrics.json)):rel_partsmetrics_path.relative_to(root).partsiflen(rel_parts)2:modelrel_parts[0]taskrel_parts[1]else:modelunknowntaskrel_parts[0]rows.append({model:model,task:task,path:str(metrics_path),metrics:load_metrics(metrics_path),})returnrowsdefplot_bar(rows,metric,output):labels[]values[]forrowinrows:ifmetricinrow[metrics]:labels.append(f{row[model]}/{row[task]})values.append(row[metrics][metric])ifnotlabels:raiseSystemExit(f没有模型/任务包含指标{metric})xnp.arange(len(labels))fig,axplt.subplots(figsize(10,6))ax.bar(x,values,color#4C72B0,alpha0.85)ax.set_xticks(x)ax.set_xticklabels(labels,rotation30,haright)ax.set_ylabel(metric)ax.set_title(f不同模型/任务{metric}对比)ax.grid(axisy,alpha0.3)fig.tight_layout()fig.savefig(output,dpi200)print(f柱状图已保存{output})defplot_radar(rows,metric,output):task_metrics{}model_names[]forrowinrows:ifmetricinrow[metrics]:modelrow[model]taskrow[task]task_metrics.setdefault(task,{})[model]row[metrics][metric]ifmodelnotinmodel_names:model_names.append(model)ifnottask_metricsornotmodel_names:raiseSystemExit(可用数据不足无法绘制雷达图)taskssorted(task_metrics.keys())anglesnp.linspace(0,2*np.pi,len(tasks),endpointFalse).tolist()anglesangles[:1]fig,axplt.subplots(figsize(8,8),subplot_kwdict(polarTrue))formodelinmodel_names:values[task_metrics.get(task,{}).get(model,0.0)fortaskintasks]valuesvalues[:1]ax.plot(angles,values,labelmodel,markero)ax.fill(angles,values,alpha0.1)ax.set_xticks(angles[:-1])ax.set_xticklabels(tasks)ax.set_ylim(0,1.0)ax.legend(locupper right,bbox_to_anchor(1.25,1.1))ax.set_title(f{metric}雷达图,pad20)fig.tight_layout()fig.savefig(output,dpi200)print(f雷达图已保存{output})defmain():parserargparse.ArgumentParser(description可视化 DeepSeek Harness 评测结果)parser.add_argument(--root,requiredTrue,help结果根目录例如 results)parser.add_argument(--metric,requiredTrue,help指标名例如 acc、acc_norm、exact_match)parser.add_argument(--type,choices[bar,radar],requiredTrue,help图表类型)parser.add_argument(--output,requiredTrue,help输出图片路径例如 results_comparison.png)argsparser.parse_args()rowscollect_results(args.root)ifnotrows:raiseSystemExit(f在{args.root}下未找到 metrics.json)ifargs.typebar:plot_bar(rows,args.metric,args.output)else:plot_radar(rows,args.metric,args.output)if__name____main__:main()运行示例# 对比不同模型/任务在 acc_norm 指标上的柱状图python visualize_results.py\--rootresults\--metricacc_norm\--typebar\--outputresults_comparison.png# 生成雷达图python visualize_results.py\--rootresults\--metricacc_norm\--typeradar\--outputresults_radar.png9. 进阶用法9.1 多任务批量评测python-mdeepseek_harness\--modeldeepseek-chat\--backendopenai\--tasksmmlu,ceval,gsm8k,human_eval\--num-fewshot5,5,0,09.2 多次采样计算 passk代码类任务需要多次采样时可以在任务配置中增加num_samples:20metric_list:-metric:pass_at_kk:59.3 断点续跑如果评测中断可以基于已有日志继续python-mdeepseek_harness\--modeldeepseek-chat\--backendopenai\--tasksmmlu\--continue-from ./results/deepseek-chat/mmlu具体参数名以你使用的版本为准部分版本使用--load-from或--resume。9.4 多进程加速在不使用 vLLM 的情况下可以通过增加并发请求数提升 API 吞吐python-mdeepseek_harness\--modeldeepseek-chat\--backendopenai\--tasksgsm8k\--num-concurrent-requests16\--request-interval0.1注意不要超过 API 速率限制避免被限流。10. 常见问题排查10.1 显存不足 OOM优先减少--batch-size或缩短--max-model-lenpython-mdeepseek_harness\--modeldeepseek-ai/DeepSeek-V3\--backendvllm\--tasksmmlu\--batch-size1\--max-model-len409610.2 API 限流降低--num-concurrent-requests增加--request-interval或使用重试逻辑。部分版本支持--retry-count和--retry-delay。10.3 Hugging Face 模型或数据集下载慢国内环境可以设置镜像exportHF_ENDPOINThttps://hf-mirror.comexportHF_HOME/data/huggingface也可以先手动下载数据集后使用本地路径exportHF_DATASETS_OFFLINE110.4 结果与官方分数不一致确认以下几点few-shot 数量是否一致温度是否设为 0是否使用相同的提示模板选择题是否启用了acc_normDeepSeek API 和本地模型的权重版本是否一致。11. 总结DeepSeek Harness 的核心价值在于把复杂评测流程标准化让你用同一条命令切换不同后端、不同任务、不同采样策略。日常使用记住三个关键点即可明确模型来源API 用openai后端本地权重用transformers或vllm明确评测任务内置任务名直接写自定义任务用 YAML明确可复现性日志、指标、采样参数都要保留。安装完成后建议先用一个小任务验证环境python-mdeepseek_harness\--modeldeepseek-chat\--backendopenai\--tasksgsm8k\--num-fewshot0\--batch-size4跑通这条命令再逐步扩展到完整 benchmark。