企业官网建设流程全解析

Transformers 快速上手全解：Pipeline 推理、AutoClass 加载与 Trainer 微调实战

【免费下载链接】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

本文基于 Hugging Face Transformers 官方文档 Quick Tour（快速导览） 展开，完整覆盖从环境安装、pipeline一键推理、AutoClass 加载预训练模型、自定义模型构建，到使用Trainer与 TensorFlow 完成训练的全流程。读完后，你将掌握在 Transformers 中做快速推理、替换模型/分词器、保存与跨框架转换模型，以及搭建完整微调训练循环的具体操作方法，并能对照仓库源码理解每个 API 背后的实现位置。

环境准备

开始之前，先确认依赖库已安装。官方导览给出的安装命令为：

pip install transformers datasets evaluate accelerate

此外，还需要安装你使用的机器学习框架，例如 PyTorch：

pip install torch

其中datasets用于加载数据集（后文的语音识别与训练示例都会用到），accelerate是pipeline中device_map分布式加载以及Trainer多卡/混合精度训练所依赖的库。

Pipeline：最简洁的预训练模型推理入口

pipeline()是使用预训练模型做推理最简单、最快的方式。它把「前处理组件（tokenizer / image_processor / feature_extractor / processor）+ 模型 + 后处理」封装成一个可直接调用的对象，覆盖文本、图像、音频与多模态等多种模态。

仓库中该工厂函数的实现位于 pipeline 入口，其函数签名为：

pipeline( task: str | None = None, model: str | PreTrainedModel | None = None, config=None, tokenizer=None, feature_extractor=None, image_processor=None, video_processor=None, processor=None, revision=None, use_fast: bool = True, token=None, device=None, device_map=None, dtype: str | torch.dtype | None = "auto", trust_remote_code=None, model_kwargs=None, pipeline_class=None, **kwargs, ) -> Pipeline

几个关键参数值得注意（依据 源码 docstring）：

• task：决定返回哪个 pipeline 实现类；未提供前处理组件时，pipeline会自动按model→config→task的优先级加载默认组件；
• use_fast：默认True，尽量使用 Rust 加速的 Fast tokenizer；
• device/device_map：控制模型放置的设备，两者不能同时使用；device_map="auto"可借助 accelerate 自动切分大模型；
• dtype：默认"auto"，按模型保存时的精度加载；
• trust_remote_code：是否允许执行 Hub 上仓库携带的自定义代码，仅建议在已审查过代码时开启。

支持的任务与默认模型

官方文档列出了常见任务及其流水线标识符：

从源码结构看，任务到实现的映射集中在 SUPPORTED_TASKS 这张注册表中，每个任务包含三部分：impl（pipeline 类）、pt（可加载该任务的 Auto 类）、default（默认模型及版本 commit）。例如：

• text-classification的默认模型是distilbert/distilbert-base-uncased-finetuned-sst-2-english；
• automatic-speech-recognition的默认模型是facebook/wav2vec2-base-960h；
• image-classification的默认模型是google/vit-base-patch16-224。

也就是说，当你只写pipeline("sentiment-analysis")而不指定模型时，框架会按上表自动下载对应的默认模型与 tokenizer 并缓存到本地。此外，TASK_ALIASES 注册了三个任务别名：sentiment-analysis→text-classification、ner→token-classification、text-to-speech→text-to-audio，这就是文档示例中可以直接使用"sentiment-analysis"这个任务名的原因。

示例一：情感分析

创建 pipeline 实例并指定任务：

>>> from transformers import pipeline >>> classifier = pipeline("sentiment-analysis")

随后即可对目标文本调用：

>>> classifier("I love showing you the 🤗 Transformers library.") [{'label': 'POSITIVE', 'score': 0.9998}]

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

>>> results = classifier(["We love showing you the 🤗 Transformers library.", "I don't want to dislike it."]) >>> for result in results: ... print(f"label: {result['label']}, score: {round(result['score'], 4)}") label: POSITIVE, score: 0.9998 label: NEGATIVE, score: 0.5309

示例二：在数据集上批量跑自动语音识别

