Transformers指南：16万星模型框架的推理、微调与量化实战

项目：huggingface/transformers | 星数：168333 | 语言：Python | 协议：Apache-2.0 | GitHub仓库

更新日期：2026-10-29 · 作者：CodeArts 编辑部

它解决的到底是什么问题

在没有 Transformers 之前，用 BERT 要自己抄 modeling 文件，用 LLaMA 要自己对 tokenizer 的 special token，换个模型就得重写一遍加载逻辑。HuggingFace 的 Transformers 把这件事标准化了：同一套 AutoModel / AutoTokenizer 接口能加载 100 万+ 模型，覆盖文本、视觉、音频、多模态四类任务。168333 星、Apache-2.0 协议，是当前 AI 工程里几乎绕不过去的基础设施。

从 pipeline 开始：三行代码跑通推理

from transformers import pipeline

clf = pipeline('sentiment-analysis', model='distilbert-base-uncased-finetuned-sst-2-english')
print(clf('Transformers makes model loading boring, in a good way.'))

pipeline 会自动下载模型、选择 tokenizer、处理输入、后处理输出。适合快速验证"这个模型能不能用"。可选的 task 名称覆盖很广：text-generation、summarization、question-answering、automatic-speech-recognition、image-classification、zero-shot-classification 等。

国内网络下载慢是最常见的拦路虎，设置镜像即可：export HF_ENDPOINT=https://hf-mirror.com，或用 hf download 命令预先缓存到本地再离线加载（local_files_only=True）。

底层三件套：Tokenizer、Model、Config

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

tok = AutoTokenizer.from_pretrained('distilbert-base-uncased-finetuned-sst-2-english')
model = AutoModelForSequenceClassification.from_pretrained('distilbert-base-uncased-finetuned-sst-2-english')

batch = tok(['这条评论很好', 'This is terrible'], padding=True, truncation=True, return_tensors='pt')
with torch.no_grad():
    logits = model(**batch).logits
print(logits.argmax(dim=-1))

三个要点值得记住：padding=True 按 batch 内最长补齐，truncation=True 超长自动截断（不设会直接抛错），return_tensors='pt' 转成 PyTorch 张量。换模型只需改一行字符串，这是整个框架最值钱的设计。

显存不够：device_map 与量化

本地跑 7B 以上模型，先考虑显存。最省事的是自动分片：

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    'Qwen/Qwen2.5-7B-Instruct',
    device_map='auto',
    torch_dtype='auto',
    load_in_4bit=True   # 需安装 bitsandbytes
)

device_map='auto' 会按可用显存把层分到 GPU/CPU，load_in_4bit=True 用 bitsandbytes 做 NF4 量化，7B 模型显存占用可从约 14GB 降到 4GB 左右。量化后推理速度略有提升，但生成质量在多数任务上肉眼难辨下降。

微调：Trainer 还是自己写循环

小规模数据（几千条以内）用 Trainer 最划算，它把训练循环、评估、checkpoint、日志都封装好了：

from transformers import Trainer, TrainingArguments

args = TrainingArguments(
    output_dir='./out',
    per_device_train_batch_size=8,
    num_train_epochs=3,
    learning_rate=2e-5,
    eval_strategy='epoch',
    save_strategy='epoch',
    fp16=True,
    logging_steps=50
)
Trainer(model=model, args=args, train_dataset=train_ds,
        eval_dataset=val_ds, tokenizer=tok).train()

如果要做 LoRA 之类参数高效微调，配合 peft 库给模型套一层 LoraConfig，可训练参数能降到 0.1% 量级，单卡就能微调 7B。这也是当前个人开发者最常见的路线。

推理加速：从 generate 参数说起

out = model.generate(
    **inputs,
    max_new_tokens=256,
    do_sample=True,
    temperature=0.7,
    top_p=0.9,
    repetition_penalty=1.1
)

几个实用判断：需要确定性输出就关掉 do_sample（贪心解码）；需要多样性用 temperature + top_p 组合，一般不要同时大幅调这两个；repetition_penalty 超过 1.3 容易让输出变得生硬。真正追求吞吐时，直接用 vLLM 或 SGLang 替代原生 generate，这是数量级的差别。

落地时的几个注意事项

• 模型版本要固定：from_pretrained('repo', revision='commit_hash')，否则上游更新可能悄悄改变输出。
• tokenizer 与模型必须配对：混用不同模型的 tokenizer 会得到静默错误而非报错。
• 注意模型许可证：仓库代码是 Apache-2.0，但单个模型权重常有自己的许可（如 Llama 系列的自定义许可），商用前务必单独确认。
• 批处理优先：服务端用小模型批处理往往比大模型逐条推理更划算，延迟和成本都能兼顾。

一句话总结

Transformers 把"用模型"的门槛降到了改一行字符串的水平，真正的功力体现在后面：量化压显存、LoRA 降微调成本、vLLM 提吞吐。把这三件事想清楚，比纠结用哪个模型更有价值。