lm-evaluation-harness 中的 squad_completion 任务：面向小模型的零样本 SQuAD 补全评测实战指南

• 大模型
• 推理模型
• 微调
• 模型推理服务

导读

lm_eval/tasks/squad_completion是 lm-evaluation-harness 内置的一个问答（QA）评测任务变体，它源自论文Simple Linear Attention Language Models Balance The Recall-Throughput Tradeoff（即 Stanford 的 Based 项目），将经典 SQuAD 阅读理解任务改造成"补全（completion）"形式，专为零样本（zero-shot）评估小规模语言模型设计。读完本文，你将掌握该任务的定位、数据来源、评测指标与完整命令行用法，并能结合 task.py 的源码理解其底层实现原理，以及它与标准squadv2任务的关键差异。本仓库（s1 测试时扩展项目）将 lm-evaluation-harness 整体收纳于 eval/lm-evaluation-harness 目录，任务文档与实现均以该目录为根。

一、任务背景：从 SQuAD 到 Based 的 completion 变体

1.1 出处论文与 Based 项目

任务 README 明确指出，squad_completion是 SQuAD 问答任务的一个变体，由 HazyResearch 的 Based 项目（based-evaluation-harness）实现。其对应的核心论文为：

• 标题：Simple Linear Attention Language Models Balance The Recall-Throughput Tradeoff（简单线性注意力语言模型在"召回-吞吐量"之间取得平衡）
• 主题：研究线性注意力架构语言模型在长上下文召回能力与推理吞吐量之间的权衡

该任务用于零样本评测小规模 LM（README 原话为 "Designed for zero-shot evaluation of small LMs"）。也就是说，它不依赖 few-shot 示例，直接让模型在给定上下文与问题后自由续写答案，再用"答案是否包含在生成文本中"来打分。

1.2 关联论文与引文信息

任务同时关联两篇论文的 BibTeX 引用（详见 README）：

