matlab-integrate-pytorch-vision

MPyReq MATLAB 接口构建器

使用 MPyReq 框架，为 Python/PyTorch 模型仓库构建 MATLAB 接口。

适用场景

• 用户要求将 MATLAB 与 Python 图像处理或计算机视觉模型（分割、深度估计、目标检测、图像生成、超分辨率、姿态估计、光流、显著性目标检测等）进行接口连接
• 用户提供视觉/图像模型的 GitHub 仓库 URL，并希望从 MATLAB 调用该模型
• 用户要求为图像/CV 模型“创建 MPyReq 封装器”或“MPyReq 演示”
• 用户希望从 MATLAB 运行可通过 pip 安装的视觉模型库（例如 Cellpose、SAM2、Depth-Pro、BiRefNet、StarDist）

不适用场景

• 通用 Python-MATLAB 接口（不涉及视觉/图像模型）
• 非视觉模型：NLP、音频、表格数据、强化学习、时间序列
• 模型部署、容器化或推理服务
• 不依赖 Python 的纯 MATLAB 图像处理工作流
• 创建 Python 代码（此技能创建的是调用 Python 的 MATLAB 代码）

前提条件：MPyReq 已添加到 MATLAB 路径

在生成任何演示脚本之前，请确认 MPyReq 可用。通过 MATLAB MCP 服务（如果可用）运行 which MPyReq，或请用户确认。

如果 MPyReq 不在 MATLAB 路径中：

1. 下载 MPyReq，从 MATLAB File Exchange 获取： https://mathworks.com/matlabcentral/fileexchange/182230-matlab-based-python-requirements-manager
2. 安装 — 可以选择以下任一方式：
   • 在 MATLAB 中打开下载的 .mltbx 文件（双击），MATLAB 会自动将其安装为 MATLAB Add-On；或
   • 解压文件，并将包含 MPyReq.m 的文件夹添加到 MATLAB 路径：

     addpath("/path/to/mpyreq");
     savepath; % persist across sessions
     

3. 验证：在 MATLAB 中运行 which MPyReq — 应返回 MPyReq.m 的路径。

确认 MPyReq 已添加到路径后，才能继续生成演示。

输入

请向用户询问：

1. GitHub 仓库 URL — 要连接的 Python 模型仓库
2. 模型的用途（可选）— 帮助确定合适的推理示例

步骤 1：分析仓库

获取并分析 GitHub 仓库，以确定：

• Python 版本要求 — 检查 setup.py、setup.cfg、pyproject.toml 或 README，了解所需的 Python 版本。若未指定，默认为 "3.12"。若项目需要较旧版本的兼容性，则使用 "3.11"。
• 安装方式 — 确定项目的安装方式：
  • 如果使用 torch.hub.load()：只需将 torch 和 torchvision 作为 pip 软件包（模型会自动下载）
  • 如果是可通过 pip 安装的软件包：使用 MPyReq.pipPackage()
  • 如果是非打包的 git 仓库：使用 MPyReq.gitrepo()；若存在 requirements.txt，还需使用 MPyReq.requirementTextFile()
  • 如果需要 pip install git+<url>：使用 MPyReq.pipPackage("git+<url>", Name="<ProjectName>")
• 其他依赖项 — 所需的其他 pip 软件包（例如 torch、torchvision 等）
• 模型权重 — 确定权重的加载方式：
  • torch.hub.load() — 权重会自动下载，无需使用 MPyReq.weights()
  • 直接下载 URL — 使用包含检查点 URL 的 MPyReq.weights()
  • HuggingFace .from_pretrained() — 权重会通过库自动下载
• 推理示例 — 在 README 或示例脚本中找到主要的推理/预测代码
• 预处理要求 — 检查模型是否需要特定的输入归一化（例如 ImageNet 均值/标准差）、调整大小或中心裁剪

步骤 2：生成 MPyReq 设置脚本

创建一个 MATLAB .m 文件，用于设置 Python 环境。遵循演示文件中的以下模式：

必须：安装文件夹设置

每个生成的脚本都必须以 MPyReq.setInstallFolder() 开头。此调用会告知 MPyReq 在哪里下载 Python、软件包和模型权重。如果没有此调用，MPyReq 会显示一个 GUI 对话框，从而阻止非交互式执行。还应包含 MPyReq.autoAcceptDownloadPrompts(true)，以避免出现交互式确认提示。

% Set installation folder (SSD recommended, ~15+ GB free space)
% Change this path to a suitable location on your machine
MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);

