在 lm-evaluation-harness 中评测 MasakhaPOS：非洲语言词性标注任务的配置、提示设计与指标实现-平芜编程栈

在 lm-evaluation-harness 中评测 MasakhaPOS：非洲语言词性标注任务的配置、提示设计与指标实现

【免费下载链接】lm-evaluation-harnessA framework for few-shot evaluation of language models.项目地址: https://gitcode.com/GitHub_Trending/lm/lm-evaluation-harness

本篇指南聚焦lm-evaluation-harness仓库中lm_eval/tasks/afrobench/masakhapos任务实现，完整解析 MasakhaPOS（AfricaPOS）词性标注评测的目录组织、YAML 配置、五种提示模板、标签映射与准确率聚合逻辑。读完本文，你将掌握如何在 AfroBench 基准框架下运行、复现并扩展这一覆盖 20 种非洲语言的 POS 标注评测。

MasakhaPOS 任务背景：AfricaPOS 数据集与论文

MasakhaPOS 是面向类型学上高度多样的非洲语言的词性标注（Part-of-Speech Tagging）任务，其论文发表于 ACL 2023（Long Papers），核心贡献是 AfricaPOS——当时规模最大的、覆盖 20 种非洲语言的 POS 标注数据集。根据本任务目录下 README.md 中收录的论文摘要：

数据集遵循通用依存关系（Universal Dependencies, UD）标注指南构建，论文同时讨论了在多种非洲语言上应用 UD 指南进行标注时遇到的实际挑战；
作者使用条件随机场（CRF）与多种多语言预训练语言模型开展了系统的基线实验；
在单源（single-source）与多源（multi-source）两种设置下，选择最优迁移语言能够显著提升目标语言的 POS 标注性能，尤其是与参数微调方法结合时；
关键结论是：与目标语言在语系和形态句法属性上匹配的迁移语言，对未见语言的 POS 标注更有效。

在 AfroBench 基准中，MasakhaPOS 被归入masakhapos_tasks标签，与masakhaner（命名实体识别）等任务并列，作为 15 个任务之一用于评测 LLM 在非洲语言上的表现（见 afrobench/README.md）。在仓库的评测体系里，afrobench组运行该基准的全部任务，而masakhapos组则只运行 POS 任务相关的全部提示变体，便于单独审查和调试。

任务目录结构：分组、语言与提示变体

lm_eval/tasks/afrobench/masakhapos/目录采用"分组配置 + 按提示变体分目录"的组织方式：

masakhapos/ ├── masakhapos.yaml # 顶层 group 定义，聚合 5 个提示变体 ├── utils.py # doc_to_text / doc_to_target 基础实现 ├── gen_utils.py # 批量生成各语言 YAML 的脚本（含全部提示模板） ├── prompt_1/ ~ prompt_5/ # 每种提示变体一个目录 │ ├── masakhapos_yaml # 共享任务模板（无扩展名） │ ├── masakhapos_{lang}.yaml # 20 种语言各自的任务配置 │ └── utils.py # 该变体下的标签映射与聚合函数 └── README.md # 论文与引用信息

其中prompt_1至prompt_5五个目录结构完全对称，每个目录内都包含 20 个语言文件（如masakhapos_bam.yaml、masakhapos_yor.yaml、masakhapos_zul.yaml）以及一个无扩展名的共享模板文件masakhapos_yaml。这种设计让研究者既可以按语言、按提示逐一评测，也可以通过顶层 group 一次跑完全部组合。

顶层分组配置：masakhapos.yaml

masakhapos.yaml 定义了masakhapos组：

group: masakhapos task: - masakhapos_prompt_1 - masakhapos_prompt_2 - masakhapos_prompt_3 - masakhapos_prompt_4 - masakhapos_prompt_5 aggregate_metric_list: - metric: acc aggregation: mean weight_by_size: true metadata: version: 1

该配置的核心语义：

task列出五个子任务（每个提示变体本身也是由 20 种语言聚合而成的组），组名通过{dataset}_{lang}_{mode}规则生成；
aggregate_metric_list声明组的聚合指标为acc，使用mean聚合，并开启weight_by_size: true——意味着按各语言样本量加权平均，避免小语种主导整体分数；
这种"组套组"的层级（group → prompt → language）是 lm-evaluation-harness 处理大规模多语言评测的典型结构。

共享任务模板解析：masakhapos_yaml

每个prompt_N/目录下的无扩展名模板masakhapos_yaml是任务的"骨架"，全部 20 个语言文件都通过include: masakhapos_yaml继承它，再覆写dataset_name、doc_to_text与task三个字段。以 prompt_1/masakhapos_yaml 为例：

