HuggingFace Transformers 完全指南

官方文档：https://huggingface.co/docs/transformers/
适用版本：5.8.0（2026-05-07 核实）

概述

HuggingFace Transformers 是目前最主流的预训练模型工具库，提供数千个在 Hugging Face Hub 上发布的预训练模型，覆盖 NLP、计算机视觉、语音、多模态等任务。它的核心价值在于：一套统一 API 驯服从 BERT 到 LLaMA 的所有主流架构，无需了解每种架构的内部细节。

对比主要替代方案：

• OpenAI Python SDK：只能调用 OpenAI 闭源模型，无法在本地运行开源模型
• sentence-transformers：专注于 Embedding，不覆盖生成、分类等宽泛任务
• LiteLLM：聚合各厂商 API，依赖外部服务，不支持本地推理

适合场景：需要在本地运行开源模型（Llama、Mistral、Qwen）、Fine-tuning 已有模型、使用 BERT 类模型做文本分类 / NER / 问答。不适合场景：只需调用 GPT-4 等闭源 API（用 OpenAI SDK 更简单）。

安装

pip install transformers torch          # CPU / CUDA
pip install transformers torch --index-url https://download.pytorch.org/whl/cu118  # CUDA 11.8
pip install accelerate datasets         # 训练与数据处理
pip install bitsandbytes                # 4/8-bit 量化

pipeline — 一行完成推理

pipeline() 是 Transformers 最简洁的推理接口，屏蔽了 tokenize → forward → decode 的细节。

pipeline()

transformers.pipeline(
    task: str,
    model: str | PreTrainedModel = None,
    config: str | PreTrainedConfig = None,
    tokenizer: str | PreTrainedTokenizer = None,
    feature_extractor: str | FeatureExtractionMixin = None,
    image_processor: str | BaseImageProcessor = None,
    processor: str | ProcessorMixin = None,
    revision: str = "main",
    use_fast: bool = True,
    token: str | bool = None,
    device: int | str | torch.device = None,
    device_map: str | dict = None,
    dtype: str | torch.dtype = None,
    trust_remote_code: bool = False,
    model_kwargs: dict[str, Any] = None,
    **kwargs
) -> Pipeline

支持的任务字符串

语音（Audio）

计算机视觉（Vision）

自然语言处理（NLP）

示例

from transformers import pipeline

# 最小示例：情感分析
clf = pipeline("sentiment-analysis")
result = clf("This movie is fantastic!")
# [{'label': 'POSITIVE', 'score': 0.9998}]

# 指定模型 + GPU + 半精度
gen = pipeline(
    "text-generation",
    model="meta-llama/Llama-3.2-1B-Instruct",
    device=0,
    dtype="auto",
    token=True,               # 需要 HF 访问 token
    trust_remote_code=True,
)
output = gen("Once upon a time", max_new_tokens=100)

# 批量处理（传入列表）
ner = pipeline("ner", model="dslim/bert-base-NER")
results = ner(["Alice lives in Paris", "Bob works at Google"])

# 语音识别
asr = pipeline("automatic-speech-recognition", model="openai/whisper-base")
transcription = asr("audio.wav")
# {'text': '...'}

# 零样本分类（不需要重新训练）
classifier = pipeline("zero-shot-classification")
classifier(
    "I need to cancel my subscription",
    candidate_labels=["billing", "technical support", "account management"],
)

Auto 类 — 自动加载模型与分词器

Auto 类根据模型名称或本地路径自动选择正确的架构类，是加载预训练模型的推荐方式。

AutoTokenizer.from_pretrained()

AutoTokenizer.from_pretrained(pretrained_model_name_or_path, **kwargs)

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-uncased")

# 编码文本
inputs = tokenizer("Hello, world!", return_tensors="pt")
# {'input_ids': tensor(...), 'attention_mask': tensor(...)}

