Qdrant 向量儲存

QdrantVector 類別使用向量相似度搜尋引擎 Qdrant 提供向量搜尋。 它提供可直接用於生產環境的服務，並備有便捷 API，可儲存、搜尋及管理向量，亦支援額外 payload 及進階篩選功能。

建構函式選項

url:

string

Qdrant 執行個體的 REST URL。例如：https://xyz-example.eu-central.aws.cloud.qdrant.io:6333

apiKey:

string

可選的 Qdrant API 金鑰

https:

boolean

設定連線時是否使用 TLS。建議使用。

方法

createIndex()

indexName:

string

要建立的索引名稱

dimension:

number

向量維度（必須與 embedding 模型相符）。單向量集合必須提供。

metric?:

'cosine' | 'euclidean' | 'dotproduct'

= cosine

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

namedVectors?:

Record<string, { size: number; distance: 'cosine' | 'euclidean' | 'dotproduct' }>

具名向量空間的設定。提供此設定後，會建立包含多個具名向量欄位的集合。

建立具名向量集合

// Create a collection with multiple named vector spaces
await store.createIndex({
  indexName: 'multi_modal',
  dimension: 768, // fallback
  namedVectors: {
    text: { size: 768, distance: 'cosine' },
    image: { size: 512, distance: 'euclidean' },
  },
})

upsert()

indexName:

string

要 upsert 至的索引名稱

vectors:

number[][]

embedding 向量陣列

metadata?:

Record<string, any>[]

每個向量的元資料

ids?:

string[]

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

vectorName?:

string

使用具名向量時，要 upsert 至的向量空間名稱。

Upsert 至具名向量空間

// Upsert into the "text" vector space
await store.upsert({
  indexName: 'multi_modal',
  vectors: textEmbeddings,
  metadata: textMetadata,
  vectorName: 'text',
})

// Upsert into the "image" vector space
await store.upsert({
  indexName: 'multi_modal',
  vectors: imageEmbeddings,
  metadata: imageMetadata,
  vectorName: 'image',
})

query()

indexName:

string

要查詢的索引名稱

queryVector:

number[]

用來尋找相似向量的查詢向量

topK?:

number

= 10

要傳回的結果數目

filter?:

Record<string, any>

查詢所用的元資料篩選條件

includeVector?:

boolean

= false

結果中是否包含向量

using?:

string

使用具名向量時要查詢的向量欄位名稱。當集合包含多個具名向量欄位時使用此選項。

具名向量

Qdrant 支援每個集合包含多個向量，並為每個向量欄位指定名稱。使用 using 參數選擇要查詢的向量欄位：

const results = await store.query({
  indexName: 'my_index',
  queryVector: embedding,
  topK: 10,
  using: 'title_embedding', // Query against a specific named vector
})

listIndexes()

以字串陣列形式傳回索引名稱。

describeIndex()

indexName:

string

要描述的索引名稱

傳回：

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

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

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

deleteVectors()

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

indexName:

string

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

ids?:

string[]

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

filter?:

Record<string, any>

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

createPayloadIndex()

在集合欄位上建立 payload（元資料）索引，以便高效篩選。Qdrant Cloud 及任何設有 strict_mode_config = true 的 Qdrant 執行個體都必須建立此索引。

indexName:

string

要在其上建立 payload 索引的集合名稱

fieldName:

string

要建立索引的 payload 欄位名稱

fieldSchema:

'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'

payload 欄位的 schema 類型

wait?:

boolean

= true

是否等待操作完成

// Create a keyword index for filtering by source
await store.createPayloadIndex({
  indexName: 'my_index',
  fieldName: 'source',
  fieldSchema: 'keyword',
})

const results = await store.query({
  indexName: 'my_index',
  queryVector: queryVector,
  filter: { source: 'document-a' },
})

deletePayloadIndex()

從集合欄位移除 payload 索引。

indexName:

string

要從中刪除 payload 索引的集合名稱

fieldName:

string

要刪除的 payload 欄位索引名稱

wait?:

boolean

= true

是否等待操作完成

回應類型

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

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

錯誤處理

此儲存會擲出可被捕捉的具型別錯誤：

try {
  await store.query({
    indexName: 'index_name',
    queryVector: queryVector,
  })
} catch (error) {
  if (error instanceof VectorStoreError) {
    console.log(error.code) // 'connection_failed' | 'invalid_dimension' | etc
    console.log(error.details) // Additional error context
  }
}

相關內容

• 元資料篩選條件