matlab-use-machine-learning-apps

Learner Apps AppController 参考

mlearnapp.internal.appcontroller.AppController 提供对 Classification Learner 和 Regression Learner 应用的编程访问。使用它与 Learner 应用交互并查询其状态。

源文件（运行时加载）：<skill-base-directory>/scripts/+mlearnapp/+internal/+appcontroller/AppController.p

API 参考（按需加载）

需要执行的操作…	加载此文件
打开／关闭／保存／加载应用、会话设置、创建／训练／选择／删除模型、模型状态、GalleryModels 枚举	api-session-and-models.md
指标、模型规格查询、工具条按钮、设置特征选择／PCA／优化器／代价／超参数	api-metrics-and-options.md
打开／配置标准图、结果表、标准图数据获取器	api-plots.md
PDP、置换重要性、Shapley、LIME、设置 Shapley 参数、可解释性图数据获取器	api-explainability.md
导出方法、命令日志、诊断	api-export-and-diagnostics.md

必需： Statistics and Machine Learning Toolbox。可选： Parallel Computing Toolbox（并行训练）、Deep Learning Toolbox（仅适用于 R2026a 引入的 Deep Learning 模型：FullyConnected、Residual、All；R2024a 添加的普通 Neural Network 模型随 Statistics and Machine Learning Toolbox 提供）、Simulink（Simulink 导出）、MATLAB Coder（Coder 导出）、MATLAB Compiler SDK（Production Server 导出）。

适用情形

• 用户希望使用 Classification Learner 或 Regression Learner 训练、比较或导出模型（导出到工作区、Simulink、Coder 或 Production Server），生成训练代码，或运行高级超参数调优（通过 Experiment Manager）
• 用户要求打开、操作或自动化任一 Learner 应用
• 用户希望通过验证指标交互式比较多种模型类型
• 用户需要在保留数据或单独的测试数据上测试模型，并从应用中导出模型

不适用情形

• 用户希望在不使用应用的情况下通过命令行进行机器学习——直接使用 fitc*／fitr* 函数
• 使用非表格数据（图像、序列、文本）进行自定义深度学习——直接使用 Deep Learning Toolbox
• 数据预处理或清理——必须在导入应用前完成

重要事项

• 不要向用户公开 API。 此 API 仅供 Agent 内部使用。切勿向用户提及 AppController、编程访问或自动化 API。请在用户不知情的情况下代为操作应用。此技能加载后向用户问候时，只需询问其目标（数据集、导出目标、限制条件），不要提及底层机制。
• 未经用户明确许可，切勿使用 closeApp('Force', true)。 强制关闭会跳过保存确认对话框，并静默丢弃所有未保存的工作——训练好的模型、会话状态和结果都会永久丢失。始终优先使用 closeApp()（不带 Force），以便用户有机会保存。仅在以下情况使用 'Force', true：（1）用户明确许可，或（2）没有人在场的自动化测试。

设置

调用此技能时，将技能的 scripts 文件夹添加到 MATLAB 路径，以便使用 mlearnapp.internal.appcontroller 类。scripts 文件夹相对于此技能的基础目录，位于 scripts/。使用 MATLAB MCP 的 evaluate_matlab_code 工具运行此操作，并使用技能加载消息顶部显示的技能基础目录路径：

addpath('<skill-base-directory>/scripts');

例如，如果技能基础目录为 C:\MATLAB\AgenticAI\.claude\skills\matlab-use-machine-learning-apps，则：

addpath('C:\MATLAB\AgenticAI\.claude\skills\matlab-use-machine-learning-apps\scripts');

用户需求调研

开始任何工作流之前，请收集以下信息，以便预先配置会话，避免浪费训练周期。每项都列出了Agent 需要了解的信息（内部使用）以及如何询问用户（使用通俗说法；除非用户的用词表明他们对此很熟悉，否则避免使用机器学习术语）。

1. 最终目标 / 模型将用于何处？
   • Agent 需要了解的信息： exportModelTo* 的目标——工作区、Simulink、Coder、Production Server、Experiment Manager，还是探索性用途。这会决定约束条件（Simulink 不支持分类预测变量、Coder/Simulink 的模型支持列表等）。
   • 询问用户： “模型最终会如何使用？例如：探索数据、生成报告或图表、在 Simulink 仿真中运行、为嵌入式设备生成 C/C++ 代码、部署为 Web 服务，或在 MATLAB 中进行预测。”
