Настройка путей к ассетам при кастомных сборках

ONNX Runtime Web (ORT Web) предоставляет возможность запуска моделей ONNX прямо в браузере, используя WebAssembly (WASM) или WebGPU. Для обеспечения корректной работы библиотека требует доступ к нескольким ассетам: файлам WASM, WebGPU шейдерам, а также дополнительным бинарным файлам, необходимым для выполнения конкретных моделей. При кастомной сборке ORT Web возникает необходимость точной настройки путей к этим ассетам, чтобы избежать ошибок загрузки и несовместимости.

Структура ассетов в стандартной сборке

В стандартной сборке ONNX Runtime Web ассеты располагаются в определённых каталогах:

  • ort-wasm.wasm — основной бинарный файл WebAssembly.
  • ort-wasm-threaded.wasm — версия с поддержкой многопоточности (если используется).
  • ort-webgpu.wasm и шейдеры WebGPU — файлы, необходимые для запуска на GPU через WebGPU.
  • Дополнительные вспомогательные файлы (например, wasm-полифилы и worker-скрипты).

Библиотека по умолчанию ищет эти файлы относительно пути подключения ort.min.js или ort-core.js.

Настройка пути к ассетам

Для кастомных сборок требуется явно указывать пути к ассетам через объект конфигурации OrtEnv или через методы инициализации сессии. Основной способ настройки выглядит следующим образом:

import * as ort from "onnxruntime-web";

const sessionConfig = {
  executionProviders: ['wasm'], // или 'webgl', 'webgpu'
  graphOptimizationLevel: 'all',
  // ключевой параметр: location ассетов
  wasmPaths: {
    'ort-wasm.wasm': '/custom_assets/wasm/ort-wasm.wasm',
    'ort-wasm-threaded.wasm': '/custom_assets/wasm/ort-wasm-threaded.wasm'
  },
  webgpuShaderPath: '/custom_assets/webgpu/'
};

const session = await ort.InferenceSession.create('model.onnx', sessionConfig);

Ключевые моменты:

  • wasmPaths позволяет задать отдельные URL для каждого файла WASM.
  • webgpuShaderPath указывает директорию, где находятся шейдеры для WebGPU.
  • Путь может быть абсолютным (например, /assets/ort/) или относительным к корню веб-сервера.

Особенности кастомных сборок

  1. Разделение ассетов по CDN или локальному серверу При использовании CDN или отдельного сервера необходимо убедиться, что все ассеты доступны по указанным URL и имеют корректные MIME-типы (application/wasm для WASM, application/javascript для JS-файлов).

  2. Совместимость с многопоточностью Если включена поддержка WebAssembly Threads, путь к ort-wasm-threaded.wasm должен быть доступен независимо от обычного WASM-файла.

  3. Работа с пакетными сборками (Webpack, Vite, Rollup) Для интеграции в сборщик необходимо настроить копирование бинарных ассетов в публичную директорию проекта и использовать динамический импорт или настройку publicPath.

// пример для Webpack
module.exports = {
  output: {
    publicPath: '/static/',
  },
  module: {
    rules: [
      {
        test: /\.wasm$/,
        type: 'asset/resource',
        generator: {
          filename: 'wasm/[name][ext]'
        }
      }
    ]
  }
};

Динамическая загрузка ассетов

Для оптимизации загрузки можно подгружать WASM и шейдеры динамически, только при необходимости выбранного движка:

async function loadOrt(sessionOptions) {
  if (sessionOptions.executionProviders.includes('wasm')) {
    await ort.env.wasm.setWasmPaths(sessionOptions.wasmPaths);
  }
  if (sessionOptions.executionProviders.includes('webgpu')) {
    await ort.env.webgpu.setShaderPath(sessionOptions.webgpuShaderPath);
  }
  return ort.InferenceSession.create('model.onnx', sessionOptions);
}

Такой подход позволяет управлять ресурсами и уменьшать время первоначальной загрузки страницы.

Проверка корректности путей

Ошибки загрузки ассетов обычно проявляются как:

  • Failed to fetch resource при обращении к WASM-файлам.
  • WebGPU shader not found при отсутствии шейдеров.
  • Ошибки инициализации сессии ORT_RUNTIME_ERROR.

Для диагностики можно использовать console.log путей и проверку доступности файлов через fetch перед инициализацией:

async function verifyAssets(paths) {
  for (const key in paths) {
    const response = await fetch(paths[key]);
    if (!response.ok) {
      console.error(`Asset ${key} not found at ${paths[key]}`);
    }
  }
}

Рекомендации по организации ассетов

  • Разделять ассеты по типам: wasm/, webgpu/, workers/.
  • Использовать версии файлов в названиях (ort-wasm-v1.14.1.wasm) для контроля кэширования.
  • Включать проверку наличия ассетов на этапе сборки проекта.
  • Обеспечивать совместимость с серверным и локальным режимом работы: file:// и HTTP(S).

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

Оглавление