AlloyDBDocumentStore

API reference: AlloyDB GitHub link: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/alloydb

출처: 문서

본문

AlloyDB는 Google Cloud의 완전 관리형 PostgreSQL 호환 데이터베이스 서비스예요. AlloyDBDocumentStore는 pgvector 확장을 사용해 벡터 유사도 검색을 수행합니다.

연결은 AlloyDB Python Connector를 통해 안전하게 처리돼요. 이 커넥터는 TLS 암호화와 IAM 기반 인증을 제공해서, 수동 SSL 인증서 관리, 방화벽 규칙, IP 허용 목록이 필요 없죠.

AlloyDBDocumentStore는 임베딩 검색, 키워드 검색, 메타데이터 필터링을 지원해요.

Installation

alloydb-haystack 통합을 설치하세요:

pip install alloydb-haystack

AlloyDB 클러스터와 인스턴스를 설정하려면 AlloyDB quickstart를 따르세요.

Usage

Authentication

AlloyDBDocumentStore는 Secrets를 사용하며 기본적으로 환경 변수에서 연결 정보를 읽어요:

ALLOYDB_INSTANCE_URI: projects/PROJECT/locations/REGION/clusters/CLUSTER/instances/INSTANCE 형식의 AlloyDB 인스턴스 URI
ALLOYDB_USER: 데이터베이스 사용자. IAM 데이터베이스 인증을 쓸 때는 서비스 계정 이메일(.gserviceaccount.com 생략) 또는 전체 IAM 사용자 이메일을 사용하세요.
ALLOYDB_PASSWORD: 데이터베이스 비밀번호. enable_iam_auth=True일 때는 필요하지 않아요.

export ALLOYDB_INSTANCE_URI="projects/MY_PROJECT/locations/MY_REGION/clusters/MY_CLUSTER/instances/MY_INSTANCE"
export ALLOYDB_USER="my-db-user"
export ALLOYDB_PASSWORD="my-db-password"

비밀번호 대신 IAM으로 인증하려면 enable_iam_auth=True로 설정하고 IAM 주체에 AlloyDB Client 역할을 부여하세요. 자세한 내용은 AlloyDB IAM 인증 문서를 참고하세요.

Initialization

AlloyDBDocumentStore를 초기화하고 Documents를 작성해요. AlloyDB 연결은 첫 사용 시 지연(lazily) 설정되며, Haystack Documents를 저장하는 테이블은 없으면 자동으로 만들어집니다:

from haystack import Document
from haystack_integrations.document_stores.alloydb import AlloyDBDocumentStore

document_store = AlloyDBDocumentStore(
    db="my-database",
    embedding_dimension=768,
    vector_function="cosine_similarity",
    recreate_table=True,
)
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 docs를 참고하세요.

Documents의 임베딩을 계산하려면 SentenceTransformersDocumentEmbedder 같은 Document Embedder를 사용할 수 있어요.

Search Strategy

AlloyDBDocumentStore는 임베딩 검색을 위한 두 가지 검색 전략을 지원합니다:

"exact_nearest_neighbor"(기본값): 완벽한 재현율(recall)을 제공하지만 문서 수가 많으면 느릴 수 있어요.
"hnsw": 일부 정확도를 속도와 맞바꾸는 근사 최근접 이웃 검색 전략. 문서 수가 많을 때 권장됩니다.

"hnsw"를 쓸 때는 선택한 vector_function을 바탕으로 인덱스가 만들어져요. 그래서 이후 쿼리도 인덱스를 활용하려면 계속 같은 벡터 유사도 함수를 사용해야 합니다. 인덱스 생성은 hnsw_index_creation_kwargs로 조정할 수 있어요(pgvector 문서 참고).

Metadata Filtering

AlloyDBDocumentStore는 비교 연산자(==, !=, >, >=, <, <=, in, not in, like, not like)와 논리 연산자 AND, OR를 완전히 지원해요. like와 not like 연산자는 표준 Haystack 필터 문법에 대한 PostgreSQL 특유의 확장으로, SQL LIKE / NOT LIKE 패턴 매칭 연산자에 매핑됩니다.

NOT 논리 연산자는 지원되지 않아요. 모든 비교 연산자에 이미 부정 대응(==/!=, in/not in, like/not like)이 있으므로, 단일 조건 주변의 NOT으로 표현할 수 있는 어떤 필터든 비교 연산자를 반전시켜 다시 쓸 수 있죠. 중첩된 AND/OR 그룹을 부정하려면 드모르간 법칙을 적용하세요 — 예를 들어 NOT (A AND B)는 (NOT A) OR (NOT B)가 되고, 각 NOT A/NOT B는 반전된 비교로 표현됩니다.

필터 문법에 대한 자세한 내용은 Metadata Filtering을 참고하세요.

Supported Retrievers

AlloyDBEmbeddingRetriever: 쿼리 임베딩을 바탕으로 Document Store에서 Documents를 가져오는 임베딩 기반 Retriever
AlloyDBKeywordRetriever: PostgreSQL 전문(full-text) 검색으로 쿼리와 일치하는 Documents를 가져오는 키워드 기반 Retriever

AlloyDBDocumentStore