SKU Search

ONNX Runtime в PRO-редакции

PRO-версия загружает ONNX Runtime из папки runtime/ рядом с исполняемым файлом. Это позволяет:

• поставлять один исполняемый файл для всех конфигураций;
• использовать разные рантаймы: CPU, CUDA, DirectML, ROCm;
• не качать лишние сотни мегабайт GPU-зависимостей, если GPU не нужен.

Что входит в поставку

В архиве PRO уже есть CPU-рантайм, а также созданы пустые папки для GPU-рантаймов. После распаковки структура выглядит так:

sku-search-pro/
├── sku-service
├── config.toml
└── runtime/
    ├── linux-cpu/
    │   ├── libonnxruntime.so.1.23.2
    │   ├── libonnxruntime.so.1 -> libonnxruntime.so.1.23.2
    │   ├── libonnxruntime.so -> libonnxruntime.so.1
    │   └── libonnxruntime_providers_shared.so
    ├── linux-cuda/          # пустая, сюда кладется CUDA-рантайм
    ├── linux-rocm/          # пустая, сюда кладется ROCm-рантайм
    ├── win-cpu/             # уже содержит onnxruntime.dll с CPU + DirectML
    └── win-cuda/            # пустая, сюда кладется CUDA-рантайм

Если вы не используете GPU, ничего докачивать не нужно — сервис сразу загрузит CPU-рантайм из папки runtime/linux-cpu/ (или runtime/win-cpu/ на Windows). В win-cpu/onnxruntime.dll уже встроен DirectML execution provider; отдельно докачивать DirectML не требуется. Для CUDA нужно положить файлы в runtime/win-cuda/ или runtime/linux-cuda/.

Как подключить GPU-рантайм

1. Скачайте нужный архив с официальной страницы ONNX Runtime 1.23.2:

2. Распакуйте архив и перенесите библиотеки в папку runtime/ рядом с sku-service:

Linux CUDA:

tar -xzf onnxruntime-linux-x64-gpu-1.23.2.tgz
mkdir -p runtime/linux-cuda
cp onnxruntime-linux-x64-gpu-1.23.2/lib/libonnxruntime.so* runtime/linux-cuda/
cp onnxruntime-linux-x64-gpu-1.23.2/lib/libonnxruntime_providers_* runtime/linux-cuda/

Windows CUDA:

unzip onnxruntime-win-x64-gpu-1.23.2.zip
mkdir runtime\win-cuda
xcopy onnxruntime-win-x64-gpu-1.23.2\lib\*.dll runtime\win-cuda\

Execution providers (провайдеры инференса)

PRO-сервис пытается зарегистрировать execution providers в следующем порядке:

1. CUDA (Linux), DirectML / CUDA (Windows) — если в конфиге use_gpu = true.
2. CPU (всегда доступен).

Как сервис выбирает рантайм

Сервис ищет папку runtime/ в нескольких местах:

1. В директории, заданной переменной окружения SKU_ORT_RUNTIME_DIR.
2. Рядом с исполняемым файлом sku-service.
3. В текущей рабочей директории.

Внутри runtime/ проверяются подпапки в порядке приоритета:

• Linux: linux-cuda → linux-rocm → linux-cpu.
• Windows: win-cuda → win-cpu (в win-cpu уже есть DirectML).
• macOS: macos-cpu.

Если найден GPU-рантайм и он успешно загрузился — используется GPU. Если нет — сервис пытается загрузить CPU-рантайм. Если ни один не загрузился, embedding-движок отключается, но текстовый поиск продолжает работать.

Настройка производительности embedding-бэкенда

PRO-версия позволяет управлять тем, сколько ресурсов CPU/GPU тратить на вычисление эмбеддингов. Основные параметры — в секциях [pro.search.embedding] и [pro.search.embedding.<backend>] (где <backend> = e5 или bge_m3):

Рекомендации по CPU

