Transformers 教程

你好！

这个仓库包含了我使用 🤗 HuggingFace 的 Transformers 库制作的一些示例。目前，所有示例都是用 PyTorch 实现的。

注意：如果你对 HuggingFace 和/或 Transformers 还不熟悉，强烈建议你先观看我们的免费课程，它会介绍多种 Transformer 架构（如 BERT、GPT-2、T5、BART 等），以及 HuggingFace 生态系统中各个库的概览，包括 Transformers、Tokenizers、Datasets、Accelerate 和 hub。

关于 HuggingFace 计算机视觉生态系统的概述（2022年6月），请参考这篇 Notebook，并观看对应的视频。

Currently, it contains the following demos:

• Audio Spectrogram Transformer (paper):
  • performing inference with ASTForAudioClassification to classify audio.
• BERT (paper):
  • fine-tuning BertForTokenClassification on a named entity recognition (NER) dataset.
  • fine-tuning BertForSequenceClassification for multi-label text classification.
• BEiT (paper):
  • understanding BeitForMaskedImageModeling
• CANINE (paper):
  • fine-tuning CanineForSequenceClassification on IMDb
• CLIPSeg (paper):
  • performing zero-shot image segmentation with CLIPSeg
• Conditional DETR (paper):
  • performing inference with ConditionalDetrForObjectDetection
  • fine-tuning ConditionalDetrForObjectDetection on a custom dataset (balloon)
• ConvNeXT (paper):
  • fine-tuning (and performing inference with) ConvNextForImageClassification
• DINO (paper):
  • visualize self-attention of Vision Transformers trained using the DINO method
• DETR (paper):
  • performing inference with DetrForObjectDetection
  • fine-tuning DetrForObjectDetection on a custom object detection dataset
  • evaluating DetrForObjectDetection on the COCO detection 2017 validation set
  • performing inference with DetrForSegmentation
  • fine-tuning DetrForSegmentation on COCO panoptic 2017
• DPT (paper):
  • performing inference with DPT for monocular depth estimation
  • performing inference with DPT for semantic segmentation
• Deformable DETR (paper):
  • performing inference with DeformableDetrForObjectDetection
• DiT (paper):
  • performing inference with DiT for document image classification
• Donut (paper):
  • performing inference with Donut for document image classification
  • fine-tuning Donut for document image classification
  • performing inference with Donut for document visual question answering (DocVQA)
  • performing inference with Donut for document parsing
  • fine-tuning Donut for document parsing with PyTorch Lightning
• GIT (paper):
  • performing inference with GIT for image/video captioning and image/video question-answering
  • fine-tuning GIT on a custom image captioning dataset
• GLPN (paper):
  • performing inference with GLPNForDepthEstimation to illustrate monocular depth estimation
• GPT-J-6B (repository):
  • performing inference with GPTJForCausalLM to illustrate few-shot learning and code generation
• GroupViT (repository):
  • performing inference with GroupViTModel to illustrate zero-shot semantic segmentation
• ImageGPT (blog post):
  • (un)conditional image generation with ImageGPTForCausalLM
  • linear probing with ImageGPT
• LUKE (paper):
  • fine-tuning LukeForEntityPairClassification on a custom relation extraction dataset using PyTorch Lightning
• LayoutLM (paper):
  • fine-tuning LayoutLMForTokenClassification on the FUNSD dataset
  • fine-tuning LayoutLMForSequenceClassification on the RVL-CDIP dataset
  • adding image embeddings to LayoutLM during fine-tuning on the FUNSD dataset
• LayoutLMv2 (paper):
  • fine-tuning LayoutLMv2ForSequenceClassification on RVL-CDIP
  • fine-tuning LayoutLMv2ForTokenClassification on FUNSD
  • fine-tuning LayoutLMv2ForTokenClassification on FUNSD using the 🤗 Trainer
  • performing inference with LayoutLMv2ForTokenClassification on FUNSD
  • true inference with LayoutLMv2ForTokenClassification (when no labels are available) + Gradio demo
  • fine-tuning LayoutLMv2ForTokenClassification on CORD
  • fine-tuning LayoutLMv2ForQuestionAnswering on DOCVQA
