matlab-deploy-embedded-ai

面向工程系统的嵌入式 AI

使用 MATLAB® 和 Simulink® 将 AI 模型部署到嵌入式硬件。本技能 专为 MATLAB R2026a 编写，使用该版本中引入的 API、函数和工作流。 涵盖完整生命周期：模型创建或导入、验证、压缩、系统级仿真，以及 面向资源受限目标的代码生成。

要求使用 MATLAB R2026a 或更高版本。核心工具箱：Deep Learning Toolbox、Statistics and Machine Learning Toolbox、MATLAB Coder、Embedded Coder、Simulink 和 Fixed-Point Designer。工作流所需的支持包将在环境发现阶段检查。必须提供 MATLAB 和 Simulink Agentic Toolkits， 以便 Agent 通过 MCP 工具操控实时 MATLAB 和 Simulink 会话。

适用场景

• 将训练好的神经网络（MATLAB 原生模型或导入的模型）部署到嵌入式硬件
• 从深度学习模型生成面向 ARM Cortex-M/A/R、x86 或 GPU 目标的 C 或 CUDA 代码
• 将导入的 PyTorch、ONNX、TensorFlow 或 LiteRT 模型部署到嵌入式目标（导入步骤由 /matlab-import-external-ai-model 处理）
• 压缩 AI 模型（量化、剪枝、投影），使其适用于资源受限硬件
• 将 AI 推理集成到 Simulink 系统模型中，以便在代码生成前进行闭环仿真
• 将 loadPyTorchExportedProgram、importNetworkFromPyTorch、importNetworkFromONNX、importNetworkFromTensorFlow、dlquantizer、exportNetworkToSimulink 或 Embedded Coder 与 AI 模型搭配使用
• 在 MathWorks 原生代码生成与直接 PyTorch/LiteRT 代码生成之间进行选择

不适用场景

• 纯粹出于研究目的训练模型，且没有部署目标——直接使用 Deep Learning Toolbox 文档
• 部署到云端／服务器端点（没有嵌入式目标）——使用 MATLAB Production Server 或 MATLAB Compiler SDK
• 使用非神经网络的经典机器学习模型（决策树、SVM、集成模型）——直接使用 Statistics and Machine Learning Toolbox 的代码生成工作流。注意：fitcnet／fitrnet 神经网络模型属于本技能的适用范围
• 为非 AI Simulink 模型生成代码——使用标准 Embedded Coder 工作流
• 在没有嵌入式部署目标的情况下转换模型格式（例如，仅将 ONNX 转为 MATLAB 以便在桌面端推理）

工作流模式选择

本技能使用两种部署模式：

• 模式 1 — MATLAB 网络代码生成： 导入或构建 dlnetwork，可选择进行 压缩，然后通过 MATLAB Coder 生成 C/C++，或导出到 Simulink。 参见 references/pattern1/workflow.md。
• 模式 2 — PyTorch/LiteRT 直接代码生成： 直接加载 PyTorch（.pt2）或 LiteRT （.tflite）模型，无需转换为 dlnetwork 即可生成 C/C++。 参见 references/pattern2/workflow.md。

决策树

选择外部模型的主要依据：部署能力 + 硬件类别。

Q1: Where does the AI model come from?
 |
 +-- Trained in MATLAB, or requires training in MATLAB -------> Pattern 1
 |
 +-- External framework (PyTorch, TF, ONNX, Keras) --> Q2
      |
      Q2: Does the deployment need any of these?
       |  - Quantization (INT8 via dlquantizer)
       |  - Pruning or projection
       |  - Weight inspection / modification
       |  - exportNetworkToSimulink integration
       |
       +-- YES --> Pattern 1 (import as dlnetwork)
       |
       +-- NO ---> Q3
            |
            Q3: What is the deployment target?
             |
             +-- Cortex-M: Pattern 1
             |     (compression and Simulink verification typically needed)
             |
             +-- x86 / GPU:
             |     +-- PyTorch (.pt2) or LiteRT (.tflite) --> Pattern 2
             |     +-- ONNX, TF, Keras --> Pattern 1 (convert to ONNX recommended)
             |
             +-- Cortex-A/R:
                   +-- Small model --> Pattern 1
                   |     (import as dlnetwork, then codegen)
                   +-- Large model:
                        +-- PyTorch (.pt2) or LiteRT (.tflite) --> Pattern 2
                        +-- ONNX, TF, Keras --> Pattern 1 (convert to ONNX recommended)

