matlab-import-external-ai-model

深層学習モデルを MATLAB にインポートする

学習済みの PyTorch、ONNX、または Keras 3 モデルを MATLAB に dlnetwork オブジェクトとしてインポートし、数値的な正しさを検証します。

使用する場面

• 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 と統合する場合（エージェントはガイダンスがなくても適切に対応できます）

ルーター：どのフレームワークを使いますか？

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 ファイル（トレース済みモデル）	入力サイズを指定してインポートします（以下を参照）

常に .pt より .pt2 を優先してください。 ユーザーがトレース済みモデルを持っている場合は、 まず 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 NV 引数を使う	存在しません。.pt には PyTorchInputSizes を使用し、.pt2 では何も指定しません
PackageName NV 引数を使う	非推奨です。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 であることを必ず確認してください
• 入力サイズを推測しないでください。ユーザーに確認するか、モデルを調べてください
• カスタムレイヤーの保存には PackageName ではなく Namespace を使用してください
• .pt より .pt2 を優先してください — torch.jit.trace より torch.export.export を推奨してください

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 を使用してください
TF_USE_LEGACY_KERAS=1 を import tensorflow の後に設定する	TensorFlow をインポートする前に設定する必要があります
非推奨の 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	MATLAB 用に Keras 3 をエクスポートします（Python）
predict	All	インポートした dlnetwork で推論を実行します
dlarray	All	ディープラーニング用のラベル付き多次元配列

---

Copyright 2026 The MathWorks, Inc.

---