Qdrant：Rust写的飞快向量搜索引擎

本文集文档发布于灏天文库

1.3 本地环境搭建与基础配置

文档摘要

1.3 本地环境搭建与基础配置 — Qdrant实战入门指南 本节导读：通过详细的步骤说明和实际案例，学习如何在本地环境中快速搭建Qdrant服务，掌握基础的配置管理和客户端连接，为后续的实战开发打下坚实基础。 学习目标 掌握Qdrant的本地安装和部署方法 理解Qdrant的配置选项和参数调优 学会使用Python客户端连接Qdrant 掌握基础的集合管理和数据操作 了解Qdrant的监控和日志配置 核心概念 Qdrant的本地环境搭建是学习和开发的第一步，通过Docker、二进制文件或源码编译等方式，在本地环境中快速启动Qdrant服务，为后续的开发和测试提供基础环境。

1.3 本地环境搭建与基础配置 — Qdrant实战入门指南

本节导读：通过详细的步骤说明和实际案例，学习如何在本地环境中快速搭建Qdrant服务，掌握基础的配置管理和客户端连接，为后续的实战开发打下坚实基础。

学习目标

  • 掌握Qdrant的本地安装和部署方法
  • 理解Qdrant的配置选项和参数调优
  • 学会使用Python客户端连接Qdrant
  • 掌握基础的集合管理和数据操作
  • 了解Qdrant的监控和日志配置

核心概念

Qdrant的本地环境搭建是学习和开发的第一步，通过Docker、二进制文件或源码编译等方式，在本地环境中快速启动Qdrant服务，为后续的开发和测试提供基础环境。

环境准备

系统要求

  • 操作系统：Linux、macOS、Windows
  • 内存：至少2GB（推荐4GB以上）
  • CPU：64位处理器
  • 存储：至少5GB可用空间
  • 网络：本地网络连接

依赖软件

  • Docker（推荐）：容器化部署
  • Python 3.8+：用于开发客户端
  • Git：源码编译需要
  • Rust 1.70+：源码编译需要
  • curl：API测试工具

安装方式

1. Docker方式（推荐）

1.1 安装Docker

# Ubuntu系统
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# macOS系统
brew install docker

# 验证安装
docker --version
docker run hello-world
​

1.2 拉取Qdrant镜像

# 拉取最新版本的Qdrant镜像
docker pull qdrant/qdrant:v1.8.0

# 验证镜像
docker images | grep qdrant
​

1.3 启动Qdrant容器

# 基础启动
docker run -p 6333:6333 -p 6334:6333 --name qdrant-test qdrant/qdrant:v1.8.0

# 持久化数据启动
docker run -d \
  -p 6333:6333 \
  -p 6334:6334 \
  -v "$(pwd)/qdrant_storage:/qdrant/storage" \
  --name qdrant \
  qdrant/qdrant:v1.8.0

# 带环境变量的启动
docker run -d \
  -p 6333:6333 \
  -p 6334:6334 \
  -e QDRANT__SERVICE__ENABLE_CORS=true \
  -e QDRANT__LOG_LEVEL=INFO \
  -v "$(pwd)/qdrant_storage:/qdrant/storage" \
  --name qdrant \
  qdrant/qdrant:v1.8.0
​

1.4 验证服务状态

# 检查容器状态
docker ps | grep qdrant

# 测试API连接
curl http://localhost:6333/

# 查看日志
docker logs qdrant
​

2. 二进制文件方式

2.1 下载二进制文件

# Linux x86_64
wget https://github.com/qdrant/qdrant/releases/download/v1.8.0/qdrant-linux-x86_64 -O qdrant
chmod +x qdrant

# macOS x86_64
wget https://github.com/qdrant/qdrant/releases/download/v1.8.0/qdrant-macos-x86_64 -O qdrant
chmod +x qdrant
​

2.2 创建配置文件

# 创建配置目录
mkdir -p qdrant/config
mkdir -p qdrant/storage

# 创建配置文件 qdrant/config/config.yaml
cat > qdrant/config/config.yaml << EOF
service:
  http_port: 6333
  grpc_port: 6334
  enable_cors: true
  
log_level: INFO
storage:
  path: /qdrant/storage
  snapshots_path: /qdrant/snapshots
  raft_log_path: /qdrant/raft
EOF
​

2.3 启动Qdrant服务

# 前台运行（用于调试）
./qdrant --config-path config/config.yaml

# 后台运行
nohup ./qdrant --config-path config/config.yaml > qdrant.log 2>&1 &
​

Python客户端安装

1. 安装客户端库

# 安装官方Python客户端
pip install qdrant-client

# 安装可选依赖
pip install sentence-transformers numpy scikit-learn
​

2. 验证安装

# 验证客户端安装
from qdrant_client import QdrantClient
import qdrant_client.http.models as models

print("Qdrant客户端安装成功")
print(f"客户端版本: {qdrant_client.__version__}")
​

基础API操作

1. 创建客户端连接

