vLLM MRCR 长上下文精度评估：原理、运行方式与阈值配置详解

MRCR（Multi-Round Coreference Resolution，源自 OpenAI 的 openai/mrcr 数据集）是 vLLM 仓库内置的长上下文行为烟雾测试：模型需要在一段包含多个近似重复"针"（needle）的超长对话中，逐字复现某个特定的历史助手轮次，且回复必须以随机防猜测字符串开头。本文基于 tests/evals/mrcr/README.md 及其配套源码 mrcr_eval.py、test_mrcr_correctness.py，完整讲清这一评估的打分规则、pytest 与独立脚本两种运行方式、全部配置参数，以及样本加载、token 校验、阈值判定的源码级实现，帮助你在修改注意力后端、滑窗、分块 prefill 或前缀缓存后，用可复现的量化指标验证长上下文正确性是否退化。

什么是 MRCR：任务设计与打分规则

MRCR 数据集的每条样本是一段长对话，其中埋有若干（2/4/8 根）内容高度相似的"针"，最后要求模型逐字复述其中一个特定历史轮次。样本自带一个随机字符串 random_string_to_prepend，要求模型把它拼在答案最前面——这样模型即使"背住"了数据集也猜不中前缀，从而杜绝靠记忆蒙对的可能。

打分逻辑在 score_mrcr() 中实现，是"前缀门控 + 相似度"两阶段：

def score_mrcr(response: str, answer: str, random_prefix: str) -> float:
    """Prefix-gated SequenceMatcher ratio; 0 if the prefix is missing."""
    if not response.startswith(random_prefix):
        return 0.0
    stripped = response[len(random_prefix) :]
    return SequenceMatcher(a=answer, b=stripped, autojunk=False).ratio()

• 若回复不以 random_string_to_prepend 开头，直接记 0 分；
• 否则剥掉前缀，对参考答案计算 difflib.SequenceMatcher.ratio()，取各样本均值即 match_ratio。

除 match_ratio 外，评估还会输出前缀命中率 prefix_hit_rate、按 needle 分桶的 match_ratio_n2 / n4 / n8、样本数、总耗时、输出 token 吞吐（tokens_per_second）等指标（见 evaluate_mrcr() 返回字典），并可用 --save-results 落盘为 JSON 便于回归对比。

两种运行方式：Pytest 托管服务器 vs 独立脚本对接已启动服务

方式一：Pytest（自动拉起服务器）

pytest -s -v tests/evals/mrcr/test_mrcr_correctness.py \
    --config-list-file=configs/models-small.txt

注意 README 中的 --config-list-file 是相对于测试目录解析的：conftest.py 的 pytest_generate_tests 会先在 tests/evals/mrcr/ 目录下查找该清单文件，找不到再回落到当前工作目录。清单文件 configs/models-small.txt 目前登记了一份 YAML 配置，每个有效行对应一个被参数化的测试用例（以文件名为测试 ID）。

Pytest 用例 test_mrcr_correctness() 的执行链是：读取 YAML → 把 server_args 拆成参数并追加 --trust-remote-code --disable-uvicorn-access-log → 用 RemoteOpenAIServer 上下文管理器拉起 OpenAI 兼容服务器 → 调用 evaluate_mrcr() → 按阈值判定是否失败。默认最长等待 600 秒（startup_max_wait_seconds 可配）。

方式二：独立脚本（服务器已启动）

# 先启动服务（reasoning 模型需指定推理解析器）
vllm serve Qwen/Qwen3-0.6B --reasoning-parser qwen3 --port 8000

# 模型名与上下文长度自动发现
python tests/evals/mrcr/mrcr_eval.py --port 8000

独立脚本会自动发现服务端信息：discover_server_model() 请求 /v1/models 取第一个模型 ID 及其 max_model_len，未指定 --model 时直接采用该值。这意味着你不需要在客户端重复配置模型名，上下文长度也"跟着服务器声明走"。

配置详解：YAML 字段与命令行参数

Pytest 模式下的 YAML 配置

README 给出的完整配置示例如下（字段说明来自 README Configuration 一节）：

model_name: "Qwen/Qwen3-0.6B"
# Per-needle thresholds catch bucket-specific regressions (sliding window,
# chunked prefill, prefix cache) that an aggregate can hide. A scalar
# (e.g. `match_ratio_threshold: 0.20`) is also accepted and checked against
# the mean match ratio.
match_ratio_threshold:
  2: 0.30
  4: 0.15
  8: 0.10
num_samples: 30
needles: [2, 4, 8]
# max_prompt_tokens: 32768       # Optional; defaults to server max_model_len - max_tokens - 256
max_tokens: 2048
concurrency: 8
server_args: "--max-model-len 32768 --reasoning-parser qwen3"

当前仓库登记的真实配置 configs/Qwen3.5-4B.yaml 则展示了按 needle 分桶的严格阈值与 128K 上下文：

model_name: "Qwen/Qwen3.5-4B"
needles: [2, 4, 8]
match_ratio_threshold:
  2: 0.99
  4: 0.84
  8: 0.76
server_args: "--max-model-len 128K --reasoning-parser qwen3"

逐字段说明：

字段	默认值	含义
model_name	必填	待评估模型，Pytest 模式下同时用于拉起服务器
match_ratio_threshold	必填	字典形式按 needle 分桶判阈值，或标量对照总均值 match_ratio
num_samples	40（见 evaluate_mrcr 签名）	总样本数，均分到各 needle 桶
needles	[2, 4, 8]	参与评估的 needle 桶，仅支持 2/4/8
max_prompt_tokens	服务端 max_model_len - max_tokens - 256	提示词 token 上限；客户端可覆盖以调低
max_tokens	2048	单条回复的最大生成 token 数
concurrency	8	并发请求数（asyncio.Semaphore 控制）
server_args	""	追加给 vllm serve 的原始参数
extra_body	默认 {"chat_template_kwargs": {"enable_thinking": false}}	合并进每个请求体的额外 JSON
tolerance	0.05	阈值判定容差
startup_max_wait_seconds	600	服务器启动等待上限

