fastNLP.core.callback module

callback模块实现了 fastNLP 中的许多 callback 类,用于增强 Trainer 类。

虽然Trainer本身已经集成了一些功能,但仍然不足以囊括训练过程中可能需要到的功能, 比如负采样,learning rate decay 和 early stop等。 为了解决这个问题,fastNLP引入了callback的机制,Callback 是一种在Trainer训练过程中特定阶段会运行的函数集合。 关于 Trainer 的详细文档,请参见 trainer 模块

我们将 train() 这个函数内部分为以下的阶段,在对应阶段会触发相应的调用:

callback.on_train_begin()  # 开始进行训练
for i in range(1, n_epochs+1):
    callback.on_epoch_begin()  # 开始新的epoch
    for batch_x, batch_y in Batch:
        callback.on_batch_begin(batch_x, batch_y, indices) # batch_x是设置为input的field,batch_y是设置为target的field
        获取模型输出
        callback.on_loss_begin()
        计算loss
        callback.on_backward_begin() # 可以进行一些检查,比如loss是否为None
        反向梯度回传
        callback.on_backward_end() # 进行梯度截断等
        进行参数更新
        callback.on_step_end()
        callback.on_batch_end()
        # 根据设置进行evaluation,比如这是本epoch最后一个batch或者达到一定step
        if do evaluation:
            callback.on_valid_begin()
            进行dev data上的验证
            callback.on_valid_end()  # 可以进行在其它数据集上进行验证
    callback.on_epoch_end()  # epoch结束调用
callback.on_train_end() # 训练结束
callback.on_exception() # 这是一个特殊的步骤,在训练过程中遭遇exception会跳转到这里。

如下面的例子所示,我们可以使用内置的 callback 组件,或者继承 Callback 定义自己的 callback 组件:

from fastNLP import Callback, EarlyStopCallback, Trainer, CrossEntropyLoss, AccuracyMetric
from fastNLP.models import CNNText

start_time = time.time()

class MyCallback(Callback):
    def on_epoch_end(self):
        print('{:d}ms\n\n'.format(round((time.time()-start_time)*1000)))

model = CNNText((len(vocab),50), num_classes=5, padding=2, dropout=0.1)
trainer = Trainer(model=model, train_data=train_data, dev_data=dev_data, loss=CrossEntropyLoss(),
                  metrics=AccuracyMetric(), callbacks=[MyCallback(),EarlyStopCallback(10)])
trainer.train()
class fastNLP.core.callback.Callback[源代码]

基类:object

别名 fastNLP.Callback fastNLP.core.callback.Callback

Callback是fastNLP中被设计用于增强 Trainer 的类。 如果Callback被传递给了 Trainer , 则 Trainer 会在对应的阶段调用Callback的函数, 具体调用时机可以通过 trainer 模块 查看。 这是Callback的基类,所有的callback必须继承自这个类

property trainer

该属性可以通过self.trainer获取到,一般情况下不需要使用这个属性。

property grad_scaler

float16的gradient scaler

property auto_cast

float16用的auto cast环境

property step

当前运行到的step, 范围为[1, self.n_steps+1)

property n_steps

Trainer一共会采多少个batch。当Trainer中update_every设置为非1的值时,该值不等于update的次数

property batch_size

train和evaluate时的batch_size为多大

property epoch

当前运行的epoch数,范围是[1, self.n_epochs+1)

property n_epochs

一共会运行多少个epoch

property optimizer

初始化Trainer时传递的Optimizer

property model

正在被Trainer训练的模型

property pbar

如果在Callback中需要打印内容,请使用self.pbar.write(str)。否则可能出现命令行显示效果不太好的问题。在 on_train_begin(), on_train_end(), on_exception()中请不要使用该属性,通过print输出即可。

property update_every

Trainer中的模型多少次反向传播才进行一次梯度更新,在Trainer初始化时传入的。

property batch_per_epoch

每个epoch一共有多少个batch,只有在on_epoch_begin之后才能调用该属性。

on_train_begin()[源代码]

在Train过程开始之前调用。

返回

on_epoch_begin()[源代码]

在每个epoch开始之前调用一次

返回

on_batch_begin(batch_x, batch_y, indices)[源代码]

每次采集到一个batch的数据则调用一次。这里对batch_x或batch_y删除添加内容是可以影响到Trainer中内容的。所以在这一步 可以进行一些负采样之类的操作。batch_x和batch_y中的tensor已经被放置到了模型所在的设备上。

参数
  • batch_x (dict) – DataSet中被设置为input的field的batch。

  • batch_y (dict) – DataSet中被设置为target的field的batch。

  • indices (list(int)) – 这次采样使用到的indices,可以通过DataSet[indices]获取出这个batch采出的Instance,在一些 情况下可以帮助定位是哪个Sample导致了错误。仅当num_workers=0时有效。

返回

on_loss_begin(batch_y, predict_y)[源代码]

在计算loss前调用,即这里修改batch_y或predict_y的值是可以影响到loss计算的。

