WinoGrande 基准评测任务解析：在 lm-evaluation-harness 中实现 44k 规模的对抗式 Winograd 常识推理评测

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

WinoGrande 是一个基于 Winograd Schema Challenge 扩展而来的大规模二元填空常识推理基准，包含约 44k 个对抗式生成的问题。本文以本仓库eval/lm-evaluation-harness中 WinoGrande 任务的官方实现为主线，讲解其数据集背景、部分评估协议、YAML 任务配置、Python 预处理逻辑以及底层 multiple_choice 评测机制的完整调用链，帮助你掌握如何在该评测框架中运行、定制与验证这一经典常识推理任务。

背景：从 Winograd Schema 到 44k 规模对抗样本

WinoGrande（论文标题WinoGrande: An Adversarial Winograd Schema Challenge at Scale，作者 Sakaguchi、Le Bras、Bhagavatula 与 Choi，2019）是 Winograd Schema Challenge（Levesque, Davis, and Morgenstern 2011）的大规模改进版本。原始 Winograd 模式是一类"利用句法歧义触发代词指代消解、且词汇替换即可翻转答案"的特殊句子，人工构造成本极高；WinoGrande 通过对抗式数据生成与过滤流程，将问题规模扩展到了44k 个样本，并显著降低了数据集中可被模型"走捷径"的统计偏置（dataset-specific bias）。

任务被形式化为fill-in-a-blank（填空）任务：给定一个句子，句子中有一个占位符（_），模型需要从两个候选词（option1/option2）中选择正确的一项填入。虽然表面上是词汇选择，解题真正依赖的是常识推理——例如"奖杯太重，因为奖杯/行李箱太大"这类需要理解物性关系的句子。

注意：本仓库对该任务的评测采用部分评估（partial evaluation）协议，该方法由 Trinh & Le 在A Simple Method for Commonsense Reasoning（2018）中提出。与整句生成式评估不同，部分评估只要求模型对"占位符之后的补全片段"计算条件对数似然，从而将常识推理转化为更稳定的判别式（选择）任务。该约定已写入本任务的官方 README：tasks/winogrande/README.md。

任务实现全景：三个核心文件

WinoGrande 任务的实现由三个文件构成，彼此分工明确：

三者共同构成一个完整的TaskConfig：YAML 声明"是什么"，Python 函数定义"怎么映射"，README 说明"为什么这样设计"。

配置详解：default.yaml 逐字段拆解

default.yaml 是本任务配置的权威来源，全文如下：

task: winogrande dataset_path: winogrande dataset_name: winogrande_xl output_type: multiple_choice training_split: train validation_split: validation doc_to_text: !function preprocess_winogrande.doc_to_text doc_to_target: !function preprocess_winogrande.doc_to_target doc_to_choice: !function preprocess_winogrande.doc_to_choice should_decontaminate: true doc_to_decontamination_query: sentence metric_list: - metric: acc aggregation: mean higher_is_better: true metadata: version: 1.0 dataset_kwargs: trust_remote_code: true

各字段的实际含义如下（与 lm_eval/api/task.py 中TaskConfig数据类的字段定义一一对应）：

• task: winogrande：任务在注册表中的唯一名称，CLI 中通过--tasks winogrande引用。
• dataset_path: winogrande/dataset_name: winogrande_xl：HuggingFacedatasets库的加载路径与子集名。winogrande_xl即 XL 规模划分（约 10k+ 验证样本）。dataset_kwargs中设置trust_remote_code: true，因为该数据集依赖 Hub 上仓库自带的加载脚本。
• output_type: multiple_choice：声明本任务是判别式多选任务。框架会为每个选项分别构造loglikelihood请求，并比较各选项的对数似然来决定预测——这是部分评估协议在实现层面的落点。
• training_split: train/validation_split: validation：训练集用于 few-shot 示例采样，验证集（10,267 条）用于实际评测。TaskConfig中同样预留了test_split、fewshot_split字段，本任务未显式使用。
• doc_to_text/doc_to_target/doc_to_choice：三个!function引用，指向preprocess_winogrande.py中同名函数，负责把原始 doc 字典转换为文本/答案/选项。详见下一节。
• should_decontaminate: true+doc_to_decontamination_query: sentence：开启去污染（decontamination）流程，以sentence字段作为与训练语料比对去重的查询串。这与本仓库 docs/decontamination.md 描述的去污染机制一致。
• metric_list：唯一指标为acc，聚合方式mean，higher_is_better: true。对应 api/metrics.py 中注册的准确率聚合器。
• metadata.version: 1.0：任务配置的版本号，随任务格式变更而递增。需要注意的是，仓库 tests/testdata 中遗留的旧版回归数据winogrande-v0-res.json记录的是version 0（见下文"测试验证"），二者并不冲突——那是历史回归快照。

数据预处理逻辑：preprocess_winogrande.py 逐函数剖析

preprocess_winogrande.py 只有三个短函数，却完整承担了"原始字段 → 评测三元组"的转换：

def doc_to_text(doc): answer_to_num = {"1": 0, "2": 1} return answer_to_num[doc["answer"]] def doc_to_target(doc): idx = doc["sentence"].index("_") + 1 return doc["sentence"][idx:].strip() def doc_to_choice(doc): idx = doc["sentence"].index("_") options = [doc["option1"], doc["option2"]] return [doc["sentence"][:idx] + opt for opt in options]

三者配合的原理：