模式 A：简单的 pip 软件包（如 Cellpose）

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.12");
MPyReq.pipPackage("<package_name>");

模式 B：作为 pip 软件包的 Git 仓库（如 SAM2）

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.12");
MPyReq.pipPackage("git+https://github.com/<org>/<repo>.git", Name="<RepoName>");

模式 C：Git 仓库 + requirements.txt（如 VGGT、BiRefNet）

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.11");
MPyReq.gitrepo("https://github.com/<org>/<repo>.git");
reqTxt = MPyReq.pathTo("<repo>") + filesep + "requirements.txt";
MPyReq.requirementTextFile(reqTxt, Name="<repo>Packages");

模式 D：torch.hub 模型（如 DINOv2、ResNet 等）

当模型使用 torch.hub.load() 时，无需克隆 Git 仓库或下载权重，只需安装 torch/torchvision：

MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("3.12");
MPyReq.pipPackage("torch");
MPyReq.pipPackage("torchvision");
% Model loads automatically via torch.hub:
model = py.torch.hub.load('org/repo', 'model_name');

权重下载模式

仅在权重未通过 torch.hub.load() 或 .from_pretrained() 处理时才需要：

MPyReq.weights("<weights_url>", DownloadTo=MPyReq.pathTo("<RepoName>") + filesep + "checkpoints");

第 3 步：创建 MATLAB 推理接口

将 Python 推理示例转换为 MATLAB。转换规则和模式请参阅以下资源文件：

• references/python_matlab_conversions.md — Python 到 MATLAB 的语法转换表
• references/image_conversion_patterns.md — 图像张量转换（MATLAB 与 Python 之间）、维度重排和显示模式

第 4 步：组装最终脚本

创建单个 demo<ModelName>.m 文件，并划分清晰的章节：

%% Setup Python Environment
% Start with clean state (only if switching projects)
% terminate(pyenv); clear MPyReq

% Set installation folder (SSD recommended, ~15+ GB free space)
% Change this path to a suitable location on your machine
MPyReq.setInstallFolder(fullfile(tempdir, "MPyReq"));
MPyReq.autoAcceptDownloadPrompts(true);
MPyReq.python("<version>");
% ... package installation calls ...

%% Reference Python Code
%{
<paste the original Python inference code as a comment block>
%}

%% Load Model
% ... model loading code ...

%% Run Inference
% ... load input, run model, extract results ...

%% Visualize Results
% ... display/plot results ...

第 5 步：使用 MATLAB MCP Server 测试

检查当前会话中是否有可用的 MATLAB MCP server 工具（查找 matlabRunCode、matlab_run 或类似的 MCP 工具）。

如果 MATLAB MCP server 可用：

1. 运行设置部分 — 通过 MATLAB MCP server 执行 MPyReq.python() 和软件包安装调用，以验证 Python 环境能否正确安装。
2. 运行推理部分 — 执行模型加载和推理代码，以验证端到端功能。
3. 针对错误迭代修正 — 如果任何步骤失败，读取错误输出，修复生成的代码并重新运行。

尝试次数上限和妥善回退

将每次修复并重试的循环计为一次尝试。最多尝试 5 次（设置和推理合计）。如果 5 次后代码仍无法完全运行：

1. 停止迭代。 不要继续以相同或类似的方式重试。
2. 保存最佳版本的 demo<ModelName>.m — 即进展最远的版本（例如，设置成功但推理失败，或只运行了部分推理）。
3. 将脚本返回给用户，并按以下结构说明交接信息：

## What Works
- <list sections/steps that executed successfully>

## What Needs Attention
- <describe the remaining failure: error message, which line/section fails>
- <root cause hypothesis if known>

## Recommended Next Steps
1. <most likely fix — e.g., "Try Python 3.11 instead of 3.12 due to package compatibility">
2. <alternative approach — e.g., "Install system dependency X before running">
3. <manual verification — e.g., "Run `pip install <pkg>` in the MPyReq venv directly to check build logs">

## Environment Details
- Python version attempted: <version>
- Platform: <OS>
- Errors encountered: <brief summary of distinct errors across attempts>

4. 在脚本中清楚标记哪些部分已验证、哪些部分未验证，并使用注释：

%% Setup Python Environment — VERIFIED
% ... (code that ran successfully) ...

%% Run Inference — NEEDS MANUAL VERIFICATION
% The following section encountered errors during automated testing.
% See recommended next steps above.
% ... (best-effort code) ...

提前退出条件（未达到 5 次时停止）：

