DynamoDBDocumentStore

Amazon DynamoDB는 서버리스 NoSQL 데이터베이스예요. 기본 제공되는 벡터 검색 기능이 임베딩을 테이블에 바로 있는 벡터 인덱스에 저장하므로, 문서와 그 임베딩이 운영 데이터 옆에 자리 잡게 돼요. 별도의 벡터 데이터베이스가 필요 없죠.

출처: 문서

본문

DynamoDBDocumentStore는 각 문서를 벡터 인덱스가 있는 DynamoDB 테이블의 항목(item)으로 저장하고, DynamoDB의 SearchVectors API를 코사인 유사도로 사용해 문서를 검색해요. 임베딩 검색과 메타데이터 필터링을 지원해요.

설치 (Installation)

Haystack에서 DynamoDB를 사용하려면 dynamodb-haystack 통합을 설치하세요.

pip install dynamodb-haystack

DynamoDB의 벡터 검색은 boto3 >= 1.43.66이 필요하며, 이 패키지가 함께 설치해 줘요. 벡터 인덱스를 지원하는 로컬 DynamoDB 에뮬레이터는 없으므로 AWS 계정이 필요해요.

사용법 (Usage)

자격 증명 (Credentials)

이 Document Store는 표준 AWS 자격 증명 체인을 사용해요. 자격 증명과 리전을 환경 변수로 설정하세요.

export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-east-1

Secret 인자(aws_access_key_id, aws_secret_access_key, aws_session_token)로 전달하거나, IAM 역할 같은 다른 boto3 자격 증명 소스를 사용해도 돼요.

자격 증명에는 DescribeTable, 항목 수준 연산(PutItem, DeleteItem, Scan), SearchVectors 권한이 필요해요. 스토어가 테이블을 직접 만들게 하려면 CreateTable 권한도 필요해요.

초기화 (Initialization)

DynamoDBDocumentStore 객체를 초기화하고 문서를 써 보아요.

from haystack import Document
from haystack_integrations.document_stores.dynamodb import DynamoDBDocumentStore

document_store = DynamoDBDocumentStore(
    table_name="haystack_documents",
    index_name="haystack_vector_index",
    embedding_dimension=768,
    region_name="us-east-1",
)

document_store.write_documents(
    [
        Document(content="This is first", embedding=[0.1] * 768),
        Document(content="This is second", embedding=[0.3] * 768),
    ],
)
print(document_store.count_documents())

초기화 파라미터에 대해 더 자세히 알고 싶다면 API 문서를 참고하세요.

테이블 생성 (Table creation)

create_table_if_not_exists=True(기본값)를 설정하면 스토어가 처음 사용할 때 테이블과 벡터 인덱스를 만들고, 인덱스를 조회할 수 있을 때까지(약 20초) 기다려요. 테이블은 단일 파티션 키 id를 갖고, 벡터 인덱스는 테이블과 함께 선언돼요. 기존 테이블에 벡터 인덱스를 추가하면 백필(backfill)이 발생해 벡터 검색을 몇 분 동안 막기 때문이에요.

스토어를 기존 테이블에 연결한다면, 테이블은 단일 파티션 키 id와 embedding 속성에 대한 코사인 벡터 인덱스(일치하는 index_name과 embedding_dimension 필요)를 가져야 해요. 스토어는 첫 사용 시 이를 검증하고, 불일치하면 ValueError를 발생시켜요.

제한 사항 (Limitations)

filter_documents, count_documents, 그리고 필터 기반 일괄 연산은 일관된 전체 테이블 Scan을 실행하고 필터를 클라이언트 측에서 평가하므로, 테이블 크기에 따라 비용이 증가해요.
SearchVectors는 요청당 최대 100개의 후보를 반환하므로 top_k는 100을 넘을 수 없어요. 메타데이터 필터는 이 후보들에 적용되기 때문에, 선택적인 필터를 쓰면 top_k보다 적은 문서가 반환될 수 있어요.
코사인 유사도만 지원해요. 점수는 Haystack의 "높을수록 좋음" 규약에 맞춰 변환돼요. 동일한 벡터는 1.0, 반대 벡터는 0.0이에요.
DynamoDB 항목은 400KB로 제한돼요. 따라서 문서의 내용, 메타데이터, 임베딩이 함께 이 한도 안에 들어야 해요.

문서의 임베딩을 제대로 계산하려면 Document Embedder(예: SentenceTransformersDocumentEmbedder)를 사용할 수 있어요.

지원되는 리트리버 (Supported Retrievers)

DynamoDBEmbeddingRetriever: 쿼리 임베딩을 기반으로 Document Store에서 문서를 가져오는 임베딩 기반 리트리버예요.

DynamoDBDocumentStore