2. 验证方案。

   • Agent 需要了解的信息： 在会话启动时通过 openApp 设置，在整个会话期间固定——之后无法更改，除非启动新会话。应用默认使用 5 折交叉验证（'KFold', 5）。请根据数据集大小 × 训练成本进行选择：

     方案	适用情况	语法
     5 折交叉验证	小到中型数据（≤几千行）、速度快的模型	'KFold', 5（默认）
     20% 留出法	大型数据、速度较慢的模型（集成模型、DL、优化），或时间受限	'HoldOut', 0.2
     重代入法	用户明确希望快速迭代且不需要准确率估计（训练集准确率，结果偏乐观）	'CrossVal', 'off'

   • 询问用户： “有两件事需要确认，因为验证设置一旦开始就会固定：（1）您的数据集大约有多少行？（2）我需要考虑训练时间预算吗，还是训练时间不成问题？我会选择同时适合这两点的验证方法。”

3. 独立测试数据集。
   • Agent 需要了解的信息： 是否使用现有表格调用 importTestData，通过 TestDataFraction（例如 0.2）留出一部分数据，或完全跳过测试。测试数据不同于验证数据，只会在最终模型上使用一次。
   • 询问用户： “您是否有想留作最终检查的独立数据集？或者，我们可以留出一部分数据（比如 20%），不用于训练，只在最后使用。”
4. 性能要求。
   • Agent 需要了解的信息： 目标指标阈值（最低准确率、最高 RMSE）、预测延迟、部署吞吐量。
   • 询问用户： “模型是否需要达到特定的准确率或速度目标？例如，最低可接受准确率、每个样本的最长可接受预测时间，或在特定设备上的吞吐量。”
5. 模型大小 / 部署环境。
   • Agent 需要了解的信息： 目标环境是否为嵌入式或内存受限环境。如果是，则优先考虑紧凑型学习器（线性模型、单棵树、小型 SVM），并检查 ModelSizeMetric（通用）或 ModelSizeCoderMetric（Coder 专用）。
   • 询问用户： “模型是否需要在小型设备、嵌入式系统或内存受限的环境中运行？如果需要，我们会优先考虑更小、更简单的模型。”
6. 可解释性需求。
   • Agent 需要了解的信息： 是否应优先选择可解释的模型系列（树模型、线性模型、判别模型），以及是否应计划在训练后绘制可解释性图表（Permutation Importance、PDP、LIME、Shapley）。
   • 询问用户： “您是否需要向监管机构、审计人员或非技术相关方解释模型的决策？还是只关注原始准确率？”

根据回答从一开始就恰当地配置会话——选择合适的预测变量、验证方案、模型类型和导出路径，避免浪费训练周期。

最佳实践

数据与设置

• 测试数据拆分： 打开应用前，询问用户是否要留出一部分数据作为独立测试集。如果工作区中已有单独的测试数据集，请使用该数据集。如果没有，则在打开应用时提供使用 TestDataFraction（例如，0.2–0.25）拆分数据的选项，或让用户稍后导入测试数据。这样可确保训练后能够进行无偏评估。有关 openApp 语法和分区 NV 参数，请参阅 references/api-session-and-models.md#opening-the-app。
• 训练前检查数据： 训练模型前，检查数据是否存在潜在问题。检查以下内容：(1) 缺失值——不同模型处理方式不同，且有些模型无法处理 NaN；(2) 类别分布（分类）——使用 tabulate 或 groupcounts 检测类别不平衡；(3) 响应变量分布（回归）——检查响应变量是否存在偏度或异常值，必要时进行变换；(4) 数值预测变量中的异常值，这些值可能会影响模型性能；(5) 不变或近乎不变的预测变量，这些变量不包含有用信息。向用户报告检查结果，并据此建议预处理方法或模型选择。
• ⚠ 预处理与数据泄漏： 任何使用数据集汇总统计量的预处理操作——均值／中位数填补、基于 IQR 或 z 分数的异常值移除、标准化／归一化、目标编码等——如果在导入应用前完成，就会将验证／测试折的信息泄漏到训练数据中，导致指标过于乐观。应用不会在其交叉验证／留出折内执行这些操作（只有特征选择排序、PCA 和误分类代价矩阵会按折应用）。有关如何处理此问题的实用指南，请参阅 references/skill-guidance-details.md#preprocessing-and-data-leakage。
• 类别不平衡处理： 如果数据集存在类别不平衡（例如，90%/10% 的比例），建议：(1) 使用 ClassificationRUSBoostedEnsemble（RUSBoost），它专为不平衡数据设计，会在提升过程中对多数类进行欠采样；(2) 通过 app.setModelCostMatrix() 调整代价矩阵，加大对少数类误分类的惩罚；(3) 使用 Macro F1 或各类别指标，而不是整体准确率来评估模型质量——在类别不平衡时，准确率可能会造成误导。询问用户更重视正确预测哪个类别。

