Экспорт PyTorch TorchScript / ONNX

После завершения обучения модели модель необходимо развернуть в производственной среде. PyTorch предоставляет несколько методов экспорта моделей, среди которыхTorchScriptиONNXявляются двумя наиболее часто используемыми форматами.

В этом разделе подробно описаны принципы, использование и лучшие практики этих двух методов экспорта.

Экспорт модели — это процесс преобразования модели PyTorch в формат, который может работать на различных платформах и фреймворках. Это критически важно для таких сценариев, как развертывание модели, вывод на мобильных устройствах и миграция между фреймворками.


1. Основы TorchScript

1.1 Что такое TorchScript

TorchScript — это формат сериализации PyTorch, который преобразует код Python в автономный код виртуальной машины C++. Программы TorchScript могут выполняться в средах без интерпретатора Python.

Ключевые особенности TorchScript:

  • Преобразует динамические графы в статические графы
  • Поддерживает подмножество синтаксиса Python
  • Может выполняться в среде C++
  • Сохраняет структуру и параметры модели

1.2 Два метода преобразования

TorchScript предоставляет два способа преобразования моделей в TorchScript:

  • Трассировка TorchScript (Tracing): записывает операции, выполняя модель, и генерирует статический граф вычислений
  • Скриптинг TorchScript (Scripting): напрямую анализирует код Python и компилирует его в TorchScript

2. Трассировка TorchScript (Tracing)

2.1 Основные методы трассировки

Пример

import torch
import torch.nn as nn

# ── Определение модели ──────────────────────────────────────
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


# Создание экземпляра модели
model = SimpleNet()
model.eval()

# Пример входных данных
example_input = torch.randn(1, 3, 64, 64)

# ── Метод 1: трассировка torch.jit.trace ───────────────────
# Создание TorchScript путём запуска модели и записи операций
traced_model = torch.jit.trace(model, example_input)

print("Трассированная модель:")
print(traced_model)

# Сохранить модель
traced_model.save("simple_net_traced.pt")

# Загрузить модель
loaded_model = torch.jit.load("simple_net_traced.pt")

# Выполнить вывод с загруженной моделью
output = loaded_model(example_input)
print(f"Форма вывода: {output.shape}")

2.2 Ограничения трассировки

Метод трассировки имеет некоторые ограничения:

  • Записывает только операции, которые фактически выполняются
  • Поток управления (например, if, for) фиксирован
  • Входные данные с динамическими размерами могут вызвать проблемы

Пример

# Пример ограничений трассировки

class DynamicModel(nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x):
        # Поток управления фиксируется во время трассировки
        if x.sum() > 0:
            return x * 2
        else:
            return x / 2


model = DynamicModel()
model.eval()

# Во время трассировки ветвь if фиксируется на пути, выбранном во время трассировки
example_input = torch.tensor([1.0])
traced = torch.jit.trace(model, example_input)

# Даже при другом входе выполняется та же ветвь
print(traced(torch.tensor([1.0])))  # 2
print(traced(torch.tensor([-1.0]))) # Результат всё ещё 2, а не -0.5

Для моделей, содержащих управляющий поток, следует использовать TorchScript Scripting вместо трассировки.


3. TorchScript Scripting (Scripting)

3.1 Базовое использование

Пример

import torch

# ── Использование декоратора @torch.jit.script ───────────────
@torch.jit.script
def scripted_function(x: torch.Tensor) -> torch.Tensor:
    """Преобразование функции с помощью scripting"""
    if x.sum() > 0:
        return x * 2
    else:
        return x / 2


# Проверка scripted-функции
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.]


# ── Скриптинг модели ───────────────────────────────────
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.Тензор:
        return torch.relu(self.fc(x))

    @torch.jit.export
    def predict(self, x: torch.Tensor) -> torch.Тензор:
        """Дополнительный метод экспорта"""
        out = self.forward(x)
        return torch.argmax(out, dim=1)


model = ScriptableModel()

# Скриптировать модель
scripted_model = torch.jit.script(model)
print(scripted_model)

# Сохранить
scripted_model.save("scripted_model.pt")

3.2 Скриптинг сложных моделей

Пример

# Более сложный пример скриптинга: модель с условными конструкциями

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:
        """
Модель, поддерживающая динамические условия
        """

        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.Тензор:
        """Вспомогательный метод"""
        logits = self.forward(x, use_softmax=False)
        return torch.argmax(logits, dim=1)


# Скриптинг
model = ConditionModel(num_classes=10)
scripted_model = torch.jit.script(model, example_inputs=(torch.randn(1, 3, 32, 32),))

#
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"Форма вывода логитов: {output1.shape}")
print(f"Форма вывода Softmax: {output2.shape}")

4. Экспорт ONNX

4.1 Основы ONNX

ONNX(Open Neural Network eXchange)ONNX — это открытый формат обмена нейронными сетями, который поддерживает преобразование моделей между различными фреймворками глубокого обучения.

