🤗 Transformers 快速上手指南：用 pipeline 与 AutoClass 完成文本、语音、图像任务

本文基于 docs/source/it/quicktour.md 整理，面向希望在最短时间内上手 🤗 Transformers 的开发者。文章以官方 Quick Tour 为骨架，结合当前仓库 src/transformers 的源码实现，系统讲解如何使用 pipeline 完成零配置推理、如何用 AutoClass 加载预训练模型与分词器、如何处理批量输入与数据集迭代，以及如何保存和重新加载模型。读完本文，你将能够独立完成从「一行代码做情感分析」到「自定义模型 + 分词器接入 pipeline」再到「保存/复用微调模型」的完整闭环。

什么是 pipeline：最快使用预训练模型的方式

pipeline 是 🤗 Transformers 中最简单、最直接的预训练模型使用入口：你只需要传入一个任务名称，它就会自动完成模型与预处理组件的加载、输入预处理、模型推理和结果后处理。从源码看，一条 pipeline 由三部分组成（见 src/transformers/pipelines/init.py 的 docstring）：

• 预处理组件：tokenizer（文本）、image processor（图像）、feature extractor（音频/图像）、processor（多模态）；
• 模型：负责从输入生成预测；
• 后处理步骤：将原始输出整理成人类可读的结果。

在 Pipeline 基类中，这三个阶段被实现为 preprocess → forward → postprocess 三个方法，由 __call__ 统一编排（见 src/transformers/pipelines/base.py）。

pipeline 支持的任务一览

原文档按模态列举了 pipeline 支持的常见任务。结合仓库中 SUPPORTED_TASKS 注册表（见 src/transformers/pipelines/init.py），可以整理出更完整的任务清单：

文本（Text）

任务	说明	仓库注册的默认模型
sentiment-analysis（即 text-classification 的别名）	情感分析：判断文本情感极性	distilbert/distilbert-base-uncased-finetuned-sst-2-english
text-generation	文本生成	HuggingFaceTB/SmolLM3-3B
ner（即 token-classification 的别名）	命名实体识别：标注每个词的实体类别（人名、日期、地点等）	dbmdz/bert-large-cased-finetuned-conll03-english
question-answering	问答：从给定上下文与问题中抽取答案	—
fill-mask	掩码填充：补全被遮蔽的词语	distilbert/distilroberta-base
summarization	摘要生成	—
translation	翻译	—
feature-extraction	特征抽取：生成表示文本的张量	distilbert/distilbert-base-cased
zero-shot-classification	零样本分类	facebook/bart-large-mnli
table-question-answering	表格问答	google/tapas-base-finetuned-wtq

图像（Images）

任务	说明	仓库注册的默认模型
image-classification	图像分类	google/vit-base-patch16-224
image-segmentation	图像分割：对每个像素分类	facebook/detr-resnet-50-panoptic
object-detection	目标检测	facebook/detr-resnet-50
image-text-to-text	图像到文本（如视觉问答、图像描述）	Qwen/Qwen3-VL-2B-Instruct
mask-generation	掩码生成（SAM 类模型）	facebook/sam-vit-huge
depth-estimation	深度估计	Intel/dpt-large

音频（Audio）

任务	说明	仓库注册的默认模型
audio-classification	音频分类	superb/wav2vec2-base-superb-ks
automatic-speech-recognition（ASR）	语音识别：将音频转写为文本	facebook/wav2vec2-base-960h
text-to-audio（别名 text-to-speech）	文本转语音	suno/bark-small

此外注册表还包含 video-classification、any-to-any 等任务。表中「默认模型」一列来自当前仓库源码，当你只传任务名、不传模型时，pipeline 就会自动使用这些默认模型。

使用 pipeline 完成情感分析

以下示例来自原文档，演示用 pipeline 做情感分析。首先安装依赖（PyTorch）：

pip install torch

然后导入 pipeline 并指定任务与模型：

>>> from transformers import pipeline

>>> classificatore = pipeline("sentiment-analysis", model="MilaNLProc/feel-it-italian-sentiment")

pipeline 会自动下载并缓存指定的预训练模型与分词器。如果省略 model 参数，它会回退到该任务在 SUPPORTED_TASKS 中注册的默认模型。接下来直接用分类器处理目标文本：

>>> classificatore("Siamo molto felici di mostrarti la libreria 🤗 Transformers.")
[{'label': 'positive', 'score': 0.9997}]

输入多句文本时，只需传入一个字符串列表，pipeline 会返回一个字典列表：

