Как настроить auto-embedding Typesense на встроенной модели

Согласно Vector Search API, embed.from перечисляет строковые поля, значения которых объединяются для получения embedding. Встроенные модели имеют пространство имён ts/; документация приводит ts/all-MiniLM-L12-v2. При запросе по auto-embedding полю Typesense преобразует q той же моделью. Embeddings перегенерируются при изменении полей из embed.from, а изменение другого атрибута не должно запускать ненужную регенерацию. Загрузка встроенной модели и возможность аппаратного ускорения зависят от конфигурации сервера.

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

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

Вход: Документ a1: title «Возврат оплаты», body «Заявка рассматривается службой поддержки». Запрос «как вернуть оплату».

Ожидаемый результат: Система создаёт embedding при добавлении и возвращает a1 среди релевантных кандидатов по текстовому q; в ответе нет большого числового поля благодаря exclude_fields.

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

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

1. Подберите модель по официальному списку и испытайте русские тексты на небольшом corpus.
2. Создайте float[] поле с embed.from и model_config.model_name.
3. Загрузите один документ без ручного массива embedding.
4. Выполните запрос с q и query_by=embedding и проверьте найденный id.
5. Измените поле, входящее в embed.from, и отдельно поле вне списка, затем проверьте результат индексации.

После каждого этапа сохраняйте 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":"help_auto_v1","fields":[{"name":"title","type":"string"},{"name":"body","type":"string"},{"name":"embedding","type":"float[]","embed":{"from":["title","body"],"model_config":{"model_name":"ts/all-MiniLM-L12-v2"}}}]}'

# После добавления документа: q текстовый, query_by — auto-embedding поле.
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 'exclude_fields=embedding' 

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

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

Не добавляйте в embed.from лишние нестабильные поля: частые изменения текста приводят к перерасчёту векторов и дополнительной нагрузке. Помните, что для встроенной модели CPU/GPU нужен на генерации embedding, а само nearest-neighbor извлечение документация не описывает как GPU-операцию. Русский язык необходимо проверять отдельным размеченным набором: наличие модели в списке поддерживаемых не означает достаточное качество русского поиска в вашем домене. Если модель нужно заменить, создайте новую коллекцию и переиндексируйте данные; простое переименование поля не преобразует существующие embeddings. Для консультационного бота добавьте к документу стабильный source id и отбирайте цитируемый контекст только после бизнес-фильтра.

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

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

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