인덱스 스토어 — 인덱스 메타데이터를 담는 저장소

인덱스를 만들면 노드 벡터 외에, 인덱스 자체에 관한 추가 상태 정보가 생겨요. 이 가벼운 인덱스 메타데이터를 담아두는 곳이 인덱스 스토어예요. 문서 원문(Node)을 저장하는 문서 스토어, 벡터를 저장하는 벡터 스토어와 함께 LlamaIndex의 저장 계층을 구성합니다.

출처: 공식문서

Simple Index Store

기본적으로 LlamaIndex는 인메모리 키-값 스토어로 구현된 simple index store를 써요. index_store.persist()로 디스크에 저장하고 SimpleIndexStore.from_persist_path(...)로 다시 불러올 수 있어요. 실험 단계에서 기본값으로 시작하기 좋습니다.

MongoDB Index Store

문서 스토어와 마찬가지로 MongoDB를 인덱스 스토어의 백엔드로 쓸 수 있어요.

from llama_index.storage.index_store.mongodb import MongoIndexStore
from llama_index.core import VectorStoreIndex

# create (or load) index store
index_store = MongoIndexStore.from_uri(uri="<mongodb+srv://...>")

# create storage context
storage_context = StorageContext.from_defaults(index_store=index_store)

# build index
index = VectorStoreIndex(nodes, storage_context=storage_context)

# or alternatively, load index
from llama_index.core import load_index_from_storage

index = load_index_from_storage(storage_context)

내부적으로 MongoIndexStore는 고정된 MongoDB 데이터베이스에 연결해 인덱스 메타데이터용 컬렉션을 생성(또는 기존 컬렉션을 로드)해요. db_name과 namespace를 지정하지 않으면 각각 db_name="db_docstore", namespace="docstore"가 기본값이에요.

MongoDB를 쓸 때 중요한 점은 storage_context.persist()나 index_store.persist()를 호출할 필요가 없다는 것이에요. 데이터가 기본으로 영속되기 때문입니다. 인덱스를 다시 연결하려면 기존 db_name과 collection_name으로 MongoIndexStore를 다시 초기화하면 돼요.

Redis Index Store

Redis도 인덱스 스토어 백엔드로 지원돼요. Node 객체가 인제스트될 때 데이터를 영속합니다.

from llama_index.storage.index_store.redis import RedisIndexStore
from llama_index.core import VectorStoreIndex

index_store = RedisIndexStore.from_host_and_port(
    host="127.0.0.1", port="6379", namespace="llama_index"
)

