基于 transformers 最新源码整理，覆盖加载、推理、训练、数据整理等核心场景。

---

1. AutoTokenizer

作用：根据模型名称自动选择并加载对应的分词器（Tokenizer）。Tokenizer 负责将原始文本转换为模型可接受的 input_ids、attention_mask、token_type_ids 等张量。

常用场景：

• 任何文本/NLP 任务的预处理第一步。
• 需要与模型配对使用，确保分词方式一致。

核心方法：

• AutoTokenizer.from_pretrained(model_name)：从 Hugging Face Hub 或本地路径加载。
• tokenizer(text, return_tensors="pt", padding=True, truncation=True, max_length=512)：对文本编码。
• tokenizer.decode(input_ids)：将 token ID 转回文本。
• tokenizer.batch_decode(...)：批量解码。
• tokenizer.pad_token = tokenizer.eos_token：当模型没有 pad token 时手动设置（如 GPT-2）。

示例：

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")
inputs = tokenizer("这是一个测试句子。", return_tensors="pt")
print(inputs)  # {'input_ids': tensor(...), 'attention_mask': tensor(...), 'token_type_ids': tensor(...)}

---

2. AutoModel

作用：自动加载指定模型的基础 Transformer 编码器（没有任务头），输出最后一层隐藏状态（hidden states）。

常用场景：

• 需要自定义任务头或做特征提取（embedding）。
• 研究模型内部表示。

核心方法：

• AutoModel.from_pretrained(model_name)：加载基础模型。
• model(**inputs)：前向传播，返回 last_hidden_state、pooler_output 等。
• model.config：查看模型配置。

示例：

from transformers import AutoTokenizer, AutoModel
import torch

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

inputs = tokenizer("你好，世界。", return_tensors="pt")
with torch.no_grad():
    outputs = model(**inputs)
print(outputs.last_hidden_state.shape)  # [batch, seq_len, hidden_size]

---

3. AutoModelForCausalLM

作用：加载带有因果语言模型头（Causal LM Head）的模型，用于文本生成，如 GPT、LLaMA、Qwen 等。

常用场景：

• 文本生成、对话、续写、代码补全。
• 大语言模型（LLM）推理与微调。

核心方法：

• AutoModelForCausalLM.from_pretrained(model_name, torch_dtype="auto", device_map="auto")
• model.generate(input_ids, max_new_tokens=100, temperature=0.7, do_sample=True)：生成文本。
• model.config.is_decoder = True

示例：

from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("gpt2")
model = AutoModelForCausalLM.from_pretrained("gpt2")

inputs = tokenizer("Once upon a time", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(outputs[0]))

---

4. AutoModelForSequenceClassification

作用：加载带有序列分类头（Sequence Classification Head）的模型，用于情感分析、文本分类、主题分类等。

常用场景：

• 二分类/多分类任务，如情感分析、垃圾邮件检测。

核心方法：

• AutoModelForSequenceClassification.from_pretrained(model_name, num_labels=2)：可指定标签数。
• model(**inputs)：返回 logits，经过 softmax 得到概率。

示例：

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch.nn.functional as F

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

