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
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

# Exemple de limitations du traçage

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

import torch

# ── 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

# Exemple de scriptage plus complexe : un modèle avec des conditionnelles

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
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

# Exporter le modèle ResNet complet

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 numpy as np
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("&#x26a0; 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

import onnxruntime as ort
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

# Quantification du modèle ONNX

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

# Méthode 1 : Déploiement mobile TorchScript
# 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

# Il faut installer coremltools
# 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

# Liste de contrôle avant export

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

# Exemple complet de flux de travail d'exportation de modèle

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 !")
Autres extensions