特征工程

• 特征选择与排序： 在以下情况下建议使用：(1) 数据集的预测变量较多（>20），导致训练速度慢或模型过拟合；(2) 用户希望模型更简单／更易解释；(3) 部署时必须尽量减小模型体积；(4) 已知某些预测变量无关或冗余。API：使用 app.setDefaultFeatureSelectionOptions(...) 为所有草稿模型设置选项，或使用 app.setModelFeatureSelectionOptions(...) 为特定模型设置选项。有关根据问题类型和目标选择排序方法的说明，请参阅 references/skill-guidance-details.md#feature-selection。
• PCA： 在以下情况下建议使用 PCA：(1) 预测变量高度相关（多重共线性）；(2) 数据集包含许多数值预测变量，降维可能在不损失太多信息的情况下提升训练速度；(3) 用户希望降低模型复杂度。如果可解释性至关重要，不要建议使用 PCA（PCA 成分会失去预测变量的含义）。注意：PCA 仅应用于数值预测变量——分类预测变量会保持不变，并在变换后重新拼接，因此也支持混合数据集。使用 app.setDefaultPCAOptions('OnOff', true, 'PercentVarianceExplained', 95) 为所有草稿模型设置选项，或使用 app.setModelPCAOptions('OnOff', true, 'PercentVarianceExplained', 95) 为当前／指定模型设置选项。

模型训练与选择

• 比较模型： 训练多个模型后，打开结果表（app.clickResultsTableToolstripButton()）和比较结果图（app.openCompareResultsPlot()），帮助用户并排比较模型。结果表以可排序表格的形式显示所有验证指标（以及测试指标）。比较结果图可通过单个指标的条形图，或两个坐标轴（例如，准确率与预测速度，或准确率与模型大小）直观展示模型，以便快速分析取舍。使用 app.getResultsTableData() 和 app.getCompareResultsPlotData() 以编程方式读取数据。在用户选出最佳模型之前，先建议查看这些视图，确保决策依据多项指标，而不只是准确率。有关比较结果图的配置，请参阅 references/api-plots.md#compare-results-plot-configuration-r2024b。
• 导入外部训练的模型： 询问用户是否有工作区中的预训练模型可纳入比较。支持工作区模型（R2026a+）。有关兼容性要求、验证限制和导入详情，请参阅 references/skill-guidance-details.md#importing-models。
• 超参数优化： 当默认预设效果不理想且用户有时间预算时，建议在初步模型比较之后进行优化。优化需要使用 Optimizable* 预设（例如，ClassificationOptimizableTree）——复制常规模型并不会使其具备可优化性。默认使用 'bayesopt'，迭代 30 次。仅在小范围内进行穷举搜索时使用 'grid'；在范围非常大的情况下快速探索时使用 'random'。对于时间受限的用户，设置 'HasTrainingTimeLimit', true, 'MaximumTrainingTimeInSeconds', N。更多详情请参阅 references/skill-guidance-details.md#hyperparameter-optimization。
• 并行和后台训练： 在以下情况下，建议启用并行计算（app.toggleUseParallelButton()）：(1) 数据集较大（>10K 个观测值或 >50 个预测变量）；(2) 训练多个模型或运行多次迭代的优化；(3) 使用多个折的交叉验证。当用户希望在模型训练期间继续使用 MATLAB 时，建议启用后台训练（app.toggleUseBackgroundTrainingCheckbox()）或开启并行计算（ON）（仅当用户没有 Parallel Computing Toolbox 时才会显示该复选框）。注意：并行计算需要 Parallel Computing Toolbox。
• 模型迭代工作流： 当某种模型类型显示出潜力但仍需改进时，优先手动调整（复制 → 调整 → 比较），再考虑优化。有关工作流步骤、限制（Draft 状态要求、All 预设限制）和提示，请参阅 references/skill-guidance-details.md#model-iteration。

评估与可解释性

