HuggingFace Transformers 快速入门

HuggingFace Transformers 把”加载预训练大模型、做推理、做微调”压缩到了几行代码——它是当今 NLP 与多模态模型的事实标准入口。本页带你从一行推理到完整微调流程。前置阅读：PyTorch 入门指南、Transformer 架构。

这个库是什么

Transformers 是 HuggingFace 公司（公司名为 Hugging Face）2019 年开源的 Python 库，最初为统一封装各类 Transformer 模型而生，如今已支持数以十万计的预训练模型，覆盖文本、图像、音频、多模态。它的底层依赖 PyTorch 或 TensorFlow，但用一套统一的高层 API 把”下载模型、分词、推理、微调”全部封装好。

核心价值在于模型中心（Model Hub）：全球研究者和机构（Meta、Google、Stability AI、阿里等）把训练好的模型上传到 Hub，任何人用一行 from_pretrained() 就能下载使用。打个比方，Transformers 之于大模型，就像 App Store 之于手机应用——你不必自己从头训练，下载现成的就能用。与之配套的还有 Datasets（数据集中心）和 Tokenizers（高性能分词器），共同构成”AI 界的 GitHub”。

截至 2026 年，Hub 上已有超过 100 万 个模型 checkpoint，覆盖 NLP、计算机视觉、音频、视频、多模态等全部主流方向。Transformers 本身也已成为模型定义的跨框架枢纽——如果一种模型架构被 Transformers 支持，那么它就能自动兼容主流训练框架（Axolotl、Unsloth、DeepSpeed、FSDP）、推理引擎（vLLM、SGLang、TGI）以及本地化部署工具（llama.cpp、MLX）。

2025-2026 生态演进

Transformers 在 2025-2026 年经历了几个重要里程碑：

版本 5.x 大版本：引入了全新的 Kernels 子系统（高性能算子库），通过 pip install kernels 一键获得 Flash Attention、DeepGEMM 等 GPU 优化算子。SDPA（Scaled Dot-Product Attention，缩放点积注意力）预填充阶段结合 StaticCache 可获得高达 260% 的加速。
Multi-Token Prediction（MTP）解码：支持一次预测多个 token 的推测解码，显著提升生成速度。
FP8/FP4 量化支持：通过 DeepGEMM 实现 GPU 上的低精度推理，在保持精度的同时大幅降低显存占用。
Continuous Batching（连续批处理）：内置连续批处理管理器，支持高吞吐量推理服务场景。
FSDP2 原生支持：完全分布式数据并行 2.0，配合 from_pretrained 初始化，简化多卡训练。
新模型持续涌入：2025-2026 年新增了 Gemma 4（多模态统一模型）、DeepSeek-V3.2（稀疏注意力 MoE）、KimiK 2.5-2.7（多模态 Agent 模型）、ModernBERT（现代化的 BERT 架构）、Qwen3 系列、Inkling（975B 参数多模态模型）等数十种新架构。

安装与环境配置

# 方式一：pip 安装（默认 PyTorch 后端）
pip install transformers

# 方式二：随 NLP 全套安装
pip install transformers datasets tokenizers accelerate

# 方式三：安装含 PyTorch 依赖的完整版（推荐，v5.x 起官方推荐写法）
pip install "transformers[torch]"

# 方式四：使用 uv（Rust 编写的快速包管理器，v5.x 起官方推荐）
uv pip install "transformers[torch]"

# 可选：安装高性能算子库（Flash Attention、DeepGEMM 等）
pip install kernels

# 验证安装
python -c "import transformers; print(transformers.__version__)"

版本要求：Transformers v5.x 要求 Python 3.10+ 和 PyTorch 2.4+。请确保你的环境满足最低版本要求。

Transformers 默认使用 PyTorch 后端；想用 TensorFlow 需额外 pip install tensorflow。下载模型默认缓存在 ~/.cache/huggingface/，体积较大，磁盘要留足空间。国内网络访问 Model Hub 可能较慢，可设置环境变量 HF_ENDPOINT=https://hf-mirror.com 走镜像。导入约定写为 import transformers。

核心概念

pipeline：一行代码完成推理

pipeline() 是最高层封装——你只需指明任务类型（如 “text-classification”、“translation”），它会自动加载一个合适的预训练模型、配套的分词器、后处理逻辑，把”输入文本 → 预测结果”压缩成一行调用。这是上手最快的入口，适合快速验证想法或做原型。

