Couchbase 벡터 스토어

그만큼CouchbaseVector클래스는 다음을 사용하여 벡터 검색을 제공합니다.Couchbase 벡터 검색. Couchbase 컬렉션 내에서 효율적인 유사성 검색 및 메타데이터 필터링이 가능합니다.

요구사항

• 카우치베이스 서버 7.6.4+또는 호환되는 Capella 클러스터
• 검색 서비스 활성화됨Couchbase 배포에서

설치

npm

npm install @mastra/couchbase@latest

pnpm

pnpm add @mastra/couchbase@latest

Yarn

yarn add @mastra/couchbase@latest

Bun

bun add @mastra/couchbase@latest

사용예

import { CouchbaseVector } from '@mastra/couchbase'

const store = new CouchbaseVector({
  id: 'couchbase-vector',
  connectionString: process.env.COUCHBASE_CONNECTION_STRING,
  username: process.env.COUCHBASE_USERNAME,
  password: process.env.COUCHBASE_PASSWORD,
  bucketName: process.env.COUCHBASE_BUCKET,
  scopeName: process.env.COUCHBASE_SCOPE,
  collectionName: process.env.COUCHBASE_COLLECTION,
})

생성자 옵션

id:

string

이 벡터 저장소 인스턴스의 고유 식별자

connectionString:

string

Couchbase 연결 문자열

username:

string

Couchbase 사용자 이름

password:

string

Couchbase 비밀번호

bucketName:

string

사용할 Couchbase 버킷의 이름

scopeName:

string

사용할 Couchbase 범위의 이름

collectionName:

string

사용할 Couchbase 컬렉션의 이름

options?:

CouchbaseClientOptions

선택적 Couchbase 클라이언트 옵션

행동 양식

createIndex()

Couchbase에서 새로운 벡터 인덱스를 생성합니다.

노트

인덱스 생성은 비동기 방식입니다. createIndex를 호출한 후 쿼리하기 전에 시간을 두세요(일반적으로 소규모 데이터 세트는 1~5초, 대규모 데이터 세트는 더 오래 걸림). 프로덕션 환경에서는 고정 지연 시간을 사용하는 대신 폴링을 구현하여 인덱스 상태를 확인하세요.

indexName:

string

생성할 인덱스의 이름

dimension:

number

벡터 차원(임베딩 Model과 일치해야 함)

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

유사도 검색에 사용할 거리 측정 방식

upsert()

컬렉션에 벡터와 해당 메타데이터를 추가하거나 업데이트합니다.

노트

인덱스를 생성하기 전이나 후에 데이터를 업서트할 수 있습니다. upsert 메서드는 인덱스가 없어도 사용할 수 있습니다. Couchbase에서는 동일한 컬렉션에 여러 Search 인덱스를 만들 수 있습니다.

indexName:

string

데이터를 삽입할 인덱스의 이름

vectors:

number[][]

임베딩 벡터 배열

metadata?:

Record<string, any>[]

각 벡터의 메타데이터

ids?:

string[]

선택적 벡터 ID(제공하지 않으면 자동 생성)

query()

유사한 벡터를 검색합니다.

경고

현재 filter 및 includeVector 매개변수는 지원되지 않습니다. 결과를 가져온 후 클라이언트 측에서 필터링하거나 Couchbase SDK의 Search 기능을 직접 사용해야 합니다. 벡터 임베딩을 가져오려면 Couchbase SDK를 사용하여 ID로 전체 문서를 가져오세요.

indexName:

string

검색할 인덱스의 이름

queryVector:

number[]

유사한 벡터를 찾는 데 사용할 쿼리 벡터

topK?:

number

= 10

반환할 결과 수

filter?:

Record<string, any>

메타데이터 필터

includeVector?:

boolean

= false

결과에 벡터 데이터를 포함할지 여부

minScore?:

number

= 0

최소 유사도 점수 임계값

describeIndex()

인덱스에 대한 정보를 반환합니다.

indexName:

string

설명할 인덱스의 이름

보고:

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
}

deleteIndex()

인덱스와 해당 데이터를 모두 삭제합니다.

indexName:

string

삭제할 인덱스의 이름

listIndexes()

Couchbase 버킷의 모든 벡터 인덱스를 나열합니다.

보고:Promise<string[]>

updateVector()

새로운 벡터 데이터 및/또는 메타데이터를 사용하여 ID별로 특정 벡터 항목을 업데이트합니다. Couchbase에는 필터 기반 업데이트가 아직 구현되지 않았습니다.

indexName:

string

벡터가 포함된 인덱스의 이름

id:

string

업데이트할 벡터 항목의 ID

update:

{ vector?: number[]; metadata?: Record<string, any>; }

업데이트할 벡터 및/또는 메타데이터가 포함된 객체

deleteVector()

인덱스에서 ID로 단일 벡터를 삭제합니다.

indexName:

string

벡터가 포함된 인덱스의 이름

id:

string

삭제할 벡터의 ID

deleteVectors()

ID별로 여러 벡터를 삭제합니다. Couchbase에는 필터 기반 삭제가 아직 구현되지 않았습니다.

indexName:

string

삭제할 벡터가 포함된 인덱스의 이름

ids:

string[]

삭제할 벡터 ID 배열

disconnect()

Couchbase 클라이언트 연결을 닫습니다. 매장 이용이 끝나면 전화해야 합니다.

응답 유형

쿼리 결과는 다음 형식으로 반환됩니다.

interface QueryResult {
  id: string
  score: number
  metadata: Record<string, any>
  vector?: number[] // Only included if includeVector is true
}

오류 처리

상점에서는 포착할 수 있는 입력된 오류를 발생시킵니다.

try {
  await store.query({
    indexName: 'my_index',
    queryVector: queryVector,
  })
} catch (error) {
  // Handle specific error cases
  if (error.message.includes('Invalid index name')) {
    console.error(
      'Index name must start with a letter or underscore and contain only valid characters.',
    )
  } else if (error.message.includes('Index not found')) {
    console.error('The specified index does not exist')
  } else {
    console.error('Vector store error:', error.message)
  }
}

메모

• 인덱스 삭제 시 주의 사항:검색 인덱스를 삭제해도 연결된 Couchbase 컬렉션의 벡터/문서는 삭제되지 않습니다. 명시적으로 제거하지 않는 한 데이터는 그대로 유지됩니다.
• 필수 권한:Couchbase 사용자는 대상 컬렉션에 문서를 읽고 쓸 수 있어야 하며(kv role), Search 인덱스를 관리할 수 있어야 합니다(관련 버킷/범위의 search_admin role).
• 인덱스 정의 세부 정보 및 문서 구조:그 createIndex 메서드는 지정된 scopeName.collectionName 내의 문서를 대상으로 embedding 필드(vector 유형)와 content 필드(text 유형)를 인덱싱하는 Search 인덱스 정의를 생성합니다. 각 문서는 벡터를 embedding 필드에, 메타데이터를 metadata 필드에 저장합니다. metadata에 text 속성이 있으면 해당 값도 최상위 content 필드에 복사되며, 이 필드는 텍스트 검색용으로 인덱싱됩니다.
• 복제 및 내구성:데이터 내구성을 확보하려면 Couchbase에 내장된 복제 및 지속성 기능을 사용하세요. 효율적인 검색을 위해 인덱스 통계를 정기적으로 모니터링하세요.

제한사항

• 인덱스 생성 지연은 생성 후 즉각적인 쿼리에 영향을 미칠 수 있습니다.
• 수집 시 벡터 차원을 강제로 적용하지 않습니다(차원 불일치로 인해 쿼리 시 오류가 발생함).
• 벡터 삽입과 인덱스 업데이트는 최종적으로 일관됩니다. 쓰기 직후에는 강력한 일관성이 보장되지 않습니다.

관련된

• 메타데이터 필터