# 批量编码（自动 padding）
inputs = tokenizer(
    ["Hello world", "How are you?"],
    padding=True,
    truncation=True,
    max_length=128,
    return_tensors="pt",
)

# 保存到本地（用于离线部署）
tokenizer.save_pretrained("./my_tokenizer")

AutoModel.from_pretrained()

AutoModel.from_pretrained(pretrained_model_name_or_path, **kwargs)

from transformers import AutoModel, AutoModelForSequenceClassification, AutoModelForCausalLM
import torch

# 加载编码器（BERT 类）
model = AutoModel.from_pretrained("google-bert/bert-base-uncased")

# 分类任务：编码器 + 分类头
clf_model = AutoModelForSequenceClassification.from_pretrained(
    "distilbert-base-uncased-finetuned-sst-2-english"
)

# 生成任务：解码器（LLM）
llm = AutoModelForCausalLM.from_pretrained(
    "microsoft/phi-2",
    torch_dtype=torch.float16,
    device_map="auto",          # 自动多 GPU 分片
    low_cpu_mem_usage=True,
)

# 4-bit 量化（减少 ~75% 显存）
llm_4bit = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-8B-Instruct",
    load_in_4bit=True,
    device_map="auto",
    token=True,
)

# 保存模型
model.save_pretrained("./saved_model")

常用 AutoModel 子类

Tokenizer 核心方法

编码与解码

tokenizer = AutoTokenizer.from_pretrained("google-bert/bert-base-uncased")

# 编码：文本 → token id
encoding = tokenizer(
    "Hello, world!",
    add_special_tokens=True,   # 添加 [CLS] / [SEP] 等特殊 token
    max_length=128,
    padding="max_length",      # 填充到最大长度
    truncation=True,           # 超出截断
    return_attention_mask=True,
    return_tensors="pt",       # 返回 torch.Tensor
)
# encoding.input_ids, encoding.attention_mask, encoding.token_type_ids

# 批量编码（自动对齐 padding）
batch = tokenizer(
    ["sentence one", "sentence two"],
    padding=True,              # 同批次内对齐
    truncation=True,
    return_tensors="pt",
)

# 解码：token id → 文本
ids = [101, 7592, 1010, 2088, 999, 102]
text = tokenizer.decode(ids, skip_special_tokens=True)
# "hello , world !"

# 批量解码
texts = tokenizer.batch_decode(batch.input_ids, skip_special_tokens=True)

推理流程（手动）

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

model_name = "distilbert-base-uncased-finetuned-sst-2-english"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForSequenceClassification.from_pretrained(model_name)
model.eval()

texts = ["I love this movie!", "This was a waste of time."]
inputs = tokenizer(texts, padding=True, truncation=True, return_tensors="pt")

with torch.no_grad():
    outputs = model(**inputs)

# outputs.logits: shape [batch_size, num_labels]
probs = torch.softmax(outputs.logits, dim=-1)
labels = model.config.id2label

for i, prob in enumerate(probs):
    pred = labels[prob.argmax().item()]
    print(f"{texts[i]!r}: {pred} ({prob.max():.4f})")

文本生成

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "microsoft/phi-2"
tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.float16, device_map="auto")

inputs = tokenizer("Explain quantum computing in simple terms:", return_tensors="pt").to(model.device)

# generate() 核心参数
outputs = model.generate(
    **inputs,
    max_new_tokens=200,       # 最多新生成 200 个 token
    temperature=0.7,          # 采样温度；越高越随机，越低越确定
    top_p=0.9,                # nucleus sampling；累计概率阈值
    top_k=50,                 # top-k 采样
    do_sample=True,           # 开启采样（否则贪心解码）
    repetition_penalty=1.1,   # 惩罚重复 token
    pad_token_id=tokenizer.eos_token_id,
)

# 解码时只保留新生成的 token
new_tokens = outputs[0][inputs.input_ids.shape[1]:]
print(tokenizer.decode(new_tokens, skip_special_tokens=True))

