Transformers 全家桶 on 扎塔-Zata

trainer

Thu, 13 Mar 2025 10:45:32 +0800

使用 `Trainer` 进行文本分类的教程

Trainer 是 Hugging Face transformers 库中一个高级工具，用于简化和加速模型的训练、评估和预测流程。它封装了训练过程中的许多细节，适合快速实现深度学习任务。本教程将以你提供的代码为基础，讲解如何使用 Trainer 完成一个中文情感分类任务（基于 ChnSentiCorp_htl_all.csv 数据集）。

1. 准备工作：导入相关包

首先，我们需要导入必要的库和模块：

from transformers import AutoTokenizer, AutoModelForSequenceClassification, Trainer, TrainingArguments
from datasets import load_dataset
import torch
import evaluate

AutoTokenizer：用于加载预训练的分词器。
AutoModelForSequenceClassification：加载适用于序列分类任务的预训练模型。
Trainer 和 TrainingArguments：核心工具，用于定义训练流程和参数。
datasets：用于加载和处理数据集。
evaluate：用于加载评估指标（如准确率和 F1 分数）。

2. 加载数据集

我们需要加载用于训练的数据集，这里假设你有一个名为 ChnSentiCorp_htl_all.csv 的 CSV 文件，包含 review（文本）和 label（标签）两列：

dataset = load_dataset("csv", data_files="./ChnSentiCorp_htl_all.csv", split="train")
dataset = dataset.filter(lambda x: x["review"] is not None)
print(dataset)

load_dataset：从 CSV 文件加载数据集。
filter：过滤掉 review 列为空的样本，确保数据质量。

输出示例：

Dataset({
 features: ['label', 'review'],
 num_rows: 7766
})

3. 划分数据集

将数据集划分为训练集和测试集：

datasets = dataset.train_test_split(test_size=0.1)
print(datasets)

train_test_split：按照 9:1 的比例将数据集分为训练集（90%）和测试集（10%）。

输出示例：

DatasetDict({
 train: Dataset({
 features: ['label', 'review'],
 num_rows: 6989
 })
 test: Dataset({
 features: ['label', 'review'],
 num_rows: 777
 })
})

4. 数据集预处理

为了让数据适配模型输入，我们需要对文本进行分词（tokenization）并添加标签：

tokenizer = AutoTokenizer.from_pretrained("hfl/rbt3")

def process_function(examples):
 tokenized_examples = tokenizer(examples["review"], max_length=128, truncation=True)
 tokenized_examples["labels"] = examples["label"]
 return tokenized_examples

tokenized_datasets = datasets.map(process_function, batched=True, remove_columns=datasets["train"].column_names)
print(tokenized_datasets)

AutoTokenizer.from_pretrained：加载与预训练模型匹配的分词器（这里是 hfl/rbt3）。
process_function：
- 使用 tokenizer 对 review 文本进行分词，限制最大长度为 128，并截断超长部分。
- 将标签列 label 重命名为 labels（Trainer 要求的字段名）。
map：对整个数据集应用预处理函数，batched=True 表示批量处理，remove_columns 删除原始列，只保留分词后的字段（如 input_ids, attention_mask, labels）。

输出示例：

DatasetDict({
 train: Dataset({
 features: ['input_ids', 'token_type_ids', 'attention_mask', 'labels'],
 num_rows: 6989
 })
 test: Dataset({
 features: ['input_ids', 'token_type_ids', 'attention_mask', 'labels'],
 num_rows: 777
 })
})

5. 创建模型

加载预训练模型并用于序列分类任务：

model = AutoModelForSequenceClassification.from_pretrained("hfl/rbt3")
print(model.config)

AutoModelForSequenceClassification：加载适用于分类任务的模型（默认情况下，hfl/rbt3 会自动配置为 2 分类任务）。
model.config：查看模型配置，例如类别数量、隐藏层大小等。

输出示例：

RobertaConfig {
 "num_labels": 2,
 "hidden_size": 768,
 ...
}

6. 创建评估函数

定义一个评估函数，用于计算模型在验证集上的表现：

acc_metric = evaluate.load("accuracy")
f1_metric = evaluate.load("f1")

def eval_metric(eval_predict):
 predictions, labels = eval_predict
 predictions = predictions.argmax(axis=-1) # 将 logits 转换为预测类别
 acc = acc_metric.compute(predictions=predictions, references=labels)
 f1 = f1_metric.compute(predictions=predictions, references=labels)
 acc.update(f1) # 合并 accuracy 和 f1 分数
 return acc

evaluate.load：加载预定义的评估指标（准确率和 F1 分数）。
eval_metric：接收 Trainer 传递的预测结果（eval_predict），计算并返回指标。
- predictions.argmax：从 logits 中提取预测类别。
- acc.update(f1)：将 F1 分数添加到结果字典中。

7. 配置 `TrainingArguments`

TrainingArguments 定义了训练过程中的超参数和策略：

train_args = TrainingArguments(
 output_dir="./checkpoints", # 模型和检查点的保存路径
 per_device_train_batch_size=64, # 训练时的批量大小
 per_device_eval_batch_size=128, # 验证时的批量大小
 logging_steps=10, # 每 10 步打印一次日志
 evaluation_strategy="epoch", # 每个 epoch 评估一次
 save_strategy="epoch", # 每个 epoch 保存一次模型
 save_total_limit=3, # 最多保存 3 个检查点
 learning_rate=2e-5, # 学习率
 weight_decay=0.01, # 权重衰减
 metric_for_best_model="f1", # 使用 F1 分数选择最佳模型
 load_best_model_at_end=True # 训练结束后加载最佳模型
)
print(train_args)

