インデックスの作成と保存

概要

LlamaIndex（旧 GPT Index）では、インデックスをメモリで生成したあとに永続化（persist）しておくことで、
再起動のたびに再インデックスを行う時間とコストを省けます。
永続化の方法は大きく ①ローカル ファイルシステム、②外部ベクトル DB／クラウドストレージ、③独自バックエンド（MongoDB など） の３通りに整理できます。

---

1. 最小構成：ローカルディスクへの永続化

python
from llama_index.core import VectorStoreIndex, StorageContext, SimpleDirectoryReader

# 1) ドキュメント読込
docs = SimpleDirectoryReader("./data").load_data()

# 2) StorageContext を「永続化用ディレクトリ」とひも付ける
storage_context = StorageContext.from_defaults(persist_dir="./storage")

# 3) インデックス作成
index = VectorStoreIndex.from_documents(docs, storage_context=storage_context)

# 4) ディスクへ保存（persist）
index.storage_context.persist()          # persist_dir を省略すると ./storage

• storage_context.persist() が呼ばれると、
  ./storage/ 直下に docstore.json / index_store.json / vector_store/ などが生成されますdocs.llamaindex.ai。

• 非同期 I/O でない限り、完了時点で安全にファイルが書き出されています。

再読み込み

python
from llama_index.core import StorageContext, load_index_from_storage

sc = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(sc)      # 複数ある場合は index_id を指定

ストレージ側の設定（persist_dir だけでなく、独自 vector_store など）を再現してからロードする点が重要ですdocs.llamaindex.ai。

---

2. 複数インデックス運用と index_id

同じフォルダに複数のインデックスを保存する場合は

python
index.set_index_id("legal_docs")
index.storage_context.persist()

として ID 付きで保存し、ロード時に index_id="legal_docs" を渡しますdocs.llamaindex.ai。
ID を付けずに保存すると、フォルダ内に１つしかインデックスが無い前提でロードが行われます。

---

3. VectorStore を併用するケース

3-1. Chroma などの外部ベクトル DB

python
import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore

db = chromadb.PersistentClient(path="./chroma_db")
collection = db.get_or_create_collection("quickstart")
vector_store = ChromaVectorStore(chroma_collection=collection)

storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(docs, storage_context=storage_context)

• ベクトル自体は Chroma がディスクに自動保存するため、
  インデックス側ではメタ情報のみが persist されますdocs.llamaindex.ai。

• 既存ベクトルストアから直接復元する場合は
  VectorStoreIndex.from_vector_store(vector_store, storage_context=storage_context)
  を使いますdocs.llamaindex.ai。

3-2. FAISS/Weaviate など

ベクトルストアごとに「永続化 API の有無・呼び出しタイミング」が異なるので、
各ライブラリの save_index() 等と組み合わせて下さい。

---

4. リモートバックエンド（S3 等）への保存

LlamaIndex は fsspec 互換のファイルシステムを受け取れるため、
同一 API でクラウドバケットに保存できます。

python
import s3fs, os
fs = s3fs.S3FileSystem(
    key=os.getenv("AWS_ACCESS_KEY_ID"),
    secret=os.getenv("AWS_SECRET_ACCESS_KEY"),
    endpoint_url="https://<account>.r2.cloudflarestorage.com",
    s3_additional_kwargs={"ACL": "public-read"},
)

index.set_index_id("vector_index")
index.storage_context.persist(persist_dir="llama-index/storage_demo", fs=fs)

ロード時は同じ fs と persist_dir を渡して load_index_from_storage(...) を呼ぶだけですdocs.llamaindex.ai。

---

5. 保存フォーマットの内訳

フォーマットは後方互換を保ちつつ随時拡張されています。
Git などでバージョン管理しておくとマイグレーション時に安全です。

---

6. インクリメンタル更新と再永続化

python
new_docs = SimpleDirectoryReader("./new_data").load_data()
for d in new_docs:
    index.insert(d)        # VectorStoreIndex は内部で差分埋め込みを追加
index.storage_context.persist()

• insert() 後に 同じストレージへ persist すれば差分だけが書き込まれます。

• delete() や update() が必要な場合は Document ID を指定して操作し、最後に persist します。

---

7. ベストプラクティスまとめ

1. 生成直後に必ず persist() ― 再学習コスト節約。

2. 同一の chunk 戦略・埋め込みモデルで読み込む ― 不整合防止。

3. index_id を明示し、環境ごとにフォルダを分ける。

4. 外部ストレージの場合は vector_store 自体のバックアップポリシーも確認。

5. Schema 変更時（例：カスタム Node 属性を追加）は、
   フォルダを分けるかバージョン番号をサフィックスに付けて安全に移行。

これらを押さえておくことで、LlamaIndex で構築した検索／RAG 基盤を安定して運用できます。