pipeline也可以对一整个数据集做迭代处理。以自动语音识别为例：

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

加载音频数据集（例如 PolyAI/minds14）：

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

注意确保数据集的采样率与模型训练时的采样率一致，用cast_column转换音频列：

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

性能提示：在大型数据集上，如果输入体积较大（如音频、图像），建议不要把所有输入一次性读进内存，而是向 pipeline 传入生成器（generator）而非列表，让数据按块流动处理。

在 pipeline 中指定其他模型与 tokenizer

pipeline可以容纳 Hub 上的任意模型，很容易把它适配到其他使用场景。例如需要处理非英语文本时，可以用多语言 BERT 情感分类模型：

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

用AutoModelForSequenceClassification和AutoTokenizer加载模型及对应 tokenizer（下一节详述 AutoClass）：

>>> from transformers import AutoTokenizer, AutoModelForSequenceClassification >>> model = AutoModelForSequenceClassification.from_pretrained(model_name) >>> tokenizer = AutoTokenizer.from_pretrained(model_name)

然后把指定组件传入pipeline（对应工厂函数签名中的model与tokenizer参数），即可处理另一种语言的文本：

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

如果在 Hub 上找不到适合你使用场景的模型，就需要用自己的数据对预训练模型做微调，微调方法参见官方微调教程（docs/source/en/training.md）；微调完成后，也可以把模型推送到社区共享。

AutoClass：按名称自动加载模型与分词器

AutoModelForSequenceClassification与AutoTokenizer就是驱动上述pipeline的两个协作组件。AutoClass 是一组快捷方式：给定模型名称或路径，自动读取其架构对应的configuration.json/tokenizer_config.json并实例化正确的类。你只需选择合适的 AutoClass 及其配套前处理类，无需关心具体实现类名。

AutoTokenizer

Tokenizer 负责把文本前处理成模型可消费的数值数组，涉及词如何切分、切到哪一级等规则。最关键的一点：必须用与模型相同的模型名实例化 tokenizer，即沿用它预训练时的分词规则，否则输入分布会错位。

AutoTokenizer的实现位于 AutoTokenizer 类。加载方式：

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

把文本传给 tokenizer：

>>> encoding = tokenizer("I love showing 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：区分同一段输入中不同来源 token 的类型（Bert 类模型区分 segment A/B，全为 0 表示同一 segment）；
• attention_mask：标记哪些位置需要被注意力机制关注（真实 token 为 1，填充位为 0）。

Tokenizer 还支持接受输入列表，并通过 padding 与截断得到长度一致的批量数据：

>>> pt_batch = tokenizer( ... ["We love showing you the 🤗 Transformers library.", "I hope you don't dislike it."], ... padding=True, ... truncation=True, ... max_length=512, ... return_tensors="pt", ... )

return_tensors="pt"会把各字段转换为 PyTorch 张量；文本、图像、音频与多模态输入的前处理细节分别由AutoImageProcessor、AutoFeatureExtractor、AutoProcessor覆盖，参见官方 preprocessing 教程（docs/source/en/preprocessing.md）。

AutoModel

Transformers 提供了统一加载预训练实例的方式，AutoModel的加载方式和AutoTokenizer完全一致，区别只在于要按任务选择合适的 Auto 类。做文本（序列）分类时，需要加载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属性上输出最终激活前的结果，对其应用 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 中所有模型（PyTorch 或 TensorFlow）输出的都是最终激活函数（如 softmax）之前的张量，因为最终激活常常与损失函数合并计算。模型输出是一个特殊的数据类（Data class），其属性在 IDE 中可自动补全，且像元组或字典一样可用整数、切片或字符串索引访问，其中为None的属性会被忽略。

保存模型

微调完成后，可以用PreTrainedModel.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 的一个亮点能力是：模型可以保存后再以另一种框架重新加载，通过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)

自定义模型构建

如果只是想改改模型结构，可以修改模型的配置类（configuration）。配置类指定模型属性，例如隐藏层数量、注意力头数量等。从自定义配置初始化模型时相当于从零开始：权重随机初始化，需要自行训练才能得到有意义结果。

