nlp-recipes 模型评估指南:从分类指标到 SQuAD 问答、ROUGE 摘要与句向量评测的完整实践

原创2026-10-07 10:35:561,635 阅读
文章标签:NLP

nlp-recipes 模型评估指南:从分类指标到 SQuAD 问答、ROUGE 摘要与句向量评测的完整实践

导读

本文聚焦 utils_nlp/eval 评估子模块,系统讲解 nlp-recipes 中用于衡量 NLP 模型性能的完整工具链:包括文本分类场景的准确率、精确率、召回率与 F1 指标,问答任务基于 SQuAD 的 EM/F1 官方评估与"不可回答问题"阈值调优,摘要任务的 ROUGE(含 Perl 版与纯 Python 版、多语言扩展),以及基于 SentEval 的句向量迁移评测。阅读本文后,你将掌握该仓库中每个评估 API 的输入输出约定、底层实现原理与可复现的调用方式,并能直接将其接入自己的模型训练与评测流程。

评估子模块总览

在 nlp-recipes 中,评估能力被组织在 utils_nlp/eval 目录下,模块入口 utils_nlp/eval/init.py 对外暴露 compute_rouge_perl 与 compute_rouge_python 两个摘要评估函数。整个子模块按任务类型划分为以下几类:

任务类型 核心文件 提供的指标
通用分类 classification.py accuracy、precision、recall、f1、混淆矩阵、相关系数
问答(SQuAD v1.1) evaluate_squad.py exact_match、f1
问答(SQuAD v2.0) question_answering.py exact、f1、HasAns/NoAns 拆分、最优阈值
摘要 rouge/ + evaluate_summarization.py ROUGE-N、ROUGE-L(支持英文与印地语)
句向量 senteval.py + SentEval/ MR、CR、SUBJ、MPQA、SST、TREC、MRPC、SICK、SNLI、STS 等迁移任务指标

通用分类指标:一个函数拿到全部核心分数

对于文本分类、情感极性判断、意图识别等场景,classification.py 封装了 sklearn 的标准指标。其中核心 API 是 eval_classification(actual, predicted, round_decimals=4),它一次返回四个指标组成的字典:

from utils_nlp.eval.classification import eval_classification

metrics = eval_classification(
    actual=[0, 1, 1, 0, 1],
    predicted=[0, 1, 0, 0, 1],
    round_decimals=4,
)
# 输出形如:
# {
#   "accuracy": 0.8,
#   "precision": [1.0, 0.6667],   # 按类别分别计算
#   "recall": [0.6667, 1.0],
#   "f1": [0.8, 0.8],
# }

从源码看,precision_score、recall_score、f1_score 均以 average=None 调用,因此返回的是每个类别各自的分数列表,而非宏平均或加权平均,这对类别不均衡的诊断非常直观;accuracy_score 则返回整体准确率。round_decimals 参数默认为 4,控制小数位数。

同文件还提供两个辅助工具:

  • compute_correlation_coefficients(x, y=None):基于 numpy.corrcoef 计算 Pearson 积矩相关系数矩阵,返回 pandas DataFrame,可用于分析嵌入向量各维度之间的相关性(如句向量基线实验中的维度冗余分析)。
  • plot_confusion_matrix(y_true, y_pred, labels, normalize=False, title="Confusion matrix", plot_size=(8, 5), font_scale=1.1):用 Seaborn 热力图绘制混淆矩阵。当 normalize=True 时按行归一化(每行和为 1),便于观察每个真实类别被预测到哪些类别;labels 必须与类别顺序一致,plot_size 与 font_scale 控制图形尺寸与字号。

该函数族在分类示例中与模型训练流程配套使用,评测入口可参考 utils_nlp/eval/README.md 的定位说明——它属于"general evaluation metrics"层,向上支撑 examples/text_classification 等示例的模型效果验证。

问答任务评估:SQuAD 的 EM 与 F1

问答是 nlp-recipes 的重点场景之一,评估侧提供两个文件,分别对应 SQuAD 的两个版本。

SQuAD v1.1:官方评估脚本

evaluate_squad.py 直接移植自 bi-att-flow 项目的官方 v1.1 评估脚本,可当作命令行工具使用,也可作为模块导入:

python utils_nlp/eval/evaluate_squad.py <dataset_file> <prediction_file>

其中 dataset_file 是 SQuAD v1.1 格式的 JSON(含 version 字段,脚本会校验必须是 1.1),prediction_file 是以 qa_id 为键、预测答案文本为值的 JSON。输出为 {"exact_match": ..., "f1": ...}。

