模型存储与载入

    1.1.1 动态图存储载入体系

    为提升框架使用体验，飞桨框架2.0将主推动态图模式，动态图模式下的存储载入接口包括：

    • paddle.save

    • paddle.load

    • paddle.jit.save

    • paddle.jit.load

    本文主要介绍飞桨框架2.0动态图存储载入体系，各接口关系如下图所示：

    1.1.2 静态图存储载入体系

    静态图存储载入相关接口为飞桨框架1.x版本的主要使用接口，出于兼容性的目的，这些接口仍然可以在飞桨框架2.x使用，但不再推荐。相关接口包括：

    • paddle.static.save

    • paddle.static.load

    • paddle.static.save_inference_model

    • paddle.static.load_inference_model

    • paddle.static.load_program_state

    • paddle.static.set_program_state

    由于飞桨框架2.0不再主推静态图模式，故本文不对以上主要用于飞桨框架1.x的相关接口展开介绍，如有需要，可以阅读对应API文档。

    1.1.3 高阶API存储载入体系

    • paddle.Model.fit (训练接口，同时带有参数存储的功能)

    • paddle.Model.save

    • paddle.Model.load

    飞桨框架2.0高阶API仅有一套Save/Load接口，表意直观，体系清晰，若有需要，建议直接阅读相关API文档，此处不再赘述。

    注解

    本教程着重介绍飞桨框架2.x的各个存储载入接口的关系及各种使用场景，不对接口参数进行详细介绍，如果需要了解具体接口参数的含义，请直接阅读对应API文档。

    1.2 接口存储结果组织形式

    飞桨2.0统一了各存储接口对于同一种存储行为的处理方式，并且统一推荐或自动为存储的文件添加飞桨标准的文件后缀，详见下图：

    https://githubraw.cdn.bcebos.com/PaddlePaddle/FluidDoc/develop/doc/paddle/guides/images/save_result_format_2.0.png?raw=true

    若仅需要存储/载入模型的参数，可以使用 paddle.save/load 结合Layer和Optimizer的state_dict达成目的，此处state_dict是对象的持久参数的载体，dict的key为参数名，value为参数真实的numpy array值。

    结合以下简单示例，介绍参数存储和载入的方法，以下示例完成了一个简单网络的训练过程：

    2.1 参数存储

    参数存储时，先获取目标对象（Layer或者Optimzier）的state_dict，然后将state_dict存储至磁盘，示例如下（接前述示例）:

    1. # save
    2. paddle.save(layer.state_dict(), "linear_net.pdparams")
    3. paddle.save(adam.state_dict(), "adam.pdopt")
    1. # load
    2. layer_state_dict = paddle.load("linear_net.pdparams")
    3. opt_state_dict = paddle.load("adam.pdopt")
    5. layer.set_state_dict(layer_state_dict)
    6. adam.set_state_dict(opt_state_dict)

    若要同时存储/载入模型结构和参数，可以使用 paddle.jit.save/load 实现。

    3.1 模型&参数存储

    模型&参数存储根据训练模式不同，有两种使用情况：

    1. 动转静训练 + 模型&参数存储

    2. 动态图训练 + 模型&参数存储

    3.1.1 动转静训练 + 模型&参数存储

    动转静训练相比直接使用动态图训练具有更好的执行性能，训练完成后，直接将目标Layer传入 paddle.jit.save 存储即可。：

    一个简单的网络训练示例如下：

    1. import numpy as np
    2. import paddle
    3. import paddle.nn as nn
    4. import paddle.optimizer as opt
    6. BATCH_SIZE = 16
    7. BATCH_NUM = 4
    8. EPOCH_NUM = 4
    10. IMAGE_SIZE = 784
    11. CLASS_NUM = 10
    13. # define a random dataset
    14. class RandomDataset(paddle.io.Dataset):
    15.     def __init__(self, num_samples):
    16.         self.num_samples = num_samples
    18.     def __getitem__(self, idx):
    19.         image = np.random.random([IMAGE_SIZE]).astype('float32')
    20.         label = np.random.randint(0, CLASS_NUM - 1, (1, )).astype('int64')
    21.         return image, label
    23.     def __len__(self):
    24.         return self.num_samples
    26. class LinearNet(nn.Layer):
    27.     def __init__(self):
    28.         super(LinearNet, self).__init__()
    29.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    31.     @paddle.jit.to_static
    32.     def forward(self, x):
    33.         return self._linear(x)
    35. def train(layer, loader, loss_fn, opt):
    36.     for epoch_id in range(EPOCH_NUM):
    37.         for batch_id, (image, label) in enumerate(loader()):
    38.             out = layer(image)
    39.             loss = loss_fn(out, label)
    40.             loss.backward()
    41.             opt.step()
    42.             opt.clear_grad()
    43.             print("Epoch {} batch {}: loss = {}".format(
    44.                 epoch_id, batch_id, np.mean(loss.numpy())))
    46. # create network
    47. layer = LinearNet()
    48. loss_fn = nn.CrossEntropyLoss()
    49. adam = opt.Adam(learning_rate=0.001, parameters=layer.parameters())
    51. # create data loader
    52. dataset = RandomDataset(BATCH_NUM * BATCH_SIZE)
    53. loader = paddle.io.DataLoader(dataset,
    54.     batch_size=BATCH_SIZE,
    55.     shuffle=True,
    56.     drop_last=True,
    57.     num_workers=2)
    59. # train
    60. train(layer, loader, loss_fn, adam)

    随后使用 paddle.jit.save 对模型和参数进行存储（接前述示例）：

    1. # save
    2. path = "example.model/linear"
    3. paddle.jit.save(layer, path)

    通过动转静训练后保存模型&参数，有以下三项注意点：

    1. Layer对象的forward方法需要经由 paddle.jit.to_static 装饰

    经过 paddle.jit.to_static 装饰forward方法后，相应Layer在执行时，会先生成描述模型的Program，然后通过执行Program获取计算结果，示例如下：

    1. import paddle
    2. import paddle.nn as nn
    4. IMAGE_SIZE = 784
    5. CLASS_NUM = 10
    7. class LinearNet(nn.Layer):
    8.     def __init__(self):
    9.         super(LinearNet, self).__init__()
    10.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    12.     @paddle.jit.to_static
    13.     def forward(self, x):
    14.         return self._linear(x)

    若最终需要生成的描述模型的Program支持动态输入，可以同时指明模型的 InputSepc ，示例如下：

    1. import paddle
    2. import paddle.nn as nn
    3. from paddle.static import InputSpec
    5. IMAGE_SIZE = 784
    6. CLASS_NUM = 10
    8. class LinearNet(nn.Layer):
    9.     def __init__(self):
    10.         super(LinearNet, self).__init__()
    11.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    13.     @paddle.jit.to_static(input_spec=[InputSpec(shape=[None, 784], dtype='float32')])
    14.     def forward(self, x):
    15.         return self._linear(x)

    Layer更准确的语义是描述一个具有预测功能的模型对象，接收输入的样本数据，输出预测的结果，而loss计算是仅属于模型训练中的概念。将loss计算的实现放到Layer.forward方法中，会使Layer在不同场景下概念有所差别，并且增大Layer使用的复杂性，这不是良好的编码行为，同时也会在最终保存预测模型时引入剪枝的复杂性，因此建议保持Layer实现的简洁性，下面通过两个示例对比说明：

    错误示例如下：

    1. import paddle
    2. import paddle.nn as nn
    4. IMAGE_SIZE = 784
    5. CLASS_NUM = 10
    7. class LinearNet(nn.Layer):
    8.     def __init__(self):
    9.         super(LinearNet, self).__init__()
    10.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    12.     @paddle.jit.to_static
    13.     def forward(self, x, label=None):
    14.         out = self._linear(x)
    15.         if label:
    16.             loss = nn.functional.cross_entropy(out, label)
    17.             avg_loss = nn.functional.mean(loss)
    18.             return out, avg_loss
    19.         else:
    20.             return out

    正确示例如下：

    1. import paddle
    2. import paddle.nn as nn
    4. IMAGE_SIZE = 784
    5. CLASS_NUM = 10
    7. class LinearNet(nn.Layer):
    9.         super(LinearNet, self).__init__()
    10.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    12.     @paddle.jit.to_static
    13.     def forward(self, x):
    14.         return self._linear(x)
    1. 如果你需要存储多个方法，需要用 paddle.jit.to_static 装饰每一个需要被存储的方法。

    注解

    只有在forward之外还需要存储其他方法时才用这个特性，如果仅装饰非forward的方法，而forward没有被装饰，是不符合规范的。此时 paddle.jit.save 的 input_spec 参数必须为None。

    示例代码如下：

    存储的模型命名规则：forward的模型名字为：模型名+后缀，其他函数的模型名字为：模型名+函数名+后缀。每个函数有各自的pdmodel和pdiparams的文件，所有函数共用pdiparams.info。上述代码将在 example.model 文件夹下产生5个文件： linear.another_forward.pdiparams、 linear.pdiparams、 linear.pdmodel、 linear.another_forward.pdmodel、 linear.pdiparams.info

    3.1.2 动态图训练 + 模型&参数存储

    动态图模式相比动转静模式更加便于调试，如果你仍需要使用动态图直接训练，也可以在动态图训练完成后调用 paddle.jit.save 直接存储模型和参数。

    同样是一个简单的网络训练示例：

    1. import numpy as np
    2. import paddle
    3. import paddle.nn as nn
    4. import paddle.optimizer as opt
    5. from paddle.static import InputSpec
    7. BATCH_SIZE = 16
    8. BATCH_NUM = 4
    9. EPOCH_NUM = 4
    11. IMAGE_SIZE = 784
    12. CLASS_NUM = 10
    14. # define a random dataset
    15. class RandomDataset(paddle.io.Dataset):
    16.     def __init__(self, num_samples):
    17.         self.num_samples = num_samples
    19.     def __getitem__(self, idx):
    20.         image = np.random.random([IMAGE_SIZE]).astype('float32')
    21.         label = np.random.randint(0, CLASS_NUM - 1, (1, )).astype('int64')
    22.         return image, label
    24.     def __len__(self):
    25.         return self.num_samples
    27. class LinearNet(nn.Layer):
    28.     def __init__(self):
    29.         super(LinearNet, self).__init__()
    30.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    32.     def forward(self, x):
    33.         return self._linear(x)
    35. def train(layer, loader, loss_fn, opt):
    36.     for epoch_id in range(EPOCH_NUM):
    37.         for batch_id, (image, label) in enumerate(loader()):
    38.             out = layer(image)
    39.             loss = loss_fn(out, label)
    40.             loss.backward()
    41.             opt.step()
    42.             opt.clear_grad()
    43.             print("Epoch {} batch {}: loss = {}".format(
    44.                 epoch_id, batch_id, np.mean(loss.numpy())))
    46. # create network
    47. layer = LinearNet()
    48. loss_fn = nn.CrossEntropyLoss()
    49. adam = opt.Adam(learning_rate=0.001, parameters=layer.parameters())
    51. # create data loader
    52. dataset = RandomDataset(BATCH_NUM * BATCH_SIZE)
    53. loader = paddle.io.DataLoader(dataset,
    54.     batch_size=BATCH_SIZE,
    55.     shuffle=True,
    56.     drop_last=True,
    57.     num_workers=2)
    59. # train
    60. train(layer, loader, loss_fn, adam)

    训练完成后使用 paddle.jit.save 对模型和参数进行存储：

    1. # save
    2. path = "example.dy_model/linear"
    3. paddle.jit.save(
    4.     layer=layer,
    5.     path=path,
    6.     input_spec=[InputSpec(shape=[None, 784], dtype='float32')])

    动态图训练后使用 paddle.jit.save 存储模型和参数注意点如下：

    1. 相比动转静训练，Layer对象的forward方法不需要额外装饰，保持原实现即可

    2. 与动转静训练相同，请确保Layer.forward方法中仅实现预测功能，避免将训练所需的loss计算逻辑写入forward方法

    3. 在最后使用 paddle.jit.save 时，需要指定Layer的 InputSpec ，Layer对象forward方法的每一个参数均需要对应的 InputSpec 进行描述，不能省略。这里的 input_spec 参数支持两种类型的输入：

    • InputSpec 列表

    使用InputSpec描述forward输入参数的shape，dtype和name，如前述示例（此处示例中name省略，name省略的情况下会使用forward的对应参数名作为name，所以这里的name为 x ）：

    1. paddle.jit.save(
    2.     layer=layer,
    3.     path=path,
    4.     input_spec=[InputSpec(shape=[None, 784], dtype='float32')])
    • Example Tensor 列表

    除使用InputSpec之外，也可以直接使用forward训练时的示例输入，此处可以使用前述示例中迭代DataLoader得到的 image ，示例如下：

    1. paddle.jit.save(
    2.     layer=layer,
    3.     path=path,
    4.     input_spec=[image])

    3.2 模型&参数载入

    注解

    为了规避变量名字冲突，载入之后会重命名变量。

    载入模型及参数，示例如下：

    1. import numpy as np
    2. import paddle
    3. import paddle.nn as nn
    4. import paddle.optimizer as opt
    6. BATCH_SIZE = 16
    7. BATCH_NUM = 4
    8. EPOCH_NUM = 4
    10. IMAGE_SIZE = 784
    11. CLASS_NUM = 10
    13. # load
    14. path = "example.model/linear"
    15. loaded_layer = paddle.jit.load(path)

    载入模型及参数后进行预测，示例如下（接前述示例）：

    1. # inference
    2. loaded_layer.eval()
    3. x = paddle.randn([1, IMAGE_SIZE], 'float32')
    4. pred = loaded_layer(x)

    载入模型及参数后进行调优，示例如下（接前述示例）：

    1. # define a random dataset
    2. class RandomDataset(paddle.io.Dataset):
    3.         self.num_samples = num_samples
    5.     def __getitem__(self, idx):
    6.         image = np.random.random([IMAGE_SIZE]).astype('float32')
    7.         label = np.random.randint(0, CLASS_NUM - 1, (1, )).astype('int64')
    8.         return image, label
    10.     def __len__(self):
    11.         return self.num_samples
    13. def train(layer, loader, loss_fn, opt):
    14.     for epoch_id in range(EPOCH_NUM):
    15.         for batch_id, (image, label) in enumerate(loader()):
    16.             out = layer(image)
    17.             loss = loss_fn(out, label)
    19.             opt.step()
    20.             opt.clear_grad()
    21.             print("Epoch {} batch {}: loss = {}".format(
    22.                 epoch_id, batch_id, np.mean(loss.numpy())))
    24. # fine-tune
    25. loaded_layer.train()
    26. dataset = RandomDataset(BATCH_NUM * BATCH_SIZE)
    27. loader = paddle.io.DataLoader(dataset,
    28.     batch_size=BATCH_SIZE,
    29.     shuffle=True,
    30.     drop_last=True,
    31.     num_workers=2)
    32. loss_fn = nn.CrossEntropyLoss()
    33. adam = opt.Adam(learning_rate=0.001, parameters=loaded_layer.parameters())
    34. train(loaded_layer, loader, loss_fn, adam)
    35. # save after fine-tuning
    36. paddle.jit.save(loaded_layer, "fine-tune.model/linear", input_spec=[x])

    此外， paddle.jit.save 同时保存了模型和参数，如果你只需要从存储结果中载入模型的参数，可以使用 paddle.load 接口载入，返回所存储模型的state_dict，示例如下：

    1. import paddle
    2. import paddle.nn as nn
    4. IMAGE_SIZE = 784
    5. CLASS_NUM = 10
    7. class LinearNet(nn.Layer):
    8.     def __init__(self):
    9.         super(LinearNet, self).__init__()
    10.         self._linear = nn.Linear(IMAGE_SIZE, CLASS_NUM)
    12.     @paddle.jit.to_static
    13.     def forward(self, x):
    14.         return self._linear(x)
    16. # create network
    17. layer = LinearNet()
    19. # load
    20. path = "example.model/linear"
    21. state_dict = paddle.load(path)
    23. # inference
    24. layer.set_state_dict(state_dict, use_structured_name=False)
    25. layer.eval()
    26. x = paddle.randn([1, IMAGE_SIZE], 'float32')
    27. pred = layer(x)

    如果你是从飞桨框架1.x切换到2.x，曾经使用飞桨框架1.x的fluid相关接口存储模型或者参数，飞桨框架2.x也对这种情况进行了兼容性支持，包括以下几种情况。

    飞桨1.x模型准备及训练示例，该示例为后续所有示例的前序逻辑：

    1. 同时载入模型和参数

    使用 paddle.jit.load 配合 **configs 载入模型和参数。

    如果你是按照 paddle.fluid.io.save_inference_model 的默认格式存储的，可以按照如下方式载入（接前述示例）：

    1. # save default
    2. model_path = "fc.example.model"
    3. fluid.io.save_inference_model(
    4.     model_path, ["image"], [pred], exe)
    6. # enable dynamic mode
    7. paddle.disable_static(place)
    9. # load
    10. fc = paddle.jit.load(model_path)
    12. # inference
    13. fc.eval()
    14. x = paddle.randn([1, IMAGE_SIZE], 'float32')
    15. pred = fc(x)

    如果你指定了存储的模型文件名，可以按照以下方式载入（接前述示例）：

    1. # save with model_filename
    2. model_path = "fc.example.model.with_model_filename"
    3. fluid.io.save_inference_model(
    4.     model_path, ["image"], [pred], exe, model_filename="__simplenet__")
    6. # enable dynamic mode
    7. paddle.disable_static(place)
    9. # load
    10. fc = paddle.jit.load(model_path, model_filename="__simplenet__")
    12. # inference
    13. fc.eval()
    14. x = paddle.randn([1, IMAGE_SIZE], 'float32')
    15. pred = fc(x)

    如果你指定了存储的参数文件名，可以按照以下方式载入（接前述示例）：

    1. # save with params_filename
    2. model_path = "fc.example.model.with_params_filename"
    3. fluid.io.save_inference_model(
    4.     model_path, ["image"], [pred], exe, params_filename="__params__")
    6. # enable dynamic mode
    7. paddle.disable_static(place)
    9. # load
    10. fc = paddle.jit.load(model_path, params_filename="__params__")
    12. # inference
    13. fc.eval()
    14. x = paddle.randn([1, IMAGE_SIZE], 'float32')
    15. pred = fc(x)
    1. 仅载入参数

    如果你仅需要从 paddle.fluid.io.save_inference_model 的存储结果中载入参数，以state_dict的形式配置到已有代码的模型中，可以使用 paddle.load 配合 **configs 载入。

    如果你是按照 paddle.fluid.io.save_inference_model 的默认格式存储的，可以按照如下方式载入（接前述示例）：

    1. model_path = "fc.example.model"
    3. load_param_dict = paddle.load(model_path)

    如果你指定了存储的模型文件名，可以按照以下方式载入（接前述示例）：

    1. model_path = "fc.example.model.with_model_filename"
    3. load_param_dict = paddle.load(model_path, model_filename="__simplenet__")

    如果你指定了存储的参数文件名，可以按照以下方式载入（接前述示例）：

    1. model_path = "fc.example.model.with_params_filename"
    3. load_param_dict = paddle.load(model_path, params_filename="__params__")

    注解

    一般预测模型不会存储优化器Optimizer的参数，因此此处载入的仅包括模型本身的参数。

    注解

    由于 structured_name 是动态图下独有的变量命名方式，因此从静态图存储结果载入的state_dict在配置到动态图的Layer中时，需要配置 Layer.set_state_dict(use_structured_name=False) 。

    4.2 从 paddle.fluid.save 存储结果中载入参数

    1. # save by fluid.save
    2. model_path = "fc.example.model.save"
    3. program = fluid.default_main_program()
    4. fluid.save(program, model_path)
    6. # enable dynamic mode
    7. paddle.disable_static(place)
    9. load_param_dict = paddle.load("fc.example.model.save.pdparams")

    注解

    由于 paddle.fluid.save 接口原先在静态图模式下的定位是存储训练时参数，或者说存储Checkpoint，故尽管其同时存储了模型结构，目前也暂不支持从 paddle.fluid.save 的存储结果中同时载入模型和参数，后续如有需求再考虑支持。

    4.3 从 paddle.fluid.io.save_params/save_persistables 存储结果中载入参数

    这两个接口在飞桨1.x版本时，已经不再推荐作为存储模型参数的接口使用，故并未继承至飞桨2.x，之后也不会再推荐使用这两个接口存储参数。

    对于使用这两个接口存储参数兼容载入的支持，分为两种情况，下面以 paddle.fluid.io.save_params 接口为例介绍相关使用方法：

    1. 使用默认方式存储，各参数分散存储为单独的文件，文件名为参数名

    这种存储方式仍然可以使用 paddle.load 接口兼容载入，使用示例如下（接前述示例）：

    1. # save by fluid.io.save_params
    2. model_path = "fc.example.model.save_params"
    3. fluid.io.save_params(exe, model_path)
    5. # load
    6. state_dict = paddle.load(model_path)
    7. print(state_dict)
    1. 指定了参数存储的文件，将所有参数存储至单个文件中

    目前暂时推荐你使用 接口解决此处的载入问题，需要获取原Program中的参数列表传入该方法，使用示例如下（接前述示例）：