这份 Qdrant 速查表汇集常用命令、REST 与 gRPC 客户端调用、过滤器、快照、集群操作和环境变量写法，方便在终端旁快速查阅。具体原理与完整步骤见本系列相应章节。

原文以 Qdrant v1.18.x 为测试范围。脚本中的 ${QDRANT_VERSION} 需要先明确设置；原文提供的版本查询命令为 curl -s https://api.github.com/repos/qdrant/qdrant/releases/latest | jq -r .tag_name。生产部署应先确认兼容版本并固定标签，不要未经验证自动跟随最新版本。

端口、默认值和关键路径

使用 Docker 运行

下面的快速示例持久化数据、发布两个端口，并配置自动重启。未限制地址的 -p 会发布到所有接口，应先按自己的环境收紧网络范围。

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  --restart unless-stopped \
  qdrant/qdrant

通过环境变量设置 API 密钥。任何超出受控本机环境的访问还应配置 TLS、访问边界与代理：

docker run -d --name qdrant \
  -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  -e QDRANT__SERVICE__API_KEY="$(openssl rand -base64 32)" \
  --restart unless-stopped \
  qdrant/qdrant

GPU 镜像用于受支持版本和配置中的索引加速，不是使用 Qdrant 的必要条件：

docker run -d --name qdrant \
  --gpus all \
  -p 6333:6333 -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage:z" \
  qdrant/qdrant:${QDRANT_VERSION}-gpu-nvidia

Docker Compose 示例

以下配置包含持久化目录、从环境变量读取的密钥和内存限制。实际生产还应配置资源余量、备份、TLS 与健康检查，不能只凭这几项就认定已完成生产部署。

services:
  qdrant:
    image: qdrant/qdrant:${QDRANT_VERSION}  # https://github.com/qdrant/qdrant/releases
    container_name: qdrant
    restart: unless-stopped
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage:/qdrant/storage:z
      - ./qdrant_snapshots:/qdrant/snapshots:z
    environment:
      QDRANT__SERVICE__API_KEY: ${QDRANT_API_KEY}
    deploy:
      resources:
        limits:
          memory: 4G

原生安装命令

原生安装的 systemd 服务

将以下 unit 保存到 /etc/systemd/system/qdrant.service。原文写成 /etc/qdrant/qdrant.service，该目录不是 systemd 默认的系统 unit 搜索位置；若使用它，必须另行链接，直接采用标准路径更清楚。

# /etc/systemd/system/qdrant.service
[Unit]
Description=Qdrant Vector Database
After=network.target

[Service]
Type=simple
User=qdrant
Group=qdrant
ExecStart=/usr/bin/qdrant --config-path /etc/qdrant/config.yaml
Restart=on-failure
RestartSec=5
LimitNOFILE=65536

[Install]
WantedBy=multi-user.target

创建用户与数据目录，再加载并启用服务：

sudo useradd -r -s /sbin/nologin qdrant
sudo mkdir -p /var/lib/qdrant/storage /etc/qdrant
sudo chown -R qdrant:qdrant /var/lib/qdrant
sudo systemctl daemon-reload
sudo systemctl enable --now qdrant
sudo systemctl status qdrant

存活、就绪与版本检查

分别检查进程存活、服务就绪和版本信息：

# Liveness
curl -s http://localhost:6333/healthz

# Readiness (returns 200 only when collections are loaded)
curl -s http://localhost:6333/readyz

# Telemetry / version
curl -s http://localhost:6333/telemetry | jq '.app.version'

集合：创建、列出、查看与删除

集合是点数据的顶层组织单元：

# Create a collection (768-dim, cosine distance)
curl -X PUT http://localhost:6333/collections/articles \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 768,
      "distance": "Cosine"
    }
  }'

# List
curl -s http://localhost:6333/collections -H "api-key: $QDRANT_API_KEY"

# Get config and stats
curl -s http://localhost:6333/collections/articles -H "api-key: $QDRANT_API_KEY"

# Delete
curl -X DELETE http://localhost:6333/collections/articles -H "api-key: $QDRANT_API_KEY"

创建包含稠密与稀疏命名向量的集合，供混合搜索使用：

curl -X PUT http://localhost:6333/collections/articles \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "dense": {"size": 768, "distance": "Cosine"}
    },
    "sparse_vectors": {
      "bm25": {}
    }
  }'

