Fast-Bert

新增 - 用于文本分类训练的学习率查找工具（感谢借用了 https://github.com/davidtvs/pytorch-lr-finder 的实现）

支持 LAMB 优化器，以加快训练速度。 有关 LAMB 优化器的论文，请参阅 https://arxiv.org/abs/1904.00962。

同时支持 BERT 和 XLNet，适用于多分类和多标签文本分类任务。

Fast-Bert 是一个深度学习库，使开发者和数据科学家能够训练和部署基于 BERT 和 XLNet 的模型，用于从文本分类开始的自然语言处理任务。

FastBert 的开发建立在优秀的 Hugging Face BERT PyTorch 库 所提供的坚实基础上，并受到 fast.ai 的启发，致力于让前沿的深度学习技术能够被更广泛的机器学习从业者所使用。

通过 Fast-Bert，您将能够：

1. 在您的自定义数据集上训练（更准确地说是微调）BERT、RoBERTa 和 XLNet 文本分类模型。

2. 调整模型超参数，例如训练轮数、学习率、批量大小、优化器调度等。

3. 保存并部署训练好的模型以进行推理（包括在 AWS Sagemaker 上部署）。

Fast-Bert 将同时支持多分类和多标签文本分类任务；未来还将支持其他自然语言处理任务，如命名实体识别、问答系统以及自定义语料库的微调。

1. BERT（由 Google 发布），其论文为 Jacob Devlin、Ming-Wei Chang、Kenton Lee 和 Kristina Toutanova 撰写的《BERT：面向语言理解的深度双向 Transformer 预训练》（https://arxiv.org/abs/1810.04805）。

2. XLNet（由 Google 和 CMU 共同发布），其论文为 Zhilin Yang*、Zihang Dai*、Yiming Yang、Jaime Carbonell、Ruslan Salakhutdinov 和 Quoc V. Le 撰写的《XLNet：通用自回归语言理解预训练》（https://arxiv.org/abs/1906.08237）。

3. RoBERTa（由 Facebook 发布），这是一种由 Yinhan Liu、Myle Ott、Naman Goyal、Jingfei Du 等人提出的鲁棒优化的 BERT 预训练方法。

4. DistilBERT（由 HuggingFace 发布），其发布伴随着 Victor Sanh、Lysandre Debut 和 Thomas Wolf 撰写的博客文章《更小、更快、更便宜、更轻：推出 DistilBERT，即 BERT 的蒸馏版本》（https://medium.com/huggingface/distilbert-8cf3380435b5）。

安装

此仓库已在 Python 3.6 及以上版本上测试通过。

使用 pip

可以通过以下命令使用 pip 安装 PyTorch-Transformers：

pip install fast-bert

从源代码安装

克隆仓库并运行：

pip install [--editable] .

或者

pip install git+https://github.com/kaushaltrivedi/fast-bert.git

此外，您还需要安装 NVIDIA Apex。

git clone https://github.com/NVIDIA/apex
cd apex
pip install -v --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./

使用方法

文本分类

1. 创建 DataBunch 对象

DataBunch 对象接收训练集、验证集和测试集的 CSV 文件，并将数据转换为 BERT、RoBERTa、DistilBERT 或 XLNet 所需的内部表示形式。该对象还会根据设备配置、批大小和最大序列长度实例化相应 的数据加载器。

from fast_bert.data_cls import BertDataBunch

databunch = BertDataBunch(DATA_PATH, LABEL_PATH,
                          tokenizer='bert-base-uncased',
                          train_file='train.csv',
                          val_file='val.csv',
                          label_file='labels.csv',
                          text_col='text',
                          label_col='label',
                          batch_size_per_gpu=16,
                          max_seq_length=512,
                          multi_gpu=True,
                          multi_label=False,
                          model_type='bert')

train.csv 和 val.csv 的文件格式

索引	文本	标签
0	看了其他评论，我惊讶于竟然没有任何警告提醒潜在观众，在租借这部烂片时他们会遇到什么。首先，我租这部电影时以为它只是个制作尚可的《夺宝奇兵》模仿作品。	neg
1	我已经看了前 17 集，这部剧真是太棒了！自从《新世纪福音战士》以来，我还没有对哪部动画如此着迷过。这部剧其实改编自一款成人游戏，我不确定之前是否有人这样做过。虽然我没玩过那款游戏，但据我所知，它与原作非常契合。	pos
2	这部电影绝对称得上是一部黑暗而 gritty 的杰作。也许我有些偏颇，因为种族隔离时代一直是我非常关注的领域。	pos

