企业官网建设流程全解析

Transformers 脚本化训练完整指南：从本地微调、分布式扩展到 Hub 模型共享

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers

本指南基于仓库内文档 run_scripts_fr.md 编写，系统讲解如何使用 🤗 Transformers 官方示例脚本（以 PyTorch 摘要生成任务为主线）完成从环境搭建、单机微调、分布式/混合精度训练、TPU 训练、Accelerate 无 Trainer 训练，到自定义数据集适配、断点续训与模型上传 Hub 的完整流程。读完本文，你将能够独立运行和改造仓库 examples/pytorch 下的任意任务脚本，并把训练产物一键发布到 Model Hub。

脚本全家桶：示例脚本的定位与目录结构

除了仓库内的 notebooks 教程外，🤗 Transformers 还提供了一套可直接运行的示例脚本，覆盖 PyTorch、TensorFlow 与 JAX/Flax 三个框架，用于演示在具体任务（文本分类、问答、摘要、语音识别、图像分类等）上如何微调模型。在本仓库快照中，PyTorch 脚本统一维护在 examples/pytorch 目录下，包含 summarization、translation、text-classification、question-answering、speech-recognition 等十余个任务子目录；此外还有社区维护的 research_projects 目录存放研究型脚本。

使用这些脚本前需要明确三点定位：

• 脚本不是开箱即用的万能工具：官方并不保证每个脚本能直接适配你遇到的所有问题，通常需要根据具体任务对脚本做适当修改；
• 预处理逻辑完全暴露：为了便于改造，绝大多数脚本将数据加载、清洗、分词等预处理流程以完整函数形式展示在脚本主体中（例如 run_summarization.py 中的preprocess_function），你可以直接按需修改；
• 社区遗留脚本需谨慎：examples/legacy等历史遗留脚本多由社区贡献、不再积极维护，通常依赖特定版本的 Transformers，很可能与最新版库不兼容，仅在研究参考时使用。

下文以摘要生成（Summarization）任务为贯穿全文的实战主线，PyTorch 与 TensorFlow 示例默认同时可用（本仓库快照仅包含 PyTorch 版本，TensorFlow/JAX 分支可在官方对应版本仓库中查看）。

环境配置：从源码安装最新版 Transformers

要确保示例脚本与库的 API 完全对齐，官方推荐从源码安装 Transformers 到全新的虚拟环境，而不是使用 PyPI 上的稳定发布版：

git clone https://gitcode.com/GitHub_Trending/tra/transformers cd transformers pip install .

这一要求在源码层面有直接印证：示例脚本头部都带有版本硬校验，例如 run_summarization.py 中的check_min_version("4.57.0.dev0")，只有开发版（dev0）才能通过检查；同时require_version("datasets>=1.8.0")会对依赖库做最小版本校验。

切换到旧版本示例

如果需要运行旧版示例（例如 v3.5.1 时代的脚本），可以先克隆仓库后切换到对应版本标签：

git checkout tags/v3.5.1

旧版示例脚本会绑定该标签下的库实现，切换后请务必在相同版本下运行，避免 API 不兼容。

安装示例专属依赖

进入目标示例目录后，安装该示例特有的依赖：

pip install -r requirements.txt

以摘要任务为例，examples/pytorch/summarization/requirements.txt 声明的依赖包括：datasets >= 1.8.0（数据集加载）、accelerate >= 0.12.0（Accelerate 训练）、sentencepiece（T5 等 SentencePiece 分词器所需，注意排除 0.1.92 版本）、rouge-score与evaluate（摘要评估指标）、nltk（摘要后处理分句）、py7zr（CNN/DailyMail 压缩数据集解压）以及torch >= 1.3。这些依赖与 run_summarization.py 头部声明的脚本运行依赖完全一致。

运行第一个微调脚本：T5-small + CNN/DailyMail 摘要

示例脚本会自动从 🤗 Datasets 库下载并预处理数据集，然后借助Trainer在支持摘要任务的模型架构上完成微调。下面用T5-small在CNN/DailyMail新闻数据集上做摘要微调：

python examples/pytorch/summarization/run_summarization.py \ --model_name_or_path google-t5/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 \ --predict_with_generate

核心参数逐项解读

source_prefix 为什么对 T5 是必需的

T5 在预训练时使用"任务前缀"来区分下游任务，因此微调摘要任务时必须加上"summarize: "前缀。源码中有两处直接印证：

1. 启动时的前置警告——run_summarization.py 会检测google-t5/t5-small、t5-base、t5-large、t5-3b、t5-11b等 T5 模型在未提供--source_prefix时给出 warning；
2. 预处理阶段——第 482 行 将prefix赋值为data_args.source_prefix（默认空字符串），第 555 行 在分词前执行inputs = [prefix + inp for inp in inputs]，把前缀拼接到每条源文本前。

数据列自动映射与预处理管线