tag: - masakhapos_tasks - masakhapos_prompt_1 dataset_path: masakhane/masakhapos dataset_name: null dataset_kwargs: {trust_remote_code: True} output_type: generate_until generation_kwargs: do_sample: false until: - </s> - <|im_end|> validation_split: validation test_split: test fewshot_split: train doc_to_target: !function utils.doc_to_target should_decontaminate: true doc_to_decontamination_query: "Sentence: {{token}}\nOutput:" filter_list: - filter: - function: regex_pos name: flexible-extract metric_list: - metric: acc aggregation: !function utils.acc_score higher_is_better: true ignore_case: true ignore_punctuation: true regexes_to_ignore: - "," metadata: version: 1.0

各字段作用如下：

配置项	值	说明
`tag`	`masakhapos_tasks`、`masakhapos_prompt_N`	任务标签，`masakhapos_tasks`供 AfroBench 总标签体系索引
`dataset_path`/`dataset_name`	`masakhane/masakhapos`/`null`	数据集来源为 Masakhane 社区发布的 AfricaPOS 数据集；具体语言由语言文件中的`dataset_name`（如`bam`）指定
`dataset_kwargs`	`trust_remote_code: True`	数据集需远程加载代码，需显式信任
`output_type`	`generate_until`	生成式任务：模型自由生成，直到遇到停止符
`generation_kwargs`	`do_sample: false`、`until: [</s>, <\|im_end\|>]`	贪心解码；同时覆盖 Llama 系`</s>`与 Chat 系`<\|im_end\|>`两种结束符
`validation_split`/`test_split`/`fewshot_split`	`validation`/`test`/`train`	few-shot 示例取自训练集，验证/测试使用官方划分
`doc_to_target`	`!function utils.doc_to_target`	从样本读取`upos`整数标签并映射为 POS 标签串
`should_decontaminate`	`true`	开启去污染检查（见 docs/decontamination.md）
`filter_list`	`regex_pos`（flexible-extract）	用正则从模型输出中提取`(word, TAG)`元组列表，容忍格式噪声
`metric_list`	`acc`+`!function utils.acc_score`	词级准确率，按句子逐对计算后取均值

值得注意：metric_list中同时出现了ignore_case: true、ignore_punctuation: true与regexes_to_ignore: [","]——这三者主要作用于原始字符串匹配类指标，而 POS 任务实际分数由utils.acc_score计算；regex_pos过滤函数负责把模型输出的自由文本解析成结构化标签序列，是"生成式输出"能够被逐词打分的桥梁。

五种提示模板：从通用指令到专家角色

任务设计了 5 种提示变体，全部集中在 gen_utils.py 的prompt_func()中。它们共享同一套 POS 标签集合：ADJ, ADP, ADV, AUX, CCONJ, DET, INTJ, NOUN, NUM, PART, PRON, PROPN, PUNCT, SCONJ, SYM, VERB, X（对应 UD 通用标签体系），并要求模型输出"按输入词序排列的(word, tag)元组列表"：

prompt_1：通用指令式。"Please provide the POS tags for each word in the input sentence…"，直接面向任意语言文本，作为基线提示；
prompt_2：专家角色 + 语言注入。"You are an expert in tagging words and sentences in {lang} with the right POS tag."，其中{lang}会替换为目标语言的英文名（如Bambara），提示模型以该语言专家身份标注；
prompt_3：语言学家角色。"Acting as a {lang} linguist and without making any corrections or changes to the text…"，强调只做标注、不改动原文，约束模型不擅自改写句子；
prompt_4：任务式指令。"Annotate each word in the provided sentence with the appropriate POS tag."，措辞更简洁，弱化角色设定；
prompt_5：带标签定义的详解式。"NOUN: Noun (person, place, thing), VERB: Verb (action, state)…"——为 17 个标签逐一给出英文释义，对能力较弱的模型更友好，但提示更长。

prompt_2与prompt_3中的语言名在 YAML 生成阶段由languages字典（如bam: Bambara、zul: isiZulu、pcm: Nigerian Pidgin）注入，因此同一变体下每种语言的提示文本不同。生成后的实际效果可从 prompt_1/masakhapos_bam.yaml 与 prompt_2/masakhapos_bam.yaml 中对照查看——前者是通用指令，后者带有 "expert in tagging words and sentences in Bambara" 的角色前缀。

数据转换与标签映射：utils.py

masakhapos/utils.py 提供两个核心函数：

