fastNLP/tutorials/tutorial_for_developer.md

# fastNLP开发者指南
#### 本教程涉及以下类：
- DataSet
- Sampler
- Batch
- Model
- Loss
- Metric
- Trainer
- Tester

#### DataSet: 用于承载数据。
1. DataSet里面每个元素只能是以下的三类`np.float64`, `np.int64`, `np.str`。如果传入的数据是`int`则被转换为`np.int64`, `float`被转为`np.float64`。   
2. DataSet可以将field设置为input或者target。其中被设置为input的field会被传递给Model.forward, 这个过程中我们是通过键匹配完成传递的。举例来说，假设DataSet中有'x1', 'x2', 'x3'被设置为了input，而
    - 函数是Model.forward(self, x1, x3), 那么DataSet中'x1', 'x3'会被传递给forward函数。多余的'x2'会被忽略
    - 函数是Model.forward(self, x1, x4), 这里多需要了一个'x4', 但是DataSet的input field中没有这个field，会报错。
    - 函数是Model.forward(self, x1, **kwargs), 会把'x1', 'x2', 'x3'都传入。但如果是Model.forward(self, x4, **kwargs)就会发生报错，因为没有'x4'。
3. 对于设置为target的field的名称，我们建议取名为'target'（如果只有一个需要predict的值），但是不强制。后面会讲为什么target可以不强制。  
DataSet应该是不需要单独再开发的，如果有不能满足的场景，请在开发群提出或者github提交issue。

#### Sampler: 给定一个DataSet，返回一个序号的list，Batch按照这个list输出数据。
Sampler需要继承fastNLP.core.sampler.BaseSampler
```python
class BaseSampler(object):
    """The base class of all samplers.

    Sub-classes must implement the __call__ method.
    __call__ takes a DataSet object and returns a list of int - the sampling indices.
    """
def __call__(self, *args, **kwargs):
    raise NotImplementedError
    
# 子类需要复写__call__方法。这个函数只能有一个必选参数, 且必须是DataSet类别， 否则Trainer没法调
class SonSampler(BaseSampler):
    def __init__(self, xxx):
        # 可以实现init也不可以不实现。
        pass
    def __call__(self, data_set):
        pass
```

#### Batch: 将DataSet中设置为input和target的field取出来构成batch_x, batch_y
并且根据情况(主要根据数据类型能不能转为Tensor)将数据转换为pytorch的Tensor。batch中sample的取出顺序是由Sampler决定的。  
Sampler是传入一个DataSet，返回一个与DataSet等长的序号list，Batch一次会取出batch_size个sample(最后一个batch可能数量不足batch_size个)。   
举例：  
1. SequentialSampler是顺序采样

    假设传入的DataSet长度是100, SequentialSampler返回的序号list就是[0, 1, ...,98, 99]. batch_size如果被设置为4，那么第一个batch所获取的instance就是[0, 1, 2, 3]这四个instance. 第二个batch所获取instace就是[4, 5, 6, 7], ...直到采完所有的sample。   
2. RandomSampler是随机采样   

    假设传入的DataSet长度是100, RandomSampler返回的序号list可能是[0, 99, 20, 5, 3, 1, ...]. 依次按照batch_size的大小取出sample。  

Batch应该不需要继承与开发，如果你有特殊需求请在开发群里提出。

#### Model：用户自定的Model
必须是nn.Module的子类
1. 必须实现forward方法，并且forward方法不能出现*arg这种参数. 例如
    ```python
    def forward(self, word_seq, *args): #这是不允许的.
        # ...
        pass
    ```
    返回值必须是dict的  
    ```python
    def forward(self, word_seq, seq_lens):  
        xxx = "xxx"
        return {'pred': xxx} #return的值必须是dict的。里面的预测的key推荐使用pred，但是不做强制限制。输出元素数目不限。  
    ```
2. 如果实现了predict方法，在做evaluation的时候将调用predict方法而不是forward。如果没有predict方法，则在evaluation时调用forward方法。predict方法也不能使用*args这种参数形式，同时结果也必须返回一个dict，同样推荐key为'pred'。