阈值判定的源码在 test_mrcr_correctness.py：字典阈值逐桶比对 match_ratio_nN（某桶无样本直接记失败），标量阈值比对总 match_ratio，两者都允许 tolerance（默认 0.05）的松弛量。分桶阈值的意义在于：滑窗注意力、分块 prefill、前缀缓存等实现通常只影响特定长度区间，总均值可能掩盖单桶退化。

独立脚本的全部命令行参数

来自 mrcr_eval.py 的 argparse 定义：

参数	默认值	说明
--model	自动从 /v1/models 发现	请求体中的模型名
--num-samples	40	总样本数
--needles	2 4 8（可选值 2/4/8）	needle 桶列表
--max-prompt-tokens	服务端 max_model_len - max_tokens - 256，下限 512	提示词 token 上限
--max-tokens	2048	最大生成 token 数
--host	http://127.0.0.1	服务器地址
--port	8000	服务器端口
--temperature	0.0	采样温度，确定性复现
--seed	42	采样种子，同时派生样本洗牌种子
--concurrency	8	并发请求数
--extra-body	默认关闭 thinking 的 extra_body	合并进请求的 JSON；传 {} 可禁用默认项
--save-results	不保存	结果 JSON 输出路径

样本加载与双重 token 校验机制

数据源是 HuggingFace 上的 openai/mrcr 仓库，但评估从不下载完整的 1.4 GB 数据集。NEEDLE_SHARDS 只映射三个 parquet 分片：

NEEDLE_SHARDS = {
    2: "2needle/2needle_0.parquet",
    4: "4needle/4needle_0.parquet",
    8: "8needle/8needle_0.parquet",
}

加载流程（_load_mrcr_samples()）分四层：

1. 桶内均衡配额：num_samples 均分到各 needle 桶，余数分配给靠前的桶；每桶不足时打印警告。
2. 流式洗牌：以 datasets 库 streaming=True 方式加载对应分片，shuffle(seed=seed+n, buffer_size=16)——不同桶用不同种子，保证各桶样本独立可复现。
3. 字符级预过滤：n_chars × 4 ≤ max_prompt_tokens（CHARS_PER_TOKEN = 4 的启发式，见 第 28-31 行），快速丢弃明显超长的样本，避免浪费请求。
4. /tokenize 权威校验：对通过预过滤的样本，用 count_chat_tokens() 调用服务器的 /tokenize 端点，在真实 chat template 下渲染出准确的 token 数，超过 max_prompt_tokens 才最终丢弃。该端点由 vllm/entrypoints/serve/tokenize/api_router.py 的 POST /tokenize 路由提供。

这个双重校验的意义在于：预过滤是廉价的近似，而 chat template 的实际展开（角色标记、生成提示等）只有走服务端的 /tokenize 才能精确度量，从而保证进入评估的每条样本都在服务端声明的上下文窗口之内。max_prompt_tokens 默认公式为 max(512, max_model_len - max_tokens - 256)，其中 256 是 PROMPT_SAFETY_BUFFER，为 chat template 的额外 token 预留余量；控制烟雾测试的上下文长度应改服务端的 --max-model-len，而不是在客户端绕开该公式。

请求细节与 reasoning 模型的正确处理

评估对每条样本发起标准 /v1/chat/completions 请求（temperature=0、固定 seed、max_tokens 见上表），由 asyncio.Semaphore 限制并发，单请求超时 30 分钟，失败请求记空回复（前缀门控下自动得 0 分）。

对 reasoning 模型有两个关键处理：

1. 默认关闭 thinking：DEFAULT_EXTRA_BODY 为 {"chat_template_kwargs": {"enable_thinking": False}}，跳过思维链以免干扰被评分答案；非 reasoning 模板会忽略该键。
2. 服务端 --reasoning-parser：即使未完全关闭，--reasoning-parser qwen3（或 deepseek_r1 等）会把 <think> 内容路由到 message.reasoning_content，使其不污染进入 message.content 的被打分答案。这也是 README 示例中 vllm serve ... --reasoning-parser qwen3 的原因。

适用前提与注意事项

• 客户端需安装 datasets 库（缺失时 mrcr_eval.py 会抛出带安装提示的 ImportError）；评估会从 HuggingFace 流式拉取样本，需要网络可达。
• 若服务器未在 /v1/models 中声明 max_model_len，独立脚本会要求显式传 --max-prompt-tokens（见 evaluate_mrcr()）。
• needles 仅支持 2/4/8，其他值在加载阶段即报错（Unsupported needle count）；所有桶都装不下样本时抛出 No MRCR samples fit，提示放宽 max_prompt_tokens。
• 该测试定位是烟雾测试（smoke test）：样本量小、关注"是否退化"而非绝对能力排名，因此阈值应随模型与上下文窗口单独标定——参考 Qwen3.5-4B.yaml 中 128K 窗口下 0.99/0.84/0.76 的逐桶阈值写法。

综上，vLLM 的 MRCR 评估以"前缀门控相似度"作为核心打分，以 needle 分桶阈值捕捉特定机制引入的长上下文回归，配合 /tokenize 端点做模板级 token 校验，并原生支持 reasoning 模型。修改注意力实现或 KV 缓存路径后，用 pytest -s -v tests/evals/mrcr/test_mrcr_correctness.py --config-list-file=configs/models-small.txt 跑一轮回归，是仓库内置的低成本验证手段。