核心计算逻辑值得展开说明:

  • normalize_answer(s):统一做小写、去冠词(a、an、the)、去标点、压缩空白,让答案比较不受格式干扰;
  • f1_score(prediction, ground_truth):对归一化后的 token 序列求交集计数,进而算 precision、recall 与 F1;
  • metric_max_over_ground_truths(...):一个问题通常有多个标注答案,取预测答案与所有标准答案中最高的得分;
  • evaluate(dataset, predictions):遍历全部文章的段落与问题,累计 EM/F1 后乘以 100 输出百分制分数;对没有预测的问题会向 stderr 打印 "Unanswered question ... will receive score 0." 并跳过。

SQuAD v2.0:处理不可回答问题

SQuAD v2.0 引入了"无答案"样本,question_answering.py 在 XLNet 作者的修改基础上,实现了带"不可回答概率阈值"的完整评估流程。主入口为 evaluate_qa(actual_dataset, preds, na_probs=None, na_prob_thresh=0, unanswerable_exists=False, out_file=None):

  • actual_dataset:utils_nlp.dataset 中的 QADataset 类实例,评估时逐项取 item.qa_id 与 item.answer_text;
  • preds:{qa_id: 预测答案文本} 字典;
  • na_probs:{qa_id: 不可回答概率} 字典,为 None 时所有概率置 0;
  • na_prob_thresh:判定"该问题不可回答"的概率阈值,当 na_probs[qid] > na_prob_thresh 时预测视为"无答案";
  • out_file:非空时将评估结果以 JSON 形式写出,否则打印到终端。

评估输出是一个 OrderedDict,包含 exact、f1、total,并进一步拆分 HasAns_* 与 NoAns_* 两组子分数,便于单独观察有答案/无答案子集的表现。若提供了 na_probs,还会追加 best_exact、best_exact_thresh、best_f1、best_f1_thresh;当存在不可回答样本时额外给出 has_ans_exact 与 has_ans_f1。

底层两个关键函数决定了这些分数如何产生:

  • get_raw_scores(qa_ids, actuals, preds):不做任何阈值处理,逐问句计算原始 EM/F1,并对每条标准答案取最大值;对无答案问题,gold 视为空字符串。
  • find_best_thresh(...):通过枚举所有 na_probs 升序排列的阈值,找出使总得分最优的"不可回答判定阈值"。其思想是:阈值越低,越多问题被判为不可回答;正确判为不可回答的样本贡献 +1,有答案却判为不可回答则损失其原始分。该函数返回百分制最优得分与对应阈值。

在 utils_nlp/models/transformers/question_answering.py 的评测流程中即可看到 evaluate_qa 与模型预测的配合方式,相关端到端实践可参考 examples/question_answering/question_answering_squad_transformers.ipynb。

摘要任务评估:三种 ROUGE 计算途径

摘要质量评估是文本生成任务的关键环节,nlp-recipes 在 utils_nlp/eval/rouge/ 下提供了三种途径,统一由 compute_rouge.py 暴露。

途径一:compute_rouge_perl(官方 Perl 版)

compute_rouge_perl(cand, ref, is_input_files=False, verbose=False) 基于 pyrouge 的 Rouge155 包装官方 Perl 版 ROUGE。其工作流程是:在临时目录创建 candidate/ 与 reference/ 两个子目录,按序写入 cand.{i}.txt 与 ref.{i}.txt,然后调用 convert_and_evaluate() 并解析出全部 ROUGE 分数;结束后清理临时目录。参数约定:

  • cand / ref:当 is_input_files=False 时是逐条摘要的字符串列表;为 True 时是包含摘要文本的文件路径(每行一条);
  • verbose=True 时打印完整 ROUGE 原始输出;
  • 函数内部断言候选与参考条数相等,因此调用前务必保证两者长度一致。

使用该途径需要本机安装 Perl 版 ROUGE 与 pyrouge 依赖,适合需要与官方结果严格对齐的场景。

途径二:compute_rouge_python(纯 Python 版)

compute_rouge_python(cand, ref, is_input_files=False, language="en") 使用 py-rouge 包,无需 Perl 环境。英文场景下使用 Rouge(metrics=["rouge-n", "rouge-l"], max_n=2, limit_length=False, apply_avg=True),即计算 ROUGE-1、ROUGE-2 与 ROUGE-L,且不对摘要长度做截断,并对所有样本取平均。返回值中每个指标包含 f、p、r 三个分量。

途径三:RougeExt——非英语(印地语)扩展