重要参数：
- evaluation_strategy 和 save_strategy：控制评估和保存的频率。
- metric_for_best_model：指定用于选择最佳模型的指标。
- load_best_model_at_end：确保训练结束后使用性能最好的模型。

8. 创建 `Trainer`

将模型、参数和数据集组合成 Trainer 对象：

from transformers import DataCollatorWithPadding

trainer = Trainer(
 model=model,
 args=train_args,
 train_dataset=tokenized_datasets["train"],
 eval_dataset=tokenized_datasets["test"],
 data_collator=DataCollatorWithPadding(tokenizer=tokenizer),
 compute_metrics=eval_metric
)

DataCollatorWithPadding：动态填充输入序列到相同长度，优化批量处理效率。
Trainer 参数：
- model：待训练的模型。
- args：训练参数。
- train_dataset 和 eval_dataset：训练和验证数据集。
- data_collator：数据整理器。
- compute_metrics：自定义的评估函数。

9. 模型训练

开始训练模型：

trainer.train()

trainer.train()：执行完整的训练循环。
训练过程中会：
- 每 logging_steps（10 步）打印损失。
- 每个 epoch 评估模型并保存检查点。
- 根据 metric_for_best_model（F1 分数）选择最佳模型。

输出示例：

[164/164 01:23, Epoch 3/3]
Epoch Training Loss Validation Loss Accuracy F1
1 0.3521 0.2914 0.875 0.882
2 0.2456 0.2678 0.890 0.895
3 0.1987 0.2593 0.892 0.899

10. 模型评估

在测试集上评估模型性能：

eval_results = trainer.evaluate(tokenized_datasets["test"])
print(eval_results)

trainer.evaluate()：计算并返回测试集上的指标（accuracy 和 F1）。
输出示例：

{'eval_loss': 0.2593, 'eval_accuracy': 0.892, 'eval_f1': 0.899, 'eval_runtime': 2.34}

11. 模型预测

对测试集或新输入进行预测：

预测整个测试集

predictions = trainer.predict(tokenized_datasets["test"])
print(predictions.metrics)

trainer.predict()：返回预测结果，包括 logits、标签和评估指标。

输出示例：

{'test_loss': 0.2593, 'test_accuracy': 0.892, 'test_f1': 0.899}

预测单个句子

from transformers import pipeline

model.config.id2label = {0: "负向", 1: "正向"} # 定义标签映射
pipe = pipeline("text-classification", model=model, tokenizer=tokenizer, device=0)
sen = "我觉得不错！"
result = pipe(sen)
print(result)

pipeline：快速构建推理管道。
id2label：将数字标签映射为人类可读的标签。
输出示例：

[{'label': '正向', 'score': 0.95}]

总结

通过以上步骤，你可以使用 Trainer 完成以下任务：

数据加载与预处理。
模型配置与训练。
评估模型性能。
对新数据进行预测。

`Trainer` 的优点

简洁：无需手动编写训练循环。
灵活：支持自定义评估指标和超参数。
高效：内置优化（如动态填充、多 GPU 支持）。

evaluate

Thu, 13 Mar 2025 10:40:16 +0800

`evaluate` 库使用指南

evaluate 是一个强大的 Python 库，用于计算和可视化机器学习模型的评估指标。本教程将带你逐步了解如何使用该库，包括加载评估函数、计算指标以及可视化结果。

1. 查看支持的评估函数

evaluate 库支持多种评估指标，例如 accuracy（准确率）、f1（F1 分数）、precision（精确率）和 recall（召回率）。你可以通过以下方式查看支持的评估函数：

import evaluate

# 查看支持的评估函数列表
evaluate.list_evaluation_modules()

注意：截至 2024-01-11，list_evaluation_modules() 可能无法完整显示所有支持的指标，但这不影响使用。你可以在 Hugging Face 官网查看完整的评估函数列表。

2. 加载评估函数

要使用某个评估指标，首先需要加载它。例如，加载 accuracy 指标：

accuracy = evaluate.load("accuracy")

这个加载很容易由于网络问题不能加载

这会返回一个评估对象，你可以用它来计算准确率。

3. 查看函数说明

加载评估函数后，可以查看其描述和输入要求：

# 查看指标的描述
print(accuracy.description)

# 查看输入参数的说明
print(accuracy.inputs_description)

# 查看评估对象的详细信息
print(accuracy)

输出将告诉你该指标的作用以及它期望的输入格式。例如，accuracy 需要 references（真实标签）和 predictions（预测标签）。

4. 评估指标计算

4.1 全局计算

你可以一次性计算整个数据集的指标：

accuracy = evaluate.load("accuracy")
results = accuracy.compute(references=[0, 1, 2, 0, 1, 2], predictions=[0, 1, 1, 2, 1, 0])
print(results)

输出示例：

{'accuracy': 0.5}

这里，references 是真实标签，predictions 是模型预测结果。结果显示准确率为 50%。

4.2 迭代计算

如果数据量很大，可以通过迭代的方式逐步添加数据：

单样本迭代

accuracy = evaluate.load("accuracy")
for ref, pred in zip([0, 1, 0, 1], [1, 0, 0, 1]):
 accuracy.add(references=ref, predictions=pred)
result = accuracy.compute()
print(result)

批量迭代

accuracy = evaluate.load("accuracy")
for refs, preds in zip([[0, 1], [0, 1]], [[1, 0], [0, 1]]):
 accuracy.add_batch(references=refs, predictions=preds)
result = accuracy.compute()
print(result)

两种方法都适合处理流式数据或大数据集。

5. 多个评估指标计算

你可以使用 evaluate.combine 同时加载多个指标：

clf_metrics = evaluate.combine(["accuracy", "f1", "recall", "precision"])
print(clf_metrics)

然后一次性计算所有指标：

