문서 스토어 — Node 객체를 담는 저장소

문서를 인제스트할 때 원문은 그대로 두지 않고, 의미 단위로 쪼갠 뒤 사용해요. LlamaIndex는 이렇게 쪼개진 문서 청크를 Node 객체라고 부르는데, 이 Node 객체들을 저장하는 곳이 문서 스토어예요. 인덱스 스토어가 메타데이터를, 벡터 스토어가 임베딩을 담당한다면, 문서 스토어는 원본 청크 그 자체를 보관하는 역할을 합니다.

출처: 공식문서

Simple Document Store

기본적으로 SimpleDocumentStore는 Node 객체를 인메모리로 저장해요. docstore.persist()로 디스크에 저장하고 SimpleDocumentStore.from_persist_path(...)로 다시 불러올 수 있어요. 파이프라인을 처음 만들 때는 이 기본값이면 충분합니다.

MongoDB Document Store

MongoDB를 문서 스토어 백엔드로 쓰면 Node 객체가 인제스트될 때 데이터가 영속돼요.

from llama_index.storage.docstore.mongodb import MongoDocumentStore
from llama_index.core.node_parser import SentenceSplitter

# create parser and parse document into nodes
parser = SentenceSplitter()
nodes = parser.get_nodes_from_documents(documents)

# create (or load) docstore and add nodes
docstore = MongoDocumentStore.from_uri(uri="<mongodb+srv://...>")
docstore.add_documents(nodes)

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

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

내부적으로 MongoDocumentStore는 고정된 MongoDB 데이터베이스에 연결해 노드용 컬렉션을 생성(또는 로드)해요. db_name·namespace를 지정하지 않으면 기본값은 db_name="db_docstore", namespace="docstore"예요. MongoDB를 쓰면 storage_context.persist()나 docstore.persist()를 호출하지 않아도 데이터가 기본 영속됩니다.

Redis Document Store

Redis를 문서 스토어 백엔드로 쓸 수 있어요.

from llama_index.storage.docstore.redis import RedisDocumentStore
from llama_index.core.node_parser import SentenceSplitter

parser = SentenceSplitter()
nodes = parser.get_nodes_from_documents(documents)

docstore = RedisDocumentStore.from_host_and_port(
    host="127.0.0.1", port="6379", namespace="llama_index"
)
docstore.add_documents(nodes)

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

RedisDocumentStore는 Redis에 연결해 노드를 {namespace}/docs 아래에 저장해요. namespace 기본값은 "docstore"이며, 기존 host·port·namespace로 다시 초기화하면 문서 스토어를 복구할 수 있어요.

Firestore Document Store

Google Cloud의 Firestore를 문서 스토어 백엔드로 쓸 수 있어요.

from llama_index.storage.docstore.firestore import FirestoreDocumentStore
from llama_index.core.node_parser import SentenceSplitter

parser = SentenceSplitter()
nodes = parser.get_nodes_from_documents(documents)

docstore = FirestoreDocumentStore.from_database(
    project="project-id",
    database="(default)",
)
docstore.add_documents(nodes)

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

FirestoreDocumentStore는 Google Cloud의 Firestore 데이터베이스에 연결해 {namespace}/docs 아래에 노드를 저장해요. namespace 기본값은 "docstore"이고, 기존 project·database·namespace로 다시 초기화하면 복구됩니다.

Couchbase Document Store

Couchbase를 문서 스토어 백엔드로 쓸 수 있어요.

from llama_index.storage.docstore.couchbase import CouchbaseDocumentStore
from llama_index.core.node_parser import SentenceSplitter

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))

parser = SentenceSplitter()
nodes = parser.get_nodes_from_documents(documents)

docstore = CouchbaseDocumentStore.from_couchbase_client(
    client=cluster,
    bucket_name="llama-index",
    scope_name="_default",
    namespace="default",
)
docstore.add_documents(nodes)

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

CouchbaseDocumentStore는 지정한 {bucket_name}·{scope_name}에서 {namespace}_data라는 컬렉션에 노드를 추가해요. 기본 컬렉션은 docstore_data이며, 컬렉션 이름에는 영숫자 외에 -, _, %만 허용되고 그 외 특수문자는 _로 변환됩니다.

Tablestore Document Store

Tablestore를 문서 스토어 백엔드로 쓸 수 있어요.

from llama_index.core import Document
from llama_index.core import StorageContext, VectorStoreIndex
from llama_index.core.node_parser import SentenceSplitter

from llama_index.storage.docstore.tablestore import TablestoreDocumentStore

parser = SentenceSplitter()
documents = [
    Document(text="I like cat.", id_="1", metadata={"key1": "value1"}),
    Document(text="Mike likes dog.", id_="2", metadata={"key2": "value2"}),
]
nodes = parser.get_nodes_from_documents(documents)

docs_tore = TablestoreDocumentStore.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>",
)
docs_tore.add_documents(nodes)

storage_context = StorageContext.from_defaults(docstore=docs_tore)
index = VectorStoreIndex(nodes, storage_context=storage_context)

TablestoreDocumentStore는 Tablestore 데이터베이스에 연결해 {namespace}_data라는 테이블에 노드를 추가해요. 기존 endpoint·instance_name·access_key_id·access_key_secret으로 다시 초기화하면 복구할 수 있습니다.

Google AlloyDB Document Store

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

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

from llama_index.core import SummaryIndex
from llama_index_alloydb_pg import AlloyDBEngine, AlloyDBDocumentStore

parser = SentenceSplitter()
nodes = parser.get_nodes_from_documents(documents)

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

engine.init_doc_store_table(table_name=TABLE_NAME)

doc_store = AlloyDBDocumentStore.create_sync(engine=engine, table_name=TABLE_NAME)
doc_store.add_documents(nodes)

storage_context = StorageContext.from_defaults(docstore=doc_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

테이블 생성·AlloyDBDocumentStore 생성 시 schema_name을 지정할 수 있고 기본값은 public이에요. 재연결 시엔 기존 AlloyDBEngine만으로 다시 초기화하면 됩니다.

Google Cloud SQL for PostgreSQL Document Store

Cloud SQL for PostgreSQL을 문서 스토어 백엔드로 쓸 수 있어요.

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

from llama_index.core import SummaryIndex
from llama_index_cloud_sql_pg import PostgresEngine, PostgresDocumentStore

parser = SentenceSplitter()
nodes = parser.get_nodes_from_documents(documents)

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

engine.init_doc_store_table(table_name=TABLE_NAME)

doc_store = PostgresDocumentStore.create_sync(engine=engine, table_name=TABLE_NAME)
doc_store.add_documents(nodes)

storage_context = StorageContext.from_defaults(docstore=doc_store)
index = VectorStoreIndex(nodes, storage_context=storage_context)

schema_name을 지정할 수 있고 기본값은 public이에요. 재연결 시엔 기존 PostgresEngine으로 다시 초기화하면 됩니다.

더 알아보기

Vector Stores — 문서 임베딩을 저장하는 벡터 스토어
Index Stores — 인덱스 메타데이터를 담는 인덱스 스토어
Key-Value Stores — 문서·인덱스 스토어의 기반이 되는 키-값 저장소
Customizing Storage — 저장 계층을 원하는 백엔드로 바꾸는 방법