• 相同错误重复出现 2 次或以上，且没有新信息 — 立即停止
• MATLAB 无法控制的环境或平台问题（例如，缺少系统库、网络受阻、GPU 驱动不匹配）— 停止并报告
• 软件包构建失败且需要系统级干预（例如，缺少 C 编译器、CUDA 版本不匹配）— 停止并报告

如果 MATLAB MCP server 不可用：

1. 将生成的 demo<ModelName>.m 文件返回给用户。
2. 提供设置说明，概述：
   • 前置条件（MATLAB 版本、MPyReq 已添加到路径）
   • 将运行的 MPyReq 命令及其安装内容
   • 首次运行时的预期行为（下载 Python 和软件包，可能需要几分钟）
   • 运行方法：在 MATLAB 中打开脚本，并逐节运行（Ctrl+Enter）
3. 说明任何特定于平台的注意事项（例如，Windows CUDA 设置、UV_EXTRA_INDEX_URL）。

重要说明

• 未经用户明确许可，绝不修改克隆仓库的源代码（例如编辑配置文件、修补 Python 模块）。如果某种变通方案需要修改源代码，请说明要做的更改，并让用户决定。
• 绝不在 MATLAB 中使用 Python 双下划线方法（__enter__、__exit__、__init__ 等）——双下划线在 MATLAB 语法中无效。对于 torch.no_grad() 或 torch.inference_mode() 等上下文管理器，请使用等效的函数式 API（例如 py.torch.set_grad_enabled(false/true)），而不是 with 语句模式。
• 始终将输出转换回 MATLAB 的维度顺序——PyTorch 使用 NCHW（批次在前、通道在第二位）。MATLAB 要求批次在最后、通道在倒数第二位（H x W x C x B）。使用 permute 重新排序，然后使用 squeeze 移除大小为 1 的批次维度。
• 将边界框转换为 MATLAB 格式——Python 模型通常返回 [x1, y1, x2, y2]（角点对）。MATLAB 要求 M x 4 格式 [startX, startY, width, height]。宽度使用 boxes(:,3) - boxes(:,1) 计算，高度使用 boxes(:,4) - boxes(:,2) 计算。
• 加载图像时始终使用 imread——绝不要使用 Python 图像库（PIL、OpenCV 等）。将图像 I/O 保留在 MATLAB 端，并将图像转换为张量供 Python 使用。
• 始终将原始 Python 推理代码作为 %{ %} 注释块包含在内，以供参考
• 当直接使用 py.module.submodule 不起作用时（嵌套较深），请使用 py.importlib.import_module()
• 对于 Windows GPU/CUDA 支持，请注意可能需要设置 UV_EXTRA_INDEX_URL
• 如果仓库要求切换到特定目录（例如使用相对配置路径），请使用 cd(MPyReq.pathTo("<Name>"))
• 在适用的情况下，测试生成的代码能否处理 GPU 和 CPU 路径
• 保持 MATLAB 接口符合 MATLAB 惯例——使用 MATLAB 图像类型、显示函数和数据结构

有关其他注意事项（类别 ID 映射、opencv-python 问题、insertObjectAnnotation 提示），请参阅 references/common_gotchas.md。

参考文件

此技能附带以下参考文件。请从技能的 references/ 目录中读取：

示例演示（预期输出格式）

• references/demo-cellpose.md — 简单的 pip 包模式
• references/demo-sam2.md — 带权重的 git+pip 模式
• references/demo-depthpro.md — 带权重的 git 仓库 + pip 安装模式
• references/demo-birefnet.md — git 仓库 + requirements.txt + 权重
• references/demo-stardist.md — 复杂的依赖管理
• references/demo-vggt.md — git 仓库 + requirements.txt，点云输出

转换指南

• references/python_matlab_conversions.md — Python 到 MATLAB 的语法转换表
• references/image_conversion_patterns.md — 图像张量转换和显示模式
• references/common_gotchas.md — 类别 ID 映射、opencv-python 问题、注释提示

MPyReq 文档

• references/readme.md — MPyReq 文档概览

MPyReq 类位于项目的 mpyreq/MPyReq.m 中。

技能反馈

如果此技能的指南有误、不完整或不起作用，请在回复中输出纯文本反馈标记，然后继续执行任务。

格式：IPCV-SKILL-FEEDBACK [matlab-integrate-pytorch-vision] [category]: what failed; what you did instead 类别：wrong-command（命令不正确或已过时）、missing-guidance（遗漏步骤）、 discovery-failure（建议的方法不起作用）、platform-issue（特定于环境的问题）

---

版权所有 2026 The MathWorks, Inc.

---