跳至主要內容

libSQL 向量儲存

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

安裝
安裝 的直接連結

npm install @mastra/libsql@latest

用法
用法 的直接連結

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()
createindex 的直接連結

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

indexName:

string
要建立的索引名稱

dimension:

number
向量維度大小（必須與嵌入模型相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'
= cosine
相似度搜尋所使用的距離度量。注意：libSQL 目前只支援餘弦相似度。

upsert()
upsert 的直接連結

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

indexName:

string
要插入資料的索引名稱

vectors:

number[][]
嵌入向量陣列

metadata?:

Record<string, any>[]
每個向量的元資料

ids?:

string[]
可選的向量 ID（如未提供則自動產生）

query()
query 的直接連結

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

indexName:

string
要搜尋的索引名稱

queryVector:

number[]
用來尋找相似向量的查詢向量

topK?:

number
= 10
要傳回的結果數目

filter?:

Filter
元資料篩選條件

includeVector?:

boolean
= false
是否在結果中包含向量資料

minScore?:

number
= 0
最低相似度分數門檻

describeIndex()
describeindex 的直接連結

取得索引的資料。

indexName:

string
要取得資料的索引名稱

傳回：

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

deleteIndex()
deleteindex 的直接連結

刪除索引及其所有資料。

indexName:

string
要刪除的索引名稱

listIndexes()
listindexes 的直接連結

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

傳回：Promise<string[]>

truncateIndex()
truncateindex 的直接連結

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

indexName:

string
要清空的索引名稱

updateVector()
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()
deletevector 的直接連結

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

indexName:

string
包含該向量的索引名稱

id:

string
要刪除的向量項目 ID

deleteVectors()
deletevectors 的直接連結

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

indexName:

string
包含待刪除向量的索引名稱

ids?:

string[]
待刪除的向量 ID 陣列（與 filter 互斥）

filter?:

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

回應類型
回應類型 的直接連結

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

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

錯誤處理
錯誤處理 的直接連結

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

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 的本機嵌入
使用 fastembed 的本機嵌入 的直接連結

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

安裝 fastembed 以開始使用：

npm install @mastra/fastembed@latest

將以下內容加入你的 Agent：

src/mastra/agents/example-libsql-agent.ts
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
    },
  }),
})
On this page