SupabaseDocumentStore

SupabaseDocumentStore

SupabaseDocumentStore 는 Supabase(PostgreSQL 기반 오픈소스 백엔드 플랫폼)에 문서를 저장하고 검색하는 Document Store예요. Haystack용 Supabase 통합은 두 가지 Document Store를 제공해요 — 벡터 검색용 pgvector 스토어와 다국어 전문 검색용 PGroonga 스토어죠.

출처: 문서

본문

Supabase는 PostgreSQL 위에 구축된 오픈소스 백엔드 플랫폼이에요. Haystack용 Supabase 통합은 두 가지 Document Store를 제공해요:

  • SupabasePgvectorDocumentStore — pgvector PostgreSQL 확장(이 문맥에서는 Supabase에 사전 설치돼 있음)을 사용한 벡터 유사도 검색
  • SupabaseGroongaDocumentStore — PGroonga PostgreSQL 확장을 사용한 다국어 전문(full-text) 검색. 임베딩이 필요 없어요.

설치 (Installation)

pip install supabase-haystack

이 페이지의 예시는 sentence-transformers-haystack 패키지로 이동한 Sentence Transformers 임베더를 사용해요. 예시를 실행하려면 이 패키지도 설치하세요:

pip install sentence-transformers-haystack

SupabasePgvectorDocumentStore

SupabasePgvectorDocumentStore 는 PgvectorDocumentStore 를 Supabase 특화 기본값으로 감싼 얇은 래퍼예요:

  • 연결 문자열을 SUPABASE_DB_URL 환경 변수에서 읽어요.
  • pgvector가 Supabase에 사전 설치되어 있어 create_extension 의 기본값을 False 로 해요.

연결 (Connection)

Supabase 데이터베이스 연결 문자열로 SUPABASE_DB_URL 환경 변수를 설정하세요. **세션 모드(포트 5432)**를 사용하세요:

Supabase는 두 개의 풀러 포트를 제공해요: 트랜잭션 모드(포트 6543)와 세션 모드(포트 5432). pgvector 연산과의 호환성을 위해 세션 모드나 직접 연결을 사용하는 게 좋아요.

export SUPABASE_DB_URL="postgresql://postgres.[project-ref]:***@aws-0-[region].pooler.supabase.com:5432/postgres"

초기화 (Initialization)

from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore

document_store = SupabasePgvectorDocumentStore(
    embedding_dimension=768,
    vector_function="cosine_similarity",
    recreate_table=True,
)

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

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

예시: RAG 파이프라인

from haystack import Document, Pipeline
from haystack.document_stores.types.policy import DuplicatePolicy
from haystack_integrations.components.embedders.sentence_transformers import (
    SentenceTransformersTextEmbedder,
    SentenceTransformersDocumentEmbedder,
)
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage
from haystack.utils import Secret
from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
from haystack_integrations.components.retrievers.supabase import (
    SupabasePgvectorEmbeddingRetriever,
)

document_store = SupabasePgvectorDocumentStore(
    embedding_dimension=768,
    vector_function="cosine_similarity",
    recreate_table=True,
)

# Index documents
documents = [
    Document(content="There are over 7,000 languages spoken around the world today."),
    Document(
        content="Elephants have been observed to behave in a way that indicates a high level of self-awareness.",
    ),
    Document(
        content="In certain places, you can witness the phenomenon of bioluminescent waves.",
    ),
]
embedder = SentenceTransformersDocumentEmbedder()
documents_with_embeddings = embedder.run(documents)
document_store.write_documents(
    documents_with_embeddings["documents"],
    policy=DuplicatePolicy.OVERWRITE,
)

# Query pipeline
prompt_template = [
    ChatMessage.from_system("Answer the question based on the provided context."),
    ChatMessage.from_user(
        "Query: {{query}}\nDocuments:\n{% for doc in documents %}{{ doc.content }}\n{% endfor %}\nAnswer:"
    ),
]
query_pipeline = Pipeline()
query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
query_pipeline.add_component(
    "retriever",
    SupabasePgvectorEmbeddingRetriever(document_store=document_store),
)
query_pipeline.add_component(
    "prompt_builder",
    ChatPromptBuilder(
        template=prompt_template,
        required_variables=["query", "documents"],
    ),
)
query_pipeline.add_component("generator", OpenAIChatGenerator(model="gpt-4o"))
query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
query_pipeline.connect("retriever.documents", "prompt_builder.documents")
query_pipeline.connect("prompt_builder.prompt", "generator.messages")
result = query_pipeline.run(
    {
        "text_embedder": {"text": "How many languages are there?"},
        "prompt_builder": {"query": "How many languages are there?"},
    },
)

SupabaseGroongaDocumentStore

SupabaseGroongaDocumentStore 는 빠른 다국어 전문 검색을 위한 PostgreSQL 확장인 PGroonga를 사용해요. pgvector 스토어와 달리 일반 텍스트 쿼리로 동작하고 임베딩이 필요 없어요.

사전 조건 (Prerequisites)

Supabase 프로젝트에서 PGroonga를 활성화해야 해요. Supabase SQL 편집기에서 다음 SQL을 실행하세요:

CREATE EXTENSION IF NOT EXISTS pgroonga;

또한 PGroonga가 검색에 쓰는 SQL 함수를 만들어야 해요. 필요한 함수 정의는 통합 README에서 확인할 수 있어요.

초기화 (Initialization)

from haystack_integrations.document_stores.supabase import SupabaseGroongaDocumentStore
from haystack.utils import Secret

document_store = SupabaseGroongaDocumentStore(
    supabase_url="https://.supabase.co",
    supabase_key=Secret.from_env_var("SUPABASE_SERVICE_KEY"),
    table_name="haystack_groonga_documents",
)
document_store.warm_up()

참고: 스토어를 쓰기 전에 반드시 warm_up() 을 호출해야 해요. Supabase 클라이언트를 초기화하고, 테이블과 PGroonga 인덱스가 없으면 만들어요.

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

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

  • SupabaseGroongaBM25Retriever: PGroonga 전문 검색으로 문서를 검색해요. 임베딩 없이 동작하며, 하이브리드 검색 파이프라인을 위해 SupabasePgvectorEmbeddingRetriever 와 결합할 수 있어요.

더 알아보기 (Learn more)