PaddleNLP SQuAD 指标模块（paddlenlp.metrics.squad）完全指南：从答案后处理到 EM/F1 评估

人工智能大模型预训练微调LoRARLHF强化学习分布式训练【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址https://gitcode.com/gh_mirrors/pa/PaddleNLP点击查看免费下载导读本文系统讲解 PaddleNLP 中面向抽取式问答Extractive QA的官方评估工具模块paddlenlp.metrics.squad对应 API 文档页面 paddlenlp.metrics.squad.rst该页面通过automodule指令自动生成。该模块承担两项核心职责将模型输出的 start/end logits 后处理为原始上下文中的答案文本compute_prediction以及基于 SQuAD 官方评测协议计算 EMExact Match与 F1 指标squad_evaluate。读完本文你将掌握如何在自己的阅读理解项目中接入这两套 API理解n_best_size、max_answer_length、null_score_diff_threshold等关键参数对答案质量与无答案判定结果的影响并能对照源码逐行看懂 SQuAD 评测的完整链路。模块定位阅读理解任务的后处理与评测工具箱paddlenlp.metrics.squad定义于 paddlenlp/metrics/squad.py其代码风格源于 SQuAD 官方评测脚本与 Transformers 生态但被移植为纯 NumPy 实现文件注释明确说明do it with numpy to stay independent from torch/tf因此可以在 CPU 环境下独立完成推理结果的后处理与指标计算不依赖深度学习框架。根据 paddlenlp/metrics/README.md 的指标总览表Squad 指标被定位为用于 SQuAD 和 DuReader-robust 的评价指标公开的 API 入口为paddlenlp.metrics.compute_predictions与paddlenlp.metrics.squad_evaluate。需要特别说明的是从当前仓库源码看paddlenlp/metrics/__init__.py并未将这两个函数直接 re-export 到包顶层命名空间因此实际使用时需要从子模块显式导入即from paddlenlp.metrics.squad import compute_prediction, squad_evaluate这一用法与仓库中的官方示例 run_squad.py 完全一致。答案后处理compute_prediction 完整拆解compute_prediction是抽取式问答推理链路的最后一环模型通常输出每个 token 作为答案起点与终点的 logits而该函数负责把这组 logits 翻译成原始上下文中的答案子串并附带概率。函数签名与参数说明def compute_prediction( examples, features, predictions, version_2_with_negativeFalse, n_best_size20, max_answer_length30, null_score_diff_threshold0.0, ):参数类型默认值说明exampleslist必填原始 SQuAD 风格数据见下方数据格式说明featureslist必填经 tokenizer 处理后的 feature每个元素需包含example_id、offset_mapping可选token_is_max_contextpredictionstuple必填模型输出必须是包含 start_logits 与 end_logits 两个列表的二元组version_2_with_negativeboolFalse数据集是否包含无答案样本SQuAD 2.0 特性n_best_sizeint20每个问题最终保留的候选答案数量上限max_answer_lengthint30允许的最大答案长度按 token 计注意 docstring 中Defaults to 20为注释笔误源码实际默认 30null_score_diff_thresholdfloat0.0仅在version_2_with_negativeTrue时生效用于判定空答案的分数差阈值数据格式约定examples每个元素至少包含id、context字段SQuAD 2.0 场景下还应包含is_impossible或answers字段供后续squad_evaluate使用。features与examples是多对一关系一个长文本问题可能被切分为多个 feature。每个 feature 必须包含example_id所属原始 example 的 idoffset_mapping每个 token 在原始 context 中的字符区间(start, end)若某 token 不属于 context如[CLS]、[SEP]等特殊 token则为None或空列表token_is_max_context可选布尔字典标注该 token 在当前 feature 中是否拥有最大上下文用于过滤跨窗口切分导致的半上下文答案。核心算法流程建立 example 到 feature 的映射利用examples[id]构建example_id_to_index再把所有 feature 按example_id归组到features_per_examplesquad.py。逐 feature 枚举候选答案对每个 feature取 start/end logits 中分数最高的前n_best_size个位置np.argsort降序切片两两组合生成候选 span并执行三重过滤squad.py越界或offset_mapping为None/空的位置直接跳过end_index start_index反向 span或end_index - start_index 1 max_answer_length超长跳过若提供了token_is_max_context起点不在最大上下文内的候选被剔除。空答案null候选的追踪始终记录start_logits[0] end_logits[0]即[CLS]位置得分之和作为空答案分数min_null_predictionsquad.py。汇总与 softmax 归一化对每个 example 的全部候选按分数降序取前n_best_size个通过offset_mapping还原为 context 子串再用 LogSumExp 技巧计算 softmax 概率squad.py。极端情况下若无任何非空候选会插入一条{text: empty, ...}占位预测防止后续崩溃。最终答案选择squad.pySQuAD 1.x直接取概率最高的候选文本SQuAD 2.0先找最佳非空预测计算score_diff null_score - start_logit - end_logit若score_diff null_score_diff_threshold则判定该问题无答案输出空字符串否则输出最佳非空答案。返回值三元组(all_predictions, all_nbest_json, scores_diff_json)——all_predictions{qid: 最终答案文本}all_nbest_json{qid: n_best 候选列表}含text、start_logit、end_logit、probabilityscores_diff_json{qid: score_diff}仅 SQuAD 2.0 有实际意义所有数值均转为 Python float 以保证 JSON 可序列化。指标计算squad_evaluate 与 EM/F1 详解compute_prediction产出答案后需要squad_evaluate对照标准答案计算 EM 与 F1。SQuAD 的 EM/F1 是字符/词级别匹配指标与分类任务常用的 token 级指标完全不同下面结合源码说明其实现。答案归一化normalize_answer 与 compute_exact / compute_f1normalize_answer(s)squad.py依次执行小写化、去标点remove_punctuation内置了中英文标点集合含。“”《》……·、「」『』等全角字符、去掉英文冠词a/an/the、压缩多余空白。compute_exact(a_gold, a_pred)归一化后字符串完全相等返回1否则返回0。compute_f1(a_gold, a_pred, is_whitespace_splitedTrue)对归一化后的字符串做分词默认按空白切分英文场景适用中文可置False此时退化为整句比对用collections.Counter计算交集词数进而得到 precision、recall 与 F1若两侧均为空则按是否相等返回1或0squad.py。原始分数统计get_raw_scoresget_raw_scores(examples, preds, is_whitespace_splitedTrue)对每个 example 取answers[text]中的全部标准答案并过滤掉归一化后为空串的答案对每个预测取所有标准答案中 EM/F1 的最大值max-over-gold 策略缺失预测的 qid 会通过logger.info打印告警squad.py。无答案样本的处理与阈值搜索SQuAD 2.0 的核心难点是区分模型答错与确实无答案。该模块提供了一整套辅助函数make_qid_to_has_ans(examples)根据is_impossible字段或answers是否为空构造 qid 的是否有答案映射。apply_no_ans_threshold(scores, na_probs, qid_to_has_ans, na_prob_thresh)当某 qid 的na_probs即scores_diff_json超过阈值时认为模型预测无答案此时若真实也无答案则计1.0分否则计0.0分squad.py。make_eval_dict/merge_eval汇总 EM/F1 的总体结果与HasAns/NoAns分组结果格式为{exact: ..., f1: ..., total: ...}。find_best_thresh/find_all_best_thresh在验证集上按na_probs排序扫描寻找使总分数最大的最优na_prob_thresh输出best_exact、best_exact_thresh、best_f1、best_f1_threshsquad.py。主入口squad_evaluatedef squad_evaluate(examples, preds, na_probsNone, na_prob_thresh1.0, is_whitespace_splitedTrue):参数类型默认值说明exampleslist必填原始 SQuAD 风格数据predsdict必填compute_prediction返回的all_predictionsna_probsdictNone各 qid 的 score_diff即scores_diff_json用于空答案判定为None时全置0.0na_prob_threshfloat1.0判定无答案的阈值仅 SQuAD 2.0 有意义is_whitespace_splitedboolTrue是否按空白分词计算 F1英文为 True中文建议 False执行流程squad.py构造qid_to_has_ans拆分has_ans_qids与no_ans_qids用get_raw_scores计算原始 EM/F1用apply_no_ans_threshold结合阈值得到过滤后的分数make_eval_dict生成总体指标若存在有答案/无答案样本则分别追加HasAns_*、NoAns_*分组指标存在无答案样本时还会输出best_exact、best_f1及对应最优阈值通过logger.info(json.dumps(out_eval, indent2))打印结果并返回该 dict。实战接入在 run_squad 流程中的完整调用链仓库官方示例 run_squad.py 完整演示了两个 API 的配合方式其评估函数evaluate的核心逻辑如下run_squad.pyall_predictions, all_nbest_json, scores_diff_json compute_prediction( examples[raw_data for raw_data in raw_dataset], featuresfeatures, predictions(all_start_logits, all_end_logits), version_2_with_negative..., n_best_size20, max_answer_length30, null_score_diff_threshold0.0, ) squad_evaluate(examples[raw_data for raw_data in raw_dataset], predsall_predictions, na_probsscores_diff_json)对应数据集加载run_squad.pySQuAD 2.0 使用load_dataset(squad_v2, ...)SQuAD 1.x 使用load_dataset(squad, ...)均通过trust_remote_codeTrue加载。完整的训练与评估脚本位于slm/examples/machine_reading_comprehension/SQuAD/目录slm/model_zoo下的bert/static_ipu、luke、megatronbert、mpnet/squad等子目录中也提供了基于不同骨干模型的 run_squad 实现可作为多模型适配参考。此外该模块还被子模块 paddlenlp/metrics/dureader.py 复用支撑 DuReader 系列中文阅读理解数据集的指标计算这与 README 中SQuAD 和 DuReader-robust 评价指标的定位相互印证。使用建议与注意事项导入路径请从子模块导入from paddlenlp.metrics.squad import compute_prediction, squad_evaluate勿依赖包顶层导出。参数调优n_best_size太小可能漏掉正确 spanmax_answer_length过小会截断长答案源码默认 30超过 SQuAD 官方脚本常见的 30 上限之外的答案会被丢弃null_score_diff_threshold与na_prob_thresh共同控制 SQuAD 2.0 的无答案判定灵敏度实际部署前建议用find_all_best_thresh在验证集上标定最优阈值。中文场景计算 F1 时建议将is_whitespace_splited置为False否则按空白切分会把整句当作单个 token导致 F1 退化为 EM 式的整句匹配。纯 NumPy 实现整个模块不依赖 paddle/torch/tf 张量logits 需预先转成 Python list 或 NumPy 数组便于在推理服务端独立部署评测。总结paddlenlp.metrics.squad是 PaddleNLP 抽取式阅读理解任务的标准评测后端compute_prediction负责把模型 logits 解码为可读答案并输出候选概率squad_evaluate负责按官方协议计算 EM/F1含 SQuAD 2.0 的无答案处理与最优阈值搜索。结合 slm/examples/machine_reading_comprehension/SQuAD/run_squad.py 即可搭建一套完整的抽取式问答训练与评测流水线且这套指标逻辑同样适用于 DuReader 系列中文数据集。赞分享人工智能大模型预训练微调LoRARLHF强化学习分布式训练【免费下载链接】PaddleNLPEasy-to-use and powerful LLM and SLM library with awesome model zoo.项目地址https://gitcode.com/gh_mirrors/pa/PaddleNLP点击查看免费下载相关推荐VibeVoice-TTS深度解析90分钟4人长对话合成背后的ICLR 2026 Oral技术秘密VibeVoice TTS深度解析90分钟4人长对话合成背后的ICLR 2026 Oral技术秘密 VibeVoice TTS 是微软开源的长对话多说话人 文语音音频人工智能大模型模型推理服务微调PaddleNLP Metrics 指标库完全指南从困惑度到 SQuAD 的模型评价实践PaddleNLP Metrics 指标库完全指南从困惑度到 SQuAD 的模型评价实践 PaddleNLP 在 paddlenlp.metrics 子包中内人工智能大模型预训练微调LoRARLHF强化学习分布式训练模型推理服务推理引擎模型量化模型压缩本地部署NLPDeepSeek-R1评估指标详解pass1、EM与F1分数对比DeepSeek R1评估指标详解pass1、EM与F1分数对比 引言大模型推理能力评估的三大核心指标 你是否在选择大模型时被各种评估指标搞得眼花缭乱为基础模型大模型人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考