Transformers 快速入门：从 pipeline 推理、AutoClass 加载到 Trainer 微调的完整技术路线

本文以 Transformers 官方文档的"快速入门"为主线，带你完整走通该库的四大核心能力：用 pipeline 一行代码完成推理、用 AutoClass 加载预训练模型与分词器并手动前向、用 Trainer/TrainingArguments 快速微调，以及用 AutoConfig 从零构建自定义模型。读完后，你将掌握一个预训练模型从"下载—调用—替换—保存—训练"的完整生命周期，并理解每一步背后的源码实现位置（如任务注册表 src/transformers/pipelines/init.py 与管道基类 src/transformers/pipelines/base.py）。

环境准备

开始之前，确保安装所有必要的库：

pip install transformers datasets evaluate accelerate

同时安装你偏好的机器学习框架（下文实操以 PyTorch 为主）：

pip install torch

一、pipeline：使用预训练模型推理的最快路径

pipeline 是使用预训练模型进行推理的最简单方式。它把"加载模型、预处理输入、执行推理、后处理输出"封装成一条链式调用，开箱即用地支持众多任务。文档中列出的常用任务及对应的任务标识符如下（按模态分组）：

任务	描述	模态	任务标识符
文本分类	为给定文本序列分配标签	NLP	pipeline(task="sentiment-analysis")
文本生成	基于给定提示词生成文本	NLP	pipeline(task="text-generation")
摘要生成	为文本序列或文档生成摘要	NLP	pipeline(task="summarization")
图像分类	为给定图像分配标签	计算机视觉	pipeline(task="image-classification")
图像分割	为图像中每个像素分配标签（支持语义分割、全景分割、实例分割）	计算机视觉	pipeline(task="image-segmentation")
目标检测	预测图像中物体的边界框和类别	计算机视觉	pipeline(task="object-detection")
音频分类	为给定音频数据分配标签	音频	pipeline(task="audio-classification")
自动语音识别	将语音转写为文本	音频	pipeline(task="automatic-speech-recognition")
视觉问答	给定图像和问题，回答关于图像的问题	多模态	pipeline(task="vqa")
文档问答	给定文档图像和问题，回答关于文档的问题	多模态	pipeline(task="document-question-answering")
图像描述	为给定图像生成文字描述	多模态	pipeline(task="image-to-text")

完整任务清单可在源码的任务注册表中查看：src/transformers/pipelines/init.py 中的 SUPPORTED_TASKS 字典定义了每个任务对应的管道实现类（impl）、支持的 AutoModel 家族（pt）、默认模型及版本（default）与模态类型（type）。

情感分析：第一个 pipeline

以文本情感分析为例，创建一个 pipeline 实例并指定任务：

>>> from transformers import pipeline

>>> classifier = pipeline("sentiment-analysis")

pipeline("sentilment-analysis") 会自动下载并缓存一个默认的预训练模型及对应的分词器，然后直接对目标文本推理：

>>> classifier("We are very happy to show you the 🤗 Transformers library.")
[{'label': 'POSITIVE', 'score': 0.9998}]

这个"默认模型"并非魔法，而是硬编码在源码中的。从源码看，"sentiment-analysis" 实际上是 "text-classification" 的别名，而该任务的默认模型正是 SST-2 上微调过的 DistilBERT，与文档描述完全一致：

# src/transformers/pipelines/__init__.py
TASK_ALIASES = {
    "sentiment-analysis": "text-classification",
    "ner": "token-classification",
    "text-to-speech": "text-to-audio",
}
SUPPORTED_TASKS = {
    ...
    "text-classification": {
        "impl": TextClassificationPipeline,
        "pt": (AutoModelForSequenceClassification,) if is_torch_available() else (),
        "default": {"model": ("distilbert/distilbert-base-uncased-finetuned-sst-2-english", "714eb0f")},
        "type": "text",
    },
    ...
}

（见 src/transformers/pipelines/init.py）

此外，TextClassificationPipeline 的输出分数并非简单的原始 logits：当模型有多个标签时执行 softmax，只有一个标签时执行 sigmoid，回归任务则不做任何变换——这段逻辑定义在 src/transformers/pipelines/text_classification.py 的 sigmoid/softmax 函数与 ClassificationFunction 枚举中，这解释了为什么示例输出里的 score 是 0~1 之间的概率值。

批量输入

如果有多个输入，以列表形式传入 pipeline，返回一个字典列表：

>>> results = classifier(["We are very happy to show you the 🤗 Transformers library.", "We hope you don't hate it."])
>>> for result in results:
...     print(f"label: {result['label']}, with score: {round(result['score'], 4)}")
label: POSITIVE, with score: 0.9998
label: NEGATIVE, with score: 0.5309

