README_zh-hans.md

English | 简体中文 | 繁體中文 | 한국어 | Español | 日本語 | हिन्दी | Русский | Português | తెలుగు | Français | Deutsch | Italiano | Tiếng Việt | العربية | اردو | বাংলা |

为文本、视觉、音频、视频与多模态提供推理与训练的先进预训练模型

Transformers 充当跨文本、计算机视觉、音频、视频与多模态的最先进机器学习模型的「模型定义框架」，同时覆盖推理与训练。

它将模型的定义集中化，使整个生态系统对该定义达成一致。transformers 是跨框架的枢纽：一旦某模型定义被支持，它通常就能兼容多数训练框架（如 Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch‑Lightning 等）、推理引擎（如 vLLM、SGLang、TGI 等），以及依赖 transformers 模型定义的相关库（如 llama.cpp、mlx 等）。

我们的目标是持续支持新的最先进模型，并通过让模型定义保持简单、可定制且高效来普及其使用。

目前在 Hugging Face Hub 上有超过 1M+ 使用 transformers 的模型检查点，可随取随用。

今天就去探索 Hub，找到一个模型，并用 Transformers 立刻开始吧。

安装

Transformers 支持 Python 3.10+，以及 PyTorch 2.4+。

使用 venv 或 uv（一个基于 Rust 的快速 Python 包与项目管理器）创建并激活虚拟环境：

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

在虚拟环境中安装 Transformers：

# pip
pip install "transformers[torch]"

# uv
uv pip install "transformers[torch]"

如果你需要库中的最新改动或计划参与贡献，可从源码安装（注意：最新版可能不稳定；如遇错误，欢迎在 issues 中反馈）：

git clone https://github.com/huggingface/transformers.git
cd transformers

# pip
pip install '.[torch]'

# uv
uv pip install '.[torch]'

快速上手

使用 Pipeline API 一步上手。Pipeline 是一个高级推理类，支持文本、音频、视觉与多模态任务，负责输入预处理并返回适配的输出。

实例化一个用于文本生成的 pipeline，指定使用的模型。模型会被下载并缓存，方便复用。最后传入文本作为提示：

from transformers import pipeline

pipeline = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
pipeline("the secret to baking a really good cake is ")
[{'generated_text': 'the secret to baking a really good cake is 1) to use the right ingredients and 2) to follow the recipe exactly. the recipe for the cake is as follows: 1 cup of sugar, 1 cup of flour, 1 cup of milk, 1 cup of butter, 1 cup of eggs, 1 cup of chocolate chips. if you want to make 2 cakes, how much sugar do you need? To make 2 cakes, you will need 2 cups of sugar.'}]

要与模型进行「聊天」，用法也一致。唯一不同是需要构造一段「聊天历史」（即 Pipeline 的输入）：

Tip

你也可以直接在命令行与模型聊天：

transformers chat Qwen/Qwen2.5-0.5B-Instruct

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

pipeline = pipeline(task="text-generation", model="meta-llama/Meta-Llama-3-8B-Instruct", dtype=torch.bfloat16, device_map="auto")
response = pipeline(chat, max_new_tokens=512)
print(response[0]["generated_text"][-1]["content"])

展开下方示例，查看 Pipeline 在不同模态与任务中的用法。

自动语音识别

from transformers import pipeline

pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
{'text': ' I have a dream that one day this nation will rise up and live out the true meaning of its creed.'}

图像分类

from transformers import pipeline