点：写入、读取、删除与遍历

Upsert、删除、scroll 和 count 均位于集合的 points 路径下：

# Upsert with payload
curl -X PUT http://localhost:6333/collections/articles/points \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "points": [
      {
        "id": 1,
        "vector": [0.1, 0.2, 0.3, "..."],
        "payload": {"title": "Qdrant Guide", "tags": ["ai", "vector"]}
      }
    ]
  }'

# Get by ID
curl -s http://localhost:6333/collections/articles/points/1 -H "api-key: $QDRANT_API_KEY"

# Delete by ID
curl -X POST http://localhost:6333/collections/articles/points/delete \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"points": [1, 2, 3]}'

# Scroll (paginate through all points)
curl -X POST http://localhost:6333/collections/articles/points/scroll \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit": 100, "with_payload": true, "with_vector": false}'

# Count
curl -X POST http://localhost:6333/collections/articles/points/count \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"exact": true}'

搜索与现代查询 API

旧 /search 在相应版本中仍可使用，新代码优先采用 /query，以支持预取、混合检索和重评分：

# Basic search
curl -X POST http://localhost:6333/collections/articles/points/search \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vector": [0.1, 0.2, 0.3, "..."],
    "limit": 10,
    "with_payload": true
  }'

# Modern query_points (v1.10+) with prefetch + filter
curl -X POST http://localhost:6333/collections/articles/points/query \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": [0.1, 0.2, 0.3, "..."],
    "limit": 10,
    "filter": {
      "must": [{"key": "tags", "match": {"value": "ai"}}]
    }
  }'

# Recommend (positives and negatives)
curl -X POST http://localhost:6333/collections/articles/points/recommend \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "positive": [1, 5],
    "negative": [99],
    "limit": 10
  }'

过滤语法速查

最后一行是嵌套路径匹配，不等同于 nested 条件。需要数组内同一个对象同时满足多个条件时，应使用真正的 nested 过滤结构。

使用 must、should、must_not 组合条件；should 要求至少一项成立，不会自动加分。为经常过滤的高选择性关键词字段建立载荷索引，并考虑写入与内存成本。

# Create a payload index (one-time, per field)
curl -X PUT http://localhost:6333/collections/articles/index \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"field_name": "tags", "field_schema": "keyword"}'

快照：创建、列出与恢复

集合快照可通过相应端点创建、列出、下载和恢复：

# Create a collection snapshot
curl -X POST http://localhost:6333/collections/articles/snapshots \
  -H "api-key: $QDRANT_API_KEY"

# List
curl -s http://localhost:6333/collections/articles/snapshots -H "api-key: $QDRANT_API_KEY"

# Download
curl -OJ http://localhost:6333/collections/articles/snapshots/<snapshot-name> \
  -H "api-key: $QDRANT_API_KEY"

# Restore from URL
curl -X PUT http://localhost:6333/collections/articles/snapshots/recover \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"location": "http://backups.example.com/articles.snapshot"}'

# Restore from upload (multipart)
curl -X POST http://localhost:6333/collections/articles/snapshots/upload \
  -H "api-key: $QDRANT_API_KEY" \
  -F "snapshot=@articles.snapshot"

# Full storage snapshot (single node only)
curl -X POST http://localhost:6333/snapshots -H "api-key: $QDRANT_API_KEY"

支持 S3 快照后端的版本可以在 config.yaml 配置对象存储。它用于快照，不能用来替代实时 segment 数据所在的本地或块存储文件系统。

storage:
  snapshots_config:
    snapshots_storage: s3
    s3_config:
      bucket: my-qdrant-snapshots
      region: eu-central-1
      access_key: AKIA...
      secret_key: ...
      endpoint_url: https://s3.eu-central-1.amazonaws.com

集群操作

集群模式启用 Raft、分片与跨节点复制。先在配置中启用：

# Enable cluster mode in config.yaml
cluster:
  enabled: true
  p2p:
    port: 6335
  consensus:
    tick_period_ms: 100

启动首节点，再使用 --bootstrap 指向已有 peer 加入其余节点：

# Bootstrap node 1 (first in the cluster)
qdrant --config-path /etc/qdrant/config.yaml --uri http://node1:6335

# Join nodes 2 and 3
qdrant --config-path /etc/qdrant/config.yaml \
  --bootstrap http://node1:6335 \
  --uri http://node2:6335

