15-Paddle 高层 API 入门：paddle.Model 的训练与评估流程

概述

前面几篇文章一直使用动态图底层训练循环：

logits=model(batch_x)loss=F.cross_entropy(logits,batch_y)loss.backward()optimizer.step()optimizer.clear_grad()

这种写法最适合理解训练机制。但当模型、数据和训练流程稳定后，Paddle 还提供了更高层的训练封装：paddle.Model。

paddle.Model可以帮助你组织：

• 模型训练。
• 模型评估。
• 模型预测。
• 优化器和损失函数配置。
• 指标管理。
• 训练日志输出。
• 模型保存。

读完本文，你应该知道何时使用paddle.Model，并能用它完成prepare -> fit -> evaluate -> predict的基本流程。

底层循环与高层 API 的区别

手写循环像手动驾驶：

你控制每一步 backward、step、clear_grad

paddle.Model像框架帮你封装常规流程：

prepare 配置训练组件 fit 执行训练 evaluate 执行评估 predict 执行预测

如果你刚学训练原理，先写底层循环；如果任务流程稳定，可以用paddle.Model提高开发效率。

基本流程：prepare、fit、evaluate、predict

高层 API 常见流程：

model=paddle.Model(network)model.prepare(optimizer,loss,metrics)model.fit(train_data,eval_data,epochs,batch_size)model.evaluate(test_data,batch_size)model.predict(test_data,batch_size)

可以理解为：

network：定义神经网络结构 Model：包装训练流程 prepare：配置优化器、损失、指标 fit：训练 evaluate：评估 predict：预测

准备网络：仍然使用 nn.Layer

paddle.Model不是替代nn.Layer，而是包装它。

importpaddleimportpaddle.nnasnnclassClassifier(nn.Layer):def__init__(self):super().__init__()self.net=nn.Sequential(nn.Linear(2,32),nn.ReLU(),nn.Linear(32,16),nn.ReLU(),nn.Linear(16,2),)defforward(self,x):returnself.net(x)

网络结构仍然由paddle.nn定义。

准备 Dataset

使用前面同样的圆形数据集：

classCircleDataset(paddle.io.Dataset):def__init__(self,num_samples,seed):super().__init__()paddle.seed(seed)self.x=paddle.rand([num_samples,2],dtype="float32")*4.0-2.0radius_square=paddle.sum(self.x**2,axis=1)self.y=(radius_square>1.0).astype("int64")def__len__(self):returnself.y.shape[0]def__getitem__(self,index):returnself.x[index],self.y[index]

创建数据：

train_dataset=CircleDataset(2048,seed=2026)val_dataset=CircleDataset(512,seed=2027)test_dataset=CircleDataset(512,seed=2028)

paddle.Model.fit()可以直接接收 Dataset，并通过batch_size参数组织 batch。

使用 prepare 配置训练组件

创建高层模型：

network=Classifier()model=paddle.Model(network)

配置优化器、损失函数、指标：

optimizer=paddle.optimizer.Adam(learning_rate=0.01,parameters=network.parameters(),)model.prepare(optimizer=optimizer,loss=paddle.nn.CrossEntropyLoss(),metrics=paddle.metric.Accuracy(),)

这里有三个组件：

• optimizer：更新参数。
• loss：计算训练损失。
• metrics：计算训练和评估指标。

注意：优化器的parameters仍然来自底层网络：

parameters=network.parameters()

使用 fit 训练模型

训练：

model.fit(train_data=train_dataset,eval_data=val_dataset,epochs=10,batch_size=64,verbose=1,)

fit会帮你完成常规训练流程：

读取 batch 前向计算 计算 loss 反向传播 优化器更新 指标统计 验证集评估 日志输出

这也是高层 API 最大的价值：减少重复模板代码。

使用 evaluate 评估模型

训练后评估测试集：

result=model.evaluate(test_data,batch_size=64,verbose=1,)print(result)

返回结果通常包含 loss 和 metrics。具体格式可根据 Paddle 版本和配置略有差异。

评估阶段由paddle.Model管理，不需要你手写model.eval()和paddle.no_grad()。

使用 predict 做预测

预测：

predictions=model.predict(test_dataset,batch_size=64,)

对于分类任务，预测结果通常是 logits 或模型输出。你可以进一步处理：

logits=predictions[0]

实际输出结构可能与版本、数据输入方式有关，使用时建议先打印：

print(type(predictions))print(len(predictions))

如果希望完全控制预测结果处理，手写动态图推理仍然更直接。

完整脚本：paddle.Model 训练分类模型

