Transformers 文档

快速浏览

Hugging Face's logo
加入 Hugging Face 社区

并获取增强的文档体验

开始使用

快速入门

开始使用 🤗 Transformers!无论是开发者还是日常用户,此快速入门都会帮助您入门并展示如何使用 pipeline() 进行推理,使用 AutoClass 加载预训练模型和预处理器,以及使用 PyTorch 或 TensorFlow 快速训练模型。如果您是新手,建议您接下来查看我们的教程或 课程,以更深入地了解此处介绍的概念。

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

!pip install transformers datasets evaluate accelerate

您还需要安装您喜欢的机器学习框架

Pytorch
隐藏 Pytorch 内容
pip install torch
TensorFlow
隐藏 TensorFlow 内容
pip install tensorflow

管道

使用预训练模型进行推理最简单、最快的方法是 pipeline()。您可以直接使用 pipeline() 来完成各种模态下的多种任务,下表中列出了一些示例。

要查看所有可用任务的完整列表,请查看 管道 API 参考

任务 描述 模态 管道标识符
文本分类 为给定的文本序列分配标签 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”)

首先,创建 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")

加载您要迭代的音频数据集(有关更多详细信息,请参阅 🤗 数据集 快速入门)。例如,加载 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']

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

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

pipeline() 可以适应来自 Hub 的任何模型,方便您将 pipeline() 适应其他用例。例如,如果您需要一个能够处理法语文本的模型,请使用 Hub 上的标签来过滤合适的模型。过滤后的首个结果返回一个针对情感分析进行了微调的多语言 BERT 模型,您可以将其用于法语文本。

>>> model_name = "nlptown/bert-base-multilingual-uncased-sentiment"
Pytorch
隐藏 Pytorch 内容

使用 AutoModelForSequenceClassificationAutoTokenizer 加载预训练模型及其关联分词器(有关 AutoClass 的更多信息,请参阅下一节)。

>>> from transformers import AutoTokenizer, AutoModelForSequenceClassification

>>> model = AutoModelForSequenceClassification.from_pretrained(model_name)
>>> tokenizer = AutoTokenizer.from_pretrained(model_name)
TensorFlow
隐藏 TensorFlow 内容

使用 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
隐藏 Pytorch 内容
>>> 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
隐藏 TensorFlow 内容
>>> 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
隐藏 Pytorch 内容

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

>>> from transformers import AutoModelForSequenceClassification

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

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

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

>>> pt_outputs = pt_model(**pt_batch)

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

>>> 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
隐藏 TensorFlow 内容

🤗 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 属性中输出最终激活值。将 softmax 函数应用于 logits 以获取概率。

>>> import tensorflow as tf

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

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

保存模型

Pytorch
隐藏 Pytorch 内容

模型微调完成后,你可以使用 PreTrainedModel.save_pretrained() 与其 tokenizer 一起保存模型。

>>> 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
隐藏 TensorFlow 内容

模型微调完成后,你可以使用 TFPreTrainedModel.save_pretrained() 与其 tokenizer 一起保存模型。

>>> 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
隐藏 Pytorch 内容
>>> from transformers import AutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(tf_save_directory)
>>> pt_model = AutoModelForSequenceClassification.from_pretrained(tf_save_directory, from_tf=True)
TensorFlow
隐藏 TensorFlow 内容
>>> from transformers import TFAutoModel

>>> tokenizer = AutoTokenizer.from_pretrained(pt_save_directory)
>>> tf_model = TFAutoModelForSequenceClassification.from_pretrained(pt_save_directory, from_pt=True)

自定义模型构建

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

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

>>> from transformers import AutoConfig

>>> my_config = AutoConfig.from_pretrained("distilbert/distilbert-base-uncased", n_heads=12)
Pytorch
隐藏 Pytorch 内容

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

>>> from transformers import AutoModel

>>> my_model = AutoModel.from_config(my_config)
TensorFlow
隐藏 TensorFlow 内容

使用 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 开始。

    >>> 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. 加载预处理类,例如 tokenizer、图像处理器、特征提取器或处理器。

    >>> 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"],
...     tokenizer=tokenizer,
...     data_collator=data_collator,
... )  # doctest: +SKIP

当你准备就绪时,调用 train() 开始训练。

>>> trainer.train()

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

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

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

使用 TensorFlow 进行训练

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

  1. 你将从 TFPreTrainedModeltf.keras.Model 开始。

    >>> 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. 创建一个函数来对数据集进行标记。

    >>> def tokenize_dataset(dataset):
    ...     return tokenizer(dataset["text"])  # doctest: +SKIP
  4. 使用 map 将 tokenizer 应用于整个数据集,然后将数据集和 tokenizer 传递给 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 核心概念的信息,请拿起一杯咖啡,看看我们的概念指南!

< > 在 GitHub 上更新