Transformers：Hugging Face 模型库快速入门指南

huggingface/transformers 是 Hugging Face 维护的开源模型定义框架，实时 Star 数约 168.2k，是整个大模型生态事实上的「模型定义中心」。本文基于官方 README 完整翻译整理，从项目定位、安装方式、Pipeline 快速上手、多模态示例、适用边界到引用方式逐一说明。

Transformers 把文本、计算机视觉、音频、视频与多模态 SOTA 模型的定义集中到一处，让整个生态共用同一份模型定义。它是跨框架的枢纽：只要一个模型定义被 Transformers 支持，就能兼容绝大多数训练框架（Axolotl、Unsloth、DeepSpeed、FSDP、PyTorch-Lightning 等）、推理引擎（vLLM、SGLang、TGI 等）以及相邻建模库（llama.cpp、mlx 等）。Hugging Face Hub 上已有超过 100 万个 Transformers 模型权重可供直接下载使用。

对国内开发者来说，Transformers 几乎是绕不开的依赖：不管你是用 Unsloth 微调、用 vLLM 部署、还是用 llama.cpp 跑 GGUF，底座那一层模型权重格式都来自 Transformers 的定义。理解它的安装、Pipeline 用法与边界，等于拿到了进入大模型工程化的门票。

从生态位看，Transformers 本身不是一个「训练框架」也不是一个「推理引擎」，而是一层中间的模型定义层。它的价值在于统一：同一个模型权重文件，可以被训练框架读去做微调，被 vLLM 读去做高并发推理，被 llama.cpp 读去跑在笔记本上。这种统一避免了每个模型都要为每个框架单独适配一遍，也是 Hugging Face 能在短短几年内把模型数量推到 100 万+ 的根本原因。

官方承诺持续帮助新 SOTA 模型落地，并通过让模型定义保持简单、可定制、高效来降低使用门槛。这也是为什么几乎所有新发布的开源大模型（Qwen、Llama、Gemma、DeepSeek 等）都会第一时间出现在 Hugging Face Hub 上，并以 Transformers 兼容格式发布——不这么做就等于主动放弃主流生态。

从用户角度看，Transformers 解决的是「模型太多、太散、太不好用」的问题。在它出现之前，每个模型都有自己的代码仓库、自己的加载方式、自己的 tokenizer，你要为每个模型学一套新 API。Transformers 把这些全部统一成一套接口：同一个 Pipeline 类，传不同模型名就能跑不同模型；同一个 AutoModel 类，加载不同架构的权重。这种统一是它能成为生态基础设施的核心原因，也是 Hugging Face 从一个小公司成长为大模型时代标准制定者的关键一步。

一、项目官方信息

二、官方图片

封面取 GitHub 仓库官方图，本文不重复贴图。官方 Logo 见 文档素材库，暗色与亮色主题各一版。

三、环境要求

Transformers 要求 Python 3.11+ 与 PyTorch 2.6+。官方推荐先用 venv 或基于 Rust 的快速包管理器 uv 创建独立虚拟环境，避免与系统包冲突。训练类任务建议 NVIDIA GPU 并装好 CUDA 版 PyTorch；纯推理也可以在 CPU 或 Apple Silicon 上运行，但速度差距明显。国内用户建议配置 Hugging Face 镜像端点（如 HF_ENDPOINT 环境变量指向国内镜像），否则首次下载 100 万级模型权重时会卡在网络上。

硬件方面，跑 7B 级模型推理建议 16GB 显存，跑 7B 级 LoRA 微调建议 24GB 显存，跑 70B 级推理建议 80GB 显存或多卡；只跑 1.5B 级小模型，8GB 显存甚至纯 CPU 也能跑通 Pipeline。磁盘方面，一个 7B 模型权重约 14GB（FP16），70B 约 140GB，建议预留至少 100GB 给 Hugging Face 缓存目录。

操作系统上，Linux 是首选，Windows 和 macOS 也支持但部分高级功能（如多卡训练、自定义 CUDA 算子）在 Linux 上最稳定。如果你是第一次用 Hugging Face 生态，建议在 Ubuntu 22.04 上操作，能避免绝大多数环境坑。Windows 用户则建议用 WSL2，原生 Windows 支持虽然有但偶尔会有 CUDA 相关小问题。

四、完整部署步骤

1. 创建虚拟环境

venv 方式：

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

uv 方式（更快，官方推荐）：

uv venv .my-env
source .my-env/bin/activate

2. 安装 Transformers

pip 方式：

pip install "transformers[torch]"

uv 方式：

uv pip install "transformers[torch]"