@misc{arora2024simple, title={Simple linear attention language models balance the recall-throughput tradeoff}, author={Simran Arora and Sabri Eyuboglu and Michael Zhang and Aman Timalsina and Silas Alberti and Dylan Zinsley and James Zou and Atri Rudra and Christopher Ré}, year={2024}, eprint={2402.18668}, archivePrefix={arXiv}, primaryClass={cs.CL} } @misc{rajpurkar2018know, title={Know What You Don't Know: Unanswerable Questions for SQuAD}, author={Pranav Rajpurkar and Robin Jia and Percy Liang}, year={2018}, eprint={1806.03822}, archivePrefix={arXiv}, primaryClass={cs.CL} }

其中第二条引用的是 SQuAD 2.0 论文Know What You Don't Know: Unanswerable Questions for SQuAD（Rajpurkar 等，2018），说明该变体在数据上继承了 SQuAD 2.0 的背景设定（详见 squadv2/README.md）。

二、任务定义与数据来源

2.1 任务清单

tasks部分登记的任务为：

squad_completion：SQuAD 任务在论文"Simple linear attention language models balance the recall-throughput tradeoff"中的实现形式，专为零样本评估小 LM 设计。

这意味着该目录只注册了一个任务名squad_completion，未注册任何组（group）。

2.2 数据与配置

任务的数据与行为由两份文件共同定义：

YAML 配置极其精简，仅两行：

task: squad_completion class: !function task.SQUADCompletion

其中class: !function task.SQUADCompletion通过函数标签把任务绑定到task.py中的SQUADCompletion类。

2.3 数据集的底层配置

从 task.py 可以看到任务的 HF 数据集配置：

class SQUADCompletion(ConfigurableTask): VERSION = 0 DATASET_PATH = "hazyresearch/based-squad" DATASET_NAME = "default"

• DATASET_PATH = "hazyresearch/based-squad"：直接从 Hugging Face Hub 拉取 Based 团队发布的 SQuAD 变体数据集；
• DATASET_NAME = "default"：使用默认数据子集；
• VERSION = 0：任务版本号，用于结果缓存与复现标识。

首次运行时需要联网下载该数据集；如果环境禁止联网或数据集未公开，任务将无法加载，这是该任务的使用前提。

三、如何运行：命令行实战

该任务属于ConfigurableTask，可直接通过 lm-evaluation-harness 的 CLI 运行。入口参数定义在main.py。下面给出针对该任务的最简命令：

lm-eval \ --model hf \ --model_args pretrained=EleutherAI/pythia-160m \ --tasks squad_completion \ --num_fewshot 0 \ --batch_size auto \ --device cuda:0 \ --output_path results/squad_completion

参数说明：

其他常用参数还包括--gen_kwargs（覆盖生成参数）、--log_samples（配合--output_path保存逐样本结果）、--wandb_args（接入 Weights & Biases）等。任务名检查：执行lm-eval --tasks list_subtasks可确认squad_completion是否已成功注册。

四、源码级解读：任务如何工作

4.1 数据划分：只有验证集

task.py 定义了数据划分方式：

def has_training_docs(self): return False def has_validation_docs(self): return True def has_test_docs(self): return False def validation_docs(self): return self.dataset["validation"]

任务没有训练集与测试集，评测只使用validation划分。这与标准squadv2（存在训练集）不同，进一步印证其"小模型零样本快速评估"的定位。

4.2 提示词与答案构造

def doc_to_text(self, doc): return doc["text"] def doc_to_target(self, doc): return doc["value"]

数据集样本包含text与value两个字段：

• doc_to_text直接返回text字段作为模型输入上下文（即"阅读材料 + 问题"的拼接文本）；
• doc_to_target返回value字段作为标准答案（gold answer）。

可见数据预处理（如上下文与问题的格式化）已在数据集侧完成，任务实现因此保持极简。

4.3 请求类型：generate_until 生成式补全

def construct_requests(self, doc, ctx, **kwargs): return [ Instance( request_type="generate_until", doc=doc, arguments=(ctx, {"until": ["\n"], "max_gen_toks": 48}), idx=0, **kwargs, ) ]

这是本任务与标准squadv2的关键区别之一：只发送一个generate_until生成请求，不发送任何loglikelihood似然请求。生成参数为：

• until: ["\n"]：遇到换行符即停止生成（答案通常为单行短文本）；
• max_gen_toks: 48：最多生成 48 个 token，防止无界续写。

generate_until属于 task.py 中ALL_OUTPUT_TYPES声明的四种输出类型之一，由模型后端逐 token 生成。

4.4 评分指标：contains（包含匹配）

def process_results(self, doc, results): continuation = results return {"contains": contains_score(continuation[0], [doc["value"]])} def aggregation(self): return {"contains": np.mean} def higher_is_better(self): return {"contains": True}

• 单样本指标为contains：判断标准答案是否出现在模型生成文本中；
• 聚合方式为np.mean，即全验证集上的平均contains；
• higher_is_better = True，分数越高越好。

contains_score的具体实现（task.py）：

def contains_score(prediction: str, labels: List[str]): return max( int(bool(re.search(re.compile(re.escape(label), re.IGNORECASE), prediction))) for label in labels )

评分要点：

1. 对每个候选答案标签用re.escape转义后编译正则；
2. re.IGNORECASE忽略大小写，在预测文本中做子串搜索；
3. 对多个候选标签取最大值（当前实现只传入了doc["value"]一个标签）；
4. 返回0/1布尔值，聚合为均值后即得到 0~1 之间的任务分数。

这个"答案包含于生成文本"的宽松匹配，比标准 SQuAD 的精确 EM（Exact Match）与 F1 要简单得多，也更适合小模型在零样本条件下的能力探测——小模型往往能"提对答案"却无法给出规范化的精确格式。

五、与标准 squadv2 任务的对比

同仓库下的 squadv2 是 SQuAD 2.0 的官方实现，与squad_completion形成鲜明对照：

从源码结构可以推断：squadv2追求的是与官方评测协议一致的 EM/F1 指标，并显式建模"无答案"情形；而squad_completion走的是"轻量补全 + 包含匹配"路线，评测成本低、实现简单，适合快速横向对比小模型。当你在论文Simple Linear Attention Language Models...的设定下复现实验时，应使用squad_completion；当需要与 SQuAD 2.0 官方基准对齐时，则应使用squadv2。

六、使用前提与注意事项

1. 网络依赖：数据集hazyresearch/based-squad需从 Hugging Face Hub 拉取，离线环境不可用；
2. 零样本定位：README 明确该任务面向零样本评测小 LM，若传入大量 few-shot 示例，其设计意图将被改变；
3. 指标宽松性：contains是包含式匹配，可能存在"预测文本恰好包含答案词但语义错误"的误判，解读结果时需结合模型生成样本（可用--log_samples --output_path保存逐样本输出）人工抽查；
4. 结果可复现：可用--seed固定随机种子（默认0,1234,1234,1234），并借助--cache_requests缓存数据集请求构建结果，加速重复实验；
5. 只读仓库：本任务文件位于只读仓库内，如需扩展或改造，建议基于该任务结构（yaml +ConfigurableTask子类）在本地新目录中自行实现，勿直接修改仓库内容。

七、小结

squad_completion是 lm-evaluation-harness 中一个"小而美"的问答评测任务：以 Based 论文的数据集hazyresearch/based-squad为源，仅用验证集、单一generate_until请求和contains包含匹配指标，即可完成对小语言模型的零样本快速评测。理解它的设计，既能让你直接复现论文评测流程，也能为自定义轻量 QA 任务（yaml + task.py 两件套）提供最简范例——这也是它作为开源基准任务的参考价值所在。

• 大模型
• 推理模型
• 微调
• 模型推理服务