DeepSeek Harness 最新实践：从模型部署到标准评测一站式上手

1. 什么是 DeepSeek Harness

DeepSeek Harness 是 DeepSeek 官方开源的模型推理与评测框架，仓库地址为：

https://github.com/deepseek-ai/DeepSeek-Harness

它的核心目标，是让开发者能够用统一、可复现的方式完成两件事：

• 推理：调用 DeepSeek 官方 API，或对接本地部署的 vLLM、SGLang 等兼容服务；
• 评测：在 MATH-500、AIME、GPQA、LiveCodeBench、SWE-bench 等常用基准上跑分。

随着 DeepSeek-R1、DeepSeek-V3 以及后续模型不断更新，官方把模型报告里使用的评测代码逐步沉淀到这个仓库中。相比早前零散的脚本，最新版 Harness 更强调"一套流程跑通推理与评估"，非常适合技术博客、模型微调、课程实验以及团队内部做能力验证。

2. 最新版本的重点能力

最新版 Harness 依然围绕"数据集 + 模型 + 流水线"三层抽象展开，但整体设计更通用：

• OpenAI 兼容协议优先：无论是 DeepSeek 官方 API，还是本地 vLLM/SGLang 启动的服务，都通过 OpenAI 风格接口接入；
• 思维链处理更完整：支持读取模型的 reasoning 内容，并与最终答案分离，方便对 CoT 类模型评分；
• 数据集覆盖更广：数学、代码、知识问答、软件工程等任务都有统一入口；
• 可复现性更强：把采样数量、温度、max tokens、chat template 等关键参数集中管理，减少"换台机器分数就变"的问题；
• 易于扩展：新增数据集或模型后端时，通常只需实现对应接口，不必重写整个评测流程。

3. 环境准备与安装

目前 Harness 通常通过源码方式安装。推荐使用 Python 3.10 以上版本：

# 克隆官方仓库
git clone https://github.com/deepseek-ai/DeepSeek-Harness.git
cd DeepSeek-Harness

# 安装依赖
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

如果你希望同时做本地推理与评测，还需要准备对应后端。以 vLLM 为例：

pip install vllm

DeepSeek 官方 API 则不需要额外部署模型，安装 openai 客户端即可：

pip install openai

4. 核心工作流

整个 Harness 可以抽象为下面的流程：
#mermaid-svg-b23NQwxC2rUf1puT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-b23NQwxC2rUf1puT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-b23NQwxC2rUf1puT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-b23NQwxC2rUf1puT .error-icon{fill:#552222;}#mermaid-svg-b23NQwxC2rUf1puT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-b23NQwxC2rUf1puT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-b23NQwxC2rUf1puT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-b23NQwxC2rUf1puT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-b23NQwxC2rUf1puT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-b23NQwxC2rUf1puT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-b23NQwxC2rUf1puT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-b23NQwxC2rUf1puT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-b23NQwxC2rUf1puT .marker.cross{stroke:#333333;}#mermaid-svg-b23NQwxC2rUf1puT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-b23NQwxC2rUf1puT p{margin:0;}#mermaid-svg-b23NQwxC2rUf1puT .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-b23NQwxC2rUf1puT .cluster-label text{fill:#333;}#mermaid-svg-b23NQwxC2rUf1puT .cluster-label span{color:#333;}#mermaid-svg-b23NQwxC2rUf1puT .cluster-label span p{background-color:transparent;}#mermaid-svg-b23NQwxC2rUf1puT .label text,#mermaid-svg-b23NQwxC2rUf1puT span{fill:#333;color:#333;}#mermaid-svg-b23NQwxC2rUf1puT .node rect,#mermaid-svg-b23NQwxC2rUf1puT .node circle,#mermaid-svg-b23NQwxC2rUf1puT .node ellipse,#mermaid-svg-b23NQwxC2rUf1puT .node polygon,#mermaid-svg-b23NQwxC2rUf1puT .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-b23NQwxC2rUf1puT .rough-node .label text,#mermaid-svg-b23NQwxC2rUf1puT .node .label text,#mermaid-svg-b23NQwxC2rUf1puT .image-shape .label,#mermaid-svg-b23NQwxC2rUf1puT .icon-shape .label{text-anchor:middle;}#mermaid-svg-b23NQwxC2rUf1puT .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-b23NQwxC2rUf1puT .rough-node .label,#mermaid-svg-b23NQwxC2rUf1puT .node .label,#mermaid-svg-b23NQwxC2rUf1puT .image-shape .label,#mermaid-svg-b23NQwxC2rUf1puT .icon-shape .label{text-align:center;}#mermaid-svg-b23NQwxC2rUf1puT .node.clickable{cursor:pointer;}#mermaid-svg-b23NQwxC2rUf1puT .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-b23NQwxC2rUf1puT .arrowheadPath{fill:#333333;}#mermaid-svg-b23NQwxC2rUf1puT .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-b23NQwxC2rUf1puT .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-b23NQwxC2rUf1puT .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-b23NQwxC2rUf1puT .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-b23NQwxC2rUf1puT .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-b23NQwxC2rUf1puT .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-b23NQwxC2rUf1puT .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-b23NQwxC2rUf1puT .cluster text{fill:#333;}#mermaid-svg-b23NQwxC2rUf1puT .cluster span{color:#333;}#mermaid-svg-b23NQwxC2rUf1puT div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-b23NQwxC2rUf1puT .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-b23NQwxC2rUf1puT rect.text{fill:none;stroke-width:0;}#mermaid-svg-b23NQwxC2rUf1puT .icon-shape,#mermaid-svg-b23NQwxC2rUf1puT .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-b23NQwxC2rUf1puT .icon-shape p,#mermaid-svg-b23NQwxC2rUf1puT .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-b23NQwxC2rUf1puT .icon-shape .label rect,#mermaid-svg-b23NQwxC2rUf1puT .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-b23NQwxC2rUf1puT .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-b23NQwxC2rUf1puT .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-b23NQwxC2rUf1puT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 加载数据集 Dataset
选择模型后端 Model
构造 Pipeline
批量推理
答案解析与 Scorer 评分
汇总指标并输出结果

