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

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

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[][]

嵌入向量陣列

metadata?:

Record<string, any>[]

每個向量的中繼資料

ids?:

string[]

選用的向量 ID（未提供時會自動產生）

query()

tableName:

string

要查詢的資料表名稱

queryVector:

number[]

查詢向量

topK?:

number

= 10

要傳回的結果數量

filter?:

Record<string, any>

中繼資料篩選條件

includeVector?:

boolean

= false

結果是否包含向量

columns?:

string[]

= []

結果中要包含的特定欄位

includeAllColumns?:

boolean

= false

結果是否包含所有欄位

listTables()

以字串陣列傳回資料表名稱。

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

getTableSchema()

tableName:

string

要描述的資料表名稱

傳回指定資料表的 schema。

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 或中繼資料篩選條件更新單一向量。必須提供 id 或 filter 其中一項，但不能同時提供兩者。

indexName:

string

包含該向量的索引名稱

id?:

string

要更新的向量 ID（不可與 filter 同時使用）

filter?:

Record<string, any>

用於識別待更新向量的中繼資料篩選條件（不可與 id 同時使用）

update:

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

包含待更新向量及／或中繼資料的物件

deleteVector()

indexName:

string

包含該向量的索引名稱

id:

string

要刪除的向量 ID

deleteVectors()

依 ID 或中繼資料篩選條件刪除多個向量。必須提供 ids 或 filter 其中一項，但不能同時提供兩者。

indexName:

string

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

ids?:

string[]

要刪除的向量 ID 陣列（不可與 filter 同時使用）

filter?:

Record<string, any>

用於識別待刪除向量的中繼資料篩選條件（不可與 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() 方法正確關閉連線
• 使用一致的 schema 儲存中繼資料，以簡化篩選操作

相關內容

• 中繼資料篩選條件