>>> risultati = classificatore(
...     ["Siamo molto felici di mostrarti la libreria 🤗 Transformers.", "Speriamo te non la odierai."]
... )
>>> for risultato in risultati:
...     print(f"etichetta: {risultato['label']}, con punteggio: {round(risultato['score'], 4)}")
etichetta: positive, con punteggio: 0.9998
etichetta: negative, con punteggio: 0.9998

从源码角度看，__call__ 会先判断输入类型（列表、Dataset、生成器或聊天消息），再通过 get_iterator 以批处理方式逐个执行 preprocess → forward → postprocess（见 src/transformers/pipelines/base.py），因此列表输入会被「急切地」消费并一次性返回全部结果。

在整个数据集上迭代：语音识别实战

pipeline 也可以直接遍历整个数据集。先安装 🤗 Datasets 库：

pip install datasets

创建一个 ASR pipeline，指定意大利语语音识别模型：

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

>>> riconoscitore_vocale = pipeline(
...     "automatic-speech-recognition", model="radiogroup-crits/wav2vec2-xls-r-1b-italian-doc4lm-5gram"
... )

然后加载数据集（例如 MInDS-14 的意大利语子集）：

>>> from datasets import load_dataset, Audio

>>> dataset = load_dataset("PolyAI/minds14", name="it-IT", split="train")  # doctest: +IGNORE_RESULT

关键一步：必须保证数据集的采样率与模型训练时的采样率一致。通过 feature_extractor.sampling_rate 获取模型的期望采样率并转换数据集的音频列：

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

此时音频文件会在访问 audio 列时被自动加载并重采样。取出前 4 条样本的原始波形向量，作为列表传给 pipeline：

>>> risultato = riconoscitore_vocale(dataset[:4]["audio"])
>>> print([d["text"] for d in risultato])
['dovrei caricare dei soldi sul mio conto corrente', 'buongiorno e senza vorrei depositare denaro sul mio conto corrente come devo fare per cortesia', 'sì salve vorrei depositare del denaro sul mio conto', 'e buon pomeriggio vorrei depositare dei soldi sul mio conto bancario volleo sapere come posso fare se e posso farlo online ed un altro conto o andandoo tramite bancomut']

实践提示：当数据集很大、且输入本身占据较大内存（如语音、音频或图像）时，不要用列表一次性加载全部输入，而应传入一个生成器（generator），让 pipeline 惰性地逐个消费输入，避免内存溢出。这一点在 __call__ 的源码中也有体现：Dataset 和生成器输入会返回一个按需消费的迭代器，而不是物化整个结果列表（见 src/transformers/pipelines/base.py）。

在 pipeline 中更换模型与分词器

pipeline 可以容纳 Model Hub 上的任意模型，只需显式指定模型名即可适配新的使用场景。例如，要处理法语文本的情感分析，可以在 Hub 上按标签筛选，得到微调过的多语言 BERT 情感模型：

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

使用 AutoModelForSequenceClassification 和 AutoTokenizer 加载预训练模型及其配套分词器：

>>> 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-tuning），可参考 训练教程；微调完成后，强烈建议将模型分享到 Model Hub 供社区使用，具体做法见 模型共享教程。

pipeline 的常用参数速查

结合 pipeline() 工厂函数的签名，常用的关键参数如下：

参数	类型	说明
task	str	任务名，决定返回哪个 pipeline 类（可参考上文任务表）
model	str / PreTrainedModel	模型标识符或模型实例；缺省时使用任务默认模型
config	str / PreTrainedConfig	配置标识符或配置对象；缺省时使用模型自带配置
tokenizer / feature_extractor / image_processor / processor	str 或对应组件实例	显式指定预处理组件；缺省时按 model → config → task 的顺序自动加载
device	int / str / torch.device	指定推理设备（如 0 或 "cuda:0"）
device_map	str / dict	分布式/多卡设备映射（如 "auto"）
dtype	str / torch.dtype	推理精度，默认 "auto"
revision	str	模型版本，可以是分支名、标签或 commit id，默认 "main"
use_fast	bool	是否优先使用 fast tokenizer，默认 True
token	str / bool	Hub 访问令牌（私有模型需要）
trust_remote_code	bool	是否信任并执行 Hub 上的自定义代码，默认 False
batch_size	int	批大小（在调用时传入）

AutoClass：pipeline 背后的自动架构分发

从内部机制看，AutoModelForSequenceClassification 与 AutoTokenizer 正是 pipeline 能力的来源。AutoClass 是一个「捷径」：它只凭模型名或路径，就能自动推断出正确的模型架构类并完成实例化。你只需为任务选择正确的 AutoClass，再用 AutoTokenizer 加载配套分词器即可。

以 nlptown/bert-base-multilingual-uncased-sentiment 为例，下面演示如何用 AutoClass 手工复现 pipeline 的完整流程。

AutoTokenizer：文本 → 模型可读的输入

分词器（tokenizer）负责把文本处理成模型能理解的格式。它先把文本切成更小的单元——token（可能是词、子词或字符，具体规则取决于分词算法）；随后把 token 映射为数字（即模型的词表 vocabulary），构造出张量输入。

加载分词器（务必与模型同名，确保使用与预训练时一致的切分规则）：

>>> from transformers import AutoTokenizer

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

把文本传给分词器：

>>> encoding = tokenizer("Siamo molto felici di mostrarti la libreria 🤗 Transformers.")
>>> print(encoding)
{'input_ids': [101, 56821, 10132, 14407, 13019, 13007, 10120, 47201, 10330, 10106, 91686, 100, 58263, 119, 102],
'token_type_ids': [0, 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, 1]}

返回的字典包含两个核心字段：

• input_ids：token 的数值化表示（术语解释见 glossary）；
• attention_mask：指示模型应该关注哪些 token（忽略 padding 部分）。

与 pipeline 一样，分词器也支持列表输入；此外还可以通过 padding、truncation 把一批长度不一的文本整理成统一长度的 batch：

>>> pt_batch = tokenizer(
...     ["Siamo molto felici di mostrarti la libreria 🤗 Transformers.", "Speriamo te non la odierai."],
...     padding=True,
...     truncation=True,
...     max_length=512,
...     return_tensors="pt",
... )

其中 return_tensors="pt" 表示返回 PyTorch 张量（若用 TensorFlow 后端则传 "tf"）。关于分词与预处理的更多细节，可阅读 tokenizer 总结。

AutoModel：加载正确的任务模型

🤗 Transformers 提供统一的预训练模型加载方式：加载 AutoModel 与加载 AutoTokenizer 的写法完全一致，唯一区别是要为当前任务选择正确的 AutoModel 变体。由于这里做的是文本（序列）分类，应使用 AutoModelForSequenceClassification：

>>> from transformers import AutoModelForSequenceClassification

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

每个任务对应哪种 AutoModel 类，可参考 任务指南 等按任务组织的文档（例如序列分类、token 分类、问答等页面会给出对应的 AutoClass）。

现在把预处理好的 batch 直接传给模型，只需用 ** 解包字典：

>>> 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.0041, 0.0037, 0.0203, 0.2005, 0.7713],
        [0.3766, 0.3292, 0.1832, 0.0558, 0.0552]], grad_fn=<SoftmaxBackward0>)

重要约定：🤗 Transformers 的所有模型（PyTorch 与 TensorFlow 皆然）都返回施加最终激活函数（如 softmax）之前的原始张量，因为最终激活函数通常与损失函数合并计算。所以概率归一化需要你自行完成。

模型本身是标准的 torch.nn.Module 或 tf.keras.Model，可以直接嵌入你自己的训练循环。为了让训练更省心，PyTorch 用户还可以使用 Trainer 类，它内置了分布式训练、混合精度等能力；TensorFlow 用户则可以直接调用 Keras 的 fit 方法。完整说明见 训练教程。

关于模型输出：🤗 Transformers 的模型输出是特殊的 dataclass，属性可以在 IDE 中自动补全；同时它们也表现得像元组或字典（可以用整数、切片或字符串索引），且值为 None 的属性会被自动忽略。

保存模型并在框架间转换

微调完成后，用 PreTrainedModel.save_pretrained 连同分词器一起保存：

>>> pt_save_directory = "./pt_save_pretrained"
>>> tokenizer.save_pretrained(pt_save_directory)  # doctest: +IGNORE_RESULT
>>> pt_model.save_pretrained(pt_save_directory)

再次使用时，用 PreTrainedModel.from_pretrained 从本地目录重新加载：

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

🤗 Transformers 一个很有特色的能力是：同一个模型可以保存一次，随后在 PyTorch 与 TensorFlow 之间互相转换。通过 from_pt 或 from_tf 参数，可以把权重从一种框架迁移到另一种：

>>> from transformers import AutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(pt_save_directory)
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(pt_save_directory, from_pt=True)

从源码看，from_pretrained 在加载权重时会根据 from_tf/from_flax 等标志位选择对应的权重转换路径（见 src/transformers/modeling_utils.py 附近对相关参数的过滤与处理逻辑）。

延伸阅读

• pipeline 与任务详解：pipeline 的完整 API 与各任务的详细说明；
• AutoClass 文档：所有 Auto 类的完整参考；
• tokenizer 总结：分词算法的原理与分类；
• 训练教程：从零微调预训练模型；
• 模型共享教程：把模型发布到 Hub 的完整流程；
• 术语表：input_ids、attention_mask 等核心概念的权威解释。