如果列名不是通常的 “text” 和 “labels”，则需要在 DataBunch 的 text_col 和 label_col 参数中指定这些列名。

labels.csv 将包含所有唯一标签的列表。在本例中，该文件内容如下：

pos
neg

对于多标签分类，labels.csv 将包含所有可能的标签：

toxic
severe_toxic
obscene
threat
insult
identity_hate

随后，train.csv 文件将为每个标签设置一列，每列的值为 0 或 1。进行多标签分类时，请别忘了将 BertDataBunch 中的 multi_label 参数设置为 True。

id	文本	toxic	severe_toxic	obscene	threat	insult	identity_hate
0	为什么以我的用户名“硬核金属乐迷”所做的编辑被回退了？	0	0	0	0	0	0
0	我会让你吃不了兜着走	1	0	0	1	0	0

label_col 将是一个标签列名的列表。在本例中，它将是：

['toxic','severe_toxic','obscene','threat','insult','identity_hate']

分词器

您可以创建一个分词器对象并将其传递给 DataBunch，也可以直接将模型名称作为分词器传入，DataBunch 会自动下载并实例化相应的分词器对象。

例如，若要使用 XLNet base cased 模型，只需将 tokenizer 参数设置为 'xlnet-base-cased'。DataBunch 会自动下载并实例化适用于 xlnet-base-cased 模型词汇表的 XLNetTokenizer。

模型类型

Fast-Bert 支持基于 XLNet、RoBERTa 和 BERT 的分类模型。请将 model_type 参数的值设置为 'bert'、roberta 或 'xlnet'，以初始化相应的 DataBunch 对象。

2. 创建 Learner 对象

BertLearner 是负责整合所有组件的“学习器”对象。它封装了模型生命周期中的关键逻辑，例如训练、验证和推理。

该学习器对象会将先前创建的数据批次（databunch）作为输入，并接受其他参数，如预训练模型的路径、是否使用 FP16 精度训练、多 GPU 支持以及多标签分类选项等。

Learner 类包含了训练循环、验证循环、优化器策略以及关键指标计算的逻辑。这使得开发者可以专注于自定义用例，而无需担心这些重复性的操作。

同时，Learner 对象也足够灵活，既可以通过调整参数进行定制，也可以通过继承 BertLearner 并重写相关方法来实现更高级的自定义功能。

from fast_bert.learner_cls import BertLearner
from fast_bert.metrics import accuracy
import logging

logger = logging.getLogger()
device_cuda = torch.device("cuda")
metrics = [{'name': 'accuracy', 'function': accuracy}]

learner = BertLearner.from_pretrained_model(
    databunch,
    pretrained_path='bert-base-uncased',
    metrics=metrics,
    device=device_cuda,
    logger=logger,
    output_dir=OUTPUT_DIR,
    finetuned_wgts_path=None,
    warmup_steps=500,
    multi_gpu=True,
    is_fp16=True,
    multi_label=False,
    logging_steps=50)

参数	描述
databunch	先前创建的数据批次对象
pretrained_path	预训练模型文件的存储目录，或预训练模型的名称，例如 bert-base-uncased、xlnet-large-cased 等
metrics	您希望模型在验证集上计算的指标函数列表，例如准确率、F1 分数等
device	torch.device 类型，可为 _cuda_ 或 _cpu_
logger	日志记录对象
output_dir	用于保存训练好的模型权重、分词器词汇表以及 TensorBoard 文件的目录
finetuned_wgts_path	提供微调后的语言模型权重路径（实验性功能）
warmup_steps	用于调度器的预热步数
multi_gpu	是否使用多 GPU 进行训练，例如在 AWS p3.8xlarge 实例上运行时
is_fp16	是否使用 FP16 精度训练
multi_label	是否进行多标签分类
logging_steps	每次计算 TensorBoard 指标之间的步数。将其设置为 0 可禁用 TensorBoard 日志记录。如果该值设置得太小，每次记录指标时都会对模型进行评估，从而降低训练速度

3. 寻找最优学习率

