matlab-import-external-ai-model

将深度学习模型导入 MATLAB

将训练好的 PyTorch、ONNX 或 Keras 3 模型作为 dlnetwork 对象导入 MATLAB，并验证数值正确性。

适用情况

• 用户想从 PyTorch、ONNX 或 Keras/TensorFlow 导入深度学习模型
• 用户有要导入 MATLAB 的 .pt2、.pt、.onnx 或 .keras 文件
• 用户提到 importNetworkFromPyTorch、importNetworkFromONNX、importNetworkFromKeras 或 importNetworkFromTensorFlow
• 用户提到 torch.export.export、torch.jit.trace、PyTorchInputSizes、InputDataFormats 或 matlabsaver
• 用户遇到导入错误、不支持的算子警告、网络未初始化或导入后可学习参数为 0
• 用户想验证导入的模型是否与源框架的输出一致

不适用情况

• 将 MATLAB 网络导出到 ONNX/PyTorch（使用 exportONNXNetwork / exportNetworkToPyTorch）
• 导入后训练或微调 — 使用 /matlab-train-network
• 部署到嵌入式硬件 — 使用 /matlab-deploy-embedded-ai
• 导入后的 Simulink 集成（Agent 无需指导也能很好地处理）

路由：选择哪个框架？

Q: What format is the source model?
 |
 +-- .pt2 (PyTorch exported program) ──────────> PYTORCH IMPORT below
 +-- .pt (PyTorch traced model) ───────────────> PYTORCH IMPORT below
 +-- .onnx ────────────────────────────────────> ONNX IMPORT below
 +-- .keras / TensorFlow 2.16+ / matlabsaver ──> KERAS IMPORT below
 +-- Unknown ("import my model") ──────────────> Ask: framework? file extension?

---

导入 PyTorch

完整流程：从 PyTorch 导出 → 导入 MATLAB → 验证数值。

确定起点

用户拥有	操作
PyTorch 模型（代码或已保存模型）	先导出为 .pt2 → 参阅 references/pytorch-export-guidance.md
.pt2 文件（导出的程序）	直接导入（见下文）
.pt 文件（跟踪模型）	使用输入尺寸导入（见下文）

始终优先选择 .pt2，而不是 .pt。 如果用户有跟踪模型，建议先使用 torch.export.export 重新导出。只有在无法重新导出时才使用跟踪模型路径。

导入 .pt2（导出的程序）

net = importNetworkFromPyTorch("model.pt2");

无需输入尺寸参数 — 形状信息已嵌入 .pt2 文件中。

导入 .pt（跟踪模型）

net = importNetworkFromPyTorch("model.pt", ...
    PyTorchInputSizes=[1 3 224 224]);

跟踪模型必须指定 PyTorchInputSizes。请按 PyTorch 的维度顺序指定尺寸。多个输入时使用元胞数组：{[1 3 256 256], [1 10]}。

名称-值参数

参数	使用时机
PyTorchInputSizes	跟踪模型（.pt）必需。 .pt2 无需指定
Namespace	控制自动生成的自定义层文件的存储位置
PreferredNestingType	选择 "networklayer"（默认值）或 "customlayer"

PyTorch 中的关键错误

错误	正确做法
使用 InputShape 名称-值参数	此参数不存在 — .pt 使用 PyTorchInputSizes，.pt2 无需指定
使用 PackageName 名称-值参数	已弃用 — 请使用 Namespace
导出前未调用 model.to("cpu")	导出前始终调用 model.to("cpu")
导出前未检查 PyTorch 版本	断言 torch.__version__ 以 "2.8" 开头
为 .pt2 传入 PyTorchInputSizes	没有必要 — .pt2 已嵌入形状信息，请省略此参数
猜测未知模型的输入尺寸	始终向用户询问确切的输入维度
假定 net.InputNames 与 forward() 的顺序一致	导入器可能会重新排序 — 始终检查 net.InputNames

PyTorch 约定

• 导出前始终调用 model.to("cpu") 和 model.eval()
• 将模型导出为 .pt2 前，始终确认 PyTorch 版本为 2.8
• 切勿猜测输入尺寸 — 请询问用户或检查模型
• 自定义层的存储位置请使用 Namespace，而非 PackageName
• 优先选择 .pt2，而不是 .pt — 建议使用 torch.export.export，而非 torch.jit.trace

PyTorch 参考资料

• references/pytorch-export-guidance.md — Python 端的完整导出流程
• references/pytorch-import-guidance.md — 两种格式的 MATLAB 详细导入说明
• references/pytorch-numeric-validation.md — 维度转换和容差比较
• references/pytorch-placeholder-guidance.md — 在自定义层中实现不支持的算子
• scripts/validateImportedNetwork.m — 使用 .npy 参考数据对数值进行验证的辅助函数

---

ONNX 导入

使用 importNetworkFromONNX 导入 ONNX 模型、诊断问题并验证数值。

工作流

1. IMPORT  → importNetworkFromONNX with appropriate NVPs
2. DIAGNOSE → Check initialization, custom layers, warnings
3. RESOLVE  → Fix issues (InputDataFormats, placeholder functions)
4. VERIFY   → Compare outputs against ONNX Runtime (if installed)

重要：第 3 步后切勿重新导入。 重新导入会重新生成 +ops/ 并覆盖所有自定义实现。

导入

net = importNetworkFromONNX("model.onnx");

如果已知输入格式：

net = importNetworkFromONNX("model.onnx", InputDataFormats="BCSS");