generate() 主要参数

Trainer — Fine-tuning 训练器

Trainer 封装了训练循环、梯度累积、混合精度、分布式训练等，是 Fine-tuning 的标准工具。

TrainingArguments

from transformers import TrainingArguments

args = TrainingArguments(
    output_dir="./results",              # 检查点保存路径
    num_train_epochs=3,
    per_device_train_batch_size=16,      # 每张 GPU 的批次大小
    per_device_eval_batch_size=64,
    warmup_steps=500,                    # 学习率预热步数
    weight_decay=0.01,                   # L2 正则化系数
    logging_dir="./logs",
    logging_steps=100,
    eval_strategy="epoch",              # 每个 epoch 评估一次
    save_strategy="epoch",
    load_best_model_at_end=True,         # 训练结束加载最优检查点
    fp16=True,                           # 开启混合精度（需要 CUDA）
    dataloader_num_workers=4,
    report_to="tensorboard",
)

Trainer 完整示例

from transformers import (
    AutoTokenizer, AutoModelForSequenceClassification,
    TrainingArguments, Trainer
)
from datasets import load_dataset
import numpy as np
from sklearn.metrics import accuracy_score, f1_score

# 加载数据集
dataset = load_dataset("imdb")
tokenizer = AutoTokenizer.from_pretrained("distilbert-base-uncased")

def tokenize(examples):
    return tokenizer(examples["text"], truncation=True, max_length=512)

tokenized = dataset.map(tokenize, batched=True, remove_columns=["text"])
tokenized = tokenized.rename_column("label", "labels")

# 加载模型
model = AutoModelForSequenceClassification.from_pretrained(
    "distilbert-base-uncased", num_labels=2
)

# 定义评估指标
def compute_metrics(eval_pred):
    logits, labels = eval_pred
    preds = np.argmax(logits, axis=-1)
    return {
        "accuracy": accuracy_score(labels, preds),
        "f1": f1_score(labels, preds, average="weighted"),
    }

training_args = TrainingArguments(
    output_dir="./imdb-distilbert",
    num_train_epochs=3,
    per_device_train_batch_size=32,
    per_device_eval_batch_size=64,
    warmup_ratio=0.1,
    weight_decay=0.01,
    eval_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
    fp16=True,
    report_to="tensorboard",
)

trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=tokenized["train"],
    eval_dataset=tokenized["test"],
    tokenizer=tokenizer,
    compute_metrics=compute_metrics,
)

trainer.train()
trainer.save_model("./best-imdb-distilbert")

模型保存与加载

# 保存（本地）
model.save_pretrained("./my_model")
tokenizer.save_pretrained("./my_model")

# 加载本地
model = AutoModelForSequenceClassification.from_pretrained("./my_model")
tokenizer = AutoTokenizer.from_pretrained("./my_model")

# 推送到 Hub（需要登录）
# huggingface-cli login
model.push_to_hub("my-username/my-model-name")
tokenizer.push_to_hub("my-username/my-model-name")

最佳实践

在生产环境中复用 pipeline 实例：每次调用 pipeline() 都会重新加载模型权重，开销极大。应在应用启动时初始化一次，后续复用同一个实例。

# 正确：全局单例
_clf = None
def get_classifier():
    global _clf
    if _clf is None:
        _clf = pipeline("text-classification", model="...", device=0)
    return _clf

# 错误：每次请求都重新创建
def classify(text):
    clf = pipeline("text-classification")  # 重新加载模型，极慢
    return clf(text)

用 torch.no_grad() 和 model.eval() 推理：不添加这两个上下文时，PyTorch 会构建计算图并保留梯度，推理时浪费约 30% 内存。

model.eval()
with torch.no_grad():
    outputs = model(**inputs)