storage_context = StorageContext.from_defaults(index_store=index_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

내부적으로 RedisIndexStore는 Redis에 연결해 노드를 {namespace}/index 아래에 저장해요. namespace를 지정하지 않으면 기본값은 "index_store"예요. 기존 host, port, namespace로 다시 초기화하면 인덱스를 다시 불러올 수 있습니다.

Couchbase Index Store

Couchbase를 인덱스 스토어 백엔드로 사용할 수 있어요.

from llama_index.storage.index_store.couchbase import CouchbaseIndexStore
from llama_index.core import VectorStoreIndex

from couchbase.cluster import Cluster
from couchbase.auth import PasswordAuthenticator
from couchbase.options import ClusterOptions
from datetime import timedelta

auth = PasswordAuthenticator("DB_USERNAME", "DB_PASSWORD")
options = ClusterOptions(authenticator=auth)
cluster = Cluster("couchbase://localhost", options)
cluster.wait_until_ready(timedelta(seconds=5))

index_store = CouchbaseIndexStore.from_couchbase_client(
    client=cluster,
    bucket_name="llama-index",
    scope_name="_default",
    namespace="default",
)

storage_context = StorageContext.from_defaults(index_store=index_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

내부적으로 CouchbaseIndexStore는 지정한 {bucket_name}·{scope_name}에서 {namespace}_index라는 컬렉션에 노드를 추가해요. namespace, bucket, scope를 직접 지정할 수 있고, 기본 컬렉션은 index_store_data예요. 컬렉션 이름에는 영숫자 외에 -, _, %만 허용되며, 그 외 특수문자는 자동으로 _로 변환됩니다.

Tablestore Index Store

Tablestore도 인덱스 스토어 백엔드로 쓸 수 있어요.

from llama_index.storage.index_store.tablestore import TablestoreIndexStore
from llama_index.core import StorageContext, VectorStoreIndex

index_store = TablestoreIndexStore.from_config(
    endpoint="<tablestore_end_point>",
    instance_name="<tablestore_instance_name>",
    access_key_id="<tablestore_access_key_id>",
    access_key_secret="<tablestore_access_key_secret>",
)

storage_context = StorageContext.from_defaults(index_store=index_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

내부적으로 TablestoreIndexStore는 Tablestore에 연결해 {namespace}_data라는 테이블에 노드를 추가해요. namespace를 지정하지 않으면 기본값을 사용하며, 기존 endpoint·instance_name·access_key_id·access_key_secret으로 다시 초기화하면 인덱스를 복구할 수 있어요.

Google AlloyDB Index Store

Google Cloud의 AlloyDB를 인덱스 스토어 백엔드로 쓸 수 있어요. 이 튜토리얼은 동기 인터페이스를 보여주며, 모든 동기 메서드에는 대응하는 비동기 메서드가 있어요.

pip install llama-index
pip install llama-index-alloydb-pg
pip install llama-index-llms-vertex

from llama_index_alloydb_pg import AlloyDBEngine, AlloyDBIndexStore
from llama_index.core import StorageContext, VectorStoreIndex

engine = AlloyDBEngine.from_instance(
    project_id=PROJECT_ID,
    region=REGION,
    cluster=CLUSTER,
    instance=INSTANCE,
    database=DATABASE,
    user=USER,
    password=PASSWORD,
)

engine.init_index_store_table(table_name=TABLE_NAME)
index_store = AlloyDBIndexStore.create_sync(engine=engine, table_name=TABLE_NAME)

storage_context = StorageContext.from_defaults(index_store=index_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

테이블 생성·AlloyDBIndexStore 생성 시 schema_name을 table_name과 함께 지정할 수 있고, 기본 schema_name은 public이에요. 내부적으로 AlloyDBIndexStore는 Google Cloud의 AlloyDB 데이터베이스에 연결해 schema_name 아래 테이블에 노드를 추가합니다. 재연결할 때는 새 테이블을 만들지 않고 기존 AlloyDBEngine만으로 AlloyDBIndexStore를 다시 초기화하면 돼요.

Google Cloud SQL for PostgreSQL Index Store

Cloud SQL for PostgreSQL도 인덱스 스토어 백엔드로 쓸 수 있어요.

pip install llama-index
pip install llama-index-cloud-sql-pg

from llama_index_cloud_sql_pg import PostgresEngine, PostgresIndexStore
from llama_index.core import StorageContext, VectorStoreIndex

engine = PostgresEngine.from_instance(
    project_id=PROJECT_ID,
    region=REGION,
    instance=INSTANCE,
    database=DATABASE,
    user=USER,
    password=PASSWORD,
)

engine.init_index_store_table(table_name=TABLE_NAME)
index_store = PostgresIndexStore.create_sync(engine=engine, table_name=TABLE_NAME)

storage_context = StorageContext.from_defaults(index_store=index_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

schema_name을 table_name과 함께 지정할 수 있고 기본값은 public이에요. 재연결 시엔 새 테이블 생성 없이 기존 PostgresEngine으로 PostgresIndexStore를 다시 초기화하면 됩니다.

더 알아보기

Document Stores — 원본 문서 청크를 저장하는 문서 스토어
Vector Stores — 문서 임베딩을 저장하는 벡터 스토어
Customizing Storage — 저장 계층을 원하는 백엔드로 바꾸는 방법
Persisting & Loading Data — 인덱스 저장·불러오기 전반