• **导出前测试：**根据验证指标确定最佳模型后，务必询问用户是否有独立的测试数据集。在留出数据上测试可以了解模型对未见数据的泛化准确率，这比仅看交叉验证准确率更可靠。使用 app.importTestData() 加载测试数据，然后调用 app.clickTestSelectedModelToolstripButton() 进行评估。通过 app.getCurrentModelTestDataMetrics() 报告测试指标，让用户在导出前做出明智的决定。
• **只测试最佳模型：**不要在测试数据集上测试多个模型。测试集只能用于最终选定的模型，且只能使用一次，以获得无偏的泛化性能估计。在同一测试集上测试多个模型，然后选择表现最好的模型，会破坏测试集的用途——这会将测试信息泄漏到模型选择过程中，导致准确率过于乐观。如果测试结果不理想，建议用户通过验证技术（例如特征工程、超参数调优、尝试不同的模型类型）改进模型，而不是在测试集上重新测试多个模型。
• **可解释性图表：确定并测试最佳模型后，如果用户需要向利益相关者解释预测结果、在受监管领域（医疗保健、金融）进行部署、发现测试准确率异常偏高或偏低，或想找出预测因素的影响，可以建议使用可解释性图表。可用图表：置换重要性（全局、快速）、部分依赖（各预测因素的影响）、LIME（局部、针对单条观测）、Shapley（兼具全局和局部分析）。⚠ Shapley 在大型数据集或复杂模型上可能较慢——触发前务必提醒用户。**关于每种图表的决策参考、Shapley 的成本控制方法，以及如何在置换重要性与 Shapley 之间选择，请参阅 references/skill-guidance-details.md#interpretability-plots。关于 Shapley/LIME 的配置 API 和图表数据字段，请参阅 references/api-explainability.md。
• **用于模型分析的图表：**根据工作流阶段建议使用相应的图表——训练后（分类/回归）、比较模型时、针对可优化模型、神经网络 / DL、在留出数据上测试后，或进行数据探索时。关于各阶段不同用途对应的图表以及 API 方法名称，请参阅 references/skill-guidance-details.md#plots-for-model-analysis。

会话与代码导出

• 保存/加载会话（R2022a+）： 如果训练耗时较长、用户想稍后继续或分享结果，建议保存会话。完成重要工作后，在关闭前务必建议保存。有关保存/加载 API 以及阻塞对话框的解决方法，请参阅 references/skill-guidance-details.md#session-management。
• 将训练工作流导出为代码： app.clickGenerateCodeToolstripButton() 会将应用工作流转换为脚本，适用于用户想在应用之外工作、将模型集成到更大型的 MATLAB 工作流、对训练代码进行版本控制，或自动化/计划工作流的情况。如果需要将代码作为字符串，请使用 app.generateCode() 变体。该方法会生成一个 .m 训练函数，涵盖数据预处理（特征选择、PCA）、模型训练和验证。适用于所有模型类型。注意：由于 cvpartition 中的随机化，重新运行生成的脚本可能无法完全复现应用的结果。
• 以编程方式导出结果： 使用 app.exportPlotData('VariableName', 'myPlot') 将当前活动图表的数据导出到工作区，以便进一步分析。使用 app.exportPlotToFigure() 将活动图表导出为独立的 MATLAB 图窗（可用于保存为图像或自定义）。使用 app.exportResultsTableToWorkspace('VariableName', 'myResults') 或 app.exportResultsTableToFile('results.csv') 将结果表（仅可见行和列）导出到工作区或 CSV 文件。当用户想分享结果、创建自定义可视化或将发现集成到报告中时，这些方法很有用。有关完整的导出方法签名和参数，请参阅 references/api-export-and-diagnostics.md#programmatic-export-methods。

部署导出

• 导出到工作区： 使用 app.exportModelToWorkspace('MyModel')（可选择使用 'IncludeTrainingData', false 以缩小导出内容）。导出的内容（所有路径均适用）： 在整个训练集上训练的完整模型（不是交叉验证折模型），因此导出的工件始终是在所有可用训练数据上重新拟合的模型。
• 导出到 Simulink（R2024a+）： 适用于基于模型的设计／控制器在环。使用 app.exportModelToSimulink(...)。不支持分类预测变量——请尽早提醒用户。完整的约束列表和支持的模型类型，请参阅 references/skill-guidance-details.md#export-to-simulink-r2024a。exportModelToSimulink 参数表请参阅 references/api-export-and-diagnostics.md#export-model-to-simulink-r2024a。
• 导出到 Coder（R2025a+）： 适用于 C/C++ 代码生成／嵌入式目标。使用 app.exportModelToCoder(...)。约束列表和尺寸指南请参阅 references/skill-guidance-details.md#export-to-coder-r2025a。exportModelToCoder 参数表请参阅 references/api-export-and-diagnostics.md#export-model-to-coder-r2025a。
• 导出到 Experiment Manager（R2022a+）： 当用户需要更精细地控制超参数调优（可编辑搜索范围、自定义约束）时，建议使用此功能。使用 app.createExperiment(...)。必须先训练模型。有关决策逻辑（何时使用而非应用级优化、何时跳过 Learner 应用），请参阅 references/skill-guidance-details.md#export-to-experiment-manager-r2022a。
• 导出到 Production Server： 适用于 REST API／Web 服务部署。使用 app.clickExportModelToProductionServerToolstripButton()。需要 MATLAB Compiler SDK。请参阅 references/skill-guidance-details.md#export-to-production-server。

