Как искать по атрибутам

Сервис автоматически ищет по attrs_flat, если вы передаете текст в запросе. Для точной фильтрации по конкретному атрибуту передавайте ключ в теле запроса:

# Поиск товаров из "стали 35" (с учетом опечаток: "сталь", "стл", "стали 35")
curl -X POST http://localhost:8080/find \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "", "material": "сталь"}], "limit": 10}'

# Точный поиск по ГОСТу (через attrs JSON, без стемминга и fuzzy)
curl -X POST http://localhost:8080/find \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "", "gost": "7798-70"}], "limit": 5}'

# Комбинированный запрос: название + произвольный атрибут
curl -X POST http://localhost:8080/find \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "болт", "color": "оцинк"}], "limit": 20}'

Совет: При включенном enable_attrs_indexing атрибуты участвуют в поиске автоматически. Вам не нужно описывать их в [[search.extended_fields]], если не требуется индивидуальная настройка веса, стемминга или fuzzy-логики.

Ограничения и рекомендации для продакшена

• Рост индекса: Индексация attrs и attrs_flat увеличивает размер индекса на ~10-15%. Для баз >1 млн позиций с редким поиском по реквизитам рекомендуется false.
• Приоритет полей: Если поле явно описано в [[search.extended_fields]], оно будет индексироваться строго по правилам конфига и не попадет в автоматический attrs_flat.
• Post-фильтрация: Результаты, найденные через attrs, проходят строгую проверку на совпадение ключ-значение. Если в запросе "gost": "7798-70", товар с "gost": "7798" не пройдет фильтр, даже если скор высокий.
• Производительность: Поиск по attrs_flat использует тот же стеммер и стоп-слова, что и name. Убедитесь, что отраслевой шум (упак, кор, шт) добавлен в stopwords.txt.

Что класть в extra, а что нет

Произвольные атрибуты удобны для коротких характеристик товара. Но не все стоит туда складывать — важно понимать, что попадает в поисковый индекс, а что только хранится.

Подходит для extra:

• Краткие характеристики: color, size, brand, material, gost, country, warranty.
• Идентификаторы, которые нужны в ответе или как фильтр: supplier_code, internal_code, oem, serial.
• Короткие текстовые метки и теги: series, line, segment.
• Значения, по которым может искать оператор: diagonal, voltage, weight.

Не подходит для extra:

• Большие тексты документов (текст договора, ТЗ, спецификации, инструкции). Они сохранятся, но и будут токенизироваться в индексе — индекс сильно разрастется, а поиск замедлится.
• Бинарные данные в base64, JSON-объекты, HTML-разметка.
• Длинные табличные данные (например, прайс-лист внутри одного поля).
• Поля, которые нужно искать по диапазонам: даты, цены (если требуется «от/до»).

Правило: если значение больше пары строк или им не ищут как по обычному слову — храните его в 1С / файловом хранилище / S3, а в SKU Search передавайте только метаданные и ключевые слова.

Режимы фильтрации по extra

По умолчанию параметры extra работают как жесткий фильтр: товар не попадает в результаты, если хотя бы одно указанное поле не совпадает. Это поведение можно изменить без переиндексации.

Пример: мягкое бустирование по бренду

Допустим, оператор ищет "кроссовки" и хочет, чтобы товары Nike шли первыми, но не хочет терять Adidas:

# config.toml
[search]
enable_attrs_indexing = true
extra_filter_mode = "soft"

[search.weights]
extra_match_boost = 0.5

curl -X POST http://localhost:8080/find \
  -H "Content-Type: application/json" \
  -d '{"items": [{"name": "кроссовки", "brand": "Nike"}], "limit": 20}'

В ответе Nike будет выше, чем Adidas, но Adidas тоже останется в списке. При extra_filter_mode = "hard" в ответе остались бы только Nike.

Кросс-коды (аналоги и заменители) — PRO only

Что это такое: Когда один товар можно заменить другим. Например, у вас есть оригинальная деталь "Болт М16х60 оцинкованный", а в базе есть три аналога от разных производителей. При поиске по артикулу ЛЮБОГО аналога — сервис вернет ВСЮ группу, и оператор увидит все доступные варианты.

Как это устроено в данных

При загрузке товаров вы указываете для каждого:

• group_id — идентификатор группы аналогов (одинаковый для всех взаимозаменяемых товаров)
• is_original — является ли этот товар оригиналом (true/false)

# Загружаем группу аналогов
    curl -X POST http://localhost:8080/add \
      -H "Content-Type: application/json" \
      -d '{
        "items": [
          {
            "id": "DETAL-001",
            "name": "Болт М16х60 оцинкованный оригинал",
            "group_id": "GROUP-BOLT-001",
            "is_original": true
          },
          {
            "id": "DETAL-002",
            "name": "Болт М16х60 оцинкованный аналог (Nord)",
            "group_id": "GROUP-BOLT-001",
            "is_original": false
          },
          {
            "id": "DETAL-003",
            "name": "Болт М16х60 оцинкованный аналог (DIN)",
            "group_id": "GROUP-BOLT-001",
            "is_original": false
          }
        ]
      }'

# Тот же запрос через CLI
# Создайте файл items.json:
    [
      {
        "id": "DETAL-001",
        "name": "Болт М16х60 оцинкованный оригинал",
        "group_id": "GROUP-BOLT-001",
        "is_original": true
      },
      {
        "id": "DETAL-002",
        "name": "Болт М16х60 оцинкованный аналог (Nord)",
        "group_id": "GROUP-BOLT-001",
        "is_original": false
      },
      {
        "id": "DETAL-003",
        "name": "Болт М16х60 оцинкованный аналог (DIN)",
        "group_id": "GROUP-BOLT-001",
        "is_original": false
      }
    ]

sku-cli add items.json

Как это выглядит в ответе поиска

При поиске по любому из товаров группы вы получите оригинал + список аналогов:

{
      "search_time_ms": 10,
      "results": [{
        "query": { "name": "болт м16" },
        "matches": [{
          "original": {
            "name_out": "Болт М16х60 оцинкованный оригинал",
            "id_out": "DETAL-001",
            "group_id": "GROUP-BOLT-001",
            "is_original": true,
            "score": 0.94
          },
          "cross_codes": [
            {
              "name_out": "Болт М16х60 оцинкованный аналог (Nord)",
              "id_out": "DETAL-002",
              "score": 0.89,
              "is_original": false
            },
            {
              "name_out": "Болт М16х60 оцинкованный аналог (DIN)",
              "id_out": "DETAL-003",
              "score": 0.85,
              "is_original": false
            }
          ]
        }]
      }]
    }

