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

# libSQL 向量儲存

libSQL 儲存實作透過與 SQLite 相容的向量搜尋方案 [libSQL](https://github.com/tursodatabase/libsql)（具備向量擴充功能的 SQLite 分支），以及同樣具備向量擴充功能的 [Turso](https://turso.tech/)，提供輕量而高效的向量資料庫解決方案。 它是 `@mastra/libsql` 套件的一部分，提供支援元資料篩選的高效向量相似度搜尋。

## 安裝

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## 用法

```typescript
import { LibSQLVector } from "@mastra/libsql";

// Create a new vector store instance
const store = new LibSQLVector({
  id: 'libsql-vector',
  url: process.env.DATABASE_URL,
  // Optional: for Turso cloud databases
  authToken: process.env.DATABASE_AUTH_TOKEN,
});

// Create an index
await store.createIndex({
  indexName: "myCollection",
  dimension: 1536,
});

// Add vectors with metadata
const vectors = [[0.1, 0.2, ...], [0.3, 0.4, ...]];
const metadata = [
  { text: "first document", category: "A" },
  { text: "second document", category: "B" }
];
await store.upsert({
  indexName: "myCollection",
  vectors,
  metadata,
});

// Query similar vectors
const queryVector = [0.1, 0.2, ...];
const results = await store.query({
  indexName: "myCollection",
  queryVector,
  topK: 10, // top K results
  filter: { category: "A" } // optional metadata filter
});
```

## 建構函數選項

**url** (`string`): libSQL 資料庫 URL。記憶體內資料庫請使用 ':memory:'，本機檔案請使用 'file:dbname.db'，亦可使用與 libSQL 相容的連線字串，例如 'libsql://your-database.turso.io'。

**authToken** (`string`): Turso 雲端資料庫的驗證權杖

**syncUrl** (`string`): 資料庫複寫 URL（Turso 專用）

**syncInterval** (`number`): 資料庫同步的間隔時間（毫秒，Turso 專用）

## 方法

### `createIndex()`

建立新的向量集合。索引名稱必須以英文字母或底線開頭，並且只能包含英文字母、數字及底線字元。維度必須是正整數。

**indexName** (`string`): 要建立的索引名稱

**dimension** (`number`): 向量維度大小（必須與嵌入模型相符）

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

### `upsert()`

在索引中加入或更新向量及其元資料。此操作使用交易，確保所有向量以不可分割的方式插入；如有任何插入失敗，整項操作都會回復。

**indexName** (`string`): 要插入資料的索引名稱

**vectors** (`number[][]`): 嵌入向量陣列

**metadata** (`Record<string, any>[]`): 每個向量的元資料

**ids** (`string[]`): 可選的向量 ID（如未提供則自動產生）

### `query()`

搜尋相似向量，並可選擇使用元資料篩選。

**indexName** (`string`): 要搜尋的索引名稱

**queryVector** (`number[]`): 用來尋找相似向量的查詢向量

**topK** (`number`): 要傳回的結果數目 (Default: `10`)

**filter** (`Filter`): 元資料篩選條件

**includeVector** (`boolean`): 是否在結果中包含向量資料 (Default: `false`)

**minScore** (`number`): 最低相似度分數門檻 (Default: `0`)

### `describeIndex()`

取得索引的資料。

**indexName** (`string`): 要取得資料的索引名稱

傳回：

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

### `deleteIndex()`

刪除索引及其所有資料。

**indexName** (`string`): 要刪除的索引名稱

### `listIndexes()`

列出資料庫中的所有向量索引。

傳回：`Promise<string[]>`

### `truncateIndex()`

移除索引中的所有向量，同時保留索引結構。

**indexName** (`string`): 要清空的索引名稱

### `updateVector()`

按 ID 或元資料篩選條件更新單一向量。必須提供 `id` 或 `filter`，但不可同時提供兩者。

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要更新的向量項目 ID（與 filter 互斥）

**filter** (`Record<string, any>`): 用來識別待更新向量的元資料篩選條件（與 id 互斥）

**update** (`object`): 包含向量及／或元資料的更新資料

**update.vector** (`number[]`): 要更新的新向量資料

**update.metadata** (`Record<string, any>`): 要更新的新元資料

### `deleteVector()`

按 ID 從索引刪除指定的向量項目。

**indexName** (`string`): 包含該向量的索引名稱

**id** (`string`): 要刪除的向量項目 ID

### `deleteVectors()`

按 ID 或元資料篩選條件刪除多個向量。必須提供 `ids` 或 `filter`，但不可同時提供兩者。

**indexName** (`string`): 包含待刪除向量的索引名稱

**ids** (`string[]`): 待刪除的向量 ID 陣列（與 filter 互斥）

**filter** (`Record<string, any>`): 用來識別待刪除向量的元資料篩選條件（與 ids 互斥）

## 回應類型

查詢結果會以下列格式傳回：

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

## 錯誤處理

此向量儲存會針對不同失敗情況擲回特定錯誤：

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

常見錯誤情況包括：

- 索引名稱格式無效
- 向量維度無效
- 找不到資料表／索引
- 資料庫連線問題
- upsert 期間交易失敗

## 用法範例

### 使用 fastembed 的本機嵌入

嵌入是 memory 的 `semanticRecall` 所使用的數值向量，可按語意（而非關鍵字）擷取相關訊息。此設定使用 `@mastra/fastembed` 產生向量嵌入。

安裝 `fastembed` 以開始使用：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

將以下內容加入你的 Agent：

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'
import { fastembed } from '@mastra/fastembed'

export const libsqlAgent = new Agent({
  id: 'libsql-agent',
  name: 'libSQL Agent',
  instructions:
    'You are an AI agent with the ability to automatically recall memories from previous interactions.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'libsql-agent-storage',
      url: 'file:libsql-agent.db',
    }),
    vector: new LibSQLVector({
      id: 'libsql-agent-vector',
      url: 'file:libsql-agent.db',
    }),
    embedder: fastembed,
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
      },
      generateTitle: true, // Explicitly enable automatic title generation
    },
  }),
})
```

## 相關內容

- [元資料篩選器](https://mastra.zisheng.pro/zh-HK/reference/rag/metadata-filters)