模式摘要

模式	适用场景	主要工具链
1 — MATLAB 网络代码生成	在 MATLAB 中训练的模型，或需要压缩／量化／导出到 Simulink／检查权重的外部模型，或面向 Cortex-M 的目标	MATLAB Coder™ / Embedded Coder™
2 — PyTorch/LiteRT 直接代码生成	面向 x86/GPU/Cortex-A 目标的外部 PyTorch（.pt2）或 LiteRT（.tflite）模型；无需压缩即可更快生成 C 代码	MATLAB Coder™ + PyTorch & LiteRT SPKG

模式 2 生成的 C 代码可移植到任何目标，但 Cortex-M 部署通常需要模式 1 的能力（压缩、Simulink 验证）。

导入步骤（模式 1）： 如需导入 PyTorch/ONNX/Keras/TensorFlow 模型，请使用 /matlab-import-external-ai-model。在导入完成后，本技能将接手处理压缩、Simulink 集成和代码生成阶段。

模式 1 与模式 2 的能力对比

能力	模式 1（dlnetwork）	模式 2（PyTorch/LiteRT 直连）
C 代码生成	是	是
目标平台：Cortex-M、Cortex-A/R、x86、GPU	是	是
权重检查／修改	是	否
dlquantizer（INT8）	是	否
投影（compressNetworkUsingProjection）	是	否
剪枝	是	否
Simulink 集成	是（exportNetworkToSimulink）	是（PyTorch SPKG Simulink 模块）
组合压缩	是	否
生成首份 C 代码的速度	较慢	较快

**经验法则：**如果需要压缩、量化或检查权重，或者使用 exportNetworkToSimulink，又或者模型已经是 dlnetwork，或目标平台是 Cortex-M，请选择模式 1。如果模型已经是 PyTorch（.pt2）或 LiteRT（.tflite）格式，且希望不进行压缩、以更短路径生成 C 代码，请选择模式 2。

**统计／机器学习模型（fitrnet/fitcnet）：**这类模型遵循模式 1，但有自己的 Simulink 集成路径。请使用 Statistics and Machine Learning Toolbox 库中的 RegressionNeuralNetwork Predict 模块（适用于 fitrnet）或 ClassificationNeuralNetwork Predict 模块（适用于 fitcnet）——不要使用 exportNetworkToSimulink（它仅适用于 dlnetwork）。使用 Simulink.SimulationInput 以编程方式配置仿真。

通用起始步骤：前提条件

无论采用哪种模式，在进入特定模式的阶段（从阶段 1 开始）之前，都务必先完成以下两个前提步骤：

1. 环境发现（静默）：加载 references/shared/environment-setup.md
2. 项目发现（交互式）：加载 references/shared/project-discovery.md

项目发现会通过上方的决策树确定工作流模式。

不要使用（旧版函数）

旧版	现代替代项
trainNetwork / train（用于 DL）	trainnet
DAGNetwork / SeriesNetwork / network	dlnetwork
taylorPrunableNetwork / updateScore / updatePrunables	compressNetworkUsingTaylorPruning（使用 trainnet 训练时）；自定义训练循环请使用 taylorPrunableNetwork
csvread / xlsread	readmatrix / readtable
datenum	datetime

有关旧版导入函数（importONNXNetwork、importKerasNetwork 等），请参阅 /matlab-import-external-ai-model，其中涵盖了所有模型导入工作流。

全局规则

建议模式与执行模式

根据用户意图区分以下两种模式：

• 建议（“我应该如何着手？”、“使用什么工作流？”、“选择哪种模式？”）：直接回答路线选择问题——说明推荐的模式、解释原因，并概述高层步骤。不要进入环境发现流程，也不要开始询问前提问题。给出建议后，询问用户是否要开始执行。
• 执行（“部署我的模型”、“带我一步步完成”、“编写脚本”）：进入完整的前提流程（环境发现 → 项目发现 → 分步执行各阶段）。

