Transformers 摘要生成（Summarization）微调实战：run_summarization.py 与 run_summarization_no_trainer.py 完整流程解析

• 推理引擎
• 大模型

本文是围绕 HuggingFace Transformers 官方示例中 Summarization 任务的实战技术指南。它基于本仓库内 Summarization 示例目录 的说明文档展开，系统讲解如何利用run_summarization.py与run_summarization_no_trainer.py两个脚本，在 CNN/DailyMail、XSum 等标准数据集或自备 CSV/JSONLINES 数据上，对 BART、Pegasus、T5 等序列到序列模型进行摘要生成任务的微调与评估。读完本文，你将掌握两种训练范式（Trainer高层封装与Accelerate裸训练循环）的完整命令行用法、关键参数语义、数据格式约定以及 ROUGE 评估的实现原理。

一、示例定位：它在当前仓库中的角色

在 FlexGen 仓库中，benchmark/third_party/transformers是为基准测试维护的 HuggingFace Transformers v4.24.0 分支（安装方式见 benchmark/third_party/README.md：在目录下执行pip3 install -e .并安装accelerate==0.15.0）。本文聚焦的 Summarization 示例位于：

• run_summarization.py：基于Trainer的高层封装脚本（共 732 行）；
• run_summarization_no_trainer.py：基于Accelerate的裸训练循环脚本（共 759 行）；
• requirements.txt：运行所需依赖清单；
• README.md：官方使用说明（本文主体骨架）。

两个脚本均通过check_min_version("4.24.0")与require_version("datasets>=1.8.0")做版本校验，因此建议在 Transformers ≥ 4.24.0、datasets ≥ 1.8.0 的环境下运行。原 README 中已废弃的bertabs与旧版finetune_trainer.py相关内容不在本仓库示例范围内，本文不展开。

二、支持的模型架构

run_summarization.py通过AutoModelForSeq2SeqLM自动加载模型，官方支持以下条件生成（conditional generation）架构：

在源码层面（run_summarization.py），脚本通过AutoModelForSeq2SeqLM.from_pretrained加载权重，AutoConfig加载配置、AutoTokenizer加载分词器。若model_name_or_path包含.ckpt后缀，会自动以from_tf=True从 TensorFlow checkpoint 转换（run_summarization.py）。

三、环境与依赖准备

requirements.txt 列出完整依赖：

accelerate datasets >= 1.8.0 sentencepiece != 0.1.92 protobuf rouge-score nltk py7zr torch >= 1.3 evaluate

其中py7zr用于解压 CNN/DailyMail 等以 7z 压缩包分发的数据集；rouge-score与nltk用于 ROUGE 指标计算；sentencepiece与protobuf是 T5、mBART、Pegasus 等模型分词器所需；accelerate供无 Trainer 脚本使用。此外，nltk的punkt分词数据会在脚本首次运行时自动下载（脚本内置了FileLock与离线模式处理，见 run_summarization.py）。

若使用本仓库内的 Transformers 分支，安装命令为（见 benchmark/third_party/README.md）：

cd benchmark/third_party/transformers pip3 install -e . pip3 install accelerate==0.15.0

四、使用 Trainer 微调（run_summarization.py）

4.1 最小可运行示例

以 T5-small 在 CNN/DailyMail 3.0.0 配置上微调为例（对应 README.md 中的官方命令，脚本路径按本仓库调整为仓库根目录相对路径）：

python benchmark/third_party/transformers/examples/pytorch/summarization/run_summarization.py \ --model_name_or_path t5-small \ --do_train \ --do_eval \ --dataset_name cnn_dailymail \ --dataset_config "3.0.0" \ --source_prefix "summarize: " \ --output_dir /tmp/tst-summarization \ --per_device_train_batch_size=4 \ --per_device_eval_batch_size=4 \ --overwrite_output_dir \ --predict_with_generate

命令逐项解读：