脚本内置了常见摘要数据集的列名映射表summarization_name_mapping（见 run_summarization.py），例如cnn_dailymail对应("article", "highlights")，xsum对应("document", "summary")，samsum对应("dialogue", "summary")。未手动指定列名时，脚本会自动套用该映射取输入文本列与摘要列。

预处理流程为：加载原始数据集 →preprocess_function过滤空记录、拼接前缀、按max_source_length=1024截断分词输入、按max_target_length=128分词标签（标签中的 pad token 会被替换为-100以便在 loss 中忽略）→ 交给DataCollatorForSeq2Seq动态 batch 化 → 送入Seq2SeqTrainer。评估阶段使用evaluate库加载 ROUGE 指标，并用 NLTK 按句切分后计算（compute_metrics）。

分布式训练与混合精度

Trainer原生支持分布式训练与混合精度，示例脚本无需额外代码即可启用：

• 加--fp16开启 16 位混合精度训练；
• 用torchrun的--nproc_per_node指定使用的 GPU 数量。

torchrun \ --nproc_per_node 8 pytorch/summarization/run_summarization.py \ --fp16 \ --model_name_or_path google-t5/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 \ --predict_with_generate

从源码看，脚本在启动时会把training_args.fp16、n_gpu、parallel_mode等分布式状态打印到日志（run_summarization.py），且数据集下载、模型加载等环节均由库保证只在单个进程执行一次，避免多进程并发下载冲突。DataCollatorForSeq2Seq在fp16开启时会将 batch 长度对齐到 8 的倍数（pad_to_multiple_of=8），以适配混合精度对内存对齐的要求（第 620-625 行）。

注：官方文档说明 TensorFlow 脚本使用MirroredStrategy自动进行多 GPU 分布式训练，无需追加任何参数，检测到多卡即默认使用。本仓库快照中未包含examples/tensorflow目录，PyTorch 版本请以torchrun方式为准。

在 TPU 上运行脚本

张量处理单元（TPU）专为加速深度学习计算设计，PyTorch 通过 XLA 编译器支持 TPU。使用 TPU 时，通过 xla_spawn.py 启动脚本，并用--num_cores指定使用的 TPU 核心数（通常为 1 或 8）：

python xla_spawn.py --num_cores 8 \ summarization/run_summarization.py \ --model_name_or_path google-t5/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 \ --predict_with_generate

其底层原理可在源码中直接看到：xla_spawn.py 将目标脚本作为模块导入，用xmp.spawn(mod._mp_fn, args=(), nprocs=args.num_cores)在多个 TPU 核心上并行拉起进程；而 run_summarization.py 末尾定义的_mp_fn(index)正是为这个启动器准备的入口，二者通过约定好的_mp_fn函数名衔接。

使用 🤗 Accelerate 运行无 Trainer 脚本

🤗 Accelerate 是面向 PyTorch 的轻量库，提供统一的训练启动方式，可在 CPU 单机、单卡、多卡（单节点/多节点）与 TPU 等配置间无缝切换，同时完整保留对 PyTorch 训练循环的控制权。要运行 Accelerate 版脚本，需先安装（文档特别说明：由于 Accelerate 迭代迅速，必须安装 git 最新版）：

pip install git+https://github.com/huggingface/accelerate

与run_summarization.py对应，Accelerate 版本脚本是run_summarization_no_trainer.py（examples/pytorch/summarization/run_summarization_no_trainer.py）。识别规则很简单：凡 Accelerate 兼容脚本，其目录下必有task_no_trainer.py形式的文件。

三步启动流程：

# 1. 交互式创建并保存启动配置 accelerate config # 2. 校验配置是否正确 accelerate test # 3. 启动训练 accelerate launch run_summarization_no_trainer.py \ --model_name_or_path google-t5/t5-small \ --dataset_name cnn_dailymail \ --dataset_config "3.0.0" \ --source_prefix "summarize: " \ --output_dir ~/tmp/tst-summarization

accelerate launch同一命令即可适用于 CPU-only、单卡、多卡分布式（单/多节点）以及 TPU 四类环境，无需修改脚本。与 Trainer 版本相比，该脚本直接暴露裸训练循环（优化器、dataloader、学习率调度均可在脚本内直接修改），自定义自由度更高，但选项数量少于 Trainer 版（例如不支持 Trainer 内置的回调、指标日志体系）。从源码结构看，run_summarization_no_trainer.py 通过Accelerator与accelerate.utils.set_seed完成设备抽象与随机种子管理，并同样内置了数据集列名映射与 ROUGE 评估逻辑。

使用自定义数据集：CSV 与 JSON Lines

摘要脚本支持 CSV 与 JSON Lines（每行一个 JSON 对象）两种自定义数据格式。使用自己的数据时需指定以下参数：

• --train_file、--validation_file：训练集与验证集文件路径；
• --text_column：输入文本（待摘要原文）所在列名；
• --summary_column：目标摘要所在列名。

完整命令示例：