从 v5.x 开始，pipeline 还支持多模态任务和对话格式输入——你可以直接传入 messages 格式的聊天历史来获取对话回复。

AutoModel 与 AutoTokenizer：按名加载

AutoModel 和 AutoTokenizer 是”智能适配器”：你给一个模型名（如 “bert-base-chinese”），它会自动判断模型架构、下载权重、实例化对应的类。不必关心该用 BertModel 还是 RobertaModel——Auto 系列”猜”出来。这种设计让同一套代码能无缝切换几十种模型架构。

预训练模型加载与复用

所有模型都通过 from_pretrained("模型名") 加载：参数可以是一个 Hub 上的名字（自动联网下载），也可以是本地目录路径（离线加载）。模型权重默认以 safetensors 格式存储（一种安全的序列化格式，防止反序列化攻击——即攻击者无法通过构造恶意权重文件来执行任意代码）。

从 v5.x 开始，from_pretrained 还支持 FSDP2 初始化——在多卡环境下直接以分布式方式加载模型，避免单卡显存不足的问题。

Trainer：标准化的微调框架

Trainer 把”训练循环”封装成对象——你传入模型、数据集、训练参数（TrainingArguments），调用 trainer.train() 就能开始微调，自动处理批次、梯度、日志、检查点、评估。它替代了手写 PyTorch 训练循环的繁琐，且支持混合精度、分布式、FSDP 等高级特性。

Kernels：高性能算子库（v5.x 新增）

Transformers v5.x 引入了独立的 kernels 包，封装了 Flash Attention、DeepGEMM（FP8/FP4 矩阵乘法）等 GPU 优化算子。安装后，Transformers 会自动检测并使用这些高性能实现，无需修改任何代码。这对大模型推理和训练的加速效果非常显著。

架构与工作流

动手实践

例 1：pipeline 一行完成文本推理

from transformers import pipeline

# 一行创建情感分析器：自动下载默认的英文情感模型
classifier = pipeline("sentiment-analysis")
results = classifier(["I love this library!", "This is terrible."])
print(results)
# [{'label':'POSITIVE','score':0.99}, {'label':'NEGATIVE','score':0.99}]

# 换成中文情感或文本分类，指定模型名即可
zh_clf = pipeline("sentiment-analysis", model="uer/roberta-base-finetuned-jd-binary-chinese")
print(zh_clf("这本书写得太好了，强烈推荐！"))

例 2：对话生成——与 LLM 对话（v5.x 对话格式）

import torch
from transformers import pipeline

# 使用 pipeline 进行对话生成（v5.x 推荐的对话格式）
chat = [
    {"role": "system", "content": "你是一个友善的 AI 助手。"},
    {"role": "user", "content": "请用一句话解释什么是 Transformer 架构。"}
]

# 指定模型、数据类型和设备映射
# dtype=torch.bfloat16：使用 bfloat16 精度（节省显存，现代 GPU 原生支持）
# device_map="auto"：自动将模型分布到可用的 GPU/CPU 上
pipe = pipeline(
    task="text-generation",
    model="Qwen/Qwen2.5-1.5B",
    dtype=torch.bfloat16,
    device_map="auto",
)
response = pipe(chat, max_new_tokens=128)
print(response[0]["generated_text"][-1]["content"])

也可以用命令行直接对话：transformers chat Qwen/Qwen2.5-0.5B-Instruct——v5.x 新增的 CLI 命令，无需写 Python 代码即可与模型交互。

例 3：手动加载 Tokenizer 与模型做推理

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

model_name = "uer/roberta-base-finetuned-jd-binary-chinese"
# 分别加载分词器与模型（Auto 系列自动适配架构）
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)

# 分词：文本转成模型能吃的数字 ID 张量
# 分词器的工作：把 "电池续航很差" → [电, 池, 续, 航, ...] → [1234, 5678, ...]
text = "电池续航很差，不推荐购买。"
inputs = tokenizer(text, return_tensors="pt")        # pt 表示返回 PyTorch 张量
print(inputs["input_ids"])                            # 查看编码结果

# 前向推理
with torch.no_grad():                                 # 推理时关闭梯度计算，节省显存
    logits = model(**inputs).logits                   # logits 是未归一化的分数
pred = torch.argmax(logits, dim=1).item()             # 取分数最高的类别
print(f"预测类别: {pred}")    # 负面对应的类别 ID

例 4：多模态 pipeline——图像分类与语音识别

