Couchbase 벡터 스토어

Couchbase 벡터 스토어 (Couchbase)

이 섹션에서는 CouchbaseSearchVectorStore를 설정해서 Couchbase를 사용해 문서 임베딩을 저장하고 유사도 검색을 수행하는 방법을 안내해요. Couchbase는 관계형 DBMS가 가진 모든 원하는 기능을 갖춘 분산 JSON 문서 데이터베이스로, 벡터 기반 저장·검색으로 정보를 질의할 수 있게 해 줘요.

출처: 문서

본문

Couchbase

이 섹션은 CouchbaseSearchVectorStore를 설정해 Couchbase를 사용해 문서 임베딩을 저장하고 유사도 검색을 수행하는 방법을 안내해요.

Couchbase는 관계형 DBMS가 가진 모든 원하는 기능을 갖춘 분산 JSON 문서 데이터베이스예요. 다른 기능들 중에서도 벡터 기반 저장·검색으로 정보를 질의할 수 있게 해 줘요.

사전 준비 (Prerequisites)

실행 중인 Couchbase 인스턴스. 다음 옵션이 가능해요:

Couchbase

자동 설정 (Auto-configuration)

참고: Spring AI auto-configuration과 starter 모듈의 아티팩트 이름에 큰 변화가 있었어요. 자세한 내용은 upgrade notes를 참고해 주세요.

Spring AI는 Couchbase Vector Store에 대한 Spring Boot 자동 설정을 제공해요. 활성화하려면 프로젝트의 Maven pom.xml 파일에 다음 의존성을 추가하세요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-vector-store-couchbase</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에:

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-vector-store-couchbase'
}

참고: Couchbase 벡터 검색에는 Couchbase Server 7.6 이상과 Java SDK 3.6.0 이상이 필요해요.

참고: 빌드 파일에 Spring AI BOM을 추가하려면 Dependency Management 섹션을 참고해 주세요.

참고: 빌드 파일에 Milestone 및/또는 Snapshot 저장소를 추가하려면 Artifact Repositories 섹션을 참고해 주세요.

벡터 스토어 구현은 구성된 bucket, scope, collection, 검색 인덱스를 기본 옵션으로 초기화할 수 있지만, 적절한 생성자에서 initializeSchema boolean을 지정해 선택해야 해요.

참고: 이것은 호환성을 깨는 변경이에요! 이전 버전의 Spring AI에서는 이 스키마 초기화가 기본으로 일어났어요.

기본값과 구성 옵션을 알려면 벡터 스토어의 구성 파라미터 목록을 살펴보세요. 추가로 구성된 EmbeddingModel 빈이 필요해요. 자세한 내용은 EmbeddingModel 섹션을 참고하세요.

이제 애플리케이션에서 CouchbaseSearchVectorStore를 벡터 스토어로 오토와이어할 수 있어요.

@Autowired VectorStore vectorStore;

// ...

List <Document> documents = List.of(
    new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("meta1", "meta1")),
    new Document("The World is Big and Salvation Lurks Around the Corner"),
    new Document("You walk forward facing the past and you turn back toward the future.", Map.of("meta2", "meta2")));

// Add the documents to Couchbase
vectorStore.add(documents);

// Retrieve documents similar to a query
List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());

구성 프로퍼티 (Configuration Properties)

Couchbase에 연결하고 CouchbaseSearchVectorStore를 사용하려면 인스턴스의 접근 세부 정보를 제공해야 해요. 구성은 Spring Boot의 application.properties로 제공할 수 있어요:

spring.ai.openai.api-key=<key>
spring.couchbase.connection-string=<conn_string>
spring.couchbase.username=<username>
spring.couchbase.password=<password>

비밀번호나 API 키 같은 민감한 정보에 환경 변수를 사용하는 것을 선호한다면 여러 옵션이 있어요:

옵션 1: Spring Expression Language (SpEL) 사용

커스텀 환경 변수 이름을 사용하고 SpEL로 애플리케이션 구성에서 참조할 수 있어요:

# In application.yml
spring:
  ai:
    openai:
      api-key: ***
  couchbase:
    connection-string: ${COUCHBASE_CONN_STRING}
    username: ${COUCHBASE_USER}
    password: ${COUCHBASE_PASSWORD}

# In your environment or .env file
export OPENAI_API_KEY=<api-key>
export COUCHBASE_CONN_STRING=<couchbase connection string like couchbase://localhost>
export COUCHBASE_USER=<couchbase username>
export COUCHBASE_PASSWORD=<couchbase password>

옵션 2: 환경 변수에 프로그래밍 방식으로 접근

또는 Java 코드에서 환경 변수에 접근할 수 있어요:

String apiKey = System.getenv("OPENAI_API_KEY");

이 방식은 환경 변수 이름을 유연하게 정하면서 민감한 정보를 애플리케이션 구성 파일 밖에 유지할 수 있게 해 줘요.

참고: 향후 작업을 위해 셸 스크립트를 만들기로 했다면 애플리케이션을 시작하기 전에 파일을 "소싱"해서 실행해야 해요, 즉 source <your_script_name>.sh.

Couchbase Cluster에 대한 Spring Boot의 자동 설정 기능은 CouchbaseSearchVectorStore가 사용할 빈 인스턴스를 만들어요. spring.couchbase.*로 시작하는 Spring Boot 프로퍼티는 Couchbase 클러스터 인스턴스를 구성하는 데 사용돼요:

Property	Description	Default Value
`spring.couchbase.connection-string`	Couchbase 연결 문자열	`couchbase://localhost`
`spring.couchbase.password`	Couchbase 인증용 비밀번호	-
`spring.couchbase.username`	Couchbase 인증용 사용자 이름	-
`spring.couchbase.env.io.minEndpoints`	노드당 최소 소켓 수	1
`spring.couchbase.env.io.maxEndpoints`	노드당 최대 소켓 수	12
`spring.couchbase.env.io.idleHttpConnectionTimeout`	HTTP 연결이 닫히고 풀에서 제거되기 전에 유휴 상태로 남을 수 있는 시간	1s
`spring.couchbase.env.ssl.enabled`	SSL 지원 활성화 여부. 달리 지정하지 않으면 "bundle"이 제공될 때 자동 활성화	-
`spring.couchbase.env.ssl.bundle`	SSL bundle 이름	-
`spring.couchbase.env.timeouts.connect`	Bucket 연결 타임아웃	10s
`spring.couchbase.env.timeouts.disconnect`	Bucket 연결 해제 타임아웃	10s
`spring.couchbase.env.timeouts.key-value`	특정 key-value 작업의 타임아웃	2500ms
`spring.couchbase.env.timeouts.key-value`	내구성 레벨을 가진 특정 key-value 작업의 타임아웃	10s
`spring.couchbase.env.timeouts.key-value-durable`	내구성 레벨을 가진 특정 key-value 작업의 타임아웃	10s
`spring.couchbase.env.timeouts.query`	SQL++ 쿼리 작업 타임아웃	75s
`spring.couchbase.env.timeouts.view`	일반·지리공간 뷰 작업 타임아웃	75s
`spring.couchbase.env.timeouts.search`	검색 서비스 타임아웃	75s
`spring.couchbase.env.timeouts.analytics`	분석 서비스 타임아웃	75s
`spring.couchbase.env.timeouts.management`	관리 작업 타임아웃	75s

spring.ai.vectorstore.couchbase.* 프리픽스로 시작하는 프로퍼티는 CouchbaseSearchVectorStore를 구성하는 데 사용돼요.

Property	Description	Default Value
`spring.ai.vectorstore.couchbase.index-name`	벡터를 저장할 인덱스의 이름.	spring-ai-document-index
`spring.ai.vectorstore.couchbase.bucket-name`	scope의 부모인 Couchbase Bucket의 이름.	default
`spring.ai.vectorstore.couchbase.scope-name`	collection의 부모인 Couchbase scope의 이름. 검색 쿼리는 scope 컨텍스트에서 실행돼요.	default
`spring.ai.vectorstore.couchbase.collection-name`	문서를 저장할 Couchbase collection의 이름.	default
`spring.ai.vectorstore.couchbase.dimensions`	벡터의 차원 수.	1536
`spring.ai.vectorstore.couchbase.similarity`	사용할 유사도 함수.	`dot_product`
`spring.ai.vectorstore.couchbase.optimization`	사용할 유사도 함수.	`recall`
`spring.ai.vectorstore.couchbase.initialize-schema`	필요한 스키마를 초기화할지 여부	`false`

다음 유사도 함수를 사용할 수 있어요:

l2_norm
dot_product

다음 인덱스 최적화를 사용할 수 있어요:

recall
latency

각각에 대한 자세한 내용은 벡터 검색에 대한 Couchbase Documentation을 참고하세요.

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

Couchbase 스토어에서도 일반적이고 휴대 가능한 메타데이터 필터를 활용할 수 있어요.

예를 들어 텍스트 표현 언어를 사용할 수 있어요:

vectorStore.similaritySearch(
    SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'")
    .build());

또는 Filter.Expression DSL로 프로그래밍 방식으로:

FilterExpressionBuilder b = new FilterExpressionBuilder();

vectorStore.similaritySearch(SearchRequest.builder()
    .query("The World")
    .topK(TOP_K)
    .filterExpression(b.and(
        b.in("author","john", "jill"),
        b.eq("article_type", "blog")).build())
    .build());

참고: 이 필터 표현식은 동일한 Couchbase SQL++ 필터로 변환돼요.

수동 구성 (Manual Configuration)

Spring Boot 자동 설정 대신 Couchbase 벡터 스토어를 수동 구성할 수 있어요. 이를 위해 프로젝트에 spring-ai-couchbase-store를 추가해야 해요:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-couchbase-store</artifactId>
</dependency>

또는 Gradle build.gradle 빌드 파일에:

dependencies {
    implementation 'org.springframework.ai:spring-ai-couchbase-store'
}

Couchbase Cluster 빈을 만드세요. 커스텀 Cluster 인스턴스 구성에 대한 더 깊이 있는 정보는 Couchbase Documentation을 읽어보세요.

@Bean
public Cluster cluster() {
    return Cluster.connect("couchbase://localhost", "username", "password");
}

그런 다음 빌더 패턴으로 CouchbaseSearchVectorStore 빈을 만드세요:

@Bean
public VectorStore couchbaseSearchVectorStore(Cluster cluster,
                                              EmbeddingModel embeddingModel,
                                              Boolean initializeSchema) {
    return CouchbaseSearchVectorStore
            .builder(cluster, embeddingModel)
            .bucketName("test")
            .scopeName("test")
            .collectionName("test")
            .initializeSchema(initializeSchema)
            .build();
}

// This can be any EmbeddingModel implementation.
@Bean
public EmbeddingModel embeddingModel() {
    return OpenAiEmbeddingModel.builder()
            .options(OpenAiEmbeddingOptions.builder().apiKey(this.openaiKey).build())
            .build();
}

제한 사항 (Limitations)

참고: 다음 Couchbase 서비스가 활성화되어 있어야 해요: Data, Query, Index, Search. Data와 Search만으로 충분할 수 있지만, 완전한 메타데이터 필터링 메커니즘을 지원하려면 Query와 Index가 필요해요.

Couchbase 벡터 스토어