遍历完整数据集：自动语音识别示例

pipeline 还可以遍历任意完整数据集。这里以自动语音识别（ASR）为例：

>>> import torch
>>> from transformers import pipeline

>>> speech_recognizer = pipeline("automatic-speech-recognition", model="facebook/wav2vec2-base-960h")

加载一个语音数据集，例如 MInDS-14：

>>> from datasets import load_dataset, Audio

>>> dataset = load_dataset("PolyAI/minds14", name="en-US", split="train")

必须确保数据集的音频采样率与 facebook/wav2vec2-base-960h 训练时使用的采样率一致：

>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=speech_recognizer.feature_extractor.sampling_rate))

调用 "audio" 列时会自动加载并裁剪音频文件。从样本中提取原始波形并作为列表传入管道：

>>> result = speech_recognizer(dataset[:4]["audio"])
>>> print([d["text"] for d in result])
['I WOULD LIKE TO SET UP A JOINT ACCOUNT WITH MY PARTNER HOW DO I PROCEED WITH DOING THAT', "FONDERING HOW I'D SET UP A JOIN TO HELL T WITH MY WIFE AND WHERE THE AP MIGHT BE", "I I'D LIKE TOY SET UP A JOINT ACCOUNT WITH MY PARTNER I'M NOT SEEING THE OPTION TO DO IT ON THE APSO I CALLED IN TO GET SOME HELP CAN I JUST DO IT OVER THE PHONE WITH YOU AND GIVE YOU THE INFORMATION OR SHOULD I DO IT IN THE AP AN I'M MISSING SOMETHING UQUETTE HAD PREFERRED TO JUST DO IT OVER THE PHONE OF POSSIBLE THINGS", 'HOW DO I FURN A JOINA COUT']

内存提示：对于包含大型输入（如音频或图像）的大数据集，建议传入生成器（generator）而不是列表，避免把所有输入一次性加载到内存中。该机制在管道基类中通过 _infer_data_format 等工具函数对输入格式做了自动推断，见 src/transformers/pipelines/base.py。

在 pipeline 中使用其他模型和分词器

pipeline 可以接收任意模型库（Hub）中的模型，便于适配其他场景。例如需要一个能处理法语的模型时，可以选用多语言 BERT 情感模型：

>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"

用 AutoModelForSequenceClassification 与 AutoTokenizer 分别加载预训练模型及其配套分词器（AutoClass 机制见下节）：

>>> from transformers import AutoTokenizer, AutoModelForSequenceClassification

>>> model = AutoModelForSequenceClassification.from_pretrained(model_name)
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)

在 pipeline 中显式指定模型和分词器，即可对法语文本推理：

>>> classifier = pipeline("sentiment-analysis", model=model, tokenizer=tokenizer)
>>> classifier("Nous sommes très heureux de vous présenter la bibliothèque 🤗 Transformers.")
[{'label': '5 stars', 'score': 0.7273}]

如果找不到适合任务的现成模型，就需要在自己的数据上微调（fine-tune）一个预训练模型——可继续阅读本文"Trainer"章节，或参考仓库中的微调示例脚本，如 examples/pytorch/text-classification。微调完成后，建议将模型与社区共享。

二、AutoClass：自动获取模型与处理器的统一入口

在后台，AutoModelForSequenceClassification 与 AutoTokenizer 协同工作，支撑起上面 pipeline() 的调用。AutoClass 是一组"自动化工厂"类，能够根据模型名称或本地路径自动解析出正确的模型架构并实例化。你只需为任务选择正确的 AutoModel 子类，以及配套的处理类（分词器 / 图像处理器 / 特征提取器 / 处理器）。

所有 Auto 类的映射逻辑集中在 src/transformers/models/auto 目录：modeling_auto.py（各任务模型映射）、tokenization_auto.py（分词器映射）、image_processing_auto.py、feature_extraction_auto.py、processing_auto.py 等。

AutoTokenizer

分词器负责把文本转换为模型可处理的数字矩阵（token id）。分词规则（如何切分词、在哪个粒度切分）因模型而异，最重要的原则是：必须用与模型同名（同配置）的分词器实例化，这样才能复现模型训练时所用的分词规则。

>>> from transformers import AutoTokenizer

>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)

把文本传给分词器：

>>> encoding = tokenizer("We are very happy to show you the 🤗 Transformers library.")
>>> print(encoding)
{'input_ids': [101, 11312, 10320, 12495, 19308, 10114, 11391, 10855, 10103, 100, 58263, 13299, 119, 102],
 'token_type_ids': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
 'attention_mask': [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]}

返回的字典包含：

