Как настроить HNSW в Typesense: M, ef_construction и ef

Документация Typesense 30.2 сообщает default M:16, ef_construction:200, и показывает hnsw_params в определении векторного поля. Для запроса ef задаётся в vector_query; официальный default — 10. HNSW выполняет приближённый поиск, поэтому уместно проверять пересечение с точным эталоном на фиксированном корпусе. Более высокая конфигурация не гарантирует окупаемого выигрыша для каждого набора данных.

Обязательно запишите версию Typesense, имя коллекции, схему, id и версию embedding-модели, способ генерации запросов и правило доступа. Четырёхмерные массивы ниже используются только как демонстрационные данные. В настоящем retrieval все векторы документов и запросов должны иметь длину вашей модели и создаваться по одному зафиксированному контракту. Секрет TYPESENSE_API_KEY храните на сервере или в секретном хранилище, не помещайте его в опубликованную страницу.

Контрольный пример: вход и ожидаемый результат

Вход: Один corpus, 200 query vectors с exact top-10 id и конфигурации baseline 16/200, test 8/100; для каждой ef=10 и ef=100.

Ожидаемый результат: Таблица с Recall@10, p95, временем индексации и памятью для каждой конфигурации; выбран минимальный ресурсный вариант, выдержавший пороги.

Прежде чем измерять результат, зафиксируйте список документов и заранее определите допустимые id. Добавьте отрицательную проверку: документ другого tenant, неверную размерность или запрос вне темы — в зависимости от рассматриваемой задачи. Числовая близость не доказывает, что найденный текст достоверен или отвечает на вопрос. При сравнении прогонов оставляйте одинаковыми corpus, фильтр, модель и набор запросов, иначе различия нельзя приписать изучаемому параметру.

Пошаговое выполнение

1. Сохраните snapshot документов и модель embeddings.
2. Измерьте defaults, явно указав их в журнале эксперимента.
3. Создайте отдельную тестовую коллекцию с hnsw_params.
4. Выполните каждый query при двух ef, сохранив k и фильтры.
5. Сравните Recall@10 и p95; выпустите только конфигурацию, прошедшую оба порога.

После каждого этапа сохраняйте HTTP-статус, тело ошибки без секретов, schema JSON и найденные id. Отдельно проверяйте состояние самого документа после импорта: в Typesense пакетная загрузка может частично провалиться даже при транспортном HTTP 200. Не принимайте запуск кода за доказательство качества поиска; испытайте полученный индекс на наборе заранее размеченных вопросов и измерьте долю полезных ответов.

Готовый шаблон запроса

curl -X POST http://localhost:8108/collections \
 -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" -H 'Content-Type: application/json' \
 -d '{"name":"articles_hnsw_test","fields":[{"name":"title","type":"string"},{"name":"embedding","type":"float[]","num_dim":4,"hnsw_params":{"M":8,"ef_construction":100}}]}'

# Пример только параметра выполнения поиска:
vector_query=embedding:([0.7,0.1,0.1,0.2], k:10, ef:100)

Параметры примера заменяйте реальным названием коллекции, размерностью и вектором. Для вызывающего из браузера приложения создайте серверный слой с ограниченными правами; не вставляйте администраторский ключ в клиентский JavaScript. Если программа ожидает JSON-ответ, проверяйте не только факт получения hits, но и идентификаторы, поля и условия видимости каждого результата.

Что важно именно в этом сценарии

Правило сравнения: одинаковые документы, одинаковая модель и метрика, одинаковый фильтр и порядок запуска. Если corpus меняется во время измерения, recall и latency нельзя корректно приписать параметрам HNSW. На небольших данных накладные расходы и прогрев могут скрыть эффект; добавьте холодные и прогретые серии. Пересчёт индекса в новой коллекции увеличивает время и временно потребляемые ресурсы, поэтому планируйте вместимость. Если вы одновременно изменили num_dim или encoders, замер HNSW уже не изолирован. Критерий успеха определяется бизнес-ограничениями: например, собственным порогом Recall@10 и p95, а не универсальной цифрой из чужого benchmark.

Расчёт Recall@10 выполните по каждому запросу: размер пересечения ANN top-10 и exact top-10 делится на 10, затем берётся среднее по запросам. Добавьте отдельную метрику бизнес-релевантности, потому что exact математическая близость не обязательно равна ответу на вопрос.

Сравнение по сценариям

Критерии приёмки