Типичные ошибки при загрузке модели и их причины

Несовпадение версии ONNX модели и ONNX Runtime Web

ONNX Runtime Web (ORT Web) поддерживает определённые версии формата ONNX. Попытка загрузить модель, созданную в более новой версии ONNX, может вызвать ошибки типа:

  • onnxruntime.InferenceSession error: unsupported opset version
  • onnxruntime.InferenceSession error: operator not implemented.

Причины:

  • Модель была экспортирована из PyTorch или TensorFlow с использованием последней версии ONNX, несовместимой с текущей версией ORT Web.
  • Использование кастомных операторов без регистрации через customOp API ORT Web.

Решение:

  • Проверка версии модели с помощью утилиты onnx.checker.check_model().
  • Экспорт модели с указанным opset_version, совместимым с ORT Web.
  • При необходимости реализовать и зарегистрировать кастомные операторы.

Ошибки при работе с путями и загрузкой файла модели

Частая проблема — неправильная передача пути к файлу модели. Ошибки выглядят следующим образом:

  • Failed to fetch
  • NetworkError when attempting to fetch resource

Причины:

  • Попытка загрузить локальный файл через file:// в браузере, где требуется HTTP/HTTPS.
  • Отсутствие поддержки CORS на сервере, откуда загружается модель.
  • Неправильный синтаксис при использовании fetch() или ort.InferenceSession.create().

Решение:

  • Разместить модель на сервере с поддержкой HTTP/HTTPS.
  • Убедиться, что сервер возвращает заголовок Access-Control-Allow-Origin: *.
  • Использовать относительные или абсолютные пути, доступные браузеру.

Несоответствие формата данных входного тензора

ORT Web строго проверяет типы и размеры входных данных. Ошибки включают:

  • Input tensor has unexpected shape
  • Input tensor data type mismatch

Причины:

  • Передача JavaScript массивов вместо Float32Array, Int32Array и т. д.
  • Размерность тензора не совпадает с определённой в модели. Например, модель ожидает [1, 3, 224, 224], а передаётся [224, 224, 3].
  • Ошибки при нормализации данных или изменении формата изображений.

Решение:

  • Проверять описание модели с помощью session.inputNames и session.inputMetadata.
  • Преобразовывать данные в нужный тип с помощью TypedArray.
  • Переставлять оси, если вход имеет другой порядок (например, HWC → CHW для изображений).

Проблемы с асинхронной загрузкой и инициализацией сессии

ORT Web работает асинхронно, и ошибки появляются, если попытаться использовать сессию до её готовности:

  • Cannot run inference before session is initialized
  • Session not yet created

Причины:

  • Использование session.run() до завершения промиса ort.InferenceSession.create().
  • Попытка повторного запуска сессии до полной инициализации.

Решение:

  • Всегда дожидаться завершения промиса:
const session = await ort.InferenceSession.create('model.onnx');
const feeds = { input: inputTensor };
const results = await session.run(feeds);
  • Не выполнять операции сессии в глобальном контексте без асинхронной обёртки.

Ошибки при работе с WebAssembly и WebGPU бэкэндами

ORT Web поддерживает несколько бэкэндов, и каждая платформа имеет свои ограничения:

  • WebAssembly backend initialization failed
  • WebGPU backend is not supported in this browser

Причины:

  • Браузер не поддерживает WebGPU или WebAssembly SIMD.
  • Попытка загрузки модели, использующей операторы, не оптимизированные для выбранного бэкэнда.
  • Конфликт версий ORT Web с используемым бэкэндом.

Решение:

  • Проверять поддержку бэкэндов через ort.env.wasm.simd и ort.env.wasm.thread.
  • При необходимости использовать полифиллы или fallback на WebAssembly.
  • Обновлять браузер до последней версии для корректной работы WebGPU.

Ошибки при работе с кастомными опциями сессии

Некорректная настройка sessionOptions может приводить к сбоям:

  • Invalid session options
  • Failed to initialize session with given options

Причины:

  • Использование неподдерживаемых опций для Web-версии, например, опций GPU, доступных только для Node.js.
  • Некорректная передача объектов в опции, например, executionProviders или graphOptimizationLevel.

Решение:

  • Проверять документацию ORT Web для допустимых параметров.
  • Использовать простые опции, например:
const session = await ort.InferenceSession.create('model.onnx', {
  executionProviders: ['wasm'],
  graphOptimizationLevel: 'all'
});

Ошибки памяти и большие модели

При загрузке крупных моделей возможны ошибки:

  • Out of memory
  • Failed to allocate tensor

Причины:

  • Браузер ограничен по памяти.
  • Размер модели превышает допустимый объём для выбранного бэкэнда.
  • Одновременное создание нескольких сессий с большими моделями.

Решение:

  • Разделять модели на части или использовать более компактные варианты (quantized модели).
  • Освобождать сессии после использования: session = null; + gc() при возможности.
  • Тестировать модель на разных бэкэндах для выявления наиболее экономного использования памяти.

Эти категории ошибок покрывают большую часть проблем, возникающих при загрузке и инициализации моделей в ONNX Runtime Web. Структурированный анализ каждой ошибки и её причин позволяет существенно снизить вероятность сбоев и ускоряет процесс интеграции моделей в веб-приложения.

Оглавление