inputs = tokenizer("I love this product!", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
probs = F.softmax(logits, dim=-1)
print(probs)

---

5. AutoConfig

作用：根据模型名自动加载模型的配置对象（Config），包含 hidden_size、num_layers、num_attention_heads、vocab_size 等超参数。

常用场景：

• 修改模型配置后从头初始化模型。
• 查看模型架构参数。
• 与 AutoModel.from_pretrained(..., config=config) 配合使用。

核心方法：

• AutoConfig.from_pretrained(model_name)
• config.hidden_size、config.num_hidden_layers
• config.update({"num_labels": 3})

示例：

from transformers import AutoConfig, AutoModelForSequenceClassification

config = AutoConfig.from_pretrained("bert-base-chinese")
config.num_labels = 5
model = AutoModelForSequenceClassification.from_config(config)

---

6. AutoProcessor

作用：自动加载多模态任务的 Processor，通常封装了 tokenizer、image processor、feature extractor 等。

常用场景：

• 视觉-语言模型（VLM），如 LLaVA、Qwen2-VL、CLIP。
• 语音-文本多模态模型。

核心方法：

• AutoProcessor.from_pretrained(model_name)
• processor(text=text, images=image, return_tensors="pt")

示例：

from transformers import AutoProcessor
from PIL import Image

processor = AutoProcessor.from_pretrained("openai/clip-vit-base-patch32")
inputs = processor(text=["a cat", "a dog"], images=Image.open("cat.jpg"), return_tensors="pt", padding=True)

---

7. pipeline

作用：高层端到端 API，一行代码完成 tokenizer + model + 后处理，适合快速原型和推理。

常用场景：

• 快速验证模型效果。
• 不需要细粒度控制的推理任务。

核心用法：

• pipeline(task, model=model_name, device=0)
• 支持 task：text-classification、token-classification、question-answering、text-generation、summarization、translation、image-classification、automatic-speech-recognition 等。

示例：

from transformers import pipeline

classifier = pipeline("sentiment-analysis", model="distilbert-base-uncased-finetuned-sst-2-english")
print(classifier("This movie is amazing!"))

---

8. Trainer

作用：Hugging Face 提供的通用训练循环封装，支持训练、评估、保存、日志、分布式训练、混合精度等。

常用场景：

• 微调预训练模型。
• 不想手写训练循环时。

核心方法：

• Trainer(model, args, train_dataset, eval_dataset, tokenizer, data_collator, compute_metrics)
• trainer.train()
• trainer.evaluate()
• trainer.save_model(output_dir)
• trainer.predict(test_dataset)

示例：

from transformers import Trainer, TrainingArguments

training_args = TrainingArguments(output_dir="./results", num_train_epochs=3, per_device_train_batch_size=8)
trainer = Trainer(
    model=model,
    args=training_args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    tokenizer=tokenizer,
    data_collator=data_collator,
    compute_metrics=compute_metrics,
)
trainer.train()

---

9. TrainingArguments

作用：配置 Trainer 的训练超参数和运行行为，是训练流程的“控制中心”。

常用参数：

• output_dir：输出目录。
• num_train_epochs：训练轮数。
• per_device_train_batch_size / per_device_eval_batch_size：每个设备的 batch size。
• learning_rate：学习率。
• warmup_steps / warmup_ratio：warmup 步数/比例。
• weight_decay：权重衰减。
• logging_steps：日志打印间隔。
• eval_strategy：评估策略（no / steps / epoch）。
• save_strategy：保存策略。
• fp16 / bf16：混合精度。
• gradient_accumulation_steps：梯度累积。
• deepspeed：DeepSpeed 配置文件路径。

示例：

from transformers import TrainingArguments

args = TrainingArguments(
    output_dir="./output",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    learning_rate=2e-5,
    eval_strategy="epoch",
    save_strategy="epoch",
    logging_steps=10,
    fp16=True,
)

---

10. DataCollatorWithPadding

作用：将不同长度的序列**动态填充（padding）**到同一 batch 内的最大长度，而不是固定 max_length，节省计算。

常用场景：

• 与 Trainer 配合处理变长文本输入。

核心参数：

• tokenizer：指定 tokenizer 以使用其 pad token。
• padding=True：动态 padding（默认）。
• max_length：可限制最大长度。

示例：

from transformers import DataCollatorWithPadding

data_collator = DataCollatorWithPadding(tokenizer=tokenizer)
# 在 Trainer 中传入

---

11. GenerationConfig

作用：集中管理文本生成参数，如最大长度、采样策略、温度、top-k、top-p、重复惩罚等。

常用场景：

• 统一配置生成行为，避免每次 generate() 都传大量参数。
• 保存/加载生成配置。

核心参数：

• max_new_tokens / max_length
• do_sample：是否采样，False 则为贪心解码。
• temperature：温度，控制随机性。
• top_k、top_p：采样过滤。
• repetition_penalty：重复惩罚。
• pad_token_id、eos_token_id、bos_token_id

示例：

from transformers import GenerationConfig

gen_config = GenerationConfig(
    max_new_tokens=200,
    do_sample=True,
    temperature=0.7,
    top_p=0.9,
    repetition_penalty=1.1,
)
model.generate(**inputs, generation_config=gen_config)

---

12. PreTrainedModel

作用：所有 PyTorch 预训练模型的基类。提供 from_pretrained、save_pretrained、push_to_hub、参数统计、设备管理、梯度检查点等通用能力。

常用场景：

• 自定义模型时继承。
• 理解所有模型共有的 API。

核心方法：

• model.save_pretrained(path)
• model.from_pretrained(path)
• model.named_parameters()
• model.gradient_checkpointing_enable()
• model.eval() / model.train()

示例：

from transformers import PreTrainedModel

print(isinstance(model, PreTrainedModel))  # True
model.save_pretrained("./my_model")

---

13. PreTrainedTokenizer / PreTrainedTokenizerFast

作用：

• PreTrainedTokenizer：纯 Python 实现的慢 tokenizer，可高度自定义。
• PreTrainedTokenizerFast：基于 Rust tokenizers 库，速度快，支持 offsets 映射。

常用场景：

• 需要处理特殊分词逻辑时继承/使用。
• AutoTokenizer 内部会根据配置选择其一。

核心方法（两者共有）：

• encode / encode_plus / batch_encode_plus
• tokenize
• convert_tokens_to_ids
• convert_ids_to_tokens
• build_inputs_with_special_tokens

---

14. PreTrainedConfig

作用：所有模型配置的基类，定义了模型架构参数（vocab_size、hidden_size、num_attention_heads、intermediate_size 等）。

常用场景：

• 修改配置后从头构建模型。
• 查看和保存模型超参数。

核心方法：

• config.to_dict()
• config.to_json_string()
• config.save_pretrained(path)
• config.update({...})

示例：

from transformers import PreTrainedConfig

config = model.config
print(config.hidden_size, config.num_hidden_layers)
config.save_pretrained("./my_config")

---

15. AutoModelForQuestionAnswering

作用：加载带有抽取式问答头的模型（通常为两个线性层，分别预测答案起始位置和结束位置）。

常用场景：

• SQuAD 风格的阅读理解、文档问答。

核心方法：

• AutoModelForQuestionAnswering.from_pretrained(model_name)
• outputs.start_logits、outputs.end_logits

示例：

from transformers import AutoTokenizer, AutoModelForQuestionAnswering
import torch

tokenizer = AutoTokenizer.from_pretrained("bert-large-uncased-whole-word-masking-finetuned-squad")
model = AutoModelForQuestionAnswering.from_pretrained("bert-large-uncased-whole-word-masking-finetuned-squad")

context = "The capital of France is Paris."
question = "What is the capital of France?"
inputs = tokenizer(question, context, return_tensors="pt")
with torch.no_grad():
    outputs = model(**inputs)

answer_start = torch.argmax(outputs.start_logits)
answer_end = torch.argmax(outputs.end_logits) + 1
answer = tokenizer.convert_tokens_to_string(tokenizer.convert_ids_to_tokens(inputs["input_ids"][0][answer_start:answer_end]))
print(answer)

---

16. AutoModelForTokenClassification

作用：加载带有Token 级分类头的模型，用于命名实体识别（NER）、词性标注（POS）、分词等。

常用场景：

• NER：识别人名、地名、组织名。
• 医学文本中的实体抽取。

核心方法：

• AutoModelForTokenClassification.from_pretrained(model_name, num_labels=9)
• outputs.logits 形状为 [batch, seq_len, num_labels]。

示例：

from transformers import AutoTokenizer, AutoModelForTokenClassification
import torch

tokenizer = AutoTokenizer.from_pretrained("dslim/bert-base-NER")
model = AutoModelForTokenClassification.from_pretrained("dslim/bert-base-NER")

inputs = tokenizer("My name is Wolfgang and I live in Berlin.", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
predictions = torch.argmax(logits, dim=2)

---

17. AutoModelForSeq2SeqLM

作用：加载带有序列到序列语言模型头的模型，如 T5、BART、mT5，用于翻译、摘要、文本生成等。

常用场景：

• 机器翻译、文本摘要、text-to-text 统一框架任务。

核心方法：

• AutoModelForSeq2SeqLM.from_pretrained("t5-small")
• model.generate(input_ids, max_new_tokens=100)

示例：

from transformers import AutoTokenizer, AutoModelForSeq2SeqLM

tokenizer = AutoTokenizer.from_pretrained("t5-small")
model = AutoModelForSeq2SeqLM.from_pretrained("t5-small")

inputs = tokenizer("translate English to German: The house is wonderful.", return_tensors="pt")
outputs = model.generate(**inputs, max_new_tokens=50)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))