这里的 [torch] 是可选依赖标记，会顺带安装 PyTorch 后端；如果已经装好 PyTorch，直接 pip install transformers 即可。如果需要 TensorFlow 或 JAX 后端，把 [torch] 换成 [tf] 或 [flax]。

安装完成后，建议先跑一个最小 Pipeline 验证环境是否正常，比如用 Qwen/Qwen2.5-0.5B 跑一次文本生成，能正常出结果就说明 Python 版本、PyTorch 版本、网络都没问题。第一次运行会自动下载模型权重，国内用户如果没配镜像，这一步可能需要耐心等待或挂代理。

从源码安装的好处是可以拿到 main 分支的最新改动，包括刚合并的模型支持和 bug 修复；坏处是 main 分支可能不稳定，偶尔会有未完全测试通过的代码。如果是做生产环境，建议用 PyPI 发布版；如果是做研究或想第一时间用新模型，再从源码安装。

3. 从源码安装

想拿最新改动或参与贡献时，从源码安装（注意最新版不一定稳定，遇到错误可以提 issue）：

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

# pip
pip install '.[torch]'

# uv
uv pip install '.[torch]'

五、使用方法

1. 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 ")

对话示例（构造 chat 历史即可，用法和文本生成完全一致，只是输入换成多轮 messages）：

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"])

也可以直接在命令行和模型聊天（前提是 transformers serve 已启动，见 服务化文档）：

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

Pipeline 的好处是「开箱即用」：你不需要手写 tokenizer 调用、不需要手写 tensor 搬运、不需要手写后处理，只要告诉它任务类型和模型名，剩下的它全帮你做了。坏处是灵活性有限——当你要做自定义训练循环、要改模型内部结构、要做张量并行时，Pipeline 就不够用了，需要直接用 AutoModelForCausalLM、AutoTokenizer 这些底层类。这也是为什么官方说「用户侧抽象只有三个类」：Pipeline 是给新手的，AutoModel/AutoTokenizer 是给进阶用户的。

2. 多模态任务示例

自动语音识别（Whisper 大模型）：

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")

图像分类（DINOv2）：

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")

视觉问答（BLIP-VQA，输入一张图加一个问题）：

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?",
)

这三个例子覆盖了 Pipeline 的典型用法：传一个文件路径或 URL，Pipeline 自动完成加载、预处理、推理、后处理。实际生产中，你可以把模型名换成 Hub 上任何兼容的模型，比如把 Qwen/Qwen2.5-1.5B 换成 Qwen/Qwen2.5-7B-Instruct，把 openai/whisper-large-v3 换成更小的 openai/whisper-large-v3-turbo，Pipeline 接口完全不用改。

3. 为什么选择 Transformers

官方 README 给出四点理由：

1. 易用的 SOTA 模型：在自然语言理解与生成、计算机视觉、音频、视频与多模态任务上性能领先；研究者、工程师、开发者入门门槛低；用户侧抽象只有三个类，统一 API 调用所有预训练模型。对新手来说，从 pip install 到跑通第一个推理只需要十分钟。
2. 更低算力成本与更小碳足迹：共享已训练模型，避免从头训练；跨模态有数百种模型架构、100 万+ 预训练权重，直接下载即可。这意味着你不需要自己买 8 张 A100 训练一个通用大模型，只需要下载一个别人已经训好的，在自己的小数据集上微调几小时。
3. 为模型生命周期各阶段选对框架：三行代码训练 SOTA 模型；同一模型可在 PyTorch、JAX、TF2.0 之间随意切换；训练、评估、生产各环节挑合适的框架。比如研究阶段用 PyTorch 快速实验，生产阶段切到 JAX 做大规模部署，模型权重格式不变。
4. 易于定制：每个架构都有复现原作者结果的示例；模型内部尽可能暴露；模型文件可脱离库单独用于快速实验。你可以把 Transformers 当成一个「模型字典」，需要哪个模型就拿哪个，不需要把整个库都吃进去。

4. 项目结构

Transformers 主仓库包含：模型实现目录 src/transformers/models/（每个模型架构一个子目录）、Pipeline 高层接口、训练 Trainer API、各种工具类与测试。文档站独立维护在 huggingface.co/docs/transformers。多语言 README 放在 i18n/ 目录下，社区项目榜放在 awesome-transformers.md。

六、FAQ 与适用边界

官方也明确说明什么时候不应该用 Transformers：

• 它不是神经网络积木式工具箱。模型文件里的代码有意不做额外抽象，目的是让研究者能直接在每个模型上快速迭代，而不是钻到额外的抽象层里。如果你想从零搭一个自己的神经网络结构，Transformers 帮不上忙，它是用现成模型的，不是造新模型的。
• 训练 API 是为 Transformers 自带的 PyTorch 模型优化的；通用机器学习循环请改用 Accelerate 等库。如果你要写一个完全自定义的训练流程，比如自己组装神经网络、自己写损失函数、自己做数据加载，那 Transformers 的 Trainer 反而会变成束缚。
• 它也不是推理引擎。Transformers 跑推理是研究级的，不是生产级的；生产高并发推理请用 vLLM、SGLang、TGI 这些专门的推理引擎，它们也是读 Transformers 的模型定义。

