InfoXLM 版 fairseq 命令行工具全解析：preprocess、train、generate、interactive、score 与 eval-lm 的实战指南

InfoXLM 版 fairseq 命令行工具全解析preprocess、train、generate、interactive、score 与 eval-lm 的实战指南【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm本文基于 InfoXLM 仓库内嵌的 fairseq 工具链command_line_tools.rst整理。官方文档将六个命令行入口数据预处理、训练、批量翻译、交互式翻译、BLEU 打分、语言模型评测的参数说明交给 Sphinx 的 argparse 自动文档生成本文将这些“只列了名字”的工具逐一对应到仓库中的真实源码实现说明每个命令的核心参数、默认行为与底层调用链帮助读者在 InfoXLM 这类多语言预训练模型的研究与复现中正确搭建“数据准备 → 训练 → 推理 → 评测”的完整流水线。六个命令行工具总览与安装官方文档开篇明确了工具集合及其职责划分命令职责入口实现文件fairseq-preprocess数据预处理构建词表并将训练数据二进制化preprocess.pyfairseq-train在单卡或多卡上训练一个新模型train.pyfairseq-generate用训练好的模型翻译已预处理的测试数据generate.pyfairseq-interactive用训练好的模型翻译原始文本交互模式interactive.pyfairseq-score对生成的译文相对参考译文做 BLEU 打分score.pyfairseq-eval-lm语言模型评测困惑度eval_lm.py从源码结构看文档中每个小节使用的.. argparse::指令:module: fairseq.options 各get_*_parser函数意味着正式渲染出的文档里每个命令的完整参数表都是由对应 parser 函数动态生成的因此参数语义的唯一权威来源就是 fairseq/options.py 所在的 fairseq 包 与各fairseq_cli入口文件。命令的注册方式定义在 setup.py 的entry_points中约第 149–158 行entry_points{ console_scripts: [ fairseq-eval-lm fairseq_cli.eval_lm:cli_main, fairseq-generate fairseq_cli.generate:cli_main, fairseq-interactive fairseq_cli.interactive:cli_main, fairseq-preprocess fairseq_cli.preprocess:cli_main, fairseq-score fairseq_cli.score:main, fairseq-train fairseq_cli.train:cli_main, fairseq-validate fairseq_cli.validate:cli_main, ], },安装该包pip install .或python setup.py install后上述命令即可在 shell 中直接使用。该仓库中 fairseq 版本号为0.9.0见 setup.py 第 119 行运行依赖torch、sacrebleu、numpy、regex等install_requires列表。需要注意fairseq-score的入口函数是main而非cli_main这是一个与其余命令不一致的细节。fairseq-preprocess构建词表并二进制化训练数据preprocess.py 的文档字符串概括了它的职责“Data pre-processing: build vocabularies and binarize training data.”。结合源码可以梳理出完整的处理流程与关键参数核心参数--task任务类型决定词表构建行为由tasks.get_task(args.task)分派--trainpref / --validpref / --testpref训练/验证/测试语料的公共前缀路径其中 valid、test 支持逗号分隔的多个 split会被依次处理并命名为valid、valid1、test、test1……见make_all函数第 225–235 行--destdir输出目录程序会自动os.makedirs创建--source-lang / --target-lang源/目标语言标识用于拼接文件后缀如train.en--srcdict / --tgtdict直接复用已有词表文件--joined-dictionary源目标共用一个词表对 BERT 式多语言模型尤其常用。注意源码中的约束它与--srcdict、--tgtdict互斥第 62–64 行assert--only-source只处理源端此时target False不构建目标词表--workers多进程并行数。源码中Binarizer.find_offsets先切分输入文件区间再由multiprocessing.Pool各写一个临时.bin分片最后ds.merge_file_合并并finalize生成.idx第 96–147 行。词表构建细节build_dictionary闭包第 47–55 行显示词表由任务侧的task.build_dictionary构建受以下参数控制--thresholdsrc / --thresholdtgttoken 频次阈值低于该值的 token 不进入词表--nwordssrc / --nwordstgt词表大小上限--padding-factor词表大小对齐到该因子的倍数便于 padded batch 对齐。处理完成后输出会打印每条语料被unk替换的比例第 149–158 行这是判断预处理质量的第一手指标若替换比例过高通常需要调低--thresholdsrc或调大--nwordssrc。对齐文件的特殊支持--align-suffix若存在trainpref . align_suffix文件会解析词级对齐信息并二进制化为train.align数据集make_binary_alignment_dataset第 160–212 行--alignfile基于对齐文件统计每个源词最常对齐的目标词写出alignment.{src}-{tgt}.txt对齐词典第 253–293 行。该词典正是后续fairseq-generate --replace-unk的依据之一。输出命名规则由dataset_dest_file决定数据集文件形如{destdir}/train.{src}-{tgt}.{lang}.bin与.idx第 322–336 行当--dataset-implraw时则只是复制原始文本文件供--raw-text场景使用第 214–223 行。fairseq-train单机多卡分布式训练train.py 的文档字符串是 “Train a new model on one or across multiple GPUs.”它是六个工具中逻辑最重的一个。前置校验与任务初始化main函数开头第 26–27 行有一条硬性断言assert args.max_tokens is not None or args.max_sentences is not None, \ Must specify batch size either with --max-tokens or --max-sentences即必须用--max-tokens或--max-sentences指定每 GPU 的 batch 规模二者至少给一个。随后按固定顺序完成utils.import_user_module(args)加载用户自定义模块 → 按--seed设置随机种子 → 分布式初始化distributed_utils.distributed_init→tasks.setup_task(args)建立任务 → 加载验证集 →task.build_model与task.build_criterion构建模型和损失 → 构造Trainer[fairseq.trainer.Trainer](https://link.gitcode.com/i/f2c63c7c48d69b3784f045c09702acb0)。训练主循环的终止条件主循环第 82–87 行同时受三重约束while ( lr args.min_lr and (epoch_itr.epoch max_epoch or (...)) and trainer.get_num_updates() max_update ):也就是说训练会在“学习率跌破--min-lr”“达到--max-epoch”“达到--max-update”三者中先发生者处停止——对预训练任务通常由前两者之一自然终止。每个 epoch 结束后按--validate-interval决定是否跑验证validate函数对args.valid_subset中的每个 split 求损失用第一个验证集的args.best_checkpoint_metric值更新学习率trainer.lr_step按--save-intervalepoch 粒度或--save-interval-updates更新步粒度见第 170–181 行保存 checkpoint并通过checkpoint_utils.save_checkpoint维护 “best” 判定best_checkpoint_metricmaximize_best_checkpoint_metric见get_valid_stats第 296–313 行。梯度累积与多卡启动方式--update-freq支持按 epoch 递进的列表train函数中update_freq args.update_freq[epoch_itr.epoch - 1]第 115–116 行实现“训练初期累积更多 mini-batch 再更新”的调度--fix-batches-to-gpus将 batch 固定到 GPU配合GroupedIterator使用--curriculum指定前 N 个 epoch 不 shuffle第 121 行。cli_main第 324–358 行展示了三种启动路径指定了--distributed-init-method且多卡用torch.multiprocessing.spawn每卡 spawn 一个进程除非--distributed-no-spawn未指定 init method 但--distributed-world-size 1在tcp://localhost:{随机端口}上 fallback 到 spawn 多进程源码还在此处提示--ddp-backendno_c10d可能更快第 349–350 行其余情况单卡直接main(args)。训练日志中会持续打印loss / ppl / wps / ups / bsz / gnorm / clip / oom等指标get_training_stats第 201–223 行这些字段名对监控脚本解析日志非常有用。fairseq-generate批量推理与自动 BLEUgenerate.py 用于“翻译已预处理的测试数据”。源码开头有三条值得记住的约束第 17–21 行assert args.path is not None, --path required for generation! assert not args.sampling or args.nbest args.beam, \ --sampling requires --nbest to be equal to --beam assert args.replace_unk is None or args.raw_text, \ --replace-unk requires a raw text dataset (--raw-text)即--pathcheckpoint 目录支持:分隔的 ensemble 多 checkpoint 平均是必填项用--sampling随机采样解码时--nbest必须等于--beam--replace-unk用对齐词典替换译文unk只在--raw-text原始文本数据上可用。关键行为细节默认 batch 大小若两者均未指定args.max_tokens回退为12000第 25–26 行——与训练命令“必须指定”形成对比模型加载后调用model.make_generation_fast_(beamable_mm_beam_size..., need_attnargs.print_alignment)第 51–55 行--print-alignment会改变前向计算图以额外输出注意力对齐生成前缀约束--prefix-size 0时取目标前 K 个 token 作为 prefix 输入task.inference_step第 100–104 行输出协议非--quiet时逐样本打印若干行这是后续脚本化解析的“稳定接口”S-id\t源句 T-id\t参考译文 H-id\tscore\t假设译文 P-id\t每位置对数概率空格分隔 A-id\tsrc-idx-tgt-idx ... # 仅在 --print-alignment I-id\t迭代步骤 # 仅在 --print-step打分方式默认用内部bleu.Scorertoken 级、带 pad/eos/unk 处理加--sacrebleu则切换为bleu.SacrebleuScorer直接对字符串打分第 86–89 行有参考集时最终打印| Generate subset with beambeam: BLEU结果。fairseq-interactive交互式原始文本翻译interactive.py 定位是“Translate raw text with a trained model”——与 generate 的区别在于它不要求预先 binarize 数据而是直接读取原始文本行典型用法--input-file -从标准输入逐行读入或管道喂入按与 generate 相同的参数体系--beam、--batch-size/max-tokens等组织 batch 后调用任务生成器。对快速验证 checkpoint 效果、或对接在线服务做 smoke test 都很方便。fairseq-score独立的 BLEU 打分器score.py 是一个刻意保持轻量的独立工具它不加载任何模型只依赖argparse、fairseq.bleu与fairseq.data.dictionary。参数定义在get_parser第 18–32 行参数默认值说明-s, --sys-标准输入系统输出文件-r, --ref必填参考译文文件-o, --order4计算到 n 元语法BLEU-4 即默认--ignore-caseoff不区分大小写打分--sacrebleuoff改用sacrebleu.corpus_bleu打分--sentence-bleuoff报告逐句 BLEU带 1 平滑并逐句打印执行逻辑分三支第 54–78 行--sacrebleu走 sacrebleu 库--sentence-bleu用内部bleu.Scorer每句reset(one_initTrue)后打印该句result_string否则累积全语料后打印 corpus 级结果。-s -时从sys.stdin读取因此与fairseq-generate的输出可以直接管道拼接构成“生成即评测”的常用工作流。fairseq-eval-lm语言模型困惑度评测eval_lm.py 的文档字符串是 “Evaluate the perplexity of a trained language model.”核心流程--path必填通过checkpoint_utils.load_model_ensemble加载同样支持:分隔的 ensemble并用--model-overrides覆盖架构参数--context-window若大于 0把每个样本的可用 token 数从--tokens-per-sample中扣除并包裹LMContextWindowDataset做滑动上下文评测第 72–85 行batch 迭代默认max_tokens36000第 102 行并用SequenceScorer对每个样本计算逐位置 log 概率BPE 修正--remove-bpe指定结尾标记时把子词片段的概率累加回完整词上再统计第 119–129、163–168 行保证困惑度按“词”而非“子词”计算sentencepiece 分支未实现会抛NotImplementedError最终输出第 211–213 行| Evaluated {N} tokens in {T}s ({r} tokens/s) | Loss: {nll:.4f}, Perplexity: {ppl:.2f}另有--output-word-probs与--output-word-stats两个诊断选项会打印每个词的对数概率与逐词统计WordStat第 20–43 行用于检查模型对特定词的行为。--num-shards / --shard-id支持把评测集分片到多个进程。实践建议以文档为纲、以源码为据的排错路径文档与源码对照本仓库文档页 command_line_tools.rst 的参数表由fairseq.options中get_preprocessing_parser、get_training_parser、get_generation_parser、get_interactive_generation_parser、get_eval_lm_parser自动生成因此升级或修改选项后以这些函数为准重新渲染文档即可保持同步典型复现流水线fairseq-preprocess先确认unk替换率→fairseq-train观察wps/loss日志与 best checkpoint 指标→fairseq-generate解析H-行→fairseq-score -r ref.txt或 generate 内建 sacrebleu语言建模任务则把最后两步替换为fairseq-eval-lm适用前提以上参数与行为均基于本仓库infoxlm/fairseq下 fairseq 0.9.0 的实际代码若你使用 PyTorch 官方发布的新版 fairseq部分选项如--raw-text、--ddp-backend的具体取值可能已有变化请以你所用版本的--help输出为准。【免费下载链接】unilmLarge-scale Self-supervised Pre-training Across Tasks, Languages, and Modalities项目地址: https://gitcode.com/GitHub_Trending/un/unilm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考