• LayoutLMv3 (paper):
  • fine-tuning LayoutLMv3ForTokenClassification on the FUNSD dataset
• LayoutXLM (paper):
  • fine-tuning LayoutXLM on the XFUND benchmark for token classification
  • fine-tuning LayoutXLM on the XFUND benchmark for relation extraction
• MarkupLM (paper):
  • inference with MarkupLM to perform question answering on web pages
  • fine-tuning MarkupLMForTokenClassification on a toy dataset for NER on web pages
• Mask2Former (paper):
  • performing inference with Mask2Former for universal image segmentation:
• MaskFormer (paper):
  • performing inference with MaskFormer (both semantic and panoptic segmentation):
  • fine-tuning MaskFormer on a custom dataset for semantic segmentation
• OneFormer (paper):
  • performing inference with OneFormer for universal image segmentation:
• Perceiver IO (paper):
  • showcasing masked language modeling and image classification with the Perceiver
  • fine-tuning the Perceiver for image classification
  • fine-tuning the Perceiver for text classification
  • predicting optical flow between a pair of images with PerceiverForOpticalFlow
  • auto-encoding a video (images, audio, labels) with PerceiverForMultimodalAutoencoding
• SAM (paper):
  • performing inference with MedSAM
  • fine-tuning SamModel on a custom dataset
• SegFormer (paper):
  • performing inference with SegformerForSemanticSegmentation
  • fine-tuning SegformerForSemanticSegmentation on custom data using native PyTorch
• T5 (paper):
  • fine-tuning T5ForConditionalGeneration on a Dutch summarization dataset on TPU using HuggingFace Accelerate
  • fine-tuning T5ForConditionalGeneration (CodeT5) for Ruby code summarization using PyTorch Lightning
• TAPAS (paper):
  • fine-tuning TapasForQuestionAnswering on the Microsoft Sequential Question Answering (SQA) dataset
  • evaluating TapasForSequenceClassification on the Table Fact Checking (TabFact) dataset
• Table Transformer (paper):
  • using the Table Transformer for table detection and table structure recognition
• TrOCR (paper):
  • performing inference with TrOCR to illustrate optical character recognition with Transformers, as well as making a Gradio demo
  • fine-tuning TrOCR on the IAM dataset using the Seq2SeqTrainer
  • fine-tuning TrOCR on the IAM dataset using native PyTorch
  • evaluating TrOCR on the IAM test set
• UPerNet (paper):
  • performing inference with UperNetForSemanticSegmentation
• VideoMAE (paper):
  • performing inference with VideoMAEForVideoClassification
• ViLT (paper):
  • fine-tuning ViLT for visual question answering (VQA)
  • performing inference with ViLT to illustrate visual question answering (VQA)
  • masked language modeling (MLM) with a pre-trained ViLT model
  • performing inference with ViLT for image-text retrieval
  • performing inference with ViLT to illustrate natural language for visual reasoning (NLVR)
• ViTMAE (paper):
  • reconstructing pixel values with ViTMAEForPreTraining
• Vision Transformer (paper):
  • performing inference with ViTForImageClassification
  • fine-tuning ViTForImageClassification on CIFAR-10 using PyTorch Lightning
  • fine-tuning ViTForImageClassification on CIFAR-10 using the 🤗 Trainer
• X-CLIP (paper):
  • performing zero-shot video classification with X-CLIP
  • zero-shot classifying a YouTube video with X-CLIP
• YOLOS (paper):
  • fine-tuning YolosForObjectDetection on a custom dataset
  • inference with YolosForObjectDetection

… 更多内容即将发布！🤗

如果您对这些演示有任何疑问，请随时在此仓库中提交一个问题。