Настройка в config.toml

[pro.cross_codes]
    enabled = true                      # Включить поддержку кросс-кодов
    max_group_size = 30                 # Максимум аналогов в ответе
    include_in_response = true          # Возвращать кросс-коды в /find
    sort_within_group = true            # Сортировать аналоги по релевантности
    include_original_in_cross_list = false  # Не дублировать оригинал в массиве аналогов

Иерархия (BOM / Where-Used) — PRO only

Что это такое: Возможность строить деревья спецификаций (BOM — Bill of Materials) и находить, где используется деталь (Where-Used).

Как это устроено в данных

При загрузке товаров вы указываете для каждого:

• parent_id — ID родительского товара (для которого эта деталь является составной частью)

# Загружаем иерархию: Изделие → Деталь1 → Деталь2
    curl -X POST http://localhost:8080/add \
      -H "Content-Type: application/json" \
      -d '{
        "items": [
          {
            "id": "PROD-001",
            "name": "Изделие (корневая сборка)",
            "parent_id": null
          },
          {
            "id": "PART-001",
            "name": "Деталь А",
            "parent_id": "PROD-001"
          },
          {
            "id": "PART-002",
            "name": "Деталь Б",
            "parent_id": "PROD-001"
          },
          {
            "id": "SUB-001",
            "name": "Поддеталь А.1",
            "parent_id": "PART-001"
          }
        ]
      }'

# Тот же запрос через CLI
# Создайте файл items.json:
    [
      {
        "id": "PROD-001",
        "name": "Изделие (корневая сборка)",
        "parent_id": null
      },
      {
        "id": "PART-001",
        "name": "Деталь А",
        "parent_id": "PROD-001"
      },
      {
        "id": "PART-002",
        "name": "Деталь Б",
        "parent_id": "PROD-001"
      },
      {
        "id": "SUB-001",
        "name": "Поддеталь А.1",
        "parent_id": "PART-001"
      }
    ]

sku-cli add items.json

Пример 1: Разузлование (direction = "down")

Показать, из чего состоит изделие "PROD-001":

curl -X POST http://localhost:8080/hierarchy \
      -H "Content-Type: application/json" \
      -d '{
        "root_id": "PROD-001",
        "direction": "down",
        "max_depth": 5,
        "include_cross_codes": false,
        "limit": 100
      }'

Ответ (дерево):

{
      "root": {
        "name_out": "Изделие (корневая сборка)",
        "id_out": "PROD-001"
      },
      "tree": {
        "item": { "name_out": "Изделие (корневая сборка)", "id_out": "PROD-001" },
        "level": 0,
        "children": [
          {
            "item": { "name_out": "Деталь А", "id_out": "PART-001" },
            "level": 1,
            "children": [
              {
                "item": { "name_out": "Поддеталь А.1", "id_out": "SUB-001" },
                "level": 2,
                "children": []
              }
            ]
          },
          {
            "item": { "name_out": "Деталь Б", "id_out": "PART-002" },
            "level": 1,
            "children": []
          }
        ]
      },
      "stats": {
        "total_nodes": 4,
        "max_depth_reached": 2,
        "cross_codes_found": 0,
        "elapsed_ms": 8
      }
    }

Пример 2: Where-Used (direction = "up")

Найти, где используется деталь "PART-001":

curl -X POST http://localhost:8080/hierarchy \
      -H "Content-Type: application/json" \
      -d '{
        "root_id": "PART-001",
        "direction": "up",
        "max_depth": 5
      }'

Ответ (цепочка родителей):

{
      "root": {
        "name_out": "Изделие (корневая сборка)",
        "id_out": "PROD-001"
      },
      "tree": {
        "item": { "name_out": "Изделие (корневая сборка)", "id_out": "PROD-001" },
        "level": 0,
        "children": [
          {
            "item": { "name_out": "Деталь А", "id_out": "PART-001" },
            "level": 1,
            "children": []
          }
        ]
      },
      "stats": {
        "total_nodes": 2,
        "max_depth_reached": 1,
        "elapsed_ms": 5
      }
    }

Пример 3: С включением кросс-кодов

При разузловании можно также получить аналоги для каждой детали:

curl -X POST http://localhost:8080/hierarchy \
      -H "Content-Type: application/json" \
      -d '{
        "root_id": "PROD-001",
        "direction": "down",
        "include_cross_codes": true
      }'

Ответ (с аналогами):

{
      "tree": {
        "item": { ... },
        "cross_codes": [],  // у корневого изделия может не быть аналогов
        "children": [
          {
            "item": { "name_out": "Деталь А", "id_out": "PART-001" },
            "cross_codes": [
              { "name_out": "Деталь А аналог (Nord)", "id_out": "PART-001-ALT" }
            ],
            "children": [ ... ]
          }
        ]
      }
    }

Настройка в config.toml

[pro.plugins.hierarchy]
    enabled = true                      # Включить плагин иерархии
    default_max_depth = 5               # Максимальная глубина по умолчанию
    default_limit = 1000                # Лимит узлов в ответе
    include_cross_codes_by_default = false  # Включать кросс-коды по умолчанию

Когда это нужно

⌨ CLI-утилита

Общие параметры

# Указать сервер явно
    sku-cli -s http://localhost:8081 health

    # Или через переменную окружения
    export SKU_CLI_SERVER=http://localhost:8082
    sku-cli health

    # Тихий режим (только JSON) — только флаг `-q`, env не поддерживается
    sku-cli -q search "болт" --format json

    # Авторизация по API-ключу (если включена) — только флаг `-a`, env не поддерживается
    sku-cli -a secret-key search "болт"

    # Загрузить config.toml (нужен для csv.default_delimiter и др.)
    sku-cli --config /etc/sku-search/config.toml health

1. Поиск

Команда search принимает позиционный запрос (название) и дополнительные фильтры. UUID длиной 36 символов автоматически интерпретируется как id.

# Обычный поиск
    sku-cli search "болт м16" --limit 5

    # Поиск по коду, артикулу, штрихкоду
    sku-cli search --code CSV-001 --art ART-42
    sku-cli search --barcode 4601234567890 --barcode 4609876543210
    sku-cli search --id 550e8400-e29b-41d4-a716-446655440000

    # Поиск с указанием стратегии (принимается везде, эффект только в PRO)
    sku-cli search "шуруповерт" --strategy hybrid --limit 10

    # Поиск только по динамическим/extra-полям (PRO only)
    sku-cli search "" --field supplier="ООО Ромашка" --dynamic-only
    sku-cli search "болт" --field material=сталь --field color=черный

    # Поиск с дополнительными 1С-полями
    sku-cli search "болт" --type "крепеж" --desc "оцинкованный" --ref "uuid-123"

    # Поиск с детальной статистикой
    sku-cli search "болт" --show-stats --format json