Преимущества ONNX:

  • Кросс-фреймворковость: поддерживается PyTorch, TensorFlow, Caffe2 и т. д.
  • Кроссплатформенность: поддерживает CPU, GPU, мобильные и другие платформы
  • Аппаратная оптимизация: можно задействовать ONNX Runtime для эффективного инференса
  • Богатый набор инструментов: множество инструментов оптимизации и решений для развёртывания

4.2 Базовый экспорт в ONNX

Пример

import torch
import torch.nn as nn
import torchvision

# ── Определение модели ──────────────────────────────────────
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()

# Пример входных данных
example_input = torch.randn(1, 3, 32, 32)

# ── Экспорт в ONNX ──────────────────────────────────
output_path = "image_classifier.onnx"

torch.onnx.export(
    model,
    example_input,
    output_path,
    export_params=True,        # Экспорт параметров модели
    opset_version=14,          # Версия ONNX
    do_constant_folding=True, # Оптимизация свёртывания констант
    input_names=['input'],     # Имена входных тензоров
    output_names=['output'],   # Имена выходных тензоров
    dynamic_axes={
        'input': {0: 'batch_size'},    # Динамическая размерность батча
        'output': {0: 'batch_size'}
    }
)

print(f"Модель экспортирована в: {output_path}")

# Проверить экспортированную модель
import onnx
onnx_model = onnx.load(output_path)
onnx.checker.check_model(onnx_model)
print("Проверка модели ONNX пройдена!")

4.3 Экспорт сложных моделей

Пример

# Экспорт полной модели ResNet

import torchvision.models as models

# Загрузка предварительно обученной модели
model = models.resnet18(pretrained=True)
model.eval()

# Пример входных данных (стандартный ResNet 224x224)
example_input = torch.randn(1, 3, 224, 224)

# Экспорт
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 был экспортирован")

# Обработка специальных слоёв при экспорте
# Для слоёв, требующих специальной обработки, используйте обходное решение
class ModelWithSpecialOps(nn.Module):
    def __init__(self):
        super().__init__()
        self.conv = nn.Conv2d(3, 64, 3, padding=1)

    def forward(self, x):
        # Используйте F.interpolate вместо псевдонима 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. Проверка и оптимизация экспорта

5.1 Проверка экспортированных моделей

Пример

import numpy as np
import onnx
import onnxruntime as ort

def verify_onnx_model(onnx_path, pytorch_model, test_input):
    """
Проверьте согласованность выходных данных между моделью ONNX и моделью PyTorch
    """

    # 1. Проверка модели ONNX
    onnx_model = onnx.load(onnx_path)
    onnx.checker.check_model(onnx_model)
    print("✓ Проверка структуры модели ONNX прошла успешно")

    # 2. Инференс PyTorch
    pytorch_model.eval()
    with torch.no_grad():
        pytorch_output = pytorch_model(test_input)

    # 3. Инференс с помощью ONNX Runtime
    ort_session = ort.InferenceSession(onnx_path)
    ort_output = ort_session.run(None, {'input': test_input.numpy()})[0]

    # 4. Сравнение выходов
    diff = np.abs(pytorch_output.numpy() - ort_output).max()
    print(f"✓ Максимальная разница выходов: {diff:.6f}")

    if diff < 1e-5:
        print("✓ Валидация выходов пройдена")
        return True
    else:
        print("&#x26a0; Разница выходов велика")
        return False


# Пример использования
model = ImageClassifier()
model.eval()

# Сначала экспортируйте
torch.onnx.export(
    model,
    torch.randn(1, 3, 32, 32),
    "test_model.onnx",
    input_names=['input'],
    output_names=['output']
)

# Валидация
test_input = torch.randn(2, 3, 32, 32)
verify_onnx_model("test_model.onnx", model, test_input)

5.2 Оптимизация ONNX Runtime

Пример

import onnxruntime as ort
from onnxruntime import GraphOptimizationLevel

# Создать сессию вывода и настроить оптимизацию
def create_optimized_session(onnx_path, providers=None):
    if providers is None:
        providers = ['CUDAExecutionProvider', 'CPUExecutionProvider']

    # Настроить параметры сессии
    sess_options = ort.SessionOptions()

    # Включить оптимизацию графа
    sess_options.graph_optimization_level = GraphOptimizationLevel.ORT_ENABLE_ALL

    # Включить другие оптимизации
    sess_options.intra_op_num_threads = 4
    sess_options.inter_op_num_threads = 4

    # Создать сессию
    session = ort.InferenceSession(onnx_path, sess_options, providers=providers)

    return session


# Использовать оптимизированную сессию для инференса
session = create_optimized_session("resnet18.onnx")

# Получить имена входов и выходов
input_name = session.get_inputs()[0].name
output_name = session.get_outputs()[0].name

# Инференс
input_data = np.random.randn(1, 3, 224, 224).astype(np.float32)
output = session.run([output_name], {input_name: input_data})[0]

print(f"Форма вывода инференса: {output.shape}")

5.3 Квантование модели

Пример

# Квантование модели ONNX

import onnx
from onnxruntime.quantization import quantize_dynamic, QuantType