其中：

• Dataset 负责读取、切分、归一化测试样本；
• Model 负责封装不同后端，统一为生成接口；
• Pipeline 把数据集、模型和评分器串起来；
• Scorer 根据任务类型做答案比对或代码执行验证。

5. 快速开始：本地启动 OpenAI 兼容服务

如果你已经有本地模型，可以先用 vLLM 启动一个兼容服务，让 Harness 按 DeepSeek 官方 API 的方式访问：

python -m vllm.entrypoints.openai.api_server \
  --model deepseek-ai/DeepSeek-V3 \
  --served-model-name deepseek-chat \
  --trust-remote-code \
  --max-model-len 8192 \
  --tensor-parallel-size 8

服务启动后，本地会监听：

http://localhost:8000/v1

此时可以直接用 openai 客户端测试连通性：

from openai import OpenAI

client = OpenAI(
    api_key="token-abc123",
    base_url="http://localhost:8000/v1",
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "9.11 和 9.8 哪个大？"},
    ],
    temperature=0.0,
)

print(response.choices[0].message.content)

如果一切正常，说明本地后端已经可以被 Harness 使用。

6. 快速开始：跑一次标准评测

进入仓库目录后，可以先查看 Harness 支持哪些参数：

python main.py --help

常见的最小评测命令形如：

# 使用 DeepSeek 官方 API 跑 MATH-500
python main.py \
  --dataset math500 \
  --model deepseek-chat \
  --use_chat_template

本地服务场景则把模型地址指向刚刚启动的 vLLM：

python main.py \
  --dataset math500 \
  --model deepseek-chat \
  --base_url http://localhost:8000/v1 \
  --api_key token-abc123 \
  --use_chat_template

实际参数以当前仓库 README 和 --help 输出为准。Harness 的参数在版本间可能调整，例如采样次数、并发数、最大输出长度等，建议在跑正式榜单前先小样本验证。

7. 常见评测数据集

下面是 Harness 中经常使用的几类基准：

数据集	任务类型	说明
MATH-500	数学推理	OpenAI 整理的 500 道数学题，开发调试非常常用
AIME 2024	数学推理	高难度竞赛题，常用于观察推理上限
GPQA Diamond	知识问答	研究生级科学问答，区分度较高
LiveCodeBench	代码生成	代码基准持续更新，时效性较强
SWE-bench Verified	软件工程	处理真实 GitHub issue，考察工程修复能力

不同数据集的评分方式也不同：数学题可能做答案标准化后比对，代码题则可能执行测试用例。Harness 通过统一的 Scorer 层隔离这些差异。

8. 自定义数据集与评估

对于自有场景，核心思路是把自己手里的问题整理成 Harness 能读的格式，并注册为新的 Dataset。

一个简化的数据加载逻辑如下：

class MyDataset:
    def __len__(self):
        return len(self.samples)

    def __getitem__(self, idx):
        sample = self.samples[idx]
        return {
            "prompt": sample["question"],
            "reference": sample["standard_answer"],
        }

随后把它接到 pipeline 中，并指定合适的评分规则即可。具体接口名称需要对照仓库源码，但最新版强调的是"数据加载、模型调用、评分器"三者解耦，因此新增场景通常不需要改动核心流程。

9. 常见问题

1. 为什么本地服务和官方 API 的结果不一致？

本地服务受采样参数、chat template、max tokens、served-model-name 以及推理后端影响。建议先统一 temperature、top_p、max_new_tokens，再检查 chat template 是否与官方一致。

2. 评测时能复现论文分数吗？

论文分数通常依赖特定 prompt、采样次数和答案解析逻辑。Harness 提供了一个可复现框架，但数据集版本、模型版本以及随机种子仍会影响结果。

3. 模型没有返回 reasoning 怎么办？

部分任务需要显式开启思维链模板，或选择支持 reasoning 的模型版本。检查模型是否进入了正确的模式，并确认客户端没有把 reasoning 内容丢弃。

4. 是否需要 GPU？

使用官方 API 时不需要 GPU；本地推理则需要根据模型规模准备显存。DeepSeek 系列模型通常建议使用 vLLM 或 SGLang 做分布式推理。

10. 总结

DeepSeek Harness 已经从早期散落的评测脚本，演进为一个结构更清晰、扩展性更好的推理与评测框架。对想要复现 DeepSeek 官方榜单，或者需要统一管理模型评测流程的开发者来说，直接使用官方 Harness 可以省去大量重复工作。

建议完整流程是：先克隆仓库 → 启动本地服务或配置官方 API → 用小数据集验证链路 → 再跑完整评测 → 最后把自有数据集接入 pipeline。这样既能快速上手，也便于后续持续维护。