量化大模型降低显存门槛：70B 参数模型全精度需约 140GB 显存，4-bit 量化后约 35GB，可在单张 A100 80G 上运行。推理精度损失通常在 1–2% 以内。

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.2-70B",
    load_in_4bit=True,
    device_map="auto",
    bnb_4bit_compute_dtype=torch.bfloat16,
)

使用 datasets 库处理大规模数据集：datasets 支持内存映射（Arrow 格式），100GB 数据集无需全量载入内存，配合 .map(batched=True) 并行处理可显著加速预处理。

from datasets import load_dataset

dataset = load_dataset("json", data_files="data.jsonl", split="train")
tokenized = dataset.map(
    lambda x: tokenizer(x["text"], truncation=True),
    batched=True,
    num_proc=4,           # 4 进程并行
    remove_columns=["text"],
)

通过 revision 锁定模型版本：Hub 上的模型权重可能随时更新，生产环境应固定到特定 commit id，避免模型漂移。

model = AutoModel.from_pretrained(
    "google-bert/bert-base-uncased",
    revision="7f56ae30",   # 锁定到具体 commit
)

批量推理优于逐条推理：逐条调用 pipeline 时 GPU 利用率通常不足 10%，传入列表可以触发批量矩阵乘法，吞吐量提升 5–20 倍。

# 正确：批量传入
results = clf(["text1", "text2", "text3", ..., "text64"])

# 低效：逐条处理
results = [clf(text) for text in texts]

常见陷阱

陷阱：设备不一致导致 RuntimeError

现象： RuntimeError: Expected all tensors to be on the same device

原因： 模型在 GPU，但 input tensor 在 CPU；或者反过来。

解决： 调用 .to(model.device) 将输入移到与模型相同的设备。

model = model.to("cuda")
inputs = tokenizer(text, return_tensors="pt")
inputs = {k: v.to(model.device) for k, v in inputs.items()}  # 正确
# inputs = inputs.to("cuda")  # 错误：dict 没有 .to() 方法

陷阱：生成时不设置 pad_token_id

现象： 批量调用 generate() 时警告 Setting pad_token_id to eos_token_id，结果截断或质量下降。

原因： GPT 类模型（LLaMA、Mistral 等）没有 pad_token 设计，批量生成时长度不一致需要 padding。

解决： 显式设置 pad_token_id，并将 tokenizer 的 padding 方向改为左侧。

tokenizer.padding_side = "left"   # 生成任务用左侧 padding
outputs = model.generate(
    **inputs,
    pad_token_id=tokenizer.eos_token_id,
    max_new_tokens=100,
)

陷阱：Fine-tuning 时忘记 num_labels

现象： 训练文本分类时 loss 异常高，模型不收敛。

原因： from_pretrained 时若不指定 num_labels，分类头的输出维度默认为 2（二分类），多分类任务下计算 loss 时维度不匹配。

解决： 加载模型时传入正确的 num_labels。

# 错误：5 分类任务用默认 num_labels=2
model = AutoModelForSequenceClassification.from_pretrained("bert-base-uncased")

# 正确：明确指定类别数
model = AutoModelForSequenceClassification.from_pretrained(
    "bert-base-uncased",
    num_labels=5,
    id2label={0: "1-star", 1: "2-star", 2: "3-star", 3: "4-star", 4: "5-star"},
    label2id={"1-star": 0, "2-star": 1, "3-star": 2, "4-star": 3, "5-star": 4},
)

陷阱：在训练循环中保留计算图耗尽内存

现象： 训练过程中 GPU 内存持续增长，最终 OOM。

原因： loss.item() 之前调用了 loss.detach() 或在日志记录时直接存储 loss tensor，导致整个计算图被保留在内存中。

解决： 使用 .item() 将标量提取为 Python float，释放计算图。

# 错误：保留了 tensor（及其完整计算图）
train_losses.append(loss)

# 正确：提取 Python float
train_losses.append(loss.item())

参见

• scikit-learn完全指南
• LangChain完全指南
• PyTorch完全指南