常见问题：

• 去哪里找模型？ 直接在 Hugging Face Hub 按趋势浏览，或在模型页面直接在线试玩，不用下载就能看效果。
• 想知道哪些项目基于 Transformers 构建？ 见 awesome-transformers 页面，列了 100 个社区项目，欢迎提 PR 补充——这个榜单是为了庆祝 Transformers 突破 10 万 Star 而建的。
• 企业版支持？ Hugging Face 提供 Enterprise Hub 企业方案，含 SLA、私有模型与审计。
• 为什么不直接用 PyTorch？ PyTorch 是通用张量计算框架，Transformers 是在 PyTorch 之上封装好的模型库。前者给你造轮子的自由，后者给你造好的轮子。做科研想改模型结构用 PyTorch，做应用想直接用现成模型用 Transformers。
• 训练和推理是同一个 API 吗？ 不是。Pipeline 是推理 API；训练要用 Trainer API 或 Accelerate 自己写循环。两者共用同一套模型定义，但入口不同。
• 支持哪些模型框架切换？ 官方 README 明确支持在 PyTorch、JAX、TF2.0 之间迁移同一模型权重，这对需要在不同团队之间共享模型的企业特别有用。
• 遇到 bug 去哪反馈？ 仓库 Issues 区，官方响应速度在开源社区里算快的。
• 怎么参与贡献？ 官方 README 欢迎提 PR 把自己的项目加进 awesome-transformers 榜单，也欢迎直接提代码修复。贡献指南在仓库里的 CONTRIBUTING 文档。
• 和 Hugging Face Hub 是什么关系？ Transformers 是库，Hub 是模型托管平台。库负责加载和运行模型，Hub 负责存储和分发模型权重。两者配套使用，从 Hub 下载权重，用 Transformers 加载运行。
• 国产模型支持得怎么样？ 很好，Qwen、GLM、DeepSeek、Yi 等主流国产模型都有官方维护的 Transformers 兼容权重，直接在 Hub 上搜名字就能用，而且更新速度很快。
• 文档看不懂怎么办？ 官方文档站有完整的教程、API 参考和示例，也有简体中文 README 可以对照阅读。
• 支持哪些模态和代表模型？ 音频侧有音频分类 CLAP、语音识别 Parakeet、Whisper、GLM-ASR、流式识别 Moonshine-Streaming、关键词检测 Wav2Vec2、语音对语音生成 Moshi、文本到音频 MusicGen、TTS CSM；视觉侧有自动分割 SAM、深度估计 DepthPro、图像分类 DINO v2、关键点检测 SuperPoint、关键点匹配 SuperGlue、目标检测 RT-DETRv2、姿态估计 VitPose、通用分割 OneFormer、视频分类 VideoMAE；多模态侧有语音/文本到文本 Voxtral、文档问答 LayoutLMv3、图像/文本到文本 Qwen-VL、图像描述 BLIP-2、文档理解 GOT-OCR2、表格问答 TAPAS、统一多模态理解与生成 Emu3、视觉到文本 Llava-OneVision、视觉问答 Llava、视觉指代分割 Kosmos-2；NLP 侧有掩码填词 ModernBERT、命名实体识别 Gemma、问答 Mixtral、摘要 BART、翻译 T5、文本生成 Llama、文本分类 Qwen。

七、跳转链接

本文所有命令与版本号均与官方 README 一致，Python 3.11+、PyTorch 2.6+ 为官方明确要求，不做任何臆造。更多入口：

• 官方网站：huggingface.co
• 完整文档：huggingface.co/docs/transformers
• GitHub 仓库：huggingface/transformers
• 模型中心：Hugging Face Hub
• 简体中文 README：i18n/README_zh-hans.md
• 社区项目榜：awesome-transformers
• 企业方案：Hugging Face Enterprise

引用方式：

@inproceedings{wolf-etal-2020-transformers,
    title = "Transformers: State-of-the-Art Natural Language Processing",
    author = "Thomas Wolf and Lysandre Debut and Victor Sanh and others",
    booktitle = "Proceedings of the 2020 Conference on Empirical Methods in Natural Language Processing: System Demonstrations",
    year = "2020",
    publisher = "Association for Computational Linguistics",
    url = "https://aclanthology.org/2020.emnlp-demos.6/",
    pages = "38--45"
}