Transformers 的 pipeline 不仅限于文本，还支持图像、音频和多模态任务：

from transformers import pipeline

# === 图像分类 ===
# 自动下载视觉模型，输入图片 URL 即可分类
img_clf = pipeline(
    task="image-classification",
    model="facebook/dinov2-small-imagenet1k-1-layer"
)
result = img_clf("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")
print(result[:3])  # Top-3 预测结果

# === 语音识别（ASR）===
# Whisper 模型支持多语言语音转文字
asr = pipeline(
    task="automatic-speech-recognition",
    model="openai/whisper-large-v3"
)
text = asr("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")
print(text["text"])
# " I have a dream that one day this nation will rise up..."

例 5：用 Trainer 微调文本分类模型

from transformers import (
    AutoTokenizer, AutoModelForSequenceClassification,
    Trainer, TrainingArguments,
)
from datasets import Dataset

# 准备一个小型中文情感数据集（实际项目用 datasets.load_dataset）
data = {"text": ["这本书很棒", "质量太差了", "非常喜欢", "太失望了",
                 "强烈推荐", "浪费钱", "物超所值", "再也不买了"],
        "label": [1, 0, 1, 0, 1, 0, 1, 0]}
dataset = Dataset.from_dict(data)

model_name = "bert-base-chinese"
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 分词预处理：把文本批量转成 ID
def tokenize(batch):
    return tokenizer(batch["text"], padding="max_length", truncation=True, max_length=32)
dataset = dataset.map(tokenize, batched=True)

# 加载模型（num_labels 指定类别数）
model = AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)

# 训练参数：轮数、批次、学习率、日志
# v5.x TrainingArguments 支持更多分布式选项（FSDP、DeepSpeed 等）
args = TrainingArguments(
    output_dir="./clf-out",
    num_train_epochs=3,
    per_device_train_batch_size=2,
    learning_rate=2e-5,
    logging_steps=2,
    # 以下为 v5.x 可选的高级参数：
    # fp16=True,                    # 混合精度训练，加速并省显存
    # save_strategy="epoch",        # 每个 epoch 保存检查点
    # report_to="none",             # 关闭 WandB 等实验跟踪
)

# Trainer 接管训练循环
trainer = Trainer(
    model=model, args=args, train_dataset=dataset,
    processing_class=tokenizer,  # v5.x 中 tokenizer 参数更名为 processing_class
)
trainer.train()
print("微调完成")

注意：v5.x 中 Trainer 的 tokenizer 参数已更名为 processing_class，以反映它不仅处理文本分词，还处理图像处理器（Image Processor）、音频处理器等多模态输入。旧代码中的 tokenizer= 仍可用但会触发弃用警告。

常用 API 速查

API	用途	示例
`pipeline(task)`	一行推理管道	`pipeline("text-classification")`
`pipeline(task, model=name)`	指定模型的管道	`pipeline("ner", model="bert-base")`
`AutoTokenizer.from_pretrained(name)`	加载分词器	`AutoTokenizer.from_pretrained("bert-base-chinese")`
`AutoModel.from_pretrained(name)`	加载通用模型	`AutoModel.from_pretrained("bert-base")`
`AutoModelForSequenceClassification`	加载分类模型	`.from_pretrained(name, num_labels=3)`
`AutoModelForCausalLM`	加载生成模型	`AutoModelForCausalLM.from_pretrained("gpt2")`
`AutoModelForVision2Seq`	加载图像描述模型	`AutoModelForVision2Seq.from_pretrained("nlpconnect/vit-gpt2")`
`AutoModelForSpeechSeq2Seq`	加载语音识别模型	`AutoModelForSpeechSeq2Seq.from_pretrained("openai/whisper")`
`tokenizer(text)`	文本编码	`tokenizer("你好", return_tensors="pt")`
`model.generate(...)`	文本生成	`model.generate(inputs, max_new_tokens=50)`
`Trainer(...)`	训练微调器	`Trainer(model=m, args=a, train_dataset=d)`
`model.push_to_hub(name)`	上传模型到 Hub	`model.push_to_hub("my-model")`
`datasets.load_dataset(name)`	加载数据集	`load_dataset("imdb")`

常见 pipeline 任务类型速记：