results = clf_metrics.compute(predictions=[0, 1, 0], references=[0, 1, 1])
print(results)

输出示例：

{'accuracy': 0.6667, 'f1': 0.6667, 'recall': 0.5, 'precision': 1.0}

这对于分类任务非常有用，可以全面评估模型性能。

6. 评估结果对比可视化

evaluate 提供了可视化工具，目前支持雷达图（radar_plot）：

from evaluate.visualization import radar_plot

# 准备数据
data = [
 {"accuracy": 0.99, "precision": 0.8, "f1": 0.95, "latency_in_seconds": 33.6},
 {"accuracy": 0.98, "precision": 0.87, "f1": 0.91, "latency_in_seconds": 11.2},
 {"accuracy": 0.98, "precision": 0.78, "f1": 0.88, "latency_in_seconds": 87.6},
 {"accuracy": 0.88, "precision": 0.78, "f1": 0.81, "latency_in_seconds": 101.6}
]
model_names = ["Model 1", "Model 2", "Model 3", "Model 4"]

# 生成雷达图
plot = radar_plot(data=data, model_names=model_names)

这将生成一个雷达图，比较不同模型在多个指标上的表现。每个模型用一条线表示，指标（如 accuracy、f1 等）分布在图的轴上。

总结

通过本教程，你学会了如何：

查看和加载 evaluate 库支持的评估指标。
使用全局或迭代方法计算单个指标。
组合多个指标进行综合评估。
可视化评估结果以对比模型性能。

evaluate 库简单易用，特别适合机器学习从业者和研究人员快速评估模型。更多信息可参考官方文档。

datasets

Thu, 13 Mar 2025 10:38:50 +0800

Hugging Face Datasets 库基本使用教程

Hugging Face 的 datasets 库是一个强大的工具，用于加载、处理和管理数据集，尤其在自然语言处理 (NLP) 任务中非常流行。本教程将结合你的代码，逐步讲解其基本用法。

1. 环境准备

首先，确保你安装了必要的库：

pip install datasets transformers

然后导入相关模块：

import transformers
from datasets import load_dataset, Dataset, load_from_disk

2. 加载在线数据集

2.1 加载完整数据集

可以通过 load_dataset 函数直接加载 Hugging Face Hub 上的在线数据集。例如：

datasets = load_dataset("madao33/new-title-chinese")
print(datasets)

输出会显示数据集的结构，通常包含 train、validation 和 test 等划分。

2.2 加载特定任务数据集

有些数据集是集合（如 super_glue），可以指定加载某项任务：

boolq_dataset = load_dataset("super_glue", "boolq")
print(boolq_dataset)

2.3 按划分加载

可以指定加载某个具体划分（如 train）：

dataset = load_dataset("madao33/new-title-chinese", split="train")
print(dataset)

还可以加载部分数据：

指定范围：train[10:100]（第10到100条）
指定百分比：train[:50%]（前50%）
自定义划分：["train[:50%]", "train[50%:]"]（分成两部分）

dataset = load_dataset("madao33/new-title-chinese", split="train[:50%]")
print(dataset)

8. 加载本地数据集

8.1 加载单个文件

支持多种格式（如 CSV）：

dataset = load_dataset("csv", data_files="./ChnSentiCorp_htl_all.csv", split="train")
print(dataset)

或使用 Dataset.from_csv：

dataset = Dataset.from_csv("./ChnSentiCorp_htl_all.csv")

8.2 加载多个文件

加载文件夹内所有文件：

dataset = load_dataset("csv", data_files=["./all_data/file1.csv", "./all_data/file2.csv"], split="train")

8.3 从 Pandas 转换

import pandas as pd
data = pd.read_csv("./ChnSentiCorp_htl_all.csv")
dataset = Dataset.from_pandas(data)

8.4 从 List 转换

需要明确字段名：

data = [{"text": "abc"}, {"text": "def"}]
dataset = Dataset.from_list(data)

8.5 使用自定义脚本

可以编写加载脚本（如 load_script.py）加载复杂数据：

dataset = load_dataset("./load_script.py", split="train")

3. 查看数据集

加载数据集后，可以通过以下方法查看数据：

3.1 访问具体样本

datasets = load_dataset("madao33/new-title-chinese")
print(datasets["train"][0]) # 第一个样本
print(datasets["train"][:2]) # 前两个样本

3.2 访问特定字段

print(datasets["train"]["title"][:5]) # 前5个标题

3.3 查看元信息

print(datasets["train"].column_names) # 列名
print(datasets["train"].features) # 数据类型和特征

4. 数据集划分

4.1 随机划分

将数据集分为训练集和测试集：

dataset = datasets["train"]
split_dataset = dataset.train_test_split(test_size=0.1) # 10%作为测试集
print(split_dataset)

4.2 按标签比例划分

对于分类任务，可以按标签比例划分：

dataset = boolq_dataset["train"]
split_dataset = dataset.train_test_split(test_size=0.1, stratify_by_column="label")
print(split_dataset)

5. 数据选取与过滤

5.1 选取

选择特定索引的样本：

selected = datasets["train"].select([0, 1]) # 取第0和第1个样本
print(selected)

5.2 过滤

根据条件过滤数据：

filter_dataset = datasets["train"].filter(lambda example: "中国" in example["title"])
print(filter_dataset["title"][:5]) # 查看过滤后的前5个标题

6. 数据映射（Map）

map 函数可以对数据集的每个样本应用自定义处理。

6.1 简单映射

给标题添加前缀：

def add_prefix(example):
 example["title"] = 'Prefix: ' + example["title"]
 return example

prefix_dataset = datasets.map(add_prefix)
print(prefix_dataset["train"][:10]["title"])

6.2 使用 Tokenizer 预处理