顺便说一下，我也是将以下算法添加到该库的主要贡献者：

• Google AI 的 TAbular PArSing (TAPAS)
• Google AI 的 Vision Transformer (ViT)
• Facebook AI 的 DINO
• Facebook AI 的 Data-efficient Image Transformers (DeiT)
• Studio Ousia 的 LUKE
• Facebook AI 的 DEtection TRansformers (DETR)
• Google AI 的 CANINE
• Microsoft Research 的 BEiT
• Microsoft Research 的 LayoutLMv2（以及 LayoutXLM）
• Microsoft Research 的 TrOCR
• NVIDIA 的 SegFormer
• OpenAI 的 ImageGPT
• Deepmind 的 Perceiver
• Facebook AI 的 MAE
• NAVER AI Lab 的 ViLT
• Facebook AI 的 ConvNeXT
• Microsoft Research 的 DiT
• KAIST 的 GLPN
• Intel Labs 的 DPT
• 华中科技大学 EIC 学院的 YOLOS
• Microsoft Research 的 TAPEX
• Microsoft Research 的 LayoutLMv3
• 南京大学多媒体计算组的 VideoMAE
• Microsoft Research 的 X-CLIP
• Microsoft Research 的 MarkupLM

所有这些项目都让我受益匪浅。我强烈建议大家也为这个库贡献自己的 AI 算法！

数据预处理

关于为 PyTorch 模型准备数据，有几种选择：

• 使用原生 PyTorch 数据集和数据加载器。这是为 PyTorch 模型准备数据的标准方法，即通过继承 torch.utils.data.Dataset 类，并创建相应的 DataLoader（一个 Python 生成器，允许循环遍历数据集中的每个样本）。在继承 Dataset 类时，需要实现三个方法：__init__、__len__（返回数据集的样本数量）和 __getitem__（根据整数索引返回数据集中的一个样本）。以下是一个创建基本文本分类数据集的示例（假设有一个包含两列“text”和“label”的 CSV 文件）：

from torch.utils.data import Dataset

class CustomTrainDataset(Dataset):
    def __init__(self, df, tokenizer):
        self.df = df
        self.tokenizer = tokenizer

    def __len__(self):
        return len(self.df)

    def __getitem__(self, idx):
        # 获取样本
        item = df.iloc[idx]
        text = item['text']
        label = item['label']
        # 对文本进行编码
        encoding = self.tokenizer(text, padding="max_length", max_length=128, truncation=True, return_tensors="pt")
        # 去掉分词器自动添加的批次维度
        encoding = {k:v.squeeze() for k,v in encoding.items()}
        # 添加标签
        encoding["label"] = torch.tensor(label)
        
        return encoding

实例化数据集的方式如下：

from transformers import BertTokenizer
import pandas as pd

tokenizer = BertTokenizer.from_pretrained("bert-base-uncased")
df = pd.read_csv("path_to_your_csv")

train_dataset = CustomTrainDataset(df=df, tokenizer=tokenizer)

访问数据集的第一个样本可以这样操作：

encoding = train_dataset[0]

实际上，通常会创建一个对应的 DataLoader 来从数据集中获取批次数据：

from torch.utils.data import DataLoader

train_dataloader = DataLoader(train_dataset, batch_size=4, shuffle=True)

我经常通过从数据加载器中取出第一个批次，打印张量的形状、将 input_ids 解码回文本等方式来检查数据是否正确创建。

batch = next(iter(train_dataloader))
for k,v in batch.items():
    print(k, v.shape)
