Как подключить OpenAI embedder к Meilisearch и проверить индексацию

Порядок действий

1. Сохраните ключ провайдера в серверном secret store и создайте непубличный ключ Meilisearch с достаточными правами; не добавляйте оба ключа во frontend.
2. Сформируйте короткий шаблон из title и body, не включая ID пользователя, приватные notes и технические поля.
3. Отправьте PATCH settings/embedders с именем ru-kb-v1; подставьте секреты только в защищённом окружении.
4. Дождитесь завершения task и проверьте её статус; задача с ошибкой провайдера не равнозначна успешно созданным embeddings.
5. Выполните два поисковых запроса: буквальный и перефразированный; сравните source IDs, а не только общие scores.

После каждого шага сохраняйте ID операции или задачи, связанные с тестом версии модели, а не только HTTP-статус. Если задача окончилась ошибкой, не скрывайте её повторным запросом к поиску: сначала устраняйте причину. Применение к Meilisearch Cloud и самостоятельной установке зависит от доступности endpoint и полномочий ключа; здесь используются точные имена HTTP API из официальной документации, но не выдуманные пункты интерфейса.

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

PATCH /indexes/kb/settings/embedders
{"ru-kb-v1":{"source":"openAi","model":"text-embedding-3-small",
  "apiKey":"${OPENAI_API_KEY}",
  "documentTemplate":"Заголовок: {{doc.title}}. Содержание: {{doc.body}}"}}

POST /indexes/kb/search
{"q":"как вернуть оплату", "hybrid":{"embedder":"ru-kb-v1","semanticRatio":1.0},"limit":5}

Никогда не копируйте заглушки URL, API key, model ID или тестовые vectors в рабочую систему без замены и проверки. Векторы длины три демонстрируют контракт данных; они не представляют реальную языковую модель и не позволяют обещать заданный порядок поисковых результатов.

Пример входа и ожидаемого результата

Вход: документ refund:1 говорит «возврат средств после отмены заказа», запрос — «как вернуть оплату»; рядом есть нерелевантный документ ship:1 о доставке. После обработки tasks ожидается появление refund:1 в top-5. Здесь нет гарантии конкретной позиции: она зависит от модели и корпуса; заранее сохраните ожидаемый ID как тестовое требование.

Что важно при внедрении

Если индекс небольшой, smoke-тест может выглядеть убедительно даже при плохом шаблоне: модель видит одни и те же слова и отвечает правильно. Создайте набор из буквальных артикулов, синонимов, отрицаний и долгих вопросов. Проверяйте Recall@5 по документам, а не впечатление от одного ответа LLM. Когда ключ провайдера недействителен, ищите статус и детали task, не повторяйте поиск до бесконечности. Если задача завершена, но часть документов не представлена семантически, проверьте наличие нужных полей в шаблоне, пропуски body, изменения модели и длину текста. Используйте отдельное имя embedder при миграции версии модели: смешивать числовые пространства старого и нового эмбеддера нельзя. Перед выдачей модели генерации оставляйте ID и текст первоисточника, не выдавая человеку только числовую оценку похожести. Реальные вызовы API и генерация векторов могут потреблять лимиты провайдера; стоимость и скорость зависят от вашего аккаунта, поэтому никаких фиксированных цен или сроков в инструкции нет.

Критерии проверки

• Task завершена успешно, а не только поставлена в очередь.
• Перефразированный canary находит refund:1 в top-5.
• Вектор и секреты отсутствуют в публичном ответе и логах frontend.
• Проверена релевантность на наборе русских запросов.

Сделайте повторный запуск тех же запросов после изменения модели, схемы, API поставщика или состава корпуса. Фиксируйте source IDs, текст-основание ответа, долю верных top-k и задержку на одинаковых данных. Для RAG найденный hit — свидетельство релевантности, не разрешение придумывать содержание: генератору передавайте только допустимые фрагменты, а утверждения проверяйте по первоисточнику.