结合 transformers 的 AutoTokenizer 进行编码：

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("bert-base-chinese")

def preprocess_function(example):
 model_inputs = tokenizer(example["content"], max_length=512, truncation=True)
 labels = tokenizer(example["title"], max_length=32, truncation=True)
 model_inputs["labels"] = labels["input_ids"]
 return model_inputs

processed_datasets = datasets.map(preprocess_function)
print(processed_datasets)

6.3 优化映射

多线程：加速处理

processed_datasets = datasets.map(preprocess_function, num_proc=4)

批量处理：提高效率

processed_datasets = datasets.map(preprocess_function, batched=True)

移除原始列：只保留处理后的字段

processed_datasets = datasets.map(preprocess_function, batched=True, remove_columns=datasets["train"].column_names)

remove_columns=datasets[“train”].column_names 的作用是告诉 datasets.map 在处理完成后，删除原始数据集中的所有列，只保留 process_function 返回的字段。具体原因如下：

减少内存占用：原始列（如 review）可能是长文本，占用大量内存。分词后，input_ids 和 attention_mask 是数值化的表示，通常比原始文本更紧凑。移除原始列可以节省内存，特别是在处理大规模数据集时。
适配模型输入： Hugging Face 的模型（如基于 transformers 的模型）通常只接受特定的输入字段（如 input_ids, attention_mask, token_type_ids, 和 labels）
简化数据结构：在分词后，原始列（如 review）的作用已经完成，保留它们没有实际意义。移除这些列可以让数据集更简洁，便于调试和后续操作。

7. 保存与加载

7.1 保存到本地

processed_datasets.save_to_disk("./processed_data")

7.2 从本地加载

processed_datasets = load_from_disk("./processed_data")
print(processed_datasets)

9. 与 DataCollator 结合使用

DataCollatorWithPadding 可以动态填充数据，适合 PyTorch 的 DataLoader。

9.1 数据预处理

from transformers import DataCollatorWithPadding

dataset = load_dataset("csv", data_files="./ChnSentiCorp_htl_all.csv", split="train")
dataset = dataset.filter(lambda x: x["review"] is not None)

def process_function(examples):
 tokenized_examples = tokenizer(examples["review"], max_length=128, truncation=True)
 tokenized_examples["labels"] = examples["label"]
 return tokenized_examples

tokenized_dataset = dataset.map(process_function, batched=True, remove_columns=dataset.column_names)

9.2 创建 DataLoader

from torch.utils.data import DataLoader

collator = DataCollatorWithPadding(tokenizer=tokenizer)
dl = DataLoader(tokenized_dataset, batch_size=4, collate_fn=collator, shuffle=True)

# 查看前几个批次
num = 0
for batch in dl:
 print(batch["input_ids"].size()) # 动态填充后的输入尺寸
 num += 1
 if num > 10:
 break

总结

通过本教程，你学会了：

加载在线和本地数据集。
查看和操作数据集（划分、选取、过滤）。
使用 map 进行数据预处理。
保存和加载处理后的数据集。
将数据集与 PyTorch 的 DataLoader 结合使用。

model

Thu, 13 Mar 2025 10:36:03 +0800

使用 Hugging Face Transformers 加载与调用预训练模型教程

本教程将介绍如何使用 Hugging Face 的 transformers 库加载预训练模型（如 hfl/rbt3）、保存模型到本地、以及如何调用模型进行推理。假设你已经安装了 transformers 库（可以通过 pip install transformers 安装）。

1. 环境准备

首先，导入必要的模块：

from transformers import AutoConfig, AutoModel, AutoTokenizer

AutoConfig: 用于加载模型的配置文件。
AutoModel: 用于加载预训练模型。
AutoTokenizer: 用于加载与模型配套的分词器。

2. 在线加载模型

Hugging Face 提供了在线加载模型的便捷方式，前提是你有网络连接。

示例代码

model = AutoModel.from_pretrained("hfl/rbt3", force_download=True)

解释

"hfl/rbt3": 指定要加载的模型名称，这里是 hfl/rbt3，一个基于 BERT 的中文预训练模型。
force_download=True: 强制重新下载模型文件，即使本地已有缓存。
模型会自动下载到本地缓存目录（通常是 ~/.cache/huggingface/transformers）。

3. 下载模型到本地（离线使用）

如果你需要离线使用模型，可以手动下载模型文件。以下是使用 Git 和 Git LFS 的方法：

完整克隆模型仓库

!git clone "https://huggingface.co/hfl/rbt3"

只下载模型权重文件

!git lfs clone "https://huggingface.co/hfl/rbt3" --include="*.bin"

注意事项

需要安装 Git 和 Git LFS（大型文件存储扩展）。
科学上网可能需要配置代理以访问 Hugging Face。
下载后，模型文件会存储在当前目录下的 rbt3 文件夹中。

4. 离线加载模型

假设模型已下载到本地目录 ./rbt3/，可以用以下方式加载：

model = AutoModel.from_pretrained("rbt3")

解释

"rbt3": 如果本地有同名文件夹，Transformers 会优先从本地加载。
如果路径不同，可以指定完整路径，例如 ./path/to/rbt3。

5. 查看与配置模型参数

模型加载后，可以通过 config 查看其配置信息。

示例代码

# 加载模型
model = AutoModel.from_pretrained("rbt3")

# 查看模型配置
print(model.config)

# 单独加载配置
config = AutoConfig.from_pretrained("./rbt3/")
print(config)

# 检查特定配置项
print(config.output_attentions)

解释

model.config: 返回模型的配置对象，包含模型架构、分词器信息等。
AutoConfig.from_pretrained: 可以单独加载配置文件。
output_attentions: 一个布尔值，表示是否输出注意力权重，默认通常为 False。

6. 模型调用