• input_ids：token 的数值表示；
• token_type_ids：区分输入中不同序列段的类型（如 BERT 的 A/B 句）；
• attention_mask：标记哪些 token 需要被"注意"（填充位为 0）。

分词器还能接收输入列表，并对文本做"填充"（padding）与"截断"（truncation），返回统一长度的批次：

>>> pt_batch = tokenizer(
...     ["We are very happy to show you the 🤗 Transformers library.", "We hope you don't hate it."],
...     padding=True,
...     truncation=True,
...     max_length=512,
...     return_tensors="pt",
... )

对于图像、音频与多模态输入，对应使用 AutoImageProcessor、AutoFeatureExtractor 和 AutoProcessor（源码分别位于 src/transformers/image_processing_base.py、src/transformers/feature_extraction_utils.py、src/transformers/processing_utils.py）。

AutoModel 与手动前向推理

Transformers 提供统一的方式加载预训练模型，加载方式与 AutoTokenizer 一致，唯一区别是选择与任务匹配的 AutoModel 子类。序列分类任务使用 AutoModelForSequenceClassification：

>>> from transformers import AutoModelForSequenceClassification

>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(model_name)

把上一步预处理的批次直接传入模型，只需在字典前加 ** 解包：

>>> pt_outputs = pt_model(**pt_batch)

模型在 logits 属性中输出最终线性层激活值。对 logits 应用 softmax 即得到概率：

>>> from torch import nn

>>> pt_predictions = nn.functional.softmax(pt_outputs.logits, dim=-1)
>>> print(pt_predictions)
tensor([[0.0021, 0.0018, 0.0115, 0.2121, 0.7725],
        [0.2084, 0.1826, 0.1969, 0.1755, 0.2365]], grad_fn=<SoftmaxBackward0>)

设计说明：所有 Transformers 模型返回的都是"最终激活函数（如 softmax）之前"的矩阵，因为最终激活函数通常与损失函数合并计算。模型输出是专门的数据类（ModelOutput，定义于 src/transformers/modeling_outputs.py），其属性在 IDE 中自动补全；输出对象既像元组又像字典，支持整数索引、切片或字符串索引，且等于 None 的属性会被自动忽略。

三、保存与重新加载模型

模型训练（微调）完成后，可以用 save_pretrained 连同分词器一起保存：

>>> pt_save_directory = "./pt_save_pretrained"
>>> tokenizer.save_pretrained(pt_save_directory)
>>> pt_model.save_pretrained(pt_save_directory)

需要再次使用时，用 from_pretrained 从本地目录加载：

>>> pt_model = AutoModelForSequenceClassification.from_pretrained("./pt_save_pretrained")

文档还描述了在 PyTorch 与 TensorFlow 之间转换加载的能力（通过 from_pt / from_tf 参数）。这里需要注意当前仓库的版本背景：从 MIGRATION_GUIDE_V5.md 的"Removal of TensorFlow and Jax"一节可见，本仓库所处的 v5 开发版本正在移除 TensorFlow 与 JAX 后端、聚焦 PyTorch，在当前代码库中已检索不到 TFAutoModelForSequenceClassification 等 TF 类。因此该能力仅适用于仍保留 TF 后端的历史版本，在当前检出中请以 PyTorch 路径为准。

从源码看，保存/加载链路的关键实现包括：

• 模型权重序列化：PreTrainedModel.save_pretrained（src/transformers/modeling_utils.py）；
• 配置与分词器各自的 save_pretrained（src/transformers/configuration_utils.py、src/transformers/tokenization_utils_base.py）；
• 连管道本身也可整体保存：Pipeline.save_pretrained（src/transformers/pipelines/base.py）。

四、构建自定义模型

你可以通过修改模型配置类来改变模型的构建方式。配置（config）决定了模型的结构超参数，如隐藏层数、注意力头数等。从自定义配置类初始化模型时是"从零开始"：参数随机初始化，必须先训练才能产生有意义的结果。

先导入 AutoConfig，加载想要修改的预训练模型配置，并在 AutoConfig.from_pretrained 中直接覆盖想改的属性（例如注意力头数）：

>>> from transformers import AutoConfig

>>> my_config = AutoConfig.from_pretrained("distilbert/distilbert-base-uncased", n_heads=12)

再用 AutoModel.from_config 从自定义配置创建模型：

>>> from transformers import AutoModel

>>> my_model = AutoModel.from_config(my_config)

AutoModel.from_config 是 Auto 工厂体系的一部分，其通用实现在 src/transformers/models/auto/auto_factory.py 的 from_config 类方法中：它根据配置中的 model_type 查找对应的建模类，再以该配置完成初始化。

五、Trainer：增强版 PyTorch 训练循环

