본문으로 건너뛰기

볼록 벡터 저장소

그만큼ConvexVector클래스는 다음을 사용하여 벡터 저장 및 유사성 검색을 제공합니다.볼록한. Convex 내부에 임베딩을 저장하고 Mastra 어댑터에서 코사인 유사성 검색을 수행합니다.

:::warning[개발 규모 검색]

ConvexVectorMastra 스토리지 핸들러를 통해 일치하는 벡터를 읽고, JavaScript로 필터링하고, 코사인 유사성을 계산하고, 결과를 정렬하고, 가장 일치하는 항목을 반환합니다. 로컬 개발, 테스트 및 소규모 데이터 세트에 사용하세요.

Convex에서 프로덕션 벡터를 검색하려면 ConvexNativeVector를 사용하세요. 배포된 Convex 벡터 인덱스와 Convex action이 필요한 Convex 네이티브 vectorSearch API를 사용합니다. :::

설치
설치에 대한 직접 링크

npm install @mastra/convex@latest

볼록한 설정
볼록한 설정에 대한 직접 링크

ConvexVector를 사용하기 전에 Convex 스키마와 저장소 핸들러를 설정해야 합니다. 설정 방법은 Convex 저장소 설정을 참조하세요.

생성자 옵션
생성자 옵션에 대한 직접 링크

deploymentUrl:

string
Convex 배포 URL입니다(예: https://your-project.convex.cloud).

adminAuthToken:

string
Convex 관리자 인증 토큰입니다.

storageFunction?:

string
= mastra/storage:handle
저장소 mutation 함수의 경로입니다.

생성자 예
생성자 예에 대한 직접 링크

기본 구성
기본 구성에 대한 직접 링크

import { ConvexVector } from '@mastra/convex'

const vectorStore = new ConvexVector({
  id: 'convex-vectors',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
})

프로덕션 벡터 워크로드에는 ConvexNativeVector를 사용하세요. 전용 Convex 테이블에 벡터를 저장하고 스키마에 정의된 Convex 벡터 인덱스를 쿼리합니다. ~ convex/schema.ts에서 각 Mastra 벡터 인덱스에 사용할 전용 테이블을 정의하세요.

convex/schema.ts
import { defineSchema } from 'convex/server'
import { defineMastraNativeVectorTable } from '@mastra/convex/schema'

export default defineSchema({
  docs_vectors: defineMastraNativeVectorTable({
    dimensions: 1536,
  }),
})

~ convex/mastra/nativeVector.ts에서 네이티브 벡터 핸들러를 내보내세요.

convex/mastra/nativeVector.ts
import {
  mastraNativeVectorAction,
  mastraNativeVectorMutation,
  mastraNativeVectorQuery,
} from '@mastra/convex/server'

export const query = mastraNativeVectorAction
export const read = mastraNativeVectorQuery
export const write = mastraNativeVectorMutation

Mastra 앱에서 배포된 테이블 및 벡터 인덱스로 ConvexNativeVector를 구성하세요.

src/mastra/index.ts
import { ConvexNativeVector } from '@mastra/convex'

const vectorStore = new ConvexNativeVector({
  id: 'convex-native-vectors',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
  indexes: {
    docs: {
      tableName: 'docs_vectors',
      vectorIndexName: 'by_embedding',
      dimension: 1536,
    },
  },
})

const results = await vectorStore.query({
  indexName: 'docs',
  queryVector: embedding,
  topK: 10,
})

기본 필터 지원을 위해 Convex 스키마에서 필터 필드를 선언하세요. 기본 벡터 핸들러는 벡터가 작성될 때 일치하는 메타데이터 필드를 최상위 문서 필드에 복사합니다.

convex/schema.ts
import { defineSchema, defineTable } from 'convex/server'
import { v } from 'convex/values'

export default defineSchema({
  docs_vectors: defineTable({
    id: v.string(),
    embedding: v.array(v.float64()),
    metadata: v.optional(v.any()),
    tenantId: v.string(),
  })
    .index('by_record_id', ['id'])
    .vectorIndex('by_embedding', {
      vectorField: 'embedding',
      dimensions: 1536,
      filterFields: ['tenantId'],
    }),
})
src/mastra/index.ts
const vectorStore = new ConvexNativeVector({
  id: 'convex-native-vectors',
  deploymentUrl: process.env.CONVEX_URL!,
  adminAuthToken: process.env.CONVEX_ADMIN_KEY!,
  indexes: {
    docs: {
      tableName: 'docs_vectors',
      dimension: 1536,
      filterFields: ['tenantId'],
    },
  },
})

await vectorStore.upsert({
  indexName: 'docs',
  ids: ['chunk-1'],
  vectors: [embedding],
  metadata: [{ tenantId: 'acme', text: 'Account setup guide' }],
})

const results = await vectorStore.query({
  indexName: 'docs',
  queryVector: embedding,
  filter: { tenantId: 'acme' },
})

ConvexNativeVector는 Convex 네이티브 벡터 필터 형태, 즉 하나의 동등성 필드 또는 동등성 필드의 $or를 지원합니다. 메타데이터 전용 쿼리, 필터 기반 업데이트 또는 필터 기반 삭제는 지원하지 않습니다. 업데이트 및 삭제에는 벡터 ID를 사용하세요.

맞춤형 저장 기능
맞춤형 저장 기능에 대한 직접 링크

const vectorStore = new ConvexVector({
  id: 'convex-vectors',
  deploymentUrl: 'https://your-project.convex.cloud',
  adminAuthToken: 'your-admin-token',
  storageFunction: 'custom/path:handler',
})

행동 양식
행동 양식에 대한 직접 링크

createIndex()
createindex에 대한 직접 링크

indexName:

string
생성할 인덱스의 이름

dimension:

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

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
유사도 검색에 사용할 거리 측정 방식(현재는 cosine만 지원)
await vectorStore.createIndex({
  indexName: 'my_vectors',
  dimension: 1536,
})

upsert()
upsert에 대한 직접 링크

indexName:

string
벡터를 업서트할 인덱스의 이름

vectors:

number[][]
임베딩 벡터 배열

metadata?:

Record<string, any>[]
각 벡터의 메타데이터

ids?:

string[]
선택적 벡터 ID(제공하지 않으면 자동 생성)
await vectorStore.upsert({
  indexName: "my_vectors",
  vectors: [[0.1, 0.2, 0.3, ...]],
  metadata: [{ label: "example" }],
  ids: ["vec-1"],
});

query()
query에 대한 직접 링크

indexName:

string
쿼리할 인덱스의 이름

queryVector:

number[]
쿼리 벡터

topK?:

number
= 10
반환할 결과 수

filter?:

Record<string, any>
메타데이터 필터

includeVector?:

boolean
= false
결과에 벡터를 포함할지 여부
const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: [0.1, 0.2, 0.3, ...],
  topK: 5,
  filter: { category: "documents" },
});

