Transformers 文档

快速浏览

快速浏览

开始使用 🤗 Transformers 吧!无论你是开发者还是普通用户,这个快速入门指南将帮助你开始,并展示如何使用 pipeline() 进行推理,使用 AutoClass 加载预训练模型和预处理器,以及使用 PyTorch 或 TensorFlow 快速训练模型。如果你是初学者,我们建议接下来查看我们的教程或 课程,以获取对这里介绍的概念的更深入解释。

在开始之前,请确保您已安装所有必要的库:

!pip install transformers datasets evaluate accelerate

您还需要安装您首选的机器学习框架:

Pytorch
Hide Pytorch content
pip install torch
TensorFlow
Hide TensorFlow content
pip install tensorflow

管道

pipeline() 是使用预训练模型进行推理的最简单和最快的方法。您可以直接使用 pipeline() 来处理跨不同模态的许多任务,其中一些任务如下表所示:

有关可用任务的完整列表,请查看pipeline API参考

任务 描述 模式 管道标识符
文本分类 为给定的文本序列分配一个标签 NLP pipeline(task=“sentiment-analysis”)
文本生成 根据提示生成文本 NLP pipeline(task=“text-generation”)
摘要生成 生成一段文本或文档的摘要 自然语言处理 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”)

首先创建一个 pipeline() 的实例,并指定你想要使用的任务。在本指南中,你将使用 pipeline() 进行情感分析作为示例:

>>> from transformers import pipeline

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

pipeline() 下载并缓存了一个默认的 预训练模型 和用于情感分析的分词器。现在你可以在你的目标文本上使用 classifier

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

如果你有多个输入,将你的输入作为列表传递给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() 也可以根据您的需求迭代整个数据集。在这个例子中,我们选择自动语音识别作为我们的任务:

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

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

加载一个音频数据集(更多详情请参阅🤗 Datasets 快速入门),您希望对其进行迭代。例如,加载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"列时会自动加载并重新采样。 从前4个样本中提取原始波形数组,并将其作为列表传递给管道:

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

对于输入数据较大的数据集(如语音或视觉),您应该传递一个生成器而不是列表,以避免将所有输入加载到内存中。请查看pipeline API参考以获取更多信息。

在管道中使用另一个模型和分词器

pipeline() 可以容纳来自 Hub 的任何模型,使得为其他用例调整 pipeline() 变得容易。例如,如果您需要一个能够处理法语文本的模型,可以使用 Hub 上的标签来筛选合适的模型。筛选结果中的顶部返回了一个多语言的 BERT 模型,该模型经过微调用于情感分析,您可以将其用于法语文本:

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

使用 AutoModelForSequenceClassificationAutoTokenizer 来加载预训练模型及其相关的分词器(更多关于 AutoClass 的内容将在下一节中介绍):

>>> from transformers import AutoTokenizer, AutoModelForSequenceClassification

>>> model = AutoModelForSequenceClassification.from_pretrained(model_name)
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)
TensorFlow
Hide TensorFlow content

使用 TFAutoModelForSequenceClassificationAutoTokenizer 来加载预训练模型及其相关的分词器(更多关于 TFAutoClass 的内容将在下一节中介绍):

>>> from transformers import AutoTokenizer, TFAutoModelForSequenceClassification

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

pipeline()中指定模型和分词器,现在你可以将classifier应用于法文文本:

>>> 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上分享模型,让机器学习对每个人来说都更加民主化!🤗

AutoClass

在底层,AutoModelForSequenceClassificationAutoTokenizer 类共同工作,驱动了你上面使用的 pipeline()AutoClass 是一个快捷方式,可以自动从其名称或路径中检索预训练模型的架构。你只需要为你的任务选择适当的 AutoClass 及其相关的预处理类。

让我们回到上一节的例子,看看如何使用AutoClass来复制pipeline()的结果。

AutoTokenizer

分词器负责将文本预处理为数字数组,作为模型的输入。分词过程受多种规则控制,包括如何拆分单词以及单词应在什么级别拆分(了解更多关于分词的信息,请参阅分词器摘要)。最重要的是要记住,您需要使用相同的模型名称实例化分词器,以确保您使用的分词规则与模型预训练时使用的规则一致。

使用AutoTokenizer加载一个分词器:

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

分词器返回一个包含以下内容的字典:

分词器还可以接受输入列表,并对文本进行填充和截断,以返回具有统一长度的批次:

