lm-evaluation-harness 中的 RULER 长上下文评测13 个任务、序列长度控制与数据生成原理【免费下载链接】lm-evaluation-harnessA framework for few-shot evaluation of language models.项目地址: https://gitcode.com/GitHub_Trending/lm/lm-evaluation-harnessRULER论文标题RULER: Whats the Real Context Size of Your Long-Context Language Models?arXiv 编号 2404.06654是业界用于衡量大语言模型真实上下文长度的经典合成基准。本文围绕 lm_eval/tasks/ruler/README.md 展开结合本仓库中该任务族的 YAML 配置与 Python 生成代码系统讲解如何在 lm-evaluation-harness 中运行全部 13 个 RULER 任务、如何通过--metadata控制多档序列长度、如何选择 tokenizer 与max_length并深入剖析针-草垛Needle-in-a-Haystack样本的合成原理与评分逻辑。读完本文你将能够独立配置并跑通一套完整的 RULER 长上下文评测并能读懂其底层实现。RULER 基准与三类任务设计RULER 在经典的 NIAHNeedle In A Haystack针在草垛中检索测试之上做了两方面的扩展针的多样化不再是单一的在长文本里找一句话而是引入不同类型、不同数量的针needle包括多键、多查询、多值等组合能力范畴的扩展新增**多跳追踪multi-hop tracing与聚合aggregation**两类任务用于测试模型在上下文检索之外的行为能力例如变量追踪、词频统计与开放域问答。原论文用 13 个代表性任务评测了 17 个长上下文语言模型。本仓库将这 13 个任务完整移植为 lm-evaluation-harness 的 YAML 任务族代码与配置位于 lm_eval/tasks/ruler/ 目录数据生成逻辑改编自 NVIDIA 的 RULER 实现prepare_niah.py 头部保留 Apache-2.0 版权声明。13 个评测任务全景本任务族共包含 13 个任务分为 NIAH 变体8 个、变量追踪1 个、聚合2 个与开放问答2 个四组。下表汇总了 README 中的任务说明并补充了从 niah_utils.py 源码中可验证的参数配置任务名说明关键生成参数源码依据niah_single_1NIAH 单针key词、value数字、haystackrepeat类似 passkey 检索type_haystackrepeat、type_needle_kwords、type_needle_vnumbersniah_single_2NIAH 单针key词、value数字、haystackessay即 vanilla NIAHtype_haystackessay、words/numbersniah_single_3NIAH 单针key词、valueUUID、haystackessaytype_haystackessay、type_needle_vuuidsniah_multikey_1NIAH 多键类似 line retrievalnum_needle_k4、essay/words/numbersniah_multikey_2NIAH 多键类似 KV retrievaltype_haystackneedle、words/numbersniah_multikey_3NIAH 多键键值均为 UUIDtype_haystackneedle、uuids/uuidsniah_multiqueryNIAH 多查询num_needle_q4、essay/words/numbersniah_multivalueNIAH 多值num_needle_v4、essay/words/numbersruler_vt变量追踪Variation Tracingvt.yaml vt_utils.pyruler_cwe常见词提取Common Word Extractioncwe.yaml cwe_utils.pyruler_fwe高频词提取Frequent Word Extractionfwe.yaml fwe_utils.pyruler_qa_squadQA SQuADv2聚合类问答qa_squad.yaml qa_utils.pyruler_qa_hotpotQA Hotpot多跳问答qa_hotpot.yaml qa_utils.py其中 8 个 NIAH 任务共用同一套提示词模板定义于 niah_utils.pySome special magic {type_needle_v} are hidden within the following text. Make sure to memorize it. I will quiz you about the {type_needle_v} afterwards. {context} What are all the special magic {type_needle_v} for {query} mentioned in the provided text?而针本身的格式则是One of the special magic {type_needle_v} for {key} is: {value}.当查询与答案的数量均为 1 时代码会自动把模板中的 Some 替换为 A、are 替换为 is并去掉复数后缀保证提示词语法正确见 niah_utils.py。快速上手最小运行命令直接运行整个 RULER 组13 个任务全部执行lm_eval --model hf \ --model_args pretrainedQwen/Qwen2.5-7B-Instruct,max_length32768 \ --tasks ruler \ --batch_size 1 \ --output_path results/ruler也可以只运行单个任务例如经典的 vanilla NIAHlm_eval --model hf \ --model_args pretrainedQwen/Qwen2.5-7B-Instruct,max_length32768 \ --tasks niah_single_2官方文档对此有三个必须注意的约束必须提供 tokenizerRULER 任务的样本是按 token 数精确构造的因此数据处理阶段需要分词器。系统会优先使用model_args中的tokenizer参数若未指定则回退到pretrained模型名关联的分词器。默认最大序列长度为 4096如要评测更长序列需通过 metadata 参数显式指定多档长度见下一节。建议显式设置max_length为避免长序列被模型侧截断建议在model_args中设置max_length例如--model_argspretrained...,max_length32768。依赖安装NIAH 样本生成依赖wonderwords随机词生成与nltk句子切分。若未安装代码会在导入时直接抛出提示见 prepare_niah.py可按以下任一方式安装pip install lm_eval[ruler] # 或 pip install wonderwords nltk此外nltk 版本必须不低于 3.9.1旧版本存在远程代码执行漏洞源码中有显式断言首次运行时会在 rank 0 上自动下载punkt_tab分词资源见 prepare_niah.py。控制评测序列长度metadata 与 max_seq_lengthsRULER 的核心价值在于按序列长度分档报告准确率。默认只评测 4096 一档原因在 common_utils.py 中定义DEFAULT_SEQ_LENGTHS [4096]如需一次性评测多档长度通过 metadata 传入lm_eval --model hf \ --model_args pretrained...,max_length131072 \ --tasks niah_single_2 \ --metadata{max_seq_lengths:[4096,8192,16384,32768,65536,131072]}metadata 参数同样可以传递给TaskManager即TaskManager(metadata: dict)。在生成函数内部各任务的实现通过kwargs.pop(max_seq_lengths, DEFAULT_SEQ_LENGTHS)读取该配置并对每个序列长度分别生成 500 个样本见 niah_utils.py。各任务 YAML 的metric_list中预定义了 6 档指标4096/8192/16384/32768/65536/131072全部使用higher_is_better: true并复用 common_utils.aggregate_metrics 聚合见 niah_single_1.yaml。而结果处理函数 process_results 采用一个取巧做法先把所有档位初始化为-1.0再只把当前样本实际所在档位doc[max_length]的分数填进去聚合时再剔除所有-1值。因此最终结果表中未生成样本的档位会显示为-1各档分数互不干扰。组级聚合ruler.yaml组配置文件 ruler.yaml 将 13 个任务按官方顺序列出并定义了一个组级聚合指标aggregate_metric_list: - metric: 4096 weight_by_size: False即在--tasks ruler时除了各任务各档位的分数外还会输出一个基于 4096 档、按任务等权平均的组分数。tokenizer 选择与防呆校验由于所有合成任务都按 token 数控制样本长度tokenizer 的准确性直接决定样本是否真的达到目标长度。为此 common_utils.py 中的get_tokenizer做了严格校验cache def get_tokenizer(tokenizerNone, pretrainedNone, **kwargs): pretrained tokenizer or pretrained assert pretrained, No tokenizer or pretrained provided. tok AutoTokenizer.from_pretrained(pretrained, trust_remote_codeTrue) if len(tok(The quick brown fox jumps over the lazy dog.).input_ids) 0: raise ValueError(...) return tok源码注释解释了这层防护的由来如果一个仓库只发布 GGUF 权重而没有 tokenizer 文件trust_remote_codeTrue加载出的可能是 vocab 为空的 tokenizer——它会把任何文本都编码成 0 个 token导致长度校准循环无限扩张。因此代码用一句固定测试句做自检编码结果为 0 就立即报错并给出解决建议例如通过 metadata 显式指定--metadata{tokenizer: Qwen/Qwen3-0.6B}从源码结构看get_tokenizer通过functools.cache缓存同一进程内多次调用只加载一次分词器。样本生成原理needle、haystack 与深度插入NIAH 类样本由 prepare_niah.py 生成核心是generate_input_output与generate_samples两个函数其机制可概括为三点。三种 haystack 素材get_haystack按type_haystack返回三种不同的草垛见 prepare_niah.pyessay加载baber/paul_graham_essays数据集拼接全部文章并做空白归一化得到真实英文文本流repeat重复句子The grass is green. The sky is blue. The sun is yellow. Here we go. There and back again.对应 passkey 场景needle直接用 NEEDLE 模板本身反复填充随机键值对对应 KV retrieval 场景每个草垛单元就是一条键值记录。40 档深度随机插入对于 essay 型草垛针被插入到从 0% 到 100% 均匀取样的 40 个深度位置DEPTHS np.linspace(0, 100, num40)见 prepare_niah.py。实现方式是先对文本做句子切分nltk 的sent_tokenize带 LRU 缓存再按深度百分比定位插入点确保针既可能出现在开头也可能出现在结尾覆盖不同注意力窗口。token 校准与防溢出循环generate_samples的核心是一个先放大再回退的校准循环见 prepare_niah.py以incremental为步长essay 为 500、repeat/needle 为 25短序列时再降到 5递增草垛单元数每次用 tokenizer 实测input answer的总 token 数若总 token 预留的 128 个生成 token max_seq_length则回退一个步长对每个样本再执行一次收缩直到放得下的内层循环放不下就跳过并记录警告最终每个样本都会附带length实际 token 数与max_length目标档位字段供结果处理阶段分档计分。源码中还针对历史 issue#2963做了防御如果 tokenizer 严重低估长度导致循环无法收敛会直接抛出带诊断信息的ValueError而不是无限空转。样本生成完成后还会校验答案必须存在于输入中避免生成出无效样本见 prepare_niah.py。评测指标与聚合逻辑RULER 任务的output_type为generate_until即让模型自由生成答案再由后处理脚本做字符串匹配打分。相关函数集中在 common_utils.pypostprocess_pred去除不可打印字符、规整空白string_match_all答案列表全部命中小写子串匹配才计 1 分用于 NIAH/追踪类任务process_resultsstring_match_part取答案命中比例的最大值用于 SQuAD 类开放答案任务process_results_part见 qa_squad.yamlaggregate_metrics剔除所有-1后求平均作为某一档位长度的最终准确率。在生成配置上各任务统一使用贪心解码do_sample: false、temperature: 0.0以保证可复现性max_gen_toks因任务而异——NIAH 任务为 128niah_single_1.yamlruler_vt为 30ruler_cwe为 120且target_delimiter改为\n\nruler_qa_squad为 32。这些差异化配置都体现在各自的任务 YAML 中。分组、标签、引用与后续阅读分组Groupruler组包含全部 13 个任务入口为 ruler.yaml标签Taglongcxt代表长上下文任务集合可用于--tasks的标签过滤所有 NIAH 任务的tag字段均含longcxt见 niah_single_1.yaml版本元数据各任务metadata.version为 1.0组级为 1供缓存与结果 schema 校验使用。如需在论文中引用 RULER 基准README 提供了官方 BibTeXarticle{hsieh2024ruler, title{RULER: Whats the Real Context Size of Your Long-Context Language Models?}, author{Cheng-Ping Hsieh and Simeng Sun and Samuel Kriman and Shantanu Acharya and Dima Rekesh and Fei Jia and Yang Zhang and Boris Ginsburg}, year{2024}, journal{arXiv preprint arXiv:2404.06654}, }若希望深入了解本仓库的任务配置语法、生成式任务generate_until的运作方式或想仿照 RULER 实现自己的合成数据集任务可继续阅读 docs/task_guide.md、docs/config_files.md、docs/interface.md 与 docs/new_task_guide.md模型侧的max_length、tokenizer等model_args说明见 docs/model_guide.md。RULER 任务族也是理解本仓库自定义数据集 按需生成样本这套扩展机制custom_dataset: !function ...语法的最佳范例之一。【免费下载链接】lm-evaluation-harnessA framework for few-shot evaluation of language models.项目地址: https://gitcode.com/GitHub_Trending/lm/lm-evaluation-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