#### Loss: 根据model.forward()返回的prediction(是一个dict)和batch_y计算相应的loss
1. 先介绍"键映射"。 如在DataSet, Model一节所看见的那样，fastNLP并不限制Model.forward()的返回值，也不限制DataSet中target field的key。计算的loss的时候，怎么才能知道从哪里取值呢？  
这里以CrossEntropyLoss为例，一般情况下, 计算CrossEntropy需要prediction和target两个值。而在CrossEntropyLoss初始化时可以传入两个参数(pred=None, target=None), 这两个参数接受的类型是str，假设(pred='output', target='label')，那么CrossEntropyLoss会使用'output'这个key在forward的output与batch_y中寻找值;'label'也是在forward的output与batch_y中寻找值。注意这里pred或target的来源并不一定非要来自于model.forward与batch_y，也可以只来自于forward的结果。  
2. 如何创建一个自己的loss
    - 使用fastNLP.LossInForward, 在model.forward()的结果中包含一个为loss的key。
    - trainer中使用loss(假设loss=CrossEntropyLoss())的时候其实是
        los = loss(prediction, batch_y)，即直接调用的是`loss.__call__()`方法，但是CrossEntropyLoss里面并没有自己实现`__call__`方法，这是因为`__call__`在LossBase中实现了。所有的loss必须继承fastNLP.core.loss.LossBase, 下面先说一下LossBase的几个方法，见下一节。  
3. 尽量不要复写`__call__()`, `_init_param_map()`方法。

```python
class LossBase():
    def __init__(self):
        self.param_map = {} # 一般情况下也不需要自己创建。调用_init_param_map()更好
        self._checked = False # 这个参数可以忽略

    def _init_param_map(self, key_map=None, **kwargs):
        # 这个函数是用于注册Loss的“键映射”，有两种传值方法，
        # 第一种是通过key_map传入dict，取值是用value到forward和batch_y取
        #    key_map = {'pred': 'output', 'target': 'label'}   
        # 第二种是自己写
        #    _init_param_map(pred='output', target='label')
        # 为什么会提供这么一个方法？通过调用这个方法会自动注册param_map，并会做一些检查，防止出现传入的key其实并不是get_loss
        #   的一个参数。注意传入这个方法的参数必须都是需要做键映射的内容，其它loss参数不要传入。如果传入(pred=None, target=None)
        #   则__call__()会到pred_dict与target_dict去寻找key为'pred'和'target'的值。
        # 但这个参数不是必须要调用的。

    def __call__(self, pred_dict, target_dict, check=False): # check=False忽略这个参数，之后应该会被删除的
        # 这个函数主要会做一些check的工作，比如pred_dict与target_dict中是否包含了计算loss所必须的key等。检查通过，则调用get_loss
        #  方法。
        fast_param = self._fast_param_map(predict_dict, target_dict):
        if fast_param:
            return self.get_loss(**fast_param)
        # 如果没有fast_param则通过匹配参数然后调用get_loss完成
        xxxx
        return loss # 返回为Tensor的loss
    def _fast_param_map(self, pred_dict, target_dict):
        # 这是一种快速计算loss的机制，因为在很多情况下其实都不需要通过"键映射"，比如计算loss时，pred_dict只有一个元素，
        #   target_dict也只有一个元素，那么无歧义地就可以把预测值与实际值用于计算loss, 基类判断了这种情况(可能还有其它无歧义的情况)。
        #   即_fast_param_map成功的话，就不需要使用键映射，这样即使在没有传递或者传递错误"键映射"的情况也可以直接计算loss。
        # 返回值是一个dict, 如果匹配成功，应该返回类似{'pred':value, 'target': value}的结果；如果dict为空则说明匹配失败，
        #   __call__方法会继续执行。

    def get_loss(self, *args, **kwargs):
        # 这个是一定需要实现的，计算loss的地方。
        # (1) get_loss中一定不能包含*arg这种参数形式。
        # (2) 如果包含**kwargs这种参数，这会将pred_dict与target_dict中所有参数传入。但是建议不要用这个参数
        raise NotImplementedError

# 下面使用L1Loss举例
class L1Loss(LossBase): # 继承LossBase
    # 初始化需要映射的值，这里需要映射的值'pred', 'target'必须与get_loss需要参数名是对应的
    def __init__(self, pred=None, target=None): 
        super(L1Loss, self).__init__()
        # 这里传入_init_param_map以使得pred和target被正确注册，但这一步不是必须的, 建议调用。传入_init_param_map的是用于
        #   “键映射"的键值对。假设初始化__init__(pred=None, target=None, threshold=0.1)中threshold是用于控制loss计算的，则
        #   不要将threshold传入_init_param_map.
        self._init_param_map(pred=pred, target=target)

    def get_loss(self, pred, target):
        # 这里'pred', 'target'必须和初始化的映射是一致的。
        return F.l1_loss(input=pred, target=target) #直接返回一个loss即可
```

