## 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. 环境准备

推荐环境：

| 项目 | 要求 |
| --- | --- |
| Python | 3.10 或 3.11 |
| 操作系统 | Linux，推荐 Ubuntu 20.04/22.04 |
| CUDA | 11.8 或 12.1（仅本地权重需要） |
| 显存 | 根据模型规模，DeepSeek-V3/R1 完整权重建议多卡部署 |

先检查环境：

```bash
python --version
nvidia-smi
pip --version
```

如果没有独立 Python 环境，建议新建虚拟环境：

```bash
python -m venv .venv
source .venv/bin/activate
```



你也可以创建一个 `check_env.py` 脚本，一次性自动检查 Python、PyTorch、CUDA 等关键依赖：

```python
# check_env.py
import platform
import subprocess
import sys

def check_python():
    print("[Python]")
    print(f"  version         : {platform.python_version()}")
    print(f"  implementation  : {platform.python_implementation()}")
    print(f"  executable      : {sys.executable}")
    ok = sys.version_info >= (3, 10)
    print(f"  status          : {'OK' if ok else 'WARN - 推荐使用 Python 3.10 或 3.11'}")
    return ok

def check_system():
    print("[System]")
    print(f"  os              : {platform.system()} {platform.release()}")
    print(f"  machine         : {platform.machine()}")

def check_nvidia_smi():
    print("[CUDA / Driver]")
    try:
        output = subprocess.check_output(
            ["nvidia-smi", "--query-gpu=name,memory.total,driver_version", "--format=csv,noheader"],
            text=True,
            stderr=subprocess.DEVNULL,
        )
        if not output.strip():
            print("  状态            : 未检测到 NVIDIA GPU")
            return False
        print("  GPU 信息        :")
        for line in output.strip().splitlines():
            print(f"    {line}")
        return True
    except FileNotFoundError:
        print("  状态            : 未找到 nvidia-smi，请确认已安装 NVIDIA 驱动")
        return False
    except subprocess.CalledProcessError:
        print("  状态            : nvidia-smi 执行失败")
        return False

def check_torch():
    print("[PyTorch]")
    try:
        import torch
        print(f"  torch version   : {torch.__version__}")
        print(f"  cuda available  : {torch.cuda.is_available()}")
        if torch.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()}")
        return True
    except ImportError:
        print("  状态            : 未安装 PyTorch，可执行 pip install torch")
        return False

def check_transformers():
    print("[Transformers]")
    try:
        import transformers
        print(f"  version         : {transformers.__version__}")
        return True
    except ImportError:
        print("  状态            : 未安装 transformers")
        return False

def main():
    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("检查结果汇总：")
    for name, ok in results.items():
        print(f"  {name:<14}: {'OK' if ok else '需处理'}")
    print("=" * 60)
    if not results["python"] or not results["torch"]:
        print("提示：请先解决标记为「需处理」的项目，再继续安装 DeepSeek Harness。")
    else:
        print("基础环境检查通过，可以继续安装 DeepSeek Harness。")

if __name__ == "__main__":
    main()
```

运行脚本：

```bash
python check_env.py
```
## 3. 安装 DeepSeek Harness

### 3.1 通过源码安装

如果使用官方仓库，安装流程通常如下：

```bash
git clone https://github.com/deepseek-ai/DeepSeek-Harness.git
cd DeepSeek-Harness
pip install -e .
```

如果仓库中提供了评测依赖清单，请一并安装：

```bash
pip install -r requirements-eval.txt
```

### 3.2 安装可选后端

根据你计划使用的推理后端选择安装：

```bash
# 使用 Hugging Face Transformers
pip install transformers datasets accelerate

# 使用 vLLM 本地推理
pip install vllm

# 使用 OpenAI 兼容接口，通常只需 requests 或 openai
pip install openai
```

## 4. 快速开始

### 4.1 通过 DeepSeek API 跑 MMLU

先准备 API Key：

```bash
export DEEPSEEK_API_KEY="sk-你的密钥"
```

然后执行：

```bash
python -m deepseek_harness \
  --model deepseek-chat \
  --backend openai \
  --tasks mmlu \
  --num-fewshot 5 \
  --batch-size 8
```

### 4.2 通过 vLLM 加载本地权重

如果你的机器已经部署了权重，且想用多卡推理，可以执行：

