Экспорт 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.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 Базовое использование
Пример
# ── Использование декоратора @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.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 Экспорт сложных моделей
Пример
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 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("⚠ Разница выходов велика")
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
Пример
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 Квантование модели
Пример
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. Трассировка модели
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 для преобразования.
Пример
# 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("Все форматы успешно экспортированы!")