Exportation PyTorch TorchScript / ONNX
Après la fin de l'entraînement du modèle, le modèle doit être déployé dans l'environnement de production. PyTorch propose plusieurs méthodes d'exportation de modèle, parmi lesquellesTorchScriptetONNXsont les deux formats les plus couramment utilisés.
Cette section détaille les principes, l'utilisation et les bonnes pratiques de ces deux méthodes d'exportation.
L'exportation de modèle est le processus de conversion d'un modèle PyTorch en un format pouvant s'exécuter sur différentes plateformes et dans différents frameworks. Cela est crucial pour des scénarios tels que le déploiement de modèles, l'inférence mobile et la migration entre frameworks.
1. Bases de TorchScript
1.1 Qu'est-ce que TorchScript ?
TorchScript est le format de sérialisation de PyTorch, qui convertit le code Python en code de machine virtuelle C++ autonome. Les programmes TorchScript peuvent s'exécuter dans des environnements sans interpréteur Python.
Caractéristiques clés de TorchScript :
- Convertit les graphes dynamiques en graphes statiques
- Prend en charge un sous-ensemble de la syntaxe Python
- Peut s'exécuter dans un environnement C++
- Préserve la structure et les paramètres du modèle
1.2 Deux méthodes de conversion
TorchScript propose deux façons de convertir des modèles en TorchScript :
- TorchScript Tracing (Tracing): Enregistre les opérations en exécutant le modèle et génère un graphe de calcul statique
- TorchScript Scripting (Scripting): Analyse directement le code Python et le compile en TorchScript
2. TorchScript Tracing (Tracing)
2.1 Méthodes de tracing de base
Exemple
import torch.nn as nn
# ── Définir le modèle ──────────────────────────────────────
class SimpleNet(nn.Module):
def __init__(self):
super().__init__()
self.conv1 = nn.Conv2d(3, 64, kernel_size=3, padding=1)
self.conv2 = nn.Conv2d(64, 128, kernel_size=3, padding=1)
self.pool = nn.MaxPool2d(2)
self.fc = nn.Linear(128 * 8 * 8, 10)
def forward(self, x):
x = self.pool(torch.relu(self.conv1(x)))
x = self.pool(torch.relu(self.conv2(x)))
x = x.view(x.size(0), -1)
x = self.fc(x)
return x
# Créer une instance du modèle
model = SimpleNet()
model.eval()
# Exemple d'entrée
example_input = torch.randn(1, 3, 64, 64)
# ── Méthode 1 : tracing avec torch.jit.trace ───────────────────
# Créer un TorchScript en exécutant le modèle et en enregistrant les opérations
traced_model = torch.jit.trace(model, example_input)
print("Modèle tracé :")
print(traced_model)
# Enregistrer le modèle
traced_model.save("simple_net_traced.pt")
# Charger le modèle
loaded_model = torch.jit.load("simple_net_traced.pt")
# Effectuer une inférence avec le modèle chargé
output = loaded_model(example_input)
print(f"Forme de sortie : {output.shape}")
2.2 Limites du traçage
La méthode de traçage présente quelques limites :
- N'enregistre que les opérations réellement exécutées
- Le flux de contrôle (par ex., if, for) est figé
- Les entrées avec des tailles dynamiques peuvent poser des problèmes
Exemple
class DynamicModel(nn.Module):
def __init__(self):
super().__init__()
def forward(self, x):
# Le flux de contrôle est figé pendant le traçage
if x.sum() > 0:
return x * 2
else:
return x / 2
model = DynamicModel()
model.eval()
# Lors du traçage, la branche if est figée sur le chemin emprunté lors du traçage
example_input = torch.tensor([1.0])
traced = torch.jit.trace(model, example_input)
# Même avec une entrée différente, la même branche est exécutée
print(traced(torch.tensor([1.0]))) # 2
print(traced(torch.tensor([-1.0]))) # Le résultat est toujours 2, pas -0.5
Pour les modèles contenant un flux de contrôle, vous devez utiliser TorchScript Scripting au lieu du traçage.
3. TorchScript Scripting (Scripting)
3.1 Utilisation de base
Exemple
# ── Utilisation du décorateur @torch.jit.script ───────────────
@torch.jit.script
def scripted_function(x: torch.Tensor) -> torch.Tensor:
"""Convertir la fonction à l'aide du scripting"""
if x.sum() > 0:
return x * 2
else:
return x / 2
# Tester la fonction scriptée
input1 = torch.tensor([1.0, 2.0])
input2 = torch.tensor([-1.0, -2.0])
print(scripted_function(input1)) # [2., 4.]
print(scripted_function(input2)) # [-0.5, -1.]
# ── Mise en script du modèle ───────────────────────────────────
class ScriptableModel(nn.Module):
def __init__(self):
super().__init__()
self.fc = nn.Linear(10, 10)
@torch.jit.export
def forward(self, x: torch.Tensor) -> torch.Tenseur:
return torch.relu(self.fc(x))
@torch.jit.export
def predict(self, x: torch.Tensor) -> torch.Tenseur:
"""Méthode d'export supplémentaire"""
out = self.forward(x)
return torch.argmax(out, dim=1)
model = ScriptableModel()
# Scriptez le modèle
scripted_model = torch.jit.script(model)
print(scripted_model)
# Enregistrer
scripted_model.save("scripted_model.pt")
3.2 Scriptage de modèles complexes
Exemple
class ConditionModel(nn.Module):
def __init__(self, num_classes: int):
super().__init__()
self.num_classes = num_classes
self.features = nn.Sequential(
nn.Conv2d(3, 32, 3, padding=1),
nn.ReLU(),
nn.MaxPool2d(2),
nn.Conv2d(32, 64, 3, padding=1),
nn.ReLU(),
nn.AdaptiveAvgPool2d(1),
nn.Flatten()
)
self.classifier = nn.Linear(64, num_classes)
def forward(self, x: torch.Tensor, use_softmax: bool = False) -> torch.Tensor:
"""
Un modèle qui prend en charge des conditions dynamiques
"""
features = self.features(x)
logits = self.classifier(features)
if use_softmax:
return torch.softmax(logits, dim=1)
else:
return logits
def get_prediction(self, x: torch.Tensor) -> torch.Tenseur:
"""Méthode auxiliaire"""
logits = self.forward(x, use_softmax=False)
return torch.argmax(logits, dim=1)
# Scriptage
model = ConditionModel(num_classes=10)
scripted_model = torch.jit.script(model, example_inputs=(torch.randn(1, 3, 32, 32),))
# Test
test_input = torch.randn(2, 3, 32, 32)
output1 = scripted_model(test_input, use_softmax=False)
output2 = scripted_model(test_input, use_softmax=True)
print(f"Forme de sortie des logits : {output1.shape}")
print(f"Forme de sortie Softmax : {output2.shape}")
4. Export ONNX
4.1 Notions de base d’ONNX
ONNX(Open Neural Network eXchange)ONNX est un format ouvert d’échange de réseaux de neurones qui prend en charge la conversion de modèles entre différents frameworks d’apprentissage profond.
Avantages d’ONNX :
- Multi-framework : pris en charge par PyTorch, TensorFlow, Caffe2, etc.
- Multi-plateforme : prend en charge CPU, GPU, mobile et d’autres plateformes
- Optimisation matérielle : peut tirer parti d’ONNX Runtime pour une inférence efficace
- Outils riches : une multitude d’outils d’optimisation et de solutions de déploiement
4.2 Export ONNX de base
Exemple
import torch.nn as nn
import torchvision
# ── Définir le modèle ──────────────────────────────────────
class ImageClassifier(nn.Module):
def __init__(self):
super().__init__()
self.features = nn.Sequential(
nn.Conv2d(3, 32, 3, padding=1),
nn.ReLU(),
nn.MaxPool2d(2),
nn.Conv2d(32, 64, 3, padding=1),
nn.ReLU(),
nn.AdaptiveAvgPool2d(1),
nn.Flatten()
)
self.classifier = nn.Linear(64, 10)
def forward(self, x):
x = self.features(x)
x = self.classifier(x)
return x
model = ImageClassifier()
model.eval()
# Exemple d'entrée
example_input = torch.randn(1, 3, 32, 32)
# ── Export vers ONNX ──────────────────────────────────
output_path = "image_classifier.onnx"
torch.onnx.export(
model,
example_input,
output_path,
export_params=True, # Exporter les paramètres du modèle
opset_version=14, # Version ONNX
do_constant_folding=True, # Optimisation par pliage de constantes
input_names=['input'], # Noms des tenseurs d'entrée
output_names=['output'], # Noms des tenseurs de sortie
dynamic_axes={
'input': {0: 'batch_size'}, # Dimension de lot dynamique
'output': {0: 'batch_size'}
}
)
print(f"Modèle exporté vers : {output_path}")
# Valider le modèle exporté
import onnx
onnx_model = onnx.load(output_path)
onnx.checker.check_model(onnx_model)
print("Validation du modèle ONNX réussie !")
4.3 Exportation de modèles complexes
Exemple
import torchvision.models as models
# Charger un modèle pré-entraîné
model = models.resnet18(pretrained=True)
model.eval()
# Exemple d'entrée (ResNet standard 224x224)
example_input = torch.randn(1, 3, 224, 224)
# Exporter
torch.onnx.export(
model,
example_input,
"resnet18.onnx",
export_params=True,
opset_version=14,
input_names=['input'],
output_names=['output'],
dynamic_axes={
'input': {0: 'batch_size', 2: 'height', 3: 'width'},
'output': {0: 'batch_size'}
}
)
print("ResNet18 a été exporté")
# Gérer les couches spéciales lors de l'exportation
# Pour les couches qui nécessitent un traitement spécial, utilisez une solution de contournement
class ModelWithSpecialOps(nn.Module):
def __init__(self):
super().__init__()
self.conv = nn.Conv2d(3, 64, 3, padding=1)
def forward(self, x):
# Utilisez F.interpolate au lieu de l'alias nn.functional
x = self.conv(x)
x = torch.nn.functional.interpolate(x, scale_factor=2, mode='bilinear', align_corners=False)
return x
model = ModelWithSpecialOps()
model.eval()
torch.onnx.export(
model,
torch.randn(1, 3, 32, 32),
"special_ops.onnx",
input_names=['input'],
output_names=['output'],
opset_version=14
)
5. Validation et optimisation de l'export
5.1 Validation des modèles exportés
Exemple
import onnx
import onnxruntime as ort
def verify_onnx_model(onnx_path, pytorch_model, test_input):
"""
Vérifier la cohérence des sorties entre le modèle ONNX et le modèle PyTorch
"""
# 1. Vérifier le modèle ONNX
onnx_model = onnx.load(onnx_path)
onnx.checker.check_model(onnx_model)
print("✓ Validation de la structure du modèle ONNX réussie")
# 2. Inférence PyTorch
pytorch_model.eval()
with torch.no_grad():
pytorch_output = pytorch_model(test_input)
# 3. Inférence avec ONNX Runtime
ort_session = ort.InferenceSession(onnx_path)
ort_output = ort_session.run(None, {'input': test_input.numpy()})[0]
# 4. Comparer les sorties
diff = np.abs(pytorch_output.numpy() - ort_output).max()
print(f"✓ Différence maximale de sortie : {diff:.6f}")
if diff < 1e-5:
print("✓ Validation de la sortie réussie")
return True
else:
print("⚠ La différence de sortie est importante")
return False
# Exemple d'utilisation
model = ImageClassifier()
model.eval()
# Exporter d'abord
torch.onnx.export(
model,
torch.randn(1, 3, 32, 32),
"test_model.onnx",
input_names=['input'],
output_names=['output']
)
# Valider
test_input = torch.randn(2, 3, 32, 32)
verify_onnx_model("test_model.onnx", model, test_input)
5.2 Optimisation d'ONNX Runtime
Exemple
from onnxruntime import GraphOptimizationLevel
# Créer une session d'inférence et configurer l'optimisation
def create_optimized_session(onnx_path, providers=None):
if providers is None:
providers = ['CUDAExecutionProvider', 'CPUExecutionProvider']
# Configurer les options de session
sess_options = ort.SessionOptions()
# Activer l'optimisation de graphe
sess_options.graph_optimization_level = GraphOptimizationLevel.ORT_ENABLE_ALL
# Activer d'autres optimisations
sess_options.intra_op_num_threads = 4
sess_options.inter_op_num_threads = 4
# Créer une session
session = ort.InferenceSession(onnx_path, sess_options, providers=providers)
return session
# Utiliser la session optimisée pour l'inférence
session = create_optimized_session("resnet18.onnx")
# Obtenir les noms des entrées et des sorties
input_name = session.get_inputs()[0].name
output_name = session.get_outputs()[0].name
# Inférence
input_data = np.random.randn(1, 3, 224, 224).astype(np.float32)
output = session.run([output_name], {input_name: input_data})[0]
print(f"Forme de sortie de l'inférence : {output.shape}")
5.3 Quantification du modèle
Exemple
import onnx
from onnxruntime.quantization import quantize_dynamic, QuantType
def quantize_onnx_model(input_path, output_path):
"""
Quantifier dynamiquement le modèle ONNX
Réduire la taille du modèle et accélérer l'inférence
"""
# Quantification dynamique (aucune donnée de calibration requise)
quantize_dynamic(
input_path,
output_path,
# Spécifier les types de poids à quantifier
weight_type=QuantType.QInt8
)
# Obtenir une comparaison de taille de fichier
import os
original_size = os.path.getsize(input_path) / 1024 / 1024
quantized_size = os.path.getsize(output_path) / 1024 / 1024
print(f"Modèle original : {original_size:.2f} MB")
print(f"Modèle quantifié : {quantized_size:.2f} MB")
print(f"Taux de compression : {original_size/quantized_size:.2f}x")
# Utilisation
quantize_onnx_model("resnet18.onnx", "resnet18_quantized.onnx")
6. Déploiement mobile
6.1 Exportation vers des formats mobiles
Exemple
# 1. Tracer le modèle
model = ImageClassifier()
model.eval()
example_input = torch.randn(1, 3, 32, 32)
traced_model = torch.jit.trace(model, example_input)
# 2. Optimiser le modèle (optimisation mobile)
optimized_model = torch.jit.optimize_for_inference(traced_model)
# 3. Enregistrer le modèle mobile
optimized_model.save("mobile_model.pt")
# Méthode 2 : Utiliser torchmobile (si disponible)
# torchmobile est utilisé pour un déploiement mobile plus léger
# Veuillez vous référer à la documentation officielle pour la compilation croisée
# Méthode 3 : Exporter vers ONNX et utiliser un runtime mobile
# iOS : Utiliser Core ML Tools
# Android : Utiliser ONNX Runtime Mobile
print("Le modèle mobile est prêt")
6.2 Exportation Core ML (iOS)
Pour la plateforme iOS, vous pouvez utiliser Core ML Tools pour convertir le modèle au format Core ML. Vous devez d'abord le convertir au format ONNX, puis utiliser Core ML Tools pour la conversion.
Exemple
# pip install coremltools
# Étapes d'exportation Core ML
# Remarque : ceci n'est disponible que sur macOS
# Étape 1 : exporter d'abord le modèle PyTorch vers ONNX
# from pytorch_example import your_model
# model = your_model()
# model.eval()
# example_input = torch.randn(1, 3, 224, 224)
# torch.onnx.export(
# model,
# example_input,
# "model.onnx",
# input_names=['input'],
# output_names=['output']
# )
# Étape 2 : Utiliser Core ML Tools pour convertir au format Core ML
# from coremltools.converters import onnx as onnx_coreml
# coreml_model = onnx_coreml.convert(
# model="model.onnx",
# minimum_deployment_target='13',
# image_input_names=['input']
# )
# coreml_model.save("model.mlmodel")
# Exemple d'utilisation
print("Le déploiement iOS nécessite un environnement macOS")
print("Étapes détaillées : 1. pip install coremltools 2. Exporter ONNX 3. Convertir avec coremltools")
7. Bonnes pratiques et problèmes courants
7.1 Dépannage de l'export
| Problème | Cause | Solution |
|---|---|---|
| Échec de l'export | Opération non prise en charge | Utilisez un opset_version plus élevé, ou remplacez l'opération |
| Sortie incohérente | Flux de contrôle dynamique | Utilisez le scripting au lieu du tracing, ou corrigez la taille d'entrée |
| Erreur d'ONNX Runtime | Opérateur non pris en charge | Vérifiez la liste des opérations prises en charge par ONNX |
7.2 Comparaison des formats d'export
| Format | Avantages | Inconvénients | Scénarios applicables |
|---|---|---|---|
| TorchScript (.pt) | Prise en charge native de PyTorch | Prise en charge inter-frameworks médiocre | Déploiement sur poste de travail/serveur |
| ONNX (.onnx) | Inter-frameworks, multiplateforme | Certaines opérations ne sont pas prises en charge | Déploiement général |
7.3 Liste de contrôle pour l'export
Exemple
def export_checklist(model, example_input):
"""Vérifications avant export"""
model.eval()
# 1. S'assurer que le modèle est en mode inférence
print(f"Mode du modèle : {'eval' if not model.training else 'train'}")
# 2. Vérifier la taille de l'entrée
print(f"Forme de l'entrée d'exemple : {example_input.shape}")
# 3. Valider la passe avant
with torch.no_grad():
output = model(example_input)
print(f"Forme de sortie : {output.shape}")
# 4. Vérifier les opérations non sérialisables
# Par exemple, les fonctions lambda
for name, module in model.named_modules():
if hasattr(module, '__call__'):
pass # Vérifier les modules personnalisés
print("✓ Vérification d'export terminée")
# Exemple d'utilisation
model = ImageClassifier()
example_input = torch.randn(1, 3, 32, 32)
export_checklist(model, example_input)
7.4 Processus d'exportation complet
Exemple
class ProductionModel(nn.Module):
"""Modèle de qualité production"""
def __init__(self):
super().__init__()
self.backbone = nn.Sequential(
nn.Conv2d(3, 64, 7, stride=2, padding=3),
nn.BatchNorm2d(64),
nn.ReLU(),
nn.MaxPool2d(3, stride=2, padding=1),
# ... d'autres couches
)
self.head = nn.Linear(512, 10)
def forward(self, x, return_features=False):
features = self.backbone(x)
features = torch.nn.functional.adaptive_avg_pool2d(features, 1).flatten(1)
if return_features:
return features
return self.head(features)
# Flux de travail d'exportation complet
model = ProductionModel()
model.load_state_dict(torch.load("weights.pth")) # Charger les poids
model.eval()
# Préparer une entrée d'exemple
example_input = torch.randn(1, 3, 224, 224)
# 1. Tracer TorchScript
traced = torch.jit.trace(model, example_input)
traced.save("model_traced.pt")
# 2. Exportation ONNX
torch.onnx.export(
traced,
example_input,
"model.onnx",
input_names=['input'],
output_names=['output'],
dynamic_axes={'input': {0: 'batch'}, 'output': {0: 'batch'}},
opset_version=14
)
# 3. Optimiser ONNX
# Utiliser onnx-simplifier pour supprimer les opérations redondantes
# onnxsim model.onnx model_simplified.onnx
print("Tous les formats ont été exportés avec succès !")