```bash
python -m deepseek_harness \
  --model deepseek-ai/DeepSeek-V3 \
  --backend vllm \
  --tasks gsm8k,human_eval \
  --tensor-parallel-size 4 \
  --max-model-len 8192
```

运行结束后，控制台会输出类似下面的结果：

```text
gsm8k: 0.892
human_eval: 0.735
```

## 5. 常用命令参数详解

常用参数含义如下：

| 参数 | 说明 |
| --- | --- |
| `--model` | 模型名称或本地路径，如 `deepseek-chat`、`/data/models/DeepSeek-V3` |
| `--backend` | 推理后端：`openai`、`transformers`、`vllm` 等 |
| `--tasks` | 评测任务，多个任务用英文逗号分隔 |
| `--num-fewshot` | few-shot 示例数量，一般为 0、5、8 |
| `--batch-size` | 单次请求批大小，API 模式建议 8 到 32 |
| `--max-gen-toks` | 生成类任务的最大输出 token 数 |
| `--temperature` | 采样温度，评测通常设为 0 |
| `--output-path` | 结果保存目录 |
| `--log-level` | 日志级别：`DEBUG`、`INFO`、`WARNING` |

完整帮助可以查看：

```bash
python -m deepseek_harness --help
```

## 6. 自定义评测任务

除了内置任务，你还可以通过 YAML 配置自己的数据集。

### 6.1 编写任务配置

创建 `my_math_qa.yaml`：

```yaml
task: my_math_qa
dataset_path: json
dataset_kwargs:
  data_files: ./data/my_math_qa.jsonl
output_type: generate_until
num_fewshot: 0
generation_kwargs:
  max_gen_toks: 256
  temperature: 0.0
metric_list:
  - metric: exact_match
```

### 6.2 准备 JSONL 数据

`./data/my_math_qa.jsonl` 每一行如下：

```json
{"question": "3 + 5 等于多少？", "answer": "8"}
{"question": "12 乘以 12 等于多少？", "answer": "144"}
```

### 6.3 运行自定义任务

```bash
python -m deepseek_harness \
  --model deepseek-chat \
  --backend openai \
  --tasks my_math_qa \
  --output-path ./results
```

如果任务名和文件名不同，可以在 YAML 里用 `group` 或 `task` 字段指定真实任务标识。

## 7. 接入不同模型后端

### 7.1 DeepSeek API

```bash
export DEEPSEEK_API_KEY="sk-xxxx"
export DEEPSEEK_BASE_URL="https://api.deepseek.com"

python -m deepseek_harness \
  --model deepseek-reasoner \
  --backend openai \
  --tasks gsm8k,math \
  --num-fewshot 0
```

`deepseek-reasoner` 适合数学、代码等需要推理的任务；`deepseek-chat` 更适合通用问答。

### 7.2 Hugging Face 本地权重

```bash
python -m deepseek_harness \
  --model /data/models/DeepSeek-V3 \
  --backend transformers \
  --dtype bfloat16 \
  --device-map auto
```

显存不足时，可以降低 `--batch-size`，或使用 4 比特/8 比特量化加载。

### 7.3 vLLM OpenAI 兼容服务

先启动 vLLM 服务：

```bash
vllm serve deepseek-ai/DeepSeek-V3 \
  --tensor-parallel-size 8 \
  --max-model-len 8192 \
  --port 8000
```

然后在 Harness 中通过 OpenAI 兼容接口调用：

```bash
python -m deepseek_harness \
  --model deepseek-ai/DeepSeek-V3 \
  --backend openai \
  --base-url http://127.0.0.1:8000/v1 \
  --api-key EMPTY \
  --tasks hellaswag,arc_challenge
```

## 8. 结果解析与日志

默认结果会写入类似下面的目录：

```text
results/
└── deepseek-chat/
    └── mmlu/
        ├── results.json
        └── metrics.json
```

`results.json` 中通常包含每个样本的输入、输出、参考答案和是否正确；`metrics.json` 中则包含聚合指标。常见指标：

- `acc`：准确率；
- `acc_norm`：归一化准确率，更适合选择题；
- `exact_match`：完全匹配，常用于数学、代码任务；
- `pass@1`：单次采样通过率。

查看指标：

```bash
cat results/deepseek-chat/mmlu/metrics.json
```



如果你需要横向对比不同模型或任务，可以创建一个 `visualize_results.py` 脚本，读取 `metrics.json` 并生成柱状图或雷达图。先安装可视化依赖：

