故障排除¶
本文档提供了使用 GoVector 时可能遇到的常见问题的解决方案。它涵盖了错误消息、性能问题和其他常见问题。
🚩 常见错误消息¶
维度不匹配¶
错误：dimension mismatch
原因：向量维度与集合的配置维度不匹配。
解决方案：
- 确保所有向量的维度与集合配置相同
- 检查集合的 VectorLen 参数
- 验证您的嵌入模型是否生成正确维度的向量
内存不足¶
错误：out of memory
原因：集合对于可用内存来说太大。
解决方案：
- 启 SQ8 量化以减少约 75% 的内存使用
- 对 HNSW 索引使用较小的 M 值
- 考虑对小型数据集使用 Flat 索引
- 增加应用程序的内存分配
集合未找到¶
错误：collection not found
原因：指定的集合不存在。
解决方案： - 检查集合名称是否有拼写错误 - 验证集合是否成功创建 - 确保您使用的是正确的数据目录
点未找到¶
错误：point not found
原因：指定的点 ID 在集合中不存在。
解决方案： - 检查点 ID 是否有拼写错误 - 验证点是否成功写入 - 确保您使用的是正确的集合
📊 性能问题¶
搜索缓慢¶
症状：搜索操作比预期花费更长时间。
可能原因： - HNSW 参数不当 - 结果集过大 - 复杂的过滤器 - 磁盘 I/O 缓慢
解决方案：
- 增加 EfSearch 参数以获得更好的召回率（但搜索更慢）
- 减少 EfSearch 参数以加快搜索速度（但召回率更低）
- 使用更具选择性的过滤器以减少结果集大小
- 使用 SSD 存储以获得更好的 I/O 性能
- 启 SQ8 量化以减少内存使用
写入缓慢¶
症状：写入操作比预期花费更长时间。
可能原因：
- 批处理大小过大
- EfConstruction 参数过高
- 磁盘 I/O 缓慢
- 禁用量化
解决方案：
- 使用适当的批处理大小（每批 100-1000 个点）
- 根据数据集大小调整 EfConstruction 参数
- 使用 SSD 存储以获得更好的 I/O 性能
- 对于写入密集型工作负载，考虑禁用量化
内存使用高¶
症状：GoVector 使用的内存比预期多。
可能原因：
- 大型数据集未启量化
- HNSW 索引的 M 值过高
- 同时加载多个集合
解决方案：
- 启 SQ8 量化以减少内存使用
- 对 HNSW 索引使用较小的 M 值
- 仅加载必要的集合
- 考虑在多个实例之间进行分片
🔧 配置问题¶
度量选择错误¶
症状：搜索结果与预期相似度不匹配。
原因：距离度量与您的用例不匹配。
解决方案： - 对归一化向量使用 Cosine - 对非归一化向量使用 Euclidean - 对某些特定用例使用 Dot
索引参数¶
症状：搜索性能或召回率不佳。
原因：HNSW 索引参数未针对您的数据集进行优化。
解决方案： - 对于小型数据集（10,000-100,000 点）：M=12, EfConstruction=100 - 对于中型数据集（100,000-1,000,000 点）：M=16, EfConstruction=200 - 对于大型数据集（1,000,000+ 点）：M=24, EfConstruction=400
🛡️ 安全问题¶
未授权访问¶
症状：未授权用户可以访问 API。
原因：未配置认证。
解决方案： - 使用带有认证的反向代理 - 限制对可信客户端的网络访问 - 在生产环境中使用 HTTPS
数据泄露¶
症状：敏感数据被暴露。
原因：Payload 包含敏感信息。
解决方案： - 不要在 payload 中存储敏感信息 - 对敏感数据使用加密 - 实现适当的访问控制
💾 存储问题¶
数据损坏¶
症状：集合无法加载或返回不正确的数据。
原因：意外关闭、磁盘错误或文件损坏。
解决方案： - 从备份恢复 - 使用日志文件系统 - 实现适当的错误处理 - 定期验证数据完整性
磁盘空间问题¶
症状：磁盘空间不足。
原因：大型向量、未启量化或过多的 payload。
解决方案： - 启 SQ8 量化 - 优化 payload 大小 - 尽可能使用较小的向量 - 清理旧集合
📡 网络问题¶
连接被拒绝¶
症状：无法连接到 GoVector 服务器。
原因： - 服务器未运行 - 主机或端口不正确 - 防火墙阻止访问
解决方案： - 启动 GoVector 服务器 - 验证主机和端口配置 - 检查防火墙设置
超时¶
症状：API 请求超时。
原因： - 服务器性能缓慢 - 网络延迟 - 结果集过大
解决方案： - 优化服务器性能 - 使用适当的批处理大小 - 减少结果集大小 - 检查网络连接
❓ 常见问题¶
如何在 HNSW 和 Flat 索引之间选择？¶
答案： - 对大型数据集（10,000+ 点）使用 HNSW，其中搜索性能很重要 - 对小型数据集（< 10,000 点）使用 Flat，其中准确性至关重要
如何优化内存使用？¶
答案：
- 启 SQ8 量化
- 对 HNSW 索引使用较小的 M 值
- 仅加载必要的集合
- 考虑对小型数据集使用 Flat 索引
如何备份 GoVector 数据？¶
答案： - 定期复制数据目录 - 使用自动备份工具 - 定期测试恢复过程
如何扩展 GoVector？¶
答案： - 使用多个集合来分散负载 - 考虑在多个实例之间进行分片 - 对微服务模式使用负载均衡 - 针对您的数据集优化 HNSW 参数
如何与其他语言集成？¶
答案： - 使用带有 HTTP API 的微服务模式 - 使用现有的 Qdrant 客户端 - 为特定语言实现自定义客户端