所有 Transformers 模型都是标准的 torch.nn.Module，因此可以直接放进任何常规训练循环。不过，库提供了 Trainer 类（src/transformers/trainer.py），它内置了标准训练循环，并在此基础上扩展了分布式训练、混合精度、深度速度、断点续训等能力。

按照任务，你通常向 Trainer 传递以下组件（以在 rotten_tomatoes 上微调序列分类模型为例）：

1. 模型：PreTrainedModel 或任意 torch.nn.Module 实例：

   >>> from transformers import AutoModelForSequenceClassification
   
   >>> model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased")
   

2. 训练参数：TrainingArguments 包含学习率、批大小、训练轮数等超参数，未显式指定的项使用默认值：

   >>> from transformers import TrainingArguments
   
   >>> training_args = TrainingArguments(
   ...     output_dir="path/to/save/folder/",
   ...     learning_rate=2e-5,
   ...     per_device_train_batch_size=8,
   ...     per_device_eval_batch_size=8,
   ...     num_train_epochs=2,
   ... )
   

3. 处理器：加载分词器（或图像处理器、特征提取器、处理器）：

   >>> from transformers import AutoTokenizer
   
   >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased")
   

4. 数据集：

   >>> from datasets import load_dataset
   
   >>> dataset = load_dataset("rotten_tomatoes")
   

5. 分词函数：

   >>> def tokenize_dataset(dataset):
   ...     return tokenizer(dataset["text"])
   

   然后用 Dataset.map 应用到整个数据集：

   >>> dataset = dataset.map(tokenize_dataset, batched=True)
   

6. 数据整理器：DataCollatorWithPadding 负责把数据集里的样本动态填充、组成批次（实现位于 src/transformers/data/data_collator.py）：

   >>> from transformers import DataCollatorWithPadding
   
   >>> data_collator = DataCollatorWithPadding(tokenizer=tokenizer)
   

把这些组件装配进 Trainer：

>>> from transformers import Trainer

>>> trainer = Trainer(
...     model=model,
...     args=training_args,
...     train_dataset=dataset["train"],
...     eval_dataset=dataset["test"],
...     tokenizer=tokenizer,
...     data_collator=data_collator,
... )

准备好之后，调用 trainer.train() 开始训练：

>>> trainer.train()

两种扩展训练循环的方式：

1. 继承 Trainer：通过覆写其方法来自定义损失函数、优化器、学习率调度器等核心行为；
2. 使用回调（Callbacks）：TrainerCallback 及其子类（src/transformers/trainer_callback.py）允许你与外部库集成、监控训练进度、报告指标或提前停止训练——但回调不修改训练循环本身；要改损失函数这类核心逻辑，仍须继承 Trainer。

对于翻译、摘要等序列到序列（seq2seq）任务，请改用 Seq2SeqTrainer 与 Seq2SeqTrainingArguments。

六、TensorFlow 训练路径（历史说明）

原始文档还介绍了 TensorFlow 侧的训练流程：所有模型曾是标准的 tf.keras.Model，可通过 Keras API 训练，并用 TFPreTrainedModel.prepare_tf_dataset 把数据集直接转换为 tf.data.Dataset，示例步骤为——

>>> from transformers import TFAutoModelForSequenceClassification

>>> model = TFAutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased")
>>> tf_dataset = model.prepare_tf_dataset(dataset["train"], batch_size=16, shuffle=True, tokenizer=tokenizer)
>>> model.compile(optimizer='adam')  # 无需损失函数参数：模型自带与任务相关的默认损失
>>> model.fit(tf_dataset)

适用前提说明：如第三节所述，当前仓库（v5 开发版本）已按计划移除 TensorFlow 后端（见 MIGRATION_GUIDE_V5.md），上述 TFAuto* 类与 prepare_tf_dataset 在当前代码库中不存在，本节内容仅作为该文档发布时版本的流程参考。当前版本的训练路径请统一使用第五节的 PyTorch Trainer 方案。

后续学习路线

完成本快速入门后，建议沿着仓库内以下资源深入：

• 微调指南：在指定数据上微调预训练模型（本文 Trainer 章节的完整展开），可参考 examples/pytorch 下各任务（text-classification、text-generation、summarization、question-answering 等）的完整训练脚本；
• 自定义架构：用 modular-transformers 机制创建自己的模型，参考 examples/modular-transformers 目录下的示例与文档说明；
• 核心概念：分词器、预处理、任务体系等概念文档，见 docs/source 目录。

注：本文内容以 docs/source/ar/quicktour.md（官方文档"快速入门"的阿拉伯语版）为主体骨架整理而成，所有源码级结论均基于当前仓库实际代码核实；其中 TensorFlow 相关章节已按当前仓库状态标注了适用性边界。