Как сохранить и загрузить индекс LlamaIndex после перезапуска

1. Постройте тестовый индекс из документа с устойчивым ID и зафиксируйте выбранную модель embeddings.
2. Запишите его storage_context в отдельный каталог с явно указанным persist_dir.
3. Завершите процесс и запустите другой процесс, создав StorageContext из того же каталога.
4. Загрузите индекс без вызова from_documents и проведите тот же контрольный запрос.
5. Ограничьте права чтения каталога и проверьте, что резервная копия восстанавливается независимо от исходного процесса.

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

from llama_index.core import Document, VectorStoreIndex
from llama_index.core import StorageContext, load_index_from_storage

directory = "./storage-r7"
# Шаг в первом процессе, требует доступной embedding-модели.
index = VectorStoreIndex.from_documents([
    Document(text="Возврат по R7: 14 дней.", id_="R7")])
index.storage_context.persist(persist_dir=directory)

# Шаг после перезапуска: не вызывайте from_documents повторно.
context = StorageContext.from_defaults(persist_dir=directory)
restored = load_index_from_storage(context)
print(len(restored.as_retriever(similarity_top_k=1).retrieve("возврат")))

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

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

Вход: документ R7 со сроком 14 дней и каталог storage-r7. Ожидается, что второй процесс загружает сохранённый индекс и запрос возвращает связанный с R7 текст. Число успешных ответов не доказывает, что используются актуальные данные: отдельно сопоставьте версию документа и метаданные индекса.

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

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

Главная проверка — именно новый процесс, а не повторная загрузка в том же Python-сеансе. Иначе можно случайно получать объект из памяти и решить, что файлы сохранены корректно. При нескольких индексах в одной папке сохраните их IDs отдельно и передайте нужный index_id; выбор произвольного индекса сделает тест ложноположительным. Перемена embedding-модели после восстановления способна изменить смысл запросов или сломать совместимость пространства векторов; сохраняйте сведения о версии модели вместе со снимком. Папка persist_dir — состояние приложения, поэтому нужны права доступа, резервное копирование и план восстановления, а не только инструкция «скопировать файлы». Если используется внешний vector store, копия локальной папки может не охватывать удалённые векторы: сверяйте полную схему хранения. Не удаляйте рабочий индекс, пока не проверите новое восстановление на отдельном стенде.

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

Чтобы проверить отсутствие повторной индексации, сделайте исходный файл недоступным перед запуском второго процесса: восстановление должно пользоваться сохранённым контекстом, а не перечитывать источник. При ошибке поиска после восстановления проверьте три слоя: файлы index/doc/vector store, наличие ID и модель для запроса. Копирование каталога во время записи может дать неполный снимок; для production нужна согласованная процедура резервирования. Зафиксируйте контрольную фразу и список разрешённых источников как манифест рядом с версией модели, но не храните там секреты доступа. Если два сервера обслуживают запросы, локальная папка одного сервера не становится автоматически доступной второму; архитектура хранения должна отражать реальный деплой.

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