nlp-recipes 的印地语摘要评测 通过 RougeExt 类支持 language="hi"。该类继承 py-rouge 的 Rouge,针对非英语语言替换了五类语言相关组件,这也是它区别于原版的核心:

  1. 句子切分器(SENTENCE_SPLIT_DICT,使用 indicnlp 的 sentence_split);
  2. 词元切分器(WORD_TOKENIZE_DICT,使用 indic_tokenize.trivial_tokenize);
  3. 需移除的字符模式(REMOVE_CHAR_PATTERN_DICT,额外包含天城文句读 \u0964、\u0965);
  4. 词干化器(STEMMER_DICT,使用 utils_nlp/language_utils/hi/hindi_stemmer.py 的 hi_stem);
  5. 词切分器(WORD_SPLIT_DICT,为将来支持如中文这类无空格分词语言预留,目前为空)。

RougeExt 的构造函数完整继承了 Rouge 的参数体系:metrics(ROUGE-N/ROUGE-L/ROUGE-W)、max_n、limit_length/length_limit/length_limit_type(默认按 665 字节截断)、apply_avg/apply_best、stemming、alpha(F1 加权系数,默认 0.5)与 weight_factor(ROUGE-W 权重,官方为 1.2)。注意 compute_rouge_python 内部对非英语语言强制 limit_length=False。

支持的语言集合在 supported_langauges = ["en", "hi"] 中定义;若传入其他语言且未同时提供 sentence_split_func、word_tokenize_func、remove_char_pattern,会抛出明确异常。因此要扩展新语言,只需仿照印地语实现这五类回调函数即可。

途径四:evaluate_summarization.get_rouge(BertSum 配套)

utils_nlp/eval/evaluate_summarization.py 中的 get_rouge(predictions, targets, temp_dir, random_seed=42) 面向 BERTSUM 系列模型,它调用 bertsum.others.utils.test_rouge 完成评测,并将预测与参考分别写入临时目录中的随机命名文件。其应用场景是 examples/text_summarization 中抽取式/生成式摘要模型的训练后评测,以及 tests/integration/test_ddp_summarization.py 等分布式训练集成测试。

句向量评测:SentEval 迁移任务配置

句向量(sentence embedding)模型的通用评测遵循 SentEval 协议,仓库在 utils_nlp/eval/SentEval 下内置了完整实现(engine.py、binary.py、probing.py、sick.py、snli.py、sst.py、trec.py、sts.py、mrpc.py、rank.py 等任务模块),并在 senteval.py 中提供 SentEvalConfig 配置容器,用于统一管理模型参数与 SentEval 运行参数:

  • model_params:跨所有评测任务保持一致的模型参数;
  • senteval_params:跨所有评测任务保持一致的 SentEval 参数;
  • append_senteval_params(params):运行时追加参数,并校验分类型迁移任务(MR、CR、SUBJ、MPQA、SST2、SST5、TREC、SICKEntailment、SNLI、MRPC)的 classifier 配置——若未提供 classifier,或其中缺少 nhid、optim、batch_size、tenacity、epoch_size 五个键,会打印 ValueError 提示,防止带着不完整配置跑出无效结果。

该配置类的实际用法可见于句向量示例 examples/sentence_similarity/bert_senteval.ipynb 与 examples/sentence_similarity/gensen_local.ipynb:先实例化 SentEvalConfig(model_params, senteval_params),再通过 append_senteval_params 注入任务列表与分类器超参,最后驱动 SentEval 引擎逐任务输出指标。句向量评测的配套数据下载脚本位于 utils_nlp/eval/SentEval/data/downstream/get_transfer_data.bash。

评估结果的可靠性保障:单元测试与集成测试

仓库为评估模块提供了可验证的依据,便于你确认各 API 的行为预期:

这些测试同时说明了评估函数的两条使用约定:输入长度必须对齐(ROUGE 内部有 assert len(candidates) == len(references)),以及问答评估要求预测字典的键与数据集 qa_id 一一对应(缺失键会打印 "Missing prediction for %s" 并跳过该样本)。

小结

utils_nlp/eval 以"通用指标 + 任务专用指标"双层结构覆盖了 nlp-recipes 的四大主流任务:分类用 eval_classification 一行拿到 accuracy/precision/recall/f1,问答按 SQuAD v1.1/v2.0 分别提供官方脚本与带阈值调优的 evaluate_qa,摘要支持 Perl 版、纯 Python 版与印地语扩展三种 ROUGE 计算,句向量评测则通过 SentEvalConfig 对接内置的 SentEval 任务集。结合上述单元测试与 examples 中的各任务 notebook,你可以把评估环节直接嵌入训练管线,实现"训练—评估—调优"的闭环。

登录后查看全文
nlp-recipes