用途
本技能用于把 Qdrant 配置为 GrepAI 的存储后端，以提供高性能的向量搜索。以下情形适合使用：需要尽可能快的搜索性能；代码库非常庞大（50K+ 文件）；已经在使用 Qdrant 基础设施；希望使用高级向量搜索功能。
什么是 Qdrant
Qdrant 是专为向量设计的数据库，提供：极快的向量相似度搜索、出色的可扩展性、高级过滤能力、便捷的 Docker 部署。
前置条件：Qdrant 服务已运行；具备到 Qdrant 的网络访问。
优势包括：性能（最快的向量搜索）、可扩展性（可处理数百万向量）、高级能力（过滤、payload、分片）、易部署（Docker 就绪）、云选项（提供 Qdrant Cloud）。
部署 Qdrant
方式一：Docker（推荐）。使用以下命令运行带持久化存储的 Qdrant：
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 使用）。
方式二：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
方式三：Qdrant Cloud。访问 cloud.qdrant.io 注册；创建集群；获取 endpoint 与 API key。
配置
基础配置（本地）：
.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 Key（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 默认无，为认证密钥。
验证配置
检查 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，可查看集合、浏览向量、执行查询、监控性能。
性能特征
搜索延迟（参考）：小规模（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 迁移：启动 Qdrant（docker run -d --name qdrant -p 6333:6333 -p 6334:6334 qdrant/qdrant）；更新配置为 store.backend: qdrant、endpoint: localhost、port: 6334；删除旧索引 rm .grepai/index.gob；重新索引 grepai watch。
从 PostgreSQL 迁移：启动 Qdrant；更新配置为使用 Qdrant；重新索引（嵌入必须重新生成）。
常见问题
连接被拒绝：确认 Qdrant 正在运行，执行 docker ps | grep qdrant 或 docker start grepai-qdrant。
gRPC 连接失败：检查 6334 端口是否暴露，如 docker run -p 6334:6334 ...。
认证失败：检查 API key，如 echo $QDRANT_API_KEY。
内存不足：在 Qdrant 配置中启用磁盘存储；提高 Docker 内存限制；使用 Qdrant Cloud 进行托管扩容。
初始索引缓慢：属正常现象，Qdrant 在后台优化，索引完成后搜索会很快。
Qdrant 与 PostgreSQL 对比
搜索速度：Qdrant 更强（⚡⚡⚡），PostgreSQL 为 ⚡⚡。设置复杂度：Qdrant 简单（Docker），PostgreSQL 中等。SQL 查询：Qdrant 不支持，PostgreSQL 支持。可扩展性：Qdrant 优秀，PostgreSQL 良好。内存效率：Qdrant 优秀，PostgreSQL 良好。团队熟悉度：Qdrant 较低，PostgreSQL 较高。
建议：大型代码库或追求最高性能时使用 Qdrant；如果需要 SQL 集成或团队更熟悉 PostgreSQL，则使用 PostgreSQL。
最佳实践
使用持久化卷：挂载 /qdrant/storage。生产环境启用 TLS：设置 use_tls: true。保护 API key：使用环境变量。监控内存：向量搜索对内存消耗较大。定期快照：重大变更前备份。
输出格式
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