Стратегии поиска

Флаг --strategy принимается в обеих редакциях, но эффект имеет только в PRO (во Free любое значение сводится к fs_only).

• fs_only — только полнотекстовый поиск (default).
• embedding_only — только векторный (семантический) поиск (PRO).
• hybrid — полнотекстовый поиск + эмбеддинги, взвешенный скор (PRO).
• parallel — полнотекстовый поиск и эмбеддинги параллельно, быстрее, но выше нагрузка (PRO).

2. Добавление товаров

Команда add загружает JSON-файл с массивом объектов ItemQuery.

# Прямая загрузка
    sku-cli add items.json

    # Проверка без записи
    sku-cli add items.json --dry-run

    # Только полнотекстовый индекс (без эмбеддингов, быстрее)
    sku-cli add items.json --fs-only

Пример файла items.json:

[
      {
        "id": "ID-001",
        "name": "Болт М6x20",
        "code": "CSV-001",
        "art": "ART-001",
        "barcode": ["4601234567890"],
        "type": "крепеж",
        "material": "сталь",
        "color": "оцинкованный"
      }
    ]

3. Импорт из CSV

Команда import преобразует CSV в батчи /add.

# Базовый импорт (батчи по 500 строк — лимит сервера)
    sku-cli import --csv items.csv

    # Импорт демо-данных из архива
    sku-cli import --csv data/demo-data.csv --batch-size 500

    # Сухой запуск
    sku-cli import --csv items.csv --dry-run

    # Пропуск ошибок и свой размер батча
    sku-cli import --csv items.csv --skip-errors --batch-size 500

    # Нестандартный разделитель через флаг
    sku-cli import --csv items.csv --delimiter ';'

    # Разделитель по умолчанию из config.toml
    sku-cli --config config.toml import --csv items.csv

    # Без эмбеддингов
    sku-cli import --csv items.csv --fs-only

CSV должен содержать колонки id и name. Рекомендуемые колонки: code, art, barcode, type. Остальные колонки импортируются как extra-атрибуты. Сервер принимает батчи максимум 500 строк; CLI по умолчанию использует 500.

4. Экспорт

# JSON в stdout
    sku-cli export --format json --limit 1000 > backup.json

    # CSV в файл
    sku-cli export --format csv --limit 10000 --output export.csv

    # Постранично
    sku-cli export --format json --offset 1000 --limit 1000 > page2.json

5. Удаление

# По одному ID
    sku-cli delete "ID-001"

    # Несколько ID
    sku-cli delete "ID-001" "ID-002" "ID-003"

    # Из файла (один ID на строку)
    sku-cli delete --file ids.txt

6. Обратная связь (feedback)

Помогает обучению поиска. Регистрирует, какой результат был выбран для запроса.

# Подтвердить релевантность (для обучения синонимов важно передать product_name)
    sku-cli feedback --query "болт м10" --matched-id "ID-001" --action accept --product-name "Болт М10х40 оцинкованный"

    # Отметить нерелевантность
    sku-cli feedback --query "болт м10" --matched-id "ID-002" --action reject

    # Запрос без результатов
    sku-cli feedback --query "перфоратор бош" --action zero_result

    # Дополнительные опции: --product-art, --product-barcode, --matched-by, --position, --session-id, --expected-id

7. Синонимы

# Добавить синонимы
    sku-cli synonyms add --word "цинк" --expansions "оцинкованный,zn,zinc"

    # Список всех синонимов
    sku-cli synonyms list

    # Фильтр по слову
    sku-cli synonyms list --word "цинк"

    # Удалить синоним
    sku-cli synonyms remove --word "цинк"

8. Администрирование индекса (PRO only)

# Статистика индекса
    sku-cli index-stats

    # Оптимизация индекса (мерж сегментов)
    sku-cli optimize

    # Очистка кэша запросов
    sku-cli cache-clear

    # Полная очистка индекса (ОСТОРОЖНО!)
    sku-cli clear --force

9. Аналитика и обучение (PRO)

# Топ запросов
    sku-cli top-queries --limit 20

    # Статистика аналитики
    sku-cli analytics stats

    # Рекомендации по тюнингу
    sku-cli analytics tuning

    # Сброс накопленной аналитики
    sku-cli analytics reset

    # Предложения синонимов на основе фидбека
    sku-cli learn

10. Управление эмбеддингами (PRO)

# Статистика эмбеддинг-движка
    sku-cli embedding stats

    # Статус фоновой очереди
    sku-cli background

    # Переиндексация векторов (синхронно)
    sku-cli embedding reindex

    # Переиндексация векторов в фоне
    sku-cli embedding reindex --background

    # Оптимизация векторного индекса
    sku-cli embedding optimize

    # Очистка кэша модели
    sku-cli embedding cache-clear

    # Удалить все векторы (ОСТОРОЖНО!)
    sku-cli embedding clear

11. Иерархия (PRO)

# Разузлование (дети)
    sku-cli hierarchy "ID-001" --direction down --depth 3

    # Where-used (родители)
    sku-cli hierarchy "ID-001" --direction up --depth 3

    # С кросс-кодами и JSON-выводом
    sku-cli hierarchy "ID-001" --include-cross --format json

12. Утилиты

# Проверка здоровья сервера
    sku-cli health
    sku-cli health | jq .db_record_count

    # Текущая конфигурация поиска
    sku-cli config

    # Версия CLI
    sku-cli version

    # Автодополнение для bash
    sku-cli completion -s bash > /etc/bash_completion.d/sku-cli

    # Автодополнение для zsh
    sku-cli completion -s zsh > ~/.zsh/completions/_sku-cli

    # Man-страница
    sku-cli man > /tmp/sku-cli.1

Быстрый справочник по переменным окружения

#!/bin/bash
    # Автоматическая синхронизация с 1С

    # Выгружаем все товары в CSV
    sku-cli export --format csv --limit 50000 --output /tmp/export.csv

    # Импортируем новые товары из прайса
    sku-cli import --csv /tmp/price.csv --skip-errors

    # Оптимизируем индекс
    sku-cli optimize

    # Получаем статистику
    sku-cli health | jq .db_record_count

Архитектура и продвинутые концепции

Три уровня поиска — от простого к сложному