• Хотите максимальную скорость индексации: установите intra_op_threads = 0 (авто), background.worker_count = 2 и background.batch_size = 500 для e5-small (или 100 для bge-m3). На 16-ядерном процессоре (AMD Ryzen 9 7945HX) фоновая индексация 10 000 коротких товаров через e5-small-int8 занимает ~51 с, то есть ~195 vec/s. Точные цифры для разных моделей и настроек приведены в разделе Производительность.
• Нужно оставить ресурсы поиску/сайту: задайте фиксированное intra_op_threads = 4 и background.worker_count = 2. Скорость индексации упадет, но поиск останется отзывчивым.
• Слабый CPU / Colab / VPS с 2 vCPU: оставьте intra_op_threads = 0 и background.worker_count = 1, иначе воркеры будут бороться за ядра. В Colab CPU-индексация 10 000 товаров занимает ~12–13 минут.

Рекомендации по GPU

• В Colab / на сервере с CUDA установите use_gpu = true и intra_op_threads = 0. GPU берет основную нагрузку инференса, а CPU-потоки остаются на токенизацию и пост-обработку.
• Если CUDA/DirectML не зарегистрируется, сервис автоматически fallback'ится на CPU — индексация замедлится, но не сломается.

Проверка

После запуска сервиса посмотрите ответ /health:

curl -s http://localhost:8080/health | jq .ort_runtime

# Или через CLI:
sku-cli health

Пример с загруженным CPU-рантаймом:

{
  "loaded": true,
  "path": "/opt/sku-search-pro/runtime/linux-cpu/libonnxruntime.so",
  "build_info": "ORT Build Info: git-branch=HEAD, git-commit-id=a83fc4d58c, build type=Release"
}

Если рантайм не найден:

{
  "loaded": false
}

Совместимость версий

Если установить другую версию (например, 1.18 или 1.30), возможны следующие сценарии:

• Рантайм не загрузится совсем — в логах будет ошибка, /health покажет "loaded": false, embedding отключится, но текстовый поиск останется работать.
• Рантайм загрузится, но модель или execution provider будут вести себя непредсказуемо — возможны сбои при индексации эмбеддингов или при поиске.

Если вы хотите использовать версию, отличную от 1.23.2, проверьте работу эмбеддингов на копии данных перед переводом в production.

Частые причины, почему рантайм не загружается

• Папка runtime/ не найдена. Убедитесь, что она лежит рядом с sku-service или в текущей директории.
• Неправильная структура подпапок. Для Linux CPU должно быть runtime/linux-cpu/libonnxruntime.so, для Windows — runtime/win-cpu/onnxruntime.dll.
• Потеряны symlink'и. Если архив распаковывался на Windows/FAT, libonnxruntime.so может оказаться битой ссылкой. Запустите setup.sh — он восстановит symlink'и.
• Несовпадение версий. Установлен ONNX Runtime не версии 1.23.2.
• Отсутствует MSVC Redistributable на Windows. PRO-версия требует установленного Visual C++ Redistributable x64.
• На Linux не найдены зависимости CUDA. Убедитесь, что в системе установлены совместимые CUDA/cuDNN-библиотеки, либо добавьте их в переменную окружения LD_LIBRARY_PATH.
• На Windows не найдены зависимости CUDA. Убедитесь, что DLL CUDA (cudart64_*.dll, cublas64_*.dll и др.) доступны либо рядом с onnxruntime.dll, либо в системной переменной PATH.
• Проблемы с правами. Библиотека должна быть доступна для чтения пользователю, от имени которого запущен сервис.

Пользовательская директория для рантайма

Если по какой-то причине рантайм нельзя положить рядом с исполняемым файлом, можно задать собственный путь через переменную окружения:

export SKU_ORT_RUNTIME_DIR=/opt/onnxruntime
./sku-service

В этом случае сервис будет искать подпапки linux-cpu, linux-cuda и т.д. именно в /opt/onnxruntime.