listIndexes()
listindexes에 대한 직접 링크

인덱스 이름의 배열을 문자열로 반환합니다.

const indexes = await vectorStore.listIndexes()
// ["my_vectors", "embeddings", ...]

describeIndex()
describeindex에 대한 직접 링크

indexName:

string
설명할 인덱스의 이름

보고:

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

deleteIndex()
deleteindex에 대한 직접 링크

indexName:

string
삭제할 인덱스의 이름

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

await vectorStore.deleteIndex({ indexName: 'my_vectors' })

updateVector()
updatevector에 대한 직접 링크

ID 또는 메타데이터 필터를 기준으로 단일 벡터를 업데이트합니다. id 또는 filter 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

indexName:

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

id?:

string
업데이트할 벡터의 ID(filter와 함께 사용할 수 없음)

filter?:

Record<string, any>
업데이트할 벡터를 식별하는 메타데이터 필터(id와 함께 사용할 수 없음)

update:

{ vector?: number[]; metadata?: Record<string, any>; }
업데이트할 벡터 및/또는 메타데이터가 포함된 객체
// Update by ID
await vectorStore.updateVector({
  indexName: 'my_vectors',
  id: 'vector123',
  update: {
    vector: [0.1, 0.2, 0.3],
    metadata: { label: 'updated' },
  },
})