始终

• 在任何工作流步骤之前，通过 detect_matlab_toolboxes 检查工具箱，并通过 matlabshared.supportpkg.getInstalled 检查支持包
• 如果缺少支持包，请让用户从 Add-On Explorer 下载——切勿代替用户安装
• 逐步引导用户——每次只进行一个阶段
• 使用一致的数据划分方式（例如，固定索引或存储的划分对象），以确保可复现性
• 在每个转换步骤中验证数值等效性
• 先生成 MEX 进行桌面端验证，再为目标平台生成 C 代码
• 所有推理输入均使用 single 精度
• **基于脚本执行：**对于在 MATLAB 中完成的每个工作流步骤，都要创建 .m 脚本文件，并使用 run_matlab_file 或 evaluate_matlab_code 执行。不要在未先写入脚本文件的情况下直接运行临时 MATLAB 命令。如果需要修改脚本，请编辑脚本文件并重新运行。这样用户可以清楚查看正在执行的代码，并确保结果可复现。重要：run_matlab_file 会将工作目录设置为脚本所在文件夹。始终使用 fullfile 构造绝对路径来指定模型文件、数据和保存的输出——切勿依赖 pwd 或相对路径。
• **每个工作流步骤后暂停：**每完成一个工作流步骤，都要暂停并明确询问用户是否允许继续下一步。这样用户可以阅读或检查你创建的 MATLAB 脚本、查看结果，并在继续前提出问题。
• **Deep Network Designer：**在 MATLAB 中训练、导入模型或将模型重建为原生 dlnetwork 后，使用 Deep Network Designer（deepNetworkDesigner(net)）加载模型，让用户直观检查其架构。宣布此操作，并等待用户确认后再继续。
• **数值等效性测试（导入工作流）：**对于从 PyTorch 或 ONNX 导入的模型：
  1. 使用捆绑的 Python（针对 PyTorch）或 ONNX runtime 对原始模型运行推理，以收集真实值参考数据。不要使用导入的 MATLAB 模型作为参考——在 R2026a 中，PyTorch 导入模型的自动生成自定义层可能不支持代码生成，因此可能需要原生重建模型。（ONNX 自动生成层从 R2025a 起支持代码生成，可能无需重建。）
  2. 将相同输入传入 MATLAB 原生重建模型，并与真实值进行比较
  3. 压缩后，报告相对于未压缩基线的准确度变化（MAE、最大误差、准确率下降百分比）。这些数值必须从当前运行中的变量计算得出——切勿将数值硬编码到 fprintf/disp 字符串中，否则使用不同输入或不同模型重新运行脚本时会输出过时数值。
  4. 运行测试，验证 MATLAB 中的压缩模型、Simulink 中的压缩模型和最终生成代码之间的数值等效性
• **测试数量建议：**运行数值等效性测试前，提出计划运行的测试数量并说明理由（考虑模型复杂度、输出范围、类别数等）。等待用户同意或提出修改后再继续。
• **代码生成报告：**不要自动打开代码生成报告——它会打开一个 GUI，在 Agent 工作流中没有实际用途。仅在用户明确要求时打开。
• **从 MATLAB 帮助或在线参考页面查询函数签名，不要依据本技能。**参数列表、名称-值对（NVP）默认值和支持层枚举均以 MATLAB 的 help <function> 输出和函数参考页面为准。应以这些内容为准，而不是本技能中的任何内嵌参数表——内嵌表格会随版本过时并占用上下文。本技能仅标出会实质改变操作流程的名称-值参数（例如，按准确度预算进行剪枝时的 ValidationThreshold）。查询步骤：
  1. 首先在当前 MATLAB 会话中尝试运行 help <function>。这种方式快速，并能反映实际安装的工具箱或支持包版本。
  2. 如果 help 仅返回“Run doc for more information.”之类的简短提示（支持包函数的帮助内容常会跳转至浏览器文档），则改用 Agent 的网页浏览功能，访问在线参考页面 https://www.mathworks.com/help/<product>/ref/<funcname>.html（函数名使用小写）。提取所有名称-值参数及其默认值，并以 Markdown 表格呈现，默认值须原样引用。
  3. 如果相关支持包已安装，但系统上完全找不到该函数（which <func> 返回 “not found”），则该支持包可能是旧版本构建。请让用户通过 Add-On Explorer 更新，而不要尝试绕过缺失函数。