• --model_name_or_path t5-small：指定预训练模型（HuggingFace Hub 模型 ID 或本地路径）；
• --do_train/--do_eval：开启训练与验证阶段（脚本要求至少传入其一，否则提示 "There is nothing to do" 并退出，见 run_summarization.py）；
• --dataset_name cnn_dailymail --dataset_config "3.0.0"：从 datasets Hub 加载 CNN/DailyMail 数据集及 3.0.0 版本配置；
• --source_prefix "summarize: "：T5 系模型必须使用的任务前缀；
• --output_dir：模型与日志输出目录；
• --overwrite_output_dir：允许覆盖已有输出目录（不传时若目录非空且未检测到 checkpoint，脚本会直接报错，见 run_summarization.py）；
• --predict_with_generate：评估与预测阶段使用model.generate做自回归解码（若省略，compute_metrics不会被挂载到 Trainer 上，见 run_summarization.py）。

4.2 T5 的 source_prefix 约定

只有 T5 系列模型（t5-small、t5-base、t5-large、t5-3b、t5-11b）必须附加--source_prefix "summarize: "参数。源码在加载模型后专门做了检查：若未提供source_prefix且模型为上述 T5 之一，会输出警告（见 run_summarization.py）。前缀会在预处理阶段拼接到每条源文本前：inputs = [prefix + inp for inp in inputs]（run_summarization.py）。

T5 模型在预训练阶段使用带任务前缀的格式，微调时保持一致的输入格式是取得良好效果的前提；而 BART/Pegasus 等模型不需要此前缀。

4.3 切换数据集：CNN/DailyMail 与 XSum

原 README 特别说明，XSum（Extreme Summarization）是另一个常用的摘要数据集。只需将数据集参数替换：

python benchmark/third_party/transformers/examples/pytorch/summarization/run_summarization.py \ --model_name_or_path t5-small \ --do_train \ --do_eval \ --dataset_name xsum \ --source_prefix "summarize: " \ --output_dir /tmp/tst-summarization \ --per_device_train_batch_size=4 \ --per_device_eval_batch_size=4 \ --overwrite_output_dir \ --predict_with_generate

之所以换数据集时无需手动指定文本/摘要列名，是因为脚本内置了summarization_name_mapping字典（run_summarization.py），自动映射各数据集对应的字段：

• cnn_dailymail→("article", "highlights")
• xsum→("document", "summary")
• samsum→("dialogue", "summary")
• big_patent→("description", "abstract")
• multi_news→("document", "summary")
• amazon_reviews_multi→("review_body", "review_title")
• 以及orange_sum、pn_summary、psc、thaisum、xglue、wiki_summary等

映射逻辑在 run_summarization.py：若用户未传--text_column/--summary_column，优先使用映射中的列名，否则退回数据集第一个/第二个字段。

4.4 使用自己的数据文件（CSV / JSONLINES）

原 README 明确指出摘要任务支持自定义 CSV 与 JSONLINES 两种格式。使用自备数据时，将--dataset_name替换为--train_file、--validation_file：

python benchmark/third_party/transformers/examples/pytorch/summarization/run_summarization.py \ --model_name_or_path t5-small \ --do_train \ --do_eval \ --train_file path_to_csv_or_jsonlines_file \ --validation_file path_to_csv_or_jsonlines_file \ --source_prefix "summarize: " \ --output_dir /tmp/tst-summarization \ --overwrite_output_dir \ --per_device_train_batch_size=4 \ --per_device_eval_batch_size=4 \ --predict_with_generate

CSV 文件

训练与验证文件应各含一列原文、一列摘要。若 CSV 只有两列（如下示例），第一列默认为text、第二列为summary：

text,summary "I'm sitting here in a boring room. It's just another rainy Sunday afternoon. I'm wasting my time I got nothing to do. I'm hanging around I'm waiting for you. But nothing ever happens. And I wonder","I'm sitting in a room where I'm waiting for something to happen" "I see trees so green, red roses too. I see them bloom for me and you. And I think to myself what a wonderful world. I see skies so blue and clouds so white. The bright blessed day, the dark sacred night. And I think to myself what a wonderful world.","I'm a gardener and I'm a big fan of flowers." "Christmas time is here. Happiness and cheer. Fun for all that children call. Their favorite time of the year. Snowflakes in the air. Carols everywhere. Olden times and ancient rhymes. Of love and dreams to share","It's that time of year again."

若 CSV 包含多列（如id,date,text,summary），需显式指定要使用的列：

--text_column text \ --summary_column summary \

JSONLINES 文件

第二种格式为每行一个 JSON 对象：