// Update by filter
await vectorStore.updateVector({
  indexName: 'my_vectors',
  filter: { category: 'product' },
  update: {
    metadata: { status: 'reviewed' },
  },
})

deleteVector()
deletevector에 대한 직접 링크

indexName:

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

id:

string
삭제할 벡터의 ID
await vectorStore.deleteVector({ indexName: 'my_vectors', id: 'vector123' })

deleteVectors()
deletevectors에 대한 직접 링크

ID 또는 메타데이터 필터를 기준으로 여러 벡터를 삭제합니다. ids 또는 filter 중 하나만 제공해야 하며, 둘 다 제공해서는 안 됩니다.

indexName:

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

ids?:

string[]
삭제할 벡터 ID 배열(filter와 함께 사용할 수 없음)

filter?:

Record<string, any>
삭제할 벡터를 식별하는 메타데이터 필터(ids와 함께 사용할 수 없음)
// Delete by IDs
await vectorStore.deleteVectors({
  indexName: 'my_vectors',
  ids: ['vec1', 'vec2', 'vec3'],
})

// Delete by filter
await vectorStore.deleteVectors({
  indexName: 'my_vectors',
  filter: { status: 'archived' },
})

응답 유형
응답 유형에 대한 직접 링크

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

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

메타데이터 필터링
메타데이터 필터링에 대한 직접 링크

ConvexVector연산자를 사용한 메타데이터 필터링을 지원합니다. 이러한 필터는 Convex에서 벡터가 로드된 후 어댑터에 의해 적용됩니다.

// Simple equality
const results = await vectorStore.query({
  indexName: 'my_vectors',
  queryVector: embedding,
  filter: { category: 'documents' },
})

// Comparison operators
const results = await vectorStore.query({
  indexName: 'my_vectors',
  queryVector: embedding,
  filter: {
    price: { $gt: 100 },
    status: { $in: ['active', 'pending'] },
  },
})

// Logical operators
const results = await vectorStore.query({
  indexName: 'my_vectors',
  queryVector: embedding,
  filter: {
    $and: [{ category: 'electronics' }, { price: { $lte: 500 } }],
  },
})

지원되는 필터 연산자
지원되는 필터 연산자에 대한 직접 링크

연산자설명
$eq같음
$ne같지 않음
$gt보다 큼
$gte크거나 같음
$lt보다 작음
$lte작거나 같음
$in배열에 포함됨
$nin배열에 포함되지 않음
$and논리 AND
$or논리 OR

아키텍처
아키텍처에 대한 직접 링크

ConvexVector는 다음 구조의 mastra_vectors 테이블에 벡터를 저장합니다.

  • id: 고유 벡터 식별자
  • indexName: 인덱스 이름
  • embedding: 벡터 데이터(수레 배열)
  • metadata: 선택적 JSON 메타데이터

Mastra 어댑터에서는 코사인 유사성을 사용하여 벡터 유사성 검색이 수행됩니다. 이는 설정을 유연하게 유지하지만 대규모 생산 벡터 컬렉션용으로 설계되지 않았습니다.

ConvexNativeVector는 각 Mastra 벡터 인덱스를 전용 Convex 테이블에 저장합니다. 쿼리는 ctx.vectorSearch를 사용하는 Convex 작업을 호출한 다음, Convex 쿼리를 통해 일치하는 문서를 불러옵니다. 이는 Convex 네이티브 벡터 검색 Model을 따릅니다.

  • 벡터 인덱스는 convex/schema.ts에서 선언합니다.
  • 벡터 검색은 Convex 작업에서 실행됩니다.
  • topK는 1에서 256 사이여야 합니다.
  • 필터는 Convex 벡터 인덱스의 filterFields에 나열된 필드를 대상으로 해야 합니다.
  • 인덱스 간 결과가 섞이지 않도록 Mastra 벡터 인덱스마다 하나의 전용 테이블을 사용하세요. 런타임 시 런타임 정의 인덱스 생성, 메타데이터 전용 쿼리, 복잡한 필터 연산자, 필터 기반 대량 업데이트 또는 삭제, Convex의 기본 벡터 검색 한도를 초과하는 결과 제한이 필요한 경우 외부 벡터 데이터베이스를 사용하세요.
On this page