> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 볼록 벡터 저장소

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

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

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

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

## 설치

**npm**:

```bash
npm install @mastra/convex@latest
```

**pnpm**:

```bash
pnpm add @mastra/convex@latest
```

**Yarn**:

```bash
yarn add @mastra/convex@latest
```

**Bun**:

```bash
bun add @mastra/convex@latest
```

## 볼록한 설정

`ConvexVector`를 사용하기 전에 Convex 스키마와 저장소 핸들러를 설정해야 합니다. 설정 방법은 [Convex 저장소 설정](https://mastra.zisheng.pro/ko/reference/storage/convex)을 참조하세요.

## 생성자 옵션

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

**adminAuthToken** (`string`): Convex 관리자 인증 토큰입니다.

**storageFunction** (`string`): 저장소 mutation 함수의 경로입니다. (Default: `mastra/storage:handle`)

## 생성자 예

### 기본 구성

```ts
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 벡터 인덱스에 사용할 전용 테이블을 정의하세요.

```typescript
import { defineSchema } from 'convex/server'
import { defineMastraNativeVectorTable } from '@mastra/convex/schema'

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

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

```typescript
import {
  mastraNativeVectorAction,
  mastraNativeVectorMutation,
  mastraNativeVectorQuery,
} from '@mastra/convex/server'

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

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

```typescript
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 스키마에서 필터 필드를 선언하세요. 기본 벡터 핸들러는 벡터가 작성될 때 일치하는 메타데이터 필드를 최상위 문서 필드에 복사합니다.

```typescript
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'],
    }),
})
```

```typescript
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를 사용하세요.

### 맞춤형 저장 기능

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

## 행동 양식

### `createIndex()`

**indexName** (`string`): 생성할 인덱스의 이름

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

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 유사도 검색에 사용할 거리 측정 방식(현재는 cosine만 지원) (Default: `cosine`)

```typescript
await vectorStore.createIndex({
  indexName: 'my_vectors',
  dimension: 1536,
})
```

### `upsert()`

**indexName** (`string`): 벡터를 업서트할 인덱스의 이름

**vectors** (`number[][]`): 임베딩 벡터 배열

**metadata** (`Record<string, any>[]`): 각 벡터의 메타데이터

**ids** (`string[]`): 선택적 벡터 ID(제공하지 않으면 자동 생성)

```typescript
await vectorStore.upsert({
  indexName: "my_vectors",
  vectors: [[0.1, 0.2, 0.3, ...]],
  metadata: [{ label: "example" }],
  ids: ["vec-1"],
});
```

### `query()`

**indexName** (`string`): 쿼리할 인덱스의 이름

**queryVector** (`number[]`): 쿼리 벡터

**topK** (`number`): 반환할 결과 수 (Default: `10`)

**filter** (`Record<string, any>`): 메타데이터 필터

**includeVector** (`boolean`): 결과에 벡터를 포함할지 여부 (Default: `false`)

```typescript
const results = await vectorStore.query({
  indexName: "my_vectors",
  queryVector: [0.1, 0.2, 0.3, ...],
  topK: 5,
  filter: { category: "documents" },
});
```

### `listIndexes()`

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

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

### `describeIndex()`

**indexName** (`string`): 설명할 인덱스의 이름

보고:

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

### `deleteIndex()`

**indexName** (`string`): 삭제할 인덱스의 이름

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

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

### `updateVector()`

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

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

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

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

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 업데이트할 벡터 및/또는 메타데이터가 포함된 객체

```typescript
// 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()`

**indexName** (`string`): 벡터가 포함된 인덱스의 이름

**id** (`string`): 삭제할 벡터의 ID

```typescript
await vectorStore.deleteVector({ indexName: 'my_vectors', id: 'vector123' })
```

### `deleteVectors()`

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

**indexName** (`string`): 삭제할 벡터가 포함된 인덱스의 이름

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

**filter** (`Record<string, any>`): 삭제할 벡터를 식별하는 메타데이터 필터(ids와 함께 사용할 수 없음)

```typescript
// 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' },
})
```

## 응답 유형

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

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

## 메타데이터 필터링

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

```typescript
// 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의 기본 벡터 검색 한도를 초과하는 결과 제한이 필요한 경우 외부 벡터 데이터베이스를 사용하세요.

## 관련된

- [볼록한 저장](https://mastra.zisheng.pro/ko/reference/storage/convex)
- [메타데이터 필터](https://mastra.zisheng.pro/ko/reference/rag/metadata-filters)
- [볼록 문서](https://docs.convex.dev/)