Embeddings API для RAG и семантического поиска

Embedding-модель преобразует текст в числовой вектор. Вектор можно сохранить в поисковом индексе и сравнить с вектором запроса пользователя: так работает семантический поиск, когда совпадения ищутся по смыслу, а не по точным словам.

Сам по себе эмбеддинг не генерирует ответ на вопрос. В RAG-сценарии сначала находят подходящие фрагменты документов, а затем передают их текстовой модели вместе с вопросом — уже она формулирует ответ. Это разделение важно для архитектуры и бюджета: эмбеддинги используются для индексации и поиска, генерация — отдельный вызов.

В публичном каталоге на 19.10.2026 доступны две embedding-модели: text-embedding-3-small и text-embedding-3-large. Точный список для вашего ключа отдаёт GET /v1/models, а назначение, ограничения и единицу цены смотрите в карточке модели на /price. Доступность зависит от текущего каталога, ключа и тарифа.

Главное правило: документы и поисковые запросы кодируйте одной моделью с одинаковыми настройками размерности. Векторы разных моделей нельзя считать совместимыми только потому, что их длина совпадает. Если меняете модель, создайте новый индекс, заново закодируйте документы и сравните качество поиска до переключения production.

Рядом с индексом храните ID модели, её настройки и размерность: без этих данных невозможно понять, почему старые векторы перестали давать корректные результаты. Размерность и метрику расстояния выбирайте по контракту модели и возможностям вашего векторного хранилища.

• Документы и запросы — одной моделью и одинаковой размерностью.
• При смене модели — новый индекс и полная переиндексация.
• ID модели, настройки и размерность храните рядом с индексом.
• Проверяйте доступность модели для своего ключа до массовой индексации.

Рабочий пайплайн состоит из последовательных шагов, и каждый из них влияет на качество. Сначала документы разбиваются на осмысленные фрагменты с сохранением ID документа и позиции. Затем фрагменты кодируются embedding-моделью и записываются в индекс. Во время запроса кодируется текст вопроса, выполняется поиск ближайших векторов, найденные фрагменты добавляются в контекст — и только потом вызывается текстовая модель.

Разбиение документов — отдельное решение: слишком крупные фрагменты размывают смысл, слишком мелкие теряют контекст. Длина одного элемента и суммарный объём запроса — разные ограничения. Размер групп подбирайте постепенно: большой массив текстов не отменяет лимит отдельного элемента.

• Разбейте документы на фрагменты с ID и позицией.
• Закодируйте фрагменты и сохраните векторы в индекс.
• На запросе закодируйте вопрос и найдите ближайшие фрагменты.
• Передайте найденный контекст текстовой модели для ответа.
• Обновляйте векторы при изменении документа.

Ограничения длины текста, числа элементов в одном запросе и размерности зависят от модели — универсальных числовых значений для всех моделей нет. Сверяйте опубликованные ограничения для выбранного тарифа и уточняйте неподтверждённые параметры до массовой индексации.

Стоимость и единицу тарификации смотрите в каталоге цен: предварительный подсчёт токенов — это оценка, окончательный расход виден в истории запросов. Для больших массивов индексируйте пакетами с сохранением соответствия «текст — вектор» по полю index в ответе.

При ошибке проверьте ключ, ID модели, форму input и доступные лимиты, затем разберите код ошибки. После таймаута сначала проверьте историю и расход: исходный запрос мог уже быть обработан и оплачен, поэтому автоматически повторять всю группу текстов не стоит.

Подготовьте реальные вопросы и ожидаемые релевантные документы. Сравнивайте долю попаданий нужного документа в первые результаты, ошибки на русских терминах и именах, стоимость индексации, время запроса и объём хранилища.

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

Отдельно проверьте устойчивость к языку и терминам: русские словоформы, аббревиатуры и названия продуктов могут давать неожиданные результаты при поиске по смыслу. Хороший тестовый набор содержит вопросы, ответы на которые разбросаны по разным документам, и вопросы с точными формулировками из базы — это показывает, где семантический поиск дополняет, а где уступает точному.

Храните версию индекса вместе с конфигурацией приложения: модель, настройки, дата индексации и список документов. Так проще объяснить изменения в качестве поиска и откатиться, если новая модель или разбиение ухудшили результат на вашем наборе.