Сервис ищет товары на трех уровнях:

Принципиальная схема поиска

┌─────────────────────────────────────────────────────────────┐
│                        sku-search                            │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Запрос пользователя: "шурик бош"                            │
│         │                                                    │
│         ▼                                                    │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         Маршрутизатор запросов                        │   │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────┐  │   │
│  │  │ Точный поиск │  │ N-gram/Fuzzy │  │ Векторный  │  │   │
│  │  │ (ID/артикул) │  │  (текст)     │  │  поиск     │  │   │
│  │  └──────┬───────┘  └──────┬───────┘  └─────┬──────┘  │   │
│  │         │                 │                 │         │   │
│  │         └─────────────────┼─────────────────┘         │   │
│  │                           ▼                           │   │
│  │              ┌─────────────────────┐                  │   │
│  │              │  Слияние и ранжирование               │   │
│  │              └─────────────────────┘                  │   │
│  └──────────────────────────────────────────────────────┘   │
│                           │                                  │
│                           ▼                                  │
│              Результат: "шуруповерт бош" (score: 0.94)       │
└─────────────────────────────────────────────────────────────┘

Семантический поиск (эмбеддинги) — как это работает

Простая аналогия: Представьте, что каждый товар и каждый поисковый запрос получают свой «отпечаток пальца» — набор из 1024 чисел (для модели bge-m3; e5-small дает 384 числа). Похожие по смыслу товары имеют похожие отпечатки. Сервис умеет находить «отпечатки», которые ближе всего к отпечатку запроса, за 5-10 мс.

Как это работает на практике

Гибридный поиск — как объединяются результаты

Когда включены оба движка (полнотекстовый + семантический поиск), сервис запускает их параллельно и объединяет результаты с весами:

Итоговый score = normalize(текстовый_score) × weight_tantivy + normalize(семантический_score) × weight_embedding

Перед объединением скоры обоих источников нормализуются (`min_max`, `robust`, `z_score`, `softmax` или `none`). Метод задается в `pro.search.orchestrator.score_normalization` (default: `robust`).

Упрощенный пример (значения до нормализации):
  Полнотекстовый поиск нашел товар с score = 0.70
  Семантический поиск нашел тот же товар с score = 0.92
  Веса: weight_tantivy = 0.6, weight_embedding = 0.4

  Итоговый score ≈ 0.70 × 0.6 + 0.92 × 0.4 = 0.42 + 0.368 = 0.788

Рекомендуемые веса

Как подготовить ONNX-модель с INT8-квантованием

# 1. Установка зависимостей (одна команда)
pip install optimum[exporters] onnxruntime transformers

# 2. Конвертация E5-small в ONNX с INT8-квантованием
optimum-cli export onnx --model intfloat/multilingual-e5-small --task feature-extraction --optimize O2 ./models/e5

optimum-cli onnxruntime quantize --onnx_model ./models/e5 -o ./models/e5-int8 --avx512

# Готово! В папке ./models/e5-int8 вы найдете model.onnx (30-40 МБ)

Доступные модели для конвертации

Векторное хранилище — что хранит и как ищет

Векторы товаров хранятся во встраиваемой векторной базе данных. Она не требует отдельного сервера — это просто файлы на диске.

• Хранит пары: (ID товара, вектор)
• Тип индекса задается параметром pro.search.embedding.vector_index_type (default: "auto"). Рекомендуется оставить "auto" — хранилище само выберет подходящий индекс. При смене типа нужно выполнить sku-cli embedding clear и переиндексировать товары, иначе останется старый индекс.
• Поиск: 1-10 мс для 1 млн векторов
• Не требует держать все векторы в RAM — данные на диске

# Что хранится в векторном хранилище (упрощенно)
┌─────────────────────────────────────┐
│  id: "DETAL-001"                    │
│  vector: [0.123, -0.456, 0.789...]  │  ← 1024 числа (bge-m3)
├─────────────────────────────────────┤
│  id: "DETAL-002"                    │
│  vector: [0.111, -0.444, 0.777...]  │
└─────────────────────────────────────┘

Как эмбеддинги работают с дополнительными полями

Простой принцип: перед отправкой в модель вы склеиваете ВСЕ значимые поля в один «супер-текст». Модель сама «поймет», где бренд, где название, где артикул.

Пример супер-текста для эмбеддинга:
  "Шуруповерт аккумуляторный Bosch GSR 12V-15 электроинструмент"

Что дает:
  • Запрос "шурик" → найдет этот товар (сленг)
  • Запрос "bosch gsr" → найдет (артикул)
  • Запрос "аккумуляторный инструмент" → найдет (категория)

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

Скорость работы: честные цифры

Сравнение подходов (для принятия решений)

Частые вопросы по архитектуре и эмбеддингам

1. Нужно ли переиндексировать все товары при смене модели?

Да. У каждой модели свое «понимание» смысла — векторы будут разными. Если вы меняете модель, векторное хранилище нужно перезаполнить.

2. А если я хочу попробовать несколько моделей?

Сервис хранит векторы только в одной таблице на инстанс (задается через lancedb.path + collection_name). Переход на другую модель делается в четыре шага:

1. Удалите старые векторы: sku-cli embedding clear (или вручную удалите файл векторного хранилища).
2. В config.toml измените active_backend, model_path и vector_dimension на новую модель.
3. Перезапустите сервис.
4. Заново загрузите все товары — сервис пересчитает эмбеддинги для каждого добавленного товара. Старые векторы при этом будут перезаписаны.

3. Как эмбеддинги влияют на время индексации?

Добавляет ~20-30 мс на товар (вычисление вектора). Для массовой загрузки используйте пакетную обработку (batch-инференс) — это ускорит процесс в 5-10 раз.

4. Мой сервер слабый — потянет ли он эмбеддинги?

Минимальные требования для E5-small с INT8:

• RAM: 500 МБ свободной (модель 30 МБ + векторное хранилище)
• CPU: любой с поддержкой AVX2 (Intel Core i3 / AMD Ryzen 3 и выше)
• Диск: SSD (для векторного хранилища)

Если сервер очень слабый — используйте только полнотекстовый поиск (эмбеддинги отключите).

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.

Подготовка ONNX-моделей для семантического поиска

Семантический поиск (эмбеддинги) требует предварительно подготовленную ONNX-модель. Сервис поддерживает модели семейства E5 (e5-small, e5-base, e5-large) и BGE-M3. CLI-утилита может автоматически скачать, экспортировать и квантовать модель.

Быстрый старт: подготовка E5-small модели