参数
  • batch_y (dict) – 在DataSet中被设置为target的field的batch集合。

  • predict_y (dict) – 模型的forward()返回的结果。

返回

on_backward_begin(loss)[源代码]

在loss得到之后,但在反向传播之前。可能可以进行loss是否为NaN的检查。

参数

loss (torch.Tensor) – 计算得到的loss值

返回

on_backward_end()[源代码]

反向梯度传播已完成,但由于update_every的设置,可能并不是每一次调用都有梯度。到这一步,还没有更新参数。

返回

on_step_end()[源代码]

到这里模型的参数已经按照梯度更新。但可能受update_every影响,并不是每次都更新了。

返回

on_batch_end()[源代码]

这一步与on_step_end是紧接着的。只是为了对称性加上了这一步。

on_valid_begin()[源代码]

如果Trainer中设置了验证,则发生验证前会调用该函数

返回

on_valid_end(eval_result, metric_key, optimizer, is_better_eval)[源代码]

每次执行验证集的evaluation后会调用。

参数
  • Dict[str – Dict[str: float]] eval_result: , evaluation的结果。一个例子为{‘AccuracyMetric’:{‘acc’:1.0}},即 传入的dict是有两层,第一层是metric的名称,第二层是metric的具体指标。

  • metric_key (str) – 初始化Trainer时传入的metric_key。

  • optimizer (torch.Optimizer) – Trainer中使用的优化器。

  • is_better_eval (bool) – 当前dev结果是否比之前的好。

返回

on_epoch_end()[源代码]

每个epoch结束将会调用该方法

on_train_end()[源代码]

训练结束,调用该方法

on_exception(exception)[源代码]

当训练过程出现异常,会触发该方法 :param exception: 某种类型的Exception,比如KeyboardInterrupt等