先导入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)

如果需要完整的新架构（而非仅改属性），官方提供了「创建自定义模型」指南（docs/source/en/create_a_model.md）进一步说明自定义配置的写法。

Trainer：面向 PyTorch 的优化训练循环

由于所有模型都是标准的torch.nn.Module，你可以把它们放进任意常规训练循环中手动训练。但 Transformers 提供了Trainer类，在基础训练循环之上额外提供分布式训练、混合精度、检查点管理、日志与评估等能力。

按照任务不同，通常向Trainer传入以下组件（以情感分类微调为例）：

1. 加载模型（PreTrainedModel或任意torch.nn.Module）：

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

2. 定义训练超参数：TrainingArguments汇集所有可调训练参数（学习率、批大小、epoch 数等），未指定项使用默认值。该类定义于 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. 加载前处理类（tokenizer、image processor、feature extractor 或 processor 之一）：

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

4. 加载数据集：

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

5. 编写 tokenize 函数并批量映射到整个数据集：

>>> def tokenize_dataset(dataset): ... return tokenizer(dataset["text"]) >>> dataset = dataset.map(tokenize_dataset, batched=True)

6. 创建动态填充的数据整理器DataCollatorWithPadding（定义于 data_collator.py），它会在运行时把同一 batch 内长度不同的样本 padding 到统一长度，避免离线预 padding 造成的显存浪费：

>>> 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"], ... processing_class=tokenizer, ... data_collator=data_collator, ... )

调用trainer.train()即开始训练：

>>> trainer.train()

两个扩展点需要区分：

• 子类化Trainer：通过覆写其内部方法可以自定义损失函数、优化器、学习率调度器等训练行为，属于对训练逻辑本身的修改；
• Callbacks（回调）：用于与外部库集成、监控训练过程、报告进度或提前停止训练；回调不修改训练循环本身，若要改损失函数等，仍须子类化Trainer。

另外，翻译、摘要等序列到序列任务应改用Seq2SeqTrainer与Seq2SeqTrainingArguments。

使用 TensorFlow 训练

所有模型同时也是标准的tf.keras.Model，因此可以直接使用 Keras API 训练。Transformers 提供TFPreTrainedModel.prepare_tf_dataset方法，把 🤗 Datasets 数据集便捷地转成tf.data.Dataset，之后直接调用 Keras 的compile与fit即可。

1. 加载 TF 版模型：

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

2. 加载 tokenizer：

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

3. 编写 tokenize 函数：

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

4. 用Dataset.map应用 tokenizer，再交给prepare_tf_dataset，可同时设置批大小与 shuffle：

>>> dataset = dataset.map(tokenize_dataset) >>> tf_dataset = model.prepare_tf_dataset( ... dataset["train"], batch_size=16, shuffle=True, tokenizer=tokenizer ... )

5.compile与fit：由于每个 Transformers 模型都自带与默认任务对应的损失函数，compile时无需显式指定 loss：

>>> from tensorflow.keras.optimizers import Adam >>> model.compile(optimizer=Adam(3e-5)) # 无需损失函数参数！ >>> model.fit(tf_dataset)

小结与下一步

本文按照官方 Quick Tour 的脉络完成了 Transformers 的核心使用闭环：

1. 推理：pipeline(task, model, tokenizer)三行代码完成从下载到预测，任务注册表与默认模型见 SUPPORTED_TASKS；
2. 组件化：AutoClass 系列（AutoTokenizer/AutoModel*/AutoConfig/TFAutoModel*）按名称统一加载各类组件，并支持save_pretrained/from_pretrained与from_pt/from_tf的框架间转换；
3. 训练：PyTorch 侧用TrainingArguments+ 数据map+DataCollatorWithPadding+Trainer搭建完整微调循环，TensorFlow 侧用prepare_tf_dataset+ Kerascompile/fit。

掌握以上内容后，可以继续深入：创建完全自定义模型、针对特定任务微调、编写训练脚本，以及阅读 Transformers 核心概念文档来理解模型输出数据类、attention mask 等细节。

【免费下载链接】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