一、核心组件API

1.1 模型类（transformers.*Model）

用于加载预训练模型，不同任务对应不同的模型类（如分类、生成、序列标注等）。

常用模型类	适用任务	示例代码
BertModel	基础特征提取（用于下游下游下游任务提供向量）	model = BertModel.from_pretrained("bert-base-chinese")
BertForSequenceClassification	文本分类（单/多标签）	model = BertForSequenceClassification.from_pretrained("bert-base-chinese", num_labels=2)
BertForTokenClassification	序列标注（如NER、词性标注）	model = BertForTokenClassification.from_pretrained("bert-base-chinese", num_labels=5)
BertForQuestionAnswering	阅读理解（抽取式问答）	model = BertForQuestionAnswering.from_pretrained("bert-base-chinese")
GPT2LMHeadModel	文本生成（如续写、摘要）	model = GPT2LMHeadModel.from_pretrained("gpt2")
T5ForConditionalGeneration	条件生成（如翻译、摘要）	model = T5ForConditionalGeneration.from_pretrained("t5-small")

核心方法：
● from_pretrained(model_name_or_path)：从预训练模型名称（如"bert-base-chinese"）或本地路径加载模型。
● save_pretrained(save_directory)：将模型保存到本地。

1.2 分词器类（transformers.*Tokenizer）

用于将文本转换为模型可接受的输入格式（token IDs、注意力掩码等），需与模型配套使用。

常用分词器	对应模型	示例代码
BertTokenizer	BERT系列	tokenizer = BertTokenizer.from_pretrained("bert-base-chinese")
GPT2Tokenizer	GPT2系列	tokenizer = GPT2Tokenizer.from_pretrained("gpt2")
T5Tokenizer	T5系列	tokenizer = T5Tokenizer.from_pretrained("t5-small")
AutoTokenizer	自动匹配任意模型	tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")

表格中，AutoTokenizer 是最灵活的选择，它能根据模型名称自动加载对应的分词器，无需手动指定具体的分词器类，在实际开发中推荐优先使用，尤其在处理多种模型时可减少代码冗余。

