RAG Qdrant 故障排查

# Qdrant 故障排查指南 ## 安装问题 ### Docker 问题 **错误**: `Cannot connect to Docker daemon` **修复**: bash # 启动 Docker 守护进程 sudo systemctl start docker # 或者在 Mac/Windows 上打开 Docker Desktop open -a Docker **错误**: `Port 6333 already in use` **修复**: bash # 查找占用端口的进程 lsof -i :6333 # 终止进程或使用其他端口 docker run -p 6334:6333 qdrant/qdrant ### Python 客户端问题 **错误**: `ModuleNotFoundError: No module named 'qdrant_client'` **修复**: bash pip install qdrant-client # 安装特定版本 pip install qdrant-client>=1.12.0 **错误**: `grpc._channel._InactiveRpcError` **修复**: bash # 安装支持 gRPC 的版本 pip install 'qdrant-client[grpc]' # 或者禁用 gRPC client = QdrantClient(host="localhost", port=6333, prefer_grpc=False) ## 连接问题 ### 无法连接到服务器 **错误**: `ConnectionRefusedError: [Errno 111] Connection refused` **解决方案**: 1. **检查服务器是否运行**: bash docker ps | grep qdrant curl http://localhost:6333/healthz 2. **验证端口绑定**: bash # 检查监听端口 netstat -tlnp | grep 6333 # Docker 端口映射 docker port 3. **使用正确的主机地址**: python # Linux 上的 Docker client = QdrantClient(host="localhost", port=6333) # Mac/Windows 上存在网络问题时 client = QdrantClient(host="127.0.0.1", port=6333) # Docker 网络内部 client = QdrantClient(host="qdrant", port=6333) ### 超时错误 **错误**: `TimeoutError: Connection timed out` **修复**: python # 增加超时时间 client = QdrantClient( host="localhost", port=6333, timeout=60 # 秒 ) # 对于大规模操作 client.upsert( collection_name="documents", points=large_batch, wait=False # 不等待索引完成 ) ### SSL/TLS 错误 **错误**: `ssl.SSLCertVerificationError` **修复**: python # Qdrant 云服务 client = QdrantClient( url="https://cluster.cloud.qdrant.io", api_key="your-api-key" ) # 自签名证书 client = QdrantClient( host="localhost", port=6333, https=True, verify=False # 禁用验证（不建议在生产环境使用） ) ## 集合问题 ### 集合已存在 **错误**: `ValueError: Collection 'documents' already exists` **修复**: python # 创建前检查 collections = client.get_collections().collections names = [c.name for c in collections] if "documents" not in names