Как задать embedding-модель локально в LlamaIndex и не смешать индексы

1. Зафиксируйте идентификатор и конфигурацию embedding-модели в манифесте индекса.
2. Создайте модель один раз и передайте её явно как embed_model в конкретный VectorStoreIndex.
3. Не меняйте Settings.embed_model незаметно для уже созданных индексов в долгоживущем процессе.
4. После сохранения и повторной загрузки проверьте ту же модель и контрольный запрос.
5. При миграции создавайте новый индекс и сравните retrieval до переключения, не смешивая векторы двух моделей.

Готовый шаблон Python

from llama_index.core import Document, VectorStoreIndex, Settings
from llama_index.embeddings.openai import OpenAIEmbedding

model = OpenAIEmbedding(model="text-embedding-3-small")
docs = [Document(text="Правило R7: возврат 14 дней.", id_="R7")]
# Локальная конфигурация индекса предпочтительна для явного эксперимента.
index = VectorStoreIndex.from_documents(docs, embed_model=model)
print(index.as_retriever(similarity_top_k=1).retrieve("срок возврата"))
# Settings.embed_model = model задаёт глобальный fallback для других интерфейсов.
print(type(Settings).__name__)

Код ниже в статье предназначен для тестовых источников без персональных сведений. Вызовы SDK не выполнялись в данном окружении с реальной моделью; синтаксис Python проверен отдельно. Не переносите вывод демонстрационного эксперимента на любой корпус и любого провайдера без повторной проверки.

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

Вход: один документ R7 и вопрос «срок возврата». Ожидается извлечение фрагмента R7 при доступной модели и её ключе. Если другой процесс использует embeddings иной модели для того же индекса, результат не следует считать сопоставимым даже при одинаковой длине вектора. Факт наличия ответа проверяйте вместе с зафиксированной конфигурацией.

Сохраните входные файлы, идентификаторы документов и ожидаемое утверждение в отдельном проверочном наборе. При неуспехе выделяйте слой ошибки: чтение источника, преобразование в nodes, получение embedding, поиск, синтез ответа или UI. Правильная форма ответа ещё не гарантирует правильного происхождения сведений.

Диагностика и границы решения

Глобальные настройки удобны для маленького скрипта, но опасны в сервисе, где одни и те же процессы обслуживают несколько индексов и команд. Изменение Settings.embed_model в одном месте может изменить поведение другого компонента, который полагался на fallback. Явная локальная передача embed_model делает эксперимент воспроизводимым и уменьшает скрытую связность. Это не означает, что модель автоматически попадёт в сохранённую папку: фиксируйте её ID и нужную конфигурацию отдельно. При загрузке индекса старая модель документов и новая модель вопросов могут иметь одинаковую размерность, но разное смысловое пространство, поэтому одного теста длины вектора недостаточно. Для приложений с отдельной LLM и embedding-моделью ведите разные версии; смена генератора не обязательно требует переиндексации, смена embedding-модели обычно требует. Не указывайте вымышленную цену API или гарантию доступности модели в своём аккаунте.

Дополнительный проверочный сценарий

Сделайте контрольные вопросы по точной фразе, перефразировке и отрицанию, затем сохраните их результаты до миграции. При новой модели постройте отдельный индекс из того же корпуса и измерьте hit rate, а не переписывайте старые векторы в том же хранилище вслепую. После переключения проверяйте идентификатор модели в конфигурации запросного сервиса на каждой реплике. В многопроцессном деплое суть проблемы не сводится к одному Python singleton: разные процессы могут стартовать с разным конфигом. Готовьте диагностический endpoint, показывающий безопасные версии модели и индекса без ключей, и сигнализируйте о несовпадении. Секреты провайдера должны храниться на сервере, не в опубликованном примере.

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