Как выполнить kNN-поиск в Typesense с готовым embedding

Официальное описание nearest-neighbor search задаёт vector_query вида embedding:([числа], k:10). Параметр q=* допускает поиск без текстовой составляющей. Количество документов контролируется k либо per_page; если заданы оба, документация указывает, что используется большее значение. exclude_fields=embedding удаляет тяжёлый массив из выдачи, но не удаляет его из индекса и не делает запрос бесполезным.

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

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

Вход: Три документа с четырёхмерными embeddings, отдельный query embedding [0.7,0.1,0.1,0.2]; ближайший эталонный документ a1 имеет именно этот вектор.

Ожидаемый результат: В top-5 есть a1, возвращены поля документа и метаданные расстояния, но массив embedding не раздувает ответ API.

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

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

1. Сгенерируйте query vector тем же энкодером и preprocessing, что применяли к документам.
2. Проверьте число координат и конечность значений до сетевого вызова.
3. Укажите q=* и vector_query с названием реального векторного поля.
4. Ограничьте выборку осознанным k, исключите массив вектора из ответа.
5. Сверьте ID и значения distance на нескольких заранее размеченных запросах.

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

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

curl -G http://localhost:8108/collections/articles_vec_v1/documents/search \
 -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
 --data-urlencode 'q=*' \
 --data-urlencode 'vector_query=embedding:([0.7,0.1,0.1,0.2], k:5)' \
 --data-urlencode 'exclude_fields=embedding' 

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

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

На маленькой иллюстрации близость очевидна, но в реальном корпусе не обещайте, что top-1 всегда отвечает на вопрос. Замерьте Recall@k относительно точной или ручной разметки и дополнительно долю случаев, когда найденный текст действительно содержит ответ. Если запросов 100 и для каждого есть допустимые релевантные id, вычислите долю успешных попаданий при фиксированном k и одних и тех же фильтрах. Не смешивайте выбор k с размером одной страницы: документация отдельно описывает пагинацию, а наличие обоих параметров меняет итоговый лимит на больший. Приложение должно сохранить source id и выделять только разрешённые выдержки перед передачей LLM.

Добавьте отрицательный canary с неверной размерностью и набор нерелевантных текстов. Возврат технически корректного JSON при неверных id — ошибка качества retrieval, а не успех интеграции. Проверяйте долю ошибок отдельно от сетевых статусов.

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

• query vector получен тем же model ID
• размерность и тип прошли локальную проверку
• эталонный id находится в top-k
• ответ не содержит embedding поля
• Есть положительный и отрицательный тест, а не только скриншот удачного запроса.
• Сохранены исходная версия схемы, модель, corpus и выборка запросов.
• Разрешённый контекст отделён от служебных и скрытых документов.