StorageContext și salvarea indexului pe disc (.persist) în LlamaIndex & Data RAG

from llama_index.core import StorageContext, load_index_from_storage

# salvare
index.storage_context.persist(persist_dir="./stocare_index")

# reîncărcare
storage_context = StorageContext.from_defaults(persist_dir="./stocare_index")
index = load_index_from_storage(storage_context)

Implicit LlamaIndex ține datele în memorie, deci la oprirea procesului indexul se pierde. StorageContext reunește componentele de stocare: document store (nodurile), index store (structura indexului), vector store (embedding-urile), graph store și, la nevoie, property graph store. storage_context.persist(persist_dir=...) le scrie pe disc, în ./storage dacă nu dai alt director.

Pentru stocurile implicite, persist() scrie docstore.json, index_store.json, graph_store.json și câte un fișier <namespace>__vector_store.json pentru fiecare vector store (de exemplu default__vector_store.json și image__vector_store.json). La reîncărcare recreezi StorageContext cu aceeași configurare și apelezi load_index_from_storage(); embedding-urile nu se recalculează.

Mai mulți indecși pot sta în același director dacă le dai ID-uri (index.set_index_id(...)) și le încarci cu index_id= sau cu load_indices_from_storage(). Parametrul fs acceptă un sistem de fișiere fsspec; documentația confirmă disc local, AWS S3 și Cloudflare R2. Cu o bază vectorială externă care salvează singură datele, persist() nu mai este necesar pentru vectori.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
persist(persist_dir=...)	Scrie stocurile pe disc. Implicit ./storage.
persist(..., fs=...)	Scrie printr-un sistem de fișiere fsspec (S3, R2).
StorageContext.from_defaults(persist_dir=...)	Reîncarcă stocurile salvate.
StorageContext.from_defaults(vector_store=..., docstore=..., index_store=...)	Construiește contextul cu stocuri alese de tine.
load_index_from_storage(ctx, index_id=...)	Reface un index; index_id e obligatoriu dacă directorul conține mai mulți indecși.
load_indices_from_storage(ctx)	Încarcă toți indecșii (sau doar index_ids=[...]).

Exemple practice și scenarii reale

Exemplul 1: Construiește o dată, apoi doar reîncarcă

import os
from llama_index.core import (
    SimpleDirectoryReader, StorageContext, VectorStoreIndex, load_index_from_storage,
)

DIR = "./storage"
if not os.path.exists(DIR):
    docs = SimpleDirectoryReader("./date").load_data()
    index = VectorStoreIndex.from_documents(docs)
    index.storage_context.persist(persist_dir=DIR)
else:
    index = load_index_from_storage(StorageContext.from_defaults(persist_dir=DIR))

Exemplul 2: Doi indecși în același director

index_hr.set_index_id("hr")
index_it.set_index_id("it")
index_hr.storage_context.persist("./storage")
index_it.storage_context.persist("./storage")

ctx = StorageContext.from_defaults(persist_dir="./storage")
index_it = load_index_from_storage(ctx, index_id="it")

Greșeli frecvente și capcane

• Să reîncarci indexul cu alt Settings.embed_model decât cel folosit la construire. Vectorii salvați nu se potrivesc cu vectorii noilor întrebări.
• Mai mulți indecși în același director fără set_index_id(). La încărcare nu mai știi care e care, iar load_index_from_storage cere index_id.
• Să salvezi doar default__vector_store.json și să ștergi restul fișierelor. Indexul are nevoie și de docstore și index store ca să se refacă.

Noțiuni și module înrudite

• vector-store-integrations
• vector-store-index
• simple-directory-reader
• ingestion-pipeline