6.1 数据准备

使用分词器将文本转换为模型可接受的输入格式。

sen = "弱小的我也有大梦想！"
tokenizer = AutoTokenizer.from_pretrained("rbt3")
inputs = tokenizer(sen, return_tensors="pt")
print(inputs)

输出

{'input_ids': tensor([[ 101, 2453, 2207, 4638, 2769, 738, 3300, 1920, 3457, 2682, 8013, 102]]),
 'token_type_ids': tensor([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]]),
 'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]])}

解释

return_tensors="pt": 返回 PyTorch 张量格式（也可以用 "tf" 返回 TensorFlow 格式）。
input_ids: 分词后的 token ID 序列。
attention_mask: 指示哪些 token 需要被关注（1 表示有效，0 表示填充）。

6.2 不带 Model Head 的调用

加载基础模型，获取隐藏状态或注意力输出。

model = AutoModel.from_pretrained("rbt3", output_attentions=True)
output = model(**inputs)
print(output)
print(output.last_hidden_state.size())
print(len(inputs["input_ids"][0]))

输出

output.last_hidden_state.size(): torch.Size([1, 12, 768])
- 1: 批次大小（batch size）。
- 12: 输入序列长度（包括 [CLS] 和 [SEP]）。
- 768: 隐藏层维度。
len(inputs["input_ids"][0]): 12，与序列长度一致。

解释

output_attentions=True: 输出注意力权重（在 output.attentions 中）。
last_hidden_state: 最后一层的隐藏状态，可用于下游任务。

6.3 带 Model Head 的调用

加载带分类头的模型，用于特定任务（如序列分类）。

from transformers import AutoModelForSequenceClassification

clz_model = AutoModelForSequenceClassification.from_pretrained("rbt3", num_labels=10)
output = clz_model(**inputs)
print(output)
print(clz_model.config.num_labels)

输出

output.logits: 分类的原始分数（logits）。
clz_model.config.num_labels: 10，表示分类类别数。

解释

num_labels=10: 指定分类任务的类别数（默认是 2）。
带 Model Head 的模型会在基础模型上添加任务特定层（这里是分类层）。

7. 总结

通过本教程，你学会了：

在线加载模型: 使用 from_pretrained 从 Hugging Face Hub 下载模型。
离线保存与加载: 通过 Git 下载模型并在本地使用。
模型配置: 查看和调整模型参数。
模型调用: 处理输入文本并获取模型输出（带或不带 Model Head）。

tokenizer

Thu, 13 Mar 2025 10:32:29 +0800

这个教程将逐步解释 Tokenizer 的基本用法，包括加载、分词、索引转换、填充截断、处理批量数据以及 Fast/Slow Tokenizer 的对比。教程将使用中文句子 “弱小的我也有大梦想!” 作为示例。

示例

from transformers import BertTokenizer

tokenizer = BertTokenizer.from_pretrained(
 'bert-base-uncased', # 预训练模型名称
 do_lower_case=True, # 是否将文本转换为小写
 max_length=512, # 最大序列长度
 truncation=True, # 是否截断超过最大长度的输入
 padding='max_length' # 填充方式
)

常用参数说明：

from_pretrained: 指定预训练模型的名称或路径。
do_lower_case: 是否对输入进行小写处理。
max_length: 指定 tokenized 后的最大长度。
truncation: 是否截断超长序列。
padding: 填充策略（如True、max_length或longest）。

# 示例文本
text = "Hello, how are you today?"

# 使用tokenizer处理文本
encoded_input = tokenizer(
 text, # 输入文本
 add_special_tokens=True, # 添加特殊标记，如[CLS]和[SEP]
 max_length=128, # 最大长度（与初始化一致）
 truncation=True, # 截断超长部分
 padding='max_length', # 填充到指定长度
 return_tensors='pt' # 返回PyTorch张量（可选：'tf'为TensorFlow，None为Python列表）
)

# 输出结果
print(encoded_input)

对文本进行Tokenization

假设你有一段文本，你可以用tokenizer将它转化为模型可以理解的输入格式：

# 示例文本
text = "Hello, how are you today?"

# 使用tokenizer处理文本
encoded_input = tokenizer(
 text, # 输入文本
 add_special_tokens=True, # 添加特殊标记，如[CLS]和[SEP]
 max_length=128, # 最大长度（与初始化一致）
 truncation=True, # 截断超长部分
 padding='max_length', # 填充到指定长度
 return_tensors='pt' # 返回PyTorch张量（可选：'tf'为TensorFlow，None为Python列表）
)

# 输出结果
print(encoded_input)

输出说明

运行后，encoded_input会是一个字典，包含以下键值：

input_ids: 文本转换为的数字ID序列。
token_type_ids: 用于区分句子对（如果是单句输入，通常全是0）。
attention_mask: 标记哪些位置是真实token（1）哪些是填充（0）。

示例输出可能像这样：

{
 'input_ids': tensor([[ 101, 7592, 1010, 2129, 2024, 2017, 2651, 1029, 102, 0, 0, ...]]),
 'token_type_ids': tensor([[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, ...]]),
 'attention_mask': tensor([[1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, ...]])
}

解码回文本（可选）

如果你想检查tokenization的结果，可以用decode方法将ID转换回文本：

decoded_text = tokenizer.decode(encoded_input['input_ids'][0], skip_special_tokens=True)
print(decoded_text) # 输出: "hello how are you today"

处理多段文本

如果有多段文本（比如一个列表），可以这样处理：

texts = ["Hello, how are you?", "I am fine, thanks!"]

encoded_inputs = tokenizer(
 texts,
 add_special_tokens=True,
 max_length=128,
 truncation=True,
 padding='max_length',
 return_tensors='pt'
)