doc_to_text(doc)将样本构造成提示文本：以多行指令 + 标签集合开头，然后以Input: {tokens}填入样本的 token 序列，最后以Output:收尾，引导模型开始生成。从format(subject=doc["tokens"])的写法看，该函数直接使用样本中的tokens字段作为输入词表。

doc_to_target(doc)完成整数标签到 POS 标签的映射：

pos_tag_map = { 0: "NOUN", 1: "PUNCT", 2: "ADP", 3: "NUM", 4: "SYM", 5: "SCONJ", 6: "ADJ", 7: "PART", 8: "DET", 9: "CCONJ", 10: "PROPN", 11: "PRON", 12: "X", 13: "_", 14: "ADV", 15: "INTJ", 16: "VERB", 17: "AUX", } return [pos_tag_map[tag] for tag in doc["upos"]]

它把数据集中upos字段的整数编码逐一映射为 17 个 UD 标签（另有13: "_"表示空标注），返回与输入词序严格对应的标签列表。prompt_2等目录内的utils.py保留了完全相同的映射，同时额外实现聚合函数。

词级准确率聚合：acc_score

在每个prompt_N/utils.py中，acc_score(items)定义了该任务的准确率聚合逻辑，核心步骤（见 prompt_2/utils.py）：

将评测样本解包为golds与preds两组；
用chain.from_iterable把模型输出中嵌套的标签序列展平；
对每条样本，将 gold 与 pred截断到相同长度（min_length = min(len(gold), len(pred))），避免模型多生成或少生成标签导致长度不匹配；
调用sklearn.metrics.accuracy_score计算该句的词级准确率；
对所有句子取平均，得到任务的acc分数（higher_is_better: true）。

这种"先逐句对齐、再逐句打分、最后全局平均"的方式，配合regex_pos过滤，使生成式 POS 标注既能容忍输出格式抖动，又能精确反映标签预测的正确率。此外，utils.py顶部还引入了weighted_f1_score（来自lm_eval.utils），说明该任务体系同样预留了 F1 类指标的计算能力。

批量生成语言配置：gen_utils.py

由于 20 种语言 × 5 种提示 = 100 个 YAML 文件结构高度重复，仓库用 gen_utils.py 自动化生成。其关键机制：

prompt_func(mode, lang)维护五种提示模板，其中{lang}由语言全名注入；
languages字典列出 20 种 ISO 语言代码及其英文名：bam(Bambara)、bbj(Ghomala)、ewe(Ewe)、fon(Fon)、hau(Hausa)、ibo(Igbo)、kin(Kinyarwanda)、lug(Luganda)、luo(Dholuo)、mos(Mossi)、nya(Chichewa)、pcm(Nigerian Pidgin)、sna(chiShona)、swa(Kiswahili)、tsn(Setswana)、twi(Twi)、wol(Wolof)、xho(isiXhosa)、yor(Yoruba)、zul(isiZulu)——涵盖西非、东非、中非与南部非洲多个语系；
每个生成文件通过include: masakhapos_yaml继承共享模板，仅覆写dataset_name（语言代码）、task（masakhapos_{lang}_{mode}）与doc_to_text（对应提示文本）；
命令行接口支持--output-dir、--mode（prompt_1~prompt_5）与--overwrite，默认写入当前目录，文件已存在且未加--overwrite时抛出FileExistsError并列出冲突文件。

生成的文件头部均带有# Generated by utils.py注释，便于区分手写配置与生成产物。

运行评测与进一步阅读

在仓库根目录运行：

python -m lm_eval --model hf --model_args pretrained=模型名 --tasks masakhapos

即可评测全部 5 种提示、20 种语言组合；如需单独调试某个提示变体或语言，可将--tasks指定为masakhapos_prompt_1、masakhapos_bam_prompt_2等粒度。AfroBench 基准还提供了afrobench（全量）与afrobench_lite（精简版）两组入口（见 afrobench/README.md），如需了解命令行接口细节可参考 docs/interface.md，任务与配置文件规范见 docs/new_task_guide.md 与 docs/config_files.md。

本任务完整覆盖了数据源、提示设计、标签映射、过滤与聚合五个环节，是从头理解"生成式结构化标注任务"如何在 lm-evaluation-harness 中落地的典型范例。引用 MasakhaPOS 论文时，可使用 masakhapos/README.md 中给出的 BibTeX 条目（Dione et al., ACL 2023）。

【免费下载链接】lm-evaluation-harnessA framework for few-shot evaluation of language models.项目地址: https://gitcode.com/GitHub_Trending/lm/lm-evaluation-harness

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考