# 1. Установка зависимостей (один раз)
    pip install optimum[onnxruntime] transformers torch onnx huggingface-hub --break-system-packages
    
    # 2. Подготовка модели (скачать, экспортировать, квантовать в INT8)
    # CLI-утилита sku-cli (входит в поставку) поддерживает команду model prepare.
    sku-cli model prepare \
        --model intfloat/e5-small-v2 \
        --output ./models/e5 \
        --quantize int8 \
        --optimize
    
    # 3. Проверка, что модель готова
    ls -la ./models/e5/int8/
    # Должны быть: model.onnx, tokenizer.json, config.json
    
    # 4. Настройка config.toml:
    # model_path = "./models/e5/int8/model.onnx"
    # vector_dimension = 384

Доступные модели

Подготовка BGE-M3 (особый случай)

# Скачать INT8 модель (рекомендуется)
    huggingface-cli download skatzR/USER-BGE-M3-ONNX-INT8 --local-dir ./models/bge-m3/int8
    
    # Или FP16 модель
    huggingface-cli download hotchpotch/vespa-onnx-BAAI-bge-m3-only-dense --local-dir ./models/bge-m3/fp16
    
    # Настройка config.toml:
    # [pro.search.embedding]
    # active_backend = "bge_m3"
    # vector_db_path = "./data/vectors.lance"
    # query_cache_enabled = true
    # session_pool_size задается только в секции бэкенда (.bge_m3 / .e5)
    #
    # [pro.search.embedding.bge_m3]
    # enabled = true
    # model_path = "./models/bge-m3/int8/model.onnx"
    # vector_dimension = 1024
    # enable_sparse = false
    # pooling = "mean"
    # intra_op_threads = 4
    # inter_op_threads = 1
    # session_pool_size = 1

Параметры команды model prepare

Проверка модели

После подготовки модели рекомендуется проверить, что она корректно загружается:

# Запускаем сервис
    ./sku-service --config config.toml
    
    # В другом терминале проверяем статус эмбеддингов
    curl http://localhost:8080/health | jq .embedding
    
    # Ожидаемый ответ:
    # {
    #   "enabled": true,
    #   "model_loaded": true,
    #   "vector_count": 50000,
    #   "vector_dimension": 384,
    #   "avg_search_time_ms": 12.3
    # }

# Тот же запрос через CLI
sku-cli health

Пример полной настройки config.toml для E5-small

[pro]
    enabled = true
    
    [pro.search.orchestrator]
    fs_enabled = true
    embedding_enabled = true
    strategy = "hybrid"
    tantivy_weight = 0.6
    embedding_weight = 0.4
    
    [pro.search.embedding]
    active_backend = "bge_m3"  # или "e5"
    vector_db_path = "./data/vectors.lance"
    query_cache_enabled = true
    # session_pool_size задается только в секции бэкенда (.bge_m3 / .e5)
    
    [pro.search.embedding.bge_m3]
    enabled = true
    model_path = "./models/bge-m3-int8/model.onnx"
    vector_dimension = 1024
    enable_sparse = false
    pooling = "mean"
    intra_op_threads = 4
    inter_op_threads = 1
    session_pool_size = 1

    # Для E5-small раскомментируйте и выключите bge_m3 выше:
    # [pro.search.embedding.e5]
    # enabled = true
    # model_path = "./models/e5-small-int8/model.onnx"
    # model_type = "e5-small"
    # vector_dimension = 384
    # pooling = "mean"
    # intra_op_threads = 4
    # inter_op_threads = 1
    # session_pool_size = 1

Конфигурация

[csv] — Параметры CSV-импорта

[server] — Сетевые параметры

[site] — Режим работы "Только для сайта" (API Gateway / Frontend Proxy)

[license] — Лицензирование PRO

[index] — Полнотекстовый индекс

[search] — Алгоритмы предобработки и фильтрации

[search.field_weights] — Веса базовых полей

[search.weights] — Веса разных типов совпадений

\[search.fuzzy\] — Тонкая настройка нечеткого поиска

[search.strategy] — Как сервис ищет: быстро или точно

[search.edge_ngram] — Префиксный поиск для коротких запросов

[search.extended_fields] — Динамические поля

[pro] — Профессиональные фичи (Enterprise)

[pro.index] — Продвинутые настройки индексации (PRO)

[pro.cross_codes] — Кросс-коды и аналоги

[pro.search.embedding] — Семантический поиск (векторные эмбеддинги)

[pro.search.embedding] — Общие настройки эмбеддингов

[pro.search.embedding.bge_m3] — Бэкенд BGE-M3

[pro.search.embedding.e5] — Бэкенд E5

[pro.search.embedding.gemini] — Бэкенд Google Gemini

[pro.search.embedding.hnsw] — Настройки HNSW индекса

[pro.search.embedding.lancedb] — Встроенное векторное хранилище

[pro.search.embedding.qdrant] — Qdrant

[pro.search.embedding.text_config] — Состав текста для эмбеддинга

# Пример конфигурации PRO с BGE-M3
[pro.search.embedding]
active_backend = "bge_m3"
vector_db_path = "./data/vectors.lance"
query_cache_enabled = true

[pro.search.embedding.bge_m3]
enabled = true
model_path = "./models/bge-m3-int8/model.onnx"
vector_dimension = 1024
enable_sparse = false
pooling = ""
intra_op_threads = 0
inter_op_threads = 0
session_pool_size = 1

# Пример переключения на E5-small
# [pro.search.embedding.e5]
# enabled = true
# model_path = "./models/e5-small-int8/model.onnx"
# model_type = "e5-small"
# vector_dimension = 384
# pooling = ""
# intra_op_threads = 0
# inter_op_threads = 0
# session_pool_size = 1

[pro.search.orchestrator] — Оркестратор поиска

[pro.background] — Фоновая очередь эмбеддингов

[pro.plugins.hierarchy] — Иерархические группы (PRO)

[security] — Безопасность и лимиты

[admin] — Администрирование

[feedback] — Обратная связь

{
  "query_name": "болт м10",
  "matched_id_out": "ID-001",
  "action": "accept",
  "product_name": "Болт М10х50 DIN 933",
  "matched_by": "name",
  "position": 1
}

curl 'http://localhost:8080/admin/learn?type=synonym'

[export] — Экспорт данных

[logging] — Логирование

[files] — Внешние словари

Обучение на обратной связи

Сервис умеет учиться на ваших действиях. Не ML, а просто и понятно: вы отправляете обратную связь, сервис анализирует ее и предлагает улучшения.

Как это работает — по шагам

