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

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(datasets1.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.0Accelerate 训练、sentencepieceT5 等 SentencePiece 分词器所需注意排除 0.1.92 版本、rouge-score与evaluate摘要评估指标、nltk摘要后处理分句、py7zrCNN/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_size4 \ --per_device_eval_batch_size4 \ --predict_with_generate核心参数逐项解读参数作用说明--model_name_or_path预训练模型标识或本地路径对应 ModelArguments 中的model_name_or_path支持 Hub 模型名或本地 checkpoint 目录--do_train/--do_eval开关训练 / 评估阶段对应Seq2SeqTrainingArguments标准选项缺省则对应阶段不执行--dataset_nameHub 数据集名称通过load_dataset(dataset_name, dataset_config_name)下载--dataset_config数据集配置名CNN/DailyMail 使用3.0.0版本配置换成 Extreme Summarization 数据集则直接用--dataset_name xsum--source_prefix输入前统一添加的任务提示前缀T5 系列模型必需见下方原理说明--output_dir输出目录存放模型权重、tokenizer、训练日志与评估结果--per_device_train_batch_size/--per_device_eval_batch_size单卡 batch size训练与评估可分别设置默认均为 8--predict_with_generate评估/预测时使用generate解码开启后才会计算 ROUGE 指标否则评估只算 losssource_prefix 为什么对 T5 是必需的T5 在预训练时使用任务前缀来区分下游任务因此微调摘要任务时必须加上summarize: 前缀。源码中有两处直接印证启动时的前置警告——run_summarization.py 会检测google-t5/t5-small、t5-base、t5-large、t5-3b、t5-11b等 T5 模型在未提供--source_prefix时给出 warning预处理阶段——第 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_length1024截断分词输入、按max_target_length128分词标签标签中的 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_size4 \ --per_device_eval_batch_size4 \ --predict_with_generate从源码看脚本在启动时会把training_args.fp16、n_gpu、parallel_mode等分布式状态打印到日志run_summarization.py且数据集下载、模型加载等环节均由库保证只在单个进程执行一次避免多进程并发下载冲突。DataCollatorForSeq2Seq在fp16开启时会将 batch 长度对齐到 8 的倍数pad_to_multiple_of8以适配混合精度对内存对齐的要求第 620-625 行。注官方文档说明 TensorFlow 脚本使用MirroredStrategy自动进行多 GPU 分布式训练无需追加任何参数检测到多卡即默认使用。本仓库快照中未包含examples/tensorflow目录PyTorch 版本请以torchrun方式为准。在 TPU 上运行脚本张量处理单元TPU专为加速深度学习计算设计PyTorch 通过 XLA 编译器支持 TPU。使用 TPU 时通过 xla_spawn.py 启动脚本并用--num_cores指定使用的 TPU 核心数通常为 1 或 8python 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_size4 \ --per_device_eval_batch_size4 \ --predict_with_generate其底层原理可在源码中直接看到xla_spawn.py 将目标脚本作为模块导入用xmp.spawn(mod._mp_fn, args(), nprocsargs.num_cores)在多个 TPU 核心上并行拉起进程而 run_summarization.py 末尾定义的_mp_fn(index)正是为这个启动器准备的入口二者通过约定好的_mp_fn函数名衔接。使用 Accelerate 运行无 Trainer 脚本 Accelerate 是面向 PyTorch 的轻量库提供统一的训练启动方式可在 CPU 单机、单卡、多卡单节点/多节点与 TPU 等配置间无缝切换同时完整保留对 PyTorch 训练循环的控制权。要运行 Accelerate 版脚本需先安装文档特别说明由于 Accelerate 迭代迅速必须安装 git 最新版pip install githttps://github.com/huggingface/accelerate与run_summarization.py对应Accelerate 版本脚本是run_summarization_no_trainer.pyexamples/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-summarizationaccelerate 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_size4 \ --per_device_eval_batch_size4 \ --predict_with_generateCSV 格式约定若 CSV 只有两列如text,summary脚本默认第一列为输入文本、第二列为摘要无需额外指定列名。若文件列数较多则必须用--text_column/--summary_column显式指定。例如列结构为id,date,text,summary时追加参数--text_column text \ --summary_column summaryJSON Lines 格式约定JSONL 文件每行是一个 JSON 对象例如{text: Im sitting here in a boring room. Its just another rainy Sunday afternoon. Im wasting my time I got nothing to do., summary: Im sitting in a room where Im waiting for something to happen} {text: I see trees so green, red roses too. I see them bloom for me and you., summary: Im a gardener and Im 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测试文件、--langmBART 等多语言 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_size4 \ --per_device_eval_batch_size4 \ --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_size4 \ --per_device_eval_batch_size4 \ --resume_from_checkpoint path_to_specific_checkpoint \ --predict_with_generate其中--resume_from_checkpoint指向具体的 checkpoint 目录。源码层面脚本将该参数直接透传给trainer.train(resume_from_checkpointcheckpoint)run_summarization.pyTrainer 会恢复模型权重、优化器状态、学习率调度器进度与训练步数确保续训与中断前的状态完全衔接。将微调模型发布到 Model Hub所有示例脚本都支持把最终模型一键上传到 Model Hub。开始前先登录 Hugging Face 账号hf auth login登录后给脚本加上--push_to_hub参数即可触发上传。该参数会自动以你的用户名 output_dir目录名创建并发布仓库。若想自定义仓库名使用--push_to_hub_model_idpython 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_size4 \ --per_device_eval_batch_size4 \ --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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考