Почему Typesense возвращает далёкие векторные результаты: distance_threshold

Официальный distance_threshold задаётся внутри vector_query. Для самостоятельного vector search документы с cosine distance выше порога исключаются. При использовании в sort_by документация отмечает иное поведение: записи могут остаться в результатах с максимальным distance score. Порог 0.30 в примере — учебный, не рекомендованный производителем для всех моделей. Distance не является вероятностью истинности утверждения.

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

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

Вход: 20 размеченных запросов о правилах возврата и 20 явно чужих тем; храните id допустимых документов и случаи, где корректен пустой результат.

Ожидаемый результат: При выбранном на validation пороге чужие темы не дают фальшивых ссылок; на тестовом наборе доля полезных попаданий остаётся не ниже вашего заранее установленного минимума.

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

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

1. Проверьте, что запрос и документы закодированы одной моделью.
2. Снимите baseline без порога и посмотрите распределение vector_distance по релевантным и нерелевантным парам.
3. Подберите несколько кандидатов порога только по validation набору.
4. Примените distance_threshold к standalone vector запросу.
5. Проверьте долю пустых выдач, полезных находок и поведение генератора при пустом контексте.

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

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

curl -G http://localhost:8108/collections/help_auto_v1/documents/search \
 -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
 --data-urlencode 'q=условия возврата оплаты' \
 --data-urlencode 'query_by=embedding' \
 --data-urlencode 'vector_query=embedding:([], k:10, distance_threshold:0.30)' \
 --data-urlencode 'exclude_fields=embedding' 

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

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

Если один запрос возвращает мало результатов, не повышайте k бесконечно: более дальние соседи не становятся ответом от увеличения списка. Измерьте precision и recall по нескольким тематикам, отдельно по кратким и длинным формулировкам. Смена модели, препроцессинга или метрики требует повторной настройки threshold; перенос числа из чужой статьи не имеет эмпирического основания. Гибридная ветвь может вести себя иначе из-за keyword совпадений, поэтому тестируйте именно тот search contract, что будет работать в продакшене. Отдельно добавьте запросы с неизвестным ответом: их идеальный результат — отсутствие подходящего источника, а не уверенный текст от LLM.

Промпт ниже применяется только к уже отфильтрованным hits. Для «нет источника» передавайте пустой список и требуйте буквальный контролируемый ответ. Даже хорошее ограничение расстояния не заменяет проверку содержания документа, потому что математическая близость и фактологическая достаточность — разные величины.

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

• threshold подобран по размеченным парам
• пустые ответы обработаны без галлюцинации
• distances проверены на нужной метрике
• качество протестировано на независимом наборе
• Есть положительный и отрицательный тест, а не только скриншот удачного запроса.
• Сохранены исходная версия схемы, модель, corpus и выборка запросов.
• Разрешённый контекст отделён от служебных и скрытых документов.