{"text": "I'm sitting here in a boring room. It's just another rainy Sunday afternoon. I'm wasting my time I got nothing to do. I'm hanging around I'm waiting for you. But nothing ever happens. And I wonder", "summary": "I'm sitting in a room where I'm waiting for something to happen"} {"text": "I see trees so green, red roses too. I see them bloom for me and you. And I think to myself what a wonderful world. I see skies so blue and clouds so white. The bright blessed day, the dark sacred night. And I think to myself what a wonderful world.", "summary": "I'm a gardener and I'm a big fan of flowers."} {"text": "Christmas time is here. Happiness and cheer. Fun for all that children call. Their favorite time of the year. Snowflakes in the air. Carols everywhere. Olden times and ancient rhymes. Of love and dreams to share", "summary": "It's that time of year again."}

与 CSV 相同：默认取第一个键为原文、第二个键为摘要（因此键名可以任意，示例用了text与summary），也可用--text_column text --summary_column summary显式指定。

文件格式的合法性在脚本参数校验阶段被强制检查：train_file与validation_file的扩展名必须是csv或json，否则断言失败（run_summarization.py）。加载时脚本依据扩展名调用load_dataset("csv"|"json", data_files=...)（run_summarization.py）。

4.5 预处理与数据整理源码解读

预处理函数preprocess_function（run_summarization.py）的核心逻辑：

1. 过滤掉原文或摘要为空的样本；
2. 在每条原文前拼接source_prefix；
3. 用tokenizer(inputs, max_length=max_source_length, padding=padding, truncation=True)对原文做截断/填充；
4. 用tokenizer(text_target=targets, ...)（即text_target关键字参数）独立对摘要做 tokenize；
5. 若采用定长填充（--pad_to_max_length）且ignore_pad_token_for_loss=True，将标签中的pad_token_id替换为-100，使 padding 部分不参与损失计算。

相关参数默认值（定义于 run_summarization.py 的DataTrainingArguments）：

模型侧参数（ModelArguments，见 run_summarization.py）：--config_name、--tokenizer_name、--cache_dir、--use_fast_tokenizer（默认 True）、--model_revision（默认 "main"）、--use_auth_token（默认 False，访问私有模型时配合huggingface-cli login使用）、--resize_position_embeddings（当max_source_length超过模型位置编码数时是否自动扩展，见 run_summarization.py）。

对 mBART 等多语言模型，脚本还会校验decoder_start_token_id：若缺失则按--lang从分词器映射设置，并要求--forced_bos_token指定首生成 token 为目标语言 token（run_summarization.py）。

4.6 数据收集器与 ROUGE 评估

数据整理阶段使用DataCollatorForSeq2Seq（run_summarization.py）：标签 padding 默认用-100（配合ignore_pad_token_for_loss），FP16 训练时按 8 的倍数对齐（pad_to_multiple_of=8）。

评估指标为 ROUGE，实现要点（run_summarization.py）：

1. 通过evaluate.load("rouge")加载指标；
2. postprocess_text用nltk.sent_tokenize将预测与参考按句子分行——rougeLSum 要求每句后带换行符，这是 ROUGE-L 变体计算的格式前提；
3. metric.compute(predictions=..., references=..., use_stemmer=True)计算 rouge1/rouge2/rougeL/rougeLsum，结果乘以 100 并保留 4 位小数；
4. 额外统计gen_len（生成序列平均长度）。

训练结束后，脚本会在--output_dir下保存模型与分词器，并生成generated_predictions.txt（--do_predict且--predict_with_generate时，见 run_summarization.py）；若不传--push_to_hub，则调用trainer.create_model_card()生成模型卡片（run_summarization.py）。

五、使用 Accelerate 微调（run_summarization_no_trainer.py）

5.1 与 Trainer 版本的区别

run_summarization_no_trainer.py同样支持上述全部架构与数据集，核心区别在于：它暴露了完整的裸训练循环，方便快速实验和任意定制（如直接修改优化器或 DataLoader 配置）。它牺牲了一部分Trainer的内置选项，但通过Accelerate库天然支持分布式训练、TPU 与混合精度。官方 README 建议先安装 Accelerate：

pip install accelerate

（对应本仓库 benchmark/third_party/README.md 中指定的accelerate==0.15.0版本。）

