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

# Qdrant Vector 存储

QdrantVector 类使用 Vector 相似度搜索引擎 [Qdrant](https://qdrant.tech/) 提供 Vector 搜索。 它提供可用于生产环境的服务，并提供便捷的 API 来存储、搜索和管理 Vector，同时支持额外的 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`): Vector 维度（必须与嵌入模型匹配）。单 Vector collection 必须提供此项。

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

**namedVectors** (`Record<string, { size: number; distance: 'cosine' | 'euclidean' | 'dotproduct' }>`): 命名 Vector 空间的配置。提供此项时，将创建包含多个命名 Vector 字段的 collection。

#### 创建命名 Vector collection

```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[][]`): 嵌入 Vector 数组

**metadata** (`Record<string, any>[]`): 每个 Vector 的元数据

**ids** (`string[]`): 可选的 Vector ID（未提供时自动生成）

**vectorName** (`string`): 使用命名 Vector 时，要 upsert 数据的 Vector 空间名称。

#### Upsert 到命名 Vector 空间

```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[]`): 用于查找相似 Vector 的查询 Vector

**topK** (`number`): 要返回的结果数量 (Default: `10`)

**filter** (`Record<string, any>`): 查询使用的元数据筛选条件

**includeVector** (`boolean`): 结果中是否包含 Vector (Default: `false`)

**using** (`string`): 使用命名 Vector 时要查询的 Vector 字段名称。当 collection 包含多个命名 Vector 字段时，请使用此项。

#### 命名 Vector

Qdrant 支持[每个 collection 包含多个 Vector](https://qdrant.tech/documentation/concepts/vectors/#named-vectors)，每个 Vector 字段都有一个名称。使用 `using` 参数选择要查询的 Vector 字段：

```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 或元数据筛选条件更新单个 Vector。必须提供 `id` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 要更新的索引名称

**id** (`string`): 要更新的 Vector ID（不能与 filter 同时使用）

**filter** (`Record<string, any>`): 用于标识待更新 Vector 的元数据筛选条件（不能与 id 同时使用）

**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): 包含待更新 Vector 和/或元数据的对象

更新指定索引中 Vector 和/或其元数据。如果同时提供 Vector 和元数据，两者都会更新。仅提供其中一个值时，则只更新该值。

### `deleteVector()`

**indexName** (`string`): 要从中删除 Vector 的索引名称

**id** (`string`): 要删除的 Vector ID

按 ID 从指定索引中删除 Vector。

### `deleteVectors()`

按 ID 或元数据筛选条件删除多个 Vector。必须提供 `ids` 或 `filter`，但不能同时提供两者。

**indexName** (`string`): 包含待删除 Vector 的索引名称

**ids** (`string[]`): 要删除的 Vector ID 数组（不能与 filter 同时使用）

**filter** (`Record<string, any>`): 用于标识待删除 Vector 的元数据筛选条件（不能与 ids 同时使用）

### `createPayloadIndex()`

在 collection 字段上创建 payload（元数据）索引，以实现高效筛选。对于 Qdrant Cloud 以及任何设置了 `strict_mode_config = true` 的 Qdrant 实例，此操作为**必需**。

**indexName** (`string`): 要在其上创建 payload 索引的 collection 名称

**fieldName** (`string`): 要建立索引的 payload 字段名称

**fieldSchema** (`'keyword' | 'integer' | 'float' | 'geo' | 'text' | 'bool' | 'datetime' | 'uuid'`): payload 字段的 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()`

从 collection 字段中移除 payload 索引。

**indexName** (`string`): 要从中删除 payload 索引的 collection 名称

**fieldName** (`string`): 要删除的 payload 字段索引名称

**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/reference/rag/metadata-filters)