```bash
pip install matplotlib numpy
```

```python
# visualize_results.py
import argparse
import json
from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np


def load_metrics(path):
    """读取 metrics.json，并摊平为数值指标字典。"""
    with open(path, encoding="utf-8") as file:
        data = json.load(file)

    metrics = {}
    for key, value in data.items():
        if isinstance(value, (int, float)):
            metrics[key] = float(value)
        elif isinstance(value, dict):
            for sub_key, sub_value in value.items():
                if isinstance(sub_value, (int, float)):
                    metrics[f"{key}.{sub_key}"] = float(sub_value)
    return metrics


def collect_results(root_dir):
    """递归扫描结果目录，收集每个 model/task 的 metrics.json。"""
    root = Path(root_dir)
    rows = []
    for metrics_path in sorted(root.rglob("metrics.json")):
        rel_parts = metrics_path.relative_to(root).parts
        if len(rel_parts) >= 2:
            model = rel_parts[0]
            task = rel_parts[1]
        else:
            model = "unknown"
            task = rel_parts[0]
        rows.append(
            {
                "model": model,
                "task": task,
                "path": str(metrics_path),
                "metrics": load_metrics(metrics_path),
            }
        )
    return rows


def plot_bar(rows, metric, output):
    labels = []
    values = []
    for row in rows:
        if metric in row["metrics"]:
            labels.append(f"{row['model']} / {row['task']}")
            values.append(row["metrics"][metric])
    if not labels:
        raise SystemExit(f"没有模型/任务包含指标：{metric}")

    x = np.arange(len(labels))
    fig, ax = plt.subplots(figsize=(10, 6))
    ax.bar(x, values, color="#4C72B0", alpha=0.85)
    ax.set_xticks(x)
    ax.set_xticklabels(labels, rotation=30, ha="right")
    ax.set_ylabel(metric)
    ax.set_title(f"不同模型/任务 {metric} 对比")
    ax.grid(axis="y", alpha=0.3)
    fig.tight_layout()
    fig.savefig(output, dpi=200)
    print(f"柱状图已保存：{output}")


def plot_radar(rows, metric, output):
    task_metrics = {}
    model_names = []
    for row in rows:
        if metric in row["metrics"]:
            model = row["model"]
            task = row["task"]
            task_metrics.setdefault(task, {})[model] = row["metrics"][metric]
            if model not in model_names:
                model_names.append(model)

    if not task_metrics or not model_names:
        raise SystemExit("可用数据不足，无法绘制雷达图")

    tasks = sorted(task_metrics.keys())
    angles = np.linspace(0, 2 * np.pi, len(tasks), endpoint=False).tolist()
    angles += angles[:1]

    fig, ax = plt.subplots(figsize=(8, 8), subplot_kw=dict(polar=True))
    for model in model_names:
        values = [task_metrics.get(task, {}).get(model, 0.0) for task in tasks]
        values += values[:1]
        ax.plot(angles, values, label=model, marker="o")
        ax.fill(angles, values, alpha=0.1)

    ax.set_xticks(angles[:-1])
    ax.set_xticklabels(tasks)
    ax.set_ylim(0, 1.0)
    ax.legend(loc="upper right", bbox_to_anchor=(1.25, 1.1))
    ax.set_title(f"{metric} 雷达图", pad=20)
    fig.tight_layout()
    fig.savefig(output, dpi=200)
    print(f"雷达图已保存：{output}")


def main():
    parser = argparse.ArgumentParser(description="可视化 DeepSeek Harness 评测结果")
    parser.add_argument("--root", required=True, help="结果根目录，例如 results")
    parser.add_argument("--metric", required=True, help="指标名，例如 acc、acc_norm、exact_match")
    parser.add_argument("--type", choices=["bar", "radar"], required=True, help="图表类型")
    parser.add_argument("--output", required=True, help="输出图片路径，例如 results_comparison.png")
    args = parser.parse_args()

    rows = collect_results(args.root)
    if not rows:
        raise SystemExit(f"在 {args.root} 下未找到 metrics.json")

    if args.type == "bar":
        plot_bar(rows, args.metric, args.output)
    else:
        plot_radar(rows, args.metric, args.output)


if __name__ == "__main__":
    main()
```

运行示例：