importpaddleimportpaddle.nnasnnclassCircleDataset(paddle.io.Dataset):def__init__(self,num_samples,seed):super().__init__()paddle.seed(seed)self.x=paddle.rand([num_samples,2],dtype="float32")*4.0-2.0radius_square=paddle.sum(self.x**2,axis=1)self.y=(radius_square>1.0).astype("int64")def__len__(self):returnself.y.shape[0]def__getitem__(self,index):returnself.x[index],self.y[index]classClassifier(nn.Layer):def__init__(self):super().__init__()self.net=nn.Sequential(nn.Linear(2,32),nn.ReLU(),nn.Linear(32,16),nn.ReLU(),nn.Linear(16,2),)defforward(self,x):returnself.net(x)defmain():paddle.seed(2026)train_dataset=CircleDataset(2048,seed=2026)val_dataset=CircleDataset(512,seed=2027)test_dataset=CircleDataset(512,seed=2028)network=Classifier()model=paddle.Model(network)optimizer=paddle.optimizer.Adam(learning_rate=0.01,parameters=network.parameters(),)model.prepare(optimizer=optimizer,loss=nn.CrossEntropyLoss(),metrics=paddle.metric.Accuracy(),)model.fit(train_data=train_dataset,eval_data=val_dataset,epochs=10,batch_size=64,verbose=1,)result=model.evaluate(test_dataset,batch_size=64,verbose=1,)print("test result:",result)if__name__=="__main__":main()

这段代码比手写循环短很多，但训练流程更“框架化”。

保存和加载 paddle.Model

paddle.Model支持保存训练模型：

model.save("circle_model")

加载时需要先创建同样网络和paddle.Model：

network=Classifier()model=paddle.Model(network)model.load("circle_model")

实际项目中，也可以继续使用底层方式保存：

paddle.save(network.state_dict(),"circle_model.pdparams")

如果你需要更细粒度控制，底层state_dict更透明；如果走高层流程，model.save()更方便。

高层 API 的优势

paddle.Model适合：

• 快速训练标准模型。
• 教学和演示。
• 统一训练、评估、预测流程。
• 减少手写训练循环模板。
• 配合 Paddle 高层生态组件。

它让代码更短，也减少一些重复错误，比如忘记切换评估模式、忘记关闭梯度等。

高层 API 的边界

不适合完全依赖paddle.Model的情况：

• 训练过程有多个优化器。
• 需要复杂自定义 loss。
• 每个 batch 有特殊控制流。
• GAN、强化学习、多任务训练等复杂范式。
• 需要手动控制梯度裁剪、混合精度、梯度累积细节。

这些场景更适合手写训练循环。

判断标准：

训练流程标准，用 paddle.Model 训练流程特殊，手写循环

与手写训练循环对照

手写循环：

forbatch_x,batch_yinloader:logits=network(batch_x)loss=F.cross_entropy(logits,batch_y)loss.backward()optimizer.step()optimizer.clear_grad()

高层 API：

model.prepare(optimizer,loss,metrics)model.fit(train_dataset,val_dataset,epochs=10,batch_size=64)

高层 API 并没有改变训练本质，只是把常规步骤封装起来。

常见错误

错误一：optimizer 绑定了错误参数

优化器应使用底层网络参数：

parameters=network.parameters()

错误二：prepare 没有配置 loss

训练分类模型需要配置：

loss=nn.CrossEntropyLoss()

错误三：metrics 与任务不匹配

分类任务可以用：

metrics=paddle.metric.Accuracy()

回归任务则不适合 Accuracy。

错误四：predict 输出结构没有先检查

不同输入方式下，预测输出可能是嵌套结构。先打印类型和长度，再处理。

错误五：复杂训练强行塞进高层 API

如果你发现大量逻辑绕不开fit的默认流程，说明应该回到底层训练循环。

建议练习：对比两种训练方式

1. 用手写训练循环训练同一个Classifier。
2. 用paddle.Model训练同一个Classifier。
3. 对比两种方式的代码长度。
4. 对比最终测试准确率。
5. 使用model.save()保存模型。
6. 使用model.evaluate()评估测试集。
7. 修改 metrics，观察日志输出变化。

总结

这一篇介绍了 Paddle 高层 API：

• paddle.Model(network)包装nn.Layer。
• prepare配置优化器、损失函数和指标。
• fit执行训练和验证。
• evaluate执行评估。
• predict执行预测。
• save/load可保存和加载高层模型。
• 标准任务适合高层 API，复杂训练更适合手写循环。

如果只能记住一句话，那就是：

paddle.Model不改变训练原理，它只是把常规训练、评估和预测流程封装得更简洁。