AIEC-new/AIEC-server/docs/troubleshooting-graph-rag.md

Graph-RAG-Agent 集成问题排查

已完成的修改

1. chat-service.js 已修改：

   • 服务地址改为 http://localhost:8000
   • API 接口路径已更新（/qa/ask → /chat）
   • 请求/响应格式已适配
   • 移除了强制的认证要求

2. 修复了递归调用问题：

   • main.js 中的事件监听器不再导致递归

当前问题及解决方案

问题1：ChatAPIService 未定义

症状：Cannot read properties of undefined (reading 'sendMessageStream')

可能原因：

1. 脚本加载顺序问题
2. 认证相关的依赖未满足
3. CORS 跨域问题

解决步骤：

1. 确保 graph-rag-agent 服务正在运行：

   cd ~/graph-rag-agent
   python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
   

2. 使用本地 HTTP 服务器访问前端（避免 file:// 协议的限制）：

   cd ~/yundage-backserver-test
   ./start-local.sh
   

3. 访问测试页面验证 API：

   http://localhost:3000/test-graph-rag.html
   

问题2：认证依赖

症状：TokenManager 相关错误

解决方案：

• chat-service.js 已修改为可选的 TokenManager 依赖
• 如果不需要认证，可以直接使用

测试步骤

1. 验证 graph-rag-agent 服务：

   curl http://localhost:8000/
   

2. 测试同步 API：

   curl -X POST http://localhost:8000/chat \
     -H "Content-Type: application/json" \
     -d '{
       "message": "什么是数字化转型？",
       "session_id": "test_123",
       "agent_type": "naive_rag_agent",
       "debug": false
     }'
   

3. 使用测试页面：

   • 打开 http://localhost:3000/test-graph-rag.html
   • 测试服务状态、同步消息和流式消息

注意事项

1. CORS 配置：graph-rag-agent 需要允许来自前端的跨域请求（localhost:3000 或 file://）
2. Neo4j 依赖：确保 Neo4j 数据库正在运行并包含必要的数据
3. 会话管理：当前实现依赖浏览器本地存储

快速启动命令

# 终端1：启动 graph-rag-agent（Python后端）
cd ~/graph-rag-agent
python -m uvicorn server.main:app --reload --host 0.0.0.0 --port 8000

# 终端2：启动前端服务器（可选，用于避免CORS问题）
cd ~/yundage-backserver-test
./start-local.sh

# 访问：http://localhost:3000
# 或者直接用浏览器打开 index.html 文件

端口说明

• 8000: graph-rag-agent (Python FastAPI 后端)
• 8080: 原 Java 后端（现在不使用）
• 3000: 前端静态文件服务器（可选）