Transformers

Transformers 库概览

Transformers 是面向文本、计算机视觉、音频、视频以及多模态场景的预训练模型库，既可用于推理也可用于训练。库的核心定位是模型定义框架：统一模型定义后，整个生态中的训练框架（Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch-Lightning 等）、推理引擎（vLLM、SGLang、TGI 等）以及周边建模库（llama.cpp、mlx 等）都能基于同一份定义协同工作。Hub 上已有超过 100 万个 Transformers 兼容的模型检查点。

安装

环境要求：Python 3.10+、PyTorch 2.5+。建议先创建虚拟环境：

# 使用 venv
python -m venv .my-env
source .my-env/bin/activate

# 或使用 uv（基于 Rust 的高速 Python 包管理器）
uv venv .my-env
source .my-env/bin/activate

安装库本体：

# pip 安装（含 PyTorch 依赖）
pip install "transformers[torch]"
# uv 安装
uv pip install "transformers[torch]"

如需最新源码或参与开发，可从 GitHub 克隆安装：

git clone https://github.com/huggingface/transformers.git
cd transformers
pip install '.[torch]'

快速上手

pipeline 是高层推理接口，覆盖文本、音频、视觉与多模态任务，内部自动完成预处理与后处理。

文本生成

from transformers import pipeline

# 文本补全：指定任务与模型，模型自动下载并缓存
generator = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
print(generator("the secret to baking a really good cake is "))

对话模式

传入对话历史（消息列表）即可与指令模型交互：

import torch
from transformers import pipeline

chat = [
    {"role": "system", "content": "You are a sassy, wise-cracking robot as imagined by Hollywood circa 1986."},
    {"role": "user", "content": "Hey, can you tell me any fun things to do in New York?"},
]

pipe = pipeline(
    task="text-generation",
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    dtype=torch.bfloat16,
    device_map="auto",  # 自动分配到可用设备
)
response = pipe(chat, max_new_tokens=512)
print(response[0]["generated_text"][-1]["content"])

此外，也可通过命令行直接对话：transformers chat Qwen/Qwen2.5-0.5B-Instruct。

多模态示例

同一 pipeline 接口可直接切换任务类型：

# 语音识别
asr = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
asr("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")

# 图像分类
clf = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
clf("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")

# 视觉问答
vqa = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
vqa(image="<图片URL>", question="What is in the image?")

核心优势

• 易用：统一 API，仅需掌握少量抽象类即可使用全部预训练模型，覆盖 NLP、视觉、音频、视频、多模态任务。
• 低成本：复用社区预训练检查点，避免从零训练；提供数百种架构、上百万检查点，降低算力与碳足迹。
• 框架自由：同一模型可在 PyTorch、JAX、TF2.0 之间自由切换，训练、评估、部署各阶段可选最合适的框架；3 行代码即可启动训练。
• 可定制：官方提供每个架构的复现示例，模型内部结构以一致方式暴露，方便改造实验。

不适用场景

• 模型代码并未刻意抽象为可组合的模块化积木，研究者若需快速迭代单模型反而可能被额外抽象干扰。
• 训练 API 针对 Transformers 提供的 PyTorch 模型优化；通用机器学习训练循环建议使用 Accelerate 等专用库。
• examples/ 下的脚本仅为示例，需根据具体场景自行调整。

支持的模型示例

涵盖音频、计算机视觉、多模态、NLP 等多个方向：

• 音频：CLAP（音频分类）、Whisper/Parakeet（语音识别）、MusicGen（文本生成音频）、CSM（文本转语音）等。
• 视觉：SAM（自动掩码生成）、DepthPro（深度估计）、DINO v2（图像分类）、RT-DETRv2（目标检测）、OneFormer（通用分割）、VideoMAE（视频分类）等。
• 多模态：Voxtral（音/文到文本）、Qwen-VL（图/文到文本）、BLIP-2（图像描述）、Llava-OneVision（视觉到文本）、LayoutLMv3（文档问答）等。
• NLP：ModernBERT（掩码词补全）、Llama（文本生成）、BART（摘要）、T5（翻译）、Gemma（命名实体识别）、Mixtral（问答）、Qwen（文本分类）等。

引用

@inproceedings{wolf-etal-2020-transformers,
    title = "Transformers: State-of-the-Art Natural Language Processing",
    author = "Thomas Wolf and Lysandre Debut and Victor Sanh and Julien Chaumond and Clement Delangue and Anthony Moi and Pierric Cistac and Tim Rault and Rémi Louf and Morgan Funtowicz and Joe Davison and Sam Shleifer and Patrick von Platen and Clara Ma and Yacine Jernite and Julien Plu and Canwen Xu and Teven Le Scao and Sylvain Gugger and Mariama Drame and Quentin Lhoest and Alexander M. Rush",
    booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    month = oct, year = "2020", address = "Online",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2020.emnlp-demos.6/",
    pages = "38--45"
}