{"timestamp":"2024-01-15T10:30:00Z","query_name":"болт м16 цинк","matched_1c_id_out":"1C-GUID-0001","product_name":"Болт М16х60 оцинкованный ГОСТ 7798-70","action":"accept"}

# Через CLI:
sku-cli learn

# Или через API:
curl http://localhost:8080/admin/learn

{
  "recommendations": [
    {
      "recommendation_type": "synonym",
      "title": "Синоним: цинк → оцинкованный",
      "description": "В 82% accept-запросов со словом 'цинк' выбран товар, содержащий 'оцинкованный'",
      "confidence": 0.82,
      "data": {
        "query_token": "цинк",
        "product_token": "оцинкованный"
      }
    },
    {
      "recommendation_type": "missing_product",
      "title": "Возможно отсутствующий товар: болт м16 din933",
      "description": "15 zero_result запросов за период",
      "confidence": 0.95,
      "data": {
        "query": "болт м16 din933",
        "count": 15
      }
    },
    {
      "recommendation_type": "check_product",
      "title": "Проверьте товар 1C-GUID-0001",
      "description": "Высокий reject rate (45%)",
      "confidence": 0.45,
      "data": {
        "id": "1C-GUID-0001",
        "reason": "Высокий reject rate (45%)"
      }
    },
    {
      "recommendation_type": "typo",
      "title": "Опечатка: перфоротар → перфоратор",
      "description": "Похоже на опечатку, найден канонический вариант",
      "confidence": 0.78,
      "data": {
        "query": "перфоротар",
        "canonical": "перфоратор"
      }
    }
  ],
  "processed_entries": 42
}

# Через CLI:
sku-cli synonyms add --word "цинк" --expansions "оцинкованный,zn,zinc"

# Или через API:
curl -X POST http://localhost:8080/synonyms \
  -H "Content-Type: application/json" \
  -d '{"items":[{"word":"цинк","expansions":["оцинкованный","zn","zinc"]}]}'

Как настроить 1С для отправки feedback

В 1С, после того как сервис вернул результаты поиска, добавьте кнопки "Выбрать этот товар" (accept) и "Ничего не нашлось" (zero_result). При нажатии вызывайте:

// Псевдокод 1С
Процедура ВыбранТовар(НайденныйТовар, ПоисковыйЗапрос)
    Данные = Новый Структура;
    Данные.Вставить("query_name", ПоисковыйЗапрос.Наименование);
    Данные.Вставить("matched_id_out", НайденныйТовар.Идентификатор);
    Данные.Вставить("product_name", НайденныйТовар.Наименование);
    Данные.Вставить("action", "accept");  // "accept" — выбрали этот товар

    // Отправка POST /feedback
    Ответ = ОтправитьHTTPЗапрос("/feedback", Данные);
КонецПроцедуры

Процедура НичегоНеНашлось(ПоисковыйЗапрос)
    Данные = Новый Структура;
    Данные.Вставить("query_name", ПоисковыйЗапрос.Наименование);
    Данные.Вставить("action", "zero_result");  // ничего не нашлось

    Ответ = ОтправитьHTTPЗапрос("/feedback", Данные);
КонецПроцедуры

Автоматизация обучения

Можно настроить cron для регулярного анализа:

# Запускать каждую неделю в понедельник в 9 утра
0 9 * * 1 cd /opt/sku-search && ./sku-cli learn >> /var/log/learn.log 2>&1

Полный цикл обучения на примере

1. Оператор ищет "болт м16 цинк", сервис предлагает "Болт М16 черный"
2. Оператор выбирает "Болт М16х60 оцинкованный ГОСТ 7798-70" и нажимает "Это тот товар", 1С отправляет feedback с action: "accept"
3. В лог попадает запись: искали "цинк", выбрали товар с "оцинкованный"
4. Администратор через неделю запускает sku-cli learn
5. Сервис анализирует: в нескольких accept-запросах со словом "цинк" выбран товар, содержащий "оцинкованный"
6. Сервис предлагает синоним: "цинк" → "оцинкованный"
7. Администратор добавляет синоним через API
8. Теперь "болт м16 цинк" находит "Болт М16х60 оцинкованный" с высоким score

Что происходит в feedback.log

Файл data/feedback.log накапливает все действия операторов. Пример содержимого:

{"timestamp":"2024-01-15T10:30:00.123Z","query_name":"болт м16 цинк","matched_1c_id_out":"1C-GUID-0001","product_name":"Болт М16х60 оцинкованный ГОСТ 7798-70","action":"accept"}
{"timestamp":"2024-01-15T10:32:15.456Z","query_name":"гайка нерж м16","matched_1c_id_out":"1C-GUID-0002","product_name":"Гайка М16 нержавеющая","action":"accept"}
{"timestamp":"2024-01-15T10:35:22.789Z","query_name":"шайба м8","matched_1c_id_out":"1C-GUID-0003","action":"zero_result"}

Вы можете анализировать его вручную:

# Сколько раз отклонили
grep '"action":"reject"' data/feedback.log | wc -l

# Сколько подтверждений
grep '"action":"accept"' data/feedback.log | wc -l

# Какие запросы чаще всего отклоняют
grep '"action":"reject"' data/feedback.log | jq -r '.query_name' | sort | uniq -c | sort -rn | head -10

Частые вопросы про обучение на фидбеке

1. Как часто нужно запускать sku-cli learn?

Зависит от объема данных. Если у вас 1000 новых feedback-записей в день — запускайте раз в неделю. Если 100 — раз в месяц. Сервис анализирует все записи с момента последнего запуска (он не хранит состояние, просто читает весь файл каждый раз).

2. Почему сервис предлагает синоним, который уже есть?

Алгоритм ищет пересечения токенов в query_name и названии выбранного товара (product_name). Если синоним уже есть в synonyms.json, он все равно может предложить его снова. Просто игнорируйте такие предложения.

3. Как удалить синоним, который добавили по ошибке?

Через API:

curl -X DELETE http://localhost:8080/synonyms/цинк
# или через CLI:
sku-cli synonyms remove --word цинк

Также можно отредактировать data/synonyms.json вручную и перезапустить сервис, но это не требуется.

4. Что означает confidence в предложениях?

Число от 0 до 1, которое показывает долю accept-запросов, содержащих query-токен, в которых выбран товар с product-токеном. 0.7 = в 70% таких accept-запросов выбран товар с предложенным токеном. Можете использовать как фильтр: добавлять только те, у кого confidence > 0.5. Внутренний порог генерации синонимов — 0.3.

