安装与配置 #

本章介绍 Qdrant 的多种安装和配置方式，从本地开发到生产部署。

安装方式概览 #

text

Qdrant 安装方式：

┌─────────────────────────────────────────────────────────────┐
│                                                              │
│  本地开发          生产部署              云服务              │
│  ┌─────────┐      ┌─────────────┐      ┌─────────────┐     │
│  │ Docker  │      │ Kubernetes  │      │ Qdrant Cloud│     │
│  │ Python  │      │ Docker Swarm│      │             │     │
│  │ Binary  │      │ 裸机部署     │      │             │     │
│  └─────────┘      └─────────────┘      └─────────────┘     │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Docker 安装（推荐） #

Docker 是最简单快捷的 Qdrant 安装方式，适合开发和测试环境。

快速启动 #

bash

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/qdrant_storage:/qdrant/storage \
    qdrant/qdrant

端口说明 #

text

端口映射：

6333 → REST API 端口
       ├── HTTP 接口
       ├── Web UI (http://localhost:6333/dashboard)
       └── 健康检查

6334 → gRPC 端口
       ├── 高性能接口
       └── 批量操作

数据持久化 #

bash

docker run -p 6333:6333 -p 6334:6334 \
    -v /path/to/data:/qdrant/storage \
    qdrant/qdrant

自定义配置 #

bash

docker run -p 6333:6333 -p 6334:6334 \
    -v $(pwd)/config/production.yaml:/qdrant/config/production.yaml \
    -v $(pwd)/storage:/qdrant/storage \
    qdrant/qdrant ./qdrant --config-path /qdrant/config/production.yaml

Docker Compose #

yaml

version: '3.8'

services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - ./qdrant_storage:/qdrant/storage
    environment:
      - QDRANT__LOG_LEVEL=INFO
    restart: unless-stopped

启动命令：

bash

docker-compose up -d

Python 内存模式 #

适合快速测试和原型开发，无需启动服务器。

安装客户端 #

bash

pip install qdrant-client

内存模式使用 #

python

from qdrant_client import QdrantClient

client = QdrantClient(":memory:")

client.create_collection(
    collection_name="test_collection",
    vectors_config={
        "size": 384,
        "distance": "Cosine"
    }
)

print("内存模式客户端已就绪")

连接本地服务器 #

python

from qdrant_client import QdrantClient

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

print(client.get_collections())

Kubernetes 部署 #

适合生产环境的大规模部署。

单节点部署 #

yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: qdrant
  labels:
    app: qdrant
spec:
  replicas: 1
  selector:
    matchLabels:
      app: qdrant
  template:
    metadata:
      labels:
        app: qdrant
    spec:
      containers:
      - name: qdrant
        image: qdrant/qdrant:latest
        ports:
        - containerPort: 6333
          name: http
        - containerPort: 6334
          name: grpc
        volumeMounts:
        - name: qdrant-storage
          mountPath: /qdrant/storage
      volumes:
      - name: qdrant-storage
        persistentVolumeClaim:
          claimName: qdrant-pvc
---
apiVersion: v1
kind: Service
metadata:
  name: qdrant
spec:
  selector:
    app: qdrant
  ports:
  - port: 6333
    name: http
    targetPort: 6333
  - port: 6334
    name: grpc
    targetPort: 6334
  type: ClusterIP

使用 Helm 部署 #

bash

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

helm install qdrant qdrant/qdrant \
    --set replicaCount=3 \
    --set persistence.size=100Gi

分布式集群配置 #

yaml

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: qdrant-cluster
spec:
  serviceName: qdrant-headless
  replicas: 3
  selector:
    matchLabels:
      app: qdrant
  template:
    metadata:
      labels:
        app: qdrant
    spec:
      containers:
      - name: qdrant
        image: qdrant/qdrant:latest
        ports:
        - containerPort: 6333
        - containerPort: 6334
        env:
        - name: QDRANT__CLUSTER__ENABLED
          value: "true"
        volumeMounts:
        - name: data
          mountPath: /qdrant/storage
  volumeClaimTemplates:
  - metadata:
      name: data
    spec:
      accessModes: ["ReadWriteOnce"]
      resources:
        requests:
          storage: 50Gi

Qdrant Cloud #

Qdrant 官方提供的托管云服务，无需运维。

创建集群 #

text

1. 访问 https://cloud.qdrant.io/
2. 注册账号
3. 创建集群：
   ├── 选择区域
   ├── 选择规格
   └── 配置网络
4. 获取连接信息

连接云实例 #

python

from qdrant_client import QdrantClient

client = QdrantClient(
    url="https://your-cluster-url.qdrant.io",
    api_key="your-api-key"
)

print(client.get_collections())

云服务优势 #

text

✅ 无需运维
✅ 自动备份
✅ 高可用保证
✅ 自动扩展
✅ 监控告警
✅ 安全合规

配置文件详解 #

Qdrant 使用 YAML 格式的配置文件。

基础配置 #

yaml

log_level: INFO

storage:
  storage_path: ./storage
  
  snapshots_path: ./snapshots
  
  on_disk_payload: true

  performance:
    max_search_threads: 4
    max_optimization_threads: 2

  wal:
    wal_capacity_mb: 32
    wal_segments_ahead: 0

  optimizers:
    deleted_threshold: 0.2
    vacuum_min_vector_count: 1000
    default_segment_number: 5
    max_segment_size_kb: 100000
    memmap_threshold_kb: 50000
    indexing_threshold_kb: 20000
    flush_interval_sec: 5
    max_optimization_threads: 2

service:
  host: 0.0.0.0
  http_port: 6333
  grpc_port: 6334
  max_request_size_mb: 32

telemetry_disabled: false

性能优化配置 #

yaml

storage:
  performance:
    max_search_threads: 8
    max_optimization_threads: 4

  optimizers:
    indexing_threshold_kb: 10000
    max_segment_size_kb: 100000
    memmap_threshold_kb: 50000

hnsw_graph:
  m: 16
  ef_construct: 100
  full_scan_threshold_kb: 10000

集群配置 #

yaml

cluster:
  enabled: true
  
  p2p:
    port: 6335
  
  consensus:
    tick_period_ms: 100
  
  collection:
    replication_factor: 2
    write_consistency_factor: 1
    read_consistency_factor: 1

安全配置 #

yaml

service:
  api_key: your-secret-api-key
  
  tls:
    cert: /path/to/cert.pem
    key: /path/to/key.pem

storage:
  snapshots_path: ./snapshots

环境变量 #

Qdrant 支持通过环境变量配置：

bash

export QDRANT__LOG_LEVEL=DEBUG
export QDRANT__SERVICE__HTTP_PORT=6333
export QDRANT__SERVICE__GRPC_PORT=6334
export QDRANT__STORAGE__STORAGE_PATH=/data/qdrant

docker run -d \
    -e QDRANT__LOG_LEVEL=INFO \
    -e QDRANT__SERVICE__API_KEY=your-api-key \
    -p 6333:6333 \
    -p 6334:6334 \
    qdrant/qdrant

客户端安装 #

Python 客户端 #

bash

pip install qdrant-client

pip install qdrant-client[fastembed]

python

from qdrant_client import QdrantClient

client = QdrantClient(
    url="http://localhost:6333",
    api_key="optional-api-key"
)

JavaScript/TypeScript 客户端 #

bash

npm install @qdrant/js-client-rest

typescript

import { QdrantClient } from '@qdrant/js-client-rest';

const client = new QdrantClient({
  url: 'http://localhost:6333',
  apiKey: 'optional-api-key'
});

Go 客户端 #

bash

go get github.com/qdrant/go-client

import "github.com/qdrant/go-client/qdrant"

client, err := qdrant.NewClient(&qdrant.Config{
    Host: "localhost",
    Port: 6334,
})

Rust 客户端 #

toml

[dependencies]
qdrant-client = "1.7"

rust

use qdrant_client::client::QdrantClient;

let client = QdrantClient::from_url("http://localhost:6334").build()?;

验证安装 #

检查服务状态 #

bash

curl http://localhost:6333/health

响应：

json

{
  "title": "qdrant - vector search engine",
  "version": "1.7.0",
  "status": "ok"
}

访问 Web UI #

text

打开浏览器访问：
http://localhost:6333/dashboard

Python 测试 #

python

from qdrant_client import QdrantClient

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

print(client.get_collections())

client.create_collection(
    collection_name="test",
    vectors_config={"size": 4, "distance": "Cosine"}
)

print("安装验证成功！")

常见问题 #

端口冲突 #

bash

修改端口映射：

docker run -p 16333:6333 -p 16334:6334 qdrant/qdrant

连接时使用新端口：
client = QdrantClient(url="http://localhost:16333")

权限问题 #

bash

修复存储目录权限：

chmod -R 755 ./qdrant_storage
chown -R 1000:1000 ./qdrant_storage

内存不足 #

yaml

调整配置减少内存使用：

storage:
  optimizers:
    indexing_threshold_kb: 5000
  performance:
    max_search_threads: 2

hnsw_graph:
  m: 8
  ef_construct: 50

小结 #

本章介绍了 Qdrant 的多种安装方式：

Docker：最简单快捷，适合开发测试
Kubernetes：生产环境推荐
Qdrant Cloud：无需运维，开箱即用
内存模式：快速原型开发

下一步 #

安装完成后，继续学习核心概念，了解 Qdrant 的数据模型！