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

# Convex 向量儲存

`ConvexVector` 類別使用 [Convex](https://convex.dev) 提供向量儲存及相似度搜尋。它在 Convex 內儲存嵌入向量，並在 Mastra adapter 中執行餘弦相似度搜尋。

> **開發規模搜尋:** `ConvexVector` 透過 Mastra 儲存處理器讀取相符的向量、在 JavaScript 中篩選、計算餘弦相似度、排序結果，然後傳回最相符的結果。適合用於本機開發、測試及小型資料集。
>
> 如要在 Convex 上進行生產環境向量搜尋，請使用 `ConvexNativeVector`。它會使用 Convex 原生 `vectorSearch` API，而此 API 需要已部署的 Convex 向量索引及 Convex action。

## 安裝

**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
```

## Convex 設定

使用 `ConvexVector` 前，你需要設定 Convex schema 及儲存處理器。設定指示請參閱 [Convex 儲存設定](https://mastra.zisheng.pro/zh-HK/reference/storage/convex)。

## 建構函式選項

**deploymentUrl** (`string`): Convex 部署 URL（例如 https\://your-project.convex.cloud）

**adminAuthToken** (`string`): Convex 管理員驗證 token

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

### 原生 Convex 向量搜尋

生產環境的向量工作負載請使用 `ConvexNativeVector`。它會將向量儲存在專用的 Convex 資料表中，並查詢在 schema 中定義的 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 schema 中宣告篩選欄位。寫入向量時，原生向量處理器會將相符的中繼資料欄位複製至文件的頂層欄位。

```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`): 向量維度（必須與嵌入模型相符）

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜尋所使用的距離度量（目前只支援餘弦距離） (Default: `cosine`)

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

### `upsert()`

**indexName** (`string`): 要 upsert 向量的索引名稱

**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 載入向量後，adapter 會套用這些篩選器。

```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 adapter 中使用餘弦相似度執行。這種方式可讓設定保持靈活，但並非為大型生產環境向量集合而設。

`ConvexNativeVector` 會將每個 Mastra 向量索引儲存在專用的 Convex 資料表中。其查詢會呼叫使用 `ctx.vectorSearch` 的 Convex action，然後透過 Convex query 載入相符的文件。這遵循 Convex 原生向量搜尋模型：

- 向量索引在 `convex/schema.ts` 中宣告。
- 向量搜尋從 Convex action 執行。
- `topK` 必須介乎 `1` 至 `256`。
- 篩選器必須針對 Convex 向量索引 `filterFields` 中列出的欄位。
- 每個 Mastra 向量索引使用一個專用資料表，以免結果跨越不同索引。

如你需要在執行階段定義索引建立、僅限中繼資料的查詢、複雜篩選運算子、基於篩選器的批量更新或刪除，或超出 Convex 原生向量搜尋上限的結果數目，請使用外部向量資料庫。

## 相關內容

- [Convex 儲存](https://mastra.zisheng.pro/zh-HK/reference/storage/convex)
- [中繼資料篩選器](https://mastra.zisheng.pro/zh-HK/reference/rag/metadata-filters)
- [Convex 說明文件](https://docs.convex.dev/)