Lance 向量儲存

LanceVectorStore 類別使用 LanceDB 提供向量搜尋。LanceDB 是建基於 Lance 欄式格式的嵌入式向量資料庫，為本機開發及生產部署提供高效儲存和快速相似度搜尋。

工廠方法

LanceVectorStore 使用工廠模式建立實例。你應使用靜態 create() 方法，而非直接使用建構函式。

uri:

string

LanceDB 資料庫的路徑，或雲端部署的 URI

options?:

ConnectionOptions

LanceDB 的其他連線選項

建構函式範例

你可以使用靜態 create 方法建立 LanceVectorStore 實例：

import { LanceVectorStore } from '@mastra/lance'

// Connect to a local database
const vectorStore = await LanceVectorStore.create('/path/to/db')

// Connect to a LanceDB cloud database
const cloudStore = await LanceVectorStore.create('db://host:port')

// Connect to a cloud database with options
const s3Store = await LanceVectorStore.create('s3://bucket/db', {
  storageOptions: { timeout: '60s' },
})

方法

createIndex()

tableName:

string

要在其中建立索引的資料表名稱

indexName:

string

要建立的索引名稱（欄名稱）

dimension:

number

向量維度（必須與你的 embedding 模型相符）

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

相似度搜尋所用的距離度量

indexConfig?:

LanceIndexConfig

= { type: 'hnsw' }

索引設定

LanceIndexConfig

type:

'ivfflat' | 'hnsw'

= hnsw

索引類型

string

ivfflat:

ivfflat

將向量分群至多個列表以進行近似搜尋。

hnsw:

hnsw

以圖形為基礎的索引，提供快速搜尋和高召回率。

numPartitions?:

number

= 128

IVF 索引的分區數量

numSubVectors?:

number

= 16

乘積量化的子向量數量

hnsw?:

HNSWConfig

HNSW 設定

object

m?:

number

每個節點的連線數量上限（預設值：16）

efConstruction?:

number

建立時的複雜度（預設值：100）

createTable()

tableName:

string

要建立的資料表名稱

data:

Record<string, unknown>[] | TableLike

資料表的初始資料

options?:

Partial<CreateTableOptions>

其他資料表建立選項

upsert()

tableName:

string

要 upsert 向量的資料表名稱

vectors:

number[][]

embedding 向量陣列

metadata?:

Record<string, any>[]

每個向量的 metadata

ids?:

string[]

選填的向量 ID（如未提供則自動產生）

query()

tableName:

string

要查詢的資料表名稱

queryVector:

number[]

查詢向量

topK?:

number

= 10

要傳回的結果數量

filter?:

Record<string, any>

Metadata 篩選條件

includeVector?:

boolean

= false

是否在結果中包含向量

columns?:

string[]

= []

要在結果中包含的特定欄

includeAllColumns?:

boolean

= false

是否在結果中包含所有欄

listTables()

傳回由資料表名稱字串組成的陣列。

const tables = await vectorStore.listTables()
// ['my_vectors', 'embeddings', 'documents']

getTableSchema()

tableName:

string

要描述的資料表名稱

傳回指定資料表的結構描述。

deleteTable()

tableName:

string

要刪除的資料表名稱

deleteAllTables()

刪除資料庫中的所有資料表。

listIndexes()

傳回由索引名稱字串組成的陣列。

describeIndex()

indexName:

string

要描述的索引名稱

傳回索引的資料：

interface IndexStats {
  dimension: number
  count: number
  metric: 'cosine' | 'euclidean' | 'dotproduct'
  type: 'ivfflat' | 'hnsw'
  config: {
    m?: number
    efConstruction?: number
    numPartitions?: number
    numSubVectors?: number
  }
}

deleteIndex()

indexName:

string

要刪除的索引名稱

updateVector()

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

indexName:

string

包含該向量的索引名稱

id?:

string

要更新的向量 ID（與 filter 互斥）

filter?:

Record<string, any>

用於識別要更新向量的 metadata 篩選條件（與 id 互斥）

update:

{ vector?: number[]; metadata?: Record<string, any>; }

包含要更新之向量及／或 metadata 的物件

deleteVector()

indexName:

string

包含該向量的索引名稱

id:

string

要刪除的向量 ID

deleteVectors()

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

indexName:

string

包含該向量的索引名稱s to delete

ids?:

string[]

要刪除的向量 ID 陣列（與 filter 互斥）

filter?:

Record<string, any>

用於識別要刪除向量的 metadata 篩選條件（與 ids 互斥）

close()

關閉資料庫連線。

回應類型

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

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

錯誤處理

此儲存會擲回可被捕捉的具類型錯誤：

try {
  await store.query({
    tableName: 'my_vectors',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof Error) {
    console.log(error.message)
  }
}

最佳實務

• 根據你的使用情境選用合適的索引類型：
  • 記憶體不受限制時，使用 HNSW 以取得更高召回率和效能
  • 處理大型資料集時，使用 IVF 以提高記憶體效率
• 處理大型資料集時，可考慮調整 numPartitions 和 numSubVectors 的值以獲得最佳效能
• 完成資料庫操作後，使用 close() 方法正確關閉連線
• 使用一致的結構描述儲存 metadata，以簡化篩選操作

相關內容

• Metadata 篩選條件