print(encoded_inputs['input_ids']) # 两个句子的input_ids

常见使用场景

单句输入: 如上面的text示例。

句子对: 如果是问答或文本分类任务，可以传入两个句子：

encoded_input = tokenizer("Hello, how are you?", "I am fine!", return_tensors='pt')

批量处理: 处理一个文本列表，用于模型训练或推理。

灵活调整参数

在使用时，你可以根据需求调整参数。例如：

不需要填充：padding=False。
不返回张量：return_tensors=None。
只获取ID：tokenizer.encode(text)（简单方法）。

Tokenizer 使用教程

在这个教程中，我们将学习如何使用 Hugging Face transformers 库中的 AutoTokenizer 来处理自然语言文本。Tokenizer 是自然语言处理 (NLP) 的核心组件，用于将原始文本转换为模型可以理解的数字表示。我们将以中文句子 “弱小的我也有大梦想!” 为例，逐步展示 Tokenizer 的功能。

环境准备

首先，确保你已经安装了 transformers 库。如果没有安装，可以通过以下命令安装：

pip install transformers

然后，导入必要的库：

from transformers import AutoTokenizer

示例句子

我们将使用以下句子作为示例：

sen = "弱小的我也有大梦想!"

Step 1: 加载与保存 Tokenizer

从 Hugging Face 加载 Tokenizer

AutoTokenizer.from_pretrained 方法允许我们从 Hugging Face 的模型仓库加载预训练的 Tokenizer。这里我们使用 "uer/roberta-base-finetuned-dianping-chinese" 模型的 Tokenizer：

tokenizer = AutoTokenizer.from_pretrained("uer/roberta-base-finetuned-dianping-chinese")
print(tokenizer)

输出会显示 Tokenizer 的类型和配置信息。

保存 Tokenizer 到本地

可以将加载的 Tokenizer 保存到本地目录：

tokenizer.save_pretrained("./roberta_tokenizer")

从本地加载 Tokenizer

从本地目录加载保存的 Tokenizer：

tokenizer = AutoTokenizer.from_pretrained("./roberta_tokenizer/")
print(tokenizer)

Step 2: 句子分词

Tokenizer 的核心功能是将句子拆分为词或子词单元（tokens）。使用 tokenize 方法：

tokens = tokenizer.tokenize(sen)
print(tokens)

输出示例：

['弱', '小', '的', '我', '也', '有', '大', '梦', '想', '!']

这些 tokens 是模型词汇表中的基本单元。

Step 3: 查看词典

Tokenizer 内部维护了一个词汇表（vocab），可以通过以下方式查看：

获取词汇表

vocab = tokenizer.vocab
print(vocab) # 输出词典（键是 token，值是对应的 ID）

获取词汇表大小

vocab_size = tokenizer.vocab_size
print(vocab_size) # 输出词汇表中的 token 数量，例如 21128

Step 4: 索引转换

在 NLP 中，模型需要将 tokens 转换为数字 ID。我们可以使用以下方法实现转换：

Tokens 转 ID

ids = tokenizer.convert_tokens_to_ids(tokens)
print(ids)

输出示例：

[2201, 2207, 4638, 2769, 738, 3300, 1920, 3457, 2682, 106]

ID 转 Tokens

tokens = tokenizer.convert_ids_to_tokens(ids)
print(tokens)

输出示例：

['弱', '小', '的', '我', '也', '有', '大', '梦', '想', '!']

Tokens 转字符串

str_sen = tokenizer.convert_tokens_to_string(tokens)
print(str_sen)

输出示例：

弱小的我也有大梦想!

更便捷的方式：编码与解码

编码（字符串 → ID）

ids = tokenizer.encode(sen, add_special_tokens=True)
print(ids)

输出示例（包含特殊 token，如 [CLS] 和 [SEP]）：

[101, 2201, 2207, 4638, 2769, 738, 3300, 1920, 3457, 2682, 106, 102]

解码（ID → 字符串）

str_sen = tokenizer.decode(ids, skip_special_tokens=False)
print(str_sen)

输出示例：

[CLS] 弱小的我也有大梦想! [SEP]

如果不需要特殊 token，可以设置 skip_special_tokens=True。

Step 5: 填充与截断

在处理批量数据时，句子长度可能不同，需要进行填充（padding）或截断（truncation）。

填充

将句子填充到指定长度（例如 15）：

ids = tokenizer.encode(sen, padding="max_length", max_length=15)
print(ids)

输出示例（0 表示填充）：

[101, 2201, 2207, 4638, 2769, 738, 3300, 1920, 3457, 2682, 106, 102, 0, 0, 0]

截断

将句子截断到指定长度（例如 5）：

ids = tokenizer.encode(sen, max_length=5, truncation=True)
print(ids)

输出示例：

[101, 2201, 2207, 4638, 102]

Step 6: 其他输入部分

模型通常需要额外的输入，例如 attention_mask 和 token_type_ids。

ids = tokenizer.encode(sen, padding="max_length", max_length=15)
attention_mask = [1 if idx != 0 else 0 for idx in ids] # 1 表示有效 token，0 表示填充
token_type_ids = [0] * len(ids) # 用于区分句子对，这里全为 0
print(ids)
print(attention_mask)
print(token_type_ids)

输出示例：

[101, 2201, 2207, 4638, 2769, 738, 3300, 1920, 3457, 2682, 106, 102, 0, 0, 0]
[1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0]
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

Step 7: 快速调用方式

encode_plus 或直接调用 tokenizer 可以一次性返回所有输入：

inputs = tokenizer.encode_plus(sen, padding="max_length", max_length=15)
print(inputs)

或者更简洁：

inputs = tokenizer(sen, padding="max_length", max_length=15)
print(inputs)

输出示例（字典形式）：