核心方法：
● tokenize(text)：将文本拆分为token（如"我爱NLP"→[“我”, “爱”, “N”, “##L”, “##P”]）。
● encode_plus(text, …)：一站式处理文本，返回input_ids（token ID）、attention_mask（注意力掩码）、token_type_ids（句子类型，如BERT的分句）等。

inputs = tokenizer.encode_plus(
    "我爱自然语言处理",
    add_special_tokens=True,  # 添加[CLS]、[SEP]等特殊token
    max_length=512,
    padding="max_length",  # 补全到max_length
    truncation=True,  # 截断过长文本
    return_tensors="pt"  # 返回PyTorch张量
)

1.3 自动类（transformers.Auto*）

自动推断模型/分词器类型，无需手动指定具体类（推荐使用，简化代码）。

自动类	功能	示例代码
AutoModel	自动加载任意模型（基础特征提取）	model = AutoModel.from_pretrained("bert-base-chinese")
AutoModelForSequenceClassification	自动加载分类模型	model = AutoModelForSequenceClassification.from_pretrained("roberta-base")
AutoTokenizer	自动加载对应分词器	tokenizer = AutoTokenizer.from_pretrained("gpt2")

这些自动类（Auto Classes）是Hugging Face Transformers库的核心特性，通过统一的接口自动适配不同预训练模型的结构和配置，大幅简化了跨模型类型的开发流程。使用时只需指定模型名称，无需手动匹配具体模型类，特别适合需要灵活切换不同模型的场景。

二、训练与评估API

2.1 Trainer 和 TrainingArguments

Trainer是Transformers库的高级训练接口，封装了训练、验证、保存等流程；TrainingArguments用于配置训练参数。

from transformers import Trainer, TrainingArguments
# 1.配置训练参数
training_args = TrainingArguments(
    output_dir="./results",  # 模型保存路径
    num_train_epochs=3,  # 训练轮次
    per_device_train_batch_size=8,  # 每个设备的批次大小
    per_device_eval_batch_size=8,  # 验证时的批次大小
    evaluation_strategy="epoch",  # 每轮结束后验证
    save_strategy="epoch",  # 每轮结束后保存模型
    logging_dir="./logs",  # 日志路径
    logging_steps=10  # 每10步打印一次日志
)


# 2. 初始化Trainer
trainer = Trainer(
    model=model,  # 待训练的模型
    args=training_args,  # 训练参数
    train_dataset=train_dataset,  # 训练数据集
    eval_dataset=eval_dataset  # 验证数据集
)

# 3. 开始训练
trainer.train()

# 4. 评估模型
eval_results = trainer.evaluate()

2.1 流水线（pipeline）

简化推理流程，一行代码完成从文本输入到结果输出的端到端任务，支持多种NLP任务。

常用任务	示例代码
情感分析	classifier = pipeline("sentiment-analysis"); classifier("这部电影很棒")
文本生成	generator = pipeline("text-generation", model="gpt2"); generator("人工智能将改变", max_length=50)
命名实体识别	ner = pipeline("ner", model="dbmdz/bert-large-cased-finetuned-conll03-english"); ner("Alice works at Google in London")
问答	qa = pipeline("question-answering"); qa(question="What is AI?", context="AI is the simulation of human intelligence...")
翻译	translator = pipeline("translation", model="t5-small"); translator("Hello world", max_length=40)

表格中展示的 pipeline 是 Hugging Face Transformers 库提供的高层API，通过简单调用即可实现各类NLP任务，无需手动配置模型和分词器细节，适合快速原型开发和任务验证。实际使用时，可根据具体语言（如中文）替换为对应的预训练模型以获得更好效果。

三、数据集处理API

3.1 Dataset 和 DatasetDict

用于处理数据集，支持高效的内存映射、并行处理和格式转换（需安装datasets库）。

from datasets import load_dataset

# 加载数据集（如IMDB情感分析数据集）
dataset = load_dataset("imdb")  # 返回DatasetDict，包含train和test

# 查看数据集结构
print(dataset["train"][0])  # 输出：{'text': '...', 'label': 0}

# 数据预处理（结合分词器）
def preprocess_function(examples):
    return tokenizer(examples["text"], truncation=True, max_length=512)

# 应用预处理到整个数据集
tokenized_dataset = dataset.map(preprocess_function, batched=True)

四、其他常用API

4.1 模型配置（transformers.*Config）

用于自定义模型结构参数（如隐藏层维度、注意力头数等），通常与from_pretrained结合使用。
from transformers import BertConfig

# 自定义BERT配置
config = BertConfig(
    vocab_size=30522,  # 词汇表大小
    hidden_size=768,  # 隐藏层维度
    num_hidden_layers=12,  # 隐藏层数量
    num_attention_heads=12  # 注意力头数
)

# 基于配置初始化模型（随机权重）
model = BertModel(config)

4.2 调度器（transformers.get_scheduler）

用于配置学习率调度策略（如线性衰减、余弦退火等），通常在自定义训练循环中使用。

from transformers import get_scheduler

optimizer = torch.optim.AdamW(model.parameters(), lr=5e-5)
num_training_steps = 3 * len(train_dataloader)  # 总训练步数

# 初始化学习率调度器
lr_scheduler = get_scheduler(
    name="linear",  # 调度策略
    optimizer=optimizer,
    num_warmup_steps=0,
    num_training_steps=num_training_steps
)

五、总结

Transformers库的API设计遵循“模块化+自动化”原则：

• 核心组件（AutoModel、AutoTokenizer）负责模型和数据处理；
• Trainer和TrainingArguments简化训练流程；
• pipeline提供开箱即用的推理能力；
• datasets库配套处理数据。

掌握这些API可以快速实现文本分类、生成、NER等各类NLP任务，无需从零构建模型结构。实际使用时，建议结合具体任务选择对应的模型类和API（如分类用AutoModelForSequenceClassification，生成用AutoModelForCausalLM）。

六、案例

6.1 案例整体介绍

下面通过一个综合案例，展示如何使用Transformers库的多种API实现文本分类和命名实体识别（NER） 任务，覆盖模型加载、数据处理、训练、评估和推理全流程。

1.案例中使用的API总结：

API类别	具体API名称	用途说明
模型加载	AutoModelForSequenceClassification	加载文本分类模型
	AutoModelForTokenClassification	加载NER序列标注模型
	AutoTokenizer	自动匹配分词器，处理文本转token ID
数据处理	load_dataset	加载公开数据集（如情感分析、NER数据集）
	Dataset.map()	批量预处理数据集（如分词、标签调整）
	DataCollatorWithPadding	动态填充数据，适配批量训练
训练配置	TrainingArguments	配置训练参数（轮次、批次、保存路径等）
	Trainer	封装训练流程，支持训练、评估、保存
推理工具	pipeline	快速实现推理（文本分类、NER等）
模型方法	from_pretrained()	从预训练模型加载参数
	save_pretrained()	保存训练后的模型（案例中隐含）

表格系统梳理了Transformers库中核心API的分类与功能，涵盖从模型加载、数据处理到训练推理的全流程，便于在实际开发中快速检索和使用对应的工具接口。

2.以下是转换后的API类别及用途说明表格：
①. 文本分类任务：
○ 用AutoModelForSequenceClassification加载BERT模型做情感分析（正面/负面）
○ 通过TrainingArguments配置训练参数，Trainer完成训练和评估
○ 推理时同时展示了两种方式：直接调用模型推理 + 使用pipeline快速推理
②. NER任务：
○ 用AutoModelForTokenClassification加载中文NER模型
○ 处理子词标签对齐问题（通过word_ids调整标签）
○ 用pipeline做实体识别，支持实体聚合（合并子词）

这个案例覆盖了Transformers库的核心API，展示了从数据加载、预处理、模型训练到推理的完整流程，适用于大多数NLP任务的快速实现。

# Transformersers库多API综合案例：文本分类与NER任务

# 安装必要库
# !pip install transformers datasets torch

import torch
from transformers import (
    AutoModelForSequenceClassification,  # 文本分类模型
    AutoModelForTokenClassification,     # NER模型
    AutoTokenizer,                       # 自动分词器
    TrainingArguments,                   # 训练参数配置
    Trainer,                             # 训练器
    pipeline,                            # 快速推理管道
    DataCollatorWithPadding              # 数据填充器
)
from datasets import load_dataset, DatasetDict  # 数据集处理
import numpy as np
from sklearn.metrics import classification_report

# ----------------------
# 1. 文本分类任务（情感分析）
# ----------------------

# 1.1 加载模型和分词器（使用Auto系列API）
model_name = "bert-base-chinese"
cls_tokenizer = AutoTokenizer.from_pretrained(model_name)
cls_model = AutoModelForSequenceClassification.from_pretrained(
    model_name,
    num_labels=2  # 二分类：正面/负面
)

# 1.2 加载并预处理数据集（使用datasets库）
# 加载中文情感分析数据集（示例用imdb的中文版本）
dataset = load_dataset("lansinuote/ChnSentiCorp")
# 查看数据集结构
print("原始数据集结构：", dataset)

# 数据预处理函数
def preprocess_cls(examples):
    return cls_tokenizer(
        examples["text"],
        truncation=True,
        max_length=128
    )

# 批量处理数据集（使用map API）
tokenized_cls_dataset = dataset.map(preprocess_cls, batched=True)
# 数据填充器（动态padding）
data_collator = DataCollatorWithPadding(tokenizer=cls_tokenizer)

# 1.3 配置训练参数（TrainingArguments）
cls_training_args = TrainingArguments(
    output_dir="./cls_results",
    num_train_epochs=2,
    per_device_train_batch_size=16,
    per_device_eval_batch_size=16,
    evaluation_strategy="epoch",  # 每轮评估一次
    save_strategy="epoch",        # 每轮保存一次
    logging_dir="./cls_logs",
    logging_steps=100
)

# 1.4 定义评估指标
def compute_cls_metrics(eval_pred):
    logits, labels = eval_pred
    predictions = np.argmax(logits, axis=1)
    return {
        "accuracy": (predictions == labels).mean()
    }

# 1.5 初始化训练器并训练（Trainer API）
cls_trainer = Trainer(
    model=cls_model,
    args=cls_training_args,
    train_dataset=tokenized_cls_dataset["train"],
    eval_dataset=tokenized_cls_dataset["validation"],
    tokenizer=cls_tokenizer,
    data_collator=data_collator,
    compute_metrics=compute_cls_metrics
)

# 开始训练
cls_trainer.train()

# 1.6 评估模型
eval_results = cls_trainer.evaluate()
print("分类任务评估结果：", eval_results)

# 1.7 推理（使用训练好的模型或pipeline）
# 方法1：直接使用模型推理
def predict_sentiment(text):
    inputs = cls_tokenizer(text, return_tensors="pt")
    with torch.no_grad():
        outputs = cls_model(**inputs)
    logits = outputs.logits
    pred = torch.argmax(logits, dim=1).item()
    return "正面" if pred == 1 else "负面"

print("模型推理结果：", predict_sentiment("这家餐厅的食物非常美味，服务也很好！"))

# 方法2：使用pipeline快速推理
cls_pipeline = pipeline(
    "text-classification",
    model=cls_model,
    tokenizer=cls_tokenizer,
    device=0 if torch.cuda.is_available() else -1  # 使用GPU
)
print("Pipeline推理结果：", cls_pipeline("这个产品质量很差，不推荐购买"))


# ----------------------
# 2. 命名实体识别（NER）任务
# ----------------------

# 2.1 加载NER模型和分词器
ner_model = AutoModelForTokenClassification.from_pretrained(
    "uer/bert-base-chinese-ner",  # 中文NER预训练模型
    num_labels=7  # 该模型包含7种实体类型
)
ner_tokenizer = AutoTokenizer.from_pretrained("uer/bert-base-chinese-ner")

# 2.2 加载数据集（使用conll2003的中文版本）
ner_dataset = load_dataset("peoples_daily_ner")
print("NER数据集结构：", ner_dataset)

# 2.3 数据预处理
def preprocess_ner(examples):
    # 处理文本和标签
    tokens = examples["tokens"]
    labels = examples["ner_tags"]
    
    # 编码文本
    encoding = ner_tokenizer(
        tokens,
        is_split_into_words=True,  # 已分词
        truncation=True,
        max_length=128
    )
    
    # 调整标签以匹配tokenizer的输出（处理子词）
    word_ids = encoding.word_ids(batch_index=0)
    previous_word_idx = None
    label_ids = []
    for word_idx in word_ids:
        if word_idx is None:
            label_ids.append(-100)  # 忽略特殊token
        elif word_idx != previous_word_idx:
            label_ids.append(labels[word_idx])
        else:
            label_ids.append(labels[word_idx] if ner_tokenizer.is_fast else -100)
        previous_word_idx = word_idx
    
    encoding["labels"] = label_ids
    return encoding

# 批量处理NER数据集
tokenized_ner_dataset = ner_dataset.map(
    preprocess_ner,
    batched=True,
    remove_columns=ner_dataset["train"].column_names
)

# 2.4 配置NER训练参数
ner_training_args = TrainingArguments(
    output_dir="./ner_results",
    num_train_epochs=3,
    per_device_train_batch_size=16,
    evaluation_strategy="epoch",
    logging_dir="./ner_logs"
)

# 2.5 定义NER评估指标
def compute_ner_metrics(eval_pred):
    logits, labels = eval_pred
    predictions = np.argmax(logits, axis=2)
    
    # 过滤掉-100的标签
    true_labels = [
        [label for label in label_seq if label != -100]
        for label_seq in labels
    ]
    true_predictions = [
        [pred for pred, label in zip(pred_seq, label_seq) if label != -100]
        for pred_seq, label_seq in zip(predictions, labels)
    ]
    
    # 计算分类报告
    flat_labels = [label for seq in true_labels for label in seq]
    flat_preds = [pred for seq in true_predictions for pred in seq]
    return classification_report(flat_labels, flat_preds, output_dict=True)

# 2.6 训练NER模型
ner_trainer = Trainer(
    model=ner_model,
    args=ner_training_args,
    train_dataset=tokenized_ner_dataset["train"],
    eval_dataset=tokenized_ner_dataset["validation"],
    compute_metrics=compute_ner_metrics
)
ner_trainer.train()

# 2.7 NER推理（使用pipeline）
ner_pipeline = pipeline(
    "ner",
    model=ner_model,
    tokenizer=ner_tokenizer,
    aggregation_strategy="average"  # 合并子词实体
)
text = "李白是唐朝著名诗人，出生于公元701年，代表作有《静夜思》。"
print("NER识别结果：", ner_pipeline(text))