pipeline 类型	用途	示例任务
`text-classification`	文本分类	情感分析、意图识别
`token-classification`	序列标注	命名实体识别（NER）
`text-generation`	文本生成	续写、对话
`summarization`	文本摘要	长文压缩
`translation`	机器翻译	中英互译
`question-answering`	问答	抽取式问答
`zero-shot-classification`	零样本分类	无需训练的分类
`image-classification`	图像分类	识别图片中的物体
`automatic-speech-recognition`	语音识别	音频转文字
`visual-question-answering`	视觉问答	看图回答问题
`image-to-text`	图像描述	为图片生成文字说明

实践要点

先 pipeline 再手写：任何新任务都先用 pipeline() 跑通基线，确认任务可行后再深入到分词器与模型细节。避免一开始就陷入底层。
显存是最大瓶颈：加载大模型前先看清楚参数量，7B 模型用 float16 至少需 14GB 显存。显存不足时考虑量化加载（load_in_4bit、load_in_8bit）、CPU 推理，或用更小模型。v5.x 还可通过安装 kernels 包启用 FP8 量化推理，进一步压缩显存。详见LLM 推理优化。
分词器与模型必须配套：用 BERT 的分词器去喂 GPT 的模型会直接报错。务必让 tokenizer 和 model 来自同一个 model_name，或显式确认它们的词表一致。详见分词器。
微调时锁住部分层：大模型全量微调显存吃紧。可冻结底层（for p in model.parameters(): p.requires_grad = False），只训练顶层分类器；或用 LoRA/PEFT 只训练少量适配参数（LoRA 是一种高效微调方法，只在原模型旁添加少量可训练的低秩矩阵）。详见LLM 微调。
小心 padding 与 truncation：批处理时序列长度不一，必须 padding=True；过长则 truncation=True 截断，否则报错。
上传模型前清理检查点：训练产生的 checkpoint 目录可能很大，上传 Hub 前确认只保留必要文件，并写好 Model Card（README）说明用途。
善用 dtype 参数：v5.x 起，from_pretrained 和 pipeline 都支持 dtype 参数（如 torch.bfloat16、torch.float16），建议在支持的 GPU 上使用 bfloat16——它拥有与 float32 相同的指数范围（不易溢出），但精度减半，显存节省一半。

典型应用场景

加载与使用大语言模型：LLaMA、Qwen、ChatGLM 等开源 LLM 几乎都首发在 HuggingFace，用 Transformers 即可加载推理。2025-2026 年热门的 DeepSeek-V3.2（稀疏注意力 MoE 架构）、Gemma 4（多模态统一模型）也都第一时间获得支持。详见语言模型演进。
文本分类与情感分析：客服工单分类、评论情感监测，微调一个 BERT 即可上线。详见Transformer 架构。
命名实体识别（NER）：从合同、简历中抽取人名、地名、机构名，token-classification 流水线开箱即用。
文档摘要与翻译：BART、T5、mBART 等序列到序列模型（Encoder-Decoder 架构，先编码再解码），用 summarization / translation 流水线调用。
多模态理解：BLIP-2、LLaVA、Qwen-VL 等视觉语言模型（Vision-Language Model，能同时理解图像和文本的模型），支持图像描述、视觉问答、OCR 文档理解等任务。
语音识别与处理：Whisper 系列模型支持 90+ 语言的语音转文字；Qwen3-ASR、Nemotron ASR 等 2025-2026 年新增模型还支持实时流式识别。
嵌入与向量检索：用 sentence-transformers 系列（基于 Transformers）生成文本向量，支撑 RAG 系统。详见嵌入模型与RAG 检索增强生成。

与同类工具对比

特性	HuggingFace Transformers	原生 PyTorch	LlamaIndex / LangChain
定位	预训练模型加载与微调	通用深度学习框架	LLM 应用编排
模型获取	Model Hub 一行下载	需手动实现或下载	调用各种 LLM API
微调支持	Trainer 标准化	需手写训练循环	弱（侧重应用层）
多后端	PyTorch / TensorFlow / JAX	仅 PyTorch	框架无关
高性能算子	Kernels 子系统（Flash Attn 等）	需手动集成	不涉及
抽象层次	模型层	计算层	应用层
最佳场景	加载 / 推理 / 微调模型	研究与自定义模型	构建 LLM 应用

关键洞察：Transformers 专注”模型层”——加载、推理、微调；LangChain/LlamaIndex 在其之上专注”应用层”——编排 RAG、Agent。两者是上下游关系，实际项目常组合使用。底层训练原理是 PyTorch，详见PyTorch 入门指南。HuggingFace 的完整生态概览详见HuggingFace 生态。