pipeline = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
pipeline("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
[{"label": "macaw", "score": 0.997848391532898},
 {"label": "sulphur-crested cockatoo, Kakatoe galerita, Cacatua galerita",
  "score": 0.0016551691805943847},
 {"label": "lorikeet", "score": 0.00018523589824326336},
 {"label": "African grey, African gray, Psittacus erithacus",
  "score": 7.85409429227002e-05},
 {"label": "quail", "score": 5.502637941390276e-05}]

视觉问答

from transformers import pipeline

pipeline = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
pipeline(
    image="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg",
    question="What is in the image?",
)
[{"answer": "statue of liberty"}]

为什么要用 Transformers？

1. 易于使用的最先进模型：

   • 在自然语言理解与生成、计算机视觉、音频、视频与多模态任务上表现优越。
   • 对研究者、工程师与开发者友好且低门槛。
   • 少量用户侧抽象，仅需学习三个类。
   • 统一的 API，使用所有预训练模型体验一致。

2. 更低计算开销与更小碳足迹：

   • 共享已训练的模型，而非每次从零开始训练。
   • 减少计算时间与生产环境成本。
   • 覆盖数十种模型架构，跨所有模态提供 1M+ 预训练检查点。

3. 在模型生命周期的每个阶段都可以选用合适的框架：

   • 3 行代码即可训练最先进模型。
   • 在 PyTorch/JAX/TF2.0 间自由迁移同一个模型。
   • 为训练、评估与生产挑选最合适的框架。

4. 轻松定制模型或用例：

   • 为每个架构提供示例以复现原论文结果。
   • 尽可能一致地暴露模型内部。
   • 模型文件可独立于库使用，便于快速实验。

为什么我不该用 Transformers？

• 该库不是一个可自由拼搭的神经网络模块化工具箱。模型文件中的代码刻意减少额外抽象，以便研究者能快速在各个模型上迭代，而无需深入更多抽象或文件跳转。
• 训练 API 优化用于 Transformers 提供的 PyTorch 模型。若需要通用的机器学习训练循环，请使用其它库，如 Accelerate。
• 示例脚本只是「示例」。它们不一定能直接适配你的具体用例，需要你进行必要的改动。

100 个使用 Transformers 的项目

Transformers 不止是一个使用预训练模型的工具包，它还是围绕 Hugging Face Hub 构建的项目社区。我们希望 Transformers 能助力开发者、研究人员、学生、老师、工程师与任何人构建理想项目。

为庆祝 Transformers 获得 100,000 颗星，我们制作了 awesome-transformers 页面，展示了 100 个由社区构建的优秀项目。

如果你拥有或使用某个项目，认为它应该在列表中出现，欢迎提交 PR 添加它！

示例模型

你可以直接在它们的 Hub 模型页 上测试我们的多数模型。

展开每个模态以查看不同用例中的部分示例模型。

音频

• 使用 Whisper 进行音频分类
• 使用 Moonshine 进行自动语音识别
• 使用 Wav2Vec2 进行关键词检索
• 使用 Moshi 进行语音到语音生成
• 使用 MusicGen 文本到音频生成
• 使用 Bark 文本到语音生成

计算机视觉

• 使用 SAM 自动生成掩码
• 使用 DepthPro 进行深度估计
• 使用 DINO v2 进行图像分类
• 使用 SuperPoint 进行关键点检测
• 使用 SuperGlue 进行关键点匹配
• 使用 RT-DETRv2 进行目标检测
• 使用 VitPose 进行姿态估计
• 使用 OneFormer 进行通用分割
• 使用 VideoMAE 进行视频分类

多模态

• 使用 Qwen2-Audio 实现音频或文本到文本
• 使用 LayoutLMv3 进行文档问答
• 使用 Qwen-VL 实现图像或文本到文本
• 使用 BLIP-2 进行图文描述
• 使用 GOT-OCR2 进行基于 OCR 的文档理解
• 使用 TAPAS 进行表格问答
• 使用 Emu3 进行统一的多模态理解与生成
• 使用 Llava-OneVision 视觉到文本
• 使用 Llava 进行视觉问答
• 使用 Kosmos-2 进行视觉指代表达分割

NLP

• 使用 ModernBERT 进行掩码词填充
• 使用 Gemma 进行命名实体识别（NER）
• 使用 Mixtral 进行问答
• 使用 BART 进行摘要
• 使用 T5 进行翻译
• 使用 Llama 进行文本生成
• 使用 Qwen 进行文本分类

引用

我们已将此库的论文正式发表，如果你使用了 🤗 Transformers 库，请引用:

@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://www.aclweb.org/anthology/2020.emnlp-demos.6",
    pages = "38--45"
}