---

18. AutoModelForMaskedLM

作用：加载带有掩码语言模型头的模型，如 BERT、RoBERTa，用于完形填空和 further pre-training。

常用场景：

• MLM 继续预训练。
• 评估模型对上下文的理解（fill-mask 任务）。

核心方法：

• AutoModelForMaskedLM.from_pretrained("bert-base-uncased")
• pipeline("fill-mask", model="...")

示例：

from transformers import AutoTokenizer, AutoModelForMaskedLM
import torch

tokenizer = AutoTokenizer.from_pretrained("bert-base-uncased")
model = AutoModelForMaskedLM.from_pretrained("bert-base-uncased")

inputs = tokenizer("The capital of France is [MASK].", return_tensors="pt")
with torch.no_grad():
    logits = model(**inputs).logits
mask_token_index = (inputs.input_ids == tokenizer.mask_token_id).nonzero(as_tuple=True)[1]
predicted_token_id = logits[0, mask_token_index].argmax(dim=-1)
print(tokenizer.decode(predicted_token_id))

---

19. set_seed

作用：设置 Python、numpy、PyTorch、CUDA 等所有相关随机种子，保证实验可复现。

常用场景：

• 训练前固定随机性。
• 调试时保证结果一致。

示例：

from transformers import set_seed

set_seed(42)

