first commit

AIEC-server/docs/graph-rag-integration.md

@@ -0,0 +1,104 @@
+# Graph-RAG-Agent 集成说明
+
+## 修改概述
+
+本次修改将 yundage-backserver-test 前端从调用原有的 Java 后端（localhost:8080）改为调用 graph-rag-agent 的 FastAPI 后端（localhost:8000），使用 naive_search_tool 进行问答。
+
+## 主要修改
+
+### 1. chat-service.js 修改
+
+修改文件：`/services/api/chat-service.js`
+
+#### 基础配置修改
+- **服务地址**：从 `http://localhost:8080` 改为 `http://localhost:8000`
+- **会话管理**：添加了会话ID生成功能，因为 graph-rag-agent 需要 session_id
+
+#### API 接口映射
+
+| 原接口 (Java) | 新接口 (graph-rag-agent) | 说明 |
+|--------------|-------------------------|------|
+| POST `/qa/ask` | POST `/chat` | 同步问答接口 |
+| POST `/qa/ask/stream` | POST `/chat/stream` | 流式问答接口 |
+| GET `/qa/conversations` | 本地存储 | graph-rag-agent 无此接口，改为从 localStorage 读取 |
+| GET `/qa/conversations/{id}/messages` | 本地存储 | 同上 |
+
+#### 请求参数转换
+
+**原请求格式**：
+```json
+{
+    "mode": "chat",
+    "conversationId": null,
+    "message": "用户消息"
+}
+```
+
+**新请求格式**：
+```json
+{
+    "message": "用户消息",
+    "session_id": "生成的会话ID",
+    "debug": false,
+    "agent_type": "naive_rag_agent",
+    "use_deeper_tool": false,
+    "show_thinking": false
+}
+```
+
+#### 响应格式适配
+
+由于前端期望特定的响应格式，在 `sendMessage` 方法中进行了格式转换：
+
+```javascript
+// 转换响应格式以适配前端
+return {
+    code: 200,
+    data: {
+        conversationId: messageData.conversationId || this.sessionId,
+        messageId: Date.now().toString(),
+        content: response.answer,
+        reference: response.reference,
+        kg_data: response.kg_data
+    },
+    message: '成功'
+};
+```
+
+#### 流式响应处理
+
+graph-rag-agent 的流式响应格式与原后端不同，主要修改：
+- 解析 SSE 数据格式从 `event:` + `data:` 改为直接解析 `data:`
+- 处理不同的状态类型：`start`、`token`、`done`、`error`
+- 累积完整内容并在完成时返回
+
+### 2. 新增功能
+
+- **generateSessionId()**：生成唯一的会话ID
+- **clearConversation()**：调用 graph-rag-agent 的 `/clear` 接口清除会话历史
+
+### 3. 本地存储集成
+
+由于 graph-rag-agent 不提供会话列表和历史消息接口，修改为：
+- 从 `window.chatManager` 读取本地存储的会话数据
+- 保持与原有前端逻辑的兼容性
+
+## 使用说明
+
+1. 确保 graph-rag-agent 服务运行在 `http://localhost:8000`
+2. 确保 Neo4j 数据库已启动并包含必要的数据
+3. 前端会自动使用 `naive_rag_agent` 进行问答
+4. 会话历史保存在浏览器本地存储中
+
+## 注意事项
+
+1. **认证**：graph-rag-agent 可能不需要 JWT 认证，但代码中保留了 Authorization header 以备后用
+2. **会话管理**：每个用户会生成唯一的 session_id，格式为 `{username}_{timestamp}_{random}`
+3. **错误处理**：保留了原有的错误处理逻辑，包括认证失败跳转等
+4. **深度搜索**：当前配置使用 naive_search_tool，如需使用 deep_research_tool，可修改 `agent_type` 参数
+
+## 后续优化建议
+
+1. 可以根据用户选择动态切换 agent_type（naive_rag_agent / deep_research_agent）
+2. 可以添加配置项控制是否显示思考过程（show_thinking）
+3. 可以实现真正的会话持久化，而不仅仅依赖浏览器本地存储