Как загрузить embeddings в Typesense через JSONL и найти ошибки по строкам

Документация Documents API прямо предупреждает: endpoint импорта возвращает HTTP 200 даже при частичных ошибках. Каждая строка ответа соответствует строке запроса, а success:false требует расследования. action=upsert создаёт либо заменяет документ с тем же id и подразумевает отправку полного документа; для частичного изменения существует другой режим update. Нельзя превращать поле embedding в необязательное при неудачном преобразовании, иначе запись окажется без поискового вектора.

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

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

Вход: Две валидные JSONL-строки с уникальными id и одна тестовая с трехмерным embedding при num_dim:4.

Ожидаемый результат: Ответ содержит по строке на документ; две валидные имеют success:true, ошибочная — success:false с причиной, а повторный импорт не увеличивает число уникальных id.

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

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

1. Проверьте наличие схемы и точную размерность до запуска импорта.
2. Назначьте стабильные строковые id; сохраните manifest id→источник→версия модели.
3. Запишите ровно один корректный JSON-объект в каждой строке JSONL без общей квадратной скобки.
4. Отправьте файл через /collections/:collection/documents/import?action=upsert.
5. Разберите весь ответ построчно, сопоставьте номер строки и id, отправьте неудачные записи на исправление.

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

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

# Файл batch.jsonl содержит по одному JSON-объекту на строку:
{"id":"a1","title":"Возврат оплаты","embedding":[0.7,0.1,0.1,0.2]}
{"id":"a2","title":"Доставка заказа","embedding":[0.1,0.6,0.2,0.1]}

curl -X POST 'http://localhost:8108/collections/articles_vec_v1/documents/import?action=upsert&return_id=true' \
  -H "X-TYPESENSE-API-KEY: $TYPESENSE_API_KEY" \
  -H 'Content-Type: text/plain' --data-binary @batch.jsonl

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

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

Типичная ошибка пайплайна — считать статус 200 подтверждением всей пачки. Заведите счётчики submitted, success, failed и rejected_by_validator и потребуйте submitted = success + failed, а число индексационных successes сверяйте с уникальными id. Сохраняйте тела неуспешных строк в ограниченном журнале без секретов и персональных данных. Для повторных запусков upsert удобен, если весь документ собран из единого источника истины; частичный patch через upsert рискует убрать старые поля. Официальный batch_size управляет серверной обработкой, а не форматом файла. Не повышайте его наугад: увеличение может ухудшить задержку поиска и временное потребление памяти. Отдельный запрос импорта ограничен документацией максимальным размером 10 GB; практические пачки следует ограничить по доступной памяти и времени повторного запуска.

Подайте в тестовый batch заведомую ошибку и убедитесь, что мониторинг реально поднимает сигнал. Без отрицательного теста красивый зелёный dashboard лишь свидетельствует, что транспорт HTTP работает, но ничего не говорит об индексировании текстов для нейросетевого поиска.

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

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