python examples/pytorch/summarization/run_summarization.py \ --model_name_or_path google-t5/t5-small \ --do_train \ --do_eval \ --train_file path_to_csv_or_jsonlines_file \ --validation_file path_to_csv_or_jsonlines_file \ --text_column text_column_name \ --summary_column summary_column_name \ --source_prefix "summarize: " \ --output_dir /tmp/tst-summarization \ --per_device_train_batch_size=4 \ --per_device_eval_batch_size=4 \ --predict_with_generate

CSV 格式约定

若 CSV 只有两列（如text,summary），脚本默认第一列为输入文本、第二列为摘要，无需额外指定列名。若文件列数较多，则必须用--text_column/--summary_column显式指定。例如列结构为id,date,text,summary时，追加参数：

--text_column text \ --summary_column summary

JSON Lines 格式约定

JSONL 文件每行是一个 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.", "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.", "summary": "I'm a gardener and I'm a big fan of flowers."}

同样地，默认取第一个键值为文本、第二个键值为摘要；键名任意，只要通过--text_column/--summary_column显式指定即可。

源码层的格式校验

脚本在解析参数阶段就做了严格约束：DataTrainingArguments.post_init要求必须提供数据集名或至少一个数据文件，否则直接抛出ValueError；且train_file、validation_file、test_file的扩展名必须是csv或json。若显式指定的--text_column/--summary_column不在数据集列名中，脚本同样会报错并列出可选列名（第 519-534 行）。此外还支持--test_file测试文件、--lang（mBART 等多语言 tokenizer 必需）、--forced_bos_token（强制首个生成 token 为目标语言）等进阶参数。

小样本试跑：提交全量训练前的快速验证

在投入可能需要数小时的全量数据集训练前，强烈建议先用少量样本验证脚本可用性。脚本提供三个截断参数：

• --max_train_samples：截断训练样本数；
• --max_eval_samples：截断评估样本数；
• --max_predict_samples：截断预测样本数。

python examples/pytorch/summarization/run_summarization.py \ --model_name_or_path google-t5/t5-small \ --max_train_samples 50 \ --max_eval_samples 50 \ --max_predict_samples 50 \ --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 \ --predict_with_generate

源码实现中，这三个参数通过train_dataset.select(range(max_train_samples))（第 573-575 行）等方式对数据集做切片，仅取前 N 条样本参与对应阶段。

注意：并非所有示例脚本都支持--max_predict_samples。如果不确定，加上-h查看脚本支持的全部参数：

examples/pytorch/summarization/run_summarization.py -h

从 checkpoint 恢复训练

训练意外中断时，可以从上一次保存的 checkpoint 无缝续训，无需从头开始：

python examples/pytorch/summarization/run_summarization.py \ --model_name_or_path google-t5/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 \ --resume_from_checkpoint path_to_specific_checkpoint \ --predict_with_generate

其中--resume_from_checkpoint指向具体的 checkpoint 目录。源码层面，脚本将该参数直接透传给trainer.train(resume_from_checkpoint=checkpoint)（run_summarization.py），Trainer 会恢复模型权重、优化器状态、学习率调度器进度与训练步数，确保续训与中断前的状态完全衔接。

将微调模型发布到 Model Hub

所有示例脚本都支持把最终模型一键上传到 Model Hub。开始前先登录 Hugging Face 账号：

hf auth login

登录后，给脚本加上--push_to_hub参数即可触发上传。该参数会自动以"你的用户名 +output_dir目录名"创建并发布仓库。若想自定义仓库名，使用--push_to_hub_model_id：

python examples/pytorch/summarization/run_summarization.py \ --model_name_or_path google-t5/t5-small \ --do_train \ --do_eval \ --dataset_name cnn_dailymail \ --dataset_config "3.0.0" \ --source_prefix "summarize: " \ --push_to_hub \ --push_to_hub_model_id finetuned-t5-cnn_dailymail \ --output_dir /tmp/tst-summarization \ --per_device_train_batch_size=4 \ --per_device_eval_batch_size=4 \ --predict_with_generate

从源码看，脚本在训练结束后会根据training_args.push_to_hub分支执行trainer.push_to_hub(**kwargs)，或仅生成本地模型卡片trainer.create_model_card(**kwargs)（run_summarization.py）。上传时自动附带的元数据（finetuned_from、tasks、dataset_tags、language等）也由这一段统一组装，确保 Hub 上的模型卡片信息完整、可复现。

小结

围绕"脚本化训练"这一主题，本文完整覆盖了从 环境搭建（源码安装 + 示例依赖）到模型发布（push_to_hub）的整条链路，并将每个命令行参数都对应到 run_summarization.py 与 run_summarization_no_trainer.py 的具体实现，便于你在改造脚本时快速定位代码位置。摘要任务只是示例，examples/pytorch 下其他任务脚本（文本分类、翻译、问答、语音识别等）遵循完全相同的参数体系与运行方式，掌握本文的通用方法论后即可举一反三。

【免费下载链接】transformers🤗 Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers