Transformers 快速上手：pipeline 与 AutoClass 完成首次推理的完整路径

本篇基于 Hugging Face Transformers 仓库的德语快速上手文档（docs/source/de/quicktour.md）并结合源码实现展开：你将掌握如何用一行 pipeline() 调用完成文本、图像、音频等常见任务的推理，如何替换底层模型与 Tokenizer 适配多语言场景，如何直接用 AutoTokenizer/AutoModel 复现 pipeline 的完整计算链路，以及如何通过自定义 AutoConfig 构建随机初始化的新模型结构。读完后，你既能照抄出可运行的推理代码，也能理解这些高级 API 背后的加载与调用机制。

1. 两大核心入口：pipeline 与 AutoClass

Transformers 的设计目标是"开箱即用"：你不需要手写数据预处理与模型加载代码，仓库提供两条互补的路径：

• pipeline()：最高层的工厂函数，输入任务名（或模型名）即可返回一个封装了"预处理 → 推理 → 后处理"全流程的可调用对象，适合快速验证与生产部署；
• AutoClass 家族（AutoConfig、AutoModel*、AutoTokenizer 等）：根据模型名/路径自动解析出对应的架构类并加载预训练权重，是 pipeline 底层的实际工作方式，也适合需要细粒度控制的场景。

文档提示：官方文档中的代码示例均提供 PyTorch 与 TensorFlow 切换器，未标注时意味着代码在两个后端下无需修改即可运行。从源码结构看，两条路径最终汇合于同一套 from_pretrained 加载逻辑与统一的模型输出数据类，这是"换框架、换任务只需换类名"体验的来源。

2. Pipeline 支持的任务清单

pipeline 的 docstring（src/transformers/pipelines/init.py#L710-L735）列出了当前版本的全部任务字符串。快速上手文档按模态组织如下：

文本任务：

• 情感分析（sentiment-analysis，text-classification 的别名）：判断文本极性；
• 文本生成：基于给定输入续写文本；
• 命名实体识别 NER：为每个词标注实体类型（人名、地名、日期等）；
• 问答：给定上下文与问题，抽取答案；
• Fill-mask：补全被掩码词的句子；
• 摘要：为长文本生成摘要；
• 翻译：跨语言翻译；
• 特征提取：输出文本的张量表征。

图像任务：图像分类、图像分割（逐像素）、目标检测。

音频任务：音频分类、自动语音识别 ASR。

源码中还注册了更多任务别名与任务，如 text-to-audio（别名 text-to-speech）、token-classification（别名 ner）、zero-shot-classification、document-question-answering 等（见 src/transformers/pipelines/init.py#L323-L359 的 check_task 文档）。完整的任务—模型映射可参考德语文档 Pipeline 教程。

3. 实战一：三行代码完成情感分析

先安装依赖（若尚未安装）：

pip install torch

然后指定任务创建 pipeline：

>>> from transformers import pipeline

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

这一步会自动下载并缓存该任务的默认预训练模型（DistilBERT 在 SST-2 情感数据集上微调的版本）及其 Tokenizer。随后可直接对目标文本推理：

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

批量输入：传入句子列表，返回字典列表：

>>> 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

3.1 结合数据集做语音识别

pipeline 还可以遍历整个数据集。以 ASR 为例，先安装 🤗 Datasets：

pip install datasets

创建指定模型的语音识别 pipeline：

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

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

加载 MInDS-14 数据集（en-US 训练集）：

>>> 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 列时文件会自动下载并重采样。取前 4 条的波形数组传入 pipeline：

>>> 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', ...]

内存优化建议：对大量输入（语音、图像等）应传入生成器（generator）而非一次性构造列表，避免所有输入同时驻留内存——pipeline 内部会按 batch_size 迭代消费输入。

4. 替换 pipeline 内部的模型与 Tokenizer

pipeline 可以挂载 Model Hub 上的任意模型，因此适配新语言或新领域只需换模型标识符。以法语文本的情感分析为例，选择多语言 BERT 模型 nlptown/bert-base-multilingual-uncased-sentiment：

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

用 AutoClass 加载预训练模型与配套 Tokenizer（AutoClass 的原理见下文第 5 节）：

>>> 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}]

从源码看，pipeline() 的完整签名支持 model、config、tokenizer、feature_extractor、image_processor、processor、revision、device、device_map、dtype、trust_remote_code、model_kwargs 等参数（src/transformers/pipelines/init.py#L671-L690）。其加载优先级值得记住：若未提供 tokenizer，先尝试用 model 加载默认 Tokenizer；再退回 config 的默认 Tokenizer；最后退回该任务的默认 Tokenizer（见 src/transformers/pipelines/init.py#L749-L756）。这意味着只要模型与 Tokenizer 来自同一 Hub 仓库，二者天然对齐；若显式传入，则需自行保证一致性。

如果找不到合适的现成模型，就需要在自有数据上微调——参见仓库中的 微调教程，微调后建议按 模型分享指南 发布到 Hub。

5. AutoClass 原理：pipeline 的底层工作方式

AutoClass 是"自动路由"缩写：它读取模型仓库中的 config.json，根据 architectures/model_type 字段解析出具体架构类（如 BertForSequenceClassification），再走统一的 from_pretrained 加载流程。你只需为任务选对 AutoModel* 变体并配套 AutoTokenizer 即可。

5.1 AutoTokenizer：文本到张量的两步转换