学习率是模型训练中最重要的超参数之一。我们引入了由 Leslie Smith 提出并集成到 fastai 库中的学习率查找工具。

learner.lr_find(start_lr=1e-5, optimizer_type='lamb')

这段代码大量借鉴了 David Silva 的 pytorch-lr-finder 库。

4. 训练模型

learner.fit(epochs=6,
            lr=6e-5,
            validate=True,  # 每个 epoch 结束后评估模型
            schedule_type="warmup_cosine",
            optimizer_type="lamb")

Fast-Bert 现在支持 LAMB 优化器。由于其训练速度较快，我们已将 LAMB 设置为默认优化器。您可以通过将 optimizer_type 设置为 'adamw' 来切换回 AdamW 优化器。

5. 保存训练好的模型文件

learner.save_model()

模型文件将被持久化到传入学习器对象的 output_dir/'model_out' 路径下。具体包含以下文件：

文件名	描述
pytorch_model.bin	训练好的模型权重
spiece.model	句子分词器词汇表（适用于 XLNet 模型）
vocab.txt	工作分词器词汇表（适用于 BERT 模型）
special_tokens_map.json	特殊标记映射
config.json	模型配置
added_tokens.json	新增标记列表

由于所有模型文件都存储在同一目录下，您可以直接将 pretrained_path 指向该目录，即可实例化学习器对象进行推理。

6. 模型推理

如果你已经有一个实例化的、训练好的 Learner 对象，只需在该对象上调用 predict_batch 方法，并传入文本数据列表即可：

texts = ['我真的很喜欢 Netflix 的原创电影',
		 '这部电影不值得看']
predictions = learner.predict_batch(texts)

如果你有一个持久化的已训练模型，并且只想对该模型运行推理逻辑，则可以使用第二种方法，即通过 Predictor 对象。

from fast_bert.prediction import BertClassificationPredictor

MODEL_PATH = OUTPUT_DIR/'model_out'

predictor = BertClassificationPredictor(
				model_path=MODEL_PATH,
				label_path=LABEL_PATH, # labels.csv 文件的路径
				multi_label=False,
				model_type='xlnet',
				do_lower_case=False,
				device=None) # 可自定义 torch.device，若可用则默认为 cuda

# 单条预测
single_prediction = predictor.predict("请给我这条文本的结果")

# 批量预测
texts = [
	"这是第一条文本",
	"这是第二条文本"
	]

multiple_predictions = predictor.predict_batch(texts)

语言模型微调

将基于 BERT 的模型应用于自定义数据集的一种有效方法是先针对该数据集对语言模型任务进行微调，这正是 fast.ai 的 ULMFit 所采用的方法。其核心思想是从预训练模型开始，然后在自定义数据集的原始文本上进一步训练模型。我们将使用掩码语言模型任务来微调语言模型。

本节将介绍如何使用 FastBert 对语言模型进行微调。

1. 导入必要的库

所需的对象存储在带有 _lm 后缀的文件中。

# 语言模型数据批次
from fast_bert.data_lm import BertLMDataBunch
# 语言模型学习器
from fast_bert.learner_lm import BertLMLearner

from pathlib import Path
from box import Box

2. 定义参数并设置数据路径

# Box 是一个方便的工具，可从 JSON 字典创建对象
args = Box({
    "seed": 42,
    "task_name": 'imdb_reviews_lm',
    "model_name": 'roberta-base',
    "model_type": 'roberta',
    "train_batch_size": 16,
    "learning_rate": 4e-5,
    "num_train_epochs": 20,
    "fp16": True,
    "fp16_opt_level": "O2",
    "warmup_steps": 1000,
    "logging_steps": 0,
    "max_seq_length": 512,
    "multi_gpu": True if torch.cuda.device_count() > 1 else False
})

DATA_PATH = Path('../lm_data/')
LOG_PATH = Path('../logs')
MODEL_PATH = Path('../lm_model_{}/'.format(args.model_type))

DATA_PATH.mkdir(exist_ok=True)
MODEL_PATH.mkdir(exist_ok=True)
LOG_PATH.mkdir(exist_ok=True)

3. 创建 DataBunch 对象

BertLMDataBunch 类包含一个静态方法 from_raw_corpus，该方法会接收原始文本列表，并为语言模型学习器创建 DataBunch。此方法首先会对文本列表进行预处理，去除 HTML 标签、多余空格等，然后生成 lm_train.txt 和 lm_val.txt 文件。这些文件将用于训练和评估语言模型微调任务。