5. А сервис сам добавит синоним, если я не проверю?

Нет. Сервис только предлагает. Решение всегда за администратором. Это сделано специально — чтобы вы случайно не испортили поиск автоматическими правками.

6. Почему после добавления синонима поиск не изменился?

Проверьте:

• Синоним добавился (проверьте GET /health — там есть synonyms_count)
• Ваш запрос содержит слово, которое совпадает с ключом синонима (регистр не важен, все приводится к нижнему)
• Синоним не конфликтует со стоп-словом (стоп-слова фильтруются ДО применения синонимов)

7. Можно ли автоматизировать добавление синонимов?

Можно, но осторожно. Напишите скрипт, который раз в неделю:

1. Вызывает GET /admin/learn
2. Фильтрует предложения с confidence > 0.8
3. Отправляет их через POST /synonyms

Рекомендуем сначала хотя бы месяц смотреть вручную, чтобы понять, какие предложения действительно полезны.

8. Что делать, если feedback.log слишком большой?

Сервис сам не ротирует этот файл. Добавьте в crontab:

# Каждую неделю архивировать и очищать
0 2 * * 0 mv /path/to/data/feedback.log /path/to/data/feedback.log.$(date +\%Y\%m\%d) && touch /path/to/data/feedback.log

9. Почему GET /admin/learn возвращает пустые предложения?

Причины:

• Нет accept-записей с product_name в feedback.log (для синонимов)
• Нет zero_result-записей (для missing_product)
• Нет повторяющихся accept/reject по одному товару (для check_product)
• Включен параметр enabled = false в конфиге (фидбек не пишется)
• В запросах все токены короче learn_min_token_len (по умолчанию 3 символа). "М6", "шт", "уп" — игнорируются

10. Можно ли обучить сервис на "хороших" совпадениях (action: "accept")?

Да. Алгоритм синонимов как раз работает на accept-записях с заполненным product_name. Хорошие совпадения показывают, что искали одно, а выбрали другое — и это самый надежный источник для предложений синонимов.

11. Как проверить, что обучение реально помогло?

Возьмите 100 запросов, на которых раньше были ошибки. Запустите поиск до добавления синонимов и после. Сравните результаты. Эффект зависит от качества и полноты feedback.

12. Что делать, если операторы нажимают "неверно" случайно?

Алгоритм ищет повторяющиеся паттерны. Для синонима нужно минимум 2 accept-записи с одним query-токеном и confidence ≥ 0.3. Случайные нажатия не наберут статистику.

Продвинутая настройка обучения

В config.toml есть параметры:

[feedback]
enabled = true                      # Включить сбор фидбека
log_path = "./data/feedback.log"    # Путь к логу
learn_min_token_len = 3             # Игнорировать слова короче 3 букв
learn_max_suggestions = 20          # Максимум предложений за раз

Что изменить, если...

Производительность

Ниже — реальные замеры на двух разных стендах. Free-версия тестировалась на скромном железе 2014 года, PRO-версия — на современном сервере с эмбеддингами. Все цифры приблизительные и зависят от CPU, RAM, диска и загрузки системы.

Free: поиск без эмбеддингов

Стенд: Mac mini 2014, Linux, 4 CPU, 8 ГБ RAM. Загружено 50 000 тестовых позиций. Цифры взяты из замеров для статьи на Infostart.

Free: QPS поиска по названию на 10 000 товаров

Замер через wrk на стенде AMD Ryzen 7 5700X, 64 ГБ RAM, NVMe SSD. 1000 случайных поисковых фраз из демо-каталога, limit=10, нагрузка: 2 потока, 10 соединений, 30 с.

Tuned-конфиг дает примерно в 2,7 раза больше QPS за счет отключения дорогих search-time фич. Это максимум throughput; production-конфиг сохраняет более высокое качество поиска.

PRO: гибридный поиск с эмбеддингами

20 000 товаров, bge-m3-int8

Стенд: AMD Ryzen 9 7945HX, 16 cores / 32 threads, 92 ГБ RAM. Модель bge-m3-int8 (1024 dim).

100 000 товаров, bge-m3-int8

Стенд: тот же AMD Ryzen 9 7945HX. Batch 500.

Ресурсы PRO

Рекомендуемые настройки фоновой индексации

Какую модель выбрать?

В PRO-режиме семантический поиск работает через ONNX Runtime. По умолчанию активна модель bge-m3, также из коробки настроена e5. Оба варианта конфигурируются через config.toml: вы указываете путь к model.onnx, размерность вектора и стратегию объединения токенов.

Скорость и размер (100k товаров)

Точность (synthetic dataset, 1500 товаров, 120 запросов)

Часто задаваемые вопросы

Что делать, если поиск не работает?

Пошаговый чек-лист:

Поиск не находит то, что должен

Запрос без name возвращает пустой результат

Причина: require_name_for_fuzzy = true.

[search]
require_name_for_fuzzy = false   # ← измените на false

При false можно искать только по динамическим полям (поставщик, бренд, ТН ВЭД).

Поиск по динамическим полям (supplier, brand) не работает

Причина 1 (PRO): extended_search_enabled = false.

[search]
extended_search_enabled = true    # ← включите

Причина 2 (PRO): поле не описано в [[search.extended_fields]].

[[search.extended_fields]]
field = "supplier"   # ← добавьте поле
weight = 0.7
stemmed = true
fuzzy = true

Сервис находит только идеальные совпадения, ничего "похожего"

Причина: слишком высокий порог auto_match_threshold.

[search]
auto_match_threshold = 0.85      # ← попробуйте снизить до 0.75-0.80
relative_score_threshold = 0.55

Слишком высокий порог (0.95+) — находим только идеальные совпадения. Слишком низкий (0.5) — много мусора.

Короткие запросы ("перф", "цинк") ничего не находят

Причина: edge_ngram.enabled = false или слишком высокий min_token_length.

[search]
min_token_length = 2           # ← должно быть 2 или меньше

[search.edge_ngram]
enabled = true                 # ← включите N-gram поиск
min_gram = 3
max_gram = 6

Опечатки не исправляются ("блот" не находит "болт")

Причина: fuzzy_max_distance = 0.

[index]
fuzzy_max_distance = 2         # ← разрешить до 2 опечаток

Расстояние 1 уже находит "блот" → "болт" (перестановка соседних букв). Расстояние 2 дополнительно находит "блоот" → "болт", но делает поиск в 1.5-2 раза медленнее.

Поиск в другом падеже не работает ("болтом" не находит "болт")