# Cluster status
curl -s http://localhost:6333/cluster -H "api-key: $QDRANT_API_KEY"

# Create collection with sharding and replication
curl -X PUT http://localhost:6333/collections/articles \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {"size": 768, "distance": "Cosine"},
    "shard_number": 6,
    "replication_factor": 2,
    "write_consistency_factor": 1
  }'

# Move a shard between peers
curl -X POST http://localhost:6333/collections/articles/cluster \
  -H "api-key: $QDRANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "move_shard": {
      "shard_id": 0,
      "from_peer_id": 1,
      "to_peer_id": 3
    }
  }'

Helm 常用命令

官方 chart 为各 Pod 创建 StatefulSet 身份与 PVC。添加仓库，再按拓扑调整副本数、存储与认证：

helm repo add qdrant https://qdrant.github.io/qdrant-helm
helm repo update

# Single node
helm install qdrant qdrant/qdrant \
  --namespace qdrant --create-namespace \
  --set apiKey=$(openssl rand -base64 32)

# 3 node cluster with persistence
helm install qdrant qdrant/qdrant \
  --namespace qdrant --create-namespace \
  --set replicaCount=3 \
  --set config.cluster.enabled=true \
  --set persistence.size=50Gi \
  --set apiKey=$(openssl rand -base64 32)

# Upgrade
helm upgrade qdrant qdrant/qdrant -n qdrant -f values.yaml

Python 客户端示例

qdrant-client 提供集合、点与查询等接口，并可选择 REST 或 gRPC。下面是入门示例：

from qdrant_client import QdrantClient
from qdrant_client.models import (
    Distance, VectorParams, PointStruct,
    Filter, FieldCondition, MatchValue, Range,
)

client = QdrantClient(url="http://localhost:6333", api_key="...")

# Create
client.create_collection(
    collection_name="articles",
    vectors_config=VectorParams(size=768, distance=Distance.COSINE),
)

# Upsert
client.upsert(
    collection_name="articles",
    points=[
        PointStruct(id=1, vector=[0.1] * 768, payload={"title": "Qdrant Guide"}),
    ],
)

# Search with filter
hits = client.query_points(
    collection_name="articles",
    query=[0.1] * 768,
    query_filter=Filter(
        must=[FieldCondition(key="title", match=MatchValue(value="Qdrant Guide"))]
    ),
    limit=10,
    with_payload=True,
).points

# Create payload index
client.create_payload_index(
    collection_name="articles",
    field_name="title",
    field_schema="keyword",
)

# Snapshot
client.create_snapshot(collection_name="articles")

配置环境变量的命名规则

配置可通过 QDRANT__SECTION__KEY 覆盖，使用两个下划线区分嵌套层级。

Web UI 路径

具体版本可能将 hash 路由呈现为 /dashboard/#/...，应以已安装 Web UI 的实际导航为准。

常见问题

• 将 NFS 或对象存储当成实时数据目录。 Qdrant 数据存储需要受支持的本地或块设备文件系统语义；不要把 S3 快照后端混同为实时数据库后端。Kubernetes 中应核对 CSI 存储类型与性能要求。
• 先启用 JWT 却没有主 API 密钥。 密钥用于签名与验证 JWT，先配置 QDRANT__SERVICE__API_KEY，再启用 jwt_rbac，令牌还应明确限定 access。
• 过滤字段缺少索引。 查询可能仍能工作，但需要更多扫描或载荷检查。为高频、高选择性字段创建适当索引。
• 二进制量化关闭重评分。 可能降低召回率，但不能把原文的 5% 至 10% 当成统一规律，应按模型、数据分布和检索参数测量。
• 从 S3 恢复的路径不明确。 应区分已配置原生 S3 快照后端与通用恢复接口。外部工具上传的私有 S3 对象，通常需要先下载，再按目标版本支持的本地文件、上传或可访问 HTTP 方式恢复；不能把裸私有 S3 地址当成必然可用的 location。
• 仅有两个 Raft 节点。 多数派需要超过一半，两个节点失去一个就无法形成多数派。跨节点容错常用三或五个共识节点，并结合分片副本与写确认策略。
• 默认 Docker 示例未启用认证或 TLS。 公开端口会增加暴露面，实际部署应限制监听和网络访问，启用密钥并配置 TLS。

赞赏