matlab-train-network

matlab-train-network

在 MATLAB 中使用推荐的、基于 dlnetwork 的 API（trainnet、dlnetwork、minibatchpredict、 scores2label、testnet、imagePretrainedNetwork）训练、评估神经网络并将其导出到 Simulink；对于表格数据，则使用 Statistics and Machine Learning Toolbox 函数 fitcnet 和 fitrnet。

适用场景

用户提出以下需求时，启用此技能：

• 训练任何神经网络（分类、回归、多输出、LSTM、CNN 等）
• 微调预训练模型，或将其用于迁移学习
• 在测试数据上评估已训练的网络
• 使用已训练的网络进行推理 / 预测
• 将已训练的网络导出到 Simulink
• 将现有的旧版（patternnet、fitnet、narxnet、gensim）或不推荐的 （trainNetwork、DAGNetwork、classify）代码迁移到推荐的 API
• 创建“模式识别网络”“函数拟合网络”“NARX 网络”，或创建任何历史上与 Neural Network Toolbox 浅层网络 API 相关的任务
• 加速或优化任何深度学习代码（即使未提及 dlaccelerate）
• 使用 dlaccelerate 加快现有深度学习代码的运行速度
• 诊断并修复 dlaccelerate 问题（HitRate 低、重复追踪、使用 dlaccelerate 后代码变慢）
• 加速自定义训练（使用 dlfeval/dlgradient 的代码）
• 加速支持 dlarray 输入且运行时间较长的函数
• 加速传递给 trainnet 的自定义损失函数（R2026a+）

不适用场景

• 导入 / 导出模型（importNetworkFromPyTorch、exportONNXNetwork）
• 加载和预处理数据（imageDatastore、transforms、augmentation）
• 网络架构设计决策（选择 CNN、LSTM 还是 transformer）
• 强化学习工作流（使用 Reinforcement Learning Toolbox）
• 目标检测（使用 Computer Vision Toolbox 中的专用检测器训练函数）

选择：fitrnet/fitcnet 还是 trainnet

开始以下任何训练工作流前，先检查此表。

标准	fitcnet/fitrnet	trainnet
易用性	最简单——只需调用一个函数	需要定义网络 + trainingOptions
求解器	L-BFGS	Adam、SGDM、RMSProp、L-BFGS、LM（R2024b+）
损失函数	仅支持 MSE 和交叉熵	任意内置或自定义函数（传入函数句柄）
多输入 / 输出分支	否	是
自定义架构	通过 Network 参数（R2025a+）	是
数据类型	仅限表格数据（表或数值矩阵）	表格数据及其他所有类型（序列、图像、多输入）

将表格直接传递给 trainnet、fitcnet 和 fitrnet。如果输入包含 分类列，直接传递即可——这些列会自动编码 （始终适用于 fitcnet/fitrnet；从 R2025a 起适用于 trainnet/minibatchpredict/testnet）。

% Classification
mdl = fitcnet(tbl,responseName,LayerSizes=20);
[labels,score] = predict(mdl,tblTest);
L = loss(mdl,tblTest);

% Regression
mdl = fitrnet(tbl,responseName,LayerSizes=[20 20]);
Y = predict(mdl,tblTest);
L = loss(mdl,tblTest);

