GraphRAG项目中ZeroDivisionError问题的分析与解决

问题背景

在使用GraphRAG项目进行本地范围查询时，开发者可能会遇到一个特定的错误："ZeroDivisionError: Weights sum to zero, can't be normalized"。这个错误通常出现在使用本地嵌入模型而非全局范围查询时，表明在权重归一化过程中出现了除零错误。

错误原因分析

该错误的根本原因在于嵌入模型返回的权重格式不正确。具体来说：

1. 权重格式不匹配：OpenAI的嵌入模型默认使用base64编码的浮点数，而大多数本地模型直接返回数字形式的浮点数。这种格式差异导致了后续处理时的计算错误。

2. API配置问题：当使用非OpenAI的嵌入服务（如本地运行的Ollama或Azure OpenAI实例）时，如果API密钥无效或配置不正确，也会导致嵌入模型返回异常结果，进而引发权重求和为零的错误。

3. 权重归一化失败：在计算嵌入向量的加权平均时，系统尝试对权重进行归一化处理，但由于上述原因导致所有权重之和为零，从而触发了除零异常。

解决方案

1. 修改嵌入格式参数

对于使用本地嵌入模型的情况，可以通过修改map_query_to_entities函数中的嵌入调用，显式指定使用浮点数格式：

search_results = text_embedding_vectorstore.similarity_search_by_text(
    text=query,
    text_embedder=lambda t: text_embedder.embed(t, encoding_format="float"),
    k=k * oversample_scaler,
)

这个修改强制嵌入模型返回浮点数而非默认的base64编码，解决了格式不匹配的问题。

2. 检查API配置

当使用云服务（如Azure OpenAI）时，需要确保：

1. API密钥有效且具有正确的权限
2. 部署名称和模型名称配置正确
3. API基础地址指向正确的端点
4. 嵌入模型与查询模型使用相同的认证信息

3. 验证索引阶段

在索引构建阶段出现问题时也可能导致后续查询异常。建议：

1. 检查索引阶段的日志输出
2. 验证嵌入模型是否成功处理了所有文档
3. 确保向量存储中包含了有效的嵌入向量

最佳实践建议

1. 环境隔离：为不同的服务（如LLM和嵌入模型）使用单独的环境变量，避免配置冲突。

2. 错误处理：在代码中添加对嵌入结果的验证逻辑，提前捕获异常情况。

3. 日志记录：增强关键步骤的日志记录，便于诊断问题。

4. 版本兼容性：确保使用的模型版本与GraphRAG项目兼容。

总结

"ZeroDivisionError: Weights sum to zero"错误在GraphRAG项目中通常与嵌入模型的配置和使用方式有关。通过理解错误的根本原因，开发者可以采取针对性的解决措施，确保本地范围查询与全局查询一样可靠工作。正确配置嵌入模型参数和验证API设置是避免此类问题的关键。