grepai-storage-qdrant

使用 Qdrant 存储 GrepAI

此技能介绍如何将 Qdrant 用作 GrepAI 的存储后端，提供高性能向量搜索。

何时使用此技能

• 需要尽可能快的搜索性能
• 代码库非常庞大（50K+ 个文件）
• 已在使用 Qdrant 基础设施
• 需要高级向量搜索功能

什么是 Qdrant？

Qdrant 是专为此用途构建的向量数据库，提供：

• ⚡ 极快的向量相似度搜索
• 📏 出色的可扩展性
• 🔧 高级筛选功能
• 🐳 轻松通过 Docker 部署

前提条件

1. 正在运行的 Qdrant 服务
2. 可访问 Qdrant 的网络

优势

优势	说明
⚡ 性能	最快的向量搜索
📏 可扩展性	可处理数百万个向量
🔍 高级功能	筛选、负载数据、分片
🐳 易于部署	已适配 Docker
☁️ 云选项	提供 Qdrant Cloud

设置 Qdrant

选项 1：Docker（推荐）

# Run Qdrant with persistent storage
docker run -d \
  --name grepai-qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

端口：

• 6333：REST API
• 6334：gRPC API（GrepAI 使用）

选项 2：Docker Compose

# docker-compose.yml
version: '3.8'
services:
  qdrant:
    image: qdrant/qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_storage:/qdrant/storage
    environment:
      - QDRANT__SERVICE__GRPC_PORT=6334

volumes:
  qdrant_storage:

docker-compose up -d

选项 3：Qdrant Cloud

1. 在 cloud.qdrant.io 注册
2. 创建集群
3. 获取端点和 API 密钥

配置

基本配置（本地）

# .grepai/config.yaml
store:
  backend: qdrant
  qdrant:
    endpoint: localhost
    port: 6334

使用 TLS（生产环境）

store:
  backend: qdrant
  qdrant:
    endpoint: qdrant.company.com
    port: 6334
    use_tls: true

使用 API 密钥（Qdrant Cloud）

store:
  backend: qdrant
  qdrant:
    endpoint: your-cluster.aws.cloud.qdrant.io
    port: 6334
    use_tls: true
    api_key: ${QDRANT_API_KEY}

设置环境变量：

export QDRANT_API_KEY="your-api-key"

配置选项

选项	默认值	说明
endpoint	localhost	Qdrant 服务主机名
port	6334	gRPC 端口
use_tls	false	启用 TLS 加密
api_key	none	身份验证密钥

验证设置

检查 Qdrant 是否正在运行

# REST API health check
curl http://localhost:6333/health

# Expected: {"status":"ok"}

检查集合（索引完成后）

# List collections
curl http://localhost:6333/collections

# Get collection info
curl http://localhost:6333/collections/grepai

在 GrepAI 中检查

grepai status

# Should show Qdrant backend info

Qdrant 控制面板

通过 http://localhost:6333/dashboard 访问 Web 控制面板：

• 查看集合
• 浏览向量
• 执行查询
• 监控性能

性能特征

搜索延迟

代码库规模	向量数	搜索时间
小型（1K 个文件）	5,000	<10ms
中型（10K 个文件）	50,000	<20ms
大型（100K 个文件）	500,000	<50ms

内存用量

Qdrant 会将向量加载到内存中，以实现快速搜索：

向量数	维度	内存
10,000	768	~60 MB
100,000	768	~600 MB
1,000,000	768	~6 GB

高级配置

Qdrant 服务配置

创建 config/production.yaml：

storage:
  storage_path: /qdrant/storage

service:
  grpc_port: 6334
  http_port: 6333
  max_request_size_mb: 32

optimizers:
  memmap_threshold_kb: 200000
  indexing_threshold_kb: 50000

在 Docker 中挂载：

docker run -d \
  -v ./config:/qdrant/config \
  -v qdrant_storage:/qdrant/storage \
  qdrant/qdrant

集合设置

GrepAI 会创建名为 grepai 的集合，设置如下：

• 向量大小：与嵌入维度匹配
• 距离：余弦相似度
• 大型数据集使用磁盘存储

集群（高级）

对于超大型部署，Qdrant 支持分布式模式：

# qdrant config
cluster:
  enabled: true
  p2p:
    port: 6335

备份与恢复

创建快照

# Create snapshot via REST API
curl -X POST 'http://localhost:6333/collections/grepai/snapshots'

恢复快照

# Restore from snapshot
curl -X PUT 'http://localhost:6333/collections/grepai/snapshots/recover' \
  -H 'Content-Type: application/json' \
  -d '{"location": "/path/to/snapshot"}'

从 GOB 迁移

1. 启动 Qdrant：

docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant

2. 更新配置：

store:
  backend: qdrant
  qdrant:
    endpoint: localhost
    port: 6334

3. 删除旧索引：

rm .grepai/index.gob

4. 重新建立索引：

grepai watch

从 PostgreSQL 迁移

1. 启动 Qdrant
2. 更新配置以使用 Qdrant
3. 重新建立索引（必须重新生成嵌入）

常见问题

❌ 问题： 连接被拒绝
✅ 解决方案： 确保 Qdrant 正在运行：

docker ps | grep qdrant
docker start grepai-qdrant

❌ 问题： gRPC 连接失败
✅ 解决方案： 检查端口 6334 是否已公开：

docker run -p 6334:6334 ...

❌ 问题： 身份验证失败
✅ 解决方案： 检查 API 密钥：

echo $QDRANT_API_KEY

❌ 问题： 内存不足
✅ 解决方案：

• 在 Qdrant 配置中启用磁盘存储
• 增加 Docker 内存限制
• 使用 Qdrant Cloud 托管扩展

❌ 问题： 初始索引速度慢
✅ 解决方案： 这是正常现象；Qdrant 会在后台进行优化。索引完成后，搜索速度会很快。

Qdrant 与 PostgreSQL

特性	Qdrant	PostgreSQL
搜索速度	⚡⚡⚡	⚡⚡
设置复杂度	简单（Docker）	中等
SQL 查询	❌	✅
可扩展性	优秀	良好
内存效率	优秀	良好
团队熟悉度	较低	较高

建议： 对于大型代码库或追求最高性能，请使用 Qdrant。如果需要集成 SQL，或团队更熟悉 PostgreSQL，请使用 PostgreSQL。

最佳实践

1. 使用持久化卷： 挂载 /qdrant/storage
2. 在生产环境中启用 TLS： 设置 use_tls: true
3. 保护 API 密钥： 使用环境变量
4. 监控内存： 向量搜索会大量占用内存
5. 定期创建快照： 在重大更改前备份

输出格式

Qdrant 存储状态：

✅ Qdrant Storage Configured

   Backend: Qdrant
   Endpoint: localhost:6334
   TLS: disabled
   Collection: grepai

   Contents:
   - Files: 5,000
   - Vectors: 25,000
   - Dimensions: 768

   Performance:
   - Connection: OK
   - Indexed: Yes
   - Search latency: ~15ms