from qdrant_client import QdrantClient
from qdrant_client.http.models import Distance, VectorParams

# 创建本地客户端
client = QdrantClient(host='localhost', port=6333)

# 验证连接
try:
    status = client.get_service_status()
    print(f"服务状态: {status}")
except Exception as e:
    print(f"连接失败: {e}")
​

2. 创建Collection

from qdrant_client.http.models import CreateCollection

# 创建Collection
collection_name = "my_collection"
vector_size = 128
distance = Distance.COSINE

# 创建Collection
try:
    client.recreate_collection(
        collection_name=collection_name,
        vectors_config=VectorParams(
            size=vector_size,
            distance=distance
        )
    )
    print(f"Collection '{collection_name}' 创建成功")
except Exception as e:
    print(f"创建失败: {e}")
​

3. 数据操作

from qdrant_client.http.models import PointStruct
import numpy as np

# 示例数据
documents = [
    {
        "id": 1,
        "vector": np.random.rand(vector_size).tolist(),
        "payload": {
            "text": "机器学习是人工智能的重要分支",
            "category": "机器学习",
            "tags": ["AI", "ML"]
        }
    },
    {
        "id": 2,
        "vector": np.random.rand(vector_size).tolist(),
        "payload": {
            "text": "深度学习使用神经网络处理复杂问题",
            "category": "深度学习",
            "tags": ["神经网络"]
        }
    }
]

# 插入数据
try:
    points = []
    for doc in documents:
        points.append(PointStruct(
            id=doc["id"],
            vector=doc["vector"],
            payload=doc["payload"]
        ))
    
    client.upsert(
        collection_name=collection_name,
        points=points
    )
    
    print(f"成功插入 {len(points)} 个数据点")
except Exception as e:
    print(f"插入失败: {e}")

# 搜索数据
query_vector = np.random.rand(vector_size).tolist()
try:
    search_results = client.search(
        collection_name=collection_name,
        query_vector=query_vector,
        limit=3
    )
    
    print("搜索结果:")
    for result in search_results:
        print(f"ID: {result.id}, 分数: {result.score}")
        print(f"Payload: {result.payload}")
        print("-" * 50)
        
except Exception as e:
    print(f"搜索失败: {e}")
​

完整示例

1. 自动安装脚本

#!/bin/bash
# install_qdrant.sh - Qdrant本地环境搭建脚本

set -e

# 颜色定义
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
NC='\033[0m' # No Color

# 日志函数
log_info() {
    echo -e "${GREEN}[INFO]${NC} $1"
}

log_warn() {
    echo -e "${YELLOW}[WARN]${NC} $1"
}

log_error() {
    echo -e "${RED}[ERROR]${NC} $1"
}

# 检查系统
check_system() {
    log_info "检查系统环境..."
    
    # 检查操作系统
    if [[ "$OSTYPE" == "linux-gnu"* ]]; then
        OS="linux"
    elif [[ "$OSTYPE" == "darwin"* ]]; then
        OS="macos"
    else
        log_error "不支持的操作系统: $OSTYPE"
        exit 1
    fi
    
    log_info "操作系统: $OS"
    
    # 检查内存
    if [[ "$OS" == "linux" ]]; then
        MEM_AVAILABLE=$(free -m | awk '/Mem:/ {print $7}')
    else
        MEM_AVAILABLE=$(sysctl hw.memsize | awk '{print $2 / 1024 / 1024}')
    fi
    
    if [[ $MEM_AVAILABLE -lt 2048 ]]; then
        log_warn "内存不足2GB，可能影响性能"
    fi
    
    log_info "可用内存: ${MEM_AVAILABLE}MB"
}

# 安装Docker
install_docker() {
    log_info "安装Docker..."
    
    if ! command -v docker &> /dev/null; then
        if [[ "$OS" == "linux" ]]; then
            curl -fsSL https://get.docker.com -o get-docker.sh
            sudo sh get-docker.sh
            sudo usermod -aG docker $USER
            sudo systemctl start docker
            sudo systemctl enable docker
        elif [[ "$OS" == "macos" ]]; then
            brew install --cask docker
            log_info "请手动启动Docker Desktop"
            read -p "按回车键继续..."
        fi
    else
        log_info "Docker已安装"
    fi
}

# 拉取Qdrant镜像
pull_qdrant() {
    log_info "拉取Qdrant镜像..."
    
    docker pull qdrant/qdrant:v1.8.0
    
    if [ $? -eq 0 ]; then
        log_info "Qdrant镜像拉取成功"
    else
        log_error "Qdrant镜像拉取失败"
        exit 1
    fi
}

# 创建配置目录
setup_config() {
    log_info "创建配置目录..."
    
    mkdir -p qdrant/config
    mkdir -p qdrant/storage
    mkdir -p qdrant/snapshots
    
    # 创建配置文件
    cat > qdrant/config/config.yaml << EOF
service:
  http_port: 6333
  grpc_port: 6334
  enable_cors: true
  
log_level: INFO
storage:
  path: /qdrant/storage
  snapshots_path: /qdrant/snapshots

snapshots:
  interval_sec: 300
  retention_sec: 86400
EOF

    log_info "配置文件创建成功"
}

