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

# Convex 向量儲存

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

> **開發規模的搜尋:** `ConvexVector` 會透過 Mastra 儲存處理常式讀取相符的向量、在 JavaScript 中篩選、計算餘弦相似度、排序結果，並傳回最相符的項目。它適合用於本機開發、測試與小型資料集。
>
> 若要在 Convex 上執行正式環境的向量搜尋，請使用 `ConvexNativeVector`。它使用 Convex 原生的 `vectorSearch` 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-TW/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',
})
```

### 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'`): 相似度搜尋使用的距離度量（目前僅支援 cosine） (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 載入向量後，介接器會套用這些篩選條件。

```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 action，再透過 Convex query 載入相符文件。這遵循 Convex 原生向量搜尋模型：

- 向量索引在 `convex/schema.ts` 中宣告。
- 向量搜尋從 Convex action 執行。
- `topK` 必須介於 `1` 到 `256` 之間。
- 篩選條件必須以 Convex 向量索引 `filterFields` 中列出的欄位為目標。
- 每個 Mastra 向量索引應使用一個專用資料表，以避免產生跨索引結果。

若需要在執行階段建立動態定義的索引、僅使用中繼資料查詢、複雜篩選運算子、依篩選條件大量更新或刪除，或結果數量超過 Convex 原生向量搜尋上限，請使用外部向量資料庫。

## 相關內容

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