Pytorch
Hide Pytorch content
>>> 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",
... )
TensorFlow
Hide TensorFlow content
>>> tf_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="tf",
... )

查看预处理教程以获取有关标记化的更多详细信息,以及如何使用AutoImageProcessorAutoFeatureExtractorAutoProcessor来预处理图像、音频和多模态输入。

AutoModel

Pytorch
Hide Pytorch content

🤗 Transformers 提供了一种简单且统一的方式来加载预训练实例。这意味着你可以像加载 AutoTokenizer 一样加载 AutoModel。唯一的区别是为任务选择正确的 AutoModel。对于文本(或序列)分类,你应该加载 AutoModelForSequenceClassification

默认情况下,权重以全精度(torch.float32)加载,无论权重实际存储的数据类型是什么,例如torch.float16。设置torch_dtype="auto"以加载模型config.json文件中定义的数据类型,以自动加载内存最优的数据类型。

>>> from transformers import AutoModelForSequenceClassification

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

查看任务摘要了解AutoModel类支持的任务。

现在直接将预处理后的输入批次传递给模型。你只需要通过添加 ** 来解包字典:

>>> 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>)
TensorFlow
Hide TensorFlow content

🤗 Transformers 提供了一种简单且统一的方式来加载预训练实例。这意味着你可以像加载 AutoTokenizer 一样加载 TFAutoModel。唯一的区别是为任务选择正确的 TFAutoModel。对于文本(或序列)分类,你应该加载 TFAutoModelForSequenceClassification

>>> from transformers import TFAutoModelForSequenceClassification

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

查看任务摘要以了解AutoModel类支持的任务。

现在将您预处理过的输入批次直接传递给模型。您可以按原样传递张量:

>>> tf_outputs = tf_model(tf_batch)

模型在logits属性中输出最终的激活值。对logits应用softmax函数以获取概率:

>>> import tensorflow as tf

>>> tf_predictions = tf.nn.softmax(tf_outputs.logits, axis=-1)
>>> tf_predictions

所有 🤗 Transformers 模型(PyTorch 或 TensorFlow)在最终激活函数(如 softmax)之前输出张量,因为最终激活函数通常与损失函数融合。模型输出是特殊的数据类,因此它们的属性在 IDE 中会自动补全。模型输出的行为类似于元组或字典(你可以使用整数、切片或字符串进行索引),在这种情况下,为 None 的属性会被忽略。

保存模型

Pytorch
Hide Pytorch content

一旦你的模型经过微调,你可以使用PreTrainedModel.save_pretrained()保存它及其分词器:

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

当你准备再次使用模型时,使用PreTrainedModel.from_pretrained()重新加载它:

>>> pt_model = AutoModelForSequenceClassification.from_pretrained("./pt_save_pretrained")
TensorFlow
Hide TensorFlow content

一旦你的模型微调完成,你可以使用TFPreTrainedModel.save_pretrained()保存它及其分词器:

>>> tf_save_directory = "./tf_save_pretrained"
>>> tokenizer.save_pretrained(tf_save_directory)
>>> tf_model.save_pretrained(tf_save_directory)

当你准备再次使用模型时,使用TFPreTrainedModel.from_pretrained()重新加载它:

>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained("./tf_save_pretrained")

一个特别酷的🤗 Transformers功能是能够保存模型并将其重新加载为PyTorch或TensorFlow模型。from_ptfrom_tf参数可以将模型从一个框架转换为另一个框架:

Pytorch
Hide Pytorch content
>>> from transformers import AutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(pt_save_directory)
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(pt_save_directory, from_pt=True)
TensorFlow
Hide TensorFlow content
>>> from transformers import TFAutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(tf_save_directory)
>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained(tf_save_directory, from_tf=True)

自定义模型构建

你可以修改模型的配置类来改变模型的构建方式。配置指定了模型的属性,例如隐藏层的数量或注意力头的数量。当你从自定义配置类初始化模型时,你是从头开始的。模型属性是随机初始化的,你需要训练模型才能使用它来获得有意义的结果。

首先导入 AutoConfig,然后加载你想要修改的预训练模型。在 AutoConfig.from_pretrained() 中,你可以指定你想要更改的属性,例如注意力头的数量:

>>> from transformers import AutoConfig

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

使用AutoModel.from_config()从您的自定义配置创建模型:

