Исправляем ImportError MISTRAL_INPUTS_DOCSTRING в NVIDIA/nv-embed-v2 (Transformers)

ImportError при загрузке NVIDIA/nv-embed-v2 в Transformers? Причина — MISTRAL_INPUTS_DOCSTRING. Проверьте среду и закрепите Transformers 4.42.4 для работы.

При загрузке NVIDIA/NV-Embed-v2 через Hugging Face Transformers некоторые пользователи сталкиваются с ImportError, связанным с внутренним кодом Mistral. Сбой проявляется сразу после инициализации модели с включённым trust_remote_code и обычно указывает на отсутствующий символ в реализации Mistral.

Минимальный пример, воспроизводящий проблему

Ниже приведён фрагмент, показывающий типичную настройку эмбеддинга, которая вызывает ошибку в несовместимых окружениях:

from transformers import AutoTokenizer, AutoModel
repo_id = "NVIDIA/nv-embed-v2"
enc_tok = AutoTokenizer.from_pretrained(repo_id)
enc_model = AutoModel.from_pretrained(repo_id, trust_remote_code=True)
enc_model.eval()

В окружениях, где проблема возникает, трассировка Python ссылается на отсутствующее имя в modeling_mistral.py.

ImportError: cannot import name 'MISTRAL_INPUTS_DOCSTRING' from 'transformers.models.mistral.modeling_mistral'

Что происходит на самом деле

Корневая причина — несовпадение версий пакета Transformers. Символ MISTRAL_INPUTS_DOCSTRING присутствует в Transformers вплоть до 4.51.3 и удалён начиная с 4.52.0, включая более новые релизы линейки 4.53.x. Если рантайм подхватывает более свежую сборку Transformers, а ваш код рассчитывает, что символ существует, импорт внутренних модулей Mistral завершается с ImportError. Такое нередко случается, когда активно другое виртуальное окружение, IDE использует интерпретатор, отличный от терминала, или интерпретатор не был перезапущен после обновления библиотеки.

Как проверить среду выполнения

Не полагайтесь на предположения — посмотрите, что именно запущено в текущем процессе Python. Проверьте версию Transformers в том же интерпретаторе, где выполняется код модели:

import transformers
print(transformers.__version__)

При необходимости также уточните версию Python и путь к интерпретатору, чтобы убедиться, что используется ожидаемое виртуальное окружение:

import sys
print(sys.version)
print(sys.executable)

Исправление: закрепите совместимую версию Transformers и перезапустите интерпретатор

Если обнаруженная версия несовместима, установите выпуск, где символ присутствует. Пользователи подтвердили, что работает 4.42.4, а карточка модели предлагает 4.42.2. После установки перезапустите IDE или сессию Python, чтобы рантайм действительно использовал новую версию.

pip install -U transformers==4.42.4

Когда окружение согласовано, исходный код менять не нужно. Для полноты — та же настройка с отдельными локальными именами:

from transformers import AutoTokenizer, AutoModel
repo_id = "NVIDIA/nv-embed-v2"
enc_tok = AutoTokenizer.from_pretrained(repo_id)
enc_model = AutoModel.from_pretrained(repo_id, trust_remote_code=True)
enc_model.eval()

Почему это важно

Модели эмбеддингов, использующие trust_remote_code, могут ссылаться на внутренние части конкретных версий библиотек. Если ваша среда тихо обновилась до сборки, в которой внутренний символ удалён, код, который раньше работал, внезапно перестаёт запускаться. Воспроизводимые ML‑конвейеры зависят от фиксации версий и проверки точного интерпретатора, используемого инструментами, особенно при переключении между терминалами, ноутбуками и IDE.

Итоги

Если при загрузке NVIDIA/NV-Embed-v2 возникает ImportError вокруг MISTRAL_INPUTS_DOCSTRING, проверьте версию Transformers в работающем процессе, убедитесь, что активны нужные venv и интерпретатор, и закрепите проверенный релиз, например 4.42.4, учитывая рекомендации карточки модели про 4.42.2. После переустановки перезапустите IDE, чтобы подтянулся корректный набор зависимостей. Эта несложная рутина экономит время и делает пайплайны эмбеддингов стабильными и предсказуемыми.