最低发行版本要求

各项功能都有最低 MATLAB 发行版本要求。在较早的发行版本中调用某项功能会报错。

功能	最低发行版本
设置优化器选项	R2019b
设置代价矩阵	R2019b
导出到 Production Server、可优化神经网络模型、分类核模型	R2021b
将会话保存到文件／从文件加载会话、特征排序、回归核模型	R2022a
结果表、偏依赖图	R2022b
创建实验（Experiment Manager）、将精简会话保存到文件、高效线性分类模型（LogisticRegression、LinearSVM、All）	R2023a
局部 Shapley、LIME、高效线性回归模型（LS、SVM、All）、可优化高效线性模型、可优化核模型	R2023b
将模型导出到 Simulink、Simulink 多模型训练预设（AllSimulink）、神经网络模型（Uni/Bi/Tri-Layered、All）	R2024a
Shapley 重要性／摘要／依赖图、结果比较图、精确率-召回率图、导出图数据、其他指标（精确率、召回率、F1 分数）	R2024b
将模型导出到 Coder、代码生成多模型训练预设（AllCodegen）、排列重要性图、ROC 曲线比较图	R2025a
从工作区导入训练好的模型	R2026a
深度学习模型（FullyConnected、Residual、All）、训练进度图、网络分析器图、导出分区和数据集	R2026a

快速参考 — 常见工作流

% 1. Open app with data
% Classification:
app = mlearnapp.internal.appcontroller.AppController.openApp('classification', Tbl, 'Response', 'KFold', 5);
% Regression:
%   app = mlearnapp.internal.appcontroller.AppController.openApp('regression', Tbl, 'Price', 'KFold', 5);

% 2. Discover available model types and create models
% IMPORTANT: Always call getAvailableModelTypes to discover exact enum names.
% Do NOT guess enum names — they vary by category and release.
% Example: Naive Bayes is 'ClassificationGaussianNaiveBayes', not 'ClassificationNaiveBayes'
available = app.getAvailableModelTypes();              % all valid for this release
% 'Category' is a case-insensitive substring filter on the enum name
% (e.g., 'Tree', 'SVM', 'Ensemble', 'KNN', 'NeuralNetwork', 'Linear', 'Kernel', 'AllSimulink', ...).
% Call getAvailableModelTypes() with no filter first if unsure which substring will match.
treeModels = app.getAvailableModelTypes('Category', 'Tree');
% For guidance on picking an All-* preset family (AllQuickToTrain vs full All vs
% family-specific like AllTrees, AllSVM, AllEnsemble, AllLinear, AllKernel, etc.),
% see references/skill-guidance-details.md#multi-train-presets-all----which-to-pick
% For model type enum names, see references/api-session-and-models.md#gallerymodels-enum-reference
app.createModelType('ClassificationAllQuickToTrain');

% 2b. (Optional) Set hyperparameters on a DRAFT model BEFORE training
% Signature: app.setModelHyperparameterOptions(modelNumber, 'Param', value, ...)
% The first argument MUST be the model number string (e.g., '2', '3.1')
app.setModelHyperparameterOptions('2', 'BoxConstraint', 10, 'KernelScale', 2);

% 3. Train and wait
app.clickTrainToolstripButton();
app.waitForTrainingToComplete();

% 4. Compare models
app.clickResultsTableToolstripButton();
app.openCompareResultsPlot();
allMetrics = app.getAllModelMetrics();

% 5. Select best model (use model number from allMetrics)
% Classification: use AccuracyMetric (or MacroF1ScoreMetric for imbalanced data)
[~, bestIdx] = max([allMetrics.AccuracyMetric]);
% Regression: use RMSEMetric (lower is better) or RSquaredMetric (higher is better)
%   [~, bestIdx] = min([allMetrics.RMSEMetric]);
app.selectModelByNumber(allMetrics(bestIdx).ModelNumber);

% 6. Test on held-out data
app.importTestData('testTable');
app.clickTestSelectedModelToolstripButton();
testMetrics = app.getCurrentModelTestDataMetrics();

% 7. Export
app.exportModelToSimulink('MyModel.slx');

% 8. Close app (use 'Force', true ONLY for automated testing — never without user permission)
app.closeApp('Force', true);

---

版权所有 2026 The MathWorks, Inc.

---