class fastNLP.core.callback.GradientClipCallback(parameters=None, clip_value=1, clip_type='norm')[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.GradientClipCallback fastNLP.core.callback.GradientClipCallback

每次backward前,将parameter的gradient clip到某个范围。

__init__(parameters=None, clip_value=1, clip_type='norm')[源代码]
参数
  • parameters (None,torch.Tensor,List[torch.Tensor]) – 一般通过model.parameters()获得。 如果为None则默认对Trainer的model中所有参数进行clip

  • clip_value (float) – 将gradient 限制到[-clip_value, clip_value]。clip_value应该为正数

  • clip_type (str) –

    支持’norm’, ‘value’ 两种:

    1 'norm', 将gradient的norm rescale到[-clip_value, clip_value]
    
    2 'value', 将gradient限制在[-clip_value, clip_value],
        小于-clip_value的gradient被赋值为-clip_value;
        大于clip_value的gradient被赋值为clip_value.
    

class fastNLP.core.callback.EarlyStopCallback(patience)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.EarlyStopCallback fastNLP.core.callback.EarlyStopCallback

多少个epoch没有变好就停止训练,相关类 EarlyStopError

__init__(patience)[源代码]
参数

patience (int) – epoch的数量

class fastNLP.core.callback.FitlogCallback(data=None, tester=None, log_loss_every=0, verbose=1, log_exception=False)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.FitlogCallback fastNLP.core.callback.FitlogCallback

该callback可将loss和progress写入到fitlog中; 如果Trainer有dev的数据,将自动把dev的结果写入到log中; 同时还支持传入 一个(或多个)test数据集进行测试(只有在trainer具有dev时才能使用),每次在dev上evaluate之后会在这些数据集上验证一下。 并将验证结果写入到fitlog中。这些数据集的结果是根据dev上最好的结果报道的,即如果dev在第3个epoch取得了最佳,则 fitlog中记录的关于这些数据集的结果就是来自第三个epoch的结果。

__init__(data=None, tester=None, log_loss_every=0, verbose=1, log_exception=False)[源代码]
参数
  • data (DataSet,Dict[DataSet]) – 传入DataSet对象,会使用多个Trainer中的metric对数据进行验证。如果需要 传入多个DataSet请通过dict的方式传入,dict的key将作为对应dataset的name传递给fitlog。data的结果的名称以’data’开头。

  • tester (Tester,Dict[Tester]) – Tester对象,将在on_valid_end时调用。tester的结果的名称以’tester’开头

  • log_loss_every (int) – 多少个step记录一次loss(记录的是这几个batch的loss平均值),如果数据集较大建议将该值设置得 大一些,不然会导致log文件巨大。默认为0, 即不要记录loss。

  • verbose (int) – 是否在终端打印evaluation的结果,0不打印。

  • log_exception (bool) – fitlog是否记录发生的exception信息

class fastNLP.core.callback.EvaluateCallback(data=None, tester=None)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.EvaluateCallback fastNLP.core.callback.EvaluateCallback

通过使用该Callback可以使得Trainer在evaluate dev之外还可以evaluate其它数据集,比如测试集。每一次验证dev之前都会先验证EvaluateCallback 中的数据。

__init__(data=None, tester=None)[源代码]
参数
  • data (DataSet,Dict[DataSet]) – 传入DataSet对象,会使用Trainer中的metric对数据进行验证。如果需要传入多个 DataSet请通过dict的方式传入。

  • tester (Tester,Dict[DataSet]) – Tester对象, 通过使用Tester对象,可以使得验证的metric与Trainer中 的metric不一样。

class fastNLP.core.callback.LRScheduler(lr_scheduler)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.LRScheduler fastNLP.core.callback.LRScheduler

对PyTorch LR Scheduler的包装以使得其可以被Trainer所使用

__init__(lr_scheduler)[源代码]
参数

lr_scheduler (torch.optim.lr_scheduler._LRScheduler) – PyTorch的lr_scheduler

class fastNLP.core.callback.ControlC(quit_and_do, action=<staticmethod object>)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.ControlC fastNLP.core.callback.ControlC

检测到 control+C 时的反馈

__init__(quit_and_do, action=<staticmethod object>)[源代码]
参数

quit_and_do (bool) – 若为True,则检测到control+C 进行后续操作(默认值为:直接退出程序);否则只退出Trainer。

class fastNLP.core.callback.LRFinder(start_lr=1e-06, end_lr=10)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.LRFinder fastNLP.core.callback.LRFinder

用第一个 epoch 找最佳的学习率,从第二个epoch开始应用它

__init__(start_lr=1e-06, end_lr=10)[源代码]
参数
  • start_lr (float) – 学习率下界

  • end_lr (float) – 学习率上界

class fastNLP.core.callback.TensorboardCallback(*options)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.TensorboardCallback fastNLP.core.callback.TensorboardCallback

接受以下一个或多个字符串作为参数: - “model” - “loss” - “metric”

警告

fastNLP 已停止对此功能的维护,请等待 fastNLP 兼容 PyTorch1.1 的下一个版本。 或者使用和 fastNLP 高度配合的 fitlog(参见 使用fitlog 辅助 fastNLP 进行科研 )。

class fastNLP.core.callback.WarmupCallback(warmup=0.1, schedule='constant')[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.WarmupCallback fastNLP.core.callback.WarmupCallback

learning rate按照一定的速率从0上升到设置的learning rate。

__init__(warmup=0.1, schedule='constant')[源代码]
参数
  • warmup (int,float) – 如果warmup为int,则在该step之前,learning rate根据schedule的策略变化; 如果warmup为float, 如0.1, 则前10%的step是按照schedule策略调整learning rate。

  • schedule (str) – 以哪种方式调整。 linear: 前warmup的step上升到指定的learning rate(从Trainer中的optimizer处获取的), 后warmup的step下降到0; constant前warmup的step上升到指定learning rate,后面的step保持learning rate.

class fastNLP.core.callback.SaveModelCallback(save_dir, top=3, only_param=False, save_on_exception=False)[源代码]

基类:fastNLP.core.callback.Callback

基类 fastNLP.Callback

别名 fastNLP.SaveModelCallback fastNLP.core.callback.SaveModelCallback

由于Trainer在训练过程中只会保存最佳的模型, 该callback可实现多种方式的结果存储。 会根据训练开始的时间戳在save_dir下建立文件夹,再在文件夹下存放多个模型:

-save_dir
    -2019-07-03-15-06-36
        -epoch:0_step:20_{metric_key}:{evaluate_performance}.pt   # metric是给定的metric_key, evaluate_performance是性能
        -epoch:1_step:40_{metric_key}:{evaluate_performance}.pt
    -2019-07-03-15-10-00
        -epoch:0_step:20_{metric_key}:{evaluate_performance}.pt   # metric是给定的metric_key, evaluate_perfomance是性能
__init__(save_dir, top=3, only_param=False, save_on_exception=False)[源代码]
参数
  • save_dir (str) – 将模型存放在哪个目录下,会在该目录下创建以时间戳命名的目录,并存放模型。如果save_dir不存在将自动创建

  • top (int) – 保存dev表现top多少模型。-1为保存所有模型。

  • only_param (bool) – 是否只保存模型的权重。

  • save_on_exception – 发生exception时,是否保存一份发生exception的模型。模型名称为epoch:x_step:x_Exception:{exception_name}.

exception fastNLP.core.callback.CallbackException(msg)[源代码]

基类:BaseException

别名 fastNLP.CallbackException fastNLP.core.callback.CallbackException

当需要通过callback跳出训练的时候可以通过抛出CallbackException并在on_exception中捕获这个值。

__init__(msg)[源代码]
参数

msg (str) – Exception的信息。

exception fastNLP.core.callback.EarlyStopError(msg)[源代码]

基类:fastNLP.core.callback.CallbackException

基类 fastNLP.CallbackException

别名 fastNLP.EarlyStopError fastNLP.core.callback.EarlyStopError

用于EarlyStop时从Trainer训练循环中跳出。