下一步是对文本进行特征提取：文本将被分词、转换为数字表示，并按 512 个标记（包括特殊标记）划分为多个块。

databunch_lm = BertLMDataBunch.from_raw_corpus(
					data_dir=DATA_PATH,
					text_list=texts,
					tokenizer=args.model_name,
					batch_size_per_gpu=args.train_batch_size,
					max_seq_length=args.max_seq_length,
                    multi_gpu=args.multi_gpu,
                    model_type=args.model_type,
                    logger=logger)

由于此步骤耗时可能较长，具体取决于自定义数据集文本的大小，因此特征化后的数据会被缓存到 data_dir/lm_cache 文件夹中的 pickle 文件中。

下次可以直接实例化 DataBunch 对象，而无需再次调用 from_raw_corpus 方法，如下所示：

databunch_lm = BertLMDataBunch(
						data_dir=DATA_PATH,
						tokenizer=args.model_name,
                        batch_size_per_gpu=args.train_batch_size,
                        max_seq_length=args.max_seq_length,
                        multi_gpu=args.multi_gpu,
                        model_type=args.model_type,
                        logger=logger)

4. 创建 LM Learner 对象

BertLearner 是一个“学习器”对象，它将所有内容整合在一起。它封装了模型生命周期中的关键逻辑，例如训练、验证和推理。Learner 对象会以先前创建的 DataBunch 作为输入，并接受其他参数，如预训练模型的位置、FP16 训练、多 GPU 支持以及多标签选项等。

Learner 类包含了训练循环、验证循环和优化策略的逻辑，这有助于开发者专注于自己的用例，而无需担心这些重复性的工作。同时，Learner 对象也足够灵活，可以通过调整参数或通过创建 BertLearner 的子类并重新定义相关方法来进行定制。

learner = BertLMLearner.from_pretrained_model(
							dataBunch=databunch_lm,
							pretrained_path=args.model_name,
							output_dir=MODEL_PATH,
							metrics=[],
							device=device,
							logger=logger,
							multi_gpu=args.multi_gpu,
							logging_steps=args.logging_steps,
							fp16_opt_level=args.fp16_opt_level)

5. 训练模型

learner.fit(epochs=6,
			lr=6e-5,
			validate=True, 	# 每个 epoch 结束后评估模型
			schedule_type="warmup_cosine",
			optimizer_type="lamb")

Fast-Bert 现在支持 LAMB 优化器。由于其训练速度较快，我们已将其设为默认优化器。你可以通过将 optimizer_type 设置为 'adamw' 来切换回 AdamW 优化器。

6. 保存训练好的模型文件

learner.save_model()

模型文件将被保存到 Learner 对象提供的 output_dir/'model_out' 路径下。保存的文件包括：

文件名	描述
pytorch_model.bin	训练好的模型权重
spiece.model	句子分词器词汇表（适用于 xlnet 模型）
vocab.txt	工作片段分词器词汇表（适用于 bert 模型）
special_tokens_map.json	特殊标记映射
config.json	模型配置
added_tokens.json	新增标记列表

其中，pytorch_model.bin 包含微调后的权重，你可以在分类任务的 Learner 对象中通过 finetuned_wgts_path 参数指向该文件。

Amazon SageMaker 支持

本库旨在帮助您训练和部署生产级别的模型。由于 Transformer 模型的训练需要昂贵的 GPU，因此我添加了在 AWS SageMaker 上训练和部署模型的支持。

该仓库包含用于在 Amazon SageMaker 中构建基于 BERT 的分类模型的 Docker 镜像和代码。

请参阅我的博客 使用 FastBert 和 Amazon SageMaker 训练并部署强大的 BERT 基础 NLP 模型，其中详细介绍了如何将 SageMaker 与 FastBert 结合使用。

引用

如果您在已发表或开源项目中使用本工作，请务必提及 此库 和 Hugging Face 的 pytorch-transformers 库，并附上本仓库的链接。

同时，请引用我关于该主题的两篇博客：

• 介绍 FastBert — 一个用于 BERT 模型的简单深度学习库

• 使用 BERT 进行多标签文本分类——强大的 Transformer

• 使用 FastBert 和 Amazon SageMaker 训练并部署强大的 BERT 基础 NLP 模型