诊断与解决

如果 net.Initialized 为 false，请读取输入形状，并使用 InputDataFormats 重新导入：

net = importNetworkFromONNX("model.onnx");
if ~net.Initialized
    inputLayer = net.Layers(1);
    fprintf("NumDims: %d\n", inputLayer.NumDims);
end

InputDataFormats 参考

字符：B（批次）、C（通道）、S（空间）、T（时间）、U（未指定）。

ONNX 输入形状	InputDataFormats
[N, C, H, W]	"BCSS"
[N, C]	"BC"
[N, T, C]	"BTC"
[N, C, T]	"BCT"

对照 ONNX Runtime 验证

如果用户的 Python 环境中已安装 onnxruntime，请比较输出。如果未安装，则跳过，不要要求用户安装。

try
    ort = py.importlib.import_module("onnxruntime");
    ortAvailable = true;
catch
    ortAvailable = false;
end

完整的比较流程请参见 references/onnx-validation-workflow.md。

ONNX 常见关键错误

错误做法	正确方法
使用 importONNXNetwork 或 importONNXLayers	这是旧版 API——始终使用 importNetworkFromONNX
实现占位内容后重新导入	只导入一次，然后再修改。切勿重新导入。
随意猜测 InputDataFormats	先从未初始化的网络读取输入形状
ORT 可用时跳过数值验证	如果已安装，请对照 ONNX Runtime 进行比较

ONNX 约定

• 始终使用 importNetworkFromONNX——切勿使用旧版 API
• 导入后对照 ONNX Runtime 进行数值验证（如果已安装）
• 修改网络或实现占位内容后，切勿重新导入
• 使用带有显式格式字符串的 dlarray：dlarray(data, "SSCB")
• 对 float32 报告最大绝对差值，并断言容差 < 1e-4

ONNX 参考

• references/onnx-validation-workflow.md — 包括多输出模型在内的完整 ORT 比较流程

---

Keras 导入

以完整的层结构和可学习参数导入 Keras 3 / TensorFlow 2.16+ 模型。

决策树

Q1: What MATLAB release is available?
 +-- R2026a or newer ──> PATH 1 (matlabsaver + importNetworkFromKeras)
 +-- R2025b or older ──> Q2
      Q2: Does the model use Keras 3-specific features? (keras.ops, multi-backend)
       +-- No (standard layers) ──> PATH 2 (tf_keras downgrade)
       +-- Yes ────────────────────> PATH 3 (ONNX export fallback)

路径 1：matlabsaver + importNetworkFromKeras（R2026a+）

Python：

import matlabsaver
matlabsaver.save_for_matlab(model, "exportedModelFolder")

应用针对 Keras 3.10+ 兼容性的 config.json 补丁（参见 references/keras-matlabsaver-workflow.md）。

MATLAB：

net = importNetworkFromKeras("exportedModelFolder");
assert(numel(net.Learnables.Value) > 0, "Import failed: 0 learnables")

路径 2：降级 tf_keras（R2026a 之前，仅限标准层）

Python：

import os
os.environ["TF_USE_LEGACY_KERAS"] = "1"  # MUST be before importing TensorFlow
import tf_keras as keras
model.save("savedModelFolder")

MATLAB：

net = importNetworkFromTensorFlow("savedModelFolder");

路径 3：导出为 ONNX（后备方案）

Python 环境中需要安装 tf2onnx：pip install tf2onnx

Python：

model.export("exportedModel.onnx", format="onnx")

MATLAB：

net = importNetworkFromONNX("exportedModel.onnx");

Keras 常见关键错误

错误做法	正确方法
importNetworkFromKeras 因 "Brace indexing..." 而失败	Keras 3.10+ 更改了 config.json——应用补丁（参见参考文档）
执行 model.export("folder") 后调用 importNetworkFromTensorFlow	缺少 keras_metadata.pb → 可学习参数数量为 0。改用 matlabsaver
在 import tensorflow 后设置 TF_USE_LEGACY_KERAS=1	必须在任何 TF 导入之前设置
使用已弃用的 importKerasNetwork	使用 importNetworkFromKeras（R2026a+）或路径 2/3

Keras 约定

• 始终验证导入的网络具有非零数量的可学习参数
• 始终先检查 MATLAB 版本，再选择导入路径
• 优先选择路径 1 > 路径 2 > 路径 3（按保真度排序）
• 导入后报告层数和可学习参数数量

Keras 参考

• references/keras-matlabsaver-workflow.md — R2026a+ 的完整 matlabsaver 流程
• references/keras-tf-keras-downgrade.md — R2026a 之前版本的 tf_keras 设置

---

主要功能

功能	框架	用途
importNetworkFromPyTorch	PyTorch	将 .pt2 或 .pt 导入为 dlnetwork
importNetworkFromONNX	ONNX	将 .onnx 导入为 dlnetwork
importNetworkFromKeras	Keras	将 Keras 3 文件夹导入为 dlnetwork（R2026a+）
importNetworkFromTensorFlow	TF/Keras	将 TF SavedModel 导入为 dlnetwork
torch.export.export	PyTorch	将模型导出为 .pt2（Python）
matlabsaver.save_for_matlab	Keras	将 Keras 3 导出为 MATLAB 格式（Python）
predict	All	对导入的 dlnetwork 运行推理
dlarray	All	用于深度学习的带标签多维数组

---

版权所有 2026 The MathWorks, Inc.

---