1. 什么是 DeepSeek Harness

DeepSeek Harness 是 DeepSeek 团队开源的一套大语言模型评测与测试框架，用于对 LLM 进行系统化的能力评估、性能测试和回归验证。它借鉴了 lm-evaluation-harness 的设计理念，并针对 DeepSeek 系列模型进行了深度优化，支持多种评测基准、自定义数据集和细粒度的结果分析。

简单来说，Harness 解决的是「如何科学地评估一个 LLM 到底行不行」的问题。无论是模型发布前的能力摸底、训练过程中的回归测试，还是上线前的安全与质量把关，Harness 都能提供标准化的评测流程和可复现的量化结果。

2. 核心特性与架构

DeepSeek Harness 的核心特性可以概括为以下几点：

• 多基准支持：内置 MMLU、C-Eval、GSM8K、HumanEval、BBH 等主流评测基准，覆盖知识、推理、代码、数学等多个维度。
• 自定义数据集：支持加载 HuggingFace 数据集、本地 JSON/CSV 文件，方便接入业务私有评测集。
• 多后端推理：支持 vLLM、HuggingFace Transformers、OpenAI 兼容 API 等多种推理后端，灵活适配不同部署环境。
• 细粒度指标：除整体准确率外，还提供按类别、按题号、按难度的分层统计，便于定位模型短板。
• 结果可复现：每次评测自动记录模型版本、参数、随机种子、Prompt 模板等元信息，保证实验可追溯。

从架构上看，Harness 主要分为四个模块：

flowchart TD
    A[评测配置 Config] --> B[数据加载器 Loader]
    B --> C[评测任务 Task]
    C --> D[推理后端 Backend]
    D --> E[结果聚合 Evaluator]
    E --> F[报告输出 Report]
    F --> G[日志与元数据]

配置层负责解析 YAML 或命令行参数；数据加载器负责读取评测集；任务层定义具体的评测逻辑（如选择题、生成题）；推理后端负责调用模型；结果聚合层计算指标并生成报告。

3. 环境准备与安装

在开始之前，建议使用 Python 3.10 及以上版本，并创建独立的虚拟环境。以下是完整的安装步骤：

# 创建虚拟环境
python3 -m venv harness_env
source harness_env/bin/activate
安装 DeepSeek Harness
pip install deepseek-harness
如果要从源码安装（推荐开发模式）
git clone https://github.com/deepseek-ai/DeepSeek-Harness.git
cd DeepSeek-Harness
pip install -e .
安装 vLLM 后端（可选，用于高性能推理）
pip install vllm
验证安装
harness --version

安装完成后，可以通过 harness --help 查看所有可用命令。如果希望使用 OpenAI 兼容 API 作为推理后端，还需要配置 API Key 和 Base URL 环境变量：

export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"

4. 快速上手：第一个评测任务

下面我们通过一个最简单的例子，演示如何使用 Harness 对模型进行 MMLU 基准评测。首先创建一个评测配置文件 eval_mmlu.yaml：

model:
  type: vllm
  name: deepseek-ai/deepseek-llm-7b-chat
  tensor_parallel_size: 1
  max_model_len: 4096
tasks:
name: mmlu
num_fewshot: 5
limit: 100
output:
dir: ./results
name: mmlu_test_run

然后运行评测命令：

harness run --config eval_mmlu.yaml

评测完成后，结果会输出到 ./results/mmlu_test_run 目录，包含 JSON 格式的详细指标和日志文件。你也可以通过命令行直接指定参数，无需配置文件：

harness run \
  --model-type vllm \
  --model deepseek-ai/deepseek-llm-7b-chat \
  --task mmlu \
  --num-fewshot 5 \
  --limit 100 \
  --output-dir ./results

5. 代码实战：自定义评测数据集

实际业务中，我们往往需要评测模型在私有数据上的表现。Harness 支持通过 Python API 灵活定义自定义评测任务。下面是一个完整的实战示例，演示如何评测模型在自定义问答数据集上的表现。

首先，创建一个自定义数据集文件 custom_qa.jsonl，每行一个 JSON 对象：

{"question": "中国的首都是哪个城市？", "answer": "北京"}
{"question": "Python 中如何定义一个函数？", "answer": "使用 def 关键字"}
{"question": "1 加 1 等于几？", "answer": "2"}

接下来，编写评测脚本 custom_eval.py：

from deepseek_harness import Harness, Task, Dataset
from deepseek_harness.metrics import ExactMatch, F1Score
1. 定义数据集加载器
def load_custom_dataset(path):
import json
samples = []
with open(path, "r", encoding="utf-8") as f:
for line in f:
data = json.loads(line.strip())
samples.append({
"question": data["question"],
"answer": data["answer"]
})
return samples
2. 定义评测任务
class CustomQATask(Task):
def init(self, dataset_path):
super().init(name="custom_qa")
self.dataset_path = dataset_path
self.metrics = [ExactMatch(), F1Score()]
def load_data(self):
    return load_custom_dataset(self.dataset_path)