Fast-Bert 快速上手指南

Fast-Bert 是一个基于 PyTorch 的深度学习库，旨在让开发者能够轻松训练和部署 BERT、RoBERTa、XLNet 及 DistilBERT 模型，主要用于文本分类任务（支持多分类和多标签分类）。它借鉴了 fast.ai 的设计理念，简化了微调流程。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux (推荐) 或 macOS。
• Python 版本: 3.6 或 3.7+。
• GPU 支持: 强烈建议使用 NVIDIA GPU 以加速训练。
• 前置依赖:
  • PyTorch
  • NVIDIA Apex: Fast-Bert 依赖 Apex 进行混合精度训练（FP16）和使用 LAMB 优化器。必须预先安装。

安装步骤

1. 安装 NVIDIA Apex

Fast-Bert 需要编译版的 Apex 支持。请执行以下命令克隆并安装：

git clone https://github.com/NVIDIA/apex
cd apex
pip install -v --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./

(注：如果国内网络下载缓慢，可尝试配置 pip 国内镜像源，但 Apex 通常需要从源码编译)

2. 安装 Fast-Bert

您可以选择通过 pip 直接安装或从源码安装。

方式一：使用 pip 安装（推荐）

pip install fast-bert

国内用户建议使用清华或阿里镜像加速：

pip install fast-bert -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：从源码安装

pip install git+https://github.com/kaushaltrivedi/fast-bert.git

基本使用

以下是使用 Fast-Bert 进行文本分类的最小化工作流程，包含数据准备、模型构建两个核心步骤。

第一步：创建 DataBunch 对象

BertDataBunch 负责加载 CSV 数据、处理分词（Tokenizer）并生成 DataLoader。

假设您有以下文件：

• train.csv: 包含 text 和 label 列的训练数据。
• val.csv: 验证数据。
• labels.csv: 包含所有唯一标签列表（例如：pos, neg）。

from fast_bert.data_cls import BertDataBunch

# 定义路径
DATA_PATH = '/path/to/data'
LABEL_PATH = '/path/to/labels'
OUTPUT_DIR = '/path/to/output'

# 初始化 DataBunch
databunch = BertDataBunch(DATA_PATH, LABEL_PATH,
                          tokenizer='bert-base-uncased', # 自动下载并实例化分词器
                          train_file='train.csv',
                          val_file='val.csv',
                          label_file='labels.csv',
                          text_col='text',               # 文本列名
                          label_col='label',             # 标签列名
                          batch_size_per_gpu=16,
                          max_seq_length=512,
                          multi_gpu=True,                # 是否启用多卡
                          multi_label=False,             # 是否为多标签分类
                          model_type='bert')             # 支持 'bert', 'roberta', 'xlnet'

数据格式说明：

• 单标签分类: labels.csv 每行一个标签；CSV 数据文件中只需一列标签。
• 多标签分类: labels.csv 列出所有可能标签；CSV 数据文件中需为每个标签设一列（值为 0 或 1），且需设置 multi_label=True，label_col 传入列名列表。

第二步：创建 Learner 对象并开始训练

BertLearner 封装了训练循环、验证逻辑和优化策略。

import torch
import logging
from fast_bert.learner_cls import BertLearner
from fast_bert.metrics import accuracy

# 配置日志和设备
logger = logging.getLogger()
device_cuda = torch.device("cuda")
metrics = [{'name': 'accuracy', 'function': accuracy}]

# 初始化 Learner
learner = BertLearner.from_pretrained_model(
						databunch,
						pretrained_path='bert-base-uncased', # 预训练模型名称或本地路径
						metrics=metrics,
						device=device_cuda,
						logger=logger,
						output_dir=OUTPUT_DIR,
						finetuned_wgts_path=None,
						warmup_steps=500,
						multi_gpu=True,
						is_fp16=True,                        # 启用混合精度训练 (需 Apex)
						multi_label=False,
						logging_steps=50)

# 开始训练
# lr: 学习率, epochs: 轮数, validate_after_step: 每隔多少步验证一次
learner.fit(lr=2e-5, epochs=4, validate_after_step=200)

训练完成后，模型权重、分词器词汇表及 TensorBoard 日志将自动保存至 output_dir 指定目录，可直接用于推理或部署（如 AWS Sagemaker）。