1. doc_to_choice：构造候选。原始样本中sentence形如"The trophy doesn't fit into the brown suitcase because _ is too big."，option1/option2是两个候选词（如"the suitcase"/"the trophy"）。函数定位占位符_，分别将两个选项拼接到前缀sentence[:idx]之后，生成两个完整的候选句子。这样模型比较的是"整句 + 补全"的连贯文本条件似然，而非孤立单词。
2. doc_to_target：确定 gold 补全。从占位符之后取sentence[idx+1:]作为正确补全片段。由于两个选项接在前缀后的句子都共享同一段后缀，doc_to_target实际上主要用于对齐与长度统计。
3. doc_to_text：返回答案序号。将 HF 数据集中的answer字段（"1"或"2"）映射为 0/1 索引。从实现结构看，该返回值配合 task.py 中process_results的 gold 对齐逻辑使用：当 gold 为整数时直接作为选项下标；gold 为字符串时则通过choices.index(gold)换算。

框架对doc_to_choice的解析支持多种形态（见 task.py）：字符串（直接作为字段名或模板求值）、列表、字典或可调用对象。本任务采用可调用对象形式，将字段访问逻辑留在 Python 侧，保证对 HuggingFace 原始格式的零侵入。

底层机制：multiple_choice 请求如何被构造与打分

理解 WinoGrande 评测，关键在于框架对output_type: multiple_choice的处理。核心调用链在 task.py 的construct_requests中：

elif self.OUTPUT_TYPE == "multiple_choice": choices = self.doc_to_choice(doc) target_delimiter = self.config.target_delimiter ... # Otherwise they are placed in the continuation arguments = [(ctx, f"{target_delimiter}{cont}") for cont in choices]

即：对每个样本，框架为每个候选生成一个(上下文, 补全)元组，封装为request_type="loglikelihood"的Instance。模型侧对每个候选计算log P(补全 | 上下文)（默认target_delimiter为空格，见TaskConfig默认值）。

评分阶段（process_results，task.py）做三件事：

1. 解包每个候选的(loglikelihood, is_greedy)；
2. 用np.argmax(lls)取对数似然最高的候选作为预测（另有基于长度归一化lls / completion_len的pred_norm变体）；
3. 将预测与 gold 对齐，计算acc（预测是否等于正确答案的 0/1），再按metric_list中的aggregation: mean汇总。

这印证了 README 中"部分评估"的含义：模型无需生成完整句子，只需对两个补全片段做判别式打分，与 Trinh & Le (2018) 的协议一致。若未来需要在metric_list中加入acc_mutual_info，construct_requests中已预留了对无条件对数似然（aux_arguments = [("", choice) for choice in choices]）的扩展逻辑，用于互信息归一化。

运行与验证：CLI 命令与回归测试

命令行评测

在 README.md 中，winogrande与其他常识推理基准并列出现在多任务评测示例中。单独运行本任务的标准方式是（仓库采用lm_eval命令入口，可参考main.py）：

lm_eval \ --model hf \ --model_args pretrained=<你的模型路径或 Hub 模型名> \ --tasks winogrande \ --num_fewshot 5 \ --batch_size auto

关键参数说明：

• --tasks winogrande：只评测本任务；也可与openbookqa,arc_easy,hellaswag,arc_challenge,piqa,boolq等合并为多任务一次跑完。
• --num_fewshot：few-shot 示例从training_split: train采样（TaskConfig.fewshot_split默认回退逻辑）。
• --batch_size auto：自动探测最优批大小。
• 评测完成后，结果中会输出acc及其标准误（如acc_stderr），结构形如{"winogrande": {"acc": ..., "acc_stderr": ...}}。

回归测试依据

仓库测试目录保留了一份历史回归快照 tests/testdata/winogrande-v0-res.json，内容为：

{"results": {"winogrande": {"acc": 0.516179952644041, "acc_stderr": 0.014045126130978606}}, "versions": {"winogrande": 0}}

它记录了该任务在早期实现（version 0）下的一次参考运行结果（acc ≈ 51.6%，接近多数类基线），可用于校验框架升级后任务格式与打分逻辑是否保持稳定；versions字段与 YAML 中metadata.version: 1.0的差异说明该快照早于当前配置版本，属于历史数据而非当前基准预期值。相关回归断言逻辑可参阅 tests/test_evaluator.py。

引用与任务清单说明

Citation

本任务的官方 README 给出的标准引用格式（BibTeX）如下，评测论文或复现实验时可直接使用：

@article{sakaguchi2019winogrande, title={WinoGrande: An Adversarial Winograd Schema Challenge at Scale}, author={Sakaguchi, Keisuke and Bras, Ronan Le and Bhagavatula, Chandra and Choi, Yejin}, journal={arXiv preprint arXiv:1907.10641}, year={2019} }

Groups / Tasks / Checklist

• Groups：winogrande目前不属于任何评测组（"Not part of a group yet"），因此它不会出现在 group 聚合结果中；若需纳入某组，需另建 group 配置并在其中引用winogrande。
• Tasks：当前注册的任务名仅winogrande一个。
• Checklist：README 末尾附带的清单是框架维护者的自查模板，逐项确认"是否为文献已有基准、是否引用原始论文、是否对照参考实现验证、主变体是否明确标注、各变体差异是否在 README 中说明"等要求。这说明：任何基于 WinoGrande 的新变体（如换数据集规模、换评估协议）在合入框架前，都应遵循同样的记录规范——包括在 README 中注明其相对主任务增加了什么、匹配了哪套已发表评测设置。

小结

在本仓库的 lm-evaluation-harness 中，WinoGrande 评测是一个"声明式配置 + 函数式映射 + 判别式打分"的标准范式：default.yaml声明数据源（winogrande_xl）与输出类型（multiple_choice），preprocess_winogrande.py将填空句子拆解为可比较的候选补全，底层construct_requests/process_results以部分评估协议计算条件对数似然并输出acc。掌握这一实现脉络后，你既可以一键运行该基准复现常识推理能力，也可以仿照其结构为其他填空式多选数据集（或为 WinoGrande 的新变体）编写同风格的任务配置。

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