Как создать векторное поле Typesense: float[], num_dim и проверка модели

В официальном справочнике коллекций num_dim превращает float[] в векторное поле. vec_dist по умолчанию cosine; альтернативный ip выбирают по контракту конкретной embedding-модели. Четыре координаты ниже нужны лишь для читаемого теста: документация рекомендует реальные векторы хотя бы от 256 измерений для качественных результатов. Выбор метрики здесь фиксируется в схеме, а не угадывается по форме пользовательского вопроса.

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

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

Вход: Манифест модели encoder-v1, реальный выход длины 4 [0.7,0.1,0.1,0.2]; контрольная отрицательная строка содержит только три числа.

Ожидаемый результат: GET коллекции показывает поле embedding с num_dim:4 и vec_dist:cosine; документ с четырьмя числами принимается, несовместимый вектор не должен пройти проверку ingestion.

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

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

1. Проверьте у энкодера размерность и описание similarity; сохраните его точный model ID.
2. Создайте новую коллекцию с версионным именем и полем float[], задав ненулевой num_dim.
3. При выборе ip подтвердите, что его требует именно используемая модель; иначе оставьте подтверждённый cosine.
4. Индексируйте одну тестовую запись, прочитайте её и испытайте заведомо неверную длину.
5. Запишите schema JSON, model ID и распределение длин векторов в акте приёмки.

После каждого этапа сохраняйте 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_vec_v1","fields":[{"name":"title","type":"string"},{"name":"tenant","type":"string","facet":true},{"name":"embedding","type":"float[]","num_dim":4,"vec_dist":"cosine"}]}' 

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

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

Для боевого индекса не подставляйте иллюстративное 4. Например, если ваша модель действительно отдаёт 384 числа, то оба значения — длина каждого массива и num_dim — равны 384. Смена версии энкодера при той же длине не делает старые embeddings совместимыми: одинаковые координатные размеры могут обозначать совершенно другое пространство. Создайте articles_vec_v2, пересчитайте корпус и запросы, а затем сравните оба индекса на одинаковом списке задач. Метрика cosine и ip тоже не являются взаимозаменяемыми: пороги и порядок результатов нужно калибровать заново. Сам Typesense не может удостовериться, что числа получены нужной моделью, поэтому храните этот факт в собственном манифесте.

Размерность — техническая проверка формы данных, но не проверка их смысла. Приложите к схеме пять пар близких и пять несвязанных текстов с ожидаемыми ранжированиями. Только после такого теста можно утверждать, что модель и метрика дают пригодный для конкретной предметной области результат.

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

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