• **压缩决策流程：**在第 5 阶段（模式 1）开始时，加载 references/pattern1/compression-decision.md，并按其中的问题流程引导用户（硬件和 Simulink 的可用性、主要目标、对重新训练的接受程度）。根据用户的回答选择压缩和代码生成路径。压缩并非必需，剪枝、投影和量化的最佳组合取决于目标——例如，对于 Cortex-M 上受延迟限制的 LSTM 模型，使用 CMSIS-DSP 的 float32 路径优于量化路径，因为 CMSIS-NN 没有循环层的 INT8 内核。

首先询问

• 每次进入下一阶段前，询问：“这一步与您的项目相关吗？”（某些阶段可能不适用）
• 数据拆分前，询问：“您已有训练集／验证集／测试集拆分吗，还是需要我来划分？”（避免覆盖用户已有的拆分）
• 选择模型前，询问：“问题类型是什么（分类／回归／序列）？有什么尺寸限制吗？”（用于确定架构）
• 使用 Simulink 前，询问：“您有现成的 Simulink 模型可供集成吗？”（用于确定是导出还是独立运行）
• 量化前，询问：“您的目标是否支持浮点运算，还是必须使用整数？”（用于确定量化路径）
• 生成代码前，询问：“目标硬件是什么？”（用于确定 Coder 配置和 CRL）
• 压缩和代码生成前（模式 1）：根据 references/pattern1/compression-decision.md 中的决策流程引导用户——硬件目标和 Simulink 可用性、主要目标、对重新训练的容忍度。用户的回答将决定要使用的压缩技术和代码替换库。即使已说明硬件目标，仍必须询问主要部署目标（闪存、SRAM、延迟、准确率），并在执行任何压缩步骤前向用户展示推荐方案以供确认。

绝不

• 一次性展示整个工作流
• 跳过环境探索或项目探索
• 在确认项目探索前打开、加载或检查用户数据
• 使用“请勿使用”部分列出的旧版函数
• 未经检查就假定工具箱或支持包可用
• 代替用户安装支持包
• 承诺不受硬件限制的性能或“随处部署”
• 生成 DAGNetwork、SeriesNetwork 或 network 对象
• 未先创建脚本文件，就直接在 MCP 服务中运行 MATLAB 命令
• 使用导入的外部模型时跳过数值等效性测试
• 未经用户明确许可就进入下一工作流步骤
• 未先根据 compression-decision.md 中的决策流程引导用户，就应用压缩
• 将导入的模型（含自定义自动生成层）用作数值基准真值——始终通过捆绑的 Python 与原始模型进行验证
• 将格式为 "CBT" 的 [C × T] 数组传递给序列模型——单序列推理时始终重塑为 [C × 1 × T]
• 将 dlnetwork 传递给 prepareNetwork——在 R2026a 中，该函数接收 dlquantizer 对象（prepareNetwork(quantObj)）并就地修改对象。旧版 net = prepareNetwork(net) 形式已不再定义

---

相关工作流（不在范围内）

本技能涵盖通过 MATLAB Coder 和 Embedded Coder 为 CPU 目标（Cortex-M、Cortex-A/R、 x86）生成 C/C++ 代码，以及通过模式 2 的 DeepLearningConfig 选项支持 GPU 目标（CUDA/TensorRT）。以下部署目标使用不同的工具链，不在本技能的涵盖范围内：

目标	工具链	说明
FPGA / SoC	HDL Coder + Deep Learning HDL Toolbox	从 dlnetwork 生成 HDL（VHDL/Verilog）
PLC	Simulink PLC Coder	从 Simulink 模型为 PLC 生成结构化文本

如果用户的目标属于上述类别，请告知他们本技能不涵盖该工作流，并推荐相应的工具链。

---

MATLAB 和 Simulink 是 The MathWorks, Inc. 的注册商标。其他商标列表请参阅 www.mathworks.com/trademarks。其他产品或品牌名称可能是其各自持有者的商标或注册商标。

版权所有 2026 The MathWorks, Inc.