Как использовать flat_search_cutoff Typesense для малого отфильтрованного набора

В официальном примере Typesense применяет filter_by=category:shoes и задаёт flat_search_cutoff:20 внутри vector_query; если после фильтра результатов меньше 20, поиск выполняется напрямую, минуя HNSW. Default путь использует встроенный HNSW. k и порог cutoff решают разные задачи: k задаёт число ближайших соседей, cutoff — условие выбора способа вычисления.

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

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

Вход: В tenant acme 12 документов, в beta — 10 000; query vector четырёхмерный. Отдельный замер на tenant gamma с 500 документами.

Ожидаемый результат: Для узкого фильтра можно сверить порядок результатов с прямым сравнением на 12 объектах; для большого фильтра сравнить HNSW baseline, p95 и использование ресурсов.

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

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

1. Сохраните один фиксированный corpus и последовательность query vectors.
2. Проверьте фильтр и число допустимых документов до измерений.
3. Снимите baseline без flat_search_cutoff.
4. Повторите запрос с cutoff, оставив прежние k и фильтр.
5. Сопоставьте ID, Recall@10, p95 и память для маленького и большого подмножеств.

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

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

curl -X POST http://localhost:8108/multi_search \
 -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" -H 'Content-Type: application/json' \
 -d '{"searches":[{"collection":"articles_vec_v1","q":"*","filter_by":"tenant:=acme","vector_query":"embedding:([0.7,0.1,0.1,0.2], k:10, flat_search_cutoff:20)","exclude_fields":"embedding"}]}' 

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

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

Не путайте cutoff с гарантией безопасности: он не заменяет filter_by и никак не подтверждает право пользователя на документы. Разницу алгоритмов важно измерять отдельно по селективности фильтра; один общий p95 на смешанной нагрузке может скрыть ухудшение наиболее дорогого сегмента. При малом числе объектов exact сравнение годится также как диагностический эталон ANN, но при большой коллекции полный перебор необоснованно дорог. Документация 29.1 упоминает исправление ошибки при сочетании flat_search_cutoff и фильтрации, поэтому обязательно тестируйте конкретную развёрнутую версию, а не переносите ожидания между старыми сборками. Для 30.2 опирайтесь на действующий API справочник и собственные canary tests.

В отчёте сохраняйте величину отфильтрованного множества. Если реальная база выросла с 12 до 200 записей, тот же параметр перестанет переключать алгоритм. Периодически обновляйте распределение размера subset и регрессионные показатели после роста данных.

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

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