Qdrant 快速入门

960 字

5 分钟

Qdrant 快速入门

2025-04-09

prog

qdrant

/

db

/

ai

Qdrant（发音为”quadrant”）是一个用Rust编写的向量相似度搜索引擎和向量数据库。它提供了一个生产级服务，带有便捷的API用于存储、搜索和管理点（带有额外payload的向量）。

核心特性#

Qdrant专为扩展过滤支持而设计，使其适用于各种基于神经网络或语义的匹配、多面搜索等应用。
由于使用Rust编写，即使在高负载下也能保持快速和可靠。
支持向量附加任何JSON格式的payload，允许基于这些payload的值进行存储和过滤。
payload支持多种数据类型和查询条件，包括关键词匹配、全文过滤、数值范围、地理位置等。

快速开始（Docker）#

1. 获取并运行Docker镜像#

1
# 拉取最新的预构建镜像
2
docker pull qdrant/qdrant
3

4
# 使用默认配置运行
5
docker run -p 6333:6333 qdrant/qdrant

运行后，Qdrant将在默认端口6333上可访问，并使用默认配置。数据将存储在docker容器内的默认路径中。如果要将数据持久化到本地目录，可以挂载卷。

2. 创建集合#

首先创建一个使用点积（Dot Product）相似度度量的集合：

1
curl -X PUT 'http://localhost:6333/collections/test_collection' \
2
-H 'Content-Type: application/json' \
3
--data-raw '{
4
  "vectors": {
5
    "size": 4,
6
    "distance": "Dot"
7
  }
8
}'

预期响应：

1
{
2
  "result": true,
3
  "status": "ok",
4
  "time": 0.031095451
5
}

3. 添加向量点#

向集合中添加包含向量和payload的点：

1
curl -L -X PUT 'http://localhost:6333/collections/test_collection/points?wait=true' \
2
-H 'Content-Type: application/json' \
3
--data-raw '{
4
  "points": [
5
    {"id": 1, "vector": [0.05, 0.61, 0.76, 0.74], "payload": {"city": "Berlin"}},
6
    {"id": 2, "vector": [0.19, 0.81, 0.75, 0.11], "payload": {"city": ["Berlin", "London"] }},
7
    {"id": 3, "vector": [0.36, 0.55, 0.47, 0.94], "payload": {"city": ["Berlin", "Moscow"] }},
8
    {"id": 4, "vector": [0.18, 0.01, 0.85, 0.80], "payload": {"city": ["London", "Moscow"] }},
9
    {"id": 5, "vector": [0.24, 0.18, 0.22, 0.44], "payload": {"count": [0] }},
10
    {"id": 6, "vector": [0.35, 0.08, 0.11, 0.44]}
11
  ]
12
}'

4. 基本向量搜索#

执行简单的向量相似度搜索，返回与查询向量最相似的3个点：

1
curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
2
-H 'Content-Type: application/json' \
3
--data-raw '{
4
  "vector": [0.2, 0.1, 0.9, 0.7],
5
  "limit": 3
6
}'

预期响应：

1
{
2
  "result": [
3
    {
4
      "id": 4,
5
      "score": 1.362
6
    },
7
    {
8
      "id": 1,
9
      "score": 1.273
10
    },
11
    {
12
      "id": 3,
13
      "score": 1.208
14
    }
15
  ],
16
  "status": "ok",
17
  "time": 0.000055785
18
}

5. 使用过滤条件的向量搜索#

通过添加过滤条件，可以限制搜索结果仅包含符合特定条件的点：

1
curl -L -X POST 'http://localhost:6333/collections/test_collection/points/search' \
2
-H 'Content-Type: application/json' \
3
--data-raw '{
4
  "filter": {
5
    "should": [
6
      {
7
        "key": "city",
8
        "match": {
9
          "value": "London"
10
        }
11
      }
12
    ]
13
  },
14
  "vector": [0.2, 0.1, 0.9, 0.7],
15
  "top": 3
16
}'

使用Python客户端#

Qdrant提供了多种客户端库，其中Python客户端提供了同步和异步请求的类型定义，以及一些便捷的辅助方法。

安装#

1
pip install qdrant-client

创建集合#

1
from qdrant_client import QdrantClient
2
from qdrant_client.http.models import Distance, VectorParams
3

4
client = QdrantClient("localhost", port=6333)
5
client.recreate_collection(
6
    collection_name="test_collection",
7
    vectors_config=VectorParams(size=4, distance=Distance.DOT),
8
)

添加点#

1
from qdrant_client.http.models import PointStruct
2

3
client.upsert(
4
    collection_name="test_collection",
5
    wait=True,
6
    points=[
7
        PointStruct(id=1, vector=[0.05, 0.61, 0.76, 0.74], payload={"city": "Berlin"}),
8
        PointStruct(id=2, vector=[0.19, 0.81, 0.75, 0.11], payload={"city": ["Berlin", "London"]}),
9
        PointStruct(id=3, vector=[0.36, 0.55, 0.47, 0.94], payload={"city": ["Berlin", "Moscow"]}),
10
        PointStruct(id=4, vector=[0.18, 0.01, 0.85, 0.80], payload={"city": ["London", "Moscow"]}),
11
        PointStruct(id=5, vector=[0.24, 0.18, 0.22, 0.44], payload={"count": [0]}),
12
        PointStruct(id=6, vector=[0.35, 0.08, 0.11, 0.44])
13
    ]
14
)

搜索#

1
search_result = client.search(
2
    collection_name="test_collection",
3
    query_vector=[0.2, 0.1, 0.9, 0.7],
4
    limit=3
5
)

内存模式（适用于开发和测试）#

Python客户端允许在不运行Qdrant服务器的情况下以本地模式运行相同的代码：

1
from qdrant_client import QdrantClient
2

3
# 使用内存模式，适用于开发和原型设计
4
client = QdrantClient(":memory:")
5

6
# 或者持久化到磁盘
7
# client = QdrantClient(path="path/to/db")

生产环境配置#

在生产环境中，可以通过配置文件覆盖默认设置。默认配置文件位于config/config.yaml，在生产环境中可以通过在docker容器内提供/qdrant/config/production.yaml来覆盖值。

在真正的生产环境中，应通过设置service.apiKey启用身份验证。对于生产环境，还应考虑设置--read-only和--user=1000:2000以进一步保护Qdrant实例。或者使用Helm图表或Qdrant Cloud，它们默认设置这些值。

使用自定义配置运行Docker：

1
docker run -p 6333:6333 \
2
-v $(pwd)/path/to/data:/qdrant/storage \
3
-v $(pwd)/path/to/custom_config.yaml:/qdrant/config/production.yaml \
4
qdrant/qdrant