# 解码批次中第一个样本的 input_ids
print(tokenizer.decode(batch['input_ids'][0].tolist())

• HuggingFace Datasets。Datasets 是 HuggingFace 提供的一个库，能够以非常快速且节省内存的方式轻松加载和处理数据。它基于 Apache Arrow 构建，并具有诸如内存映射等强大功能，使得数据仅在需要时才会被加载到内存中。它与 HuggingFace hub 具有深度集成，因此可以轻松加载知名数据集，也可以将自己的数据集分享给社区。

以 Dataset 对象的形式加载自定义数据集的方法如下（可以通过 pip install datasets 安装）：

from datasets import load_dataset

dataset = load_dataset('csv', data_files={'train': ['my_train_file_1.csv', 'my_train_file_2.csv'] 'test': 'my_test_file.csv'})

这里我加载的是本地的 CSV 文件，但该库也支持其他格式（包括 JSON、Parquet、txt），还可以直接从本地 Pandas 数据框或字典中加载数据。更多详细信息请参阅 文档。

训练框架

关于微调 Transformer 模型（或更一般地，PyTorch 模型），有几种选择：

• 使用原生 PyTorch。这是最基础的训练方式，需要用户手动编写训练循环。优点是调试起来非常方便，缺点则是需要自己实现训练过程，比如设置模型模式（model.train()/model.eval()）、管理设备分配（model.to(device)）等。典型的 PyTorch 训练循环如下所示（灵感来自 这篇优秀的 PyTorch 入门教程)：

import torch
from transformers import BertForSequenceClassification

# 实例化一个带有随机初始化分类头的预训练 BERT 模型
model = BertForSequenceClassification.from_pretrained("bert-base-uncased")

# 我在微调基于 Transformer 的模型时几乎总是使用 5e-5 的学习率
optimizer = torch.optim.Adam(model.parameters(), lr=5e-5)

# 如果有可用的 GPU，则将模型放到 GPU 上
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
model.to(device)

for epoch in range(epochs):
    model.train()
    train_loss = 0.0
    for batch in train_dataloader:
        # 将批次数据放到指定设备上
        batch = {k:v.to(device) for k,v in batch.items()}
        
        # 前向传播
        outputs = model(**batch)
        loss = outputs.loss
        
        train_loss += loss.item()
        
        loss.backward()
        optimizer.step()
        optimizer.zero_grad()

    print(f"第 {epoch} 个 epoch 后的训练损失: {train_loss/len(train_dataloader)}")
    
    model.eval()
    val_loss = 0.0
    with torch.no_grad():
        for batch in eval_dataloader:
            # 将批次数据放到指定设备上
            batch = {k:v.to(device) for k,v in batch.items()}
            
            # 前向传播
            outputs = model(**batch)
            loss = outputs.logits
            
            val_loss += loss.item()
                  
    print(f"第 {epoch} 个 epoch 后的验证损失: {val_loss/len(eval_dataloader)}")

• PyTorch Lightning (PL)。PyTorch Lightning 是一个框架，它通过将训练循环抽象为一个 Trainer 对象来自动化上述训练过程。用户不再需要自己编写训练循环，只需创建 trainer = Trainer() 并调用 trainer.fit(model) 即可。其优点是能够非常快速地开始训练模型（这也是“Lightning”名称的由来），因为所有与训练相关的代码都由 Trainer 对象处理。缺点则是调试模型可能会更加困难，因为训练和评估过程已经被抽象掉了。

• HuggingFace Trainer。HuggingFace 的 Trainer API 可以被视为类似于 PyTorch Lightning 的框架，因为它同样使用 Trainer 对象来抽象训练过程。然而，与 PyTorch Lightning 不同的是，HuggingFace Trainer 并不是一个通用框架，而是专门为微调 HuggingFace Transformers 库中提供的基于 Transformer 的模型而设计的。此外，Trainer 还提供了一个名为 Seq2SeqTrainer 的扩展，用于编码器-解码器架构的模型，例如 BART、T5 和 EncoderDecoderModel 类。需要注意的是，Transformers 库中的所有 PyTorch 示例脚本 都使用了 Trainer。

• HuggingFace Accelerate：Accelerate 是一个新项目，旨在帮助那些仍然希望自行编写训练循环（如上文所示）的人，同时让这些循环能够在不同硬件环境下自动运行，例如多 GPU、TPU Pod、混合精度等。