def build_prompt(self, sample):
return f"请回答以下问题：\n问题：{sample['question']}\n答案："
def parse_response(self, response):
# 清理模型输出，提取答案部分
return response.strip().split("\n")[0]
def compute_metrics(self, predictions, references):
results = {}
for metric in self.metrics:
results.update(metric.compute(predictions, references))
return results
3. 主流程
def main():
初始化 Harness
harness = Harness(
model_type="vllm",
model_name="deepseek-ai/deepseek-llm-7b-chat",
tensor_parallel_size=1
)
创建任务并注册
task = CustomQATask(dataset_path="./custom_qa.jsonl")
harness.add_task(task)
运行评测
results = harness.run(
output_dir="./results",
run_name="custom_qa_eval",
limit=10
)
打印结果
print("评测完成！结果如下：")
for task_name, metrics in results.items():
print(f"任务：{task_name}")
for metric_name, value in metrics.items():
print(f"  {metric_name}: {value:.4f}")
if name == "main":
main()

运行脚本：

python custom_eval.py

这个示例展示了 Harness 的核心扩展点：通过继承 Task 类，你可以完全控制数据加载、Prompt 构建、响应解析和指标计算，从而适配任意评测场景。

6. 实战：代码生成能力评测

代码生成是 LLM 的重要能力之一。下面演示如何使用 Harness 评测模型的代码生成能力，以 HumanEval 基准为例。首先创建配置文件 eval_humaneval.yaml：

model:
  type: vllm
  name: deepseek-ai/deepseek-coder-6.7b-instruct
  tensor_parallel_size: 1
  max_model_len: 8192
tasks:
name: humaneval
num_fewshot: 0
max_length: 1024
temperature: 0.2
top_p: 0.95
output:
dir: ./results
name: humaneval_run

运行评测：

harness run --config eval_humaneval.yaml

如果你希望使用 OpenAI 兼容 API 进行评测，只需修改配置中的模型类型：

model:
  type: openai
  name: deepseek-coder
  base_url: https://api.deepseek.com/v1
  api_key: ${OPENAI_API_KEY}
  max_retries: 3

评测完成后，Harness 会输出 pass@1、pass@10 等代码生成指标，并保存每个样本的生成结果，方便人工复核。

7. 结果分析与报告解读

评测完成后，理解结果报告至关重要。Harness 生成的报告通常包含以下内容：

• 总体指标：各任务的整体准确率、F1 分数等。
• 分项指标：按类别、难度、题型拆分的详细得分。
• 样本级结果：每个测试样本的模型输出、参考答案和得分。
• 元数据：模型版本、推理参数、Prompt 模板、随机种子等。

下面是一个结果文件的示例结构：

{
  "task": "custom_qa",
  "model": "deepseek-ai/deepseek-llm-7b-chat",
  "metrics": {
    "exact_match": 0.85,
    "f1": 0.92
  },
  "samples": [
    {
      "question": "中国的首都是哪个城市？",
      "reference": "北京",
      "prediction": "北京",
      "correct": true
    },
    {
      "question": "Python 中如何定义一个函数？",
      "reference": "使用 def 关键字",
      "prediction": "在 Python 中，使用 def 关键字来定义函数。",
      "correct": false
    }
  ],
  "metadata": {
    "model_version": "7b-chat-v1.0",
    "temperature": 0.0,
    "seed": 42
  }
}

通过分析样本级结果，你可以快速定位模型的典型错误模式，从而有针对性地进行 Prompt 优化或模型微调。

8. 进阶：批量评测与回归测试

在模型迭代过程中，回归测试至关重要。Harness 支持批量评测多个模型版本，并自动对比结果。下面是一个批量评测脚本示例：

from deepseek_harness import Harness
models = [
"deepseek-ai/deepseek-llm-7b-base",
"deepseek-ai/deepseek-llm-7b-chat",
"deepseek-ai/deepseek-llm-7b-chat-v1.1"
]
tasks = ["mmlu", "gsm8k", "humaneval"]
for model in models:
print(f"正在评测模型：{model}")
harness = Harness(
model_type="vllm",
model_name=model,
tensor_parallel_size=1
)
for task in tasks:
harness.add_task(task, num_fewshot=5)
results = harness.run(
    output_dir="./results",
    run_name=f"regression_{model.split('/')[-1]}"
)
汇总打印
summary = {k: v["acc"] for k, v in results.items()}
print(f"模型 {model} 评测结果：{summary}")</code></pre>
通过对比不同版本的评测结果，你可以清晰地看到每次改动对模型能力的影响，及时发现性能回退。
9. 常见问题与调优建议
在实际使用中，可能会遇到一些常见问题，这里给出对应的解决方案：
显存不足：降低 tensor_parallel_size 或 max_model_len，或使用 --dtype float16 减少显存占用。
推理速度慢：使用 vLLM 后端并开启 --gpu-memory-utilization 0.9，或增加并发数 --num-concurrent 8。
结果不稳定：固定随机种子 --seed 42，并设置 temperature=0 以获得确定性输出。
自定义数据集格式错误：确保 JSONL 每行是合法 JSON，且字段名与代码中一致。
API 调用超时：增加 max_retries 和 timeout 参数，或使用本地 vLLM 后端。
此外，建议在正式评测前先用小规模数据（如 --limit 10）验证流程，确认无误后再进行全量评测，以节省时间和计算资源。
10. 总结
本文从零开始介绍了 DeepSeek Harness 的安装、配置和实战用法，涵盖了内置基准评测、自定义数据集、代码生成评测、结果分析和批量回归测试等核心场景。通过 Harness，你可以建立标准化的模型评测流程，用数据驱动模型迭代和优化。
建议读者结合自己的业务场景，从自定义评测任务入手，逐步构建完善的评测体系。后续可以进一步探索 Harness 的分布式评测、Prompt 变体对比等高级功能，让评测工作更加高效和可靠。