Tokenizer 负责把文本转换为模型可消费的数字序列，分两步：

1. 切分：把文本拆成词元（token），拆词规则（按整词还是子词）由该模型训练时的分词方案决定——因此必须用与模型相同的名称实例化 Tokenizer，否则 token 序列与词表错位；
2. 映射：把 token 映射为模型词表中的编号。

>>> 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 的数值编号；
• attention_mask：标记哪些位置参与注意力（真实 token 为 1，填充为 0）；
• token_type_ids：区分同一条输入中的不同句子段（Bert 系模型特有）。

与 pipeline 类似，Tokenizer 也接受列表输入，并可通过 padding=True、truncation=True、max_length 把变长句子整理为等长批次，用 return_tensors 直接产出张量：

>>> 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",
... )

更完整的分词、填充与截断策略参见 预处理教程。

5.2 AutoModel：从 logits 到概率

AutoModel 家族与 AutoTokenizer 的加载方式完全一致，差别仅在于为任务选择正确的 AutoModel* 类。序列分类任务对应 AutoModelForSequenceClassification（src/transformers/models/auto/modeling_auto.py#L2250）：

>>> from transformers import AutoModelForSequenceClassification

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

把第 5.1 节的批次直接喂给模型（** 展开字典为关键字参数）：

>>> pt_outputs = pt_model(**pt_batch)

模型输出的是未经最终激活函数处理的 logits。手动做 Softmax 即可还原 pipeline 给出的概率：

>>> 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>)

两条值得写进笔记的实现约定：

• 为什么输出 logits 而非概率：最终激活函数常与损失函数融合（如 CrossEntropyLoss 内部自带 Softmax+Log），输出原始 logits 便于训练时数值稳定；
• 输出是特殊数据类：ModelOutput 同时支持属性访问（IDE 可自动补全）、按整数/切片/字符串索引，且索引时自动忽略值为 None 的字段。

模型本体就是标准的 torch.nn.Module 或 tf.keras.Model，可自由嵌入你的训练循环。若不想手写循环，PyTorch 侧可用仓库自带的 Trainer 类（支持分布式训练、混合精度等，实现在 src/transformers/trainer.py），TensorFlow 侧可用 Keras 的 fit 方法，细节见 训练教程。AutoClass 的更多用法（任务—类映射表）可参考 AutoClass 教程。

6. 保存模型与跨框架转换

微调完成后，用 save_pretrained 把模型与 Tokenizer 存到同一目录：

>>> 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")

Transformers 还保存了框架无关的权重，因此可以把模型存成一个框架、加载成另一个框架。以 PyTorch 保存的目录为例，from_pt=True / from_tf=True 参数会触发跨框架转换：

>>> from transformers import AutoModel

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

适用前提：from_pt/from_tf 用于已保存权重目录或 Hub 仓库，即"存 A 框架 → 以 B 框架加载"的桥接；它不负责内存中两个模型对象之间的实时互转。

7. 自定义模型结构：用 AutoConfig 从零搭建

不加载预训练权重时，可以改配置类来改变模型架构。PreTrainedConfig 描述了隐藏层数、注意力头数等结构超参；用自定义配置初始化模型时权重从零开始随机初始化，必须先训练才能得到有意义的结果。

用 AutoConfig.from_pretrained 加载已有配置并覆盖字段（例如把 DistilBERT 的注意力头数改为 12）：

>>> from transformers import AutoConfig

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

再用 AutoModel.from_config 按配置构建模型（AutoConfig 负责把 config.json 路由到具体配置类，from_config 则跳过权重加载、仅按超参建图）：

>>> from transformers import AutoModel

>>> my_model = AutoModel.from_config(my_config)

编写全新的自定义架构（而不只是改超参）请参见仓库中的"创建自定义模型"指南。

8. 从源码看 pipeline 的调用链

把前文拼起来，一次 classifier("...") 调用的实际执行路径（src/transformers/pipelines/base.py）为：

1. pipeline() 工厂：check_task 校验任务名并解析别名（sentiment-analysis → text-classification），按优先级加载 config → model → tokenizer，然后实例化具体 *Pipeline 子类；
2. 用户调用时进入 Pipeline.__call__（base.py#L388）：支持批量迭代，内部经预处理把原始输入转成 input_ids/attention_mask 等张量字典；
3. _forward（base.py#L1155）把张量字典喂给底层 nn.Module；
4. 后处理阶段把 logits 转成人类可读结果（如 {'label', 'score'} 字典），这正是你无需手写 Softmax 与标签映射的原因。

各任务的后处理逻辑分别实现在 src/transformers/pipelines/ 下的模块中，例如情感分析对应的 TextClassificationPipeline 在 text_classification.py。

9. 下一步

完成本篇后，建议按以下顺序深入仓库文档（均为相对仓库根目录路径）：

• Pipeline 教程：全部任务的详细用法与输出结构；
• AutoClass 教程：任务—模型类完整映射表；
• 预处理教程：分词、填充、截断的细节；
• 训练教程：用 Trainer 微调模型；
• 模型分享指南：把成果发布到 Model Hub。

核心结论回顾：pipeline() 负责"快"，AutoClass 负责"可控"，两者共享同一套 from_pretrained 加载机制与输出约定；理解了第 5 节的 Tokenizer→模型→Softmax 链路，你就拥有了在任意任务上替换模型、调试输出和落地部署的完整能力。