引用

如果您在使用我的教程时有任何引用需求，请随时注明出处 :)

@misc{rogge2025transformerstutorials,
  author = {Rogge, Niels},
  title = {教程},
  url = {[https://github.com/NielsRogge/tutorials](https://github.com/NielsRogge/Transformers-Tutorials)},
  year = {2025}
}

Transformers-Tutorials 快速上手指南

本仓库提供了基于 🤗 Hugging Face transformers 库的一系列实战演示（Demo），涵盖音频、文本、图像及多模态任务。所有示例均使用 PyTorch 实现，并配有可直接运行的 Colab 笔记本。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows
• Python 版本: 3.7 或更高
• 深度学习框架: PyTorch (推荐安装最新稳定版)
• 硬件建议: 部分模型（如 GPT-J-6B, BEiT）推理或微调需要 GPU 支持；轻量级模型可在 CPU 上运行。

安装步骤

推荐使用 pip 进行安装。为了获得更快的下载速度，国内用户建议使用清华或阿里镜像源。

1. 安装核心依赖

pip install transformers datasets accelerate torch torchvision torchaudio --index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装可选依赖（针对特定任务）

部分演示（如音频处理、文档解析）可能需要额外库：

# 音频处理 (AST, Wav2Vec2 等)
pip install librosa soundfile --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 文档智能与 OCR (Donut, LayoutLM 等)
pip install pillow opencv-python --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 训练加速与监控 (可选)
pip install pytorch-lightning tensorboard --index-url https://pypi.tuna.tsinghua.edu.cn/simple

3. 克隆本教程仓库

获取所有示例代码和 Notebook：

git clone https://github.com/NielsRogge/Transformers-Tutorials.git
cd Transformers-Tutorials

基本使用

本仓库的核心内容是各个模型目录下的 .ipynb (Jupyter Notebook) 文件。您可以直接在本地 Jupyter Lab 中打开，或点击 README 中的 "Open In Colab" 按钮在云端免费运行。

示例：使用 BERT 进行自定义命名实体识别 (NER)

以下展示如何加载预训练模型并进行微调的基本流程（对应 BERT/Custom_Named_Entity_Recognition... 示例）：

1. 导入库与加载数据

from transformers import BertTokenizerFast, BertForTokenClassification
from datasets import load_dataset

# 加载数据集 (以 ConLL2003 为例)
dataset = load_dataset("conll2003")

# 加载分词器
tokenizer = BertTokenizerFast.from_pretrained("bert-base-cased")

2. 数据预处理

def tokenize_and_align_labels(examples):
    tokenized_inputs = tokenizer(examples["tokens"], truncation=True, is_split_into_words=True)
    # 此处省略标签对齐逻辑，详见 Notebook 源码
    return tokenized_inputs

tokenized_dataset = dataset.map(tokenize_and_align_labels, batched=True)

3. 定义模型与训练参数

model = BertForTokenClassification.from_pretrained("bert-base-cased", num_labels=9)

from transformers import TrainingArguments

training_args = TrainingArguments(
    output_dir="./results",
    evaluation_strategy="epoch",
    learning_rate=2e-5,
    per_device_train_batch_size=16,
    num_train_epochs=3,
)

4. 启动训练

from transformers import Trainer

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized_dataset["train"],
    eval_dataset=tokenized_dataset["validation"],
)

trainer.train()

其他热门任务入口

• 图像分类: 查看 ConvNeXT 或 BEiT 文件夹。
• 目标检测: 查看 DETR 或 Conditional DETR 文件夹。
• 文档智能: 查看 Donut 文件夹（支持文档分类、VQA 及解析）。
• 零样本分割: 查看 CLIPSeg 或 GroupViT 文件夹。

提示: 对于每个具体模型，请直接进入对应的子文件夹运行 .ipynb 文件，其中包含了从数据加载、预处理、微调到推理评估的完整代码。