РУКОВОДСТВО · ОБНОВЛЕНО 2026-10-21
Ошибка размерности embeddings: как найти и исправить несовпадение
План диагностики записи и поиска после смены embedding-модели или настроек её выхода.
Ошибка dimension mismatch означает, что длина переданного вектора не соответствует контракту выбранного индекса или поля. Сначала сравните фактический размер массива, настройки embedding-модели и конфигурацию хранилища. Не обрезайте вектор и не добавляйте нули только ради успешной записи: так можно скрыть несовместимость представлений. Если модель изменилась, обычно нужен новый согласованный индекс и повторное построение embeddings документов. Запросы к нему должны обрабатываться совместимым способом.
1. Снимите фактическую конфигурацию
Запишите точный идентификатор embedding-модели, параметры запроса, версию клиента и размер возвращённого вектора. Сравните это с настройками индекса, в который действительно идёт запись. Иногда приложение обращается к старому окружению или использует другой ключ и маршрут. Не ограничивайтесь именем переменной в конфигурационном файле: проверьте фактический адрес и ответ сервиса. При этом не выводите ключи и содержимое закрытых документов в диагностический журнал.
2. Разделите разные виды несовместимости
Вектор может иметь неверное число координат, неправильный тип данных или содержать нечисловое значение. Другой случай — модель выдаёт массив той же длины, но пространство признаков уже отличается. Такая запись может пройти техническую проверку и испортить поиск без явной ошибки. Поэтому храните рядом с индексом контракт модели и подготовки текста. Не смешивайте embeddings разных моделей только потому, что обе возвращают одинаковое количество чисел.
3. Выберите осмысленное исправление
В Pinecone размерность dense-индекса задаётся при создании и должна соответствовать embedding-модели. Конкретные возможности изменения конфигурации зависят от хранилища. Если модель официально поддерживает меньшую размерность, используйте документированный параметр и проверьте весь процесс для документов и запросов. Это отличается от произвольного среза массива в клиенте. Если старый индекс несовместим, создайте новый и пересчитайте данные контролируемыми порциями, сохраняя идентификаторы документов и статус прогресса.
4. Проверьте поиск перед переключением
Составьте набор вопросов с известными релевантными фрагментами и сравните выдачу до и после миграции. Проверьте фильтры доступа, цитаты, пустые документы и повторную загрузку. Успешная вставка одного вектора не доказывает правильный поиск по всему корпусу. На время перехода явно выбирайте версию индекса для чтения и записи, чтобы разные части приложения не использовали несовместимые контракты. Сохраняйте старый индекс до завершения проверки по принятой политике хранения и подготовьте понятный возврат.
Частые вопросы
Можно ли дополнить вектор нулями?
Не используйте это как обычное исправление несовместимости. Сначала подтвердите математическую и программную совместимость такого преобразования для конкретной модели и индекса.
Почему ошибка появилась без изменения кода?
Могли измениться маршрут, настройки модели, окружение или целевой индекс. Сравните фактические значения и историю конфигурации.
Одинаковая длина гарантирует хороший поиск?
Нет. Разные модели могут создавать разные пространства признаков при той же размерности. Документы и запросы должны быть согласованы.
Нужно ли пересчитывать весь корпус?
При смене несовместимой embedding-модели — обычно да. Объём пересчёта определяют контракт и устройство индекса, а не только текст сообщения об ошибке.