```bash
# 对比不同模型/任务在 acc_norm 指标上的柱状图
python visualize_results.py \
  --root results \
  --metric acc_norm \
  --type bar \
  --output results_comparison.png

# 生成雷达图
python visualize_results.py \
  --root results \
  --metric acc_norm \
  --type radar \
  --output results_radar.png
```
## 9. 进阶用法

### 9.1 多任务批量评测

```bash
python -m deepseek_harness \
  --model deepseek-chat \
  --backend openai \
  --tasks mmlu,ceval,gsm8k,human_eval \
  --num-fewshot 5,5,0,0
```

### 9.2 多次采样计算 pass@k

代码类任务需要多次采样时，可以在任务配置中增加：

```yaml
num_samples: 20
metric_list:
  - metric: pass_at_k
    k: 5
```

### 9.3 断点续跑

如果评测中断，可以基于已有日志继续：

```bash
python -m deepseek_harness \
  --model deepseek-chat \
  --backend openai \
  --tasks mmlu \
  --continue-from ./results/deepseek-chat/mmlu
```

具体参数名以你使用的版本为准，部分版本使用 `--load-from` 或 `--resume`。

### 9.4 多进程加速

在不使用 vLLM 的情况下，可以通过增加并发请求数提升 API 吞吐：

```bash
python -m deepseek_harness \
  --model deepseek-chat \
  --backend openai \
  --tasks gsm8k \
  --num-concurrent-requests 16 \
  --request-interval 0.1
```

注意不要超过 API 速率限制，避免被限流。

## 10. 常见问题排查

### 10.1 显存不足 OOM

优先减少 `--batch-size`，或缩短 `--max-model-len`：

```bash
python -m deepseek_harness \
  --model deepseek-ai/DeepSeek-V3 \
  --backend vllm \
  --tasks mmlu \
  --batch-size 1 \
  --max-model-len 4096
```

### 10.2 API 限流

降低 `--num-concurrent-requests`，增加 `--request-interval`，或使用重试逻辑。部分版本支持 `--retry-count` 和 `--retry-delay`。

### 10.3 Hugging Face 模型或数据集下载慢

国内环境可以设置镜像：

```bash
export HF_ENDPOINT=https://hf-mirror.com
export HF_HOME=/data/huggingface
```

也可以先手动下载数据集后使用本地路径：

```bash
export HF_DATASETS_OFFLINE=1
```

### 10.4 结果与官方分数不一致

确认以下几点：

- few-shot 数量是否一致；
- 温度是否设为 0；
- 是否使用相同的提示模板；
- 选择题是否启用了 `acc_norm`；
- DeepSeek API 和本地模型的权重版本是否一致。

## 11. 总结

DeepSeek Harness 的核心价值在于把复杂评测流程标准化，让你用同一条命令切换不同后端、不同任务、不同采样策略。日常使用记住三个关键点即可：

1. 明确模型来源：API 用 `openai` 后端，本地权重用 `transformers` 或 `vllm`；
2. 明确评测任务：内置任务名直接写，自定义任务用 YAML；
3. 明确可复现性：日志、指标、采样参数都要保留。

安装完成后，建议先用一个小任务验证环境：

```bash
python -m deepseek_harness \
  --model deepseek-chat \
  --backend openai \
  --tasks gsm8k \
  --num-fewshot 0 \
  --batch-size 4
```

跑通这条命令，再逐步扩展到完整 benchmark。

DeepSeek Harness 是用于 DeepSeek 系列模型评测与推理的命令行框架，通常基于 lm-evaluation-harness 或官方评估脚本封装而来。它把“模型加载、数据预处理、批量推理、指标计算、结果落盘”整合成统一入口，适合以下场景：

DeepSeek Harness 安装教程与详细使用说明

人工智能

开发工具

测试

DeepSeekHarness评测框架安装与使用指南，支持MMLU、C-Eval、GSM8K等基准测试，可接入API、vLLM和本地权重。提供环境配置、多后端部署、自定义任务、结果可视化及断点续跑功能，简化模型评测流程并确保结果可复现。

数据预处理

代码解释

DeepSeek

Python

Linux

4核4G3M云服务器 新用户低至38元/年！

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

DeepSeek Harness 安装教程与详细使用说明-腾讯云开发者社区-腾讯云

DeepSeek Harness 安装教程与详细使用说明

DeepSeek Harness 安装教程与详细使用说明

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