def quantize_onnx_model(input_path, output_path):
    """
Динамически квантовать модель ONNX
Уменьшить размер модели и ускорить инференс
    """

    # Динамическое квантование (калибровочные данные не требуются)
    quantize_dynamic(
        input_path,
        output_path,
        # Укажите типы весов для квантования
        weight_type=QuantType.QInt8
    )

    # Получение сравнения размеров файлов
    import os
    original_size = os.path.getsize(input_path) / 1024 / 1024
    quantized_size = os.path.getsize(output_path) / 1024 / 1024

    print(f"Исходная модель: {original_size:.2f} MB")
    print(f"Квантованная модель: {quantized_size:.2f} MB")
    print(f"Коэффициент сжатия: {original_size/quantized_size:.2f}x")


# Использование
quantize_onnx_model("resnet18.onnx", "resnet18_quantized.onnx")

6. Мобильное развертывание

6.1 Экспорт в мобильные форматы

Пример

# Способ 1: мобильное развертывание TorchScript
# 1. Трассировка модели
model = ImageClassifier()
model.eval()
example_input = torch.randn(1, 3, 32, 32)

traced_model = torch.jit.trace(model, example_input)

# 2. Оптимизация модели (мобильная оптимизация)
optimized_model = torch.jit.optimize_for_inference(traced_model)

# 3. Сохраните мобильную модель
optimized_model.save("mobile_model.pt")

# Метод 2: Используйте torchmobile (если доступно)
# torchmobile используется для более лёгкого развёртывания на мобильных устройствах
# Обратитесь к официальной документации по кросс-компиляции

# Метод 3: Экспорт в ONNX и использование мобильной среды выполнения
# iOS: Используйте Core ML Tools
# Android: Используйте ONNX Runtime Mobile

print("Мобильная модель готова")

6.2 Экспорт Core ML (iOS)

Для платформы iOS вы можете использовать Core ML Tools, чтобы преобразовать модель в формат Core ML. Сначала необходимо преобразовать её в формат ONNX, а затем использовать Core ML Tools для преобразования.

Пример

# Нужно установить coremltools
# pip install coremltools

# Шаги экспорта Core ML
# Примечание: это доступно только на macOS

# Шаг 1: Сначала экспортируйте модель PyTorch в 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']
# )

# Шаг 2: Используйте Core ML Tools для преобразования в формат 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")

# Пример использования
print("Для развертывания в iOS требуется среда macOS")
print("Подробные шаги: 1. pip install coremltools 2. Экспорт ONNX 3. Преобразование с помощью coremltools")

7. Лучшие практики и типичные проблемы

7.1 Устранение неполадок при экспорте

Проблема Причина Решение
Экспорт не удался Неподдерживаемая операция Используйте более высокий opset_version или замените операцию
Несогласованный вывод Динамический поток управления Используйте scripting вместо tracing или исправьте размер входа
Ошибка ONNX Runtime Оператор не поддерживается Проверьте список операций, поддерживаемых ONNX

7.2 Сравнение форматов экспорта

Формат Преимущества Недостатки Применимые сценарии
TorchScript (.pt) Нативная поддержка PyTorch Слабая поддержка кросс-фреймворков Развертывание на десктопе/сервере
ONNX (.onnx) Кросс-фреймворковая, кросс-платформенная Некоторые операции не поддерживаются Общее развертывание

7.3 Чек-лист экспорта

Пример

# Чек-лист перед экспортом

def export_checklist(model, example_input):
    """Проверки перед экспортом"""
    model.eval()

    # 1. Убедитесь, что модель находится в режиме инференса
    print(f"Режим модели: {'eval' if not model.training else 'train'}")

    # 2. Проверить размер входных данных
    print(f"Форма примера входных данных: {example_input.shape}")

    # 3. Проверить прямой проход
    with torch.no_grad():
        output = model(example_input)
    print(f"Форма вывода: {output.shape}")

    # 4. Проверить наличие несериализуемых операций
    # Например, лямбда-функции
    for name, module in model.named_modules():
        if hasattr(module, '__call__'):
            pass  # Проверка пользовательских модулей

    print("✓ Проверка экспорта завершена")


# Пример использования
model = ImageClassifier()
example_input = torch.randn(1, 3, 32, 32)
export_checklist(model, example_input)

7.4 Полный процесс экспорта

Пример

# Пример полного рабочего процесса экспорта модели

class ProductionModel(nn.Module):
    """Модель производственного уровня"""
    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),
            # ... дополнительные слои
        )
        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)


# Полный рабочий процесс экспорта
model = ProductionModel()
model.load_state_dict(torch.load("weights.pth"))  # Загрузить веса
model.eval()

# Подготовить пример входных данных
example_input = torch.randn(1, 3, 224, 224)

# 1. Трассировка TorchScript
traced = torch.jit.trace(model, example_input)
traced.save("model_traced.pt")

# 2. Экспорт 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. Оптимизация ONNX
# Используйте onnx-simplifier для удаления избыточных операций
# onnxsim model.onnx model_simplified.onnx

print("Все форматы успешно экспортированы!")
Другие расширения