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

# Qdrant 向量儲存

QdrantVector 類別使用向量相似度搜尋引擎 [Qdrant](https://qdrant.tech/) 提供向量搜尋。 它提供可用於正式環境的服務，並具備方便的 API，可儲存、搜尋和管理向量，且支援額外承載資料與擴充篩選功能。

## 建構函式選項

**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`): 向量維度（必須與嵌入模型相符）。單一向量集合必須提供。

**metric** (`'cosine' | 'euclidean' | 'dotproduct'`): 相似度搜尋使用的距離度量 (Default: `cosine`)

**namedVectors** (`Record<string, { size: number; distance: 'cosine' | 'euclidean' | 'dotproduct' }>`): 具名向量空間的設定。提供此項時，會建立具有多個具名向量欄位的集合。

#### 建立具名向量集合

```typescript
// 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[][]`): 嵌入向量陣列

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

**ids** (`string[]`): 選用的向量 ID（未提供時會自動產生）

**vectorName** (`string`): 使用具名向量時，要 upsert 資料的向量空間名稱。

#### Upsert 至具名向量空間

```typescript
// 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`): 要傳回的結果數量 (Default: `10`)

**filter** (`Record<string, any>`): 查詢的中繼資料篩選條件

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

**using** (`string`): 使用具名向量時要查詢的向量欄位名稱。集合有多個具名向量欄位時使用此選項。

#### 具名向量

Qdrant 支援[每個集合使用多個向量](https://qdrant.tech/documentation/concepts/vectors/#named-vectors)，並為每個向量欄位指派名稱。使用 `using` 參數選擇要查詢的向量欄位：

```typescript
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`): 要描述的索引名稱

傳回：

```typescript
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()`

在集合欄位上建立承載資料（中繼資料）索引，以啟用高效率篩選。Qdrant Cloud 以及任何設定 `strict_mode_config = true` 的 Qdrant 執行個體都**必須**執行此操作。

**indexName** (`string`): 要建立承載資料索引的集合名稱

**fieldName** (`string`): 要建立索引的承載資料欄位名稱

**fieldSchema** (`'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'`): 承載資料欄位的 schema 型別

**wait** (`boolean`): 是否等待操作完成 (Default: `true`)

```typescript
// 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()`

從集合欄位移除承載資料索引。

**indexName** (`string`): 要從中刪除承載資料索引的集合名稱

**fieldName** (`string`): 要刪除的承載資料欄位索引名稱

**wait** (`boolean`): 是否等待操作完成 (Default: `true`)

## 回應型別

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

```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: '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
  }
}
```

## 相關內容

- [中繼資料篩選條件](https://mastra.zisheng.pro/zh-TW/reference/rag/metadata-filters)