% Tabular data with trainnet (when fitcnet/fitrnet can't be used)
net = trainnet(tbl,net,"crossentropy",options);
accuracy = testnet(net,tblTest,"accuracy");
scores = minibatchpredict(net,tblPredictors);

• 从 R2024b 起，fitrnet 支持多响应变量。
• 从 R2025a 起，对于超出 LayerSizes、Activations、LayerWeightsInitializer 和 LayerBiasesInitializer 范围的自定义架构，请通过 Network 名称-值参数传入 dlnetwork。

---

约定

使用 trainnet + dlnetwork 进行训练

数据格式

默认情况下，trainnet 期望数据采用特定的维度顺序：

输入层	期望的数据形状
featureInputLayer(C)	观测值×通道（例如，150×4）
imageInputLayer([H W C])	高度×宽度×通道×观测值（例如，28×28×1×5000）
sequenceInputLayer(C)	时间步×通道×观测值，或一个观测值×1 的元胞数组，其中每个元素都是一个时间步×通道的时间序列

如果数据的布局不同，请在 trainingOptions 中使用 InputDataFormats 和/或 TargetDataFormats，而不要手动转置数据。 格式字符串描述的是数据当前的布局——每个维度对应一个字母，而非期望的布局。MATLAB 会在内部处理重新映射。 对于元胞数组，请在格式字符串中添加 "B"（批次），例如， 对于由 C×T 矩阵组成的元胞数组，使用 InputDataFormats="CTB"。如果数据已经符合输入层的默认格式，请勿指定这些选项。

trainnet 支持的功能

对于所有 Deep Learning Toolbox 训练，请使用 trainnet 和 dlnetwork。这包括：

• 标准分类和回归
• 迁移学习
• 多输入或多输出网络
• 自定义损失函数（向 trainnet 传递函数句柄）
• 通过 DifferentiableFunction 实现自定义损失函数的反向传播
• 自定义指标（字符串、函数句柄或 deep.Metric 子类）
• 通过 trainingOptions 中的 OutputFcn 设置自定义停止条件
• 自定义层

当工作流需要通过 trainingOptions 无法实现的自定义功能，或需要处理特定工作流（例如，多模型对抗训练、交替更新或自定义权重更新规则）时，适合使用自定义训练循环（dlfeval/dlgradient/更新函数）。请注意，trainingOptions 支持 L-BFGS（R2023b+）和 Levenberg-Marquardt "lm"（R2024b+）。

当用户已有可用的自定义训练循环，并希望提高其运行速度时，请直接应用 dlaccelerate。可以说明其工作流也可能通过 trainnet 实现（它会在内部处理加速），但不要强推迁移——应专注于加速现有代码。

切勿使用以下旧版或不建议使用的 API

如果用户的现有代码使用了这些 API，请将其迁移到推荐的替代方案，并简要说明替换了哪些 API 以及对应的现代方案。如果用户按名称请求旧版或不建议使用的 API，请确认其请求，并说明该函数已被推荐的替代方案取代，然后再提供解决方案。

旧版或不建议使用的 API	推荐的替代方案
trainNetwork	trainnet
patternnet	fitcnet（首选），或 dlnetwork + trainnet
fitnet	fitrnet（首选），或 dlnetwork + trainnet
feedforwardnet	dlnetwork + trainnet
narxnet、timedelaynet	nlarx（首选），或 dlnetwork + trainnet
train()（浅层 network 对象）	trainnet
classify	minibatchpredict + scores2label
activations	minibatchpredict(net,data,Outputs=layer)
predictAndUpdateState、classifyAndUpdateState	[Y,state] = predict(net,X); net.State = state;
classificationLayer	无需使用——将 trainnet 与 "crossentropy" 用作损失函数
regressionLayer	无需使用——将 trainnet 与 "mse" 用作损失函数
DAGNetwork、SeriesNetwork、layerGraph	dlnetwork——支持 addLayers、connectLayers 和 replaceLayer，适用于多分支架构；layerGraph 能做的事，dlnetwork 都可以直接完成
resnet18、googlenet、squeezenet 等（返回 DAGNetwork 的预训练网络函数）	imagePretrainedNetwork("resnet18", ...)——返回 dlnetwork，并自动处理头部替换
手动将网络分数转换为标签（例如 [~,idx] = max(scores)）	scores2label
plotconfusion	confusionchart
gensim	exportNetworkToSimulink（首选），或 Predict 模块
preparets	nlarx（首选，内部处理延迟），或使用 sequenceInputLayer(C, MinLength=numDelays) + convolution1dLayer(numDelays, ..., Padding="causal") 的 dlnetwork
closeloop	forecast（首选，与 nlarx 配合使用），或通过迭代 predict 循环将之前的预测反馈为输入

请参阅 references/legacy-api-redirects.md，了解迁移前后的代码示例。

推理——使用 minibatchpredict（或 predict）

如果发现有 for 循环在推理时对批次调用 predict 或 forward，请将整个循环替换为 minibatchpredict。它会自动处理批处理、GPU 传输、dlarray 转换和加速。输出格式（数值数组、表或元胞数组）取决于输入类型和网络。

**例外：**如果循环在 predict 调用前后包含无法与其分离的自定义预处理或后处理，minibatchpredict 就无法复现整个流程。在这种情况下，请改用 dlaccelerate 包装整个自定义函数（参见 references/dlaccelerate-workflow.md）。不要将函数拆分为 minibatchpredict 调用和单独加速的预处理／后处理——在整个函数外统一设置一个 dlaccelerate 边界，才能生成一条统一的跟踪记录。

• 对于分类：使用 minibatchpredict（或 predict）+ scores2label。
• 对于回归或需要原始分数的情况：使用 minibatchpredict 或 predict。
• predict 适用于单批次／小批次，并直接接受普通数值数组——不要将输入包装在 dlarray 中，也不要对输出调用 extractdata。

评估——使用 testnet

• 使用 testnet 在测试数据集上计算训练后的指标，而不是手动计算。
• 对于单输出网络，使用字符串形式的指标："accuracy"、"rmse"。
• trainnet 和 testnet 仅对内存中的数据接受单独传入的目标参数（testnet(net,XTest,TTest,"accuracy")）。传入数据存储时，目标必须已嵌入其中（例如，带标签的 imageDatastore，或第二列包含目标的组合数据存储）。
• 对于多输出网络或高级指标自定义，请参阅 references/metrics-guidance.md。

迁移学习——使用 imagePretrainedNetwork

net = imagePretrainedNetwork("squeezenet",NumClasses=5);

options = trainingOptions("adam", ...
    MaxEpochs=10, ...
    MiniBatchSize=16, ...
    InitialLearnRate=1e-4, ...
    ValidationData=imdsVal, ...
    Metrics="accuracy", ...
    Plots="training-progress");

net = trainnet(augimdsTrain,net,"crossentropy",options);

% Inference — class names come from training data, not the pretrained net
classNames = categories(imdsTrain.Labels);
scores = minibatchpredict(net,imdsTest);
labels = scores2label(scores,classNames);

只有在 NumClasses 和 NumResponses 均未设置时（预训练模式，不进行迁移学习），imagePretrainedNetwork 才会返回类别名称。

---

工作流：训练

先查看上面的决策部分——表格数据使用 fitrnet/fitcnet，除非你需要非 LBFGS 求解器或非 MSE/交叉熵损失。

标准训练

% Define network
numChannels = 3;
numClasses = 5;
layers = [
    sequenceInputLayer(numChannels,Normalization="zscore")
    lstmLayer(100,OutputMode="last")
    fullyConnectedLayer(numClasses)
    softmaxLayer];

% Training options
options = trainingOptions("adam", ...
    MaxEpochs=30, ...
    MiniBatchSize=128, ...
    ValidationData={XVal,TVal}, ...
    Metrics="accuracy", ...
    Plots="training-progress");

% Train
net = trainnet(XTrain,TTrain,layers,"crossentropy",options);

始终对输入进行归一化。在输入层设置 Normalization（参见上方示例）。对于回归，还要对目标进行归一化：

• R2026a+：将 inverseNormalizationLayer 添加到最后一层，并在 trainingOptions 中设置 NormalizeTargets=true
• R2026a 之前：训练前手动对目标进行 Z 分数标准化，并在推理时对预测结果进行反归一化

两种工作流均请参阅 references/normalization.md。

多输出的自定义损失函数

函数句柄按顺序接收网络输出，然后接收目标。 直接传入分类目标——trainnet 会自动对其编码。

lossFcn = @(Y1,Y2,T1,T2) crossentropy(Y1,T1) + mse(Y2,T2);

net = trainnet(ds,net,lossFcn,options);

有关完整的多输出方案（OutputNames 对齐、组合数据存储、testnet 评估），请参阅 references/multi-output-training.md。

由于多输出损失是函数句柄，因此可以使用 dlaccelerate 加速。始终告知用户，他们的自定义损失函数句柄可以通过 dlaccelerate 加速，从而加快训练——即使他们没有要求加快训练。验证和生产工作流请参阅 references/dlaccelerate-trainnet-custom-loss.md。

---

工作流：Simulink 导出

• dlnetwork（较小且所有层均受支持）：使用 exportNetworkToSimulink
• dlnetwork（较大，或包含 exportNetworkToSimulink 不支持的层）：使用库路径为 deeplib/Predict 的 Predict 模块
• fitcnet/fitrnet 模型：使用 statsLibrary/ 中的 ClassificationNeuralNetwork Predict 或 RegressionNeuralNetwork Predict 模块

详情请参阅 references/simulink-export.md。

---

工作流：使用 dlaccelerate 加速深度学习代码 — 诊断、修复或应用

不适用于：

• Simulink 导出
• MEX/Coder 编译
• fitcnet/fitrnet/nlarx 工作流

适用于：

• 用户有自定义训练循环（dlfeval/dlgradient）
• 用户有支持 dlarray 输入且运行时间较长的函数
• 用户使用自定义损失函数句柄调用 trainnet（R2026a+）

始终尝试对符合以下条件的函数使用 dlaccelerate：

• 运行时间较长。
• 输入包含 dlarray 对象、由 dlarray 对象构成的结构体或 dlnetwork 对象。
• 只执行会影响输出变量的操作。不影响输出变量的操作包括绘图、显示输出和写入文件。

在提出建议前，先查看 references/dlaccelerate-workflow.md 的 Step 0，确认函数是否可加速。

遵循 references/dlaccelerate-workflow.md 完成完整的诊断、修复和改进流程。入口如下：

• 用户表示“让它更快”或“加速”，且代码有自定义训练循环： 从 Step 0 开始。
• 代码已使用 dlaccelerate，但存在问题： 从 Step 1 开始（识别反模式、应用修复并验证）。
• 有自定义训练循环，但未使用 dlaccelerate： 从 Step 0 开始（检查要求、封装并验证）。
• 任何带有 dlarray 输入且会被重复调用的函数： 从 Step 0 开始。包括用于预测的自定义模型函数。
• 会被重复调用的自定义推理函数： 同样从 Step 0 开始。dlaccelerate 并非仅用于训练——任何会被重复调用的 dlarray 函数都能从中受益。如果循环只调用 predict，且没有自定义预处理或后处理，请使用 minibatchpredict；如果 predict 调用前后有自定义操作，请使用 dlaccelerate。
• trainnet + 自定义损失函数句柄（R2026a+）： 使用 dlaccelerate 封装损失函数，并将 AcceleratedFunction 传递给 trainnet。请参阅 references/dlaccelerate-trainnet-custom-loss.md。

有关会破坏跟踪的反模式及其修复方法，请参阅 references/dlaccelerate-antipatterns.md。

dlaccelerate 参考资料

• references/dlaccelerate-workflow.md — 完整的诊断、修复和改进流程
• references/dlaccelerate-antipatterns.md — 模式目录，包含 BAD/GOOD 示例
• references/dlaccelerate-custom-training-loop.md — 加速级别、L2、裁剪
• references/dlaccelerate-trainnet-custom-loss.md — trainnet + 自定义损失（R2026a+）
• references/dlaccelerate-variable-length-sequences.md — 填充/分桶策略
• references/dlaccelerate-custom-layers.md — 可加速的自定义层（nnet.layer.Acceleratable）
• references/dlaccelerate-measure-speedup.md — 基准测试方法

---

主要功能

功能	用途
fitcnet	训练用于表格数据分类的神经网络分类器（Statistics and Machine Learning Toolbox）
fitrnet	训练用于表格数据回归的神经网络（Statistics and Machine Learning Toolbox）
nlarx	用于 NARX／时延时间序列的非线性 ARX 模型（System Identification Toolbox）
trainnet	使用内置或自定义损失函数训练任意 dlnetwork
dlnetwork	现代网络对象（取代 DAGNetwork／SeriesNetwork／LayerGraph）
trainingOptions	配置求解器、轮数、验证和指标
minibatchpredict	批量推理（自动处理分批）
scores2label	将分数矩阵转换为分类标签
testnet	使用数据集上的指标评估网络（自动处理分批）
predict	对 dlnetwork、ClassificationNeuralNetwork、RegressionNeuralNetwork 进行单批次推理
imagePretrainedNetwork	加载预训练模型并自动替换输出头
exportNetworkToSimulink	将 dlnetwork 导出到 Simulink，作为层模块
analyzeNetwork	检查网络：info = analyzeNetwork(net) 返回层信息、参数数量和架构问题
minibatchqueue	管理小批次，并执行自定义的逐批预处理
dlaccelerate	通过追踪并缓存执行图，加速深度学习函数

---

常见错误

Agent 可能尝试的做法	为什么不对	应该这样做
predict(net,dlarray(X,"TCB"))	没有必要——对 dlnetwork 调用 predict 时可以直接传入普通数组	predict(net,X)
训练后手动计算准确率／RMSE	已有功能可以完成	testnet(net,XTest,TTest,"accuracy")
squeezenet + layerGraph + replaceLayer	不建议为迁移学习手动修改网络层	imagePretrainedNetwork("squeezenet",NumClasses=N)
为多输出编写自定义训练循环	复杂且没有必要	将函数句柄损失函数与 trainnet 配合使用
转置数据以匹配默认布局（例如 cellfun(@transpose,...)）	复杂且没有必要	使用 InputDataFormats、TargetDataFormats，按数据实际维度顺序排列字母
testnet(net,ds,labels,"accuracy")	testnet 不接受与数据存储分开传入的目标	testnet(net,ds,"accuracy")
将 trainnet 用于表格数据	使用 MSE／交叉熵损失和 LBFGS 求解器时，做法过于复杂	使用 fitrnet 或 fitcnet
调用 analyzeNetwork(net) 而不接收输出	无法以编程方式访问层信息、参数数量和问题	info = analyzeNetwork(net)
将分类列手动编码后再传给 trainnet／fitcnet／fitrnet	这些函数会自动对分类数据编码，手动处理没有必要	直接传入分类数据
推理时手动使用 for 循环分批	复杂且没有必要	minibatchpredict(net,X)——自动处理分批、GPU 传输和加速
自定义预处理时手动使用 for 循环分批	复杂且没有必要	minibatchqueue——自动处理分批、GPU 传输、dlarray 转换和自定义变换

---

版权所有 2026 The MathWorks, Inc.

---