first commit

AIEC-server/docs/neo4j-connection-fix.md

@@ -0,0 +1,116 @@
+# Neo4j 连接问题解决方案
+
+## 问题描述
+
+前端成功调用了 graph-rag-agent API，但后端在处理时报错：
+```
+搜索过程中出现错误: Connection error.
+```
+
+这表明 graph-rag-agent 无法连接到 Neo4j 数据库。
+
+## 解决步骤
+
+### 1. 检查 Neo4j 服务状态
+
+```bash
+# 检查 Neo4j 是否在运行
+sudo systemctl status neo4j
+
+# 或者如果使用 Docker
+docker ps | grep neo4j
+```
+
+### 2. 启动 Neo4j（如果未运行）
+
+```bash
+# 使用系统服务
+sudo systemctl start neo4j
+
+# 或使用 Docker
+docker run -d \
+  --name neo4j \
+  -p 7474:7474 -p 7687:7687 \
+  -e NEO4J_AUTH=neo4j/password \
+  neo4j:latest
+```
+
+### 3. 检查 Neo4j 连接配置
+
+查看 graph-rag-agent 的配置文件：
+```bash
+cd ~/graph-rag-agent
+cat config/settings.py | grep -i neo4j
+```
+
+确保配置正确：
+- URI: `bolt://localhost:7687` 或 `neo4j://localhost:7687`
+- 用户名: 通常是 `neo4j`
+- 密码: 你设置的密码
+
+### 4. 测试 Neo4j 连接
+
+使用 Neo4j 浏览器：
+```
+http://localhost:7474
+```
+
+或使用 cypher-shell：
+```bash
+cypher-shell -u neo4j -p your-password
+```
+
+### 5. 检查数据库内容
+
+确保 Neo4j 中有必要的数据：
+```cypher
+// 在 Neo4j 浏览器中运行
+MATCH (n:__Chunk__) RETURN count(n) as chunk_count;
+MATCH (n:__Entity__) RETURN count(n) as entity_count;
+```
+
+如果返回 0，说明需要先构建知识图谱。
+
+### 6. 构建知识图谱（如果需要）
+
+```bash
+cd ~/graph-rag-agent
+# 查看是否有数据导入脚本
+ls build/
+ls scripts/
+```
+
+通常需要运行类似这样的命令：
+```bash
+python build/build_graph.py --input your_documents_folder
+```
+
+## 临时解决方案
+
+如果暂时无法解决 Neo4j 问题，可以：
+
+1. **使用 mock 数据**：修改 naive_search_tool 返回模拟数据
+2. **切换到其他 agent**：尝试不依赖 Neo4j 的 agent 类型
+3. **使用内存数据库**：配置 graph-rag-agent 使用内存模式
+
+## 验证修复
+
+修复后，使用测试页面验证：
+```
+http://localhost:3000/test-graph-rag.html
+```
+
+或直接测试 API：
+```bash
+curl -X POST http://localhost:8000/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "message": "测试问题",
+    "session_id": "test",
+    "agent_type": "naive_rag_agent"
+  }'
+```
+
+## 前端显示问题
+
+如果看到原始 JSON 而不是格式化的文本，这是因为后端返回了包含错误信息的响应。一旦 Neo4j 连接问题解决，前端会正常显示格式化的回答。