Причина: при fuzzy_max_distance = 1 сервис не успевает «согласовать» стеммированный корень с исходной формой в документе. Русский стеммер приводит «болтом» и «болт» к одному корню, но пост-фильтр ориентируется на расстояние Дамерау-Левенштейна (Damerau-Levenshtein), которое между этими формами равно 2.

[index]
fuzzy_max_distance = 2         # ← позволяет находить разные падежи и числа

Рекомендация:

• Используйте 1, если основная задача — исправлять опечатки и искать по точным артикулам/штрихкодам.
• Используйте 2, если пользователи часто вводят названия в разных падежах или числах ("болтом", "болты", "краской" → "краска"), а также при работе с кириллическими названиями, где встречаются опечатки в два символа: "краскаа" → "краска", "крска" → "краска", "телефоон" → "телефон".
• Значения >2 не рекомендуются — значительно растет задержка (+50–100% latency) и количество ложных срабатываний.

Товар с 2 совпавшими словами из 3 не показывается

Причина: слишком высокий min_token_match_ratio.

[search]
min_token_match_ratio = 0.5    # ← 50% совпадений достаточно
# Если 0.7 — нужно 70% (3 из 3 или 2 из 3 не хватит)

Сервис падает при старте с ошибкой SchemaError

Ошибка: SchemaError("An index exists but the schema does not match.")

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

Решение: удалите старый индекс и перезапустите сервис. Данные в индексе будут потеряны — перезагрузите их через POST /add.

# Остановите сервис
rm -rf ./data/index
# Перезапустите сервис — индекс создастся заново

PRO: почему не работает PRO-версия?

В /health показывает edition: "free" или license.active: false.

Возможные причины:

1. Используется Free-версия вместо PRO. Редакция определяется поставляемым исполняемым файлом и не переключается через config.toml. Проверьте:

   curl http://localhost:8080/health | jq .edition
   # Ожидаем: "pro"
   
   # Или через CLI:
   sku-cli health | jq .edition
   

   Если "free" — вы запустили Free-версию вместо PRO.

2. Нет файла лицензии. PRO требует валидный файл ./data/license.lic. Получите его через сервер активации или админ-панель.

3. PRO-файл поврежден или не соответствует вашей платформе. Скачайте архив PRO-версии заново и убедитесь, что исполняемый файл запускается без ошибок.

PRO: Как активировать PRO-версию?

1. Получите пин-код PRO-лицензии (после оплаты или от администратора).

2. Откройте в браузере страницу активации:

   • в сервисе — корень /, если PRO-версия еще не активирована;
   • на сайте — /license/activate/pro.

3. Введите полученный пин-код и нажмите кнопку активации.

4. Сервис проверит пин-код и сам установит лицензию по пути license_path (обычно ./data/license.lic). Ручное скачивание или копирование файла не требуется.

5. Проверьте статус:

   curl http://localhost:8080/health | jq .license.active
   # Ожидаем: true
   
   # Или через CLI:
   sku-cli health | jq .license.active
   

PRO: Кросс-коды и аналоги не показываются

Проверьте настройки кросс-кодов:

[pro.cross_codes]
enabled = true                  # ← должно быть true
include_in_response = true      # ← должно быть true
max_group_size = 30

PRO: Иерархия (/hierarchy) не работает

Проверьте настройки плагина:

[pro.plugins.hierarchy]
enabled = true                  # ← должно быть true
default_max_depth = 5

Также проверьте, что у товаров заполнено поле parent_id.

PRO: Эмбеддинги (семантический поиск) не работают

Чек-лист для эмбеддингов:

1. Включен PRO-режим:

   [pro]
   enabled = true
   

2. Включен оркестратор:

   [pro.search.orchestrator]
   embedding_enabled = true
   

3. Выбран активный бэкенд и указан путь к модели:

   [pro.search.embedding]
   active_backend = "bge_m3"
   
   [pro.search.embedding.bge_m3]
   enabled = true
   model_path = "./models/bge-m3-int8/model.onnx"
   vector_dimension = 1024
   

4. Модель существует и валидна:

   ls -la ./models/bge-m3-int8/model.onnx
   # Должен быть файл размером ~343 МБ (INT8)
   

5. Проверьте health-статус:

   curl http://localhost:8080/health | jq .embedding
   # Ожидаем: "enabled": true, "model_loaded": true
   
   # Или через CLI:
   sku-cli health | jq .embedding
   

6. Проверьте, что векторы построены:

   curl http://localhost:8080/health | jq .embedding.vector_count
   # Должно совпадать с .db_record_count
   
   # Или через CLI:
   sku-cli health | jq .embedding.vector_count
   

Частые ошибки при загрузке данных

Ошибка: id missing or empty

Причина: поле id обязательно для каждого товара.

{
  "name": "Болт М16",
  "id": "1C-GUID-001"   // ← обязательно!
}

Ошибка: rate limit exceeded (429)

Причина: слишком много запросов с одного IP.

[security]
rate_limit_per_minute = 0      # ← временно отключите для загрузки

Данные не сохраняются после перезапуска

Причина: неправильный путь к индексу или volume не примонтирован.

[index]
path = "./data/index"          # ← относительный путь

Фоновая индексация эмбеддингов идет слишком долго

Причина: маленький batch_size или мало worker_count.

[pro.background]
worker_count = 2
batch_size = 500               # ← для e5-small можно увеличить
lance_write_buffer_size = 1000

Как работают синонимы?

Синонимы хранятся в файле data/synonyms.json и загружаются при старте.

# Добавить синоним
sku-cli synonyms add --word "цинк" --expansions "оцинкованный,zn,zinc"

# Посмотреть список
sku-cli synonyms list

# Удалить синоним
sku-cli synonyms remove --word "цинк"

Общие рекомендации по настройке

Если сервис ничего не находит — снижайте пороги:

[search]
auto_match_threshold = 0.7
min_token_match_ratio = 0.4
relative_score_threshold = 0.4

Если сервис находит много мусора — повышайте пороги:

[search]
auto_match_threshold = 0.92
min_token_match_ratio = 0.7
relative_score_threshold = 0.6

Для массовой загрузки (100 000+ товаров):

[security]
rate_limit_per_minute = 0
rate_limit_burst = 0

[server]
max_batch_size = 500

[search]

Как получить поддержку

Если не нашли ответа на свой вопрос:

• Email: kadr78job@gmail.com
• Telegram: @kadr78job
• Документация: полный перечень эндпоинтов и параметров — в этом документе

Глоссарий

Лицензия и условия использования

Free Edition (бесплатно для всех)

PRO Edition (требует покупки лицензии)