VespaDocumentStore

Vespa 문서 저장소(document store)예요. Vespa는 구조화 검색·텍스트 검색·벡터 검색을 대규모로 지원하는 오픈소스 빅데이터 서빙 엔진이에요.

API 레퍼런스: Vespa GitHub 링크: https://github.com/deepset-ai/haystack-core-integrations/tree/main/integrations/vespa

출처: 문서

본문

Vespa는 구조화, 텍스트, 벡터 검색을 대규모로 지원하는 오픈소스 빅데이터 서빙 엔진이에요. VespaDocumentStore는 pyvespa를 통해 Haystack을 기존 Vespa 애플리케이션에 연결해 줘요. 어휘 검색(lexical)과 밀집 벡터 검색(dense vector retrieval), 그리고 메타데이터 필터링을 모두 지원해요.

대부분의 다른 Haystack Document Store와 달리, VespaDocumentStore는 Vespa 애플리케이션이나 스키마를 자동으로 만들거나 배포하지 않아요. 필요한 필드와 rank 프로필을 스스로 구성해 배포(셀프호스팅 또는 Vespa Cloud)한 뒤, Document Store가 실행 중인 엔드포인트를 가리키게 하면 돼요.

설치 (Installation)

vespa-haystack 통합을 설치해요:

pip install vespa-haystack

Vespa를 로컬로 실행하려면 Vespa quick start를 참고하세요. 관리형 Vespa 애플리케이션을 배포하려면 Vespa Cloud를 참고하세요.

사용법 (Usage)

사전 준비: Vespa 스키마 (Prerequisites: Vespa Schema)

VespaDocumentStore를 쓰려면 먼저 Document Store에 구성한 필드와 호환되는 스키마를 가진 배포된 Vespa 애플리케이션이 필요해요. 기본적으로 통합은 다음을 기대해요:

Document 본문용 텍스트 필드 content
(임베딩 검색을 쓸 때) 밀집 벡터용 텐서 필드 embedding
어휘 검색용 rank 프로필 bm25 (VespaKeywordRetriever가 사용)
closeness(field, embedding)으로 랭킹하는 rank 프로필 semantic (VespaEmbeddingRetriever가 사용)

필드와 rank 프로필 이름은 Document Store와 Retriever 생성자에서 커스터마이즈할 수 있어요. 스키마와 rank 프로필 작성에 대한 자세한 내용은 Vespa 문서를 참고하세요.

인증 (Authentication)

VespaDocumentStore는 pyvespa가 제공하는 인증 방식을 지원해요:

인증 없음: 보안이 없는 Vespa 엔드포인트에 대한 로컬 개발용. mTLS: 데이터 플레인 인증서와 키 사용 (Secret으로 cert와 key 파라미터에 전달). Bearer 토큰: Vespa Cloud 토큰 엔드포인트용 (vespa_cloud_secret_token 또는 VESPA_CLOUD_SECRET_TOKEN 환경 변수).

Vespa 엔드포인트 URL은 url 파라미터나 VESPA_URL 환경 변수로 전달할 수 있어요:

export VESPA_URL="http://localhost"

Vespa Cloud 토큰 인증의 경우:

export VESPA_URL="https://my-app.my-tenant.aws-us-east-1c.z.vespa-app.cloud"
export VESPA_CLOUD_SECRET_TOKEN="my-secret-token"

초기화 (Initialization)

VespaDocumentStore가 배포된 Vespa 애플리케이션을 가리키고 Document를 쓰게 해요. HTTP 클라이언트는 처음 사용할 때(lazily) 만들어져요:

from haystack import Document
from haystack_integrations.document_stores.vespa import VespaDocumentStore

document_store = VespaDocumentStore(
    url="http://localhost",
    schema="doc",
    namespace="doc",
    content_field="content",
    embedding_field="embedding",
    metadata_fields=["category"],
)

document_store.write_documents(
    [
        Document(
            content="Haystack integrates with Vespa for search.",
            meta={"category": "docs"},
        ),
        Document(
            content="Vespa supports lexical and vector retrieval.",
            meta={"category": "docs"},
        ),
    ],
)
print(document_store.count_documents())

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

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

메타데이터 필드 (Metadata Fields)

Vespa는 스키마에 엄격하게 묶여 있어요. Vespa에 넣거나 읽어올 모든 메타데이터 필드는 배포된 스키마에 필드로 존재해야 해요. metadata_fields 파라미터로 쓰기 때 Vespa에 보내고 읽기 때 다시 요청할 메타데이터 키의 허용 목록(allowlist)을 선언해요. 이 허용 목록에 없는 메타데이터 키는 메모리의 Document에는 유지되지만 Vespa에는 저장되지 않아요.

메타데이터 필터링 (Metadata Filtering)

VespaDocumentStore는 비교 연산자(==, !=, >, >=, <, <=, in, not in)와 논리 연산자 AND, OR, NOT을 지원해요. 필터는 가능하면 Vespa의 YQL where 절로 번역돼요.

날짜 타입 값에 대한 필터는 YQL이 비교를 직접 표현할 수 없을 때 Python에서 클라이언트 쪽으로 평가돼요. 필터 문법에 대한 자세한 내용은 Metadata Filtering을 참고하세요.

지원되는 Retriever (Supported Retrievers)

VespaEmbeddingRetriever: nearest-neighbor 검색과 설정 가능한 rank 프로필로 Vespa에서 Document를 가져오는 밀집 임베딩 기반 Retriever. VespaKeywordRetriever: 설정 가능한 rank 프로필(기본 BM25)로 Vespa에서 Document를 가져오는 어휘 기반 Retriever.

VespaDocumentStore