###  Metric: 根据Model.forward()或者Model.predict()的结果计算metric  
metric的设计和loss的设计类似。都是传入pred_dict与target_dict进行计算。但是metric的pred_dict来源可能是Model.forward的返回值， 也可能是Model.predict(如果Model具有predict方法则会调用predict方法)的返回值，下面统一用pred_dict代替。  
1. 这里的"键映射"与loss的"键映射"是类似的。举例来说，若Metric(pred='output', target='label')，则使用'output'到pred_dict和target_dict中寻找pred, 用'label'寻找target。   
2. 如何创建一个自己的Metric方法  
Metric与loss的计算不同在于，Metric的计算有两个步骤。  
    - **每个batch的输出**都会调用Metric的``__call__(pred_dict, target_dict)``方法，而``__call__``方法会调用evaluate()(需要实现)方法。   
    - 在所有batch传入之后，调用Metric的get_metric()方法得到最终的metric值。  
    - 所以Metric在调用evaluate方法时，根据拿到的数据: pred_dict与batch_y, 改变自己的状态(比如累加正确的次数，总的sample数等)。在调用get_metric()的时候给出一个最终计算结果。  
    所有的Metric必须继承自fastNLP.core.metrics.MetricBase. 例子见下一个cell        
3. 尽量不要复写``__call__()``,``_init_param_map()``方法。

```python
class MetricBase: 
    def __init__(self):
        self.param_map = {} # 一般情况下也不需要自己创建。调用_init_param_map()更好
        self._checked = False # 这个参数可以忽略

    def _init_param_map(self, key_map=None, **kwargs):
        # 这个函数是用于注册Metric的“键映射”，有两种传值方法，
        # 第一种是通过key_map传入dict，取值是用value到forward和batch_y取
        #    key_map = {'pred': 'output', 'target': 'label'}   
        # 第二种是自己写(建议使用改种方式)
        #    _init_param_map(pred='output', target='label')
        # 为什么会提供这么一个方法？通过调用这个方法会自动注册param_map，并会做一些检查，防止出现传入的key其实并不是evaluate()
        #   的一个参数。注意传入这个方法的参数必须都是需要做键映射的内容，其它evaluate参数不要传入。如果传入(pred=None, target=None)
        #   则__call__()会到pred_dict与target_dict去寻找key为'pred'和'target'的值。
        # 但这个参数不是必须要调用的。
        pass

    def __call__(self, pred_dict, target_dict, check=False): # check=False忽略这个参数，之后应该会被删除的
        # 这个函数主要会做一些check的工作，比如pred_dict与target_dict中是否包含了计算evaluate所必须的key等。检查通过，则调用
        #  evaluate方法。
        fast_param = self._fast_param_map(predict_dict, target_dict):
        if fast_param:
            return self.evaluate(**fast_param)
        # 如果没有fast_param则通过匹配参数然后调用get_loss完成
        # xxxx

    def _fast_param_map(self, pred_dict, target_dict):
        # 这是一种快速计算loss的机制，因为在很多情况下其实都不需要通过"键映射"，比如evaluate时，pred_dict只有一个元素，
        #   target_dict也只有一个元素，那么无歧义地就可以把预测值与实际值用于计算metric, 基类判断了这种情况(可能还有其它无歧义的
        #   情况)。即_fast_param_map成功的话，就不需要使用键映射，这样即使在没有传递或者传递错误"键映射"的情况也可以直接计算metric。
        # 返回值是一个dict, 如果匹配成功，应该返回类似{'pred':value, 'target': value}的结果；如果dict为空则说明匹配失败，
        #   __call__方法会继续尝试匹配。
        pass

    def evaluate(self, *args, **kwargs):
        # 这个是一定需要实现的，累加metric状态
        # (1) evaluate()中一定不能包含*arg这种参数形式。
        # (2) 如果包含**kwargs这种参数，这会将pred_dict与target_dict中所有参数传入。但是建议不要用这个参数
        raise NotImplementedError

    def get_metric(self, reset=True):
        # 这是一定需要实现的，获取最终的metric。返回值必须是一个dict。会在所有batch传入之后调用
        raise NotImplementedError

# 下面使用AccuracyMetric举例
class AccuracyMetric(MetricBase): # MetricBase
    # 初始化需要映射的值，这里需要映射的值'pred', 'target'必须与evaluate()需要参数名是对应的
    def __init__(self, pred=None, target=None): 
        super(AccuracyMetric, self).__init__()
        # 这里传入_init_param_map以使得pred和target被正确注册，但这一步不是必须的, 建议调用。传入_init_param_map的是用于
        #   “键映射"的键值对。假设初始化__init__(pred=None, target=None, threshold=0.1)中threshold是用于控制loss计算的，则
        #   不要将threshold传入_init_param_map.
        self._init_param_map(pred=pred, target=target)

        self.total = 0 # 用于累加一共有多少sample
        self.corr = 0 # 用于累加一共有多少正确的sample

    def evaluate(self, pred, target):
        # 对pred和target做一些基本的判断或者预处理等
        if pred.size()==target.size() and len(pred.size())=1: #如果pred已经做了argmax
            pass
        elif len(pred.size())==2 and len(target.size())==1: # pred还没有进行argmax
            pred = pred.argmax(dim=1)
        else:
            raise ValueError("The shape of pred and target should be ((B, n_classes), (B, )) or ("
                            "(B,),(B,)).")
        assert pred.size(0)==target.size(0), "Mismatch batch size."
        # 进行相应的累加
        self.total += pred.size(0)
        self.corr += torch.sum(torch.eq(pred, target).float()).item()

    def get_metric(self, reset=True):
        # reset用于指示是否清空累加信息。默认为True
        # 这个函数需要返回dict，可以包含多个metric。
        metric = {}
        metric['acc'] = self.corr/self.total
        if reset:
            self.total = 0
            self.corr = 0
        return metric
```