{'input_ids': [101, 2201, 2207, 4638, 2769, 738, 3300, 1920, 3457, 2682, 106, 102, 0, 0, 0], 'token_type_ids': [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], 'attention_mask': [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0]}

Step 8: 处理批量数据

可以一次性处理多个句子：

sens = ["弱小的我也有大梦想",
 "有梦想谁都了不起",
 "追逐梦想的心，比梦想本身，更可贵"]
res = tokenizer(sens)
print(res)

输出示例（字典形式，包含多个句子的编码）。

性能对比

单条循环处理

%%time
for i in range(1000):
 tokenizer(sen)

批量处理

%%time
res = tokenizer([sen] * 1000)

批量处理通常比单条循环更快。

Step 9: Fast vs Slow Tokenizer

Hugging Face 提供了 Fast Tokenizer（基于 Rust）和 Slow Tokenizer（基于 Python），Fast Tokenizer 速度更快且功能更丰富。

加载 Fast Tokenizer

fast_tokenizer = AutoTokenizer.from_pretrained("uer/roberta-base-finetuned-dianping-chinese")
print(fast_tokenizer)

加载 Slow Tokenizer

slow_tokenizer = AutoTokenizer.from_pretrained("uer/roberta-base-finetuned-dianping-chinese", use_fast=False)
print(slow_tokenizer)

性能对比

单条循环处理

%%time
for i in range(10000):
 fast_tokenizer(sen)

%%time
for i in range(10000):
 slow_tokenizer(sen)

批量处理

%%time
res = fast_tokenizer([sen] * 10000)

%%time
res = slow_tokenizer([sen] * 10000)

Fast Tokenizer 通常比 Slow Tokenizer 快得多。

Fast Tokenizer 的额外功能

Fast Tokenizer 支持返回 token 的字符偏移量：

inputs = fast_tokenizer(sen, return_offsets_mapping=True)
print(inputs)
print(inputs.word_ids()) # 每个 token 对应的单词索引

Slow Tokenizer 不支持此功能。

Step 10: 加载特殊 Tokenizer

某些模型（如 ChatGLM 或 Skywork）的 Tokenizer 需要特殊加载方式：

tokenizer = AutoTokenizer.from_pretrained("Skywork/Skywork-13B-base", trust_remote_code=True)
print(tokenizer)

保存和加载：

tokenizer.save_pretrained("skywork_tokenizer")
tokenizer = AutoTokenizer.from_pretrained("skywork_tokenizer", trust_remote_code=True)

编码与解码：

print(tokenizer.decode(tokenizer.encode(sen)))

总结

通过这个教程，我们学习了如何使用 AutoTokenizer 加载、分词、编码、解码、处理批量数据，以及 Fast/Slow Tokenizer 的区别。Tokenizer 是 NLP 任务中不可或缺的工具，掌握其用法将为后续的模型训练和推理奠定基础。

pipeline

Thu, 13 Mar 2025 10:00:55 +0800

Hugging Face `transformers.pipeline` 教程

pipeline 是 Hugging Face transformers 库提供的高层次接口，可以快速调用预训练模型完成 NLP、图像处理等任务。本教程将带你从基础用法到进阶技巧全面掌握 pipeline。

1. 查看支持的任务类型

pipeline 支持多种任务，可以通过 SUPPORTED_TASKS 查看：

from transformers.pipelines import SUPPORTED_TASKS

# 打印所有支持的任务及其详细信息
for task, details in SUPPORTED_TASKS.items():
 print(f"任务: {task}")
 print(f"详细信息: {details}\n")

常见任务示例：

text-classification：文本分类（如情感分析）
text-generation：文本生成
question-answering：问答
zero-shot-object-detection：零样本目标检测

完整列表请参考官方文档。

2. 创建与使用 `pipeline`

2.1 直接根据任务类型创建（默认模型）

默认使用英文模型，适合快速上手：

from transformers import pipeline

# 创建文本分类 pipeline
pipe = pipeline("text-classification")

# 输入文本列表
results = pipe(["very good!", "very bad!"])
print(results)

输出：

[{'label': 'POSITIVE', 'score': 0.9998}, {'label': 'NEGATIVE', 'score': 0.9987}]

2.2 指定任务和模型

选择特定模型（如中文模型）以适配需求：

# 使用中文情感分析模型
pipe = pipeline("text-classification", model="uer/roberta-base-finetuned-dianping-chinese")

# 分析中文文本
result = pipe("我觉得不太行！")
print(result)

输出：

[{'label': 'negative', 'score': 0.987}]

模型选择：可在 Hugging Face Model Hub 搜索适合的模型。

2.3 预加载模型和分词器

更灵活的方式，先加载模型和分词器，再创建 pipeline：

from transformers import AutoModelForSequenceClassification, AutoTokenizer

# 加载模型和分词器
model = AutoModelForSequenceClassification.from_pretrained("uer/roberta-base-finetuned-dianping-chinese")
tokenizer = AutoTokenizer.from_pretrained("uer/roberta-base-finetuned-dianping-chinese")

# 创建 pipeline
pipe = pipeline("text-classification", model=model, tokenizer=tokenizer)

# 使用
result = pipe("我觉得不太行！")
print(result)

输出：

Device set to use cpu
[{'label': 'negative (stars 1, 2 and 3)', 'score': 0.9735506772994995}]

3. 性能优化：使用 GPU 推理

默认情况下，pipeline 使用 CPU。可以通过 device 参数切换到 GPU：

# 指定 device=0 使用第一个 GPU
pipe = pipeline("text-classification", model="uer/roberta-base-finetuned-dianping-chinese", device=0)

# 检查模型运行设备
print(pipe.model.device) # 输出: cuda:0

# 测试推理速度
import torch
import time