>>> from transformers import AutoModel

>>> my_model = AutoModel.from_config(my_config)
TensorFlow
Hide TensorFlow content

使用TFAutoModel.from_config()从您的自定义配置创建模型:

>>> from transformers import TFAutoModel

>>> my_model = TFAutoModel.from_config(my_config)

查看创建自定义架构指南,了解更多关于构建自定义配置的信息。

Trainer - 一个PyTorch优化的训练循环

所有模型都是标准的torch.nn.Module,因此你可以在任何典型的训练循环中使用它们。虽然你可以编写自己的训练循环,但🤗 Transformers为PyTorch提供了一个Trainer类,它包含了基本的训练循环,并增加了分布式训练、混合精度等功能的额外特性。

根据你的任务,你通常会向Trainer传递以下参数:

  1. 您将从PreTrainedModeltorch.nn.Module开始。设置torch_dtype="auto"以自动加载权重存储的最节省内存的数据类型。

    >>> from transformers import AutoModelForSequenceClassification
    
    >>> model = AutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased", torch_dtype="auto")
  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")  # doctest: +IGNORE_RESULT
  5. 创建一个函数来对数据集进行分词:

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

    然后使用map将其应用于整个数据集:

    >>> dataset = dataset.map(tokenize_dataset, batched=True)
  6. 一个 DataCollatorWithPadding 用于从您的数据集中创建一批示例:

    >>> 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,
... )  # doctest: +SKIP

当你准备好时,调用 train() 开始训练:

>>> trainer.train()

对于使用序列到序列模型的任务 - 如翻译或摘要 - 请使用 Seq2SeqTrainerSeq2SeqTrainingArguments 类。

你可以通过子类化Trainer内部的方法来自定义训练循环行为。这允许你自定义诸如损失函数、优化器和调度器等功能。查看Trainer参考以了解哪些方法可以被子类化。

另一种自定义训练循环的方法是使用回调函数。你可以使用回调函数与其他库集成,并检查训练循环以报告进度或提前停止训练。回调函数不会修改训练循环中的任何内容。要自定义损失函数等内容,你需要子类化Trainer

使用 TensorFlow 进行训练

所有模型都是标准的tf.keras.Model,因此它们可以在TensorFlow中使用Keras API进行训练。🤗 Transformers提供了prepare_tf_dataset()方法,可以轻松地将您的数据集加载为tf.data.Dataset,这样您就可以立即使用Keras的compilefit方法开始训练。

  1. 你将从一个TFPreTrainedModel或一个tf.keras.Model开始:

    >>> from transformers import TFAutoModelForSequenceClassification
    
    >>> model = TFAutoModelForSequenceClassification.from_pretrained("distilbert/distilbert-base-uncased")
  2. 加载一个预处理类,如分词器、图像处理器、特征提取器或处理器:

    >>> from transformers import AutoTokenizer
    
    >>> tokenizer = AutoTokenizer.from_pretrained("distilbert/distilbert-base-uncased")
  3. 创建一个函数来对数据集进行分词:

    >>> def tokenize_dataset(dataset):
    ...     return tokenizer(dataset["text"])  # doctest: +SKIP
  4. 在整个数据集上应用分词器,使用map,然后将数据集和分词器传递给prepare_tf_dataset()。如果您愿意,还可以在此处更改批量大小并打乱数据集:

    >>> dataset = dataset.map(tokenize_dataset)  # doctest: +SKIP
    >>> tf_dataset = model.prepare_tf_dataset(
    ...     dataset["train"], batch_size=16, shuffle=True, tokenizer=tokenizer
    ... )  # doctest: +SKIP
  5. 当你准备好时,你可以调用 compilefit 来开始训练。请注意,Transformers 模型都有一个默认的任务相关损失函数,因此除非你想要指定一个,否则不需要指定:

    >>> from tensorflow.keras.optimizers import Adam
    
    >>> model.compile(optimizer='adam')  # No loss argument!
    >>> model.fit(tf_dataset)  # doctest: +SKIP

接下来是什么?

既然你已经完成了🤗 Transformers的快速入门,查看我们的指南,学习如何做更具体的事情,比如编写自定义模型、为任务微调模型,以及如何使用脚本训练模型。如果你有兴趣了解更多关于🤗 Transformers核心概念的内容,泡杯咖啡,看看我们的概念指南吧!

< > Update on GitHub