5.2 直接运行

python benchmark/third_party/transformers/examples/pytorch/summarization/run_summarization_no_trainer.py \ --model_name_or_path t5-small \ --dataset_name cnn_dailymail \ --dataset_config "3.0.0" \ --source_prefix "summarize: " \ --output_dir ~/tmp/tst-summarization

5.3 通过 accelerate 启动器运行

该脚本的优势在于支持多种运行环境，先交互式生成配置：

accelerate config

回答引导问题后，可用accelerate test验证环境是否就绪，然后启动训练：

accelerate launch benchmark/third_party/transformers/examples/pytorch/summarization/run_summarization_no_trainer.py \ --model_name_or_path t5-small \ --dataset_name cnn_dailymail \ --dataset_config "3.0.0" \ --source_prefix "summarize: " \ --output_dir ~/tmp/tst-summarization

同一条命令即可适配以下全部环境（原 README 明确列出）：

• 纯 CPU 环境；
• 单 GPU 环境；
• 多 GPU 分布式训练（单节点或多节点）；
• TPU 训练。

5.4 裸训练循环的实现要点

从源码看（run_summarization_no_trainer.py），该脚本的关键设计：

1. 参数解析：使用标准argparse（parse_args，见 run_summarization_no_trainer.py），与 Trainer 版本共享大部分数据参数（max_source_length=1024、max_target_length=128、text_column、summary_column、source_prefix等），训练参数默认值为per_device_train_batch_size=8、learning_rate=5e-5、num_train_epochs=3、gradient_accumulation_steps=1、lr_scheduler_type="linear"、num_warmup_steps=0；
2. Accelerator 初始化：Accelerator(gradient_accumulation_steps=...)统一管理设备与梯度累积（run_summarization_no_trainer.py）；
3. 优化器分组：将参数按是否需要权重衰减分成两组——bias、LayerNorm.weight、layer_norm.weight不衰减，其余参数应用--weight_decay，优化器为AdamW（run_summarization_no_trainer.py）；
4. 学习率调度：通过get_scheduler生成调度器，支持linear、cosine、cosine_with_restarts、polynomial、constant、constant_with_warmup六种类型，并按梯度累积步数换算 warmup 与总步数（run_summarization_no_trainer.py）；
5. 断点续训：--resume_from_checkpoint支持从step_{n}/epoch_{n}目录恢复；若未指定路径则自动选取最近目录（run_summarization_no_trainer.py）；
6. 评估：每个 epoch 结束后以model.generate(max_length=val_max_target_length, num_beams=...)生成摘要，经pad_across_processes、gather_for_metrics跨进程对齐后计算 ROUGE（run_summarization_no_trainer.py），最终结果写入output_dir/all_results.json，包含eval_rouge1/rouge2/rougeL/rougeLsum四项指标（run_summarization_no_trainer.py）；
7. 可选的实验追踪：--with_tracking配合--report_to（支持 tensorboard / wandb / comet_ml，默认 "all"）记录损失与指标。

5.5 加速参数速查

六、总结

围绕 Summarization 任务，本仓库中的两个脚本提供了两条互补的技术路线：

• run_summarization.py（Trainer 路线）：开箱即用、选项丰富，适合快速落地标准流程——加载数据（Hub 数据集或 CSV/JSONLINES）、预处理（前缀、截断、-100 标签屏蔽）、Seq2SeqTrainer训练、ROUGE 评估与模型卡片生成全部内置；
• run_summarization_no_trainer.py（Accelerate 路线）：训练循环完全透明，优化器分组、调度器、断点续训、多进程指标聚合均可在脚本内直接修改，配合accelerate config / test / launch一条命令打通 CPU、单卡、多卡、TPU 全场景。

两套脚本共享同一套数据约定（text/summary列映射、CSV/JSONLINES 格式、source_prefix规则）与评估逻辑（ROUGE +nltk.sent_tokenize分行、use_stemmer=True、结果放大 100 倍），读者可根据对训练过程控制粒度的需求任选其一，并参照本文的参数速查表完成定制。若需深入了解 Transformer 内部实现，可继续阅读本仓库中 tasks/summarization.mdx 等官方文档源文件。

• 推理引擎
• 大模型