#### Tester: 用于做evaluation，应该不需要更改
重要的初始化参数有data, model, metric；比较重要的function是test()。

test中的运行过程  
``` 
predict_func = 如果有model.predict则为model.predict, 否则是model.forward  
for batch_x, batch_y in batch:  
# (1) 同步数据与model  
# (2) 根据predict_func的参数从batch_x中取出数据传入到predict_func中，得到结果pred_dict  
# (3) 调用metric(pred_dict, batch_y  
# (4) 当所有batch都运行完毕，会调用metric的get_metric方法，并且以返回的值作为evaluation的结果  
metric.get_metric()
```

#### Trainer: 对训练过程的封装。  
里面比较重要的function是train()  
train()中的运行过程  
```
(1) 创建batch  
    batch = Batch(dataset, batch_size, sampler=sampler)  
    for batch_x, batch_y in batch:  
        # ...
    batch_x，batch_y都是dict。batch_x是DataSet中被设置为input的field；batch_y是DataSet中被设置为target的field。  
    两个dict中的key就是DataSet中的key，value会根据情况做好padding的tensor。
(2)会将batch_x, batch_y中tensor移动到model所在的device  
(3)根据model.forward的参数列表, 从batch_x中取出需要传递给forward的数据。  
(4)获取model.forward的输出结果pred_dict，并与batch_y一起传递给loss函数, 求得loss  
(5)对loss进行反向梯度并更新参数  
(6) 如果有验证集，则需要做验证  
    tester = Tester(model, dev_data，metric)  
    eval_results = tester.test()  
(7) 如果eval_results是当前的最佳结果，则保存模型。  
```

#### 其他
Trainer中还提供了"预跑"的功能。该功能通过check_code_level管理，如果check_code_level为-1，则不进行"预跑"。

check_code_level=0，1，2代表不同的提醒级别。
目前不同提醒级别对应的是对DataSet中设置为input或target但又没有使用的field的提醒级别。
0是忽略(默认)；1是会warning发生了未使用field的情况；2是出现了unused会直接报错并退出运行

"预跑"的主要目的有两个:
- 防止train完了之后进行evaluation的时候出现错误。之前的train就白费了
- 由于存在"键映射"，直接运行导致的报错可能不太容易debug，通过"预跑"过程的报错会有一些debug提示

"预跑"会进行以下的操作：
- 使用很小的batch_size, 检查batch_x中是否包含Model.forward所需要的参数。只会运行两个循环。
- 将Model.foward的输出pred_dict与batch_y输入到loss中， 并尝试backward. 不会更新参数，而且grad会被清零
                  如果传入了dev_data，还将进行metric的测试
- 创建Tester，并传入少量数据，检测是否可以正常运行

"预跑"操作是在Trainer初始化的时候执行的。

正常情况下，应该不需要改动"预跑"的代码。但如果你遇到bug或者有什么好的建议，欢迎在开发群或者github提交issue。