---

20. EarlyStoppingCallback

作用：在 Trainer 中实现早停（Early Stopping），当验证指标不再提升时自动停止训练，防止过拟合。

常用场景：

• 微调时使用，节省时间和算力。

核心参数：

• early_stopping_patience：允许指标不提升的轮数。
• early_stopping_threshold：提升阈值。
• 需要在 TrainingArguments 中设置 load_best_model_at_end=True、metric_for_best_model="eval_loss"、greater_is_better=False。

示例：

from transformers import TrainingArguments, Trainer, EarlyStoppingCallback

args = TrainingArguments(
    output_dir="./output",
    eval_strategy="epoch",
    save_strategy="epoch",
    load_best_model_at_end=True,
    metric_for_best_model="eval_loss",
    greater_is_better=False,
)

trainer = Trainer(
    model=model,
    args=args,
    train_dataset=train_dataset,
    eval_dataset=eval_dataset,
    callbacks=[EarlyStoppingCallback(early_stopping_patience=3)],
)
trainer.train()

---

附：20 个接口速查表

序号	接口	主要用途
1	AutoTokenizer	自动加载分词器
2	AutoModel	加载基础编码器，提取特征
3	AutoModelForCausalLM	文本生成 / LLM
4	AutoModelForSequenceClassification	文本分类
5	AutoConfig	加载/修改模型配置
6	AutoProcessor	多模态预处理
7	pipeline	一行代码端到端推理
8	Trainer	通用训练器
9	TrainingArguments	训练参数配置
10	DataCollatorWithPadding	动态 padding
11	GenerationConfig	生成策略配置
12	PreTrainedModel	所有模型基类
13	PreTrainedTokenizer / PreTrainedTokenizerFast	分词器基类
14	PreTrainedConfig	配置基类
15	AutoModelForQuestionAnswering	抽取式问答
16	AutoModelForTokenClassification	Token 分类 / NER
17	AutoModelForSeq2SeqLM	翻译 / 摘要
18	AutoModelForMaskedLM	掩码语言模型
19	set_seed	固定随机种子
20	EarlyStoppingCallback	训练早停