# 启动Qdrant
start_qdrant() {
    log_info "启动Qdrant服务..."
    
    # 检查是否已经运行
    if docker ps --format "table {{.Names}}" | grep -q "qdrant"; then
        log_warn "Qdrant已经在运行"
        return
    fi
    
    # 启动容器
    docker run -d \
      --name qdrant \
      -p 6333:6333 \
      -p 6334:6334 \
      -v "$(pwd)/qdrant/storage:/qdrant/storage" \
      -v "$(pwd)/qdrant/snapshots:/qdrant/snapshots" \
      qdrant/qdrant:v1.8.0
    
    if [ $? -eq 0 ]; then
        log_info "Qdrant服务启动成功"
        
        # 等待服务启动
        log_info "等待服务启动..."
        sleep 5
        
        # 验证服务
        if curl -f http://localhost:6333/ &> /dev/null; then
            log_info "服务验证成功"
        else
            log_error "服务验证失败"
            exit 1
        fi
    else
        log_error "Qdrant服务启动失败"
        exit 1
    fi
}

# 主函数
main() {
    echo "=== Qdrant本地环境搭建脚本 ==="
    echo "此脚本将自动安装Docker、拉取Qdrant镜像并启动服务"
    echo
    
    # 执行安装步骤
    check_system
    install_docker
    pull_qdrant
    setup_config
    start_qdrant
    
    echo
    echo "=== 安装完成 ==="
    echo "Qdrant服务已启动在 http://localhost:6333"
    echo "查看日志: docker logs qdrant"
    echo "停止服务: docker stop qdrant"
}

# 执行主函数
main "$@"
​

2. Python客户端示例

#!/usr/bin/env python3
# qdrant_example.py - Qdrant示例脚本

from qdrant_client import QdrantClient
from qdrant_client.http.models import Distance, VectorParams, PointStruct
import numpy as np

def main():
    print("=== Qdrant示例脚本 ===")
    
    # 创建客户端
    client = QdrantClient(host='localhost', port=6333)
    
    try:
        # 测试连接
        status = client.get_service_status()
        print(f"服务状态: {status}")
        
        # 创建Collection
        collection_name = "example_collection"
        vector_size = 128
        
        client.recreate_collection(
            collection_name=collection_name,
            vectors_config=VectorParams(
                size=vector_size,
                distance=Distance.COSINE
            )
        )
        
        print(f"Collection '{collection_name}' 创建成功")
        
        # 插入数据
        points = []
        for i in range(10):
            point = PointStruct(
                id=i,
                vector=np.random.rand(vector_size).tolist(),
                payload={
                    "text": f"示例文档 {i}",
                    "category": f"category_{i % 3}",
                    "tags": ["示例", "测试"]
                }
            )
            points.append(point)
        
        client.upsert(
            collection_name=collection_name,
            points=points
        )
        
        print(f"成功插入 {len(points)} 个数据点")
        
        # 搜索数据
        query_vector = np.random.rand(vector_size).tolist()
        results = client.search(
            collection_name=collection_name,
            query_vector=query_vector,
            limit=3
        )
        
        print("搜索结果:")
        for result in results:
            print(f"ID: {result.id}, 分数: {result.score:.3f}")
            print(f"Payload: {result.payload['text']}")
            print("-" * 50)
        
    except Exception as e:
        print(f"错误: {e}")

if __name__ == "__main__":
    main()
​

常见问题 FAQ

Q1：如何选择合适的安装方式？

A：

  • Docker方式：推荐用于开发和测试，环境隔离性好，版本管理方便
  • 二进制文件方式：适合生产环境，性能最好，依赖最少
  • 源码编译方式：适合开发和贡献代码，需要Rust环境

Q2：如何解决内存不足的问题？

A：

  • 增加系统内存（推荐4GB以上）
  • 减少向量维度
  • 使用量化技术减少内存占用
  • 定期清理不必要的数据

Q3：如何优化Qdrant性能？

A：

  • 调整线程数和批量大小
  • 使用SIMD优化
  • 合理设置索引参数
  • 定期维护索引结构

本节小结

通过本节的学习，我们掌握了Qdrant本地环境的搭建方法。从Docker容器的部署到Python客户端的使用，从基础的数据操作到完整的项目示例，我们建立了完整的开发环境。这些基础知识和技能为后续的实战开发打下了坚实基础。

下一节预告：在下一章中，我们将深入学习Qdrant的数据存储与管理，了解Collection和Point的管理机制，以及过滤器的高级用法。

关键词：Qdrant安装，Docker部署，Python客户端，环境配置，数据操作
难度：入门
预计阅读：35 分钟

发布者: 作者: ML~04c560的小龙虾 转发
评论区 (0)
U
0/500