times = []
for _ in range(100):
 torch.cuda.synchronize() # 同步 GPU
 start = time.time()
 pipe("我觉得不太行！")
 torch.cuda.synchronize()
 end = time.time()
 times.append(end - start)

print(f"平均推理时间: {sum(times) / 100:.4f} 秒")

对比：在 CPU 上运行相同代码（device=-1），GPU 通常显著更快。

4. 参数调整与高级用法

4.1 问答任务示例

调整参数以控制输出：

qa_pipe = pipeline("question-answering", model="uer/roberta-base-chinese-extractive-qa")

# 输入问题和上下文
result = qa_pipe(
 question="中国的首都是哪里？",
 context="中国的首都是北京",
 max_answer_len=5 # 限制答案长度
)
print(result)

输出：

{'score': 0.99, 'start': 6, 'end': 8, 'answer': '北京'}

4.2 图像任务：零样本目标检测

处理图像任务需要额外依赖（如 Pillow）：

from transformers import pipeline
from PIL import Image, ImageDraw
import requests

# 创建零样本目标检测 pipeline
detector = pipeline(model="google/owlvit-base-patch32", task="zero-shot-object-detection")

# 下载并打开图片
url = "https://unsplash.com/photos/oj0zeY2Ltk4/download?force=true&w=640"
img = Image.open(requests.get(url, stream=True).raw)

# 检测对象
predictions = detector(img, candidate_labels=["hat", "sunglasses", "book"])
print(predictions)

# 绘制结果
draw = ImageDraw.Draw(img)
for pred in predictions:
 box = pred["box"]
 draw.rectangle((box["xmin"], box["ymin"], box["xmax"], box["ymax"]), outline="red", width=1)
 draw.text((box["xmin"], box["ymin"]), f"{pred['label']}: {pred['score']:.2f}", fill="red")
img.show() # 显示图片

5. `pipeline` 背后的实现

理解底层过程有助于调试和自定义：

from transformers import AutoTokenizer, AutoModelForSequenceClassification
import torch

# 加载分词器和模型
tokenizer = AutoTokenizer.from_pretrained("uer/roberta-base-finetuned-dianping-chinese")
model = AutoModelForSequenceClassification.from_pretrained("uer/roberta-base-finetuned-dianping-chinese")

# 输入文本
input_text = "我觉得不太行！"
inputs = tokenizer(input_text, return_tensors="pt") # 转换为张量

# 模型推理
outputs = model(**inputs)
logits = outputs.logits
probs = torch.softmax(logits, dim=-1) # 转换为概率

# 获取预测结果
pred_id = torch.argmax(probs).item()
result = model.config.id2label[pred_id] # 从 ID 映射到标签
print(f"预测结果: {result}")

输出：

预测结果: negative

流程解析：

分词：tokenizer 将文本转为模型可理解的输入。
推理：model 输出 logits（原始分数）。
后处理：通过 softmax 和 argmax 转换为标签。

6. 注意事项与技巧

模型下载：首次运行会自动下载模型，需联网。
中文支持：选择中文模型（如 uer/roberta-base-chinese）以提升效果。
参数调整：如 max_length、truncation=True 可处理长文本。
硬件：大型模型建议使用 GPU（检查 torch.cuda.is_available()）。

7. 结语

通过 pipeline，你可以快速实现从文本分类到图像检测的多种任务。如果需要更深入的定制，可以参考底层实现部分，或访问 Hugging Face 文档。

Transformers 全家桶 on 扎塔-Zata

trainer

使用 Trainer 进行文本分类的教程

1. 准备工作：导入相关包

2. 加载数据集

3. 划分数据集

4. 数据集预处理

5. 创建模型

6. 创建评估函数

7. 配置 TrainingArguments

8. 创建 Trainer

9. 模型训练

10. 模型评估

11. 模型预测

预测整个测试集

预测单个句子

总结

Trainer 的优点

evaluate

evaluate 库使用指南

1. 查看支持的评估函数

2. 加载评估函数

3. 查看函数说明

4. 评估指标计算

4.1 全局计算

4.2 迭代计算

单样本迭代

批量迭代

5. 多个评估指标计算

6. 评估结果对比可视化

总结

datasets

Hugging Face Datasets 库基本使用教程

1. 环境准备

2. 加载在线数据集

2.1 加载完整数据集

2.2 加载特定任务数据集

2.3 按划分加载

8. 加载本地数据集

8.1 加载单个文件

8.2 加载多个文件

8.3 从 Pandas 转换

8.4 从 List 转换

8.5 使用自定义脚本

3. 查看数据集

3.1 访问具体样本

3.2 访问特定字段

3.3 查看元信息

4. 数据集划分

4.1 随机划分

4.2 按标签比例划分

5. 数据选取与过滤

5.1 选取

5.2 过滤

6. 数据映射（Map）

6.1 简单映射

6.2 使用 Tokenizer 预处理

6.3 优化映射

7. 保存与加载

7.1 保存到本地

7.2 从本地加载

9. 与 DataCollator 结合使用

9.1 数据预处理

9.2 创建 DataLoader

总结

model

使用 Hugging Face Transformers 加载与调用预训练模型教程

1. 环境准备

2. 在线加载模型

示例代码

解释

3. 下载模型到本地（离线使用）

完整克隆模型仓库

只下载模型权重文件

注意事项

4. 离线加载模型

解释

5. 查看与配置模型参数

示例代码

解释

使用 `Trainer` 进行文本分类的教程

7. 配置 `TrainingArguments`

8. 创建 `Trainer`

`Trainer` 的优点

`evaluate` 库使用指南

Hugging Face `transformers.pipeline` 教程

2. 创建与使用 `pipeline`

5. `pipeline` 背后的实现