From 4fa3adbf3b252e4ca398745583921cb3fb511042 Mon Sep 17 00:00:00 2001 From: wizardchen Date: Wed, 5 Nov 2025 23:18:44 +0800 Subject: [PATCH] feat: Add agent configuration and cleanup scripts for database migrations --- .gitignore | 1 + STREAM_EVENT_BASED_REFACTORING.md | 405 ++++++++ SUMMARY.md | 306 ++++++ TEST_AGENT_CONFIG.md | 333 +++++++ TEST_AGENT_STEPS.md | 221 +++++ client/README.md | 123 ++- client/agent.go | 137 +++ client/agent_example.go | 291 ++++++ client/cmd/agent_test/Makefile | 75 ++ client/cmd/agent_test/QUICKSTART.md | 293 ++++++ client/cmd/agent_test/README.md | 307 ++++++ client/cmd/agent_test/go.mod | 7 + client/cmd/agent_test/main.go | 369 ++++++++ client/cmd/agent_test/run.sh | 172 ++++ client/cmd/agent_test/test_scenarios.sh | 159 ++++ client/session.go | 16 +- config/config.yaml | 15 +- docker-compose.yml | 2 + docs/AGENT.md | 527 +++++++++++ docs/CONTEXT_MANAGER.md | 401 ++++++++ frontend/src/api/chat/index.ts | 5 + frontend/src/api/initialization/index.ts | 12 +- frontend/src/api/model/index.ts | 117 +++ frontend/src/api/system/index.ts | 28 +- frontend/src/assets/img/agent-active.svg | 5 + frontend/src/assets/img/agent.svg | 5 + frontend/src/assets/img/at-icon.svg | 4 + frontend/src/assets/img/setting-green.svg | 7 +- frontend/src/assets/img/setting.svg | 7 +- frontend/src/components/Input-field.vue | 375 +++++++- .../src/components/KnowledgeBaseSelector.vue | 371 ++++++++ frontend/src/components/ModelEditorDialog.vue | 886 ++++++++++++++++++ frontend/src/components/UserMenu.vue | 301 ++++++ frontend/src/components/menu.vue | 65 +- frontend/src/router/index.ts | 14 +- frontend/src/stores/menu.ts | 2 +- frontend/src/stores/settings.ts | 183 ++++ frontend/src/stores/ui.ts | 22 + frontend/src/types/tool-results.ts | 163 ++++ frontend/src/utils/tool-icons.ts | 55 ++ .../chat/components/AgentStreamDisplay.vue | 879 +++++++++++++++++ .../chat/components/ToolResultRenderer.vue | 120 +++ frontend/src/views/chat/components/botmsg.vue | 4 +- .../components/tool-results/ChunkDetail.vue | 75 ++ .../components/tool-results/DatabaseQuery.vue | 164 ++++ .../components/tool-results/DocumentInfo.vue | 89 ++ .../tool-results/GraphQueryResults.vue | 125 +++ .../tool-results/KnowledgeBaseList.vue | 108 +++ .../components/tool-results/PlanDisplay.vue | 176 ++++ .../components/tool-results/RelatedChunks.vue | 115 +++ .../components/tool-results/SearchResults.vue | 142 +++ .../tool-results/ThinkingDisplay.vue | 49 + .../components/tool-results/tool-results.less | 289 ++++++ frontend/src/views/chat/index.vue | 288 +++++- frontend/src/views/creatChat/creatChat.vue | 130 +-- .../initialization/InitializationContent.vue | 237 +++++ frontend/src/views/settings/AgentSettings.vue | 652 +++++++++++++ .../src/views/settings/GeneralSettings.vue | 167 ++++ .../views/settings/KnowledgeBaseSettings.vue | 216 +++++ frontend/src/views/settings/ModelSettings.vue | 633 +++++++++++++ .../src/views/settings/OllamaSettings.vue | 641 +++++++++++++ frontend/src/views/settings/Settings.vue | 559 +++++++++-- frontend/src/views/settings/SystemInfo.vue | 533 +++++++++++ .../src/views/settings/SystemSettings.vue | 211 ----- internal/agent/engine.go | 725 ++++++++++++++ internal/agent/prompts.go | 616 ++++++++++++ internal/agent/tools/database_query.go | 456 +++++++++ internal/agent/tools/get_document_info.go | 332 +++++++ internal/agent/tools/get_related_chunks.go | 427 +++++++++ internal/agent/tools/knowledge_search.go | 816 ++++++++++++++++ internal/agent/tools/query_knowledge_graph.go | 423 +++++++++ internal/agent/tools/registry.go | 108 +++ internal/agent/tools/thinking.go | 115 +++ internal/agent/tools/todo_write.go | 344 +++++++ internal/agent/tools/tool.go | 77 ++ internal/application/repository/model.go | 19 +- internal/application/service/agent_service.go | 287 ++++++ .../chat_pipline/chat_completion_stream.go | 5 + internal/application/service/chunk.go | 13 +- .../application/service/context_manager.go | 354 +++++++ internal/application/service/extract.go | 1 - internal/application/service/knowledge.go | 2 +- internal/application/service/model.go | 80 +- internal/application/service/session.go | 204 ++++ internal/config/config.go | 10 + internal/container/container.go | 11 +- internal/errors/errors.go | 39 + internal/event/SUMMARY.md | 238 +++++ internal/event/event.go | 224 +++++ internal/event/event_data.go | 197 ++++ internal/event/example_test.go | 247 +++++ internal/event/global.go | 57 ++ internal/event/middleware.go | 94 ++ internal/event/usage_example.md | 419 +++++++++ internal/handler/agent_stream_handler.go | 480 ++++++++++ internal/handler/chunk.go | 2 +- internal/handler/initialization.go | 39 +- internal/handler/session.go | 297 ++++-- internal/handler/tenant.go | 170 ++++ internal/models/chat/chat.go | 35 +- internal/models/chat/remote_api.go | 215 ++++- internal/models/utils/ollama/ollama.go | 31 +- internal/router/router.go | 11 + internal/stream/memory_manager.go | 58 +- internal/stream/redis_manager.go | 101 +- internal/types/agent.go | 110 +++ internal/types/chat.go | 33 +- internal/types/interfaces/agent.go | 33 + internal/types/interfaces/chunk.go | 2 +- internal/types/interfaces/context_manager.go | 49 + internal/types/interfaces/model.go | 2 + internal/types/interfaces/session.go | 4 + internal/types/interfaces/stream_manager.go | 25 +- internal/types/message.go | 35 + internal/types/session.go | 43 + internal/types/tenant.go | 6 +- internal/utils/json.go | 11 + migrations/README.md | 199 ++++ migrations/mysql/00-init-db.sql | 4 + .../mysql/02-add-agent-config-if-missing.sql | 114 +++ .../mysql/03-cleanup-unreferenced-models.sql | 137 +++ migrations/paradedb/00-init-db.sql | 11 + .../02-add-agent-config-if-missing.sql | 173 ++++ .../03-cleanup-unreferenced-models.sql | 228 +++++ scripts/migrate.sh | 0 test_agent_config.sh | 148 +++ 126 files changed, 22506 insertions(+), 629 deletions(-) create mode 100644 STREAM_EVENT_BASED_REFACTORING.md create mode 100644 SUMMARY.md create mode 100644 TEST_AGENT_CONFIG.md create mode 100644 TEST_AGENT_STEPS.md create mode 100644 client/agent.go create mode 100644 client/agent_example.go create mode 100644 client/cmd/agent_test/Makefile create mode 100644 client/cmd/agent_test/QUICKSTART.md create mode 100644 client/cmd/agent_test/README.md create mode 100644 client/cmd/agent_test/go.mod create mode 100644 client/cmd/agent_test/main.go create mode 100755 client/cmd/agent_test/run.sh create mode 100755 client/cmd/agent_test/test_scenarios.sh create mode 100644 docs/AGENT.md create mode 100644 docs/CONTEXT_MANAGER.md create mode 100644 frontend/src/api/model/index.ts create mode 100644 frontend/src/assets/img/agent-active.svg create mode 100644 frontend/src/assets/img/agent.svg create mode 100644 frontend/src/assets/img/at-icon.svg create mode 100644 frontend/src/components/KnowledgeBaseSelector.vue create mode 100644 frontend/src/components/ModelEditorDialog.vue create mode 100644 frontend/src/components/UserMenu.vue create mode 100644 frontend/src/stores/ui.ts create mode 100644 frontend/src/types/tool-results.ts create mode 100644 frontend/src/utils/tool-icons.ts create mode 100644 frontend/src/views/chat/components/AgentStreamDisplay.vue create mode 100644 frontend/src/views/chat/components/ToolResultRenderer.vue create mode 100644 frontend/src/views/chat/components/tool-results/ChunkDetail.vue create mode 100644 frontend/src/views/chat/components/tool-results/DatabaseQuery.vue create mode 100644 frontend/src/views/chat/components/tool-results/DocumentInfo.vue create mode 100644 frontend/src/views/chat/components/tool-results/GraphQueryResults.vue create mode 100644 frontend/src/views/chat/components/tool-results/KnowledgeBaseList.vue create mode 100644 frontend/src/views/chat/components/tool-results/PlanDisplay.vue create mode 100644 frontend/src/views/chat/components/tool-results/RelatedChunks.vue create mode 100644 frontend/src/views/chat/components/tool-results/SearchResults.vue create mode 100644 frontend/src/views/chat/components/tool-results/ThinkingDisplay.vue create mode 100644 frontend/src/views/chat/components/tool-results/tool-results.less create mode 100644 frontend/src/views/settings/AgentSettings.vue create mode 100644 frontend/src/views/settings/GeneralSettings.vue create mode 100644 frontend/src/views/settings/KnowledgeBaseSettings.vue create mode 100644 frontend/src/views/settings/ModelSettings.vue create mode 100644 frontend/src/views/settings/OllamaSettings.vue create mode 100644 frontend/src/views/settings/SystemInfo.vue delete mode 100644 frontend/src/views/settings/SystemSettings.vue create mode 100644 internal/agent/engine.go create mode 100644 internal/agent/prompts.go create mode 100644 internal/agent/tools/database_query.go create mode 100644 internal/agent/tools/get_document_info.go create mode 100644 internal/agent/tools/get_related_chunks.go create mode 100644 internal/agent/tools/knowledge_search.go create mode 100644 internal/agent/tools/query_knowledge_graph.go create mode 100644 internal/agent/tools/registry.go create mode 100644 internal/agent/tools/thinking.go create mode 100644 internal/agent/tools/todo_write.go create mode 100644 internal/agent/tools/tool.go create mode 100644 internal/application/service/agent_service.go create mode 100644 internal/application/service/context_manager.go create mode 100644 internal/event/SUMMARY.md create mode 100644 internal/event/event.go create mode 100644 internal/event/event_data.go create mode 100644 internal/event/example_test.go create mode 100644 internal/event/global.go create mode 100644 internal/event/middleware.go create mode 100644 internal/event/usage_example.md create mode 100644 internal/handler/agent_stream_handler.go create mode 100644 internal/types/agent.go create mode 100644 internal/types/interfaces/agent.go create mode 100644 internal/types/interfaces/context_manager.go create mode 100644 internal/utils/json.go create mode 100644 migrations/README.md create mode 100644 migrations/mysql/02-add-agent-config-if-missing.sql create mode 100644 migrations/mysql/03-cleanup-unreferenced-models.sql create mode 100644 migrations/paradedb/02-add-agent-config-if-missing.sql create mode 100644 migrations/paradedb/03-cleanup-unreferenced-models.sql mode change 100644 => 100755 scripts/migrate.sh create mode 100755 test_agent_config.sh diff --git a/.gitignore b/.gitignore index 3fb44ce2..2bf74024 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,4 @@ data/files/ ### macOS # General .DS_Store +/scripts/scale_dev_jobs.sh \ No newline at end of file diff --git a/STREAM_EVENT_BASED_REFACTORING.md b/STREAM_EVENT_BASED_REFACTORING.md new file mode 100644 index 00000000..c595c524 --- /dev/null +++ b/STREAM_EVENT_BASED_REFACTORING.md @@ -0,0 +1,405 @@ +# Stream Manager 重构:从内容累积到事件流 + +## 问题分析 + +用户指出了一个关键问题:当前只有 `handleFinalAnswer` 在更新 stream,但其他事件(thinking、tool_call、tool_result 等)也应该推送到 stream。这样当用户刷新页面时,可以**恢复完整的输出过程**。 + +### 之前的问题 ❌ + +```go +// StreamInfo 只存储累积的内容 +type StreamInfo struct { + SessionID string + RequestID string + Query string + Content string // ❌ 只有累积内容,丢失了事件流 + KnowledgeReferences types.References + LastUpdated time.Time + IsCompleted bool +} + +// UpdateStream 只能追加内容 +func UpdateStream(ctx, sessionID, requestID string, + content string, references types.References) error +``` + +**问题:** +1. ❌ 只保存最终内容,没有保存事件流 +2. ❌ 刷新页面后,只能看到累积的答案,看不到思考/工具调用过程 +3. ❌ 无法重现完整的 Agent 执行过程 +4. ❌ 用户体验差:刷新后丢失所有中间状态 + +## 改进方案 ✅ + +### 核心思想 + +**从存储内容到存储事件流** - 每个事件(thinking、tool_call、tool_result 等)都推送到stream,刷新时可以完整重放。 + +### 新的数据结构 + +```go +// StreamEvent 代表一个事件 +type StreamEvent struct { + Type types.ResponseType // 事件类型 + Content string // 事件内容 + Done bool // 是否完成 + Timestamp time.Time // 事件时间 + Data map[string]interface{} // 附加数据 +} + +// StreamInfo 存储完整的事件流 +type StreamInfo struct { + SessionID string + RequestID string + Query string + Events []StreamEvent // ✅ 完整的事件流 + KnowledgeReferences types.References + LastUpdated time.Time + IsCompleted bool +} +``` + +### 新的接口 + +```go +type StreamManager interface { + // RegisterStream 注册新流 + RegisterStream(ctx, sessionID, requestID, query string) error + + // PushEvent 推送单个事件 ✅ + PushEvent(ctx, sessionID, requestID string, event StreamEvent) error + + // UpdateReferences 更新知识引用 ✅ + UpdateReferences(ctx, sessionID, requestID string, references types.References) error + + // CompleteStream 完成流 + CompleteStream(ctx, sessionID, requestID string) error + + // GetStream 获取流(用于刷新重放)✅ + GetStream(ctx, sessionID, requestID string) (*StreamInfo, error) +} +``` + +## 实现详情 + +### 1. AgentStreamHandler - 推送所有事件 + +#### handleThought + +```go +func (h *AgentStreamHandler) handleThought(...) error { + // 1. 发送 SSE + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // 2. 推送事件到 stream(用于刷新重放)✅ + h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + Type: types.ResponseTypeThinking, + Content: data.Content, + Done: data.Done, + Timestamp: time.Now(), + }) +} +``` + +#### handleToolCall + +```go +func (h *AgentStreamHandler) handleToolCall(...) error { + // 1. 发送 SSE + h.ginContext.SSEvent("message", response) + + // 2. 推送事件到 stream(含工具调用详情)✅ + h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + Type: types.ResponseTypeToolCall, + Content: fmt.Sprintf("Calling tool: %s", data.ToolName), + Timestamp: time.Now(), + Data: map[string]interface{}{ + "tool_name": data.ToolName, + "arguments": data.Arguments, + }, + }) +} +``` + +#### handleToolResult + +```go +func (h *AgentStreamHandler) handleToolResult(...) error { + // 1. 发送 SSE + h.ginContext.SSEvent("message", response) + + // 2. 推送事件到 stream(含结果详情)✅ + h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + Type: responseType, + Content: content, + Timestamp: time.Now(), + Data: map[string]interface{}{ + "tool_name": data.ToolName, + "success": data.Success, + "output": data.Output, + "error": data.Error, + }, + }) +} +``` + +#### handleReflection + +```go +func (h *AgentStreamHandler) handleReflection(...) error { + // 1. 发送 SSE + h.ginContext.SSEvent("message", response) + + // 2. 推送事件到 stream ✅ + h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + Type: "reflection", + Content: data.Content, + Timestamp: time.Now(), + }) +} +``` + +#### handleFinalAnswer + +```go +func (h *AgentStreamHandler) handleFinalAnswer(...) error { + // 1. 发送 SSE + h.ginContext.SSEvent("message", response) + + // 2. 推送事件到 stream ✅ + h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + Type: types.ResponseTypeAnswer, + Content: data.Content, + Done: data.Done, + Timestamp: time.Now(), + }) +} +``` + +### 2. 刷新重放逻辑 + +#### 之前 ❌ - 只显示累积内容 + +```go +// 只发送累积的内容 +if streamInfo.Content != "" { + c.SSEvent("message", &types.StreamResponse{ + Content: streamInfo.Content, // ❌ 失去中间过程 + }) +} +``` + +#### 现在 ✅ - 完整重放事件流 + +```go +// 重放所有事件 +if len(streamInfo.Events) > 0 { + logger.Debugf(ctx, "Replaying %d existing events", len(streamInfo.Events)) + for _, evt := range streamInfo.Events { + c.SSEvent("message", &types.StreamResponse{ + ID: message.RequestID, + ResponseType: evt.Type, + Content: evt.Content, + Done: evt.Done, + }) + } +} +``` + +### 3. 实时监控新事件 + +#### 之前 ❌ - 监控内容增量 + +```go +// 计算内容差异 +if len(latestStreamInfo.Content) > len(currentContent) { + newContent := latestStreamInfo.Content[len(currentContent):] + contentCh <- newContent + currentContent = latestStreamInfo.Content +} +``` + +#### 现在 ✅ - 监控新事件 + +```go +// 检测新事件 +if len(latestStreamInfo.Events) > currentEventCount { + eventIndexCh <- currentEventCount + currentEventCount = len(latestStreamInfo.Events) +} + +// 发送新事件 +case startIdx := <-eventIndexCh: + for i := startIdx; i < len(latestStreamInfo.Events); i++ { + evt := latestStreamInfo.Events[i] + c.SSEvent("message", &types.StreamResponse{ + ResponseType: evt.Type, + Content: evt.Content, + Done: evt.Done, + }) + } +``` + +## 数据流对比 + +### 之前 ❌ + +``` +Agent 执行 + │ + ├─→ thinking event → SSE → 前端 (丢失) + ├─→ tool_call event → SSE → 前端 (丢失) + ├─→ tool_result event → SSE → 前端 (丢失) + └─→ final_answer event → SSE → 前端 + └─→ UpdateStream(累积内容) + +用户刷新 → GetStream → 只有累积内容 ❌ +``` + +### 现在 ✅ + +``` +Agent 执行 + │ + ├─→ thinking event → SSE → 前端 + │ └─→ PushEvent(thinking) ✅ + ├─→ tool_call event → SSE → 前端 + │ └─→ PushEvent(tool_call) ✅ + ├─→ tool_result event → SSE → 前端 + │ └─→ PushEvent(tool_result) ✅ + └─→ final_answer event → SSE → 前端 + └─→ PushEvent(final_answer) ✅ + +用户刷新 → GetStream → 完整事件流 ✅ + → 重放所有事件 +``` + +## 优势总结 + +| 方面 | 之前 ❌ | 现在 ✅ | +|------|---------|---------| +| **事件保留** | 只保留最终内容 | 保留完整事件流 | +| **刷新体验** | 丢失中间过程 | 完整重放 | +| **思考过程** | 不可见 | 可见 | +| **工具调用** | 不可见 | 可见 | +| **错误调试** | 困难 | 容易(完整历史) | +| **用户体验** | 差 | 好 | + +## 存储实现 + +### Memory Manager + +```go +type memoryStreamInfo struct { + sessionID string + requestID string + query string + events []interfaces.StreamEvent // ✅ 事件数组 + knowledgeReferences types.References + lastUpdated time.Time + isCompleted bool +} + +func (m *MemoryStreamManager) PushEvent(..., event interfaces.StreamEvent) error { + stream.events = append(stream.events, event) // ✅ 追加事件 + stream.lastUpdated = time.Now() + return nil +} +``` + +### Redis Manager + +```go +type redisStreamInfo struct { + SessionID string `json:"session_id"` + RequestID string `json:"request_id"` + Query string `json:"query"` + Events []interfaces.StreamEvent `json:"events"` // ✅ 事件数组 + KnowledgeReferences types.References `json:"knowledge_references"` + LastUpdated time.Time `json:"last_updated"` + IsCompleted bool `json:"is_completed"` +} + +func (r *RedisStreamManager) PushEvent(..., event interfaces.StreamEvent) error { + info.Events = append(info.Events, event) // ✅ 追加事件 + updatedData, _ := json.Marshal(info) + return r.client.Set(ctx, key, updatedData, r.ttl).Err() +} +``` + +## 使用场景 + +### 场景 1: 正常执行 + +1. Agent 执行过程中,每个事件同时: + - 发送 SSE 给前端(实时显示) + - PushEvent 到 stream(持久化) + +### 场景 2: 刷新页面 + +1. 前端重新连接 +2. GetStream 获取完整事件流 +3. 重放所有事件 +4. 继续监听新事件 + +### 场景 3: 断线重连 + +1. 客户端记录已接收的事件数量 +2. 重连后从 `Events[lastIndex:]` 开始重放 +3. 无缝恢复 + +## 前端适配 + +```typescript +// 刷新时恢复状态 +const streamInfo = await api.getStream(sessionId, messageId); + +// 重放所有历史事件 +streamInfo.events.forEach(event => { + switch (event.type) { + case 'thinking': + showThinking(event.content); + break; + case 'tool_call': + showToolCall(event.data.tool_name, event.data.arguments); + break; + case 'tool_result': + showToolResult(event.data.tool_name, event.data.output); + break; + case 'answer': + showAnswer(event.content); + break; + } +}); + +// 继续监听新事件 +connectSSE(sessionId, messageId); +``` + +## 性能考虑 + +### 内存占用 + +- 每个事件 ~100-500 bytes +- 典型的 Agent 执行 ~20-50 个事件 +- 总计 ~2-25 KB per session +- 可接受 + +### Redis 存储 + +- JSON 序列化事件数组 +- TTL 控制:默认 1 小时后自动清理 +- 压缩:Redis 自动处理 + +### 优化策略 + +1. **事件限制**: 可选地限制最大事件数(如 1000个) +2. **压缩**: 对大量事件进行压缩 +3. **分片**: 超大事件流可以分片存储 + +--- + +**重构完成时间**: 2025-10-31 +**状态**: ✅ 完成,支持完整事件流重放 + diff --git a/SUMMARY.md b/SUMMARY.md new file mode 100644 index 00000000..34ea2cd7 --- /dev/null +++ b/SUMMARY.md @@ -0,0 +1,306 @@ +# Summary of Changes + +## 完成的工作 + +本次提交完成了两个主要任务: + +### 1. Client包中添加AgentQA支持 + +为WeKnora的Go client包添加了完整的Agent QA功能支持,包括: + +#### 新增文件 +- **`client/agent.go`** - Agent QA的核心实现 + - `AgentQAStream()` - 执行Agent问答并处理SSE流 + - `AgentSession` - Agent会话封装 + - 支持所有Agent事件类型(thinking, tool_call, tool_result, references, answer, reflection, error) + +- **`client/agent_example.go`** - 完整的使用示例 + - 基础Agent问答 + - 工具调用跟踪 + - 知识引用捕获 + - 完整事件跟踪 + - 自定义错误处理 + - 流取消控制 + - 多会话管理 + +#### 终端调试工具 +创建了功能完善的交互式终端调试工具: + +- **`client/cmd/agent_test/main.go`** - 主程序(371行) + - 交互式命令行界面 + - 彩色输出 + - 实时显示所有Agent事件 + - 会话管理(创建、切换、列表) + - 性能统计 + +- **辅助文件**: + - `Makefile` - 构建和运行脚本 + - `run.sh` - 快速启动脚本(支持环境变量配置) + - `test_scenarios.sh` - 测试场景脚本 + - `.env.example` - 环境变量示例 + - `README.md` - 详细使用文档(370行) + - `QUICKSTART.md` - 5分钟快速入门指南(294行) + +#### 文档更新 +- 更新了 `client/README.md`,添加了Agent问答的完整文档 + - API使用说明 + - 事件类型表格 + - 代码示例 + - 终端工具说明 + +### 2. Agent配置架构重构(租户级别) + +将Agent配置从知识库级别重构为租户级别的全局配置。 + +#### 架构变更 + +**之前的问题**: +- Agent配置在每个知识库中独立配置 +- 配置分散,难以管理 +- 缺乏全局控制 + +**新的架构**: +``` +Tenant (全局默认配置) + ↓ +Session (可选的覆盖配置) +``` + +#### 数据模型变更 + +1. **`internal/types/tenant.go`** + - ✅ 添加了 `AgentConfig` 字段 + +2. **`internal/types/knowledgebase.go`** + - ✅ 移除了 `AgentConfig` 字段 + +3. **`internal/application/service/session.go`** + - ✅ 添加了 `tenantService` 依赖 + - ✅ 更新了 `NewSessionService` 构造函数 + - ✅ 修改了配置优先级逻辑(Session > Tenant) + +4. **`internal/handler/initialization.go`** + - ✅ 移除了在知识库初始化时更新租户配置的不当逻辑 + - ✅ 更新了 `GetCurrentConfigByKB` 从租户读取Agent配置 + +#### 新增API接口 + +在 `internal/handler/tenant.go` 中添加了专门的租户Agent配置管理接口: + +1. **`GET /api/v1/tenants/:id/agent-config`** + - 获取租户的全局Agent配置 + - 如果未配置则返回默认值 + +2. **`PUT /api/v1/tenants/:id/agent-config`** + - 更新租户的全局Agent配置 + - 包含完整的参数验证 + - Validation规则: + - `max_iterations`: 1-20之间 + - `temperature`: 0-2之间 + - `thinking_model_id`: Agent启用时必填 + - `allowed_tools`: 至少一个工具 + +#### 路由更新 + +在 `internal/router/router.go` 中注册了新的API端点: +```go +tenantRoutes.GET("/:id/agent-config", handler.GetTenantAgentConfig) +tenantRoutes.PUT("/:id/agent-config", handler.UpdateTenantAgentConfig) +``` + +#### 数据库迁移 + +创建了两个迁移脚本: + +1. **MySQL**: `migrations/mysql/007_move_agent_config_to_tenant.sql` +2. **ParadeDB**: `migrations/paradedb/008_move_agent_config_to_tenant.sql` + +迁移步骤: +- 在 tenants 表添加 agent_config 列 +- 将现有的 agent_config 从 knowledge_bases 迁移到 tenants +- 从 knowledge_bases 表删除 agent_config 列 + +#### 文档 + +创建了完整的重构文档: + +**`AGENT_CONFIG_TENANT_REFACTORING.md`** (430行) +- 问题陈述 +- 解决方案 +- 所有变更的详细说明 +- 数据库迁移指南 +- API变更文档 +- 使用场景示例 +- 测试指南 +- 向后兼容性说明 + +## 技术细节 + +### Agent QA Client实现特点 + +1. **事件驱动**: 使用回调函数处理各种Agent事件 +2. **SSE流式处理**: 实时接收和处理服务器推送事件 +3. **类型安全**: 完整的类型定义和错误处理 +4. **灵活性**: 支持自定义事件处理和错误处理 +5. **易用性**: 提供简单的封装和丰富的示例 + +### 终端调试工具特点 + +1. **交互式**: 命令行式交互,支持多种命令 +2. **可视化**: 彩色输出,清晰展示各种事件 +3. **完整性**: 显示思考、工具调用、引用、答案、反思等所有信息 +4. **统计信息**: 显示耗时、工具调用次数、引用数量等 +5. **会话管理**: 支持创建、切换、列表会话 + +### 架构重构优势 + +1. **简化管理**: 租户级别的全局配置,一次设置全局生效 +2. **一致性**: 所有会话默认使用相同的Agent配置 +3. **灵活性**: 会话级别仍可覆盖配置 +4. **正确的关注点分离**: + - 租户配置 → 全局Agent策略 + - 会话配置 → 特定场景的覆盖 + - 知识库配置 → 不再包含Agent配置 + +## 文件清单 + +### 新增文件 + +``` +client/ +├── agent.go (139行) +├── agent_example.go (293行) +└── cmd/ + └── agent_test/ + ├── main.go (371行) + ├── go.mod (7行) + ├── Makefile (76行) + ├── run.sh (173行) + ├── test_scenarios.sh (160行) + ├── .env.example (17行) + ├── README.md (370行) + └── QUICKSTART.md (294行) + +migrations/ +├── mysql/ +│ └── 007_move_agent_config_to_tenant.sql (32行) +└── paradedb/ + └── 008_move_agent_config_to_tenant.sql (34行) + +# 文档 +AGENT_CONFIG_TENANT_REFACTORING.md (430行) +SUMMARY.md (本文件) +``` + +### 修改的文件 + +``` +client/README.md (增加了~100行Agent文档) +internal/types/tenant.go (添加AgentConfig字段) +internal/types/knowledgebase.go (移除AgentConfig字段) +internal/application/service/session.go (添加租户服务依赖,更新配置逻辑) +internal/handler/initialization.go (移除不当逻辑,更新读取逻辑) +internal/handler/tenant.go (添加2个新的API接口,~150行) +internal/router/router.go (注册新的API路由) +``` + +## 如何使用 + +### 使用Agent QA Client + +```go +import "github.com/Tencent/WeKnora/client" + +// 创建client +client := client.NewClient("http://localhost:8080") + +// 创建Agent会话 +agentSession := client.NewAgentSession("session_id") + +// 执行问答 +err := agentSession.Ask(ctx, "你的问题", func(resp *client.AgentStreamResponse) error { + switch resp.ResponseType { + case client.AgentResponseTypeAnswer: + fmt.Print(resp.Content) + } + return nil +}) +``` + +### 使用终端调试工具 + +```bash +cd client/cmd/agent_test +./run.sh -k kb_12345 + +# 或使用make +make build +./agent_test -url http://localhost:8080 -kb kb_12345 +``` + +### 管理租户Agent配置 + +```bash +# 获取配置 +curl http://localhost:8080/api/v1/tenants/1/agent-config + +# 更新配置 +curl -X PUT http://localhost:8080/api/v1/tenants/1/agent-config \ + -H "Content-Type: application/json" \ + -d '{ + "enabled": true, + "max_iterations": 5, + "temperature": 0.7, + "thinking_model_id": "model-123", + "allowed_tools": ["knowledge_search"] + }' +``` + +## 数据库迁移 + +在生产环境部署前,需要执行数据库迁移: + +```bash +# For MySQL +mysql -u username -p database_name < migrations/mysql/007_move_agent_config_to_tenant.sql + +# For PostgreSQL/ParadeDB +psql -U username -d database_name -f migrations/paradedb/008_move_agent_config_to_tenant.sql +``` + +## 测试建议 + +1. **单元测试**: 测试Agent配置的读取逻辑 +2. **集成测试**: 测试会话创建和Agent QA流程 +3. **API测试**: 测试新的租户Agent配置接口 +4. **迁移测试**: 在测试环境验证数据库迁移 +5. **终端工具测试**: 使用终端工具进行端到端测试 + +## 注意事项 + +⚠️ **Breaking Change**: 这是一个破坏性变更 + +- 现有的知识库级别的Agent配置将失效 +- 需要运行数据库迁移脚本 +- 需要更新使用Agent功能的代码 +- 建议在测试环境充分测试后再部署到生产环境 + +## 相关文档 + +- [Agent配置重构文档](AGENT_CONFIG_TENANT_REFACTORING.md) +- [Client Agent使用文档](client/README.md) +- [终端工具快速入门](client/cmd/agent_test/QUICKSTART.md) +- [终端工具完整文档](client/cmd/agent_test/README.md) +- [Agent示例代码](client/agent_example.go) + +## 贡献者 + +- 架构设计和实现 +- 完整的文档编写 +- 测试工具开发 + +--- + +**创建时间**: 2025-11-03 +**最后更新**: 2025-11-03 + diff --git a/TEST_AGENT_CONFIG.md b/TEST_AGENT_CONFIG.md new file mode 100644 index 00000000..e0f0d615 --- /dev/null +++ b/TEST_AGENT_CONFIG.md @@ -0,0 +1,333 @@ +# Agent 配置功能测试指南 + +## 快速测试步骤 + +### 准备工作 + +1. **确保数据库已迁移** + + ```bash + # MySQL + mysql -h localhost -u root -p weknora < migrations/mysql/02-add-agent-support.sql + + # 或 PostgreSQL + psql -h localhost -U postgres -d weknora -f migrations/paradedb/02-add-agent-support.sql + ``` + +2. **启动后端服务** + + ```bash + cd /Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora + go run cmd/server/main.go + ``` + +3. **启动前端服务** + + ```bash + cd /Users/wizard/code/go/src/git.woa.com/wxg-prc/WeKnora/frontend + npm run dev + ``` + +### 测试场景 + +#### 场景 1:Agent 配置保存到后台 + +**步骤:** + +1. 打开浏览器访问:`http://localhost:5173`(或前端服务地址) +2. 导航到 **设置** 页面 +3. 在 **Agent 智能问答模式** 区域: + - 打开 Agent 模式开关 + - 设置最大推理步数为 `8` + - 调整温度参数为 `0.8` + - 选择允许的工具 +4. 点击 **保存配置** 按钮 +5. 验证提示"配置保存成功" + +**验证:** + +- 打开浏览器开发者工具(F12) +- 查看 Network 标签,找到 `PUT /api/v1/tenants/1/agent-config` 请求 +- 验证请求状态为 200 +- 查看响应内容确认配置已保存 + +**数据库验证:** + +```sql +SELECT agent_config FROM tenants WHERE id = 1; +``` + +预期输出类似: +```json +{ + "enabled": true, + "max_iterations": 8, + "temperature": 0.8, + "allowed_tools": ["knowledge_search", "multi_kb_search", "list_knowledge_bases"], + ... +} +``` + +--- + +#### 场景 2:刷新页面后配置保持 + +**步骤:** + +1. 完成场景 1 的配置保存 +2. 刷新浏览器页面(F5) +3. 再次进入 **设置** 页面 + +**验证:** + +- Agent 模式开关保持启用状态 +- 最大推理步数显示为 `8` +- 温度参数显示为 `0.8` +- 工具选择保持不变 + +--- + +#### 场景 3:快速切换按钮功能 + +**步骤:** + +1. 导航到对话页面(选择任意知识库和会话) +2. 观察输入框左下角的机器人图标 🤖 +3. 点击机器人图标 + +**验证:** + +- **初始状态(禁用):** + - 图标灰色,半透明 + - 悬停时背景变浅蓝色 + +- **点击后(启用):** + - 图标变为彩色 + - 有呼吸动画效果 + - 显示提示"Agent 智能模式已启用" + - 页面顶部出现 "Agent 智能模式" 指示器(绿色标签) + +- **再次点击(禁用):** + - 图标变回灰色 + - 显示提示"Agent 智能模式已禁用" + - 顶部指示器消失 + +--- + +#### 场景 4:Agent 模式对话测试 + +**步骤:** + +1. 在对话页面,确保 Agent 模式已启用(机器人图标彩色) +2. 输入一个复杂问题,例如: + ``` + 请对比文档 A 和文档 B 的核心观点,并给出详细分析 + ``` +3. 发送消息 + +**验证:** + +- 能看到 Agent 的思考过程(thinking steps) +- 显示工具调用过程(tool calls) +- 最终给出综合答案 +- 请求 URL 为 `/api/v1/agent-chat/:session_id`(而非 `/api/v1/knowledge-chat`) + +**对比测试:** + +1. 禁用 Agent 模式(点击机器人图标) +2. 发送相同的问题 +3. 验证使用普通 QA 模式(直接返回答案,无思考步骤) +4. 请求 URL 为 `/api/v1/knowledge-chat/:session_id` + +--- + +#### 场景 5:UI 样式验证 + +**设置页面样式:** + +- ✅ 页面标题左侧有绿色竖线装饰 +- ✅ 配置区域使用浅绿色渐变背景 +- ✅ Agent 配置区域有绿色左边框 +- ✅ 主按钮使用绿色渐变 (#07c05f → #00a651) +- ✅ 按钮悬停时有上浮动画效果 +- ✅ 表单输入框聚焦时有绿色边框和阴影 + +**输入框样式:** + +- ✅ 机器人图标位于左下角 +- ✅ 禁用时灰色半透明 +- ✅ 启用时彩色有动画 +- ✅ 悬停时有缩放效果 + +--- + +## 常见问题排查 + +### 问题 1:保存配置时出现 404 错误 + +**原因:** 后端路由未正确注册 + +**排查:** +```bash +# 检查后端日志,确认路由是否注册 +curl -X GET http://localhost:8080/api/v1/tenants/1/agent-config +``` + +**解决:** 重新编译并启动后端服务 + +--- + +### 问题 2:刷新后配置丢失 + +**原因:** 可能只保存到 localStorage,未保存到后端 + +**排查:** +```sql +-- 查询数据库 +SELECT agent_config FROM tenants WHERE id = 1; +``` + +**解决:** 确保 `onSubmit` 方法中调用了 `updateAgentConfig` API + +--- + +### 问题 3:快速切换按钮不显示 + +**原因:** 前端代码未更新或缓存问题 + +**排查:** +```bash +# 检查 Input-field.vue 是否包含切换按钮代码 +grep -n "answers-input-agent" frontend/src/components/Input-field.vue +``` + +**解决:** +1. 清除浏览器缓存 +2. 强制刷新(Ctrl+Shift+R) +3. 重新构建前端 + +--- + +### 问题 4:Agent 模式不生效 + +**原因:** Session 创建时未传递 Agent 配置 + +**排查:** +```javascript +// 浏览器控制台 +console.log(useSettingsStore().isAgentEnabled) +``` + +**解决:** 确保 `chat/index.vue` 中正确读取 `isAgentEnabled` 状态 + +--- + +## 性能测试 + +### 配置保存性能 + +```bash +# 测试 API 响应时间 +time curl -X PUT http://localhost:8080/api/v1/tenants/1/agent-config \ + -H "Content-Type: application/json" \ + -d '{ + "enabled": true, + "max_iterations": 5, + "temperature": 0.7, + "allowed_tools": ["knowledge_search"] + }' +``` + +预期响应时间:< 100ms + +--- + +### 配置读取性能 + +```bash +# 测试 API 响应时间 +time curl -X GET http://localhost:8080/api/v1/tenants/1/agent-config +``` + +预期响应时间:< 50ms + +--- + +## 浏览器兼容性测试 + +- ✅ Chrome/Edge (最新版) +- ✅ Firefox (最新版) +- ✅ Safari (最新版) + +--- + +## 测试完成清单 + +- [ ] 场景 1:Agent 配置保存到后台 +- [ ] 场景 2:刷新页面后配置保持 +- [ ] 场景 3:快速切换按钮功能 +- [ ] 场景 4:Agent 模式对话测试 +- [ ] 场景 5:UI 样式验证 +- [ ] 数据库迁移成功 +- [ ] 后端 API 正常响应 +- [ ] 前端页面正常显示 +- [ ] 浏览器控制台无错误 +- [ ] 所有配置正确保存和加载 + +--- + +## 测试报告模板 + +```markdown +## Agent 配置功能测试报告 + +**测试日期:** YYYY-MM-DD +**测试人员:** [姓名] +**环境:** [开发/测试/生产] + +### 测试结果 + +| 场景 | 状态 | 备注 | +|------|------|------| +| Agent 配置保存 | ✅ / ❌ | | +| 配置持久化 | ✅ / ❌ | | +| 快速切换按钮 | ✅ / ❌ | | +| Agent 模式对话 | ✅ / ❌ | | +| UI 样式 | ✅ / ❌ | | + +### 发现的问题 + +1. [问题描述] + - **严重程度:** 高/中/低 + - **重现步骤:** ... + - **预期结果:** ... + - **实际结果:** ... + +### 建议改进 + +1. [改进建议] + +### 总体评价 + +[整体功能评价] +``` + +--- + +## 下一步 + +完成测试后,如果一切正常,可以: + +1. 提交代码到版本控制 +2. 创建 Pull Request +3. 通知团队进行 Code Review +4. 部署到测试环境 +5. 准备发布说明 + +--- + +**注意事项:** +- 测试过程中请记录所有错误和警告信息 +- 截图保存关键步骤和结果 +- 如有问题,请查看 AGENT_CONFIG_DEPLOYMENT.md 中的常见问题部分 + diff --git a/TEST_AGENT_STEPS.md b/TEST_AGENT_STEPS.md new file mode 100644 index 00000000..032d8fda --- /dev/null +++ b/TEST_AGENT_STEPS.md @@ -0,0 +1,221 @@ +# 测试Agent Steps功能 + +## 前置条件 + +1. 运行数据库迁移脚本: +```bash +# MySQL +mysql -u user -p database < migrations/mysql/05-add-agent-steps-to-messages.sql + +# ParadeDB/PostgreSQL +psql -U user -d database -f migrations/paradedb/05-add-agent-steps-to-messages.sql +``` + +2. 启动服务器: +```bash +./server +``` + +## 测试步骤 + +### 1. 创建启用Agent的会话 + +```bash +curl -X POST http://localhost:8080/api/v1/sessions \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 1" \ + -d '{ + "knowledge_base_id": "your-kb-id" + }' +``` + +### 2. 发送Agent查询(使用Agent模式) + +```bash +curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/agent/qa \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 1" \ + -d '{ + "query": "帮我搜索关于机器学习的知识" + }' +``` + +### 3. 加载消息历史并检查AgentSteps + +```bash +curl http://localhost:8080/api/v1/sessions/{session_id}/messages?limit=10 \ + -H "X-Tenant-ID: 1" +``` + +### 预期响应格式 + +```json +{ + "success": true, + "data": [ + { + "id": "message-uuid", + "session_id": "session-uuid", + "role": "user", + "content": "帮我搜索关于机器学习的知识", + "knowledge_references": [], + "is_completed": true, + "created_at": "2025-10-31T10:00:00Z", + "updated_at": "2025-10-31T10:00:00Z" + }, + { + "id": "message-uuid-2", + "session_id": "session-uuid", + "role": "assistant", + "content": "根据搜索结果,机器学习是...", + "knowledge_references": [ + { + "id": "chunk-id", + "content": "...", + "score": 0.95, + "knowledge_id": "doc-id", + "knowledge_title": "机器学习基础" + } + ], + "agent_steps": [ + { + "iteration": 0, + "thought": "用户想了解机器学习,我需要搜索相关知识库", + "tool_calls": [ + { + "id": "call_123", + "name": "search_knowledge", + "args": { + "query": "机器学习", + "knowledge_bases": ["kb-id"] + }, + "result": { + "success": true, + "output": "找到5个相关文档", + "data": { + "knowledge_refs": [...] + } + }, + "duration": 150 + } + ], + "observations": [ + "找到5个相关文档" + ], + "timestamp": "2025-10-31T10:00:01Z" + } + ], + "is_completed": true, + "created_at": "2025-10-31T10:00:00Z", + "updated_at": "2025-10-31T10:00:02Z" + } + ] +} +``` + +## 验证要点 + +### ✅ 用户对话历史(Message表) +- assistant消息包含`agent_steps`字段 +- 每个step包含: + - `iteration`: 迭代次数 + - `thought`: Agent的思考内容 + - `tool_calls`: 调用的工具列表 + - `observations`: 观察结果 + - `timestamp`: 时间戳 +- user消息不包含`agent_steps`字段(使用omitempty) + +### ✅ 大模型上下文分离 +后续对话时,传给LLM的上下文应该是: +```go +// 只包含简化的Role+Content +[ + {"role": "user", "content": "帮我搜索关于机器学习的知识"}, + {"role": "assistant", "content": "根据搜索结果,机器学习是..."} + // 不包含agent_steps信息 +] +``` + +可以通过日志验证: +``` +INFO: Loaded 2 history messages for agent context +``` + +### ✅ 数据库验证 + +```sql +-- 检查agent_steps列 +SELECT id, role, + CASE + WHEN agent_steps IS NULL THEN 'NULL' + ELSE JSON_EXTRACT(agent_steps, '$[0].iteration') + END as first_step_iteration +FROM messages +WHERE session_id = 'your-session-id' +ORDER BY created_at DESC; +``` + +## 常见问题 + +### Q1: agent_steps字段为空? +检查: +- Agent模式是否启用(使用`/agent/qa`端点) +- 数据库迁移是否执行成功 +- Handler的事件监听器是否注册 + +### Q2: 上下文是否包含agent_steps? +- 不应该包含! +- 检查`convertMessagesToChatHistory`函数 +- 确保只使用`Role`和`Content`字段 + +### Q3: 性能影响? +- `agent_steps`使用JSON存储,查询效率高 +- 前端可以按需展示或折叠步骤详情 +- 添加了`idx_messages_session_role`索引优化查询 + +## 前端集成建议 + +```typescript +interface Message { + id: string; + role: 'user' | 'assistant'; + content: string; + agent_steps?: AgentStep[]; // 可选字段 + knowledge_references?: Reference[]; +} + +interface AgentStep { + iteration: number; + thought: string; + tool_calls: ToolCall[]; + observations: string[]; + timestamp: string; +} + +// 展示Agent思考过程 +function renderAgentSteps(steps: AgentStep[]) { + return steps.map(step => ( +
+

步骤 {step.iteration + 1}

+

思考: {step.thought}

+ +
+ )); +} +``` + +## 总结 + +这个实现成功地: +1. ✅ 存储了Agent的详细执行步骤 +2. ✅ 每次任务只记录一个Q和A +3. ✅ 分离了用户历史和LLM上下文 +4. ✅ 避免了上下文重复 +5. ✅ 保持了向后兼容性 + diff --git a/client/README.md b/client/README.md index b236055a..2509aaf6 100644 --- a/client/README.md +++ b/client/README.md @@ -11,9 +11,10 @@ 3. **知识管理**:添加、获取和删除知识内容 4. **租户管理**:租户的CRUD操作 5. **知识问答**:支持普通问答和流式问答 -6. **分块管理**:查询、更新和删除知识分块 -7. **消息管理**:获取和删除会话消息 -8. **模型管理**:创建、获取、更新和删除模型 +6. **Agent问答**:支持基于Agent的智能问答,包含思考过程、工具调用和反思 +7. **分块管理**:查询、更新和删除知识分块 +8. **消息管理**:获取和删除会话消息 +9. **模型管理**:创建、获取、更新和删除模型 ## 使用方法 @@ -114,6 +115,122 @@ if err != nil { } ``` +### 示例:Agent智能问答 + +Agent问答提供更强大的智能对话能力,支持工具调用、思考过程展示和自我反思。 + +```go +// 创建Agent会话 +agentSession := apiClient.NewAgentSession(session.ID) + +// 进行Agent问答,带完整事件处理 +err := agentSession.Ask(context.Background(), "搜索机器学习相关知识并总结要点", + func(resp *client.AgentStreamResponse) error { + switch resp.ResponseType { + case client.AgentResponseTypeThinking: + // Agent正在思考 + if resp.Done { + fmt.Printf("💭 思考: %s\n", resp.Content) + } + + case client.AgentResponseTypeToolCall: + // Agent调用工具 + if resp.Data != nil { + toolName := resp.Data["tool_name"] + fmt.Printf("🔧 调用工具: %v\n", toolName) + } + + case client.AgentResponseTypeToolResult: + // 工具执行结果 + fmt.Printf("✓ 工具结果: %s\n", resp.Content) + + case client.AgentResponseTypeReferences: + // 知识引用 + if resp.KnowledgeReferences != nil { + fmt.Printf("📚 找到 %d 条相关知识\n", len(resp.KnowledgeReferences)) + for _, ref := range resp.KnowledgeReferences { + fmt.Printf(" - [%.3f] %s\n", ref.Score, ref.KnowledgeTitle) + } + } + + case client.AgentResponseTypeAnswer: + // 最终答案(流式输出) + fmt.Print(resp.Content) + if resp.Done { + fmt.Println() // 结束后换行 + } + + case client.AgentResponseTypeReflection: + // Agent的自我反思 + if resp.Done { + fmt.Printf("🤔 反思: %s\n", resp.Content) + } + + case client.AgentResponseTypeError: + // 错误信息 + fmt.Printf("❌ 错误: %s\n", resp.Content) + } + return nil + }) + +if err != nil { + // 处理错误 +} + +// 简化版:只关心最终答案 +var finalAnswer string +err = agentSession.Ask(context.Background(), "什么是深度学习?", + func(resp *client.AgentStreamResponse) error { + if resp.ResponseType == client.AgentResponseTypeAnswer { + finalAnswer += resp.Content + } + return nil + }) +``` + +### Agent事件类型说明 + +| 事件类型 | 说明 | 何时触发 | +|---------|------|---------| +| `AgentResponseTypeThinking` | Agent思考过程 | Agent分析问题和制定计划时 | +| `AgentResponseTypeToolCall` | 工具调用 | Agent决定使用某个工具时 | +| `AgentResponseTypeToolResult` | 工具执行结果 | 工具执行完成后 | +| `AgentResponseTypeReferences` | 知识引用 | 检索到相关知识时 | +| `AgentResponseTypeAnswer` | 最终答案 | Agent生成回答时(流式) | +| `AgentResponseTypeReflection` | 自我反思 | Agent评估自己的回答时 | +| `AgentResponseTypeError` | 错误 | 发生错误时 | + +### Agent问答测试工具 + +我们提供了一个交互式命令行工具用于测试Agent功能: + +```bash +cd client/cmd/agent_test +go build -o agent_test +./agent_test -url http://localhost:8080 -kb +``` + +该工具支持: +- 创建和管理会话 +- 交互式Agent问答 +- 实时显示所有Agent事件 +- 性能统计和调试信息 + +详细使用说明请参考 `client/cmd/agent_test/README.md`。 + +### Agent问答的高级用法 + +更多高级用法示例,请参考 `agent_example.go` 文件,包括: +- 基础Agent问答 +- 工具调用跟踪 +- 知识引用捕获 +- 完整事件跟踪 +- 自定义错误处理 +- 流取消控制 +- 多会话管理 + +``` + ### 示例:管理模型 ```go diff --git a/client/agent.go b/client/agent.go new file mode 100644 index 00000000..aebc1434 --- /dev/null +++ b/client/agent.go @@ -0,0 +1,137 @@ +// Package client provides the implementation for interacting with the WeKnora API +// The Agent related interfaces are used to manage agent-based question-answering +package client + +import ( + "bufio" + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "strings" +) + +// AgentQARequest agent Q&A request +type AgentQARequest struct { + Query string `json:"query"` +} + +// AgentResponseType defines the type of agent response +type AgentResponseType string + +const ( + AgentResponseTypeThinking AgentResponseType = "thinking" + AgentResponseTypeToolCall AgentResponseType = "tool_call" + AgentResponseTypeToolResult AgentResponseType = "tool_result" + AgentResponseTypeReferences AgentResponseType = "references" + AgentResponseTypeAnswer AgentResponseType = "answer" + AgentResponseTypeReflection AgentResponseType = "reflection" + AgentResponseTypeError AgentResponseType = "error" +) + +// AgentStreamResponse agent streaming response +type AgentStreamResponse struct { + ID string `json:"id"` // Unique identifier + ResponseType AgentResponseType `json:"response_type"` // Response type + Content string `json:"content,omitempty"` // Current content fragment + Done bool `json:"done"` // Whether completed + KnowledgeReferences []*SearchResult `json:"knowledge_references"` // Knowledge references + Data map[string]interface{} `json:"data,omitempty"` // Additional event data +} + +// AgentEventCallback is called for each streaming event +// Return error to stop processing the stream +type AgentEventCallback func(*AgentStreamResponse) error + +// AgentQAStream performs agent-based Q&A with SSE streaming +// The callback will be invoked for each event received from the server +func (c *Client) AgentQAStream(ctx context.Context, sessionID string, query string, callback AgentEventCallback) error { + path := fmt.Sprintf("/api/v1/agent-chat/%s", sessionID) + + request := &AgentQARequest{ + Query: query, + } + + resp, err := c.doRequest(ctx, http.MethodPost, path, request, nil) + if err != nil { + return fmt.Errorf("request failed: %w", err) + } + defer resp.Body.Close() + + if resp.StatusCode < 200 || resp.StatusCode >= 300 { + body, _ := io.ReadAll(resp.Body) + return fmt.Errorf("HTTP error %d: %s", resp.StatusCode, string(body)) + } + + // Process SSE stream + return c.processAgentSSEStream(resp.Body, callback) +} + +// processAgentSSEStream processes the SSE stream and invokes callback for each event +func (c *Client) processAgentSSEStream(reader io.Reader, callback AgentEventCallback) error { + scanner := bufio.NewScanner(reader) + var dataBuffer string + + for scanner.Scan() { + line := scanner.Text() + + // Empty line indicates the end of an event + if line == "" { + if dataBuffer != "" { + var streamResponse AgentStreamResponse + if err := json.Unmarshal([]byte(dataBuffer), &streamResponse); err != nil { + return fmt.Errorf("failed to parse SSE data: %w", err) + } + + if err := callback(&streamResponse); err != nil { + return err + } + dataBuffer = "" + } + continue + } + + // Process lines with event: prefix (for future use) + if strings.HasPrefix(line, "event:") { + // Event type is available but not currently used + // eventType := strings.TrimSpace(line[6:]) + continue + } + + // Process lines with data: prefix + if strings.HasPrefix(line, "data:") { + dataBuffer = strings.TrimSpace(line[5:]) // Remove "data:" prefix + } + } + + if err := scanner.Err(); err != nil { + return fmt.Errorf("failed to read SSE stream: %w", err) + } + + return nil +} + +// AgentSession is a wrapper for agent-based interactions +type AgentSession struct { + client *Client + sessionID string +} + +// NewAgentSession creates a new agent session wrapper +func (c *Client) NewAgentSession(sessionID string) *AgentSession { + return &AgentSession{ + client: c, + sessionID: sessionID, + } +} + +// Ask sends a query to the agent and processes the streaming response +func (as *AgentSession) Ask(ctx context.Context, query string, callback AgentEventCallback) error { + return as.client.AgentQAStream(ctx, as.sessionID, query, callback) +} + +// GetSessionID returns the session ID +func (as *AgentSession) GetSessionID() string { + return as.sessionID +} diff --git a/client/agent_example.go b/client/agent_example.go new file mode 100644 index 00000000..7261c101 --- /dev/null +++ b/client/agent_example.go @@ -0,0 +1,291 @@ +package client + +import ( + "context" + "fmt" + "log" + "time" +) + +// ExampleAgentQABasic demonstrates basic agent QA usage +func ExampleAgentQABasic() { + // Create client + client := NewClient("http://localhost:8080", WithTimeout(60*time.Second)) + + // Create a session + ctx := context.Background() + session, err := client.CreateSession(ctx, &CreateSessionRequest{ + KnowledgeBaseID: "your_kb_id", + SessionStrategy: &SessionStrategy{ + MaxRounds: 10, + EnableRewrite: false, + FallbackStrategy: "default", + EmbeddingTopK: 10, + }, + }) + if err != nil { + log.Fatalf("Failed to create session: %v", err) + } + + fmt.Printf("Session created: %s\n", session.ID) + + // Create agent session wrapper + agentSession := client.NewAgentSession(session.ID) + + // Ask a question + err = agentSession.Ask(ctx, "What is machine learning?", func(resp *AgentStreamResponse) error { + switch resp.ResponseType { + case AgentResponseTypeThinking: + if resp.Done { + fmt.Printf("Thinking: %s\n", resp.Content) + } + case AgentResponseTypeAnswer: + fmt.Print(resp.Content) // Print answer incrementally + if resp.Done { + fmt.Println() // New line at the end + } + } + return nil + }) + + if err != nil { + log.Fatalf("Agent QA failed: %v", err) + } +} + +// ExampleAgentQAWithToolTracking demonstrates tracking tool calls +func ExampleAgentQAWithToolTracking() { + client := NewClient("http://localhost:8080") + agentSession := client.NewAgentSession("existing_session_id") + + ctx := context.Background() + toolCalls := make([]string, 0) + + err := agentSession.Ask(ctx, "Search for information about neural networks", func(resp *AgentStreamResponse) error { + switch resp.ResponseType { + case AgentResponseTypeToolCall: + if resp.Data != nil { + if toolName, ok := resp.Data["tool_name"].(string); ok { + toolCalls = append(toolCalls, toolName) + fmt.Printf("Tool called: %s\n", toolName) + } + } + case AgentResponseTypeToolResult: + fmt.Printf("Tool result: %s\n", resp.Content) + case AgentResponseTypeAnswer: + if resp.Done { + fmt.Printf("Final answer: %s\n", resp.Content) + } + } + return nil + }) + + if err != nil { + log.Fatalf("Error: %v", err) + } + + fmt.Printf("Total tool calls: %d\n", len(toolCalls)) +} + +// ExampleAgentQAWithReferences demonstrates capturing knowledge references +func ExampleAgentQAWithReferences() { + client := NewClient("http://localhost:8080") + agentSession := client.NewAgentSession("existing_session_id") + + ctx := context.Background() + var references []*SearchResult + var finalAnswer string + + err := agentSession.Ask(ctx, "Explain deep learning", func(resp *AgentStreamResponse) error { + switch resp.ResponseType { + case AgentResponseTypeReferences: + if resp.KnowledgeReferences != nil { + references = append(references, resp.KnowledgeReferences...) + fmt.Printf("Found %d references\n", len(resp.KnowledgeReferences)) + } + case AgentResponseTypeAnswer: + finalAnswer += resp.Content + } + return nil + }) + + if err != nil { + log.Fatalf("Error: %v", err) + } + + // Process results + fmt.Println("Final Answer:", finalAnswer) + fmt.Printf("\nBased on %d knowledge references:\n", len(references)) + for i, ref := range references { + fmt.Printf("%d. [Score: %.3f] %s\n", i+1, ref.Score, ref.KnowledgeTitle) + } +} + +// ExampleAgentQAWithFullEventTracking demonstrates comprehensive event tracking +func ExampleAgentQAWithFullEventTracking() { + client := NewClient("http://localhost:8080") + agentSession := client.NewAgentSession("existing_session_id") + + ctx := context.Background() + + // Tracking state + state := struct { + thinking string + toolCalls []map[string]interface{} + toolResults []string + references []*SearchResult + answer string + reflections []string + errors []string + }{} + + err := agentSession.Ask(ctx, "Your question here", func(resp *AgentStreamResponse) error { + switch resp.ResponseType { + case AgentResponseTypeThinking: + state.thinking += resp.Content + if resp.Done { + fmt.Printf("💭 Thinking: %s\n", state.thinking) + } + + case AgentResponseTypeToolCall: + toolCall := map[string]interface{}{ + "name": resp.Data["tool_name"], + "arguments": resp.Data["arguments"], + } + state.toolCalls = append(state.toolCalls, toolCall) + fmt.Printf("🔧 Tool Call: %v\n", resp.Data["tool_name"]) + + case AgentResponseTypeToolResult: + state.toolResults = append(state.toolResults, resp.Content) + success := "✓" + if resp.Data != nil { + if s, ok := resp.Data["success"].(bool); ok && !s { + success = "✗" + } + } + fmt.Printf("%s Tool Result: %s\n", success, resp.Content) + + case AgentResponseTypeReferences: + if resp.KnowledgeReferences != nil { + state.references = append(state.references, resp.KnowledgeReferences...) + fmt.Printf("📚 References: %d\n", len(resp.KnowledgeReferences)) + } + + case AgentResponseTypeAnswer: + state.answer += resp.Content + if resp.Done { + fmt.Printf("📝 Answer: %s\n", state.answer) + } + + case AgentResponseTypeReflection: + if resp.Done { + state.reflections = append(state.reflections, resp.Content) + fmt.Printf("🤔 Reflection: %s\n", resp.Content) + } + + case AgentResponseTypeError: + state.errors = append(state.errors, resp.Content) + fmt.Printf("❌ Error: %s\n", resp.Content) + } + + return nil + }) + + if err != nil { + log.Fatalf("Error: %v", err) + } + + // Print summary + fmt.Println("\n=== Summary ===") + fmt.Printf("Tool Calls: %d\n", len(state.toolCalls)) + fmt.Printf("References: %d\n", len(state.references)) + fmt.Printf("Reflections: %d\n", len(state.reflections)) + fmt.Printf("Errors: %d\n", len(state.errors)) +} + +// ExampleAgentQAWithCustomErrorHandling demonstrates custom error handling +func ExampleAgentQAWithCustomErrorHandling() { + client := NewClient("http://localhost:8080") + agentSession := client.NewAgentSession("existing_session_id") + + ctx := context.Background() + hasError := false + + err := agentSession.Ask(ctx, "Your question", func(resp *AgentStreamResponse) error { + if resp.ResponseType == AgentResponseTypeError { + hasError = true + // Log error to your monitoring system + fmt.Printf("Agent error occurred: %s\n", resp.Content) + // You can return an error here to stop processing + // return fmt.Errorf("stopping due to error: %s", resp.Content) + } + return nil + }) + + if err != nil { + log.Printf("Stream error: %v", err) + } + + if hasError { + log.Println("Agent encountered errors during processing") + } +} + +// ExampleAgentQAStreamCancellation demonstrates canceling a stream +func ExampleAgentQAStreamCancellation() { + client := NewClient("http://localhost:8080") + agentSession := client.NewAgentSession("existing_session_id") + + // Create a context with timeout + ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) + defer cancel() + + // Or cancel based on a condition + maxToolCalls := 5 + toolCallCount := 0 + + err := agentSession.Ask(ctx, "Complex query that might take long", func(resp *AgentStreamResponse) error { + if resp.ResponseType == AgentResponseTypeToolCall { + toolCallCount++ + if toolCallCount > maxToolCalls { + // Stop processing if too many tool calls + return fmt.Errorf("too many tool calls: %d", toolCallCount) + } + } + return nil + }) + + if err != nil { + log.Printf("Stream stopped: %v", err) + } +} + +// ExampleMultipleAgentSessions demonstrates managing multiple agent sessions +func ExampleMultipleAgentSessions() { + client := NewClient("http://localhost:8080") + + ctx := context.Background() + + // Create multiple sessions for different purposes + sessions := map[string]*AgentSession{ + "technical": client.NewAgentSession("session_id_1"), + "general": client.NewAgentSession("session_id_2"), + "customer": client.NewAgentSession("session_id_3"), + } + + // Use appropriate session based on query type + queryType := "technical" + query := "How does gradient descent work?" + + if session, ok := sessions[queryType]; ok { + err := session.Ask(ctx, query, func(resp *AgentStreamResponse) error { + if resp.ResponseType == AgentResponseTypeAnswer && resp.Done { + fmt.Printf("[%s] Answer: %s\n", queryType, resp.Content) + } + return nil + }) + if err != nil { + log.Printf("Error in %s session: %v", queryType, err) + } + } +} diff --git a/client/cmd/agent_test/Makefile b/client/cmd/agent_test/Makefile new file mode 100644 index 00000000..dd55bab8 --- /dev/null +++ b/client/cmd/agent_test/Makefile @@ -0,0 +1,75 @@ +.PHONY: build run clean help + +# Binary name +BINARY=agent_test + +# Build parameters +GOOS?=$(shell go env GOOS) +GOARCH?=$(shell go env GOARCH) + +# Default target +all: build + +# Build the binary +build: + @echo "Building $(BINARY)..." + @go build -o $(BINARY) . + @echo "Build complete: ./$(BINARY)" + +# Build and run with default settings +run: build + @./$(BINARY) + +# Run with custom parameters +run-local: build + @./$(BINARY) -url http://localhost:8080 -kb $(KB_ID) + +# Run with existing session +run-session: build + @./$(BINARY) -url http://localhost:8080 -session $(SESSION_ID) + +# Clean build artifacts +clean: + @echo "Cleaning..." + @rm -f $(BINARY) + @echo "Clean complete" + +# Install dependencies +deps: + @echo "Installing dependencies..." + @go mod download + @go mod tidy + @echo "Dependencies installed" + +# Run tests +test: + @go test -v ./... + +# Build for multiple platforms +build-all: + @echo "Building for multiple platforms..." + @GOOS=linux GOARCH=amd64 go build -o $(BINARY)-linux-amd64 . + @GOOS=darwin GOARCH=amd64 go build -o $(BINARY)-darwin-amd64 . + @GOOS=darwin GOARCH=arm64 go build -o $(BINARY)-darwin-arm64 . + @GOOS=windows GOARCH=amd64 go build -o $(BINARY)-windows-amd64.exe . + @echo "Build complete for all platforms" + +# Help +help: + @echo "Available targets:" + @echo " make build - Build the binary" + @echo " make run - Build and run with no parameters" + @echo " make run-local - Build and run with local server (requires KB_ID env var)" + @echo " make run-session - Build and run with existing session (requires SESSION_ID env var)" + @echo " make clean - Remove build artifacts" + @echo " make deps - Install dependencies" + @echo " make test - Run tests" + @echo " make build-all - Build for multiple platforms" + @echo " make help - Show this help message" + @echo "" + @echo "Examples:" + @echo " make build" + @echo " KB_ID=kb_123 make run-local" + @echo " SESSION_ID=sess_456 make run-session" + @echo " ./$(BINARY) -url http://localhost:8080 -kb kb_123 -token mytoken" + diff --git a/client/cmd/agent_test/QUICKSTART.md b/client/cmd/agent_test/QUICKSTART.md new file mode 100644 index 00000000..cb6eb01f --- /dev/null +++ b/client/cmd/agent_test/QUICKSTART.md @@ -0,0 +1,293 @@ +# Quick Start Guide + +Get started with the WeKnora Agent Test Tool in 5 minutes! + +## Prerequisites + +- Go 1.21 or higher +- Access to a running WeKnora instance +- A knowledge base ID (or create one through the tool) + +## Quick Start + +### Option 1: Using the Build Script (Recommended) + +```bash +# 1. Navigate to the tool directory +cd client/cmd/agent_test + +# 2. Build and run with your knowledge base +./run.sh -k kb_your_knowledge_base_id + +# Or with a remote server +./run.sh -u https://api.weknora.com -k kb_12345 -t your_token +``` + +### Option 2: Using Make + +```bash +# Build the binary +make build + +# Run with environment variables +KB_ID=kb_12345 make run-local + +# Or run the binary directly +./agent_test -url http://localhost:8080 -kb kb_12345 +``` + +### Option 3: Direct Go Build + +```bash +# Build +go build -o agent_test . + +# Run +./agent_test -url http://localhost:8080 -kb kb_your_knowledge_base_id +``` + +## First Steps + +Once the tool is running, you'll see an interactive prompt: + +``` +╔════════════════════════════════════════════════════════════╗ +║ WeKnora Agent QA Testing Tool ║ +╚════════════════════════════════════════════════════════════╝ + +[No Session] > +``` + +### 1. Create a New Session + +``` +> new +``` + +The tool will create a new session and show you the session ID. + +### 2. Ask Your First Question + +``` +[Session: abc12345] > ask What is machine learning? +``` + +You'll see real-time output showing: +- 💭 Agent thinking process +- 🔧 Tool calls (if any) +- 📚 Knowledge references +- 📝 Final answer +- 🤔 Reflections (if any) + +### 3. Continue the Conversation + +``` +[Session: abc12345] > ask Can you give me examples? +[Session: abc12345] > ask How does it work? +``` + +### 4. View Session Info + +``` +[Session: abc12345] > info +``` + +### 5. List All Sessions + +``` +[Session: abc12345] > sessions +``` + +### 6. Exit + +``` +[Session: abc12345] > exit +``` + +## Command Reference + +| Command | Description | Example | +|---------|-------------|---------| +| `new` | Create a new session | `> new` | +| `ask ` | Ask the agent a question | `> ask What is AI?` | +| `info` | Show current session details | `> info` | +| `sessions` | List all your sessions | `> sessions` | +| `switch ` | Switch to another session | `> switch sess_123` | +| `help` | Show help message | `> help` | +| `exit` or `quit` | Exit the program | `> exit` | + +## Example Session + +```bash +$ ./run.sh -k kb_ml_docs + +[No Session] > new +✓ Session created successfully! + Session ID: sess_a1b2c3d4 + Knowledge Base: kb_ml_docs + Created At: 2025-11-03T10:00:00Z + +[Session: sess_a1b] > ask What is a neural network? + +╔═══ Agent Processing ═══╗ +Query: What is a neural network? + +💭 Thinking: I need to search the knowledge base for information about neural networks... + +🔧 Tool Call: search_knowledge + Arguments: map[query:neural network definition] + +✓ Tool Result: + Found 3 relevant knowledge chunks + +📚 Knowledge References: Found 3 reference(s) + 1. [Score: 0.892] A neural network is a series of algorithms... + Knowledge: Neural Networks 101 (Chunk: 2) + 2. [Score: 0.856] Neural networks mimic biological neurons... + Knowledge: Deep Learning Basics (Chunk: 5) + 3. [Score: 0.834] The structure consists of layers... + Knowledge: ML Architectures (Chunk: 8) + +📝 Final Answer: +A neural network is a computing system inspired by biological neural networks +in animal brains. It consists of interconnected nodes (artificial neurons) +organized in layers that process information using a connectionist approach +to computation. Neural networks learn to perform tasks by considering examples, +generally without being programmed with task-specific rules. + +🤔 Reflection: I successfully found relevant information in the knowledge base +and provided a comprehensive answer covering the definition, structure, and +learning mechanism of neural networks. + +╔═══ Summary ═══╗ +Duration: 2.34s +Tool Calls: 1 (search_knowledge) +References: 3 +Reflections: 1 +╚═══════════════╝ + +[Session: sess_a1b] > ask What are the main types? + +╔═══ Agent Processing ═══╗ +Query: What are the main types? + +💭 Thinking: The user is asking about types of neural networks based on the +previous context... + +[... continuing the conversation ...] +``` + +## Testing Scenarios + +We provide a test scenarios script for common testing patterns: + +```bash +# Run interactive scenario menu +./test_scenarios.sh + +# Run a specific scenario +./test_scenarios.sh 1 # Basic Q&A +./test_scenarios.sh 2 # Complex queries +./test_scenarios.sh 3 # Multi-turn conversation +``` + +## Configuration with Environment Variables + +Create a configuration file for repeated use: + +```bash +# Create config file +cat > config.env << EOF +export WEKNORA_URL=http://localhost:8080 +export WEKNORA_KB_ID=kb_your_knowledge_base_id +export WEKNORA_TOKEN=your_token_if_needed +EOF + +# Load and run +source config.env +./run.sh +``` + +## Troubleshooting + +### "Connection refused" +- Make sure WeKnora server is running +- Check the URL is correct +- Verify network connectivity + +### "Knowledge base not found" +- Verify your knowledge base ID is correct +- Check you have access to the knowledge base +- Ensure the knowledge base has been initialized + +### "Session not found" +- The session may have expired or been deleted +- Create a new session with `new` command + +### No tool calls happening +- Check your knowledge base has content +- Verify the agent configuration includes tool definitions +- Look for error messages in the output + +## Advanced Usage + +### Using with Docker + +If WeKnora is running in Docker: + +```bash +# Get the container's IP or use host networking +./agent_test -url http://localhost:8080 -kb kb_123 +``` + +### Testing with Production + +```bash +# Use production URL with authentication +./agent_test \ + -url https://api.weknora.com \ + -token $PROD_TOKEN \ + -kb kb_prod_123 +``` + +### Continuing an Existing Session + +```bash +# Skip session creation and continue existing one +./agent_test -url http://localhost:8080 -session sess_existing_id +``` + +### Batch Testing + +```bash +# Pipe commands for automated testing +echo -e "new\nask What is AI?\ninfo\nexit" | ./agent_test -url http://localhost:8080 -kb kb_123 +``` + +## Next Steps + +- Read the full [README.md](README.md) for detailed documentation +- Check [agent_example.go](../../agent_example.go) for code examples +- Explore the [client package documentation](../../README.md) +- Review agent events and response types in the main README + +## Getting Help + +If you encounter issues: + +1. Check the [README.md](README.md) for detailed documentation +2. Review the error messages - they usually indicate the problem +3. Verify your configuration (URL, KB ID, token) +4. Check WeKnora server logs for backend issues +5. Use `info` command to check session state + +## Tips + +- **Start Simple**: Begin with basic questions to verify connectivity +- **Use Info**: The `info` command shows valuable session configuration +- **Watch Events**: Pay attention to all event types to understand agent behavior +- **Check References**: Knowledge references show if retrieval is working correctly +- **Monitor Performance**: The summary shows timing and tool usage statistics + +Happy testing! 🚀 + diff --git a/client/cmd/agent_test/README.md b/client/cmd/agent_test/README.md new file mode 100644 index 00000000..9c004b3c --- /dev/null +++ b/client/cmd/agent_test/README.md @@ -0,0 +1,307 @@ +# WeKnora Agent QA Testing Tool + +An interactive command-line tool for testing and debugging WeKnora's Agent QA functionality. + +## Features + +- 🎯 Interactive terminal interface with colored output +- 📊 Real-time streaming of agent events +- 🔧 Display tool calls and their results +- 💭 Show agent thinking process +- 📚 Display knowledge references with scores +- 🤔 Capture agent reflections +- 📝 Track complete conversation flow +- ⏱️ Performance metrics and timing +- 🔄 Session management (create, switch, list) + +## Installation + +```bash +cd client/cmd/agent_test +go build -o agent_test +``` + +## Usage + +### Basic Usage + +```bash +# Start with a new session +./agent_test -url http://localhost:8080 -kb + +# With authentication token +./agent_test -url http://localhost:8080 -token -kb + +# Use existing session +./agent_test -url http://localhost:8080 -session +``` + +### Command Line Flags + +- `-url` : WeKnora API base URL (default: http://localhost:8080) +- `-token` : API authentication token (optional) +- `-kb` : Knowledge base ID (required for creating new sessions) +- `-session` : Existing session ID to continue conversation (optional) + +### Interactive Commands + +Once the tool is running, you can use these commands: + +#### Session Management + +- `new` - Create a new session + ``` + > new + ``` + +- `sessions` - List all sessions + ``` + > sessions + ``` + +- `switch ` - Switch to another session + ``` + > switch abc123... + ``` + +- `info` - Show current session information + ``` + > info + ``` + +#### Agent Interaction + +- `ask ` - Ask the agent a question + ``` + > ask What is machine learning? + > ask How can I improve model accuracy? + > ask Explain the difference between supervised and unsupervised learning + ``` + +#### General + +- `help` - Show help message +- `exit` or `quit` - Exit the program + +## Agent Events + +The tool displays various agent events in real-time: + +### 💭 Thinking Events +Shows the agent's internal reasoning process +``` +💭 Thinking: Let me search for information about machine learning... +``` + +### 🔧 Tool Call Events +Displays when the agent calls a tool +``` +🔧 Tool Call: search_knowledge + Arguments: {"query": "machine learning definition"} +``` + +### ✓ Tool Result Events +Shows the results from tool execution +``` +✓ Tool Result: + Found 5 relevant knowledge chunks +``` + +### 📚 Knowledge References +Lists retrieved knowledge with relevance scores +``` +📚 Knowledge References: Found 3 reference(s) + 1. [Score: 0.875] Machine learning is a subset of artificial intelligence... + Knowledge: ML Basics (Chunk: 2) + 2. [Score: 0.823] There are three main types of machine learning... + Knowledge: ML Types (Chunk: 5) +``` + +### 📝 Final Answer +The agent's complete response +``` +📝 Final Answer: +Machine learning is an application of artificial intelligence that provides +systems the ability to automatically learn and improve from experience... +``` + +### 🤔 Reflection Events +Agent's self-reflection on its responses +``` +🤔 Reflection: I provided a comprehensive answer covering the main aspects +of machine learning with relevant examples. +``` + +### Summary +At the end of each query, a summary is displayed: +``` +╔═══ Summary ═══╗ +Duration: 3.45s +Tool Calls: 2 (search_knowledge, format_response) +References: 3 +Reflections: 1 +╚═══════════════╝ +``` + +## Example Session + +```bash +$ ./agent_test -url http://localhost:8080 -kb kb_12345 + +╔════════════════════════════════════════════════════════════╗ +║ WeKnora Agent QA Testing Tool ║ +╚════════════════════════════════════════════════════════════╝ + +[No Session] > new +✓ Session created successfully! + Session ID: sess_abc123xyz + Knowledge Base: kb_12345 + Created At: 2025-11-03T10:30:00Z + +[Session: sess_abc] > ask What is neural networks? + +╔═══ Agent Processing ═══╗ +Query: What is neural networks? + +💭 Thinking: I need to search for information about neural networks... + +🔧 Tool Call: search_knowledge + Arguments: map[query:neural networks] + +✓ Tool Result: + Successfully retrieved 3 relevant chunks + +📚 Knowledge References: Found 3 reference(s) + 1. [Score: 0.892] A neural network is a series of algorithms... + Knowledge: Deep Learning Fundamentals (Chunk: 1) + 2. [Score: 0.856] Neural networks consist of layers of neurons... + Knowledge: Neural Network Architecture (Chunk: 3) + +📝 Final Answer: +Neural networks are computing systems inspired by biological neural networks +that constitute animal brains. They consist of interconnected nodes (neurons) +organized in layers... + +🤔 Reflection: The answer provides a clear definition with supporting +references from the knowledge base. + +╔═══ Summary ═══╗ +Duration: 2.87s +Tool Calls: 1 (search_knowledge) +References: 3 +Reflections: 1 +╚═══════════════╝ + +[Session: sess_abc] > info + +╔═══ Session Information ═══╗ +Session ID: sess_abc123xyz +Knowledge Base ID: kb_12345 +Max Rounds: 10 +Created At: 2025-11-03T10:30:00Z +╚═══════════════════════════╝ + +[Session: sess_abc] > exit + +Goodbye! +``` + +## Testing Scenarios + +### 1. Basic Q&A +Test simple question-answering with knowledge retrieval: +``` +> ask What is machine learning? +``` + +### 2. Multi-Turn Conversation +Test context awareness: +``` +> ask What is supervised learning? +> ask Can you give me some examples? +> ask How does it differ from unsupervised learning? +``` + +### 3. Complex Queries +Test agent's reasoning capabilities: +``` +> ask Compare and contrast supervised learning and reinforcement learning, including their use cases +``` + +### 4. Tool Usage +Test tool calling and reflection: +``` +> ask Search for information about deep learning and summarize the key concepts +``` + +### 5. Edge Cases +Test error handling: +``` +> ask [empty query] +> ask [very long query with 1000+ characters] +``` + +## Debugging + +The tool displays detailed information for debugging: + +1. **Event Timing**: Track how long each phase takes +2. **Tool Arguments**: See exactly what parameters are passed to tools +3. **Knowledge Scores**: Evaluate retrieval quality +4. **Error Messages**: Clear error reporting for failed operations +5. **Session State**: Monitor session configuration and status + +## Troubleshooting + +### Connection Issues +``` +✗ Request failed: connection refused +``` +- Check if WeKnora server is running +- Verify the URL is correct +- Check network connectivity + +### Authentication Errors +``` +✗ HTTP error 401: Unauthorized +``` +- Verify your API token is valid +- Check token hasn't expired + +### Session Not Found +``` +✗ Failed to get session info: session not found +``` +- Session may have been deleted +- Create a new session with `new` command + +## Advanced Usage + +### Using with Different Environments + +Development: +```bash +./agent_test -url http://localhost:8080 -kb kb_dev +``` + +Staging: +```bash +./agent_test -url https://staging.weknora.com -token $STAGING_TOKEN -kb kb_staging +``` + +Production: +```bash +./agent_test -url https://api.weknora.com -token $PROD_TOKEN -kb kb_prod +``` + +### Scripting + +You can pipe commands for automated testing: +```bash +echo -e "new\nask What is AI?\nexit" | ./agent_test -url http://localhost:8080 -kb kb_test +``` + +## License + +Copyright (c) 2025 Tencent. All rights reserved. + diff --git a/client/cmd/agent_test/go.mod b/client/cmd/agent_test/go.mod new file mode 100644 index 00000000..6bbbe051 --- /dev/null +++ b/client/cmd/agent_test/go.mod @@ -0,0 +1,7 @@ +module github.com/Tencent/WeKnora/client/cmd/agent_test + +go 1.24.2 + +require github.com/Tencent/WeKnora/client v0.0.0 + +replace github.com/Tencent/WeKnora/client => ../.. diff --git a/client/cmd/agent_test/main.go b/client/cmd/agent_test/main.go new file mode 100644 index 00000000..c3877527 --- /dev/null +++ b/client/cmd/agent_test/main.go @@ -0,0 +1,369 @@ +package main + +import ( + "bufio" + "context" + "flag" + "fmt" + "os" + "strings" + "time" + + "github.com/Tencent/WeKnora/client" +) + +// Colors for terminal output +const ( + ColorReset = "\033[0m" + ColorRed = "\033[31m" + ColorGreen = "\033[32m" + ColorYellow = "\033[33m" + ColorBlue = "\033[34m" + ColorMagenta = "\033[35m" + ColorCyan = "\033[36m" + ColorWhite = "\033[37m" + ColorBold = "\033[1m" +) + +// Config holds the configuration +type Config struct { + BaseURL string + Token string + KnowledgeBaseID string +} + +// CLI represents the command line interface +type CLI struct { + client *client.Client + config *Config + currentSessionID string + agentSession *client.AgentSession +} + +func main() { + baseURL := flag.String("url", "http://localhost:8080", "WeKnora API base URL") + token := flag.String("token", "", "API authentication token") + kbID := flag.String("kb", "", "Knowledge base ID") + sessionID := flag.String("session", "", "Existing session ID (optional)") + + flag.Parse() + + config := &Config{ + BaseURL: *baseURL, + Token: *token, + KnowledgeBaseID: *kbID, + } + + cli := NewCLI(config) + + // Use existing session if provided + if *sessionID != "" { + cli.currentSessionID = *sessionID + cli.agentSession = cli.client.NewAgentSession(*sessionID) + fmt.Printf("%s✓ Using existing session: %s%s\n\n", ColorGreen, *sessionID, ColorReset) + } + + cli.Run() +} + +// NewCLI creates a new CLI instance +func NewCLI(config *Config) *CLI { + clientOptions := []client.ClientOption{ + client.WithTimeout(120 * time.Second), + } + if config.Token != "" { + clientOptions = append(clientOptions, client.WithToken(config.Token)) + } + + return &CLI{ + client: client.NewClient(config.BaseURL, clientOptions...), + config: config, + } +} + +// Run starts the interactive CLI +func (cli *CLI) Run() { + cli.printWelcome() + + reader := bufio.NewReader(os.Stdin) + + for { + fmt.Print(cli.getPrompt()) + + input, err := reader.ReadString('\n') + if err != nil { + fmt.Printf("%sError reading input: %v%s\n", ColorRed, err, ColorReset) + continue + } + + input = strings.TrimSpace(input) + if input == "" { + continue + } + + if !cli.handleCommand(input) { + break + } + } + + fmt.Printf("\n%sGoodbye!%s\n", ColorCyan, ColorReset) +} + +func (cli *CLI) getPrompt() string { + if cli.currentSessionID != "" { + return fmt.Sprintf("%s[Session: %s]%s > ", ColorBlue, cli.currentSessionID[:8], ColorReset) + } + return fmt.Sprintf("%s[No Session]%s > ", ColorYellow, ColorReset) +} + +func (cli *CLI) printWelcome() { + fmt.Printf("\n%s╔════════════════════════════════════════════════════════════╗%s\n", ColorCyan, ColorReset) + fmt.Printf("%s║ WeKnora Agent QA Testing Tool ║%s\n", ColorCyan, ColorReset) + fmt.Printf("%s╚════════════════════════════════════════════════════════════╝%s\n\n", ColorCyan, ColorReset) + fmt.Printf("%sAvailable commands:%s\n", ColorBold, ColorReset) + fmt.Printf(" %snew%s - Create a new session\n", ColorGreen, ColorReset) + fmt.Printf(" %sask %s - Ask agent a question\n", ColorGreen, ColorReset) + fmt.Printf(" %sinfo%s - Show current session info\n", ColorGreen, ColorReset) + fmt.Printf(" %ssessions%s - List all sessions\n", ColorGreen, ColorReset) + fmt.Printf(" %sswitch %s - Switch to another session\n", ColorGreen, ColorReset) + fmt.Printf(" %shelp%s - Show this help message\n", ColorGreen, ColorReset) + fmt.Printf(" %sexit/quit%s - Exit the program\n\n", ColorGreen, ColorReset) +} + +func (cli *CLI) handleCommand(input string) bool { + parts := strings.SplitN(input, " ", 2) + command := strings.ToLower(parts[0]) + + switch command { + case "help": + cli.printWelcome() + case "new": + cli.createNewSession() + case "ask": + if len(parts) < 2 { + fmt.Printf("%sUsage: ask %s\n", ColorRed, ColorReset) + return true + } + cli.askQuestion(parts[1]) + case "info": + cli.showSessionInfo() + case "sessions": + cli.listSessions() + case "switch": + if len(parts) < 2 { + fmt.Printf("%sUsage: switch %s\n", ColorRed, ColorReset) + return true + } + cli.switchSession(parts[1]) + case "exit", "quit": + return false + default: + fmt.Printf("%sUnknown command: %s. Type 'help' for available commands.%s\n", ColorRed, command, ColorReset) + } + + return true +} + +func (cli *CLI) createNewSession() { + if cli.config.KnowledgeBaseID == "" { + fmt.Printf("%sError: Knowledge base ID is required. Use -kb flag.%s\n", ColorRed, ColorReset) + return + } + + fmt.Printf("%sCreating new session...%s\n", ColorYellow, ColorReset) + + ctx := context.Background() + request := &client.CreateSessionRequest{ + KnowledgeBaseID: cli.config.KnowledgeBaseID, + SessionStrategy: &client.SessionStrategy{ + MaxRounds: 10, + EnableRewrite: false, + FallbackStrategy: "default", + EmbeddingTopK: 10, + }, + } + + session, err := cli.client.CreateSession(ctx, request) + if err != nil { + fmt.Printf("%s✗ Failed to create session: %v%s\n", ColorRed, err, ColorReset) + return + } + + cli.currentSessionID = session.ID + cli.agentSession = cli.client.NewAgentSession(session.ID) + + fmt.Printf("%s✓ Session created successfully!%s\n", ColorGreen, ColorReset) + fmt.Printf(" Session ID: %s%s%s\n", ColorCyan, session.ID, ColorReset) + fmt.Printf(" Knowledge Base: %s%s%s\n", ColorCyan, session.KnowledgeBaseID, ColorReset) + fmt.Printf(" Created At: %s%s%s\n\n", ColorCyan, session.CreatedAt, ColorReset) +} + +func (cli *CLI) askQuestion(query string) { + if cli.agentSession == nil { + fmt.Printf("%sError: No active session. Create one with 'new' command.%s\n", ColorRed, ColorReset) + return + } + + fmt.Printf("\n%s╔═══ Agent Processing ═══╗%s\n", ColorCyan, ColorReset) + fmt.Printf("%sQuery: %s%s%s\n\n", ColorBold, ColorWhite, query, ColorReset) + + ctx := context.Background() + + var ( + thinkingContent string + finalAnswer string + references []*client.SearchResult + toolCalls []string + reflections []string + ) + + startTime := time.Now() + + err := cli.agentSession.Ask(ctx, query, func(resp *client.AgentStreamResponse) error { + switch resp.ResponseType { + case client.AgentResponseTypeThinking: + thinkingContent += resp.Content + if resp.Done { + fmt.Printf("%s💭 Thinking:%s %s\n\n", ColorYellow, ColorReset, thinkingContent) + thinkingContent = "" + } + + case client.AgentResponseTypeToolCall: + toolName := "Unknown" + if resp.Data != nil { + if name, ok := resp.Data["tool_name"].(string); ok { + toolName = name + } + } + toolCalls = append(toolCalls, toolName) + fmt.Printf("%s🔧 Tool Call:%s %s\n", ColorMagenta, ColorReset, toolName) + if resp.Data != nil { + if args, ok := resp.Data["arguments"]; ok { + fmt.Printf(" Arguments: %v\n", args) + } + } + + case client.AgentResponseTypeToolResult: + fmt.Printf("%s✓ Tool Result:%s\n", ColorGreen, ColorReset) + fmt.Printf(" %s\n\n", resp.Content) + + case client.AgentResponseTypeReferences: + if resp.KnowledgeReferences != nil { + references = append(references, resp.KnowledgeReferences...) + fmt.Printf("%s📚 Knowledge References:%s Found %d reference(s)\n", ColorCyan, ColorReset, len(resp.KnowledgeReferences)) + for i, ref := range resp.KnowledgeReferences { + fmt.Printf(" %d. [Score: %.3f] %s\n", i+1, ref.Score, truncateString(ref.Content, 80)) + fmt.Printf(" Knowledge: %s (Chunk: %d)\n", ref.KnowledgeTitle, ref.ChunkIndex) + } + fmt.Println() + } + + case client.AgentResponseTypeAnswer: + finalAnswer += resp.Content + if resp.Done { + fmt.Printf("%s📝 Final Answer:%s\n", ColorGreen, ColorReset) + fmt.Printf("%s\n\n", finalAnswer) + } + + case client.AgentResponseTypeReflection: + if resp.Done && resp.Content != "" { + reflections = append(reflections, resp.Content) + fmt.Printf("%s🤔 Reflection:%s %s\n\n", ColorBlue, ColorReset, resp.Content) + } + + case client.AgentResponseTypeError: + fmt.Printf("%s✗ Error:%s %s\n\n", ColorRed, ColorReset, resp.Content) + } + + return nil + }) + + if err != nil { + fmt.Printf("%s✗ Agent QA failed: %v%s\n", ColorRed, err, ColorReset) + return + } + + duration := time.Since(startTime) + + // Print summary + fmt.Printf("%s╔═══ Summary ═══╗%s\n", ColorCyan, ColorReset) + fmt.Printf("Duration: %s%.2fs%s\n", ColorCyan, duration.Seconds(), ColorReset) + fmt.Printf("Tool Calls: %s%d%s", ColorCyan, len(toolCalls), ColorReset) + if len(toolCalls) > 0 { + fmt.Printf(" (%s)", strings.Join(toolCalls, ", ")) + } + fmt.Println() + fmt.Printf("References: %s%d%s\n", ColorCyan, len(references), ColorReset) + fmt.Printf("Reflections: %s%d%s\n", ColorCyan, len(reflections), ColorReset) + fmt.Printf("%s╚═══════════════╝%s\n\n", ColorCyan, ColorReset) +} + +func (cli *CLI) showSessionInfo() { + if cli.currentSessionID == "" { + fmt.Printf("%sNo active session.%s\n", ColorYellow, ColorReset) + return + } + + ctx := context.Background() + session, err := cli.client.GetSession(ctx, cli.currentSessionID) + if err != nil { + fmt.Printf("%s✗ Failed to get session info: %v%s\n", ColorRed, err, ColorReset) + return + } + + fmt.Printf("\n%s╔═══ Session Information ═══╗%s\n", ColorCyan, ColorReset) + fmt.Printf("Session ID: %s%s%s\n", ColorWhite, session.ID, ColorReset) + fmt.Printf("Title: %s%s%s\n", ColorWhite, session.Title, ColorReset) + fmt.Printf("Knowledge Base ID: %s%s%s\n", ColorWhite, session.KnowledgeBaseID, ColorReset) + fmt.Printf("Max Rounds: %s%d%s\n", ColorWhite, session.MaxRounds, ColorReset) + fmt.Printf("Enable Rewrite: %s%v%s\n", ColorWhite, session.EnableRewrite, ColorReset) + fmt.Printf("Summary Model: %s%s%s\n", ColorWhite, session.SummaryModelID, ColorReset) + fmt.Printf("Created At: %s%s%s\n", ColorWhite, session.CreatedAt, ColorReset) + fmt.Printf("Updated At: %s%s%s\n", ColorWhite, session.UpdatedAt, ColorReset) + fmt.Printf("%s╚═══════════════════════════╝%s\n\n", ColorCyan, ColorReset) +} + +func (cli *CLI) listSessions() { + ctx := context.Background() + sessions, total, err := cli.client.GetSessionsByTenant(ctx, 1, 10) + if err != nil { + fmt.Printf("%s✗ Failed to list sessions: %v%s\n", ColorRed, err, ColorReset) + return + } + + fmt.Printf("\n%s╔═══ Sessions (Total: %d) ═══╗%s\n", ColorCyan, total, ColorReset) + for i, session := range sessions { + marker := " " + if session.ID == cli.currentSessionID { + marker = "►" + } + fmt.Printf("%s%s %d. %s%s\n", ColorGreen, marker, i+1, session.ID, ColorReset) + fmt.Printf(" Title: %s\n", session.Title) + fmt.Printf(" KB: %s\n", session.KnowledgeBaseID) + fmt.Printf(" Created: %s\n", session.CreatedAt) + fmt.Println() + } + fmt.Printf("%s╚════════════════════════════╝%s\n\n", ColorCyan, ColorReset) +} + +func (cli *CLI) switchSession(sessionID string) { + ctx := context.Background() + session, err := cli.client.GetSession(ctx, sessionID) + if err != nil { + fmt.Printf("%s✗ Failed to switch session: %v%s\n", ColorRed, err, ColorReset) + return + } + + cli.currentSessionID = session.ID + cli.agentSession = cli.client.NewAgentSession(session.ID) + + fmt.Printf("%s✓ Switched to session: %s%s\n", ColorGreen, session.ID, ColorReset) +} + +func truncateString(s string, maxLen int) string { + s = strings.ReplaceAll(s, "\n", " ") + if len(s) <= maxLen { + return s + } + return s[:maxLen] + "..." +} diff --git a/client/cmd/agent_test/run.sh b/client/cmd/agent_test/run.sh new file mode 100755 index 00000000..906ed5af --- /dev/null +++ b/client/cmd/agent_test/run.sh @@ -0,0 +1,172 @@ +#!/bin/bash + +# WeKnora Agent Test Tool - Quick Start Script +# This script helps you quickly build and run the agent test tool + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Default values +DEFAULT_URL="http://localhost:8080" +BINARY_NAME="agent_test" + +# Function to print colored output +print_info() { + echo -e "${BLUE}ℹ${NC} $1" +} + +print_success() { + echo -e "${GREEN}✓${NC} $1" +} + +print_warning() { + echo -e "${YELLOW}⚠${NC} $1" +} + +print_error() { + echo -e "${RED}✗${NC} $1" +} + +# Function to build the binary +build() { + print_info "Building agent test tool..." + if go build -o "$BINARY_NAME" .; then + print_success "Build successful!" + return 0 + else + print_error "Build failed!" + return 1 + fi +} + +# Function to show usage +usage() { + cat << EOF +WeKnora Agent Test Tool - Quick Start Script + +Usage: + $0 [OPTIONS] + +Options: + -u, --url URL WeKnora API URL (default: $DEFAULT_URL) + -k, --kb KB_ID Knowledge Base ID + -s, --session ID Existing Session ID + -t, --token TOKEN API authentication token + -b, --build-only Only build, don't run + -h, --help Show this help message + +Examples: + # Build and run with a knowledge base + $0 -k kb_123456 + + # Use a different server URL + $0 -u https://api.weknora.com -k kb_123456 -t mytoken + + # Continue an existing session + $0 -s sess_123456 + + # Only build the binary + $0 --build-only + +Environment Variables: + WEKNORA_URL Default API URL + WEKNORA_KB_ID Default Knowledge Base ID + WEKNORA_TOKEN Default API Token + WEKNORA_SESSION_ID Default Session ID + +EOF +} + +# Parse command line arguments +URL="${WEKNORA_URL:-$DEFAULT_URL}" +KB_ID="${WEKNORA_KB_ID:-}" +SESSION_ID="${WEKNORA_SESSION_ID:-}" +TOKEN="${WEKNORA_TOKEN:-}" +BUILD_ONLY=false + +while [[ $# -gt 0 ]]; do + case $1 in + -u|--url) + URL="$2" + shift 2 + ;; + -k|--kb) + KB_ID="$2" + shift 2 + ;; + -s|--session) + SESSION_ID="$2" + shift 2 + ;; + -t|--token) + TOKEN="$2" + shift 2 + ;; + -b|--build-only) + BUILD_ONLY=true + shift + ;; + -h|--help) + usage + exit 0 + ;; + *) + print_error "Unknown option: $1" + usage + exit 1 + ;; + esac +done + +# Build the binary +if ! build; then + exit 1 +fi + +# Exit if build-only mode +if [ "$BUILD_ONLY" = true ]; then + print_info "Build-only mode. Binary created: ./$BINARY_NAME" + exit 0 +fi + +# Validate parameters +if [ -z "$SESSION_ID" ] && [ -z "$KB_ID" ]; then + print_warning "Neither session ID nor knowledge base ID provided." + print_info "You can create a new session after starting the tool." +fi + +# Build command arguments +ARGS="-url $URL" + +if [ -n "$KB_ID" ]; then + ARGS="$ARGS -kb $KB_ID" +fi + +if [ -n "$SESSION_ID" ]; then + ARGS="$ARGS -session $SESSION_ID" +fi + +if [ -n "$TOKEN" ]; then + ARGS="$ARGS -token $TOKEN" +fi + +# Show configuration +echo "" +print_info "Configuration:" +echo " URL: $URL" +[ -n "$KB_ID" ] && echo " Knowledge Base: $KB_ID" +[ -n "$SESSION_ID" ] && echo " Session: $SESSION_ID" +[ -n "$TOKEN" ] && echo " Token: [provided]" +echo "" + +# Run the tool +print_info "Starting agent test tool..." +echo "" +./$BINARY_NAME $ARGS + diff --git a/client/cmd/agent_test/test_scenarios.sh b/client/cmd/agent_test/test_scenarios.sh new file mode 100755 index 00000000..385b041b --- /dev/null +++ b/client/cmd/agent_test/test_scenarios.sh @@ -0,0 +1,159 @@ +#!/bin/bash + +# Test Scenarios for WeKnora Agent QA +# This script contains various test scenarios you can run + +set -e + +# Colors +GREEN='\033[0;32m' +BLUE='\033[0;34m' +YELLOW='\033[1;33m' +NC='\033[0m' + +print_scenario() { + echo -e "\n${BLUE}═══════════════════════════════════════════════${NC}" + echo -e "${BLUE} $1${NC}" + echo -e "${BLUE}═══════════════════════════════════════════════${NC}\n" +} + +# Check if binary exists +if [ ! -f "./agent_test" ]; then + echo "Building agent_test..." + make build +fi + +# Load environment variables if .env exists +if [ -f ".env" ]; then + export $(cat .env | grep -v '^#' | xargs) +fi + +# Check required variables +if [ -z "$WEKNORA_KB_ID" ]; then + echo "Error: WEKNORA_KB_ID is not set" + echo "Please set it in .env file or export WEKNORA_KB_ID=your_kb_id" + exit 1 +fi + +URL="${WEKNORA_URL:-http://localhost:8080}" +KB_ID="$WEKNORA_KB_ID" +TOKEN="${WEKNORA_TOKEN:-}" + +# Scenario 1: Basic Q&A +scenario_basic() { + print_scenario "Scenario 1: Basic Question & Answer" + echo -e "${YELLOW}This will test basic agent Q&A functionality${NC}\n" + echo "Try asking: What is machine learning?" + echo "" + + if [ -n "$TOKEN" ]; then + ./agent_test -url "$URL" -kb "$KB_ID" -token "$TOKEN" + else + ./agent_test -url "$URL" -kb "$KB_ID" + fi +} + +# Scenario 2: Complex query with tool usage +scenario_complex() { + print_scenario "Scenario 2: Complex Query with Tool Usage" + echo -e "${YELLOW}This will test agent's ability to use tools${NC}\n" + echo "Try asking: Search for information about neural networks and explain the key concepts" + echo "" + + if [ -n "$TOKEN" ]; then + ./agent_test -url "$URL" -kb "$KB_ID" -token "$TOKEN" + else + ./agent_test -url "$URL" -kb "$KB_ID" + fi +} + +# Scenario 3: Multi-turn conversation +scenario_multiturn() { + print_scenario "Scenario 3: Multi-turn Conversation" + echo -e "${YELLOW}This will test agent's context awareness${NC}\n" + echo "Try this sequence:" + echo " 1. What is supervised learning?" + echo " 2. Can you give me some examples?" + echo " 3. How does it compare to unsupervised learning?" + echo "" + + if [ -n "$TOKEN" ]; then + ./agent_test -url "$URL" -kb "$KB_ID" -token "$TOKEN" + else + ./agent_test -url "$URL" -kb "$KB_ID" + fi +} + +# Show menu +show_menu() { + echo -e "\n${GREEN}WeKnora Agent Test Scenarios${NC}\n" + echo "Select a test scenario to run:" + echo " 1) Basic Q&A" + echo " 2) Complex Query with Tool Usage" + echo " 3) Multi-turn Conversation" + echo " 4) Custom (manual testing)" + echo " 5) Exit" + echo "" + read -p "Enter your choice [1-5]: " choice + + case $choice in + 1) scenario_basic ;; + 2) scenario_complex ;; + 3) scenario_multiturn ;; + 4) + print_scenario "Custom Testing" + if [ -n "$TOKEN" ]; then + ./agent_test -url "$URL" -kb "$KB_ID" -token "$TOKEN" + else + ./agent_test -url "$URL" -kb "$KB_ID" + fi + ;; + 5) + echo "Goodbye!" + exit 0 + ;; + *) + echo "Invalid choice. Please try again." + show_menu + ;; + esac +} + +# Main +if [ "$1" == "--help" ] || [ "$1" == "-h" ]; then + echo "Usage: $0 [scenario_number]" + echo "" + echo "Available scenarios:" + echo " 1 - Basic Q&A" + echo " 2 - Complex Query with Tool Usage" + echo " 3 - Multi-turn Conversation" + echo " 4 - Custom (manual testing)" + echo "" + echo "If no argument is provided, an interactive menu will be shown." + exit 0 +fi + +# If scenario number is provided as argument +if [ -n "$1" ]; then + case $1 in + 1) scenario_basic ;; + 2) scenario_complex ;; + 3) scenario_multiturn ;; + 4) + if [ -n "$TOKEN" ]; then + ./agent_test -url "$URL" -kb "$KB_ID" -token "$TOKEN" + else + ./agent_test -url "$URL" -kb "$KB_ID" + fi + ;; + *) + echo "Invalid scenario number: $1" + echo "Use --help to see available scenarios" + exit 1 + ;; + esac +else + # Show interactive menu + show_menu +fi + diff --git a/client/session.go b/client/session.go index 86b380d8..90403c6f 100644 --- a/client/session.go +++ b/client/session.go @@ -49,10 +49,23 @@ type SummaryConfig struct { MaxCompletionTokens int `json:"max_completion_tokens"` } +// AgentConfig defines agent configuration for agent mode +type AgentConfig struct { + Enabled bool `json:"enabled"` // Whether agent mode is enabled + EnablePlanning bool `json:"enable_planning"` // Whether to plan before executing + MaxIterations int `json:"max_iterations"` // Maximum number of ReAct iterations + ReflectionEnabled bool `json:"reflection_enabled"` // Whether to enable reflection + AllowedTools []string `json:"allowed_tools"` // List of allowed tool names + Temperature float64 `json:"temperature"` // LLM temperature for agent + ThinkingModelID string `json:"thinking_model_id"` // Model ID for reasoning + KnowledgeBases []string `json:"knowledge_bases"` // Accessible knowledge base IDs +} + // CreateSessionRequest session creation request type CreateSessionRequest struct { - KnowledgeBaseID string `json:"knowledge_base_id"` // Associated knowledge base ID + KnowledgeBaseID string `json:"knowledge_base_id"` // Associated knowledge base ID (optional in agent mode) SessionStrategy *SessionStrategy `json:"session_strategy"` // Session strategy + AgentConfig *AgentConfig `json:"agent_config"` // Agent configuration (optional, for agent mode) } // Session session information @@ -73,6 +86,7 @@ type Session struct { RerankThreshold float64 `json:"reranking_threshold"` // Reranking threshold SummaryModelID string `json:"summary_model_id"` SummaryParameters *SummaryConfig `json:"summary_parameters"` + AgentConfig *AgentConfig `json:"agent_config"` // Agent configuration (optional) CreatedAt string `json:"created_at"` UpdatedAt string `json:"updated_at"` } diff --git a/config/config.yaml b/config/config.yaml index cc8e6e6e..5119b9d7 100644 --- a/config/config.yaml +++ b/config/config.yaml @@ -599,4 +599,17 @@ extract: with_tag: | 请随机生成一段文本,要求内容与 %s 等相关,字数在 [50-200] 之间,并且尽量包含一些与这些标签相关的专业术语或典型元素,使文本更具针对性和相关性。 with_no_tag: | - 请随机生成一段文本,内容请自由发挥,字数在 [50-200] 之间。 \ No newline at end of file + 请随机生成一段文本,内容请自由发挥,字数在 [50-200] 之间。 +# Agent 配置 +agent: + enabled: true + default_max_iterations: 5 + default_temperature: 0.7 + reflection_enabled: false + default_tools: + - knowledge_search + - multi_kb_search + - list_knowledge_bases + - get_related_chunks + - query_knowledge_graph + - get_document_info diff --git a/docker-compose.yml b/docker-compose.yml index 9f29764f..54f0ea7c 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -191,6 +191,8 @@ services: - postgres-data:/var/lib/postgresql/data - ./migrations/paradedb/00-init-db.sql:/docker-entrypoint-initdb.d/00-init-db.sql - ./migrations/paradedb/01-migrate-to-paradedb.sql:/docker-entrypoint-initdb.d/01-migrate-to-paradedb.sql + - ./migrations/paradedb/02-add-agent-config-if-missing.sql:/docker-entrypoint-initdb.d/02-add-agent-config-if-missing.sql + - ./migrations/paradedb/03-cleanup-unreferenced-models.sql:/docker-entrypoint-initdb.d/03-cleanup-unreferenced-models.sql networks: - WeKnora-network healthcheck: diff --git a/docs/AGENT.md b/docs/AGENT.md new file mode 100644 index 00000000..8ec12f9b --- /dev/null +++ b/docs/AGENT.md @@ -0,0 +1,527 @@ +# WeKnora Agent Mode 文档 + +## 概述 + +WeKnora Agent Mode 是基于 ReAct (Reasoning + Acting) 框架实现的智能代理系统,能够通过工具调用和迭代推理来回答复杂问题。 + +### 核心特性 + +- **ReAct 框架**: Thought → Action → Observation 循环 +- **工具系统**: 7个知识库相关工具 +- **可选规划**: 可在执行前生成任务计划 +- **事件追踪**: 完整的执行过程可视化 +- **灵活配置**: 支持多种参数调整 + +## 架构设计 + +### Agent 工作流程 + +``` +用户查询 + ↓ +[可选] 生成执行计划 + ↓ +┌─────────────────┐ +│ ReAct 循环开始 │ +├─────────────────┤ +│ 1. Think (思考) │ → LLM 分析当前状态 +│ 2. Act (行动) │ → 调用工具获取信息 +│ 3. Observe (观察)│ → 处理工具返回结果 +│ [可选] Reflect │ → 反思当前步骤 +│ 4. Decide (决策)│ → 继续或结束? +└─────────────────┘ + ↓ +生成最终答案 +``` + +### 组件结构 + +``` +internal/agent/ +├── engine.go # Agent 执行引擎 +├── prompts.go # System prompts +└── tools/ # 工具系统 + ├── tool.go + ├── registry.go + ├── knowledge_search.go + ├── multi_kb_search.go + ├── list_knowledge_bases.go + ├── get_chunk_detail.go + ├── get_related_chunks.go + ├── query_knowledge_graph.go + └── get_document_info.go +``` + +## 配置说明 + +### Agent 配置结构 + +```go +type AgentConfig struct { + Enabled bool // 是否启用 Agent 模式 + EnablePlanning bool // 是否先规划 + MaxIterations int // 最大迭代次数 (1-20) + ReflectionEnabled bool // 是否启用反思 + AllowedTools []string // 允许的工具列表 + Temperature float64 // LLM 温度 (0-2) + ThinkingModelID string // 推理模型 ID + KnowledgeBases []string // 可访问的知识库 ID +} +``` + +### 全局配置 (config.yaml) + +```yaml +agent: + enabled: true + default_max_iterations: 5 + default_temperature: 0.7 + reflection_enabled: false + default_tools: + - knowledge_search + - multi_kb_search + - list_knowledge_bases + - get_chunk_detail + - get_related_chunks + - query_knowledge_graph + - get_document_info +``` + +## 可用工具 + +### 1. knowledge_search +搜索指定知识库中的相关内容。 + +**参数:** +- `knowledge_base_id` (必需): 知识库ID +- `query` (必需): 搜索查询内容 +- `top_k` (可选): 返回结果数量,默认5 + +**示例:** +``` +knowledge_search(knowledge_base_id="kb123", query="什么是RAG", top_k=5) +``` + +### 2. multi_kb_search +在多个知识库中智能搜索,自动选择最相关的知识库。 + +**参数:** +- `query` (必需): 搜索查询内容 +- `top_k` (可选): 每个知识库返回的结果数量,默认3 + +**适用场景:** 跨知识库查询,不确定信息在哪个知识库中 + +### 3. list_knowledge_bases +列出当前可访问的所有知识库。 + +**参数:** 无 + +**用途:** 了解有哪些知识库可以搜索 + +### 4. get_chunk_detail +获取指定chunk的详细信息,包括完整内容、来源文档。 + +**参数:** +- `chunk_id` (必需): Chunk ID + +**用途:** 当搜索结果不够详细时获取完整内容 + +### 5. get_related_chunks +获取与指定chunk相关的其他chunks。 + +**参数:** +- `chunk_id` (必需): Chunk ID +- `relation_type` (可选): "sequential" (顺序) 或 "semantic" (语义) +- `limit` (可选): 返回数量,默认5 + +**用途:** 发现相关信息,扩展上下文 + +### 6. query_knowledge_graph +查询知识图谱中的实体和关系。 + +**参数:** +- `knowledge_base_id` (必需): 知识库ID +- `query` (必需): 查询内容(实体名称或查询文本) + +**前提:** 知识库已配置知识图谱抽取 + +### 7. get_document_info +获取文档的元数据信息。 + +**参数:** +- `knowledge_id` (必需): 文档/知识ID + +**用途:** 了解文档的整体情况 + +## 使用指南 + +### 创建 Agent Session + +```bash +POST /api/v1/sessions + +{ + "knowledge_base_id": "kb123", + "session_strategy": { + "summary_model_id": "model123", + ... + }, + "agent_config": { + "enabled": true, + "enable_planning": false, + "max_iterations": 5, + "reflection_enabled": false, + "allowed_tools": [ + "knowledge_search", + "multi_kb_search", + "list_knowledge_bases" + ], + "temperature": 0.7, + "knowledge_bases": ["kb123", "kb456"] + } +} +``` + +### 发起 Agent 查询 + +```bash +POST /api/v1/sessions/{session_id}/agent-qa + +{ + "query": "请解释RAG技术的工作原理" +} +``` + +### 响应格式 + +Agent 会返回 SSE (Server-Sent Events) 流式响应: + +1. **知识引用** (可选) +```json +{ + "response_type": "references", + "knowledge_references": [...] +} +``` + +2. **Agent 思考过程** (可选,用于调试) +```json +{ + "response_type": "agent_thought", + "content": "我需要先搜索相关知识..." +} +``` + +3. **工具调用** (可选) +```json +{ + "response_type": "agent_action", + "content": "调用工具: knowledge_search" +} +``` + +4. **最终答案** +```json +{ + "response_type": "answer", + "content": "RAG技术的工作原理是...", + "done": true +} +``` + +## 最佳实践 + +### 1. 工具选择策略 + +- **已知知识库**: 使用 `knowledge_search` +- **不确定位置**: 使用 `multi_kb_search` +- **需要上下文**: 使用 `get_related_chunks` +- **探索阶段**: 先用 `list_knowledge_bases` + +### 2. 迭代次数设置 + +- **简单查询**: 3-5 次 +- **复杂问题**: 5-10 次 +- **探索性任务**: 10-15 次 +- **最大限制**: 20 次 (防止无限循环) + +### 3. 温度参数 + +- **精确查询**: 0.3-0.5 (更确定性) +- **创造性任务**: 0.7-1.0 (更多样性) +- **默认推荐**: 0.7 + +### 4. Planning 启用时机 + +- **复杂多步骤任务**: 启用 +- **简单直接查询**: 禁用 +- **探索性问题**: 启用 + +### 5. Reflection 启用时机 + +- **关键任务**: 启用 (提高准确性) +- **快速响应**: 禁用 (减少延迟) +- **默认**: 禁用 + +## 工作原理详解 + +### ReAct Prompt Template + +``` +你是一个智能知识库助手。你的任务是通过使用提供的工具来回答用户问题。 + +工作流程: +1. 分析用户问题,确定需要什么信息 +2. 使用合适的工具获取信息(可以多次调用不同工具) +3. 基于获取的信息,提供准确、完整的答案 + +注意事项: +- 优先使用 multi_kb_search 进行跨知识库搜索 +- 如果需要特定知识库,先用 list_knowledge_bases 查看可用知识库 +- 如果搜索结果不够详细,使用 get_chunk_detail 获取完整内容 +- 使用 get_related_chunks 发现相关信息 +- 如果涉及实体关系,使用 query_knowledge_graph +- 引用信息时,说明来源(chunk_id 或 knowledge_base) +- 如果找不到相关信息,诚实告知用户 + +当前可访问的知识库: +{knowledge_bases} + +{plan_context} +``` + +### 工具调用解析 + +Agent 会尝试从 LLM 输出中解析工具调用,支持的格式: + +``` +tool_name(arg1="value1", arg2="value2") +``` + +例如: +``` +knowledge_search(knowledge_base_id="kb123", query="RAG技术") +``` + +### 循环控制 + +Agent 会在以下情况停止: + +1. LLM 输出包含 "最终答案" 或 "Final Answer" +2. 达到最大迭代次数 +3. 工具调用失败且无法恢复 +4. 检测到重复循环模式 + +## 事件追踪 + +Agent 执行过程中会发送以下事件 (通过 Event Bus): + +### agent.plan +```go +type AgentPlanData struct { + Query string + Plan []string + Duration int64 +} +``` + +### agent.step +```go +type AgentStepData struct { + Iteration int + Thought string + ToolCalls []ToolCall + Duration int64 +} +``` + +### agent.tool +```go +type AgentActionData struct { + Iteration int + ToolName string + ToolInput map[string]interface{} + ToolOutput string + Success bool + Error string + Duration int64 +} +``` + +## 示例场景 + +### 场景 1: 简单知识查询 + +**用户问题**: "什么是 RAG?" + +**Agent 执行流程**: +1. **Think**: 需要搜索 RAG 相关知识 +2. **Act**: `multi_kb_search(query="RAG")` +3. **Observe**: 获得3条相关结果 +4. **Think**: 信息足够,可以回答 +5. **Final Answer**: 基于搜索结果生成答案 + +**迭代次数**: 2 + +### 场景 2: 跨文档关联查询 + +**用户问题**: "比较 RAG 和微调的优缺点" + +**Agent 执行流程**: +1. **Think**: 需要分别查找 RAG 和微调的信息 +2. **Act**: `multi_kb_search(query="RAG优缺点")` +3. **Observe**: 获得 RAG 相关信息 +4. **Think**: 还需要微调的信息 +5. **Act**: `multi_kb_search(query="模型微调优缺点")` +6. **Observe**: 获得微调相关信息 +7. **Think**: 信息完整,进行对比 +8. **Final Answer**: 综合两者信息生成对比答案 + +**迭代次数**: 4 + +### 场景 3: 深入探索 + +**用户问题**: "详细解释向量数据库的工作原理" + +**Agent 执行流程**: +1. **Think**: 先查看有哪些知识库 +2. **Act**: `list_knowledge_bases()` +3. **Observe**: 发现有"数据库技术"知识库 +4. **Think**: 在该知识库中搜索 +5. **Act**: `knowledge_search(knowledge_base_id="db_kb", query="向量数据库")` +6. **Observe**: 找到相关 chunk +7. **Think**: 需要更多细节 +8. **Act**: `get_chunk_detail(chunk_id="chunk123")` +9. **Observe**: 获得完整内容 +10. **Think**: 查看相关内容 +11. **Act**: `get_related_chunks(chunk_id="chunk123", relation_type="sequential")` +12. **Observe**: 获得上下文 +13. **Final Answer**: 基于详细信息生成深入解释 + +**迭代次数**: 7 + +## 常见问题 + +### Q: Agent 和普通 RAG 有什么区别? + +**A**: +- **普通 RAG**: 一次性检索 → 生成答案 +- **Agent**: 可以多次迭代,根据中间结果调整策略,调用不同工具 + +### Q: 什么时候使用 Agent 模式? + +**A**: +- 需要多步推理的复杂问题 +- 需要在多个知识库中查找信息 +- 需要深入探索和关联分析 +- 问题模糊,需要澄清和逐步细化 + +### Q: Agent 模式的成本如何? + +**A**: +- **Token 消耗**: 比普通 RAG 高 (多次 LLM 调用) +- **响应时间**: 较长 (迭代执行) +- **准确性**: 通常更高 (多步验证) + +### Q: 如何优化 Agent 性能? + +**A**: +1. 合理设置 `max_iterations` (避免过多) +2. 选择必要的工具 (`allowed_tools`) +3. 禁用不需要的功能 (planning, reflection) +4. 使用更快的模型作为 thinking_model + +### Q: 工具调用失败怎么办? + +**A**: Agent 会: +1. 在 Observation 中记录错误 +2. 尝试使用其他工具 +3. 如果多次失败,会在最终答案中说明 + +## 技术限制与注意事项 + +### 当前限制 + +1. **工具调用解析**: 使用简单的模式匹配,可能无法处理复杂格式 +2. **Function Calling**: 当前使用 prompt-based 方式,未来可升级为原生 function calling +3. **并行工具调用**: 当前不支持,工具按顺序执行 +4. **图谱查询**: 当前使用 hybrid search,完整图谱功能开发中 + +### 未来改进 + +- [ ] 支持 LLM 原生 function calling (GPT-4, Claude 等) +- [ ] 并行工具执行 +- [ ] 更智能的循环检测 +- [ ] 工具结果缓存 +- [ ] 自定义工具注册 +- [ ] Agent 执行可视化 UI + +## 开发指南 + +### 创建自定义工具 + +```go +package tools + +import ( + "context" + "github.com/Tencent/WeKnora/internal/types" +) + +type CustomTool struct { + BaseTool + // 添加依赖 +} + +func NewCustomTool() *CustomTool { + return &CustomTool{ + BaseTool: NewBaseTool( + "custom_tool", + "工具描述", + ), + } +} + +func (t *CustomTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "param1": map[string]interface{}{ + "type": "string", + "description": "参数描述", + }, + }, + "required": []string{"param1"}, + } +} + +func (t *CustomTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + // 实现工具逻辑 + param1 := args["param1"].(string) + + // 执行操作 + result := doSomething(param1) + + return &types.ToolResult{ + Success: true, + Output: result, + Data: map[string]interface{}{}, + }, nil +} +``` + +### 注册自定义工具 + +在 `agent_service.go` 的 `registerTools` 方法中添加: + +```go +case "custom_tool": + registry.RegisterTool(tools.NewCustomTool()) +``` + +## 总结 + +WeKnora Agent Mode 提供了强大的迭代推理能力,适用于复杂的知识查询场景。通过合理配置和工具选择,可以在准确性和效率之间找到最佳平衡点。 + +如有问题或建议,请提交 Issue 或 Pull Request。 + diff --git a/docs/CONTEXT_MANAGER.md b/docs/CONTEXT_MANAGER.md new file mode 100644 index 00000000..7e5bc477 --- /dev/null +++ b/docs/CONTEXT_MANAGER.md @@ -0,0 +1,401 @@ +# LLM Context Manager - 大模型上下文管理器 + +## 概述 + +LLM Context Manager 是一个专门用于管理大模型对话上下文的组件,它**独立于消息存储系统**,专注于管理发送给大模型的上下文窗口。 + +### 关键特性 + +1. **独立管理**: 与消息的数据库存储分离,专门管理发送给 LLM 的上下文 +2. **Token 限制管理**: 自动监控和管理上下文的 Token 数量 +3. **智能压缩**: 当上下文超出限制时,自动应用压缩策略 +4. **按 Session 维护**: 每个会话独立管理其上下文 +5. **灵活配置**: 支持会话级别的自定义配置 + +## 为什么需要 Context Manager? + +### 问题背景 + +- **消息存储** vs **LLM 上下文**: + - 消息存储:完整保存所有对话历史,用于展示和审计 + - LLM 上下文:有 Token 限制,需要精简管理 + +- **Token 限制**: 不同模型有不同的上下文窗口限制(如 4K, 8K, 16K tokens) + +- **性能优化**: 过长的上下文会增加推理时间和成本 + +### 解决方案 + +Context Manager 提供: +- 自动管理上下文窗口大小 +- 智能压缩历史消息 +- 保留最重要的上下文信息 +- 与消息存储解耦 + +## 架构设计 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Session Service │ +│ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ Message Repo │ │ Context Manager │ │ +│ │ (Complete │ │ (LLM Context │ │ +│ │ History) │ │ Window) │ │ +│ └──────────────────┘ └──────────────────┘ │ +│ │ │ │ +│ │ Save all messages │ Manage LLM │ +│ │ for display │ context │ +│ ▼ ▼ │ +│ ┌──────────────────┐ ┌──────────────────┐ │ +│ │ Database │ │ In-Memory │ │ +│ │ (Persistent) │ │ (Session-based) │ │ +│ └──────────────────┘ └──────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 压缩策略 + +### 1. 滑动窗口策略 (Sliding Window) + +保留最近的 N 条消息,丢弃更早的消息。 + +**优点:** +- 简单高效 +- 不需要额外的 LLM 调用 +- 适合短期对话 + +**配置示例:** +```json +{ + "enabled": true, + "max_tokens": 8192, + "compression_strategy": "sliding_window", + "recent_message_count": 20 +} +``` + +**工作原理:** +``` +原始消息: [system, msg1, msg2, msg3, ..., msg18, msg19, msg20, msg21, msg22] + ↑ + 保留最近20条消息 +压缩结果: [system, msg3, msg4, ..., msg20, msg21, msg22] + └─────┘ └──────────────────────────────────┘ + 保留系统消息 保留最近的20条消息 +``` + +### 2. 智能压缩策略 (Smart Compression) + +使用 LLM 总结旧消息,保留最近消息的完整内容。 + +**优点:** +- 保留历史关键信息 +- 更好的上下文连贯性 +- 适合长期对话 + +**配置示例:** +```json +{ + "enabled": true, + "max_tokens": 8192, + "compression_strategy": "smart", + "recent_message_count": 10 +} +``` + +**工作原理:** +``` +原始消息: [system, msg1, msg2, ..., msg15, msg16, msg17, msg18, msg19, msg20] + └───────────────┘ └─────────────────────────────┘ + 旧消息(总结) 最近消息(保留) + +压缩结果: [system, summary, msg16, msg17, msg18, msg19, msg20] + └─────┘ └──────┘ └──────────────────────────────┘ + 系统消息 总结 保留最近的10条消息(完整) +``` + +## 使用方法 + +### 1. 默认配置 + +如果不设置 `context_config`,系统使用默认配置: +- 最大 Token: 8192 +- 策略: 滑动窗口 +- 保留消息数: 20 + +```go +// 不需要特别配置,自动使用默认设置 +session := &types.Session{ + TenantID: tenantID, + KnowledgeBaseID: kbID, + // context_config 为 nil,使用默认配置 +} +``` + +### 2. 自定义配置 - 滑动窗口 + +```go +session := &types.Session{ + TenantID: tenantID, + KnowledgeBaseID: kbID, + ContextConfig: &types.ContextConfig{ + Enabled: true, + MaxTokens: 16384, // GPT-4 的上下文窗口 + CompressionStrategy: types.ContextCompressionSlidingWindow, + RecentMessageCount: 30, // 保留最近30条消息 + }, +} +``` + +### 3. 自定义配置 - 智能压缩 + +```go +session := &types.Session{ + TenantID: tenantID, + KnowledgeBaseID: kbID, + SummaryModelID: "gpt-4", // 用于总结的模型 + ContextConfig: &types.ContextConfig{ + Enabled: true, + MaxTokens: 8192, + CompressionStrategy: types.ContextCompressionSmart, + RecentMessageCount: 15, // 保留最近15条完整消息 + }, +} +``` + +### 4. 通过 API 创建/更新会话 + +```bash +# 创建带上下文配置的会话 +curl -X POST http://localhost:8080/api/v1/sessions \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 1" \ + -d '{ + "knowledge_base_id": "kb-123", + "context_config": { + "enabled": true, + "max_tokens": 8192, + "compression_strategy": "sliding_window", + "recent_message_count": 20 + } + }' +``` + +## 工作流程 + +### 对话流程 + +``` +1. 用户发送消息 + ↓ +2. 保存消息到数据库 (Message Repo) + ↓ +3. 添加消息到上下文管理器 (Context Manager) + ↓ +4. Context Manager 检查 Token 限制 + ↓ +5. 如果超出限制,应用压缩策略 + ↓ +6. 获取压缩后的上下文 + ↓ +7. 发送给 LLM + ↓ +8. 保存响应到数据库 + ↓ +9. 添加响应到上下文管理器 +``` + +### 代码示例 + +```go +// 在 AgentQA 中的使用 +func (s *sessionService) AgentQA(ctx context.Context, sessionID, query string, assistantMessageID string) ( + []*types.SearchResult, <-chan types.StreamResponse, error, +) { + // 1. 获取会话配置 + session, err := s.sessionRepo.Get(ctx, tenantID, sessionID) + + // 2. 从上下文管理器获取 LLM 上下文(自动应用压缩) + history, err := s.getContextForSession(ctx, session, sessionID) + // history 是压缩后的,适合发送给 LLM 的消息列表 + + // 3. 执行 Agent + eventChan, err := engine.ExecuteStreamWithHistory(ctx, query, history) + + // 4. 保存新消息后,添加到上下文管理器 + // s.AddMessageToContext(ctx, session, sessionID, newMessage) + + return searchResults, responseChan, nil +} +``` + +## 配置参数说明 + +### ContextConfig 字段 + +| 字段 | 类型 | 说明 | 默认值 | +|------|------|------|--------| +| `enabled` | bool | 是否启用上下文管理 | true | +| `max_tokens` | int | 最大 Token 数 | 8192 | +| `compression_strategy` | string | 压缩策略: "sliding_window" 或 "smart" | "sliding_window" | +| `recent_message_count` | int | 保留的最近消息数 | 20 (sliding_window)
10 (smart) | + +### 推荐配置 + +#### 短期对话(客服、问答) +```json +{ + "enabled": true, + "max_tokens": 4096, + "compression_strategy": "sliding_window", + "recent_message_count": 15 +} +``` + +#### 长期对话(咨询、助手) +```json +{ + "enabled": true, + "max_tokens": 8192, + "compression_strategy": "smart", + "recent_message_count": 10 +} +``` + +#### 高端模型(GPT-4 Turbo, Claude) +```json +{ + "enabled": true, + "max_tokens": 16384, + "compression_strategy": "smart", + "recent_message_count": 20 +} +``` + +## 监控和调试 + +### 查看上下文统计 + +```go +// 获取上下文统计信息 +stats, err := contextManager.GetContextStats(ctx, sessionID) +if err == nil { + log.Printf("Session %s context stats:", sessionID) + log.Printf(" Messages: %d", stats.MessageCount) + log.Printf(" Tokens: ~%d", stats.TokenCount) + log.Printf(" Compressed: %v", stats.IsCompressed) + log.Printf(" Original messages: %d", stats.OriginalMessageCount) +} +``` + +### 日志示例 + +``` +INFO Using custom context config for session abc123: strategy=smart, max_tokens=8192, recent_count=10 +INFO Context exceeds max tokens (9500 > 8192), applying compression +INFO Summarizing 15 old messages +INFO Successfully summarized 15 messages +INFO Smart compression: 25 -> 11 messages (system: 1, compressed: 1, recent: 10) +INFO LLM context stats for session abc123: messages=11, tokens=~7800, compressed=true +``` + +## 与消息存储的区别 + +| 特性 | 消息存储 (Message Repo) | 上下文管理器 (Context Manager) | +|------|------------------------|------------------------------| +| 目的 | 完整保存对话历史 | 管理 LLM 输入上下文 | +| 存储 | 数据库(持久化) | 内存(会话级别) | +| 内容 | 所有消息(完整) | 压缩后的消息 | +| 大小限制 | 无限制 | 受 Token 限制 | +| 使用场景 | 展示历史、审计 | LLM 推理输入 | +| 生命周期 | 永久保存 | 会话期间 | + +## 最佳实践 + +1. **选择合适的策略**: + - 短对话 → 滑动窗口(性能更好) + - 长对话 → 智能压缩(保留更多上下文) + +2. **配置 Token 限制**: + - 设置为模型上下文窗口的 70-80% + - 为响应留出足够空间 + +3. **调整保留消息数**: + - 滑动窗口: 15-30 条消息 + - 智能压缩: 8-15 条最近消息 + +4. **监控压缩效果**: + - 定期检查 Token 使用情况 + - 观察压缩是否影响对话质量 + +5. **性能考虑**: + - 智能压缩会额外调用 LLM(有成本) + - 滑动窗口无额外开销 + +## 数据库迁移 + +运行以下迁移脚本添加 `context_config` 字段: + +### MySQL +```bash +mysql -u root -p your_database < migrations/mysql/06-add-context-config-to-sessions.sql +``` + +### ParadeDB/PostgreSQL +```bash +psql -U postgres -d your_database -f migrations/paradedb/06-add-context-config-to-sessions.sql +``` + +## 常见问题 + +### Q1: 上下文管理器的数据会持久化吗? +**A**: 不会。上下文管理器是内存级别的,按 Session 维护。重启后会清空,需要从消息历史重新构建。 + +### Q2: 如何清空某个会话的上下文? +**A**: +```go +err := contextManager.ClearContext(ctx, sessionID) +``` + +### Q3: 压缩后的消息会影响数据库中的消息吗? +**A**: 不会。压缩只影响发送给 LLM 的上下文,数据库中的消息完整保留。 + +### Q4: 智能压缩的总结质量如何保证? +**A**: +- 使用会话配置的 `summary_model_id` 模型 +- 可以使用更强的模型(如 GPT-4)进行总结 +- 总结时使用低 temperature (0.3) 确保一致性 + +### Q5: 如何为现有会话启用上下文管理? +**A**: +```bash +# 更新会话配置 +curl -X PUT http://localhost:8080/api/v1/sessions/{session_id} \ + -H "Content-Type: application/json" \ + -H "X-Tenant-ID: 1" \ + -d '{ + "context_config": { + "enabled": true, + "max_tokens": 8192, + "compression_strategy": "sliding_window", + "recent_message_count": 20 + } + }' +``` + +## 未来改进 + +- [ ] 支持更多压缩策略(如 MapReduce 总结) +- [ ] 支持自定义 Token 计算器 +- [ ] 持久化压缩后的上下文摘要 +- [ ] 支持跨会话的上下文共享 +- [ ] 添加更详细的压缩指标和监控 +- [ ] 支持上下文恢复机制 + +## 参考 + +- [Agent 文档](./AGENT.md) +- [API 文档](./API.md) +- [消息管理](../internal/types/message.go) + diff --git a/frontend/src/api/chat/index.ts b/frontend/src/api/chat/index.ts index 2d5fe315..38e71136 100644 --- a/frontend/src/api/chat/index.ts +++ b/frontend/src/api/chat/index.ts @@ -18,6 +18,11 @@ export async function knowledgeChat(data: { session_id: string; query: string; } return postChat(`/api/v1/knowledge-chat/${data.session_id}`, { query: data.query }); } +// Agent chat with streaming support +export async function agentChat(data: { session_id: string; query: string; }) { + return postChat(`/api/v1/agent-chat/${data.session_id}`, { query: data.query }); +} + export async function getMessageList(data: { session_id: string; limit: number, created_at: string }) { if (data.created_at) { return get(`/api/v1/messages/${data.session_id}/load?before_time=${encodeURIComponent(data.created_at)}&limit=${data.limit}`); diff --git a/frontend/src/api/initialization/index.ts b/frontend/src/api/initialization/index.ts index 1fea566a..90ea608a 100644 --- a/frontend/src/api/initialization/index.ts +++ b/frontend/src/api/initialization/index.ts @@ -100,8 +100,16 @@ export function checkOllamaStatus(): Promise<{ available: boolean; version?: str }); } -// 列出已安装的 Ollama 模型 -export function listOllamaModels(): Promise { +// Ollama 模型详细信息接口 +export interface OllamaModelInfo { + name: string; + size: number; + digest: string; + modified_at: string; +} + +// 列出已安装的 Ollama 模型(详细信息) +export function listOllamaModels(): Promise { return new Promise((resolve, reject) => { get('/api/v1/initialization/ollama/models') .then((response: any) => { diff --git a/frontend/src/api/model/index.ts b/frontend/src/api/model/index.ts new file mode 100644 index 00000000..e01b0755 --- /dev/null +++ b/frontend/src/api/model/index.ts @@ -0,0 +1,117 @@ +import { get, post, put, del } from '../../utils/request'; + +// 模型类型定义 +export interface ModelConfig { + id?: string; + tenant_id?: number; + name: string; + type: 'KnowledgeQA' | 'Embedding' | 'Rerank' | 'VLLM'; + source: 'local' | 'remote'; + description?: string; + parameters: { + base_url?: string; + api_key?: string; + embedding_parameters?: { + dimension?: number; + truncate_prompt_tokens?: number; + }; + interface_type?: 'ollama' | 'openai'; // VLLM专用 + }; + is_default?: boolean; + status?: string; + created_at?: string; + updated_at?: string; + deleted_at?: string | null; +} + +// 创建模型 +export function createModel(data: ModelConfig): Promise { + return new Promise((resolve, reject) => { + post('/api/v1/models', data) + .then((response: any) => { + if (response.success && response.data) { + resolve(response.data); + } else { + reject(new Error(response.message || '创建模型失败')); + } + }) + .catch((error: any) => { + console.error('创建模型失败:', error); + reject(error); + }); + }); +} + +// 获取模型列表 +export function listModels(type?: string): Promise { + return new Promise((resolve, reject) => { + const url = type ? `/api/v1/models?type=${type}` : '/api/v1/models'; + get(url) + .then((response: any) => { + if (response.success && response.data) { + resolve(response.data); + } else { + resolve([]); + } + }) + .catch((error: any) => { + console.error('获取模型列表失败:', error); + resolve([]); + }); + }); +} + +// 获取单个模型 +export function getModel(id: string): Promise { + return new Promise((resolve, reject) => { + get(`/api/v1/models/${id}`) + .then((response: any) => { + if (response.success && response.data) { + resolve(response.data); + } else { + reject(new Error(response.message || '获取模型失败')); + } + }) + .catch((error: any) => { + console.error('获取模型失败:', error); + reject(error); + }); + }); +} + +// 更新模型 +export function updateModel(id: string, data: Partial): Promise { + return new Promise((resolve, reject) => { + put(`/api/v1/models/${id}`, data) + .then((response: any) => { + if (response.success && response.data) { + resolve(response.data); + } else { + reject(new Error(response.message || '更新模型失败')); + } + }) + .catch((error: any) => { + console.error('更新模型失败:', error); + reject(error); + }); + }); +} + +// 删除模型 +export function deleteModel(id: string): Promise { + return new Promise((resolve, reject) => { + del(`/api/v1/models/${id}`) + .then((response: any) => { + if (response.success) { + resolve(); + } else { + reject(new Error(response.message || '删除模型失败')); + } + }) + .catch((error: any) => { + console.error('删除模型失败:', error); + reject(error); + }); + }); +} + diff --git a/frontend/src/api/system/index.ts b/frontend/src/api/system/index.ts index 41011011..72d58b1a 100644 --- a/frontend/src/api/system/index.ts +++ b/frontend/src/api/system/index.ts @@ -1,4 +1,4 @@ -import { get } from '@/utils/request' +import { get, put } from '@/utils/request' export interface SystemInfo { version: string @@ -7,6 +7,32 @@ export interface SystemInfo { go_version?: string } +export interface ToolDefinition { + name: string + label: string + description: string +} + +export interface AgentConfig { + enabled: boolean + max_iterations: number + reflection_enabled: boolean + allowed_tools: string[] + temperature: number + thinking_model_id: string + rerank_model_id: string + knowledge_bases?: string[] + available_tools?: ToolDefinition[] // GET 响应中包含,POST/PUT 不需要 +} + export function getSystemInfo(): Promise<{ data: SystemInfo }> { return get('/api/v1/system/info') } + +export function getAgentConfig(): Promise<{ data: AgentConfig }> { + return get('/api/v1/tenants/agent-config') +} + +export function updateAgentConfig(config: AgentConfig): Promise<{ data: AgentConfig }> { + return put('/api/v1/tenants/agent-config', config) +} diff --git a/frontend/src/assets/img/agent-active.svg b/frontend/src/assets/img/agent-active.svg new file mode 100644 index 00000000..2ddce930 --- /dev/null +++ b/frontend/src/assets/img/agent-active.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/frontend/src/assets/img/agent.svg b/frontend/src/assets/img/agent.svg new file mode 100644 index 00000000..fd134d36 --- /dev/null +++ b/frontend/src/assets/img/agent.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/frontend/src/assets/img/at-icon.svg b/frontend/src/assets/img/at-icon.svg new file mode 100644 index 00000000..eddefe44 --- /dev/null +++ b/frontend/src/assets/img/at-icon.svg @@ -0,0 +1,4 @@ + + + + diff --git a/frontend/src/assets/img/setting-green.svg b/frontend/src/assets/img/setting-green.svg index 71488877..ffcdaa33 100644 --- a/frontend/src/assets/img/setting-green.svg +++ b/frontend/src/assets/img/setting-green.svg @@ -1,5 +1,4 @@ - - - - \ No newline at end of file + + + diff --git a/frontend/src/assets/img/setting.svg b/frontend/src/assets/img/setting.svg index e0f5b33a..ec10d1de 100644 --- a/frontend/src/assets/img/setting.svg +++ b/frontend/src/assets/img/setting.svg @@ -1,5 +1,4 @@ - - - - \ No newline at end of file + + + diff --git a/frontend/src/components/Input-field.vue b/frontend/src/components/Input-field.vue index 5d45e142..7b049b1a 100644 --- a/frontend/src/components/Input-field.vue +++ b/frontend/src/components/Input-field.vue @@ -1,27 +1,79 @@ diff --git a/frontend/src/components/KnowledgeBaseSelector.vue b/frontend/src/components/KnowledgeBaseSelector.vue new file mode 100644 index 00000000..45cb319f --- /dev/null +++ b/frontend/src/components/KnowledgeBaseSelector.vue @@ -0,0 +1,371 @@ + + + + + diff --git a/frontend/src/components/ModelEditorDialog.vue b/frontend/src/components/ModelEditorDialog.vue new file mode 100644 index 00000000..91c83f21 --- /dev/null +++ b/frontend/src/components/ModelEditorDialog.vue @@ -0,0 +1,886 @@ + + + + + + diff --git a/frontend/src/components/UserMenu.vue b/frontend/src/components/UserMenu.vue new file mode 100644 index 00000000..97e626b8 --- /dev/null +++ b/frontend/src/components/UserMenu.vue @@ -0,0 +1,301 @@ + + + + + + diff --git a/frontend/src/components/menu.vue b/frontend/src/components/menu.vue index b8f6f008..9c4929c7 100644 --- a/frontend/src/components/menu.vue +++ b/frontend/src/components/menu.vue @@ -75,38 +75,9 @@ - + { currentRoute === 'knowledgeBaseDetail' || currentRoute === 'knowledgeBaseSettings'; case 'creatChat': - return currentRoute === 'kbCreatChat'; - case 'tenant': - return currentRoute === 'tenant'; + return currentRoute === 'kbCreatChat' || currentRoute === 'globalCreatChat'; + case 'settings': + return currentRoute === 'settings'; default: return itemPath === currentpath.value; } @@ -178,8 +152,8 @@ const getIconActiveState = (itemPath: string) => { currentRoute === 'knowledgeBaseDetail' || currentRoute === 'knowledgeBaseSettings' ), - isCreatChatActive: itemPath === 'creatChat' && currentRoute === 'kbCreatChat', - isTenantActive: itemPath === 'tenant' && currentRoute === 'tenant', + isCreatChatActive: itemPath === 'creatChat' && (currentRoute === 'kbCreatChat' || currentRoute === 'globalCreatChat'), + isSettingsActive: itemPath === 'settings' && currentRoute === 'settings', isChatActive: itemPath === 'chat' && currentRoute === 'chat' }; }; @@ -187,7 +161,7 @@ const getIconActiveState = (itemPath: string) => { // 分离上下两部分菜单 const topMenuItems = computed(() => { return (menuArr.value as unknown as MenuItem[]).filter((item: MenuItem) => - item.path === 'knowledge-bases' || (isInKnowledgeBase.value && item.path === 'creatChat') + item.path === 'knowledge-bases' || item.path === 'creatChat' ); }); @@ -430,13 +404,13 @@ let fileAddIcon = ref('file-add-green.svg'); let knowledgeIcon = ref('zhishiku-green.svg'); let prefixIcon = ref('prefixIcon.svg'); let logoutIcon = ref('logout.svg'); -let tenantIcon = ref('user.svg'); // 使用专门的用户图标 +let settingIcon = ref('setting.svg'); // 设置图标 let pathPrefix = ref(route.name) const getIcon = (path: string) => { // 根据当前路由状态更新所有图标 const kbActiveState = getIconActiveState('knowledge-bases'); const creatChatActiveState = getIconActiveState('creatChat'); - const tenantActiveState = getIconActiveState('tenant'); + const settingsActiveState = getIconActiveState('settings'); // 上传图标:只在知识库相关页面显示绿色 fileAddIcon.value = kbActiveState.isKbActive ? 'file-add-green.svg' : 'file-add.svg'; @@ -449,8 +423,8 @@ let pathPrefix = ref(route.name) kbActiveState.isKbActive ? 'prefixIcon-grey.svg' : 'prefixIcon.svg'; - // 租户图标:只在租户页面显示绿色 - tenantIcon.value = tenantActiveState.isTenantActive ? 'user-green.svg' : 'user.svg'; + // 设置图标:只在设置页面显示绿色 + settingIcon.value = settingsActiveState.isSettingsActive ? 'setting-green.svg' : 'setting.svg'; // 退出图标:始终显示默认 logoutIcon.value = 'logout.svg'; @@ -465,6 +439,10 @@ const handleMenuClick = async (path: string) => { } else { router.push('/platform/knowledge-bases') } + } else if (path === 'settings') { + // 设置菜单项:打开设置弹窗并跳转路由 + uiStore.openSettings() + router.push('/platform/settings') } else { gotopage(path) } @@ -493,11 +471,14 @@ const gotopage = async (path: string) => { return; } else { if (path === 'creatChat') { + // 尝试获取当前知识库ID const kbId = await getCurrentKbId() if (kbId) { + // 如果在知识库内部,进入该知识库的对话页 router.push(`/platform/knowledge-bases/${kbId}/creatChat`) } else { - router.push(`/platform/knowledge-bases`) + // 如果不在知识库内,也进入对话创建页,让用户通过 @ 按钮选择知识库 + router.push(`/platform/creatChat`) } } else { router.push(`/platform/${path}`); diff --git a/frontend/src/router/index.ts b/frontend/src/router/index.ts index 8432b0a8..4c47f62d 100644 --- a/frontend/src/router/index.ts +++ b/frontend/src/router/index.ts @@ -31,8 +31,12 @@ const router = createRouter({ children: [ { path: "tenant", - name: "tenant", - component: () => import("../views/tenant/TenantInfo.vue"), + redirect: "/platform/settings" + }, + { + path: "settings", + name: "settings", + component: () => import("../views/settings/Settings.vue"), meta: { requiresInit: true, requiresAuth: true } }, { @@ -47,6 +51,12 @@ const router = createRouter({ component: () => import("../views/knowledge/KnowledgeBase.vue"), meta: { requiresInit: true, requiresAuth: true } }, + { + path: "creatChat", + name: "globalCreatChat", + component: () => import("../views/creatChat/creatChat.vue"), + meta: { requiresInit: true, requiresAuth: true } + }, { path: "knowledge-bases/:kbId/creatChat", name: "kbCreatChat", diff --git a/frontend/src/stores/menu.ts b/frontend/src/stores/menu.ts index 90ebb5bf..5846f777 100644 --- a/frontend/src/stores/menu.ts +++ b/frontend/src/stores/menu.ts @@ -13,7 +13,7 @@ export const useMenuStore = defineStore('menuStore', { childrenPath: 'chat', children: reactive([]), }, - { title: '系统信息', icon: 'tenant', path: 'tenant' }, + { title: '设置', icon: 'setting', path: 'settings' }, { title: '退出登录', icon: 'logout', path: 'logout' } ]), isFirstSession: false, diff --git a/frontend/src/stores/settings.ts b/frontend/src/stores/settings.ts index b22a8b49..1bd537ae 100644 --- a/frontend/src/stores/settings.ts +++ b/frontend/src/stores/settings.ts @@ -5,6 +5,47 @@ interface Settings { endpoint: string; apiKey: string; knowledgeBaseId: string; + isAgentEnabled: boolean; + agentConfig: AgentConfig; + selectedKnowledgeBases: string[]; // 当前选中的知识库ID列表 + modelConfig: ModelConfig; // 模型配置 + ollamaConfig: OllamaConfig; // Ollama配置 +} + +// Agent 配置接口 +interface AgentConfig { + maxIterations: number; + temperature: number; + thinkingModelId: string; + rerankModelId: string; + allowedTools: string[]; +} + +// 单个模型项接口 +interface ModelItem { + id: string; // 唯一ID + name: string; // 显示名称 + source: 'local' | 'remote'; // 模型来源 + modelName: string; // 模型标识 + baseUrl?: string; // 远程API URL + apiKey?: string; // 远程API Key + dimension?: number; // Embedding专用:向量维度 + interfaceType?: 'ollama' | 'openai'; // VLLM专用:接口类型 + isDefault?: boolean; // 是否为默认模型 +} + +// 模型配置接口 - 支持多模型 +interface ModelConfig { + chatModels: ModelItem[]; + embeddingModels: ModelItem[]; + rerankModels: ModelItem[]; + vllmModels: ModelItem[]; // VLLM视觉模型 +} + +// Ollama 配置接口 +interface OllamaConfig { + baseUrl: string; // Ollama 服务地址 + enabled: boolean; // 是否启用 } // 默认设置 @@ -12,6 +53,25 @@ const defaultSettings: Settings = { endpoint: import.meta.env.VITE_IS_DOCKER ? "" : "http://localhost:8080", apiKey: "", knowledgeBaseId: "", + isAgentEnabled: false, + agentConfig: { + maxIterations: 5, + temperature: 0.7, + thinkingModelId: "", + rerankModelId: "", + allowedTools: ["knowledge_search", "multi_kb_search", "list_knowledge_bases"] + }, + selectedKnowledgeBases: [], // 默认为空数组 + modelConfig: { + chatModels: [], + embeddingModels: [], + rerankModels: [], + vllmModels: [] + }, + ollamaConfig: { + baseUrl: "http://localhost:11434", + enabled: true + } }; export const useSettingsStore = defineStore("settings", { @@ -20,6 +80,17 @@ export const useSettingsStore = defineStore("settings", { settings: JSON.parse(localStorage.getItem("WeKnora_settings") || JSON.stringify(defaultSettings)), }), + getters: { + // Agent 是否启用 + isAgentEnabled: (state) => state.settings.isAgentEnabled || false, + + // 获取 Agent 配置 + agentConfig: (state) => state.settings.agentConfig || defaultSettings.agentConfig, + + // 获取模型配置 + modelConfig: (state) => state.settings.modelConfig || defaultSettings.modelConfig, + }, + actions: { // 保存设置 saveSettings(settings: Settings) { @@ -47,5 +118,117 @@ export const useSettingsStore = defineStore("settings", { getKnowledgeBaseId(): string { return this.settings.knowledgeBaseId; }, + + // 启用/禁用 Agent + toggleAgent(enabled: boolean) { + this.settings.isAgentEnabled = enabled; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 更新 Agent 配置 + updateAgentConfig(config: Partial) { + this.settings.agentConfig = { ...this.settings.agentConfig, ...config }; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 更新模型配置 + updateModelConfig(config: Partial) { + this.settings.modelConfig = { ...this.settings.modelConfig, ...config }; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 添加模型 + addModel(type: 'chat' | 'embedding' | 'rerank' | 'vllm', model: ModelItem) { + const key = `${type}Models` as keyof ModelConfig; + const models = [...this.settings.modelConfig[key]] as ModelItem[]; + // 如果设为默认,取消其他模型的默认状态 + if (model.isDefault) { + models.forEach(m => m.isDefault = false); + } + // 如果是第一个模型,自动设为默认 + if (models.length === 0) { + model.isDefault = true; + } + models.push(model); + this.settings.modelConfig[key] = models as any; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 更新模型 + updateModel(type: 'chat' | 'embedding' | 'rerank' | 'vllm', modelId: string, updates: Partial) { + const key = `${type}Models` as keyof ModelConfig; + const models = [...this.settings.modelConfig[key]] as ModelItem[]; + const index = models.findIndex(m => m.id === modelId); + if (index !== -1) { + // 如果要设为默认,取消其他模型的默认状态 + if (updates.isDefault) { + models.forEach(m => m.isDefault = false); + } + models[index] = { ...models[index], ...updates }; + this.settings.modelConfig[key] = models as any; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + } + }, + + // 删除模型 + deleteModel(type: 'chat' | 'embedding' | 'rerank' | 'vllm', modelId: string) { + const key = `${type}Models` as keyof ModelConfig; + let models = [...this.settings.modelConfig[key]] as ModelItem[]; + const deletedModel = models.find(m => m.id === modelId); + models = models.filter(m => m.id !== modelId); + // 如果删除的是默认模型,设置第一个为默认 + if (deletedModel?.isDefault && models.length > 0) { + models[0].isDefault = true; + } + this.settings.modelConfig[key] = models as any; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 设置默认模型 + setDefaultModel(type: 'chat' | 'embedding' | 'rerank' | 'vllm', modelId: string) { + const key = `${type}Models` as keyof ModelConfig; + const models = [...this.settings.modelConfig[key]] as ModelItem[]; + models.forEach(m => m.isDefault = (m.id === modelId)); + this.settings.modelConfig[key] = models as any; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 更新 Ollama 配置 + updateOllamaConfig(config: Partial) { + this.settings.ollamaConfig = { ...this.settings.ollamaConfig, ...config }; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 选择知识库(替换整个列表) + selectKnowledgeBases(kbIds: string[]) { + this.settings.selectedKnowledgeBases = kbIds; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 添加单个知识库 + addKnowledgeBase(kbId: string) { + if (!this.settings.selectedKnowledgeBases.includes(kbId)) { + this.settings.selectedKnowledgeBases.push(kbId); + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + } + }, + + // 移除单个知识库 + removeKnowledgeBase(kbId: string) { + this.settings.selectedKnowledgeBases = + this.settings.selectedKnowledgeBases.filter(id => id !== kbId); + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 清空知识库选择 + clearKnowledgeBases() { + this.settings.selectedKnowledgeBases = []; + localStorage.setItem("WeKnora_settings", JSON.stringify(this.settings)); + }, + + // 获取选中的知识库列表 + getSelectedKnowledgeBases(): string[] { + return this.settings.selectedKnowledgeBases || []; + }, }, }); \ No newline at end of file diff --git a/frontend/src/stores/ui.ts b/frontend/src/stores/ui.ts new file mode 100644 index 00000000..e7d7aabe --- /dev/null +++ b/frontend/src/stores/ui.ts @@ -0,0 +1,22 @@ +import { defineStore } from 'pinia' + +export const useUIStore = defineStore('ui', { + state: () => ({ + showSettingsModal: false + }), + + actions: { + openSettings() { + this.showSettingsModal = true + }, + + closeSettings() { + this.showSettingsModal = false + }, + + toggleSettings() { + this.showSettingsModal = !this.showSettingsModal + } + } +}) + diff --git a/frontend/src/types/tool-results.ts b/frontend/src/types/tool-results.ts new file mode 100644 index 00000000..fee4b853 --- /dev/null +++ b/frontend/src/types/tool-results.ts @@ -0,0 +1,163 @@ +/** + * Tool Results Type Definitions + * TypeScript interfaces for all tool result types + */ + +// Relevance levels +export type RelevanceLevel = '高相关' | '中相关' | '低相关' | '弱相关'; + +// Display types +export type DisplayType = + | 'search_results' + | 'chunk_detail' + | 'related_chunks' + | 'knowledge_base_list' + | 'document_info' + | 'graph_query_results' + | 'thinking' + | 'plan' + | 'database_query'; + +// Search result item +export interface SearchResultItem { + result_index: number; + chunk_id: string; + content: string; + score: number; + relevance_level: RelevanceLevel; + knowledge_id: string; + knowledge_title: string; + match_type: string; +} + +// Chunk item +export interface ChunkItem { + index: number; + chunk_id: string; + chunk_index: number; + content: string; + knowledge_id: string; +} + +// Knowledge base item +export interface KnowledgeBaseItem { + index: number; + id: string; + name: string; + description: string; +} + +// Graph config +export interface GraphConfig { + nodes: string[]; + relations: string[]; +} + +// Search results data +export interface SearchResultsData { + display_type: 'search_results'; + results?: SearchResultItem[]; + count?: number; + kb_counts?: Record; + query?: string; + knowledge_base_id?: string; +} + +// Chunk detail data +export interface ChunkDetailData { + display_type: 'chunk_detail'; + chunk_id: string; + content: string; + chunk_index: number; + knowledge_id: string; + content_length?: number; +} + +// Related chunks data +export interface RelatedChunksData { + display_type: 'related_chunks'; + chunk_id: string; + relation_type: string; + count: number; + chunks: ChunkItem[]; +} + +// Knowledge base list data +export interface KnowledgeBaseListData { + display_type: 'knowledge_base_list'; + knowledge_bases: KnowledgeBaseItem[]; + count: number; +} + +// Document info data +export interface DocumentInfoData { + display_type: 'document_info'; + knowledge_id: string; + title: string; + chunk_count_min: number; +} + +// Graph query results data +export interface GraphQueryResultsData { + display_type: 'graph_query_results'; + results: SearchResultItem[]; + count: number; + graph_config: GraphConfig; +} + +// Thinking data +export interface ThinkingData { + display_type: 'thinking'; + thought: string; +} + +// Plan step +export interface PlanStep { + id: string; + description: string; + tools_to_use?: string; + status: 'pending' | 'in_progress' | 'completed' | 'skipped'; +} + +// Plan data +export interface PlanData { + display_type: 'plan'; + task: string; + steps: PlanStep[]; + total_steps: number; +} + +// Database query data +export interface DatabaseQueryData { + display_type: 'database_query'; + columns: string[]; + rows: Array>; + row_count: number; + query: string; +} + +// Union type for all tool result data +export type ToolResultData = + | SearchResultsData + | ChunkDetailData + | RelatedChunksData + | KnowledgeBaseListData + | DocumentInfoData + | GraphQueryResultsData + | ThinkingData + | PlanData + | DatabaseQueryData; + +// Action data (from index.vue) +export interface ActionData { + description: string; + success: boolean; + tool_name?: string; + arguments?: any; + output?: string; + error?: string; + details?: boolean; + display_type?: DisplayType; + tool_data?: Record; +} + diff --git a/frontend/src/utils/tool-icons.ts b/frontend/src/utils/tool-icons.ts new file mode 100644 index 00000000..3fffddf2 --- /dev/null +++ b/frontend/src/utils/tool-icons.ts @@ -0,0 +1,55 @@ +/** + * Tool Icons Utility + * Maps tool names and match types to icons for better UI display + */ + +// Tool name to icon mapping +export const toolIcons: Record = { + multi_kb_search: '🔍', + knowledge_search: '📚', + get_chunk_detail: '📄', + get_related_chunks: '🔗', + list_knowledge_bases: '📂', + get_document_info: 'ℹ️', + query_knowledge_graph: '🕸️', + think: '💭', + todo_write: '📋', +}; + +// Match type to icon mapping +export const matchTypeIcons: Record = { + '向量匹配': '🎯', + '关键词匹配': '🔤', + '相邻块匹配': '📌', + '历史匹配': '📜', + '父块匹配': '⬆️', + '关系块匹配': '🔗', + '图谱匹配': '🕸️', +}; + +// Get icon for a tool name +export function getToolIcon(toolName: string): string { + return toolIcons[toolName] || '🛠️'; +} + +// Get icon for a match type +export function getMatchTypeIcon(matchType: string): string { + return matchTypeIcons[matchType] || '📍'; +} + +// Get tool display name (user-friendly) +export function getToolDisplayName(toolName: string): string { + const displayNames: Record = { + multi_kb_search: '跨库搜索', + knowledge_search: '知识库搜索', + get_chunk_detail: '获取片段详情', + get_related_chunks: '获取相关片段', + list_knowledge_bases: '列出知识库', + get_document_info: '获取文档信息', + query_knowledge_graph: '查询知识图谱', + think: '思考', + todo_write: '制定计划', + }; + return displayNames[toolName] || toolName; +} + diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vue new file mode 100644 index 00000000..45c3805c --- /dev/null +++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue @@ -0,0 +1,879 @@ + + + + + diff --git a/frontend/src/views/chat/components/ToolResultRenderer.vue b/frontend/src/views/chat/components/ToolResultRenderer.vue new file mode 100644 index 00000000..7662d03e --- /dev/null +++ b/frontend/src/views/chat/components/ToolResultRenderer.vue @@ -0,0 +1,120 @@ + + + + + + diff --git a/frontend/src/views/chat/components/botmsg.vue b/frontend/src/views/chat/components/botmsg.vue index d476065f..7e59b9f6 100644 --- a/frontend/src/views/chat/components/botmsg.vue +++ b/frontend/src/views/chat/components/botmsg.vue @@ -2,7 +2,8 @@
- + +
@@ -22,6 +23,7 @@ import { onMounted, watch, computed, ref, reactive, defineProps, nextTick } from import { marked } from 'marked'; import docInfo from './docInfo.vue'; import deepThink from './deepThink.vue'; +import AgentStreamDisplay from './AgentStreamDisplay.vue'; import picturePreview from '@/components/picture-preview.vue'; import { sanitizeHTML, safeMarkdownToHTML, createSafeImage, isValidImageURL } from '@/utils/security'; diff --git a/frontend/src/views/chat/components/tool-results/ChunkDetail.vue b/frontend/src/views/chat/components/tool-results/ChunkDetail.vue new file mode 100644 index 00000000..b7906846 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/ChunkDetail.vue @@ -0,0 +1,75 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/DatabaseQuery.vue b/frontend/src/views/chat/components/tool-results/DatabaseQuery.vue new file mode 100644 index 00000000..c21b21ed --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/DatabaseQuery.vue @@ -0,0 +1,164 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/DocumentInfo.vue b/frontend/src/views/chat/components/tool-results/DocumentInfo.vue new file mode 100644 index 00000000..208a5026 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/DocumentInfo.vue @@ -0,0 +1,89 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/GraphQueryResults.vue b/frontend/src/views/chat/components/tool-results/GraphQueryResults.vue new file mode 100644 index 00000000..9ed66ff4 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/GraphQueryResults.vue @@ -0,0 +1,125 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/KnowledgeBaseList.vue b/frontend/src/views/chat/components/tool-results/KnowledgeBaseList.vue new file mode 100644 index 00000000..521d2922 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/KnowledgeBaseList.vue @@ -0,0 +1,108 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/PlanDisplay.vue b/frontend/src/views/chat/components/tool-results/PlanDisplay.vue new file mode 100644 index 00000000..17a291f3 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/PlanDisplay.vue @@ -0,0 +1,176 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/RelatedChunks.vue b/frontend/src/views/chat/components/tool-results/RelatedChunks.vue new file mode 100644 index 00000000..83c302c4 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/RelatedChunks.vue @@ -0,0 +1,115 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/SearchResults.vue b/frontend/src/views/chat/components/tool-results/SearchResults.vue new file mode 100644 index 00000000..5c1557db --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/SearchResults.vue @@ -0,0 +1,142 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/ThinkingDisplay.vue b/frontend/src/views/chat/components/tool-results/ThinkingDisplay.vue new file mode 100644 index 00000000..2f03dd79 --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/ThinkingDisplay.vue @@ -0,0 +1,49 @@ + + + + + + diff --git a/frontend/src/views/chat/components/tool-results/tool-results.less b/frontend/src/views/chat/components/tool-results/tool-results.less new file mode 100644 index 00000000..7188fcef --- /dev/null +++ b/frontend/src/views/chat/components/tool-results/tool-results.less @@ -0,0 +1,289 @@ +/** + * Tool Results Shared Styles + * Common styles for all tool result components + */ + +// Color scheme for relevance levels +@relevance-high: #00a870; +@relevance-medium: #ff9800; +@relevance-low: #757575; +@relevance-weak: #bdbdbd; + +// Card colors +@card-bg: #f8f9fa; +@card-border: #e7e7e7; +@card-hover-border: #07c05f; +@card-radius: 8px; +@card-shadow: 0 2px 4px rgba(0, 0, 0, 0.05); +@card-shadow-hover: 0 4px 8px rgba(0, 0, 0, 0.1); + +// Animation timing +@transition-time: 0.3s; + +// Tool result container +.tool-result-container { + margin: 8px 0; +} + +// Relevance badge styles +.relevance-badge { + display: inline-flex; + align-items: center; + padding: 4px 8px; + border-radius: 4px; + font-size: 12px; + font-weight: 600; + gap: 4px; + + &.high { + background-color: @relevance-high; + color: white; + } + + &.medium { + background-color: @relevance-medium; + color: white; + } + + &.low { + background-color: @relevance-low; + color: white; + } + + &.weak { + background-color: @relevance-weak; + color: #333; + } +} + +// Match type badge +.match-type-badge { + display: inline-flex; + align-items: center; + padding: 2px 6px; + border-radius: 3px; + font-size: 11px; + background-color: #e7e7e7; + color: #666; + gap: 2px; +} + +// Result card +.result-card { + background: @card-bg; + border: 1px solid @card-border; + border-radius: @card-radius; + margin-bottom: 8px; + overflow: hidden; + transition: all @transition-time ease; + + &:hover { + border-color: @card-hover-border; + box-shadow: @card-shadow-hover; + } +} + +.result-header { + padding: 10px 12px; + cursor: pointer; + user-select: none; + display: flex; + align-items: center; + justify-content: space-between; + gap: 8px; + + &:hover { + background: rgba(7, 192, 95, 0.05); + } +} + +.result-title { + display: flex; + align-items: center; + gap: 8px; + flex: 1; + font-size: 14px; + font-weight: 500; +} + +.result-meta { + display: flex; + align-items: center; + gap: 6px; + font-size: 12px; + color: #8b8b8b; +} + +.result-content { + padding: 0 12px 12px 12px; + border-top: 1px solid @card-border; + background: white; + max-height: 0; + opacity: 0; + overflow: hidden; + transition: max-height @transition-time ease, opacity @transition-time ease, padding @transition-time ease; + + &.expanded { + max-height: 2000px; + opacity: 1; + padding: 12px; + } +} + +.expand-icon { + font-size: 12px; + color: #8b8b8b; + transition: transform 0.2s ease; + + &.expanded { + transform: rotate(90deg); + } +} + +// Info sections +.info-section { + margin-top: 12px; + + &:first-child { + margin-top: 0; + } +} + +.info-section-title { + font-size: 12px; + font-weight: 600; + color: #666; + text-transform: uppercase; + letter-spacing: 0.5px; + margin-bottom: 6px; +} + +.info-field { + display: flex; + gap: 8px; + margin-bottom: 4px; + font-size: 13px; + + .field-label { + color: #8b8b8b; + min-width: 80px; + } + + .field-value { + color: #333; + flex: 1; + } +} + +// Statistics card (for KB counts, etc.) +.stats-card { + background: #f0f7ff; + border: 1px solid #d6e4ff; + border-radius: 6px; + padding: 10px 12px; + margin-bottom: 12px; +} + +.stats-title { + font-size: 13px; + font-weight: 600; + color: #333; + margin-bottom: 6px; +} + +.stats-list { + display: flex; + flex-direction: column; + gap: 4px; +} + +.stats-item { + font-size: 12px; + color: #666; + display: flex; + justify-content: space-between; +} + +// Grid layout for cards +.card-grid { + display: grid; + grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); + gap: 12px; + margin-top: 8px; +} + +// List item +.list-item { + display: flex; + flex-direction: column; + gap: 4px; + padding: 8px 0; + border-bottom: 1px solid #f0f0f0; + + &:last-child { + border-bottom: none; + } +} + +// Content preview (truncated) +.content-preview { + font-size: 13px; + color: #333; + line-height: 1.5; + max-height: 60px; + overflow: hidden; + text-overflow: ellipsis; + display: -webkit-box; + -webkit-line-clamp: 3; + -webkit-box-orient: vertical; +} + +// Full content +.full-content { + font-size: 13px; + color: #333; + line-height: 1.6; + white-space: pre-wrap; + word-break: break-word; + padding: 8px; + background: #f5f5f5; + border-radius: 4px; + border: 1px solid @card-border; +} + +// Action buttons +.action-button { + padding: 4px 10px; + font-size: 12px; + border-radius: 4px; + border: 1px solid @card-border; + background: white; + color: #666; + cursor: pointer; + transition: all 0.2s ease; + + &:hover { + border-color: @card-hover-border; + color: @card-hover-border; + } +} + +// Empty state +.empty-state { + padding: 24px; + text-align: center; + color: #8b8b8b; + font-size: 14px; +} + +// Code block +.code-block { + font-family: 'Monaco', 'Courier New', monospace; + font-size: 12px; + background: #f5f5f5; + padding: 8px; + border-radius: 4px; + border: 1px solid @card-border; + overflow-x: auto; +} + diff --git a/frontend/src/views/chat/index.vue b/frontend/src/views/chat/index.vue index c770ddc9..b29d9e44 100644 --- a/frontend/src/views/chat/index.vue +++ b/frontend/src/views/chat/index.vue @@ -32,7 +32,9 @@ import usermsg from './components/usermsg.vue'; import { getMessageList, generateSessionsTitle } from "@/api/chat/index"; import { useStream } from '../../api/chat/streame' import { useMenuStore } from '@/stores/menu'; +import { useSettingsStore } from '@/stores/settings'; const usemenuStore = useMenuStore(); +const useSettingsStoreInstance = useSettingsStore(); const { menuArr, isFirstSession, firstQuery } = storeToRefs(usemenuStore); const { output, onChunk, isStreaming, isLoading, error, startStream, stopStream } = useStream(); const route = useRoute(); @@ -109,7 +111,11 @@ const handleMsgList = async (data, isScrollType = false, newScrollHeight) => { let chatlist = data.reverse() for (let i = 0, len = chatlist.length; i < len; i++) { let item = chatlist[i]; - item.thinking = false; + item.isAgentMode = false; // Agent 模式标记 + item.agentEventStream = item.agentEventStream || []; + item._eventMap = new Map(); + item._pendingToolCalls = new Map(); + if (item.content) { if (!item.content.includes('') && !item.content.includes('<\/think>')) { item.thinkContent = ""; @@ -157,18 +163,45 @@ const sendMsg = async (value) => { messagesList.push({ content: value, role: 'user' }); scrollToBottom(); + // 判断是否使用 Agent 模式 + const isAgentMode = useSettingsStoreInstance.isAgentEnabled; + const chatUrl = isAgentMode ? '/api/v1/agent-chat' : '/api/v1/knowledge-chat'; + await startStream({ session_id: session_id.value, knowledge_base_id: knowledge_base_id.value, query: value, method: 'POST', - url: '/api/v1/knowledge-chat' + url: chatUrl }); } // 处理流式数据 onChunk((data) => { loading.value = false; + + // 日志:打印接收到的事件 + console.log('[Agent Event Received]', { + response_type: data.response_type, + id: data.id, + done: data.done, + content_length: data.content?.length || 0, + content_preview: data.content ? data.content.substring(0, 50) : '', + data: data.data + }); + + // 判断是否是 Agent 模式的响应 + const isAgentResponse = data.response_type === 'thinking' || + data.response_type === 'tool_call' || + data.response_type === 'references'; + + // Agent 模式处理 + if (isAgentResponse || messagesList[messagesList.length - 1]?.isAgentMode) { + handleAgentChunk(data); + return; + } + + // 原有的知识库 QA 处理逻辑 fullContent.value += data.content; let obj = { ...data, content: '', role: 'assistant', showThink: false }; @@ -203,6 +236,233 @@ onChunk((data) => { } updateAssistantSession(obj); }) +// 处理 Agent 流式数据 (Cursor-style UI) +const handleAgentChunk = (data) => { + const message = messagesList.findLast((item) => item.request_id === data.id || item.id === data.id); + + if (!message) { + // 创建新的 Assistant 消息 + const newMsg = { + id: data.id, + request_id: data.id, + role: 'assistant', + content: '', + isAgentMode: true, + // Event stream: ordered list of all agent events (thinking, tool calls, etc) + agentEventStream: [], + // Map to track event by event_id for quick lookup + _eventMap: new Map(), + knowledge_references: [] + }; + messagesList.push(newMsg); + scrollToBottom(); + return; + } + + message.isAgentMode = true; + + switch(data.response_type) { + case 'thinking': + { + const eventId = data.data?.event_id; + console.log('[Thinking Event]', { + event_id: eventId, + done: data.done, + content_length: data.content?.length || 0 + }); + + // Initialize structures + if (!message.agentEventStream) message.agentEventStream = []; + if (!message._eventMap) message._eventMap = new Map(); + + if (!data.done) { + // Check if this thinking event already exists + let thinkingEvent = message._eventMap.get(eventId); + + if (!thinkingEvent) { + // Create new thinking event + console.log('[Thinking] Creating new thinking event, event_id:', eventId); + thinkingEvent = { + type: 'thinking', + event_id: eventId, + content: '', + done: false, + startTime: Date.now(), + thinking: true + }; + + // Add to event stream + message.agentEventStream.push(thinkingEvent); + message._eventMap.set(eventId, thinkingEvent); + } + + // Accumulate content + if (data.content) { + thinkingEvent.content += data.content; + console.log('[Thinking] Event', eventId, 'accumulated:', thinkingEvent.content.length, 'chars'); + } + + } else { + // Thinking completed + const thinkingEvent = message._eventMap.get(eventId); + if (thinkingEvent) { + console.log('[Thinking] Completing event, event_id:', eventId, 'content length:', thinkingEvent.content.length); + + // Mark as done + thinkingEvent.done = true; + thinkingEvent.thinking = false; + thinkingEvent.duration_ms = data.data?.duration_ms || (Date.now() - thinkingEvent.startTime); + thinkingEvent.completed_at = data.data?.completed_at || Date.now(); + + console.log('[Thinking] Event completed, duration:', thinkingEvent.duration_ms, 'ms'); + } else { + console.warn('[Thinking] Received done for unknown event_id:', eventId); + } + } + } + break; + + case 'tool_call': + // Store pending tool call to pair with result later + if (data.data && data.data.tool_name) { + console.log('[Tool Call]', data.data.tool_name); + + if (!message.agentEventStream) message.agentEventStream = []; + if (!message._pendingToolCalls) message._pendingToolCalls = new Map(); + + const toolCallId = data.data.tool_call_id || (data.data.tool_name + '_' + Date.now()); + + // Create tool call event + const toolCallEvent = { + type: 'tool_call', + tool_call_id: toolCallId, + tool_name: data.data.tool_name, + arguments: data.data.arguments, + timestamp: Date.now(), + pending: true + }; + + // Add to event stream + message.agentEventStream.push(toolCallEvent); + message._pendingToolCalls.set(toolCallId, toolCallEvent); + } + break; + + case 'tool_result': + case 'error': + // Tool result - update the corresponding tool call event + if (data.data) { + const toolCallId = data.data.tool_call_id; + const toolName = data.data.tool_name; + const success = data.response_type !== 'error' && data.data.success !== false; + + console.log('[Tool Result]', { + tool_call_id: toolCallId, + tool_name: toolName, + success: success + }); + + // Find and update the pending tool call event + let toolCallEvent = null; + if (message._pendingToolCalls) { + if (toolCallId && message._pendingToolCalls.has(toolCallId)) { + toolCallEvent = message._pendingToolCalls.get(toolCallId); + message._pendingToolCalls.delete(toolCallId); + } else { + // Try to find by tool_name if no tool_call_id match + for (const [key, value] of message._pendingToolCalls.entries()) { + if (value.tool_name === toolName) { + toolCallEvent = value; + message._pendingToolCalls.delete(key); + break; + } + } + } + } + + if (toolCallEvent) { + // Update the existing event with result + toolCallEvent.pending = false; + toolCallEvent.success = success; + toolCallEvent.output = success ? (data.data.output || data.content) : (data.data.error || data.content); + toolCallEvent.error = !success ? (data.data.error || data.content) : undefined; + toolCallEvent.duration = data.data.duration_ms; + toolCallEvent.display_type = data.data.display_type; + toolCallEvent.tool_data = data.data; + + console.log('[Tool Result] Updated event in stream'); + } else { + console.warn('[Tool Result] No pending tool call found for', toolCallId || toolName); + } + + // If this is an error response without tool data, handle it + if (data.response_type === 'error' && !toolName) { + message.content = data.content || '处理出错'; + isReplying.value = false; + } + } else if (data.response_type === 'error') { + // Generic error without tool context + message.content = data.content || '处理出错'; + isReplying.value = false; + } + break; + + + case 'references': + // 知识引用 + if (data.knowledge_references) { + message.knowledge_references = data.knowledge_references; + } + break; + + case 'answer': + // 最终答案 + message.thinking = false; + message.content = (message.content || '') + (data.content || ''); + fullContent.value += data.content || ''; + + // Add or update answer event in agentEventStream + if (!message.agentEventStream) message.agentEventStream = []; + + let answerEvent = message.agentEventStream.find((e) => e.type === 'answer'); + if (!answerEvent) { + answerEvent = { + type: 'answer', + content: '', + done: false + }; + message.agentEventStream.push(answerEvent); + } + + answerEvent.content = message.content; + answerEvent.done = data.done; + + if (data.done) { + console.log('[Agent] Answer done, content length:', message.content?.length || 0); + + // 完成 + isReplying.value = false; + fullContent.value = ''; + + // 生成标题 + if (isFirstSession.value || isNeedTitle.value) { + generateSessionsTitle(session_id.value, { + messages: [{ role: "user", content: userquery.value }] + }).then(res => { + if (res.data) { + usemenuStore.changeIsFirstSession(false); + usemenuStore.updatasessionTitle(session_id.value, res.data); + isNeedTitle.value = false; + } + }); + } + } + break; + } + + scrollToBottom(); +}; + const updateAssistantSession = (payload) => { const message = messagesList.findLast((item) => { if (item.request_id === payload.id) { @@ -296,6 +556,30 @@ onBeforeRouteUpdate((to, from, next) => { } +.agent-mode-indicator { + display: flex; + align-items: center; + gap: 8px; + padding: 8px 16px; + background: linear-gradient(135deg, #e6f7ff 0%, #bae7ff 100%); + border: 1px solid #91d5ff; + border-radius: 6px; + margin-bottom: 12px; + max-width: 800px; + width: 100%; + + .agent-icon { + font-size: 20px; + } + + .agent-text { + font-size: 14px; + font-weight: 500; + color: #0050b3; + flex: 1; + } +} + .msg_list { display: flex; flex-direction: column; diff --git a/frontend/src/views/creatChat/creatChat.vue b/frontend/src/views/creatChat/creatChat.vue index 10783ba6..3cf56d6c 100644 --- a/frontend/src/views/creatChat/creatChat.vue +++ b/frontend/src/views/creatChat/creatChat.vue @@ -2,113 +2,77 @@
- 基于知识库内容问答 + 基于知识库内容问答 - AI 问答
- - - - - - - - - - - diff --git a/frontend/src/views/initialization/InitializationContent.vue b/frontend/src/views/initialization/InitializationContent.vue index e26716f8..4c51ff4a 100644 --- a/frontend/src/views/initialization/InitializationContent.vue +++ b/frontend/src/views/initialization/InitializationContent.vue @@ -971,6 +971,88 @@
+ +
+

+ Agent 智能问答配置 + 已启用 + 未启用 +

+ +
+ +
+ + + +
+ 启用 Agent 模式,通过 ReAct 推理框架回答复杂问题 + + 了解更多 + +
+
+
+
+ + +
+
+ + +
Agent 最多执行多少步推理,建议 5-10 步
+
+
+ +
+ + +
控制回答的随机性,0=更精确,1=更有创造性
+
+
+ +
+ + +
指定用于 Agent 推理的模型 ID
+
+
+ +
+ + + 知识库检索 + 多知识库检索 + 列出知识库 + 获取文档块详情 + 获取相关文档块 + 查询知识图谱 + 获取文档信息 + +
选择 Agent 可以使用的工具
+
+
+
+
+
+ + + +
+

什么是 Agent 模式?

+

Agent 模式基于 ReAct (Reasoning + Acting) 框架,能够通过以下方式回答复杂问题:

+
    +
  • 多步推理:Agent 会分步思考和分析问题
  • +
  • 工具调用:根据需要调用知识库检索等工具
  • +
  • 自我反思:评估中间结果并调整策略
  • +
  • 上下文记忆:支持多轮连续对话
  • +
+ +

适用场景

+
    +
  • 需要对比分析多个文档
  • +
  • 需要多步推理的复杂问题
  • +
  • 需要在多个知识库中查找信息
  • +
  • 需要深度分析和总结
  • +
+ +

与普通模式的区别

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
特性普通模式Agent 模式
推理方式单次检索+生成多步推理循环
工具使用固定流程动态决策
适用问题简单直接问题复杂推理问题
响应时间快相对较慢
+
+
@@ -1188,9 +1326,19 @@ const formData = reactive({ tags: [] as string[], nodes: [] as Node[], relations: [] as Relation[] + }, + agent: { + enabled: false, + maxIterations: 5, + temperature: 0.7, + thinkingModelId: '', + allowedTools: ['knowledge_search', 'multi_kb_search', 'list_knowledge_bases'] } }); +// Agent 帮助对话框状态 +const showAgentHelp = ref(false); + // 输入防抖定时器 const inputDebounceTimers = reactive>({}); @@ -1637,6 +1785,18 @@ const loadCurrentConfig = async () => { } } + // 回填 Agent 配置 + if ((config as any).agent) { + Object.assign(formData.agent, { + enabled: (config as any).agent.enabled || false, + maxIterations: (config as any).agent.maxIterations || 5, + temperature: (config as any).agent.temperature || 0.7, + thinkingModelId: (config as any).agent.thinkingModelId || '', + allowedTools: (config as any).agent.allowedTools || ['knowledge_search', 'multi_kb_search', 'list_knowledge_bases'] + }); + console.log('Agent config loaded:', formData.agent); + } + // 在配置加载完成后,检查模型状态 await checkModelsAfterLoading(config); @@ -3564,4 +3724,81 @@ onMounted(async () => { .select-input-node > li:hover { background-color: var(--td-bg-color-container-hover); } + +/* Agent 配置样式 */ +.agent-detail-config { + margin-top: 16px; + padding-left: 20px; + border-left: 3px solid #0052d9; +} + +.checkbox-with-label { + display: flex; + align-items: center; +} + +.field-description { + font-size: 12px; + color: #00000099; + margin-top: 4px; +} + +/* Agent 帮助对话框样式 */ +.agent-help-content { + h4 { + font-size: 14px; + font-weight: 600; + color: #000000; + margin: 16px 0 8px 0; + + &:first-child { + margin-top: 0; + } + } + + p { + font-size: 14px; + color: #00000099; + line-height: 1.6; + margin: 8px 0; + } + + ul { + margin: 8px 0; + padding-left: 20px; + + li { + font-size: 14px; + color: #00000099; + line-height: 1.8; + + strong { + color: #000000; + } + } + } + + .comparison-table { + width: 100%; + border-collapse: collapse; + margin: 12px 0; + font-size: 13px; + + th, td { + border: 1px solid #e7e7e7; + padding: 8px 12px; + text-align: left; + } + + th { + background: #f5f5f5; + font-weight: 600; + color: #000000; + } + + td { + color: #00000099; + } + } +} \ No newline at end of file diff --git a/frontend/src/views/settings/AgentSettings.vue b/frontend/src/views/settings/AgentSettings.vue new file mode 100644 index 00000000..63402b56 --- /dev/null +++ b/frontend/src/views/settings/AgentSettings.vue @@ -0,0 +1,652 @@ + + + + + + diff --git a/frontend/src/views/settings/GeneralSettings.vue b/frontend/src/views/settings/GeneralSettings.vue new file mode 100644 index 00000000..c2330b15 --- /dev/null +++ b/frontend/src/views/settings/GeneralSettings.vue @@ -0,0 +1,167 @@ + + + + + + diff --git a/frontend/src/views/settings/KnowledgeBaseSettings.vue b/frontend/src/views/settings/KnowledgeBaseSettings.vue new file mode 100644 index 00000000..f2043863 --- /dev/null +++ b/frontend/src/views/settings/KnowledgeBaseSettings.vue @@ -0,0 +1,216 @@ + + + + + + diff --git a/frontend/src/views/settings/ModelSettings.vue b/frontend/src/views/settings/ModelSettings.vue new file mode 100644 index 00000000..30924455 --- /dev/null +++ b/frontend/src/views/settings/ModelSettings.vue @@ -0,0 +1,633 @@ + + + + + diff --git a/frontend/src/views/settings/OllamaSettings.vue b/frontend/src/views/settings/OllamaSettings.vue new file mode 100644 index 00000000..7d3bfe54 --- /dev/null +++ b/frontend/src/views/settings/OllamaSettings.vue @@ -0,0 +1,641 @@ + + + + + diff --git a/frontend/src/views/settings/Settings.vue b/frontend/src/views/settings/Settings.vue index 616e43ae..fe511672 100644 --- a/frontend/src/views/settings/Settings.vue +++ b/frontend/src/views/settings/Settings.vue @@ -1,100 +1,489 @@ \ No newline at end of file + +/* 弹窗容器 */ +.settings-modal { + position: relative; + width: 100%; + max-width: 900px; + height: 700px; + background: #ffffff; + border-radius: 12px; + box-shadow: 0 6px 28px rgba(15, 23, 42, 0.08); + overflow: hidden; + display: flex; + flex-direction: column; +} + +/* 关闭按钮 */ +.close-btn { + position: absolute; + top: 16px; + right: 16px; + width: 32px; + height: 32px; + border: none; + background: transparent; + color: #666666; + cursor: pointer; + border-radius: 6px; + display: flex; + align-items: center; + justify-content: center; + transition: all 0.2s ease; + z-index: 10; + + &:hover { + background: #f5f5f5; + color: #333333; + } +} + +.settings-container { + display: flex; + height: 100%; + width: 100%; + overflow: hidden; +} + +/* 左侧导航栏 */ +.settings-sidebar { + width: 220px; + background-color: #f8f9fa; + border-right: 1px solid #e5e7eb; + flex-shrink: 0; + overflow-y: auto; + display: flex; + flex-direction: column; +} + +.sidebar-header { + padding: 24px 16px 16px; + border-bottom: 1px solid #e5e7eb; +} + +.sidebar-title { + font-size: 18px; + font-weight: 600; + color: #333333; + margin: 0; +} + +.settings-nav { + padding: 16px 8px; + flex: 1; +} + +.nav-item { + display: flex; + align-items: center; + padding: 10px 16px; + margin-bottom: 4px; + border-radius: 6px; + cursor: pointer; + color: #666666; + font-size: 14px; + transition: all 0.2s ease; + user-select: none; + + &:hover { + background-color: #e8f5ed; + color: #333333; + } + + &.active { + background-color: rgba(7, 192, 95, 0.1); + color: #07C05F; + font-weight: 500; + } +} + +.nav-icon { + margin-right: 12px; + font-size: 16px; + display: flex; + align-items: center; + justify-content: center; + width: 20px; + height: 20px; +} + +.nav-label { + flex: 1; +} + +.expand-icon { + margin-left: 4px; + font-size: 14px; + transition: transform 0.2s ease; +} + +/* 子菜单 */ +.submenu { + margin-left: 32px; + margin-bottom: 4px; + overflow: hidden; +} + +.submenu-item { + padding: 8px 16px; + margin-bottom: 2px; + border-radius: 4px; + cursor: pointer; + color: #666666; + font-size: 13px; + transition: all 0.2s ease; + user-select: none; + + &:hover { + background-color: #f5f7fa; + color: #333333; + } + + &.active { + background-color: rgba(7, 192, 95, 0.08); + color: #07C05F; + font-weight: 500; + } +} + +.submenu-label { + display: block; +} + +/* 子菜单动画 */ +.submenu-enter-active, +.submenu-leave-active { + transition: all 0.2s ease; +} + +.submenu-enter-from { + opacity: 0; + max-height: 0; +} + +.submenu-enter-to { + opacity: 1; + max-height: 300px; +} + +.submenu-leave-from { + opacity: 1; + max-height: 300px; +} + +.submenu-leave-to { + opacity: 0; + max-height: 0; +} + +/* 右侧内容区域 */ +.settings-content { + flex: 1; + overflow-y: auto; + background-color: #ffffff; +} + +.content-wrapper { + max-width: 600px; + padding: 40px 48px; +} + +.section { + animation: fadeIn 0.3s ease; +} + +@keyframes fadeIn { + from { + opacity: 0; + transform: translateY(10px); + } + to { + opacity: 1; + transform: translateY(0); + } +} + +/* 弹窗动画 */ +.modal-enter-active, +.modal-leave-active { + transition: opacity 0.2s ease; +} + +.modal-enter-active .settings-modal, +.modal-leave-active .settings-modal { + transition: transform 0.2s ease, opacity 0.2s ease; +} + +.modal-enter-from, +.modal-leave-to { + opacity: 0; +} + +.modal-enter-from .settings-modal, +.modal-leave-to .settings-modal { + transform: scale(0.95); + opacity: 0; +} + +/* 滚动条样式 */ +.settings-sidebar::-webkit-scrollbar, +.settings-content::-webkit-scrollbar { + width: 6px; +} + +.settings-sidebar::-webkit-scrollbar-track { + background: #f8f9fa; +} + +.settings-sidebar::-webkit-scrollbar-thumb { + background: #d0d0d0; + border-radius: 3px; +} + +.settings-sidebar::-webkit-scrollbar-thumb:hover { + background: #b0b0b0; +} + +.settings-content::-webkit-scrollbar-track { + background: #ffffff; +} + +.settings-content::-webkit-scrollbar-thumb { + background: #d0d0d0; + border-radius: 3px; +} + +.settings-content::-webkit-scrollbar-thumb:hover { + background: #b0b0b0; +} + + diff --git a/frontend/src/views/settings/SystemInfo.vue b/frontend/src/views/settings/SystemInfo.vue new file mode 100644 index 00000000..258e9b96 --- /dev/null +++ b/frontend/src/views/settings/SystemInfo.vue @@ -0,0 +1,533 @@ + + + + + diff --git a/frontend/src/views/settings/SystemSettings.vue b/frontend/src/views/settings/SystemSettings.vue deleted file mode 100644 index 17ba9e1c..00000000 --- a/frontend/src/views/settings/SystemSettings.vue +++ /dev/null @@ -1,211 +0,0 @@ - - - - - diff --git a/internal/agent/engine.go b/internal/agent/engine.go new file mode 100644 index 00000000..77fa25e9 --- /dev/null +++ b/internal/agent/engine.go @@ -0,0 +1,725 @@ +package agent + +import ( + "context" + "encoding/json" + "fmt" + "strings" + "time" + + "github.com/Tencent/WeKnora/internal/agent/tools" + "github.com/Tencent/WeKnora/internal/event" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/models/chat" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/google/uuid" +) + +// generateEventID generates a unique event ID with type suffix for better traceability +func generateEventID(suffix string) string { + return fmt.Sprintf("%s-%s", uuid.New().String()[:8], suffix) +} + +// AgentEngine is the core engine for running ReAct agents +type AgentEngine struct { + config *types.AgentConfig + toolRegistry *tools.ToolRegistry + chatModel chat.Chat + knowledgeService interfaces.KnowledgeBaseService + eventBus *event.EventBus + knowledgeBasesInfo []*KnowledgeBaseInfo // Detailed knowledge base information for prompt +} + +// listToolNames returns tool.function names for logging +func listToolNames(ts []chat.Tool) []string { + names := make([]string, 0, len(ts)) + for _, t := range ts { + names = append(names, t.Function.Name) + } + return names +} + +// NewAgentEngine creates a new agent engine +func NewAgentEngine( + config *types.AgentConfig, + chatModel chat.Chat, + toolRegistry *tools.ToolRegistry, + knowledgeService interfaces.KnowledgeBaseService, + eventBus *event.EventBus, + knowledgeBasesInfo []*KnowledgeBaseInfo, +) *AgentEngine { + if eventBus == nil { + eventBus = event.NewEventBus() + } + return &AgentEngine{ + config: config, + toolRegistry: toolRegistry, + chatModel: chatModel, + knowledgeService: knowledgeService, + eventBus: eventBus, + knowledgeBasesInfo: knowledgeBasesInfo, + } +} + +// Execute executes the agent with conversation history and streaming output +// All events are emitted to EventBus and handled by subscribers (like Handler layer) +func (e *AgentEngine) Execute(ctx context.Context, sessionID, query string, llmContext []chat.Message) (*types.AgentState, error) { + logger.Infof(ctx, "========== Agent Execution Started ==========") + logger.Infof(ctx, "[Agent] SessionID: %s", sessionID) + logger.Infof(ctx, "[Agent] User Query: %s", query) + logger.Infof(ctx, "[Agent] LLM Context Messages: %d", len(llmContext)) + + // Initialize state + state := &types.AgentState{ + RoundSteps: []types.AgentStep{}, + KnowledgeRefs: []*types.SearchResult{}, + IsComplete: false, + CurrentRound: 0, + } + + // Build system prompt + systemPrompt := BuildReActSystemPrompt(e.knowledgeBasesInfo) + logger.Debugf(ctx, "[Agent] SystemPrompt Length: %d characters", len(systemPrompt)) + logger.Debugf(ctx, "[Agent] SystemPrompt (stream)\n----\n%s\n----", systemPrompt) + + // Initialize messages with history + messages := e.buildMessagesWithLLMContext(systemPrompt, query, llmContext) + logger.Infof(ctx, "[Agent] Total messages for LLM: %d (system: 1, history: %d, user query: 1)", + len(messages), len(llmContext)) + + // Get tool definitions for function calling + tools := e.buildToolsForLLM() + logger.Infof(ctx, "[Agent] Tools enabled (%d): %s", len(tools), strings.Join(listToolNames(tools), ", ")) + + _, err := e.executeLoop(ctx, state, query, messages, tools, sessionID) + if err != nil { + logger.Errorf(ctx, "[Agent] Execution failed: %v", err) + e.eventBus.Emit(ctx, event.Event{ + ID: generateEventID("error"), + Type: event.EventError, + SessionID: sessionID, + Data: event.ErrorData{ + Error: err.Error(), + Stage: "agent_execution", + SessionID: sessionID, + }, + }) + return nil, err + } + + logger.Infof(ctx, "========== Agent Execution Completed Successfully ==========") + logger.Infof(ctx, "[Agent] Total rounds: %d, Round steps: %d, Is complete: %v", + state.CurrentRound, len(state.RoundSteps), state.IsComplete) + return state, nil +} + +// executeLoop executes the main ReAct loop +// All events are emitted through EventBus with the given sessionID +func (e *AgentEngine) executeLoop( + ctx context.Context, + state *types.AgentState, + query string, + messages []chat.Message, + tools []chat.Tool, + sessionID string, +) (*types.AgentState, error) { + startTime := time.Now() + for state.CurrentRound < e.config.MaxIterations { + roundStart := time.Now() + logger.Infof(ctx, "========== Round %d/%d Started ==========", state.CurrentRound+1, e.config.MaxIterations) + logger.Infof(ctx, "[Agent][Round-%d] Message history size: %d messages", state.CurrentRound+1, len(messages)) + + // 1. Think: Call LLM with function calling and stream thinking through EventBus + logger.Infof(ctx, "[Agent][Round-%d] Calling LLM with %d tools available...", state.CurrentRound+1, len(tools)) + response, err := e.streamThinkingToEventBus(ctx, messages, tools, state.CurrentRound, sessionID) + if err != nil { + logger.Errorf(ctx, "[Agent][Round-%d] LLM call failed: %v", state.CurrentRound+1, err) + return state, fmt.Errorf("LLM call failed: %w", err) + } + + // Debug: log finish reason and tool call count from LLM + logger.Infof(ctx, "[Agent][Round-%d] LLM response received: finish_reason=%s, tool_calls=%d, content_length=%d", + state.CurrentRound+1, response.FinishReason, len(response.ToolCalls), len(response.Content)) + logger.Debugf(ctx, "[Agent] LLM response finish=%s, toolCalls=%d", response.FinishReason, len(response.ToolCalls)) + if response.Content != "" { + logger.Debugf(ctx, "[Agent][Round-%d] LLM thought content:\n%s", state.CurrentRound+1, response.Content) + } + + // Create agent step + step := types.AgentStep{ + Iteration: state.CurrentRound, + Thought: response.Content, + ToolCalls: make([]types.ToolCall, 0), + Timestamp: time.Now(), + } + + // Emit step event + e.eventBus.Emit(ctx, event.Event{ + ID: generateEventID("step"), + Type: event.EventAgentStep, + SessionID: sessionID, + Data: event.AgentStepData{ + Iteration: state.CurrentRound, + Thought: response.Content, + ToolCalls: step.ToolCalls, + Duration: time.Since(roundStart).Milliseconds(), + }, + }) + + // 2. Check finish reason - if stop and no tool calls, agent is done + if response.FinishReason == "stop" && len(response.ToolCalls) == 0 { + logger.Infof(ctx, "[Agent][Round-%d] Agent finished - no more tool calls needed", state.CurrentRound+1) + logger.Infof(ctx, "[Agent] Final answer length: %d characters", len(response.Content)) + state.FinalAnswer = response.Content + state.IsComplete = true + state.RoundSteps = append(state.RoundSteps, step) + + // Emit final answer done marker + e.eventBus.Emit(ctx, event.Event{ + ID: generateEventID("answer-done"), + Type: event.EventAgentFinalAnswer, + SessionID: sessionID, + Data: event.AgentFinalAnswerData{ + Content: "", + Done: true, + }, + }) + logger.Infof(ctx, "[Agent][Round-%d] Duration: %dms", state.CurrentRound+1, time.Since(roundStart).Milliseconds()) + break + } + + // 3. Act: Execute tool calls if any + if len(response.ToolCalls) > 0 { + logger.Infof(ctx, "[Agent][Round-%d] Executing %d tool calls...", state.CurrentRound+1, len(response.ToolCalls)) + + for i, tc := range response.ToolCalls { + logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool: %s, ID: %s", + state.CurrentRound+1, i+1, len(response.ToolCalls), tc.Function.Name, tc.ID) + + var args map[string]any + if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil { + logger.Errorf(ctx, "[Agent][Round-%d][Tool-%d/%d] Failed to parse tool arguments: %v", + state.CurrentRound+1, i+1, len(response.ToolCalls), err) + continue + } + + // Log the arguments in a readable format + argsJSON, _ := json.MarshalIndent(args, "", " ") + logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Arguments:\n%s", + state.CurrentRound+1, i+1, len(response.ToolCalls), string(argsJSON)) + + toolCallStartTime := time.Now() + e.eventBus.Emit(ctx, event.Event{ + ID: tc.ID + "-tool-call", + Type: event.EventAgentToolCall, + SessionID: sessionID, + Data: event.AgentToolCallData{ + ToolCallID: tc.ID, + ToolName: tc.Function.Name, + Arguments: args, + Iteration: state.CurrentRound, + }, + }) + logger.Debugf(ctx, "[Agent] ToolCall -> %s args=%s", tc.Function.Name, tc.Function.Arguments) + + // Execute tool + logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Executing tool: %s...", + state.CurrentRound+1, i+1, len(response.ToolCalls), tc.Function.Name) + result, err := e.toolRegistry.ExecuteTool(ctx, tc.Function.Name, args) + duration := time.Since(toolCallStartTime).Milliseconds() + logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool execution completed in %dms", + state.CurrentRound+1, i+1, len(response.ToolCalls), duration) + + toolCall := types.ToolCall{ + ID: tc.ID, + Name: tc.Function.Name, + Args: args, + Result: result, + Duration: duration, + } + + if err != nil { + logger.Errorf(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool call failed: %s, error: %v", + state.CurrentRound+1, i+1, len(response.ToolCalls), tc.Function.Name, err) + toolCall.Result = &types.ToolResult{ + Success: false, + Error: err.Error(), + } + } + + if toolCall.Result != nil { + logger.Infof(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool result: success=%v, output_length=%d", + state.CurrentRound+1, i+1, len(response.ToolCalls), + toolCall.Result.Success, len(toolCall.Result.Output)) + logger.Debugf(ctx, "[Agent] ToolResult <- %s success=%v len(output)=%d", + tc.Function.Name, toolCall.Result.Success, len(toolCall.Result.Output)) + + // Log the output content for debugging + if toolCall.Result.Output != "" { + // Truncate if too long for logging + outputPreview := toolCall.Result.Output + if len(outputPreview) > 500 { + outputPreview = outputPreview[:500] + "... (truncated)" + } + logger.Debugf(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool output preview:\n%s", + state.CurrentRound+1, i+1, len(response.ToolCalls), outputPreview) + } + + if toolCall.Result.Error != "" { + logger.Warnf(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool error: %s", + state.CurrentRound+1, i+1, len(response.ToolCalls), toolCall.Result.Error) + } + + // Log structured data if present + if toolCall.Result.Data != nil { + dataJSON, _ := json.MarshalIndent(toolCall.Result.Data, "", " ") + logger.Debugf(ctx, "[Agent][Round-%d][Tool-%d/%d] Tool data:\n%s", + state.CurrentRound+1, i+1, len(response.ToolCalls), string(dataJSON)) + } + } + + // Store tool call (Observations are now derived from ToolCall.Result.Output) + step.ToolCalls = append(step.ToolCalls, toolCall) + + // Emit tool result event (include structured data from tool result) + e.eventBus.Emit(ctx, event.Event{ + ID: tc.ID + "-tool-result", + Type: event.EventAgentToolResult, + SessionID: sessionID, + Data: event.AgentToolResultData{ + ToolCallID: tc.ID, + ToolName: tc.Function.Name, + Output: result.Output, + Error: result.Error, + Success: result.Success, + Duration: duration, + Iteration: state.CurrentRound, + Data: result.Data, // Pass structured data for frontend rendering + }, + }) + + // Emit tool execution event (for internal monitoring) + e.eventBus.Emit(ctx, event.Event{ + ID: tc.ID + "-tool-exec", + Type: event.EventAgentTool, + SessionID: sessionID, + Data: event.AgentActionData{ + Iteration: state.CurrentRound, + ToolName: tc.Function.Name, + ToolInput: args, + ToolOutput: result.Output, + Success: result.Success, + Error: result.Error, + Duration: duration, + }, + }) + + // Optional: Reflection after each tool call (streaming) + if e.config.ReflectionEnabled && result != nil { + reflection, err := e.streamReflectionToEventBus( + ctx, tc.ID, tc.Function.Name, args, result.Output, + state.CurrentRound, sessionID, + ) + if err != nil { + logger.Warnf(ctx, "Reflection failed: %v", err) + } else if reflection != "" { + // Store reflection in the corresponding tool call + // Find the tool call we just added and update it + if len(step.ToolCalls) > 0 { + lastIdx := len(step.ToolCalls) - 1 + step.ToolCalls[lastIdx].Reflection = reflection + } + } + } + } + } + + state.RoundSteps = append(state.RoundSteps, step) + // 4. Observe: Add tool results to messages + messages = e.appendToolResults(messages, step) + // 5. Check if we should continue + state.CurrentRound++ + } + + // If loop finished without final answer, generate one + if !state.IsComplete { + logger.Info(ctx, "Reached max iterations, generating final answer") + + // Stream final answer generation through EventBus + if err := e.streamFinalAnswerToEventBus(ctx, query, state, sessionID); err != nil { + logger.Errorf(ctx, "Failed to synthesize final answer: %v", err) + state.FinalAnswer = "抱歉,我无法生成完整的答案。" + } + state.IsComplete = true + } + + // Emit completion event + // Convert knowledge refs to interface{} slice for event data + knowledgeRefsInterface := make([]interface{}, 0, len(state.KnowledgeRefs)) + for _, ref := range state.KnowledgeRefs { + knowledgeRefsInterface = append(knowledgeRefsInterface, ref) + } + + e.eventBus.Emit(ctx, event.Event{ + ID: generateEventID("complete"), + Type: event.EventAgentComplete, + SessionID: sessionID, + Data: event.AgentCompleteData{ + FinalAnswer: state.FinalAnswer, + KnowledgeRefs: knowledgeRefsInterface, + AgentSteps: state.RoundSteps, // Include detailed execution steps for message storage + TotalSteps: len(state.RoundSteps), + TotalDuration: time.Since(startTime).Milliseconds(), + }, + }) + + logger.Infof(ctx, "Agent execution completed in %d rounds", state.CurrentRound) + return state, nil +} + +// buildToolsForLLM builds the tools list for LLM function calling +func (e *AgentEngine) buildToolsForLLM() []chat.Tool { + functionDefs := e.toolRegistry.GetFunctionDefinitions(e.config.AllowedTools) + tools := make([]chat.Tool, 0, len(functionDefs)) + for _, def := range functionDefs { + tools = append(tools, chat.Tool{ + Type: "function", + Function: chat.FunctionDef{ + Name: def.Name, + Description: def.Description, + Parameters: def.Parameters, + }, + }) + } + + return tools +} + +// appendToolResults adds tool results to the message history following OpenAI's tool calling format +func (e *AgentEngine) appendToolResults(messages []chat.Message, step types.AgentStep) []chat.Message { + // Add assistant message with tool calls (if any) + if step.Thought != "" || len(step.ToolCalls) > 0 { + assistantMsg := chat.Message{ + Role: "assistant", + Content: step.Thought, + } + + // Add tool calls to assistant message (following OpenAI format) + if len(step.ToolCalls) > 0 { + assistantMsg.ToolCalls = make([]chat.ToolCall, 0, len(step.ToolCalls)) + for _, tc := range step.ToolCalls { + // Convert arguments back to JSON string + argsJSON, _ := json.Marshal(tc.Args) + + assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, chat.ToolCall{ + ID: tc.ID, + Type: "function", + Function: chat.FunctionCall{ + Name: tc.Name, + Arguments: string(argsJSON), + }, + }) + } + } + + messages = append(messages, assistantMsg) + } + + // Add tool result messages (role: "tool", following OpenAI format) + for _, toolCall := range step.ToolCalls { + resultContent := toolCall.Result.Output + if !toolCall.Result.Success { + resultContent = fmt.Sprintf("Error: %s", toolCall.Result.Error) + } + + messages = append(messages, chat.Message{ + Role: "tool", + Content: resultContent, + ToolCallID: toolCall.ID, + Name: toolCall.Name, + }) + } + + return messages +} + +// streamLLMToEventBus streams LLM response through EventBus (generic method) +// emitFunc: callback to emit each chunk event +// Returns: full accumulated content, tool calls (if any), error +func (e *AgentEngine) streamLLMToEventBus( + ctx context.Context, + messages []chat.Message, + opts *chat.ChatOptions, + emitFunc func(chunk *types.StreamResponse, fullContent string), +) (string, []types.LLMToolCall, error) { + logger.Debugf(ctx, "[Agent][Stream] Starting LLM stream with %d messages", len(messages)) + + stream, err := e.chatModel.ChatStream(ctx, messages, opts) + if err != nil { + logger.Errorf(ctx, "[Agent][Stream] Failed to start LLM stream: %v", err) + return "", nil, err + } + + fullContent := "" + var toolCalls []types.LLMToolCall + chunkCount := 0 + + for chunk := range stream { + chunkCount++ + + if chunk.Content != "" { + fullContent += chunk.Content + } + + // Collect tool calls if present + if len(chunk.ToolCalls) > 0 { + toolCalls = chunk.ToolCalls + } + + // Emit event through callback + if emitFunc != nil { + emitFunc(&chunk, fullContent) + } + } + + return fullContent, toolCalls, nil +} + +// streamReflectionToEventBus streams reflection process through EventBus +// Note: Reflection is now handled through the think tool in main loop +func (e *AgentEngine) streamReflectionToEventBus( + ctx context.Context, + toolCallID string, + toolName string, + args map[string]interface{}, + result string, + iteration int, + sessionID string, +) (string, error) { + // Simplified reflection without BuildReflectionPrompt + reflectionPrompt := fmt.Sprintf(`请评估刚才调用工具 %s 的结果,并决定下一步行动。 + +工具返回: %s + +思考: +1. 结果是否满足需求? +2. 下一步应该做什么?`, toolName, result) + + messages := []chat.Message{ + {Role: "user", Content: reflectionPrompt}, + } + + // Generate a single ID for this entire reflection stream + reflectionID := generateEventID("reflection") + + fullReflection, _, err := e.streamLLMToEventBus( + ctx, + messages, + &chat.ChatOptions{Temperature: 0.5}, + func(chunk *types.StreamResponse, fullContent string) { + if chunk.Content != "" { + e.eventBus.Emit(ctx, event.Event{ + ID: reflectionID, // Same ID for all chunks in this stream + Type: event.EventAgentReflection, + SessionID: sessionID, + Data: event.AgentReflectionData{ + ToolCallID: toolCallID, + Content: chunk.Content, + Iteration: iteration, + Done: chunk.Done, + }, + }) + } + }, + ) + + if err != nil { + logger.Warnf(ctx, "Reflection failed: %v", err) + return "", err + } + + return fullReflection, nil +} + +// streamThinkingToEventBus streams the thinking process through EventBus +func (e *AgentEngine) streamThinkingToEventBus( + ctx context.Context, + messages []chat.Message, + tools []chat.Tool, + iteration int, + sessionID string, +) (*types.ChatResponse, error) { + logger.Infof(ctx, "[Agent][Thinking][Iteration-%d] Starting thinking stream with temperature=%.2f, tools=%d", + iteration+1, e.config.Temperature, len(tools)) + + opts := &chat.ChatOptions{ + Temperature: e.config.Temperature, + Tools: tools, + } + logger.Debug(context.Background(), "[Agent] streamLLM opts tool_choice=auto temperature=", e.config.Temperature) + + // Generate a single ID for this entire thinking stream + thinkingID := generateEventID("thinking") + logger.Debugf(ctx, "[Agent][Thinking][Iteration-%d] ThinkingID: %s", iteration+1, thinkingID) + + fullContent, toolCalls, err := e.streamLLMToEventBus( + ctx, + messages, + opts, + func(chunk *types.StreamResponse, fullContent string) { + if chunk.Content != "" { + logger.Debugf(ctx, "[Agent][Thinking][Iteration-%d] Emitting thought chunk: %d chars", + iteration+1, len(chunk.Content)) + e.eventBus.Emit(ctx, event.Event{ + ID: thinkingID, // Same ID for all chunks in this stream + Type: event.EventAgentThought, + SessionID: sessionID, + Data: event.AgentThoughtData{ + Content: chunk.Content, + Iteration: iteration, + Done: chunk.Done, + }, + }) + } + }, + ) + + if err != nil { + logger.Errorf(ctx, "[Agent][Thinking][Iteration-%d] Thinking stream failed: %v", iteration+1, err) + return nil, err + } + + logger.Infof(ctx, "[Agent][Thinking][Iteration-%d] Thinking completed: content=%d chars, tool_calls=%d", + iteration+1, len(fullContent), len(toolCalls)) + + // Build response + return &types.ChatResponse{ + Content: fullContent, + ToolCalls: toolCalls, + FinishReason: "stop", + }, nil +} + +// streamFinalAnswerToEventBus streams the final answer generation through EventBus +func (e *AgentEngine) streamFinalAnswerToEventBus( + ctx context.Context, + query string, + state *types.AgentState, + sessionID string, +) error { + logger.Infof(ctx, "[Agent][FinalAnswer] Starting final answer generation") + logger.Infof(ctx, "[Agent][FinalAnswer] Context: %d steps with total %d tool calls", + len(state.RoundSteps), countTotalToolCalls(state.RoundSteps)) + + // Build messages with all context + systemPrompt := BuildReActSystemPrompt(e.knowledgeBasesInfo) + + messages := []chat.Message{ + {Role: "system", Content: systemPrompt}, + {Role: "user", Content: query}, + } + + // Add all tool call results as context + toolResultCount := 0 + for stepIdx, step := range state.RoundSteps { + for toolIdx, toolCall := range step.ToolCalls { + toolResultCount++ + messages = append(messages, chat.Message{ + Role: "user", + Content: fmt.Sprintf("工具 %s 返回: %s", toolCall.Name, toolCall.Result.Output), + }) + logger.Debugf(ctx, "[Agent][FinalAnswer] Added tool result [Step-%d][Tool-%d]: %s (output: %d chars)", + stepIdx+1, toolIdx+1, toolCall.Name, len(toolCall.Result.Output)) + } + } + + logger.Infof(ctx, "[Agent][FinalAnswer] Total context messages: %d (including %d tool results)", + len(messages), toolResultCount) + + // Add final answer prompt + finalPrompt := fmt.Sprintf(`基于上述工具调用结果,请为用户问题生成完整答案。 + +用户问题: %s + +要求: +1. 基于实际检索到的内容回答 +2. 清晰标注信息来源 (chunk_id, 文档名) +3. 结构化组织答案 +4. 如信息不足,诚实说明 + +现在请生成最终答案:`, query) + + messages = append(messages, chat.Message{ + Role: "user", + Content: finalPrompt, + }) + + // Generate a single ID for this entire final answer stream + answerID := generateEventID("answer") + logger.Debugf(ctx, "[Agent][FinalAnswer] AnswerID: %s", answerID) + + fullAnswer, _, err := e.streamLLMToEventBus( + ctx, + messages, + &chat.ChatOptions{Temperature: e.config.Temperature}, + func(chunk *types.StreamResponse, fullContent string) { + if chunk.Content != "" { + logger.Debugf(ctx, "[Agent][FinalAnswer] Emitting answer chunk: %d chars", len(chunk.Content)) + e.eventBus.Emit(ctx, event.Event{ + ID: answerID, // Same ID for all chunks in this stream + Type: event.EventAgentFinalAnswer, + SessionID: sessionID, + Data: event.AgentFinalAnswerData{ + Content: chunk.Content, + Done: chunk.Done, + }, + }) + } + }, + ) + + if err != nil { + logger.Errorf(ctx, "[Agent][FinalAnswer] Final answer generation failed: %v", err) + return err + } + + logger.Infof(ctx, "[Agent][FinalAnswer] Final answer generated: %d characters", len(fullAnswer)) + state.FinalAnswer = fullAnswer + return nil +} + +// countTotalToolCalls counts total tool calls across all steps +func countTotalToolCalls(steps []types.AgentStep) int { + total := 0 + for _, step := range steps { + total += len(step.ToolCalls) + } + return total +} + +// buildMessagesWithLLMContext builds the message array with LLM context +func (e *AgentEngine) buildMessagesWithLLMContext(systemPrompt, currentQuery string, llmContext []chat.Message) []chat.Message { + messages := []chat.Message{ + {Role: "system", Content: systemPrompt}, + } + + if len(llmContext) > 0 { + for _, msg := range llmContext { + if msg.Role == "system" { + continue + } + if msg.Role == "user" || msg.Role == "assistant" || msg.Role == "tool" { + messages = append(messages, msg) + } + } + logger.Infof(context.Background(), "Added %d history messages to context", len(llmContext)) + } + + messages = append(messages, chat.Message{ + Role: "user", + Content: currentQuery, + }) + + return messages +} diff --git a/internal/agent/prompts.go b/internal/agent/prompts.go new file mode 100644 index 00000000..2fa48725 --- /dev/null +++ b/internal/agent/prompts.go @@ -0,0 +1,616 @@ +package agent + +import ( + "fmt" + "strings" +) + +// formatFileSize formats file size in human-readable format +func formatFileSize(size int64) string { + const ( + KB = 1024 + MB = 1024 * KB + GB = 1024 * MB + ) + + if size < KB { + return fmt.Sprintf("%d B", size) + } else if size < MB { + return fmt.Sprintf("%.2f KB", float64(size)/KB) + } else if size < GB { + return fmt.Sprintf("%.2f MB", float64(size)/MB) + } + return fmt.Sprintf("%.2f GB", float64(size)/GB) +} + +// RecentDocInfo contains brief information about a recently added document +type RecentDocInfo struct { + KnowledgeID string + Title string + FileName string + FileSize int64 + Type string + CreatedAt string // Formatted time string +} + +// KnowledgeBaseInfo contains essential information about a knowledge base for agent prompt +type KnowledgeBaseInfo struct { + ID string + Name string + Description string + DocCount int + RecentDocs []RecentDocInfo // Recently added documents (up to 10) +} + +// formatKnowledgeBaseList formats knowledge base information for the prompt +func formatKnowledgeBaseList(kbInfos []*KnowledgeBaseInfo) string { + if len(kbInfos) == 0 { + return "None" + } + + var builder strings.Builder + builder.WriteString("\n") + for i, kb := range kbInfos { + builder.WriteString(fmt.Sprintf("%d. **%s** (knowledge_base_id: `%s`)\n", i+1, kb.Name, kb.ID)) + if kb.Description != "" { + builder.WriteString(fmt.Sprintf(" - Description: %s\n", kb.Description)) + } + builder.WriteString(fmt.Sprintf(" - Document count: %d\n", kb.DocCount)) + + // Display recent documents if available + if len(kb.RecentDocs) > 0 { + builder.WriteString(" - Recently added documents:\n\n") + builder.WriteString(" | # | Document Name | Type | Created At | Knowledge ID | File Size |\n") + builder.WriteString(" |---|---------------|------|------------|--------------|----------|\n") + for j, doc := range kb.RecentDocs { + if j >= 10 { // Limit to 10 documents + break + } + docName := doc.Title + if docName == "" { + docName = doc.FileName + } + // Format file size + fileSize := formatFileSize(doc.FileSize) + builder.WriteString(fmt.Sprintf(" | %d | %s | %s | %s | `%s` | %s |\n", + j+1, docName, doc.Type, doc.CreatedAt, doc.KnowledgeID, fileSize)) + } + builder.WriteString("\n") + } + builder.WriteString("\n") + } + return builder.String() +} + +// BuildReActSystemPrompt builds the system prompt for ReAct mode with enhanced guidance +func BuildReActSystemPrompt(knowledgeBases []*KnowledgeBaseInfo) string { + kbList := formatKnowledgeBaseList(knowledgeBases) + + prompt := fmt.Sprintf(`# Role + +You are WeKnora, an intelligent knowledge base assistant. Your mission is to provide accurate, traceable information through systematic tool use and structured task management. + +Core capabilities: +- Knowledge retrieval expert: proficient in searching and extracting information from knowledge bases +- Systematic thinker: use think and todo_write tools for planning and tracking +- Quality controller: ensure all answers are evidence-based and verifiable +- Persistent optimizer: adjust strategies based on results, never give up easily + +# Known Information + +## Available Knowledge Bases +%s + +## Available Tools + +You have 7 core tools: + +Planning & Thinking: +1. thinking - Strategic analysis and decision making + - Use for: problem analysis, result evaluation, strategy planning + - Frequency: very high (before any important decision) + - Cost: zero, always beneficial + +2. todo_write - Task management (strongly recommended) + - Use for: creating and updating task lists, tracking multi-step research + - Frequency: very high (any task requiring 2+ steps) + - Purpose: organize complex tasks, prevent omissions, maintain focus + - Critical: must use for multi-step tasks + +Search & Retrieval: +3. knowledge_search - Primary search tool + - Capabilities: vector search, keyword search, hybrid search + - Automatic ReRank: unifies scores from different sources to 0-1 range + - Supports: multi-knowledge base search, parallel queries + - Frequency: very high (most common retrieval tool) + +4. get_related_chunks - Context expansion + - Use for: retrieving adjacent chunks (sequential) or semantically similar chunks (semantic) + - When: need to understand context or find related content + +5. get_document_info - Document metadata + - Use for: document metadata, structure, statistics + - When: need document background or exploration + +Data & Analytics: +6. database_query - Direct database queries + - Use for: statistical analysis, status queries, data aggregation + - Capabilities: execute SQL queries with automatic tenant_id security injection + - When: need counts, aggregations, system status, storage usage, or structured data queries + - Safety: read-only SELECT queries, automatic tenant isolation + +Advanced Tools: +7. query_knowledge_graph - Knowledge graph queries + - Use for: exploring entity relationships and concept associations + - When: need to understand inter-entity or concept networks + +# Core Principles + +## 1. Accuracy First - Evidence-Based Answers +- All answers must be based on knowledge base retrieval results +- Strictly prohibited: fabrication, guessing, or using external information +- Required: provide source citations for key information (chunk_id, document name, relevance score) +- Be honest: clearly state when information is insufficient, suggest query improvements + +## 2. Systematic Approach - Organized Workflow +- Think before acting: use think tool for analysis and planning (frequent use recommended) +- Organize complex tasks: use todo_write for multi-step tasks (strongly recommended) +- Track progress: update todo status to ensure no steps are missed +- Evaluate results: assess quality after each tool call, decide next steps +- Know when to stop: generate answer when sufficient information is gathered +- Quality over speed: multiple tool calls for better answers is worthwhile +- Never give up easily: one failed search doesn't mean no answer exists, try different strategies + +## 3. Citation Requirements - Traceability +- All key assertions must have chunk_id citations +- Note relevance scores (must indicate when score < 0.7) +- When using 3+ sources, must provide summary list at end +- Citation format must follow strict standards (see below) + +## 4. Task Management Best Practices - Using todo_write +- When to use: any task requiring 2+ steps +- Creation timing: after problem analysis, before execution +- Update frequency: immediately update status after completing each step +- Status management: pending -> in_progress -> completed +- Flexible adjustment: skip unnecessary steps based on findings + +# Standard Workflows + +## Simple Query Pattern (single factual query) +`+"```"+` +User question + ↓ +think (quick analysis: what information needed? which KB?) + ↓ +knowledge_search + ↓ +evaluate quality + ↓ + if high quality (>=0.7) → answer with citations + else if medium quality (0.5-0.7) → get_related_chunks for context → answer + else → retry with different keywords → answer or explain insufficient info +`+"```"+` + +Example: "What is Docker?" +Characteristics: single step, no todo_write needed + +## Complex Research Pattern (multi-dimensional, strongly recommend todo_write) +`+"```"+` +User question + ↓ +think (deep analysis: identify multiple dimensions, what information needed) + ↓ +todo_write (create structured task list: step1, step2, step3) + ↓ +Execute step1: mark in_progress → knowledge_search → think (evaluate) → mark completed + ↓ +Execute step2: mark in_progress → knowledge_search → get_related_chunks → mark completed + ↓ +Execute step3: mark in_progress → query_knowledge_graph → mark completed + ↓ +think (integrate all findings, check completeness) + ↓ +comprehensive answer (cite all sources) +`+"```"+` + +Example: "How to design a highly available microservices architecture?" +Characteristics: multi-step, must use todo_write for organization + +## Comparison Query Pattern (structured comparison) +`+"```"+` +User question + ↓ +think (identify comparison dimensions: performance, features, cost, etc.) + ↓ +todo_write (create comparison tasks: research A, research B, synthesize) + ↓ +Mark step1 in_progress → knowledge_search(target A) → get_related_chunks → completed + ↓ +Mark step2 in_progress → knowledge_search(target B) → get_related_chunks → completed + ↓ +Mark step3 in_progress → think (comparative analysis) → structured answer → completed +`+"```"+` + +Example: "Compare Redis and Memcached" +Characteristics: structured comparison, use todo_write for fair coverage + +## Exploration Query Pattern (concept relationships) +`+"```"+` +User question + ↓ +think (analyze exploration needs) + ↓ +todo_write (if multi-step: initial search, graph query, relationship expansion) + ↓ +knowledge_search (initial retrieval) + ↓ +query_knowledge_graph (explore relationships) + ↓ +get_related_chunks (expand understanding) + ↓ +comprehensive relationship network answer +`+"```"+` + +Example: "Relationship between Docker and Kubernetes" + +# Parallelization Guidance + +## Core Principle +When multiple tool calls have no dependencies, execute them in parallel for efficiency. + +## Parallelizable Scenarios + +1. Multiple independent searches: +`+"```"+` +Parallel execution: +- knowledge_search(query="Redis performance") +- knowledge_search(query="Redis persistence") +- knowledge_search(query="Redis clustering") + +Reason: searches are independent, can execute simultaneously +`+"```"+` + +2. Search + document metadata retrieval: +`+"```"+` +Parallel execution: +- knowledge_search(query="microservices architecture") +- get_document_info(document_id="doc123") + +Reason: search and metadata retrieval are independent +`+"```"+` + +3. Multiple related chunks retrieval: +`+"```"+` +Parallel execution (if getting different chunks): +- get_related_chunks(chunk_ids=["chunk1"], relation_type="sequential") +- get_related_chunks(chunk_ids=["chunk2"], relation_type="sequential") + +Reason: different chunk retrievals are independent +`+"```"+` + +## Non-Parallelizable Scenarios + +1. Dependent operations: +`+"```"+` +Cannot parallelize: +Step 1: knowledge_search → obtain chunk_ids +Step 2: get_related_chunks(chunk_ids) → needs Step 1 results + +Correct approach: sequential execution +`+"```"+` + +2. Operations requiring evaluation: +`+"```"+` +Cannot parallelize: +Step 1: knowledge_search → evaluate result quality +Step 2: decide whether to call get_related_chunks based on quality + +Correct approach: search, think for evaluation, then decide next step +`+"```"+` + +## Best Practices +- Comparison queries: parallel search for multiple targets +- Multi-dimensional research: parallel search for each dimension +- Batch data retrieval: prefer batch interfaces when available +- Do not sacrifice logical clarity for parallelization +- Do not parallelize operations with dependencies + +# Tool Selection Framework + +## Initial Search Phase +1. Uncertain which knowledge base? -> knowledge_search (omit knowledge_base_ids to search all available KBs) +2. Know specific knowledge base? -> knowledge_search (specify knowledge_base_ids) +3. Need document metadata? -> get_document_info +4. Need statistical data or system status? -> database_query + +Note: Available knowledge base information is provided in the system prompt, no query needed + +## Deep Dive Phase +1. Need context around results? -> get_related_chunks (sequential) +2. Looking for similar content? -> get_related_chunks (semantic) +3. Entity relationship questions? -> query_knowledge_graph +4. Need data analysis or system metrics? -> database_query + +## Planning and Thinking Phase +1. Before any important decision -> think (frequent use recommended, zero cost, always beneficial) +2. Any multi-step task -> think -> todo_write (strongly recommended) +3. Evaluate result quality -> think (after each search) +4. Update task progress -> todo_write (update status to completed/skipped) + +## Data & System Query Phase +1. Statistical questions (counts, sums, averages) -> database_query +2. System status queries (storage usage, processing status) -> database_query +3. Data analysis (grouping, filtering, aggregation) -> database_query +4. Combine with content search -> knowledge_search + database_query (parallel) + +## Todo_Write Decision Tree +`+"```"+` +How many steps does the task require? + ↓ +1 step → no todo_write needed, execute directly + ↓ +2-3 steps → strongly recommend todo_write (maintain organization) + ↓ +4+ steps → must use todo_write (otherwise easily becomes chaotic) +`+"```"+` + +# Failure Recovery Modes + +## Mode 1: Low Quality Search Results (all scores < 0.6) + +Steps: +1. Use think tool to analyze why results are poor +2. If multi-step task, update todo_write to mark current step as problematic, plan alternative strategy +3. Try alternative query strategies: + - More specific terms ("Redis config" -> "Redis persistence RDB AOF configuration") + - Synonyms or related concepts ("deploy" -> "install" / "start" / "configure") + - Broader context ("high availability" -> "high availability architecture fault tolerance failover") + - Check available knowledge base scope (information provided in system prompt) +5. Honestly inform user of information gaps, suggest supplementing knowledge base + +Prohibited: +- Do not give up after one failed search +- Do not fabricate answers based on low-quality results +- Do not skip trying other query strategies + +Example (using todo_write): +`+"```"+` +todo_write: step1=search Redis config(in_progress), step2=organize answer(pending) +-> knowledge_search("Redis config") -> all results < 0.5 +-> think: too broad, try specific config items +-> knowledge_search(vector_queries=["Redis persistence config"], keyword_queries=["RDB", "AOF"]) +-> if still poor, update todo: step1=completed (result: insufficient info) +-> inform user: "Knowledge base has limited Redis configuration details, suggest uploading Redis official documentation" +`+"```"+` + +## Mode 2: Incomplete Information + +Steps: +1. Use think to evaluate information gaps (what dimensions are missing?) +2. Determine missing dimensions (what, why, how, when, where) +3. If multi-step research, use todo_write to add new search steps +4. Targeted search for missing parts (can parallelize searches for multiple dimensions) +5. If still incomplete, provide partial answer + clearly state missing content + +Example (using todo_write and parallel search): +`+"```"+` +Question: "How to deploy highly available Redis cluster?" +-> think: multi-dimensional problem, needs structured research +-> todo_write: step1=standalone deployment, step2=cluster config, step3=HA solution +-> Execute step1: knowledge_search -> found standalone deployment (score: 0.82) -> completed +-> think: missing cluster and HA configuration, step2 and step3 need supplemental search +-> Parallel execute step2+step3: + - knowledge_search(vector_queries=["Redis cluster configuration"]) + - knowledge_search(vector_queries=["Redis Sentinel high availability"]) +-> Comprehensive answer, mark sources and information completeness +`+"```"+` + +## Mode 3: Tool Call Failure + +Steps: +1. Check error message +2. Use think to analyze failure reason and alternative approaches +3. Adjust parameters (reduce top_k, switch knowledge base, correct parameter format) +4. Try alternative tools +5. Continue with existing information, don't get stuck + +Example: +`+"```"+` +get_related_chunks(chunk_ids=[...10 IDs]) -> failed (possible timeout) +-> think: too many IDs at once, batch process +-> Parallel execute: + - get_related_chunks(chunk_ids=[first 5]) + - get_related_chunks(chunk_ids=[last 5]) +Or: use knowledge_search as alternative to get context +`+"```"+` + +## Mode 4: Never Give Up Principle (CRITICAL) + +Key Rules: +- Never acceptable: give up after one failed search +- Must do: try at least 2-3 different query approaches +- Must do: combine use of different tools +- Must do: search from different angles (what, how, why, when) +- Must do: use todo_write to track attempted strategies + +Tool Combination Strategies: +- Search -> no results -> retry with different keywords -> still no results -> explain information gap +- Search -> low score results -> get_related_chunks to view complete content -> evaluate usability +- Search -> incomplete results -> get_related_chunks to expand context -> synthesize information + +# Answer Quality Standards + +## Pre-Answer Checklist +Before generating answer, confirm: +- All key assertions have chunk_id citations +- Source document names clearly marked +- Low relevance sources (<0.7) have score annotations +- Information gaps clearly stated +- Uses structured format (headings, lists, paragraphs) +- At least 2 search strategies attempted (if first attempt suboptimal) +- Multi-step task todos all marked as completed or skipped + +## Citation Format (STRICT) + +Inline citation (single source): +`+"```"+` +According to "Redis Manual" (chunk: abc123, relevance: 0.85), there are two persistence methods... +`+"```"+` + +Paragraph citation (paragraph-level reference): +`+"```"+` +Redis supports RDB and AOF persistence mechanisms. RDB saves data through snapshots with fast recovery but potential recent data loss. +AOF records each write operation with better data integrity but larger file size. + +[Source: "Redis Configuration Guide", chunk: xyz789, relevance: 0.92] +`+"```"+` + +End summary (required when using 3+ sources): +## References + +1. "Redis Manual" - chunk: abc123 (relevance: 0.85) - persistence mechanism explanation +2. "Redis Configuration Guide" - chunk: xyz789 (relevance: 0.92) - RDB configuration details +3. "High Availability Architecture" - chunk: def456 (relevance: 0.78) - master-slave replication approach + +Low relevance annotation (<0.7 must annotate): + +According to retrieval results (WARNING: relevance: 0.65, may not be precise enough), the default value for this configuration is... +Suggestion: This information has low relevance, recommend consulting official documentation + +# Tool Combination Patterns + +1. Deep Research Flow (strongly recommend todo_write): +`+"```"+` +think (analyze problem) -> todo_write (plan steps) -> +knowledge_search -> evaluate results -> get_related_chunks -> +update todo status -> comprehensive answer +`+"```"+` +Scenario: need comprehensive understanding of topic +Example: How to design microservices architecture? +Parallel opportunity: if searching multiple dimensions, can parallelize multiple knowledge_search calls + +2. Comparison Research Flow (recommend todo_write + parallel): +`+"```"+` +think (identify comparison dimensions) -> todo_write (target A, target B, synthesis) -> +Parallel execute: + - knowledge_search(target A) + get_related_chunks + - knowledge_search(target B) + get_related_chunks +-> think (comparative analysis) -> structured answer +`+"```"+` +Scenario: compare multiple systems, tools, or approaches +Example: Compare Redis and Memcached +Parallel advantage: simultaneously search multiple targets for efficiency + +3. Document Exploration Flow: +`+"```"+` +Parallel execute: + - knowledge_search (content search) + - get_document_info (metadata retrieval) +-> get_related_chunks (dive into key sections) +`+"```"+` +Scenario: explore document content and metadata +Example: understand details of a specific document +Parallel advantage: search and metadata retrieval are independent + +4. Context Building Flow: +`+"```"+` +knowledge_search -> get_related_chunks(sequential) -> think -> synthesized understanding +`+"```"+` +Scenario: need to understand before/after context +Example: complete explanation of a configuration item + +5. Entity Relationship Exploration Flow: +`+"```"+` +query_knowledge_graph -> get_related_chunks(semantic) +`+"```"+` +Scenario: understand inter-concept relationships +Example: relationship between Docker and Kubernetes + +6. Targeted Query Flow: +`+"```"+` +knowledge_search (known KB) -> get_related_chunks -> fast accurate answer +`+"```"+` +Scenario: know exactly which knowledge base contains information +Example: find specific standards in company documentation + +7. Multi-dimensional Parallel Research Flow (todo_write most valuable scenario): +`+"```"+` +think (identify multiple research dimensions) -> todo_write (dim1, dim2, dim3, synthesis) -> +Parallel execute multiple dimensions: + - knowledge_search(dimension 1) + - knowledge_search(dimension 2) + - knowledge_search(dimension 3) +-> evaluate each, use get_related_chunks if needed -> +update each todo to completed -> +think (synthesize all dimensions) -> comprehensive answer +`+"```"+` +Scenario: complex multi-dimensional problems +Example: "Comprehensively analyze microservices architecture design, deployment, monitoring, and security" +Key value: todo_write helps track completion status of each dimension + +8. Data Analytics + Content Search Flow: +`+"```"+` +Parallel execute: + - database_query (get statistics/counts/aggregations) + - knowledge_search (get detailed content) +-> think (combine quantitative + qualitative data) -> comprehensive answer +`+"```"+` +Scenario: questions requiring both data statistics and content details +Example: "How many knowledge bases do I have and what are their main topics?" +Parallel advantage: statistics and content search are independent + +9. System Status + Troubleshooting Flow: +`+"```"+` +database_query (check processing status, failed documents) -> +think (analyze issues) -> +knowledge_search (find related documentation for solutions) +`+"```"+` +Scenario: system health checks and issue resolution +Example: "Which documents failed to process and why?" + +# Important Reminders + +## Core Value of todo_write +- Organization: decompose complex tasks into manageable steps +- Traceability: clearly know what's completed and what remains +- Flexibility: dynamically adjust based on findings, skip unnecessary steps +- Focus: concentrate on one step at a time, avoid confusion +- Completeness: ensure no important dimensions are missed + +## Golden Rules for Using todo_write +1. Use for 2+ steps: any task requiring 2+ steps should use todo_write +2. Real-time updates: immediately update status after completing each step +3. Clear status: pending -> in_progress -> completed/skipped +4. Dynamic adjustment: promptly mark unnecessary steps as skipped +5. Parallel mindset: consider which steps can be parallelized when creating todos + +## Quality and Efficiency Balance +- think tool: zero cost, frequent use always beneficial +- todo_write tool: strongly recommended for multi-step tasks, maintains organization +- Parallel execution: parallelize tool calls without dependencies for efficiency +- Multiple searches: better than single inaccurate search +- Accurate citations: all answers must include chunk_id for traceability +- Honesty: clearly state insufficient information > fabricate low-quality answers +- Relevance annotation: must be cautious and annotate when < 0.7 + +## Strictly Prohibited Behaviors +- Give up after one failed search +- Answers without source citations +- Assertions based on low-quality results (<0.5) +- Fabricate or guess information outside knowledge base +- Use 3+ sources without end summary +- Multi-step tasks without todo_write leading to chaos +- Sequential execution when parallelization opportunities exist, wasting time +- Use database_query for content search (use knowledge_search instead) +- Manually add tenant_id conditions in SQL (automatically injected for security) + +## Core Identity +Remember: you are a knowledge base assistant, not a general AI. Your value lies in: +- Accuracy: reliable answers based on knowledge base +- Traceability: all assertions have clear sources +- Systematic: use think and todo_write for structured thinking +- Efficiency: leverage parallel execution for faster response +- Professional: evidence-based professional answers`, kbList) + + return prompt +} diff --git a/internal/agent/tools/database_query.go b/internal/agent/tools/database_query.go new file mode 100644 index 00000000..36c9e975 --- /dev/null +++ b/internal/agent/tools/database_query.go @@ -0,0 +1,456 @@ +package tools + +import ( + "context" + "database/sql" + "encoding/json" + "fmt" + "regexp" + "strings" + + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" + "gorm.io/gorm" +) + +// DatabaseQueryTool allows AI to query the database with auto-injected tenant_id for security +type DatabaseQueryTool struct { + BaseTool + db *gorm.DB + tenantID uint +} + +// NewDatabaseQueryTool creates a new database query tool +func NewDatabaseQueryTool(db *gorm.DB, tenantID uint) *DatabaseQueryTool { + description := `Execute SQL queries to retrieve information from the database. + +## Security Features +- Automatic tenant_id injection: All queries are automatically filtered by the logged-in user's tenant_id +- Read-only queries: Only SELECT statements are allowed +- Safe tables: Only allow queries on authorized tables + +## Available Tables and Columns + +### knowledge_bases +- id (VARCHAR): Knowledge base ID +- name (VARCHAR): Knowledge base name +- description (TEXT): Description +- tenant_id (INTEGER): Owner tenant ID +- embedding_model_id, summary_model_id, rerank_model_id, vlm_model_id (VARCHAR): Model IDs +- created_at, updated_at (TIMESTAMP) + +### knowledges (documents) +- id (VARCHAR): Document ID +- tenant_id (INTEGER): Owner tenant ID +- knowledge_base_id (VARCHAR): Parent knowledge base ID +- type (VARCHAR): Document type +- title (VARCHAR): Document title +- description (TEXT): Description +- source (VARCHAR): Source location +- parse_status (VARCHAR): Processing status (unprocessed/processing/completed/failed) +- enable_status (VARCHAR): Enable status (enabled/disabled) +- file_name, file_type (VARCHAR): File information +- file_size, storage_size (BIGINT): Size in bytes +- created_at, updated_at, processed_at (TIMESTAMP) + + + +### chunks +- id (VARCHAR): Chunk ID +- tenant_id (INTEGER): Owner tenant ID +- knowledge_base_id (VARCHAR): Parent knowledge base ID +- knowledge_id (VARCHAR): Parent document ID +- content (TEXT): Chunk content +- chunk_index (INTEGER): Index in document +- is_enabled (BOOLEAN): Enable status +- chunk_type (VARCHAR): Type (text/image/table) +- created_at, updated_at (TIMESTAMP) + +## Usage Examples + +Query knowledge base information: +{ + "sql": "SELECT id, name, description FROM knowledge_bases ORDER BY created_at DESC LIMIT 10" +} + +Count documents by status: +{ + "sql": "SELECT parse_status, COUNT(*) as count FROM knowledges GROUP BY parse_status" +} + +Find recent sessions: +{ + "sql": "SELECT id, title, created_at FROM sessions ORDER BY created_at DESC LIMIT 5" +} + +Get storage usage: +{ + "sql": "SELECT SUM(storage_size) as total_storage FROM knowledges" +} + +Join knowledge bases and documents: +{ + "sql": "SELECT kb.name as kb_name, COUNT(k.id) as doc_count FROM knowledge_bases kb LEFT JOIN knowledges k ON kb.id = k.knowledge_base_id GROUP BY kb.id, kb.name" +} + +## Important Notes +- DO NOT include tenant_id in WHERE clause - it's automatically added +- Only SELECT queries are allowed +- Limit results with LIMIT clause for better performance +- Use appropriate JOINs when querying across tables +- All timestamps are in UTC with time zone` + + return &DatabaseQueryTool{ + BaseTool: NewBaseTool("database_query", description), + db: db, + tenantID: tenantID, + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *DatabaseQueryTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "sql": map[string]interface{}{ + "type": "string", + "description": "The SELECT SQL query to execute. DO NOT include tenant_id condition - it will be automatically added for security.", + }, + }, + "required": []string{"sql"}, + } +} + +// Execute executes the database query tool +func (t *DatabaseQueryTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + logger.Infof(ctx, "[Tool][DatabaseQuery] Execute started") + + // Extract SQL from args + sqlQuery, ok := args["sql"].(string) + if !ok || sqlQuery == "" { + logger.Errorf(ctx, "[Tool][DatabaseQuery] Missing or invalid SQL parameter") + return &types.ToolResult{ + Success: false, + Error: "Missing or invalid 'sql' parameter", + }, fmt.Errorf("missing sql parameter") + } + + logger.Infof(ctx, "[Tool][DatabaseQuery] Original SQL query:\n%s", sqlQuery) + logger.Infof(ctx, "[Tool][DatabaseQuery] Tenant ID: %d", t.tenantID) + + // Validate and secure the SQL query + logger.Debugf(ctx, "[Tool][DatabaseQuery] Validating and securing SQL...") + securedSQL, err := t.validateAndSecureSQL(sqlQuery) + if err != nil { + logger.Errorf(ctx, "[Tool][DatabaseQuery] SQL validation failed: %v", err) + return &types.ToolResult{ + Success: false, + Error: fmt.Sprintf("SQL validation failed: %v", err), + }, err + } + + logger.Infof(ctx, "[Tool][DatabaseQuery] Secured SQL query:\n%s", securedSQL) + logger.Infof(ctx, "Executing secured SQL query - original: %s, secured: %s, tenant_id: %d", + sqlQuery, securedSQL, t.tenantID) + + // Execute the query + logger.Infof(ctx, "[Tool][DatabaseQuery] Executing query against database...") + rows, err := t.db.WithContext(ctx).Raw(securedSQL).Rows() + if err != nil { + logger.Errorf(ctx, "[Tool][DatabaseQuery] Query execution failed: %v", err) + return &types.ToolResult{ + Success: false, + Error: fmt.Sprintf("Query execution failed: %v", err), + }, err + } + defer rows.Close() + + logger.Debugf(ctx, "[Tool][DatabaseQuery] Query executed successfully, processing rows...") + + // Get column names + columns, err := rows.Columns() + if err != nil { + return &types.ToolResult{ + Success: false, + Error: fmt.Sprintf("Failed to get columns: %v", err), + }, err + } + + // Process results + results := make([]map[string]interface{}, 0) + for rows.Next() { + // Create a slice of interface{} to hold each column value + columnValues := make([]interface{}, len(columns)) + columnPointers := make([]interface{}, len(columns)) + for i := range columnValues { + columnPointers[i] = &columnValues[i] + } + + // Scan the row + if err := rows.Scan(columnPointers...); err != nil { + return &types.ToolResult{ + Success: false, + Error: fmt.Sprintf("Failed to scan row: %v", err), + }, err + } + + // Create a map for this row + rowMap := make(map[string]interface{}) + for i, colName := range columns { + val := columnValues[i] + // Convert []byte to string for better readability + if b, ok := val.([]byte); ok { + rowMap[colName] = string(b) + } else { + rowMap[colName] = val + } + } + results = append(results, rowMap) + } + + if err := rows.Err(); err != nil { + return &types.ToolResult{ + Success: false, + Error: fmt.Sprintf("Error iterating rows: %v", err), + }, err + } + + logger.Infof(ctx, "[Tool][DatabaseQuery] Retrieved %d rows with %d columns", len(results), len(columns)) + logger.Debugf(ctx, "[Tool][DatabaseQuery] Columns: %v", columns) + + // Log first few rows for debugging + if len(results) > 0 { + logger.Debugf(ctx, "[Tool][DatabaseQuery] First row sample:") + for key, value := range results[0] { + logger.Debugf(ctx, "[Tool][DatabaseQuery] %s: %v", key, value) + } + } + + // Format output + logger.Debugf(ctx, "[Tool][DatabaseQuery] Formatting query results...") + output := t.formatQueryResults(columns, results, securedSQL) + + logger.Infof(ctx, "[Tool][DatabaseQuery] Execute completed successfully: %d rows returned", len(results)) + return &types.ToolResult{ + Success: true, + Output: output, + Data: map[string]interface{}{ + "columns": columns, + "rows": results, + "row_count": len(results), + "query": securedSQL, + "tenant_id": t.tenantID, + "display_type": "database_query", + }, + }, nil +} + +// validateAndSecureSQL validates the SQL query and injects tenant_id conditions +func (t *DatabaseQueryTool) validateAndSecureSQL(sqlQuery string) (string, error) { + // Normalize SQL: trim and convert to lowercase for analysis + normalizedSQL := strings.TrimSpace(sqlQuery) + lowerSQL := strings.ToLower(normalizedSQL) + + // 1. Check if it's a SELECT statement + if !strings.HasPrefix(lowerSQL, "select") { + return "", fmt.Errorf("only SELECT queries are allowed") + } + + // 2. Check for dangerous keywords + dangerousKeywords := []string{ + "drop", "delete", "insert", "update", "alter", "create", + "truncate", "replace", "execute", "exec", "grant", "revoke", + } + for _, keyword := range dangerousKeywords { + // Use word boundary to avoid false positives (e.g., "description" contains "script") + pattern := fmt.Sprintf(`\b%s\b`, keyword) + matched, _ := regexp.MatchString(pattern, lowerSQL) + if matched { + return "", fmt.Errorf("dangerous keyword detected: %s", keyword) + } + } + + // 3. Check for allowed tables + allowedTables := []string{ + "tenants", "knowledge_bases", "knowledges", "sessions", + "messages", "chunks", "embeddings", "models", + } + + // Extract table names from FROM and JOIN clauses + tablePattern := regexp.MustCompile(`(?i)\b(?:from|join)\s+([a-z_]+)(?:\s+as\s+[a-z_]+|\s+[a-z_]+)?`) + matches := tablePattern.FindAllStringSubmatch(lowerSQL, -1) + + tablesInQuery := make(map[string]bool) + for _, match := range matches { + if len(match) > 1 { + tableName := strings.ToLower(match[1]) + tablesInQuery[tableName] = true + } + } + + // Verify all tables are allowed + for tableName := range tablesInQuery { + allowed := false + for _, allowedTable := range allowedTables { + if tableName == allowedTable { + allowed = true + break + } + } + if !allowed { + return "", fmt.Errorf("table not allowed: %s", tableName) + } + } + + // 4. Inject tenant_id conditions for tables that have tenant_id + tablesWithTenantID := map[string]bool{ + "tenants": true, + "knowledge_bases": true, + "knowledges": true, + "sessions": true, + "chunks": true, + } + + // Build tenant_id injection + securedSQL := normalizedSQL + + // Check if WHERE clause exists + wherePattern := regexp.MustCompile(`(?i)\bwhere\b`) + hasWhere := wherePattern.MatchString(securedSQL) + + // Find table aliases + aliasPattern := regexp.MustCompile(`(?i)(?:from|join)\s+([a-z_]+)(?:\s+(?:as\s+)?([a-z_]+))?`) + aliasMatches := aliasPattern.FindAllStringSubmatch(lowerSQL, -1) + + tableAliases := make(map[string]string) // table -> alias + for _, match := range aliasMatches { + if len(match) >= 3 && match[2] != "" { + // Has explicit alias + tableAliases[match[1]] = match[2] + } else if len(match) >= 2 { + // No alias, use table name itself + tableAliases[match[1]] = match[1] + } + } + + // Build tenant_id conditions + var tenantConditions []string + for tableName := range tablesInQuery { + if tablesWithTenantID[tableName] { + alias := tableAliases[tableName] + if alias == "" { + alias = tableName + } + // Special handling for tenants table - use id instead of tenant_id + if tableName == "tenants" { + tenantConditions = append(tenantConditions, fmt.Sprintf("%s.id = %d", alias, t.tenantID)) + } else { + tenantConditions = append(tenantConditions, fmt.Sprintf("%s.tenant_id = %d", alias, t.tenantID)) + } + } + } + + if len(tenantConditions) > 0 { + tenantFilter := strings.Join(tenantConditions, " AND ") + if hasWhere { + // Add to existing WHERE clause + securedSQL = wherePattern.ReplaceAllString(securedSQL, fmt.Sprintf("WHERE %s AND ", tenantFilter)) + } else { + // Add new WHERE clause before ORDER BY, GROUP BY, LIMIT, etc. + orderByPattern := regexp.MustCompile(`(?i)\b(group\s+by|order\s+by|limit|offset|having)\b`) + if orderByPattern.MatchString(securedSQL) { + securedSQL = orderByPattern.ReplaceAllStringFunc(securedSQL, func(match string) string { + return fmt.Sprintf(" WHERE %s %s", tenantFilter, match) + }) + } else { + // Add WHERE clause at the end + securedSQL = fmt.Sprintf("%s WHERE %s", securedSQL, tenantFilter) + } + } + } + + return securedSQL, nil +} + +// formatQueryResults formats query results into readable text +func (t *DatabaseQueryTool) formatQueryResults(columns []string, results []map[string]interface{}, query string) string { + output := "=== 查询结果 ===\n\n" + output += fmt.Sprintf("执行的SQL: %s\n\n", query) + output += fmt.Sprintf("返回 %d 行数据\n\n", len(results)) + + if len(results) == 0 { + output += "未找到匹配的记录。\n" + return output + } + + output += "=== 数据详情 ===\n\n" + + // Format each row + for i, row := range results { + output += fmt.Sprintf("--- 记录 #%d ---\n", i+1) + for _, col := range columns { + value := row[col] + // Format the value + var formattedValue string + if value == nil { + formattedValue = "" + } else if jsonData, err := json.Marshal(value); err == nil { + // Check if it's a complex type + switch v := value.(type) { + case string: + formattedValue = v + case []byte: + formattedValue = string(v) + default: + formattedValue = string(jsonData) + } + } else { + formattedValue = fmt.Sprintf("%v", value) + } + + output += fmt.Sprintf(" %s: %s\n", col, formattedValue) + } + output += "\n" + } + + // Add summary statistics if applicable + if len(results) > 10 { + output += fmt.Sprintf("注意: 显示了前 %d 条记录,共 %d 条。建议使用 LIMIT 子句限制结果数量。\n", len(results), len(results)) + } + + return output +} + +// Helper function to convert database value to proper type +func convertDatabaseValue(val interface{}) interface{} { + if val == nil { + return nil + } + + switch v := val.(type) { + case []byte: + return string(v) + case sql.NullString: + if v.Valid { + return v.String + } + return nil + case sql.NullInt64: + if v.Valid { + return v.Int64 + } + return nil + case sql.NullFloat64: + if v.Valid { + return v.Float64 + } + return nil + case sql.NullBool: + if v.Valid { + return v.Bool + } + return nil + default: + return v + } +} diff --git a/internal/agent/tools/get_document_info.go b/internal/agent/tools/get_document_info.go new file mode 100644 index 00000000..49e26f00 --- /dev/null +++ b/internal/agent/tools/get_document_info.go @@ -0,0 +1,332 @@ +package tools + +import ( + "context" + "fmt" + "sync" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +// GetDocumentInfoTool retrieves detailed information about a document/knowledge +type GetDocumentInfoTool struct { + BaseTool + knowledgeService interfaces.KnowledgeService + chunkService interfaces.ChunkService +} + +// NewGetDocumentInfoTool creates a new get document info tool +func NewGetDocumentInfoTool( + knowledgeService interfaces.KnowledgeService, + chunkService interfaces.ChunkService, +) *GetDocumentInfoTool { + description := `Retrieve detailed metadata information about documents. + +## When to Use + +Use this tool when: +- Need to understand document basic information (title, type, size, etc.) +- Check if document exists and is available +- Batch query metadata for multiple documents +- Understand document processing status + +Do not use when: +- Need document content (use knowledge_search) +- Need specific text chunks (search results already contain full content) + + +## Returned Information + +- Basic info: title, description, source type +- File info: filename, type, size +- Processing status: whether processed, chunk count +- Metadata: custom tags and properties + + +## Notes + +- Concurrent query for multiple documents provides better performance +- Returns complete document metadata, not just title +- Can check document processing status (parse_status)` + + return &GetDocumentInfoTool{ + BaseTool: NewBaseTool("get_document_info", description), + knowledgeService: knowledgeService, + chunkService: chunkService, + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *GetDocumentInfoTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "knowledge_ids": map[string]interface{}{ + "type": "array", + "description": "Array of document/knowledge IDs, obtained from knowledge_id field in search results, supports concurrent batch queries", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 10, + }, + }, + "required": []string{"knowledge_ids"}, + } +} + +// Execute retrieves document information with concurrent processing +func (t *GetDocumentInfoTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + // Extract knowledge_ids array + knowledgeIDsRaw, ok := args["knowledge_ids"].([]interface{}) + if !ok || len(knowledgeIDsRaw) == 0 { + return &types.ToolResult{ + Success: false, + Error: "knowledge_ids is required and must be a non-empty array", + }, fmt.Errorf("knowledge_ids is required") + } + + // Convert to string slice + var knowledgeIDs []string + for _, id := range knowledgeIDsRaw { + if idStr, ok := id.(string); ok && idStr != "" { + knowledgeIDs = append(knowledgeIDs, idStr) + } + } + + if len(knowledgeIDs) == 0 { + return &types.ToolResult{ + Success: false, + Error: "knowledge_ids must contain at least one valid knowledge ID", + }, fmt.Errorf("no valid knowledge IDs provided") + } + + // Concurrently get info for each knowledge ID + type docInfo struct { + knowledge *types.Knowledge + chunkCount int + err error + } + + var wg sync.WaitGroup + var mu sync.Mutex + results := make(map[string]*docInfo) + + for _, knowledgeID := range knowledgeIDs { + wg.Add(1) + go func(id string) { + defer wg.Done() + + // Get knowledge metadata + knowledge, err := t.knowledgeService.GetKnowledgeByID(ctx, id) + if err != nil { + mu.Lock() + results[id] = &docInfo{ + err: fmt.Errorf("无法获取文档信息: %v", err), + } + mu.Unlock() + return + } + + // Get chunk count + chunks, err := t.chunkService.ListChunksByKnowledgeID(ctx, id) + chunkCount := 0 + if err == nil { + chunkCount = len(chunks) + } + + mu.Lock() + results[id] = &docInfo{ + knowledge: knowledge, + chunkCount: chunkCount, + } + mu.Unlock() + }(knowledgeID) + } + + wg.Wait() + + // Collect successful results and errors + successDocs := make([]*docInfo, 0) + var errors []string + + for _, knowledgeID := range knowledgeIDs { + result := results[knowledgeID] + if result.err != nil { + errors = append(errors, fmt.Sprintf("%s: %v", knowledgeID, result.err)) + } else if result.knowledge != nil { + successDocs = append(successDocs, result) + } + } + + if len(successDocs) == 0 { + return &types.ToolResult{ + Success: false, + Error: fmt.Sprintf("无法获取任何文档信息。错误: %v", errors), + }, fmt.Errorf("all document retrievals failed") + } + + // Format output + output := "=== 文档信息 ===\n\n" + output += fmt.Sprintf("成功获取 %d / %d 个文档信息\n\n", len(successDocs), len(knowledgeIDs)) + + if len(errors) > 0 { + output += "=== 部分失败 ===\n" + for _, errMsg := range errors { + output += fmt.Sprintf(" - %s\n", errMsg) + } + output += "\n" + } + + formattedDocs := make([]map[string]interface{}, 0, len(successDocs)) + for i, doc := range successDocs { + k := doc.knowledge + + // Get file type icon + typeIcon := getTypeIcon(k.Type, k.FileType) + + output += fmt.Sprintf("【文档 #%d】 %s\n", i+1, typeIcon) + output += fmt.Sprintf(" ID: %s\n", k.ID) + output += fmt.Sprintf(" 标题: %s\n", k.Title) + + if k.Description != "" { + output += fmt.Sprintf(" 描述: %s\n", k.Description) + } + + output += fmt.Sprintf(" 来源: %s\n", formatSource(k.Type, k.Source)) + + if k.FileName != "" { + output += fmt.Sprintf(" 文件名: %s\n", k.FileName) + output += fmt.Sprintf(" 文件类型: %s\n", k.FileType) + output += fmt.Sprintf(" 文件大小: %s\n", formatFileSize(k.FileSize)) + } + + output += fmt.Sprintf(" 处理状态: %s\n", formatParseStatus(k.ParseStatus)) + output += fmt.Sprintf(" 分块数量: %d 个\n", doc.chunkCount) + + if k.Metadata != nil { + if metadata, err := k.Metadata.Map(); err == nil && len(metadata) > 0 { + output += " 元数据:\n" + for key, value := range metadata { + output += fmt.Sprintf(" - %s: %v\n", key, value) + } + } + } + + output += "\n" + + formattedDocs = append(formattedDocs, map[string]interface{}{ + "knowledge_id": k.ID, + "title": k.Title, + "description": k.Description, + "type": k.Type, + "source": k.Source, + "file_name": k.FileName, + "file_type": k.FileType, + "file_size": k.FileSize, + "parse_status": k.ParseStatus, + "chunk_count": doc.chunkCount, + "metadata": k.GetMetadata(), + "type_icon": typeIcon, + }) + } + + output += "=== Usage Tips ===\n" + output += "- Use knowledge_search to search document content\n" + output += "- Use get_related_chunks to view context and related chunks\n" + output += "- Search results already contain full chunk content\n" + + // Extract first document title for summary + var firstTitle string + if len(successDocs) > 0 && successDocs[0].knowledge != nil { + firstTitle = successDocs[0].knowledge.Title + } + + return &types.ToolResult{ + Success: true, + Output: output, + Data: map[string]interface{}{ + "documents": formattedDocs, + "total_docs": len(successDocs), + "requested": len(knowledgeIDs), + "errors": errors, + "display_type": "document_info", + "title": firstTitle, // For frontend summary display + }, + }, nil +} + +// Helper functions + +func getTypeIcon(knowledgeType, fileType string) string { + switch knowledgeType { + case "file": + switch fileType { + case "pdf", "PDF": + return "📄 PDF" + case "docx", "doc", "DOCX", "DOC": + return "📝 Word" + case "txt", "TXT": + return "📃 Text" + case "md", "MD", "markdown": + return "📋 Markdown" + case "xlsx", "xls", "XLSX", "XLS": + return "📊 Excel" + case "pptx", "ppt", "PPTX", "PPT": + return "📊 PowerPoint" + default: + return "📄 File" + } + case "url": + return "🌐 URL" + case "passage": + return "📝 Passage" + default: + return "📄 Document" + } +} + +func formatSource(knowledgeType, source string) string { + switch knowledgeType { + case "file": + return "文件上传" + case "url": + return fmt.Sprintf("URL: %s", source) + case "passage": + return "文本输入" + default: + return knowledgeType + } +} + +func formatFileSize(size int64) string { + if size == 0 { + return "未知" + } + const unit = 1024 + if size < unit { + return fmt.Sprintf("%d B", size) + } + div, exp := int64(unit), 0 + for n := size / unit; n >= unit; n /= unit { + div *= unit + exp++ + } + return fmt.Sprintf("%.1f %cB", float64(size)/float64(div), "KMGTPE"[exp]) +} + +func formatParseStatus(status string) string { + switch status { + case "pending": + return "⏳ 待处理" + case "processing": + return "🔄 处理中" + case "completed", "success": + return "✅ 已完成" + case "failed": + return "❌ 失败" + default: + return status + } +} diff --git a/internal/agent/tools/get_related_chunks.go b/internal/agent/tools/get_related_chunks.go new file mode 100644 index 00000000..efad17b2 --- /dev/null +++ b/internal/agent/tools/get_related_chunks.go @@ -0,0 +1,427 @@ +package tools + +import ( + "context" + "fmt" + "sync" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +// GetRelatedChunksTool retrieves chunks related to a given chunk +type GetRelatedChunksTool struct { + BaseTool + chunkService interfaces.ChunkService + knowledgeBaseService interfaces.KnowledgeBaseService +} + +// NewGetRelatedChunksTool creates a new get related chunks tool +func NewGetRelatedChunksTool(chunkService interfaces.ChunkService, knowledgeBaseService interfaces.KnowledgeBaseService) *GetRelatedChunksTool { + description := `Retrieve chunks related to specified reference chunks. Supports sequential (adjacent) and semantic (similar) relation types. + +## When to Use + +Use this tool when: +- Search results need additional context for full understanding +- You need to see content before/after a specific chunk +- Looking for semantically similar content across the document +- Understanding the complete narrative flow of a topic + +Do not use when: +- Search results already provide sufficient complete content +- Only need a single specific chunk without context + +## Parameters + +chunk_ids (required): Array of reference chunk IDs (1-10) +- Obtained from search results +- Supports concurrent batch processing +- Example: ["chunk_abc", "chunk_def"] + +relation_type (optional): Type of relation +- "sequential" (default): Get adjacent chunks before and after +- "semantic": Get semantically similar chunks regardless of position + +limit (optional): Number of related chunks to return per reference chunk +- Default: 5 +- Range: 1-10 +- Sequential: retrieves limit/2 chunks before and after +- Semantic: retrieves top limit most similar chunks + +## Relation Types + +Sequential: +- Retrieves adjacent chunks in document order +- Useful for understanding complete narrative flow +- Ideal for scenarios requiring continuous reading +- Example: viewing complete configuration steps + +Semantic: +- Finds content-similar chunks regardless of position +- Discovers related discussions throughout document +- Ideal for topic expansion and cross-referencing +- Example: finding all mentions of a specific concept + +## Usage Patterns + +1. Context expansion: knowledge_search -> get_related_chunks(sequential) +2. Topic exploration: knowledge_search -> get_related_chunks(semantic) +3. Deep research: knowledge_search -> get_related_chunks(both sequential and semantic) + +## Notes + +- Results are automatically deduplicated +- Source chunks are excluded from results +- Sequential results sorted by chunk_index +- Semantic results sorted by similarity score +- Limit value of 5 typically provides sufficient context without information overload` + + return &GetRelatedChunksTool{ + BaseTool: NewBaseTool("get_related_chunks", description), + chunkService: chunkService, + knowledgeBaseService: knowledgeBaseService, + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *GetRelatedChunksTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "chunk_ids": map[string]interface{}{ + "type": "array", + "description": "Array of reference chunk IDs", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 10, + }, + "relation_type": map[string]interface{}{ + "type": "string", + "description": "Type: sequential (default) or semantic", + "enum": []string{"sequential", "semantic"}, + "default": "sequential", + }, + "limit": map[string]interface{}{ + "type": "integer", + "description": "Number of related chunks per input chunk (default: 5)", + "default": 5, + "minimum": 1, + "maximum": 10, + }, + }, + "required": []string{"chunk_ids"}, + } +} + +// Execute executes the get related chunks tool with concurrent processing +func (t *GetRelatedChunksTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + // Extract chunk_ids array + chunkIDsRaw, ok := args["chunk_ids"].([]interface{}) + if !ok || len(chunkIDsRaw) == 0 { + return &types.ToolResult{ + Success: false, + Error: "chunk_ids is required and must be a non-empty array", + }, fmt.Errorf("chunk_ids is required") + } + + // Convert to string slice + var chunkIDs []string + for _, id := range chunkIDsRaw { + if idStr, ok := id.(string); ok && idStr != "" { + chunkIDs = append(chunkIDs, idStr) + } + } + + if len(chunkIDs) == 0 { + return &types.ToolResult{ + Success: false, + Error: "chunk_ids must contain at least one valid chunk ID", + }, fmt.Errorf("no valid chunk IDs provided") + } + + relationType := "sequential" + if rt, ok := args["relation_type"].(string); ok { + relationType = rt + } + + limit := 5 + if l, ok := args["limit"].(float64); ok { + limit = int(l) + } + if limit < 1 { + limit = 1 + } + if limit > 10 { + limit = 10 + } + + // Concurrently get related chunks for each chunk ID + type relatedResult struct { + sourceChunk *types.Chunk + relatedChunks []*types.Chunk + err error + } + + var wg sync.WaitGroup + var mu sync.Mutex + results := make(map[string]*relatedResult) + + for _, chunkID := range chunkIDs { + wg.Add(1) + go func(id string) { + defer wg.Done() + + // Get the original chunk first + chunk, err := t.chunkService.GetChunkByID(ctx, id) + if err != nil || chunk == nil { + mu.Lock() + results[id] = &relatedResult{err: fmt.Errorf("failed to retrieve chunk: %v", err)} + mu.Unlock() + return + } + + var relatedChunks []*types.Chunk + + if relationType == "sequential" { + relatedChunks, err = t.getSequentialRelatedChunks(ctx, chunk, limit) + } else if relationType == "semantic" { + relatedChunks, err = t.getSemanticRelatedChunks(ctx, chunk, limit) + } + + mu.Lock() + results[id] = &relatedResult{ + sourceChunk: chunk, + relatedChunks: relatedChunks, + err: err, + } + mu.Unlock() + }(chunkID) + } + + wg.Wait() + + // Collect and deduplicate all related chunks + seenChunks := make(map[string]*types.Chunk) + sourceChunkIDs := make(map[string]bool) + var errors []string + + // Mark source chunks to exclude them from results + for _, chunkID := range chunkIDs { + sourceChunkIDs[chunkID] = true + } + + for _, chunkID := range chunkIDs { + result := results[chunkID] + if result.err != nil { + errors = append(errors, fmt.Sprintf("chunk %s: %v", chunkID, result.err)) + continue + } + + for _, chunk := range result.relatedChunks { + // Exclude source chunks and avoid duplicates + if !sourceChunkIDs[chunk.ID] { + if _, seen := seenChunks[chunk.ID]; !seen { + seenChunks[chunk.ID] = chunk + } + } + } + } + + // Convert map to slice and sort + allRelatedChunks := make([]*types.Chunk, 0, len(seenChunks)) + for _, chunk := range seenChunks { + allRelatedChunks = append(allRelatedChunks, chunk) + } + + // Sort chunks + if relationType == "sequential" { + // Sort by knowledge_id and chunk_index for sequential + sortChunksByPosition(allRelatedChunks) + } + // For semantic, keep the order from search results (already sorted by relevance) + + if len(allRelatedChunks) == 0 { + return &types.ToolResult{ + Success: true, + Output: "No related chunks found. Possible reasons:\n- Chunk is the only chunk in document\n- Semantic similarity threshold not met\n- Invalid chunk_id provided", + Data: map[string]interface{}{ + "chunk_ids": chunkIDs, + "relation_type": relationType, + "count": 0, + "chunks": []interface{}{}, + "errors": errors, + }, + }, nil + } + + // Format output + return t.formatOutput(chunkIDs, relationType, allRelatedChunks, errors) +} + +// getSequentialRelatedChunks gets chunks before and after the reference chunk +func (t *GetRelatedChunksTool) getSequentialRelatedChunks(ctx context.Context, chunk *types.Chunk, limit int) ([]*types.Chunk, error) { + // Get all chunks from the same knowledge + allChunks, err := t.chunkService.ListChunksByKnowledgeID(ctx, chunk.KnowledgeID) + if err != nil { + return nil, fmt.Errorf("failed to retrieve document chunks: %v", err) + } + + relatedChunks := make([]*types.Chunk, 0) + + // Bidirectional window: get chunks before and after + halfLimit := limit / 2 + if halfLimit < 1 { + halfLimit = 1 + } + + minIndex := chunk.ChunkIndex - halfLimit + maxIndex := chunk.ChunkIndex + halfLimit + + for _, c := range allChunks { + // Within range and not the source chunk itself + if c.ChunkIndex >= minIndex && c.ChunkIndex <= maxIndex && c.ID != chunk.ID { + relatedChunks = append(relatedChunks, c) + } + } + + return relatedChunks, nil +} + +// getSemanticRelatedChunks gets semantically similar chunks using hybrid search +func (t *GetRelatedChunksTool) getSemanticRelatedChunks(ctx context.Context, chunk *types.Chunk, limit int) ([]*types.Chunk, error) { + // Use chunk content as query for semantic search + searchParams := types.SearchParams{ + QueryText: chunk.Content, + MatchCount: limit + 5, // Get extra results for filtering + } + + // Search in the knowledge base that contains this chunk + searchResults, err := t.knowledgeBaseService.HybridSearch(ctx, chunk.KnowledgeBaseID, searchParams) + if err != nil { + return nil, fmt.Errorf("semantic search failed: %v", err) + } + + // Convert search results to chunks, excluding the source chunk + relatedChunks := make([]*types.Chunk, 0, limit) + for _, result := range searchResults { + if result.ID == chunk.ID { + continue // Skip the source chunk itself + } + + // Convert SearchResult to Chunk + relatedChunk := &types.Chunk{ + ID: result.ID, + KnowledgeID: result.KnowledgeID, + KnowledgeBaseID: chunk.KnowledgeBaseID, + Content: result.Content, + ChunkIndex: result.ChunkIndex, + } + + relatedChunks = append(relatedChunks, relatedChunk) + + if len(relatedChunks) >= limit { + break + } + } + + return relatedChunks, nil +} + +// sortChunksByPosition sorts chunks by knowledge_id and chunk_index +func sortChunksByPosition(chunks []*types.Chunk) { + // Simple bubble sort for small arrays + n := len(chunks) + for i := 0; i < n-1; i++ { + for j := 0; j < n-i-1; j++ { + // First sort by knowledge_id, then by chunk_index + if chunks[j].KnowledgeID > chunks[j+1].KnowledgeID || + (chunks[j].KnowledgeID == chunks[j+1].KnowledgeID && + chunks[j].ChunkIndex > chunks[j+1].ChunkIndex) { + chunks[j], chunks[j+1] = chunks[j+1], chunks[j] + } + } + } +} + +// formatOutput formats the tool output +func (t *GetRelatedChunksTool) formatOutput( + chunkIDs []string, + relationType string, + chunks []*types.Chunk, + errors []string, +) (*types.ToolResult, error) { + relationTypeLabel := map[string]string{ + "sequential": "Sequential (Adjacent)", + "semantic": "Semantic (Similar Content)", + } + + output := "=== Related Chunks ===\n\n" + output += fmt.Sprintf("Reference chunks: %d\n", len(chunkIDs)) + output += fmt.Sprintf("Relation type: %s\n", relationTypeLabel[relationType]) + output += fmt.Sprintf("Found %d related chunks (deduplicated)\n\n", len(chunks)) + + if len(errors) > 0 { + output += "=== Partial Failures ===\n" + for _, errMsg := range errors { + output += fmt.Sprintf(" - %s\n", errMsg) + } + output += "\n" + } + + output += "=== Content ===\n\n" + + formattedChunks := make([]map[string]interface{}, 0, len(chunks)) + currentKnowledge := "" + + for i, c := range chunks { + // Group by knowledge document + if c.KnowledgeID != currentKnowledge { + currentKnowledge = c.KnowledgeID + if i > 0 { + output += "\n" + } + output += fmt.Sprintf("[Document: %s]\n\n", c.KnowledgeID) + } + + output += fmt.Sprintf("Chunk #%d (Position: %d):\n", i+1, c.ChunkIndex+1) + output += fmt.Sprintf(" chunk_id: %s\n", c.ID) + output += fmt.Sprintf(" content: %s\n\n", c.Content) + + formattedChunks = append(formattedChunks, map[string]interface{}{ + "index": i + 1, + "chunk_id": c.ID, + "chunk_index": c.ChunkIndex, + "content": c.Content, + "knowledge_id": c.KnowledgeID, + }) + } + + output += "=== Notes ===\n" + if relationType == "sequential" { + output += "- Adjacent chunks in document order\n" + output += "- Useful for understanding complete narrative flow\n" + output += "- Sorted by position\n" + } else { + output += "- Semantically similar chunks sorted by relevance\n" + output += "- Useful for discovering related discussions\n" + output += "- Ideal for topic expansion and cross-referencing\n" + } + output += "- Source chunks excluded\n" + output += "- Results deduplicated\n" + + return &types.ToolResult{ + Success: true, + Output: output, + Data: map[string]interface{}{ + "chunk_ids": chunkIDs, + "relation_type": relationType, + "count": len(chunks), + "chunks": formattedChunks, + "errors": errors, + "display_type": "related_chunks", + }, + }, nil +} diff --git a/internal/agent/tools/knowledge_search.go b/internal/agent/tools/knowledge_search.go new file mode 100644 index 00000000..1587a46a --- /dev/null +++ b/internal/agent/tools/knowledge_search.go @@ -0,0 +1,816 @@ +package tools + +import ( + "context" + "encoding/json" + "fmt" + "sort" + "sync" + + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/models/rerank" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +// searchResultWithMeta wraps search result with metadata about which query matched it +type searchResultWithMeta struct { + *types.SearchResult + SourceQuery string + QueryType string // "vector" or "keyword" +} + +// KnowledgeSearchTool searches knowledge bases with flexible query modes +type KnowledgeSearchTool struct { + BaseTool + knowledgeService interfaces.KnowledgeBaseService + tenantID uint + allowedKBs []string + rerankModel rerank.Reranker +} + +// NewKnowledgeSearchTool creates a new knowledge search tool +func NewKnowledgeSearchTool( + knowledgeService interfaces.KnowledgeBaseService, + tenantID uint, + allowedKBs []string, + rerankModel rerank.Reranker, +) *KnowledgeSearchTool { + description := `Search within knowledge bases with flexible query modes. Unified tool that supports both targeted and broad searches. + +## Features +- Multi-KB search: Search across multiple knowledge bases concurrently +- Flexible queries: Support vector, keyword, or hybrid search modes +- Quality filtering: Automatically filters low-quality chunks + +## Usage + +**Use when**: +- You know which knowledge bases to target (specify knowledge_base_ids) +- You're unsure which KB contains the info (omit knowledge_base_ids to search all allowed KBs) +- Want to search specific KBs with same query +- Need semantic (vector) or exact keyword searches +- Want to search only specific documents within KBs + +**Parameters**: +- knowledge_base_ids (optional): Array of KB IDs to search (1-10). If omitted, searches all allowed KBs. +- query (optional): Single search query (for simple hybrid search) +- vector_queries (optional): Array of semantic queries for vector search (1-5 queries) +- keyword_queries (optional): Array of keyword queries for keyword search (1-5 queries) +- top_k (optional): Results per KB per query (default: 5, max: 20) +- vector_threshold (optional): Minimum score for vector results (default: 0.6, 0.0-1.0) +- keyword_threshold (optional): Minimum score for keyword results (default: 0.5, 0.0-1.0) +- knowledge_ids (optional): Array of document IDs to filter results (only return results from these documents) +- min_score (optional): Absolute minimum score to include results (default: 0.3, filters very low quality chunks) + +**Search Modes**: +- Simple: Provide single query parameter (hybrid search) +- Vector only: Provide vector_queries only +- Keyword only: Provide keyword_queries only +- Hybrid: Provide both vector_queries and keyword_queries +- At least one query parameter must be provided + +**Returns**: Merged and deduplicated search results from all KBs + +## Examples + +` + "`" + ` +# Simple search in specific KBs +{ + "knowledge_base_ids": ["kb1", "kb2"], + "query": "什么是向量数据库" +} + +# Search all allowed KBs with vector queries +{ + "vector_queries": ["什么是向量数据库", "向量数据库的定义"] +} + +# Multiple query types with thresholds +{ + "knowledge_base_ids": ["kb1"], + "vector_queries": ["向量数据库应用"], + "keyword_queries": ["Docker", "部署"], + "vector_threshold": 0.7, + "keyword_threshold": 0.6 +} + +# Search specific documents +{ + "knowledge_base_ids": ["kb1"], + "query": "彗星的起源", + "knowledge_ids": ["doc1", "doc2"] +} +` + "`" + ` + +## Tips + +- Concurrent search across multiple KBs and queries +- Results are automatically reranked to unify scores from different sources +- Reranked scores are in 0-1 range and directly comparable +- Results are merged, deduplicated and sorted by relevance +- Use vector_queries for semantic/conceptual searches +- Use keyword_queries for exact term matching +- Results below threshold are automatically filtered +- High relevance (>=0.8): directly usable +- Medium relevance (0.6-0.8): reference only +- Low relevance (<0.6): use with caution` + + return &KnowledgeSearchTool{ + BaseTool: NewBaseTool("knowledge_search", description), + knowledgeService: knowledgeService, + tenantID: tenantID, + allowedKBs: allowedKBs, + rerankModel: rerankModel, + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *KnowledgeSearchTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "knowledge_base_ids": map[string]interface{}{ + "type": "array", + "description": "Array of knowledge base IDs to search in (optional, if omitted searches all allowed KBs)", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 10, + }, + "query": map[string]interface{}{ + "type": "string", + "description": "Single search query for simple hybrid search", + }, + "vector_queries": map[string]interface{}{ + "type": "array", + "description": "Array of semantic queries for vector search (1-5 queries)", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 5, + }, + "keyword_queries": map[string]interface{}{ + "type": "array", + "description": "Array of keyword queries for keyword search (1-5 queries)", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 5, + }, + "top_k": map[string]interface{}{ + "type": "integer", + "description": "Number of results per knowledge base per query (default: 5)", + "default": 5, + "minimum": 1, + "maximum": 20, + }, + "vector_threshold": map[string]interface{}{ + "type": "number", + "description": "Minimum score for vector results (default: 0.6)", + "default": 0.6, + "minimum": 0.0, + "maximum": 1.0, + }, + "keyword_threshold": map[string]interface{}{ + "type": "number", + "description": "Minimum score for keyword results (default: 0.5)", + "default": 0.5, + "minimum": 0.0, + "maximum": 1.0, + }, + "knowledge_ids": map[string]interface{}{ + "type": "array", + "description": "Optional array of document IDs to filter results (only return results from these specific documents)", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 50, + }, + "min_score": map[string]interface{}{ + "type": "number", + "description": "Absolute minimum score threshold for filtering very low quality results (default: 0.3)", + "default": 0.3, + "minimum": 0.0, + "maximum": 1.0, + }, + }, + "required": []string{}, + } +} + +// Execute executes the knowledge search tool with flexible query modes +func (t *KnowledgeSearchTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + logger.Infof(ctx, "[Tool][KnowledgeSearch] Execute started") + + // Log input arguments + argsJSON, _ := json.MarshalIndent(args, "", " ") + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Input args:\n%s", string(argsJSON)) + + // Determine which KBs to search + var kbIDs []string + if kbIDsRaw, ok := args["knowledge_base_ids"].([]interface{}); ok && len(kbIDsRaw) > 0 { + for _, id := range kbIDsRaw { + if idStr, ok := id.(string); ok && idStr != "" { + kbIDs = append(kbIDs, idStr) + } + } + logger.Infof(ctx, "[Tool][KnowledgeSearch] User specified %d knowledge bases: %v", len(kbIDs), kbIDs) + } + + // If no KBs specified, use allowed KBs + if len(kbIDs) == 0 { + kbIDs = t.allowedKBs + if len(kbIDs) == 0 { + logger.Errorf(ctx, "[Tool][KnowledgeSearch] No knowledge bases available") + return &types.ToolResult{ + Success: false, + Error: "no knowledge bases specified and no allowed KBs configured", + }, fmt.Errorf("no knowledge bases available") + } + logger.Infof(ctx, "[Tool][KnowledgeSearch] Using all allowed KBs (%d): %v", len(kbIDs), kbIDs) + } + + // Parse query parameters + var singleQuery string + var vectorQueries, keywordQueries []string + + // Parse single query + if q, ok := args["query"].(string); ok && q != "" { + singleQuery = q + } + + // Parse vector_queries + if vq, ok := args["vector_queries"].([]interface{}); ok { + for _, q := range vq { + if queryStr, ok := q.(string); ok && queryStr != "" { + vectorQueries = append(vectorQueries, queryStr) + } + } + } + + // Parse keyword_queries + if kq, ok := args["keyword_queries"].([]interface{}); ok { + for _, q := range kq { + if queryStr, ok := q.(string); ok && queryStr != "" { + keywordQueries = append(keywordQueries, queryStr) + } + } + } + + // If single query provided, treat it as both vector and keyword query + if singleQuery != "" { + if len(vectorQueries) == 0 && len(keywordQueries) == 0 { + vectorQueries = []string{singleQuery} + keywordQueries = []string{singleQuery} + } + } + + // Validate: at least one query must be provided + if len(vectorQueries) == 0 && len(keywordQueries) == 0 { + logger.Errorf(ctx, "[Tool][KnowledgeSearch] No query provided") + return &types.ToolResult{ + Success: false, + Error: "at least one of query, vector_queries, or keyword_queries must be provided", + }, fmt.Errorf("no query provided") + } + + logger.Infof(ctx, "[Tool][KnowledgeSearch] Query mode: single=%v, vector_queries=%d, keyword_queries=%d", + singleQuery != "", len(vectorQueries), len(keywordQueries)) + if singleQuery != "" { + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Single query: %s", singleQuery) + } + if len(vectorQueries) > 0 { + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Vector queries: %v", vectorQueries) + } + if len(keywordQueries) > 0 { + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Keyword queries: %v", keywordQueries) + } + + // Parse thresholds + vectorThreshold := 0.6 + if vt, ok := args["vector_threshold"].(float64); ok { + vectorThreshold = vt + } + + keywordThreshold := 0.5 + if kt, ok := args["keyword_threshold"].(float64); ok { + keywordThreshold = kt + } + + // Parse min_score for absolute filtering + minScore := 0.3 + if ms, ok := args["min_score"].(float64); ok { + minScore = ms + } + + // Parse top_k + topK := 5 + if topKVal, ok := args["top_k"]; ok { + switch v := topKVal.(type) { + case float64: + topK = int(v) + case int: + topK = v + } + } + + logger.Infof(ctx, "[Tool][KnowledgeSearch] Search params: top_k=%d, vector_threshold=%.2f, keyword_threshold=%.2f, min_score=%.2f", + topK, vectorThreshold, keywordThreshold, minScore) + + // Extract knowledge_ids filter if provided + var knowledgeIDsFilter map[string]bool + if knowledgeIDsRaw, ok := args["knowledge_ids"].([]interface{}); ok && len(knowledgeIDsRaw) > 0 { + knowledgeIDsFilter = make(map[string]bool) + for _, id := range knowledgeIDsRaw { + if idStr, ok := id.(string); ok && idStr != "" { + knowledgeIDsFilter[idStr] = true + } + } + } + + // Execute concurrent search + logger.Infof(ctx, "[Tool][KnowledgeSearch] Starting concurrent search across %d KBs", len(kbIDs)) + allResults := t.concurrentSearch(ctx, vectorQueries, keywordQueries, kbIDs, + topK, vectorThreshold, keywordThreshold) + logger.Infof(ctx, "[Tool][KnowledgeSearch] Concurrent search completed: %d raw results", len(allResults)) + + // Filter by knowledge_ids if provided + if len(knowledgeIDsFilter) > 0 { + logger.Infof(ctx, "[Tool][KnowledgeSearch] Filtering by %d knowledge IDs", len(knowledgeIDsFilter)) + filtered := make([]*searchResultWithMeta, 0) + for _, r := range allResults { + if knowledgeIDsFilter[r.KnowledgeID] { + filtered = append(filtered, r) + } + } + logger.Infof(ctx, "[Tool][KnowledgeSearch] After knowledge_id filter: %d results (from %d)", + len(filtered), len(allResults)) + allResults = filtered + } + + // Filter by threshold first + logger.Infof(ctx, "[Tool][KnowledgeSearch] Applying threshold filter...") + filteredResults := t.filterByThreshold(allResults, vectorThreshold, keywordThreshold) + logger.Infof(ctx, "[Tool][KnowledgeSearch] After threshold filter: %d results (from %d)", + len(filteredResults), len(allResults)) + + // Apply ReRank if model is configured + if t.rerankModel != nil && len(filteredResults) > 0 { + logger.Infof(ctx, "[Tool][KnowledgeSearch] Applying rerank with model: %s, input: %d results", + t.rerankModel.GetModelName(), len(filteredResults)) + rerankQuery := singleQuery + if rerankQuery == "" && len(vectorQueries) > 0 { + rerankQuery = vectorQueries[0] // Use first vector query as rerank query + } else if rerankQuery == "" && len(keywordQueries) > 0 { + rerankQuery = keywordQueries[0] // Use first keyword query as fallback + } + + if rerankQuery != "" { + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Rerank query: %s", rerankQuery) + rerankedResults, err := t.rerankResults(ctx, rerankQuery, filteredResults) + if err != nil { + logger.Warnf(ctx, "[Tool][KnowledgeSearch] Rerank failed, using original results: %v", err) + } else { + filteredResults = rerankedResults + logger.Infof(ctx, "[Tool][KnowledgeSearch] Rerank completed successfully: %d results", + len(filteredResults)) + } + } + } + + // Apply absolute minimum score filter to remove very low quality chunks + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Applying min_score filter (%.2f)...", minScore) + filteredResults = t.filterByMinScore(filteredResults, minScore) + logger.Infof(ctx, "[Tool][KnowledgeSearch] After min_score filter: %d results", len(filteredResults)) + + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Deduplicating results...") + deduplicatedResults := t.deduplicateResults(filteredResults) + logger.Infof(ctx, "[Tool][KnowledgeSearch] After deduplication: %d results (from %d)", + len(deduplicatedResults), len(filteredResults)) + + // Sort results by score (descending) + logger.Debugf(ctx, "[Tool][KnowledgeSearch] Sorting results by score...") + sort.Slice(deduplicatedResults, func(i, j int) bool { + if deduplicatedResults[i].Score != deduplicatedResults[j].Score { + return deduplicatedResults[i].Score > deduplicatedResults[j].Score + } + // If scores are equal, prefer vector matches + if deduplicatedResults[i].QueryType != deduplicatedResults[j].QueryType { + return deduplicatedResults[i].QueryType == "vector" + } + return deduplicatedResults[i].KnowledgeID < deduplicatedResults[j].KnowledgeID + }) + + // Log top results + if len(deduplicatedResults) > 0 { + logger.Infof(ctx, "[Tool][KnowledgeSearch] Top 5 results by score:") + for i := 0; i < len(deduplicatedResults) && i < 5; i++ { + r := deduplicatedResults[i] + logger.Infof(ctx, "[Tool][KnowledgeSearch] #%d: score=%.3f, type=%s, kb=%s, chunk_id=%s", + i+1, r.Score, r.QueryType, r.KnowledgeID, r.ID) + } + } + + // Build output + logger.Infof(ctx, "[Tool][KnowledgeSearch] Formatting output with %d final results", len(deduplicatedResults)) + result, err := t.formatOutput(deduplicatedResults, vectorQueries, keywordQueries, + kbIDs, len(allResults), vectorThreshold, keywordThreshold, knowledgeIDsFilter, singleQuery) + if err != nil { + logger.Errorf(ctx, "[Tool][KnowledgeSearch] Failed to format output: %v", err) + return result, err + } + + logger.Infof(ctx, "[Tool][KnowledgeSearch] Execute completed successfully") + return result, nil +} + +// concurrentSearch executes vector and keyword searches concurrently +func (t *KnowledgeSearchTool) concurrentSearch( + ctx context.Context, + vectorQueries, keywordQueries []string, + kbsToSearch []string, + topK int, + vectorThreshold, keywordThreshold float64, +) []*searchResultWithMeta { + var wg sync.WaitGroup + var mu sync.Mutex + allResults := make([]*searchResultWithMeta, 0) + + // Launch vector searches + if len(vectorQueries) > 0 { + wg.Add(1) + go func() { + defer wg.Done() + results := t.searchWithQueries(ctx, vectorQueries, kbsToSearch, topK, + vectorThreshold, 1.0, "vector") + mu.Lock() + allResults = append(allResults, results...) + mu.Unlock() + }() + } + + // Launch keyword searches + if len(keywordQueries) > 0 { + wg.Add(1) + go func() { + defer wg.Done() + results := t.searchWithQueries(ctx, keywordQueries, kbsToSearch, topK, + 1.0, keywordThreshold, "keyword") + mu.Lock() + allResults = append(allResults, results...) + mu.Unlock() + }() + } + + wg.Wait() + return allResults +} + +// searchWithQueries executes multiple queries concurrently +func (t *KnowledgeSearchTool) searchWithQueries( + ctx context.Context, + queries []string, + kbsToSearch []string, + topK int, + vectorThreshold, keywordThreshold float64, + queryType string, +) []*searchResultWithMeta { + var wg sync.WaitGroup + var mu sync.Mutex + allResults := make([]*searchResultWithMeta, 0) + + for _, query := range queries { + wg.Add(1) + go func(q string) { + defer wg.Done() + results := t.searchSingleQuery(ctx, q, kbsToSearch, topK, + vectorThreshold, keywordThreshold, queryType) + mu.Lock() + allResults = append(allResults, results...) + mu.Unlock() + }(query) + } + + wg.Wait() + return allResults +} + +// searchSingleQuery searches a single query across multiple KBs concurrently +func (t *KnowledgeSearchTool) searchSingleQuery( + ctx context.Context, + query string, + kbsToSearch []string, + topK int, + vectorThreshold, keywordThreshold float64, + queryType string, +) []*searchResultWithMeta { + var wg sync.WaitGroup + var mu sync.Mutex + results := make([]*searchResultWithMeta, 0) + + searchParams := types.SearchParams{ + QueryText: query, + MatchCount: topK, + VectorThreshold: vectorThreshold, + KeywordThreshold: keywordThreshold, + } + + for _, kbID := range kbsToSearch { + wg.Add(1) + go func(kb string) { + defer wg.Done() + + kbResults, err := t.knowledgeService.HybridSearch(ctx, kb, searchParams) + if err != nil { + // Log error but continue with other KBs + return + } + + // Wrap results with metadata + mu.Lock() + for _, r := range kbResults { + results = append(results, &searchResultWithMeta{ + SearchResult: r, + SourceQuery: query, + QueryType: queryType, + }) + } + mu.Unlock() + }(kbID) + } + + wg.Wait() + return results +} + +// filterByThreshold filters results based on match type and threshold +func (t *KnowledgeSearchTool) filterByThreshold( + results []*searchResultWithMeta, + vectorThreshold, keywordThreshold float64, +) []*searchResultWithMeta { + filtered := make([]*searchResultWithMeta, 0) + for _, r := range results { + // Check if result meets threshold based on match type + if r.MatchType == types.MatchTypeEmbedding && r.Score >= vectorThreshold { + filtered = append(filtered, r) + } else if r.MatchType == types.MatchTypeKeywords && r.Score >= keywordThreshold { + filtered = append(filtered, r) + } else { + // For other match types (graph, nearby chunk, etc.), use the lower threshold + minThreshold := vectorThreshold + if keywordThreshold < minThreshold { + minThreshold = keywordThreshold + } + if r.Score >= minThreshold { + filtered = append(filtered, r) + } + } + } + return filtered +} + +// rerankResults applies reranking to search results using the configured rerank model +func (t *KnowledgeSearchTool) rerankResults( + ctx context.Context, + query string, + results []*searchResultWithMeta, +) ([]*searchResultWithMeta, error) { + // Prepare passages for reranking + passages := make([]string, len(results)) + for i, result := range results { + passages[i] = result.Content + } + + // Call rerank model + rerankResp, err := t.rerankModel.Rerank(ctx, query, passages) + if err != nil { + return nil, fmt.Errorf("rerank call failed: %w", err) + } + + // Map reranked results back with new scores + reranked := make([]*searchResultWithMeta, 0, len(rerankResp)) + for _, rr := range rerankResp { + if rr.Index >= 0 && rr.Index < len(results) { + // Create new result with reranked score + newResult := *results[rr.Index] + newResult.Score = rr.RelevanceScore + reranked = append(reranked, &newResult) + } + } + + logger.Infof(ctx, "Reranked %d results from %d original results", len(reranked), len(results)) + return reranked, nil +} + +// filterByMinScore filters results by absolute minimum score +func (t *KnowledgeSearchTool) filterByMinScore( + results []*searchResultWithMeta, + minScore float64, +) []*searchResultWithMeta { + filtered := make([]*searchResultWithMeta, 0) + for _, r := range results { + if r.Score >= minScore { + filtered = append(filtered, r) + } + } + return filtered +} + +// deduplicateResults removes duplicate chunks, keeping the highest score +func (t *KnowledgeSearchTool) deduplicateResults(results []*searchResultWithMeta) []*searchResultWithMeta { + seen := make(map[string]*searchResultWithMeta) + + for _, r := range results { + if existing, ok := seen[r.ID]; ok { + // Keep the result with higher score + if r.Score > existing.Score { + seen[r.ID] = r + } + } else { + seen[r.ID] = r + } + } + + deduplicated := make([]*searchResultWithMeta, 0, len(seen)) + for _, r := range seen { + deduplicated = append(deduplicated, r) + } + + return deduplicated +} + +// formatOutput formats the search results for display +func (t *KnowledgeSearchTool) formatOutput( + results []*searchResultWithMeta, + vectorQueries, keywordQueries []string, + kbsToSearch []string, + totalBeforeFilter int, + vectorThreshold, keywordThreshold float64, + knowledgeIDsFilter map[string]bool, + singleQuery string, +) (*types.ToolResult, error) { + if len(results) == 0 { + data := map[string]interface{}{ + "knowledge_base_ids": kbsToSearch, + "results": []interface{}{}, + "count": 0, + } + if len(knowledgeIDsFilter) > 0 { + filterList := make([]string, 0, len(knowledgeIDsFilter)) + for id := range knowledgeIDsFilter { + filterList = append(filterList, id) + } + data["knowledge_ids"] = filterList + } + if singleQuery != "" { + data["query"] = singleQuery + } + return &types.ToolResult{ + Success: true, + Output: fmt.Sprintf("No relevant content found in %d knowledge base(s).", len(kbsToSearch)), + Data: data, + }, nil + } + + // Determine search mode + searchMode := "Hybrid (Vector + Keyword)" + if len(vectorQueries) > 0 && len(keywordQueries) == 0 { + searchMode = "Vector" + } else if len(vectorQueries) == 0 && len(keywordQueries) > 0 { + searchMode = "Keyword" + } + + // Build output header + output := "=== Search Results ===\n" + output += fmt.Sprintf("Knowledge Bases: %v\n", kbsToSearch) + if len(knowledgeIDsFilter) > 0 { + filterList := make([]string, 0, len(knowledgeIDsFilter)) + for id := range knowledgeIDsFilter { + filterList = append(filterList, id) + } + output += fmt.Sprintf("Document Filter: %v\n", filterList) + } + output += fmt.Sprintf("Search Mode: %s\n", searchMode) + + if singleQuery != "" { + output += fmt.Sprintf("Query: %s\n", singleQuery) + } else { + if len(vectorQueries) > 0 { + output += fmt.Sprintf("Vector Queries: %v\n", vectorQueries) + output += fmt.Sprintf("Vector Threshold: %.2f\n", vectorThreshold) + } + if len(keywordQueries) > 0 { + output += fmt.Sprintf("Keyword Queries: %v\n", keywordQueries) + output += fmt.Sprintf("Keyword Threshold: %.2f\n", keywordThreshold) + } + } + + output += fmt.Sprintf("Found %d relevant results (deduplicated)", len(results)) + if totalBeforeFilter > len(results) { + output += fmt.Sprintf(" (filtered from %d)", totalBeforeFilter) + } + output += "\n\n" + + // Count results by KB + kbCounts := make(map[string]int) + for _, r := range results { + kbCounts[r.KnowledgeID]++ + } + + output += "Knowledge Base Coverage:\n" + for kbID, count := range kbCounts { + output += fmt.Sprintf(" - %s: %d results\n", kbID, count) + } + output += "\n=== Detailed Results ===\n\n" + + // Format individual results + formattedResults := make([]map[string]interface{}, 0, len(results)) + currentKB := "" + + for i, result := range results { + // Group by knowledge base + if result.KnowledgeID != currentKB { + currentKB = result.KnowledgeID + if i > 0 { + output += "\n" + } + output += fmt.Sprintf("[Source Document: %s]\n", result.KnowledgeTitle) + } + + relevanceLevel := GetRelevanceLevel(result.Score) + output += fmt.Sprintf("\nResult #%d:\n", i+1) + output += fmt.Sprintf(" Relevance: %.2f (%s)\n", result.Score, relevanceLevel) + output += fmt.Sprintf(" Match Type: %s", FormatMatchType(result.MatchType)) + if result.SourceQuery != "" && result.SourceQuery != singleQuery { + output += fmt.Sprintf(" (Query: \"%s\")", result.SourceQuery) + } + output += "\n" + output += fmt.Sprintf(" Content: %s\n", result.Content) + output += fmt.Sprintf(" [chunk_id: %s - full content included above]\n", result.ID) + + formattedResults = append(formattedResults, map[string]interface{}{ + "result_index": i + 1, + "chunk_id": result.ID, + "content": result.Content, + "score": result.Score, + "relevance_level": relevanceLevel, + "knowledge_id": result.KnowledgeID, + "knowledge_title": result.KnowledgeTitle, + "match_type": result.MatchType, + "source_query": result.SourceQuery, + "query_type": result.QueryType, + }) + } + + // Add usage guidance + output += "\n\n=== Usage Guidelines ===\n" + output += "- High relevance (>=0.8): directly usable for answering\n" + output += "- Medium relevance (0.6-0.8): use as supplementary reference\n" + output += "- Low relevance (<0.6): use with caution, may not be accurate\n" + if totalBeforeFilter > len(results) { + output += "- Results below threshold have been automatically filtered\n" + } + output += "- Full content is already included in search results above\n" + output += "- Results are deduplicated across knowledge bases and sorted by relevance\n" + output += "- Use get_related_chunks to expand context if needed\n" + + data := map[string]interface{}{ + "knowledge_base_ids": kbsToSearch, + "results": formattedResults, + "count": len(results), + "kb_counts": kbCounts, + "search_mode": searchMode, + "display_type": "search_results", + } + if len(knowledgeIDsFilter) > 0 { + filterList := make([]string, 0, len(knowledgeIDsFilter)) + for id := range knowledgeIDsFilter { + filterList = append(filterList, id) + } + data["knowledge_ids"] = filterList + } + if singleQuery != "" { + data["query"] = singleQuery + } + if len(vectorQueries) > 0 { + data["vector_queries"] = vectorQueries + } + if len(keywordQueries) > 0 { + data["keyword_queries"] = keywordQueries + } + if totalBeforeFilter > len(results) { + data["total_before_filter"] = totalBeforeFilter + data["total_after_filter"] = len(results) + } + + return &types.ToolResult{ + Success: true, + Output: output, + Data: data, + }, nil +} diff --git a/internal/agent/tools/query_knowledge_graph.go b/internal/agent/tools/query_knowledge_graph.go new file mode 100644 index 00000000..6aa7ed57 --- /dev/null +++ b/internal/agent/tools/query_knowledge_graph.go @@ -0,0 +1,423 @@ +package tools + +import ( + "context" + "fmt" + "sort" + "sync" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +// QueryKnowledgeGraphTool queries the knowledge graph for entities and relationships +type QueryKnowledgeGraphTool struct { + BaseTool + knowledgeService interfaces.KnowledgeBaseService +} + +// NewQueryKnowledgeGraphTool creates a new query knowledge graph tool +func NewQueryKnowledgeGraphTool(knowledgeService interfaces.KnowledgeBaseService) *QueryKnowledgeGraphTool { + description := `查询知识图谱,探索实体关系和知识网络。 + +## 何时使用 + +**适用场景**: +- ✅ 需要了解实体之间的关系(如"Docker和Kubernetes的关系") +- ✅ 探索知识网络和概念关联 +- ✅ 查找特定实体的相关信息 +- ✅ 理解技术架构和系统关系 + +**不适用**: +- ❌ 普通文本搜索(用 knowledge_search 更合适) +- ❌ 知识库未配置图谱抽取 +- ❌ 需要精确的文档内容(用 knowledge_search) + +## 参数说明 + +**knowledge_base_ids** (required): 要查询的知识库ID数组(1-10个) +- 只有配置了图谱抽取的知识库才会有效 +- 支持批量并发查询多个知识库 +- 示例: ["kb_tech", "kb_arch"] + +**query** (required): 查询内容 +- 可以是实体名称(如"Docker") +- 可以是关系查询(如"容器编排") +- 可以是概念搜索(如"微服务架构") + +## 图谱配置 + +知识图谱需要在知识库中预先配置: +- **实体类型**(Nodes):如"技术"、"工具"、"概念" +- **关系类型**(Relations):如"依赖"、"使用"、"包含" + +如果知识库未配置图谱,工具会提示并返回普通搜索结果。 + +## 配合使用 + +1. **关系探索**: query_knowledge_graph → get_chunk_detail(查看详细内容) +2. **网络分析**: query_knowledge_graph → get_related_chunks(扩展上下文) +3. **主题研究**: knowledge_search → query_knowledge_graph(深入实体关系) + +## 当前状态 + +⚠️ **注意**: 完整的图数据库集成正在开发中。当前版本: +- ✓ 支持图谱配置查询 +- ✓ 返回图谱相关的文档片段 +- ✓ 显示实体和关系配置信息 +- ⏳ 完整的图查询语言(Cypher)支持开发中 +- ⏳ 可视化图数据结构开发中 + +## Tips + +- 结果会标注图谱配置状态 +- 返回的Data字段包含结构化图信息供前端展示 +- 跨知识库结果自动去重 +- 按相关度排序` + + return &QueryKnowledgeGraphTool{ + BaseTool: NewBaseTool("query_knowledge_graph", description), + knowledgeService: knowledgeService, + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *QueryKnowledgeGraphTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "knowledge_base_ids": map[string]interface{}{ + "type": "array", + "description": "Array of knowledge base IDs to query", + "items": map[string]interface{}{ + "type": "string", + }, + "minItems": 1, + "maxItems": 10, + }, + "query": map[string]interface{}{ + "type": "string", + "description": "查询内容(实体名称或查询文本)", + }, + }, + "required": []string{"knowledge_base_ids", "query"}, + } +} + +// Execute queries the knowledge graph with concurrent KB processing +func (t *QueryKnowledgeGraphTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + // Extract knowledge_base_ids array + kbIDsRaw, ok := args["knowledge_base_ids"].([]interface{}) + if !ok || len(kbIDsRaw) == 0 { + return &types.ToolResult{ + Success: false, + Error: "knowledge_base_ids is required and must be a non-empty array", + }, fmt.Errorf("knowledge_base_ids is required") + } + + // Convert to string slice + var kbIDs []string + for _, id := range kbIDsRaw { + if idStr, ok := id.(string); ok && idStr != "" { + kbIDs = append(kbIDs, idStr) + } + } + + if len(kbIDs) == 0 { + return &types.ToolResult{ + Success: false, + Error: "knowledge_base_ids must contain at least one valid KB ID", + }, fmt.Errorf("no valid KB IDs provided") + } + + query, ok := args["query"].(string) + if !ok || query == "" { + return &types.ToolResult{ + Success: false, + Error: "query is required", + }, fmt.Errorf("invalid query") + } + + // Concurrently query all knowledge bases + type graphQueryResult struct { + kbID string + kb *types.KnowledgeBase + results []*types.SearchResult + err error + } + + var wg sync.WaitGroup + var mu sync.Mutex + kbResults := make(map[string]*graphQueryResult) + + searchParams := types.SearchParams{ + QueryText: query, + MatchCount: 10, + } + + for _, kbID := range kbIDs { + wg.Add(1) + go func(id string) { + defer wg.Done() + + // Get knowledge base to check graph configuration + kb, err := t.knowledgeService.GetKnowledgeBaseByID(ctx, id) + if err != nil { + mu.Lock() + kbResults[id] = &graphQueryResult{kbID: id, err: fmt.Errorf("获取知识库失败: %v", err)} + mu.Unlock() + return + } + + // Check if graph extraction is enabled + if kb.ExtractConfig == nil || (len(kb.ExtractConfig.Nodes) == 0 && len(kb.ExtractConfig.Relations) == 0) { + mu.Lock() + kbResults[id] = &graphQueryResult{kbID: id, err: fmt.Errorf("未配置知识图谱抽取")} + mu.Unlock() + return + } + + // Query graph + results, err := t.knowledgeService.HybridSearch(ctx, id, searchParams) + if err != nil { + mu.Lock() + kbResults[id] = &graphQueryResult{kbID: id, kb: kb, err: fmt.Errorf("查询失败: %v", err)} + mu.Unlock() + return + } + + mu.Lock() + kbResults[id] = &graphQueryResult{kbID: id, kb: kb, results: results} + mu.Unlock() + }(kbID) + } + + wg.Wait() + + // Collect and deduplicate results + seenChunks := make(map[string]*types.SearchResult) + var errors []string + graphConfigs := make(map[string]map[string]interface{}) + kbCounts := make(map[string]int) + + for _, kbID := range kbIDs { + result := kbResults[kbID] + if result.err != nil { + errors = append(errors, fmt.Sprintf("KB %s: %v", kbID, result.err)) + continue + } + + if result.kb != nil && result.kb.ExtractConfig != nil { + graphConfigs[kbID] = map[string]interface{}{ + "nodes": result.kb.ExtractConfig.Nodes, + "relations": result.kb.ExtractConfig.Relations, + } + } + + kbCounts[kbID] = len(result.results) + for _, r := range result.results { + if _, seen := seenChunks[r.ID]; !seen { + seenChunks[r.ID] = r + } + } + } + + // Convert map to slice and sort by score + allResults := make([]*types.SearchResult, 0, len(seenChunks)) + for _, result := range seenChunks { + allResults = append(allResults, result) + } + + sort.Slice(allResults, func(i, j int) bool { + return allResults[i].Score > allResults[j].Score + }) + + if len(allResults) == 0 { + return &types.ToolResult{ + Success: true, + Output: "未找到相关的图谱信息。", + Data: map[string]interface{}{ + "knowledge_base_ids": kbIDs, + "query": query, + "results": []interface{}{}, + "graph_configs": graphConfigs, + "errors": errors, + }, + }, nil + } + + // Format output with enhanced graph information + output := "=== 知识图谱查询 ===\n\n" + output += fmt.Sprintf("📊 查询: %s\n", query) + output += fmt.Sprintf("🎯 目标知识库: %v\n", kbIDs) + output += fmt.Sprintf("✓ 找到 %d 条相关结果(已去重)\n\n", len(allResults)) + + if len(errors) > 0 { + output += "=== ⚠️ 部分失败 ===\n" + for _, errMsg := range errors { + output += fmt.Sprintf(" - %s\n", errMsg) + } + output += "\n" + } + + // Display graph configuration status + hasGraphConfig := false + output += "=== 📈 图谱配置状态 ===\n\n" + for kbID, config := range graphConfigs { + hasGraphConfig = true + output += fmt.Sprintf("知识库【%s】:\n", kbID) + + nodes, _ := config["nodes"].([]interface{}) + relations, _ := config["relations"].([]interface{}) + + if len(nodes) > 0 { + output += fmt.Sprintf(" ✓ 实体类型 (%d): ", len(nodes)) + nodeNames := make([]string, 0, len(nodes)) + for _, n := range nodes { + if nodeMap, ok := n.(map[string]interface{}); ok { + if name, ok := nodeMap["name"].(string); ok { + nodeNames = append(nodeNames, name) + } + } + } + output += fmt.Sprintf("%v\n", nodeNames) + } else { + output += " ⚠️ 未配置实体类型\n" + } + + if len(relations) > 0 { + output += fmt.Sprintf(" ✓ 关系类型 (%d): ", len(relations)) + relNames := make([]string, 0, len(relations)) + for _, r := range relations { + if relMap, ok := r.(map[string]interface{}); ok { + if name, ok := relMap["name"].(string); ok { + relNames = append(relNames, name) + } + } + } + output += fmt.Sprintf("%v\n", relNames) + } else { + output += " ⚠️ 未配置关系类型\n" + } + output += "\n" + } + + if !hasGraphConfig { + output += "⚠️ 所查询的知识库均未配置图谱抽取\n" + output += "💡 提示: 需要在知识库设置中配置实体和关系类型\n\n" + } + + // Display result counts by KB + if len(kbCounts) > 0 { + output += "=== 📚 知识库覆盖 ===\n" + for kbID, count := range kbCounts { + output += fmt.Sprintf(" - %s: %d 条结果\n", kbID, count) + } + output += "\n" + } + + // Display search results + output += "=== 🔍 查询结果 ===\n\n" + if !hasGraphConfig { + output += "💡 当前返回相关文档片段(知识库未配置图谱)\n\n" + } else { + output += "💡 基于图谱配置的相关内容检索\n\n" + } + + formattedResults := make([]map[string]interface{}, 0, len(allResults)) + currentKB := "" + + for i, result := range allResults { + // Group by knowledge base + if result.KnowledgeID != currentKB { + currentKB = result.KnowledgeID + if i > 0 { + output += "\n" + } + output += fmt.Sprintf("【来源文档: %s】\n\n", result.KnowledgeTitle) + } + + relevanceLevel := GetRelevanceLevel(result.Score) + + output += fmt.Sprintf("结果 #%d:\n", i+1) + output += fmt.Sprintf(" 📍 相关度: %.2f (%s)\n", result.Score, relevanceLevel) + output += fmt.Sprintf(" 🔗 匹配方式: %s\n", FormatMatchType(result.MatchType)) + output += fmt.Sprintf(" 📄 内容: %s\n", result.Content) + output += fmt.Sprintf(" 🆔 chunk_id: %s\n\n", result.ID) + + formattedResults = append(formattedResults, map[string]interface{}{ + "result_index": i + 1, + "chunk_id": result.ID, + "content": result.Content, + "score": result.Score, + "relevance_level": relevanceLevel, + "knowledge_id": result.KnowledgeID, + "knowledge_title": result.KnowledgeTitle, + "match_type": FormatMatchType(result.MatchType), + }) + } + + output += "=== 💡 使用提示 ===\n" + output += "- ✓ 结果已跨知识库去重并按相关度排序\n" + output += "- ✓ 使用 get_chunk_detail 获取完整内容\n" + output += "- ✓ 使用 get_related_chunks 探索上下文\n" + if !hasGraphConfig { + output += "- ⚠️ 配置图谱抽取以获得更精准的实体关系结果\n" + } + output += "- ⏳ 完整的图查询语言(Cypher)支持开发中\n" + + // Build structured graph data for frontend visualization + graphData := buildGraphVisualizationData(allResults, graphConfigs) + + return &types.ToolResult{ + Success: true, + Output: output, + Data: map[string]interface{}{ + "knowledge_base_ids": kbIDs, + "query": query, + "results": formattedResults, + "count": len(allResults), + "kb_counts": kbCounts, + "graph_configs": graphConfigs, + "graph_data": graphData, + "has_graph_config": hasGraphConfig, + "errors": errors, + "display_type": "graph_query_results", + }, + }, nil +} + +// buildGraphVisualizationData builds structured data for graph visualization +func buildGraphVisualizationData(results []*types.SearchResult, graphConfigs map[string]map[string]interface{}) map[string]interface{} { + // Build a simple graph structure for frontend visualization + nodes := make([]map[string]interface{}, 0) + edges := make([]map[string]interface{}, 0) + + // Create nodes from results + seenEntities := make(map[string]bool) + for i, result := range results { + if !seenEntities[result.ID] { + nodes = append(nodes, map[string]interface{}{ + "id": result.ID, + "label": fmt.Sprintf("Chunk %d", i+1), + "content": result.Content, + "kb_id": result.KnowledgeID, + "kb_title": result.KnowledgeTitle, + "score": result.Score, + "type": "chunk", + }) + seenEntities[result.ID] = true + } + } + + // TODO: Extract actual entities and relations when graph extraction is fully implemented + // For now, create placeholder structure + + return map[string]interface{}{ + "nodes": nodes, + "edges": edges, + "total_nodes": len(nodes), + "total_edges": len(edges), + "visualization_note": "完整的图可视化功能开发中,当前显示文档节点", + } +} diff --git a/internal/agent/tools/registry.go b/internal/agent/tools/registry.go new file mode 100644 index 00000000..85c7e38b --- /dev/null +++ b/internal/agent/tools/registry.go @@ -0,0 +1,108 @@ +package tools + +import ( + "context" + "fmt" + + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "gorm.io/gorm" +) + +// ToolRegistry manages the registration and retrieval of tools +type ToolRegistry struct { + tools map[string]types.Tool + knowledgeBaseService interfaces.KnowledgeBaseService + knowledgeService interfaces.KnowledgeService + chunkService interfaces.ChunkService + db *gorm.DB // gorm.DB interface for database query tool +} + +// NewToolRegistry creates a new tool registry +func NewToolRegistry( + knowledgeBaseService interfaces.KnowledgeBaseService, + knowledgeService interfaces.KnowledgeService, + chunkService interfaces.ChunkService, + db *gorm.DB, // gorm.DB for database operations +) *ToolRegistry { + return &ToolRegistry{ + tools: make(map[string]types.Tool), + knowledgeBaseService: knowledgeBaseService, + knowledgeService: knowledgeService, + chunkService: chunkService, + db: db, + } +} + +// RegisterTool adds a tool to the registry +func (r *ToolRegistry) RegisterTool(tool types.Tool) { + r.tools[tool.Name()] = tool +} + +// GetTool retrieves a tool by name +func (r *ToolRegistry) GetTool(name string) (types.Tool, error) { + tool, exists := r.tools[name] + if !exists { + return nil, fmt.Errorf("tool not found: %s", name) + } + return tool, nil +} + +// ListTools returns all registered tool names +func (r *ToolRegistry) ListTools() []string { + names := make([]string, 0, len(r.tools)) + for name := range r.tools { + names = append(names, name) + } + return names +} + +// GetFunctionDefinitions returns function definitions for allowed tools +// This is used for LLM function calling +func (r *ToolRegistry) GetFunctionDefinitions(allowedTools []string) []types.FunctionDefinition { + definitions := make([]types.FunctionDefinition, 0) + + // If no allowed tools specified, return all tools + if len(allowedTools) == 0 { + for _, tool := range r.tools { + definitions = append(definitions, types.FunctionDefinition{ + Name: tool.Name(), + Description: tool.Description(), + Parameters: tool.Parameters(), + }) + } + return definitions + } + + // Create a map for quick lookup + allowedMap := make(map[string]bool) + for _, name := range allowedTools { + allowedMap[name] = true + } + + // Only include allowed tools + for name, tool := range r.tools { + if allowedMap[name] { + definitions = append(definitions, types.FunctionDefinition{ + Name: tool.Name(), + Description: tool.Description(), + Parameters: tool.Parameters(), + }) + } + } + + return definitions +} + +// ExecuteTool executes a tool by name with the given arguments +func (r *ToolRegistry) ExecuteTool(ctx context.Context, name string, args map[string]interface{}) (*types.ToolResult, error) { + tool, err := r.GetTool(name) + if err != nil { + return &types.ToolResult{ + Success: false, + Error: err.Error(), + }, err + } + + return tool.Execute(ctx, args) +} diff --git a/internal/agent/tools/thinking.go b/internal/agent/tools/thinking.go new file mode 100644 index 00000000..e8261174 --- /dev/null +++ b/internal/agent/tools/thinking.go @@ -0,0 +1,115 @@ +package tools + +import ( + "context" + + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" +) + +// ThinkingTool implements the thinking tool functionality +// This is a no-op tool inspired by code-agent and tau-bench +// It logs thoughts for transparency and better decision-making +type ThinkingTool struct { + BaseTool +} + +// NewThinkingTool creates a new thinking tool instance +func NewThinkingTool() *ThinkingTool { + description := `Deep reasoning tool for systematic thinking. Use this frequently to analyze, plan, and reflect. + +## Purpose + +This tool helps you: +- **Analyze problems** before acting +- **Plan your approach** for complex tasks +- **Evaluate results** after tool calls +- **Reflect** on strategy and adjust + +This is a no-op tool - it doesn't fetch data, but helps organize your reasoning transparently. + +## When to Use + +**Use frequently at key moments**: +- **Start**: Analyze the question, understand what's needed +- **Before major decisions**: Which tool to use? What query to run? +- **After tool calls**: Evaluate results, decide next step +- **Before answering**: Organize information, check completeness + +## What to Think About + +### At Start +- What is the user really asking? +- What information do I need? +- What's my search strategy? + +### After Search Results +- Are results relevant? Complete? +- Do I need more context (get_related_chunks)? +- Should I search more or answer now? + +### Before Answering +- Do I have enough information? +- Are all sources cited? +- Is the structure clear? + + +## Tips + +- Use before important decisions +- Keep thoughts focused and actionable +- End with clear next step +- Don't overthink simple queries` + + return &ThinkingTool{ + BaseTool: NewBaseTool( + "thinking", + description, + ), + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *ThinkingTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "thought": map[string]interface{}{ + "type": "string", + "description": "Your thinking process and reasoning content", + }, + }, + "required": []string{"thought"}, + } +} + +// Execute executes the thinking tool +func (t *ThinkingTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + logger.Infof(ctx, "[Tool][Thinking] Execute started") + + thought, ok := args["thought"].(string) + if !ok { + thought = "Thought content not provided" + logger.Warnf(ctx, "[Tool][Thinking] No thought content provided") + } + + logger.Infof(ctx, "[Tool][Thinking] Thought length: %d characters", len(thought)) + logger.Debugf(ctx, "[Tool][Thinking] Thought content:\n%s", thought) + + // This is a no-op tool - it just logs the thought + // The thought itself is valuable for transparency and decision-making + + // Format output for better display + output := "Thought process recorded:\n\n" + output += thought + + logger.Infof(ctx, "[Tool][Thinking] Execute completed") + return &types.ToolResult{ + Success: true, + Output: output, + Data: map[string]interface{}{ + "thought": thought, + "display_type": "thinking", + }, + }, nil +} diff --git a/internal/agent/tools/todo_write.go b/internal/agent/tools/todo_write.go new file mode 100644 index 00000000..648f38a3 --- /dev/null +++ b/internal/agent/tools/todo_write.go @@ -0,0 +1,344 @@ +package tools + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/Tencent/WeKnora/internal/types" +) + +// TodoWriteTool implements a planning tool for complex tasks +// This is an optional tool that helps organize multi-step research +type TodoWriteTool struct { + BaseTool +} + +// PlanStep represents a single step in the research plan +type PlanStep struct { + ID string `json:"id"` + Description string `json:"description"` + ToolsToUse string `json:"tools_to_use"` + Status string `json:"status"` // pending, in_progress, completed, skipped +} + +// NewTodoWriteTool creates a new todo_write tool instance +func NewTodoWriteTool() *TodoWriteTool { + description := `Use this tool to create a structured, actionable plan for complex research tasks. This helps you organize multi-step investigations, track progress, and ensure comprehensive coverage. + +## Critical Thinking Integration +**IMPORTANT**: When working with complex research questions, you should typically use the **think tool** for deep analysis BEFORE creating your plan. This ensures: + +- **Problem Analysis**: Use think tool to analyze the research question, identify key dimensions, and explore different angles +- **Strategic Planning**: Use think tool to consider what information is needed, which knowledge bases to search, and potential challenges +- **Scope Definition**: Use think tool to determine the depth and breadth of research required + +The think tool helps ensure your plan is comprehensive, well-structured, and addresses all aspects of the research question effectively. + +## When to Use This Tool + +Use this tool proactively in these scenarios: + +1. **Complex multi-dimensional questions** - Questions requiring investigation of multiple aspects or dimensions +2. **Comparison tasks** - When you need to compare multiple systems, approaches, or solutions systematically +3. **Deep research tasks** - Questions requiring exploration of multiple knowledge areas or documents +4. **Architecture analysis** - Tasks involving system design, architecture review, or technical deep-dives +5. **User requests explicit planning** - When users ask for structured analysis or step-by-step investigation + +## When NOT to Use This Tool + +Skip using this tool when: + +1. **Simple, direct queries** - Questions with straightforward answers (e.g., "What is a vector database?") +2. **Single-step searches** - When you already know exactly what to search for +3. **Mid-execution** - Don't create plans after you've already started searching +4. **Trivial lookups** - Simple fact-finding that requires one tool call + +NOTE: If the question can be answered with 1-2 simple searches, skip planning and search directly. + +## Examples of When to Use + + +User: "如何设计一个高可用的微服务架构?需要考虑哪些方面?" +Assistant: This is a complex, multi-dimensional question. Let me first think through the key aspects and then create a structured research plan. +*Uses think tool to analyze: architecture patterns, reliability concerns, deployment strategies, monitoring needs* +Assistant: Based on my analysis, let me create a research plan covering the main dimensions. +*Creates plan with steps for:* +1. Search microservices architecture patterns and best practices +2. Investigate high availability strategies (load balancing, failover, redundancy) +3. Research service mesh and communication patterns +4. Explore monitoring and observability solutions +5. Investigate deployment and scaling strategies +*Begins executing the plan* + + +The assistant used both think and todo_write tools because: +1. First used think tool to analyze the multi-dimensional nature of the question +2. Identified key areas: architecture, availability, communication, monitoring, deployment +3. Created a structured plan to ensure systematic coverage +4. The plan helps avoid missing critical aspects of high availability + + + + +User: "对比Redis、Memcached和Hazelcast这三种缓存系统的性能、成本和适用场景" +Assistant: This is a structured comparison task. Let me think through the comparison dimensions and create a systematic research plan. +*Uses think tool to identify: performance metrics, cost factors, use case categories, comparison criteria* +Assistant: I'll create a research plan to ensure fair, comprehensive comparison across all three systems. +*Creates plan with steps:* +1. Search Redis characteristics (performance, features, use cases) +2. Search Memcached characteristics (performance, features, use cases) +3. Search Hazelcast characteristics (performance, features, use cases) +4. Search direct performance comparisons between these systems +5. Investigate cost considerations and deployment complexity +*Executes searches systematically* + + +The assistant used todo_write because: +1. Comparison tasks benefit from structured, parallel research +2. The plan ensures each system is investigated equally +3. Structured approach prevents bias toward any particular system +4. Makes it easier to synthesize structured comparison at the end + + + +## Examples of When NOT to Use + + +User: "向量数据库的主要用途是什么?" +Assistant: Let me search for information about vector database use cases. +*Uses knowledge_search directly without planning* + + +The assistant skipped todo_write because: +1. This is a simple, direct question +2. One well-crafted search will likely provide the answer +3. No need to organize multiple research steps +4. Planning would add unnecessary overhead + + + + +User: "Kubernetes是什么?" +Assistant: Let me search for information about Kubernetes. +*Uses knowledge_search directly* + + +Simple definitional question - just search directly without planning. + + + +## Standard Workflow + +The recommended workflow when using this tool: + +` + "```" + ` +Step 1: User asks complex question + ↓ +Step 2: Use think tool (analyze problem, identify dimensions, consider approaches) + ↓ +Step 3: Use todo_write tool (create structured plan with steps, tools, priorities) [OPTIONAL] + ↓ +Step 4: Execute plan steps (use search tools, mark progress) + ↓ +Step 5: Use think tool (evaluate results, identify gaps) + ↓ +Step 6: Adjust plan or execute remaining steps + ↓ +Step 7: Synthesize comprehensive answer with citations +` + "```" + ` + +## Plan Structure + +Your plan should include steps with: +- **ID**: Unique identifier for each step (e.g., "step1", "step2") +- **Description**: Clear description of what to investigate +- **Tools to Use**: Which tools to use (e.g., "knowledge_search", "get_related_chunks") +- **Status**: Current status (pending, in_progress, completed, skipped) + +## Step Status Management + +1. **Status Values**: + - **pending**: Step not yet started (default for new steps) + - **in_progress**: Currently executing this step + - **completed**: Step finished successfully with results + - **skipped**: Step determined to be unnecessary based on findings + +2. **Status Management Best Practices**: + - Start with all steps as "pending" + - Mark one step as "in_progress" before executing it + - Update to "completed" immediately after finishing + - Mark as "skipped" if findings make a step unnecessary + +## Parameters + +- **task** (required): The complex task or question you need to create a plan for + - Be specific about what needs to be accomplished + - Include the user's actual question or research goal + +- **steps** (required): Array of plan steps, each containing: + - **id**: Unique identifier (e.g., "step1", "step2") + - **description**: What to investigate or accomplish + - **tools_to_use**: Suggested tools for this step + - **status**: Current status (pending, in_progress, completed, skipped) + +## Best Practices + +1. **Think First**: Always use think tool before creating a plan to ensure thorough analysis +2. **Be Specific**: Each step should have a clear, actionable objective +3. **Stay Flexible**: Adjust the plan based on findings - some steps may become unnecessary +4. **Track Progress**: Update step status as you work through the plan +5. **Don't Over-plan**: 3-7 steps is usually sufficient; more suggests over-complexity +` + + return &TodoWriteTool{ + BaseTool: NewBaseTool("todo_write", description), + } +} + +// Parameters returns the JSON schema for the tool's parameters +func (t *TodoWriteTool) Parameters() map[string]interface{} { + return map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "task": map[string]interface{}{ + "type": "string", + "description": "The complex task or question you need to create a plan for", + }, + "steps": map[string]interface{}{ + "type": "array", + "description": "Array of research plan steps with status tracking", + "items": map[string]interface{}{ + "type": "object", + "properties": map[string]interface{}{ + "id": map[string]interface{}{ + "type": "string", + "description": "Unique identifier for this step (e.g., 'step1', 'step2')", + }, + "description": map[string]interface{}{ + "type": "string", + "description": "Clear description of what to investigate or accomplish in this step", + }, + "tools_to_use": map[string]interface{}{ + "type": "string", + "description": "Suggested tools for this step (e.g., 'knowledge_search', 'get_related_chunks')", + }, + "status": map[string]interface{}{ + "type": "string", + "enum": []string{"pending", "in_progress", "completed", "skipped"}, + "description": "Current status: pending (not started), in_progress (executing), completed (finished), skipped (unnecessary)", + }, + }, + "required": []string{"id", "description", "status"}, + }, + }, + }, + "required": []string{"task", "steps"}, + } +} + +// Execute executes the todo_write tool +func (t *TodoWriteTool) Execute(ctx context.Context, args map[string]interface{}) (*types.ToolResult, error) { + task, ok := args["task"].(string) + if !ok { + task = "未提供任务描述" + } + + // Parse plan steps + var planSteps []PlanStep + if stepsData, ok := args["steps"].([]interface{}); ok { + for _, stepData := range stepsData { + if stepMap, ok := stepData.(map[string]interface{}); ok { + step := PlanStep{ + ID: getStringField(stepMap, "id"), + Description: getStringField(stepMap, "description"), + ToolsToUse: getStringField(stepMap, "tools_to_use"), + Status: getStringField(stepMap, "status"), + } + planSteps = append(planSteps, step) + } + } + } + + // Generate formatted output + output := generatePlanOutput(task, planSteps) + + // Prepare structured data for response + stepsJSON, _ := json.Marshal(planSteps) + + return &types.ToolResult{ + Success: true, + Output: output, + Data: map[string]interface{}{ + "task": task, + "steps": planSteps, + "steps_json": string(stepsJSON), + "total_steps": len(planSteps), + "plan_created": true, + "display_type": "plan", + }, + }, nil +} + +// Helper function to safely get string field from map +func getStringField(m map[string]interface{}, key string) string { + if val, ok := m[key].(string); ok { + return val + } + return "" +} + +// generatePlanOutput generates a formatted plan output +func generatePlanOutput(task string, steps []PlanStep) string { + output := "计划已创建\n\n" + output += fmt.Sprintf("**任务**: %s\n\n", task) + + if len(steps) == 0 { + output += "注意:未提供具体步骤。建议创建3-7个结构化步骤以系统化研究。\n\n" + output += "建议的通用流程:\n" + output += "1. 使用 knowledge_search 进行初步信息收集\n" + output += "2. 使用 get_related_chunks 获取关键信息详情\n" + output += "3. 使用 get_related_chunks 扩展上下文理解\n" + output += "4. 使用 think 工具评估结果并综合答案\n" + return output + } + + output += "**计划步骤**:\n\n" + + // Display all steps in order + for i, step := range steps { + output += formatPlanStep(i+1, step) + } + + output += "\n**执行指南**:\n" + output += "- 每步执行前标记为 in_progress,完成后标记为 completed\n" + output += "- 根据搜索结果灵活调整计划,可跳过不必要的步骤\n" + output += "- 在关键决策点使用 think 工具深入分析\n" + output += "- 如果某一步骤已获得足够信息,可跳过后续步骤\n\n" + output += "注意:计划是指导而非硬性要求,保持灵活应对。" + + return output +} + +// formatPlanStep formats a single plan step for output +func formatPlanStep(index int, step PlanStep) string { + statusEmoji := map[string]string{ + "pending": "⏳", + "in_progress": "🔄", + "completed": "✅", + "skipped": "⏭️", + } + + emoji, ok := statusEmoji[step.Status] + if !ok { + emoji = "⏳" + } + + output := fmt.Sprintf(" %d. %s [%s] %s\n", index, emoji, step.Status, step.Description) + + if step.ToolsToUse != "" { + output += fmt.Sprintf(" 工具: %s\n", step.ToolsToUse) + } + + return output +} diff --git a/internal/agent/tools/tool.go b/internal/agent/tools/tool.go new file mode 100644 index 00000000..9768e198 --- /dev/null +++ b/internal/agent/tools/tool.go @@ -0,0 +1,77 @@ +package tools + +import ( + "fmt" + + "github.com/Tencent/WeKnora/internal/types" +) + +// BaseTool provides common functionality for tools +type BaseTool struct { + name string + description string +} + +// NewBaseTool creates a new base tool +func NewBaseTool(name, description string) BaseTool { + return BaseTool{ + name: name, + description: description, + } +} + +// Name returns the tool name +func (t *BaseTool) Name() string { + return t.name +} + +// Description returns the tool description +func (t *BaseTool) Description() string { + return t.description +} + +// ToolExecutor is a helper interface for executing tools +type ToolExecutor interface { + types.Tool + + // GetContext returns any context-specific data needed for tool execution + GetContext() map[string]interface{} +} + +// Shared helper functions for tool output formatting + +// GetRelevanceLevel converts a score to a human-readable relevance level +func GetRelevanceLevel(score float64) string { + switch { + case score >= 0.8: + return "高相关" + case score >= 0.6: + return "中相关" + case score >= 0.4: + return "低相关" + default: + return "弱相关" + } +} + +// FormatMatchType converts MatchType to a human-readable string +func FormatMatchType(mt types.MatchType) string { + switch mt { + case types.MatchTypeEmbedding: + return "向量匹配" + case types.MatchTypeKeywords: + return "关键词匹配" + case types.MatchTypeNearByChunk: + return "相邻块匹配" + case types.MatchTypeHistory: + return "历史匹配" + case types.MatchTypeParentChunk: + return "父块匹配" + case types.MatchTypeRelationChunk: + return "关系块匹配" + case types.MatchTypeGraph: + return "图谱匹配" + default: + return fmt.Sprintf("未知类型(%d)", mt) + } +} diff --git a/internal/application/repository/model.go b/internal/application/repository/model.go index 568f76c7..7dab452d 100644 --- a/internal/application/repository/model.go +++ b/internal/application/repository/model.go @@ -64,9 +64,10 @@ func (r *modelRepository) List( // Update updates a model func (r *modelRepository) Update(ctx context.Context, m *types.Model) error { + // Use Select to explicitly update all fields, including zero values like false return r.db.WithContext(ctx).Debug().Model(&types.Model{}).Where( "id = ? AND tenant_id = ?", m.ID, m.TenantID, - ).Updates(m).Error + ).Select("*").Updates(m).Error } // Delete deletes a model @@ -75,3 +76,19 @@ func (r *modelRepository) Delete(ctx context.Context, tenantID uint, id string) "id = ? AND tenant_id = ?", id, tenantID, ).Delete(&types.Model{}).Error } + +// ClearDefaultByType clears the default flag for all models of a specific type +// This is a batch operation that updates all matching records in one query +func (r *modelRepository) ClearDefaultByType(ctx context.Context, tenantID uint, modelType types.ModelType, excludeID string) error { + query := r.db.WithContext(ctx).Model(&types.Model{}).Where( + "tenant_id = ? AND type = ? AND is_default = ?", tenantID, modelType, true, + ) + + // If excludeID is provided, exclude that model from the update + if excludeID != "" { + query = query.Where("id != ?", excludeID) + } + + // Batch update: set is_default to false for all matching records + return query.Update("is_default", false).Error +} diff --git a/internal/application/service/agent_service.go b/internal/application/service/agent_service.go new file mode 100644 index 00000000..11a6f7e5 --- /dev/null +++ b/internal/application/service/agent_service.go @@ -0,0 +1,287 @@ +package service + +import ( + "context" + "fmt" + + "github.com/Tencent/WeKnora/internal/agent" + "github.com/Tencent/WeKnora/internal/agent/tools" + "github.com/Tencent/WeKnora/internal/config" + "github.com/Tencent/WeKnora/internal/event" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/models/chat" + "github.com/Tencent/WeKnora/internal/models/rerank" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "gorm.io/gorm" +) + +// agentService implements agent-related business logic +type agentService struct { + cfg *config.Config + modelService interfaces.ModelService + knowledgeBaseService interfaces.KnowledgeBaseService + knowledgeService interfaces.KnowledgeService + chunkService interfaces.ChunkService + eventBus *event.EventBus + db *gorm.DB +} + +// NewAgentService creates a new agent service +func NewAgentService( + cfg *config.Config, + modelService interfaces.ModelService, + knowledgeBaseService interfaces.KnowledgeBaseService, + knowledgeService interfaces.KnowledgeService, + chunkService interfaces.ChunkService, + eventBus *event.EventBus, + db *gorm.DB, +) interfaces.AgentService { + return &agentService{ + cfg: cfg, + modelService: modelService, + knowledgeBaseService: knowledgeBaseService, + knowledgeService: knowledgeService, + chunkService: chunkService, + eventBus: eventBus, + db: db, + } +} + +// CreateAgentEngineWithEventBus creates an agent engine with the given configuration and EventBus +func (s *agentService) CreateAgentEngine( + ctx context.Context, + config *types.AgentConfig, + eventBus *event.EventBus, +) (interfaces.AgentEngine, error) { + logger.Infof(ctx, "Creating agent engine with custom EventBus") + + // Validate config + if err := s.ValidateConfig(config); err != nil { + return nil, fmt.Errorf("invalid agent config: %w", err) + } + + chatModel, err := s.modelService.GetChatModel(ctx, config.ThinkingModelID) + if err != nil { + return nil, fmt.Errorf("failed to get thinking model: %w", err) + } + + if chatModel == nil { + return nil, fmt.Errorf("chat model is nil after initialization") + } + + rerankModel, err := s.modelService.GetRerankModel(ctx, config.RerankModelID) + if err != nil { + return nil, fmt.Errorf("failed to get rerank model: %w", err) + } + + if rerankModel == nil { + return nil, fmt.Errorf("rerank model is nil after initialization") + } + + // Create tool registry + toolRegistry := tools.NewToolRegistry(s.knowledgeBaseService, s.knowledgeService, s.chunkService, s.db) + + // Register tools + if err := s.registerTools(ctx, toolRegistry, config, chatModel, rerankModel); err != nil { + return nil, fmt.Errorf("failed to register tools: %w", err) + } + + // Get knowledge base detailed information for prompt + kbInfos, err := s.getKnowledgeBaseInfos(ctx, config.KnowledgeBases) + if err != nil { + logger.Warnf(ctx, "Failed to get knowledge base details, using IDs only: %v", err) + // Create fallback info with IDs only + kbInfos = make([]*agent.KnowledgeBaseInfo, 0, len(config.KnowledgeBases)) + for _, kbID := range config.KnowledgeBases { + kbInfos = append(kbInfos, &agent.KnowledgeBaseInfo{ + ID: kbID, + Name: kbID, // Use ID as name when details unavailable + Description: "", + DocCount: 0, + }) + } + } + + // Create engine with provided EventBus + engine := agent.NewAgentEngine( + config, + chatModel, + toolRegistry, + s.knowledgeBaseService, + eventBus, + kbInfos, + ) + + return engine, nil +} + +// registerTools registers tools based on the agent configuration +func (s *agentService) registerTools( + ctx context.Context, + registry *tools.ToolRegistry, + config *types.AgentConfig, + chatModel chat.Chat, + rerankModel rerank.Reranker, +) error { + // If no specific tools allowed, register default tools + allowedTools := config.AllowedTools + if len(allowedTools) == 0 { + // Register default tools from config + if s.cfg.Agent != nil && len(s.cfg.Agent.DefaultTools) > 0 { + allowedTools = s.cfg.Agent.DefaultTools + } else { + // Fallback to all tools + allowedTools = []string{ + "thinking", + "todo_write", + "knowledge_search", + "get_related_chunks", + "query_knowledge_graph", + "get_document_info", + "database_query", + } + } + } + // Get tenant ID from context + tenantID := uint(0) + if tid, ok := ctx.Value(types.TenantIDContextKey).(uint); ok { + tenantID = tid + } + logger.Infof(ctx, "Registering tools: %v, tenant ID: %d", allowedTools, tenantID) + + // Register each allowed tool + for _, toolName := range allowedTools { + switch toolName { + case "thinking": + registry.RegisterTool(tools.NewThinkingTool()) + case "todo_write": + registry.RegisterTool(tools.NewTodoWriteTool()) + case "knowledge_search": + registry.RegisterTool(tools.NewKnowledgeSearchTool(s.knowledgeBaseService, tenantID, config.KnowledgeBases, rerankModel)) + case "get_related_chunks": + registry.RegisterTool(tools.NewGetRelatedChunksTool(s.chunkService, s.knowledgeBaseService)) + case "query_knowledge_graph": + registry.RegisterTool(tools.NewQueryKnowledgeGraphTool(s.knowledgeBaseService)) + case "get_document_info": + registry.RegisterTool(tools.NewGetDocumentInfoTool(s.knowledgeService, s.chunkService)) + case "database_query": + registry.RegisterTool(tools.NewDatabaseQueryTool(s.db, tenantID)) + default: + logger.Warnf(ctx, "Unknown tool: %s", toolName) + } + } + + logger.Infof(ctx, "Registered %d tools", len(registry.ListTools())) + return nil +} + +// ValidateConfig validates the agent configuration +func (s *agentService) ValidateConfig(config *types.AgentConfig) error { + if config == nil { + return fmt.Errorf("config cannot be nil") + } + + if !config.Enabled { + return fmt.Errorf("agent is not enabled") + } + + if config.MaxIterations <= 0 { + config.MaxIterations = 5 // Default + } + + if config.MaxIterations > 20 { + return fmt.Errorf("max iterations too high: %d (max 20)", config.MaxIterations) + } + + if config.ThinkingModelID == "" { + return fmt.Errorf("ThinkingModelID is required but not set") + } + + return nil +} + +// getKnowledgeBaseInfos retrieves detailed information for knowledge bases +func (s *agentService) getKnowledgeBaseInfos(ctx context.Context, kbIDs []string) ([]*agent.KnowledgeBaseInfo, error) { + if len(kbIDs) == 0 { + return []*agent.KnowledgeBaseInfo{}, nil + } + + kbInfos := make([]*agent.KnowledgeBaseInfo, 0, len(kbIDs)) + + for _, kbID := range kbIDs { + // Get knowledge base details + kb, err := s.knowledgeBaseService.GetKnowledgeBaseByID(ctx, kbID) + if err != nil { + logger.Warnf(ctx, "Failed to get knowledge base %s: %v", kbID, err) + // Add fallback info + kbInfos = append(kbInfos, &agent.KnowledgeBaseInfo{ + ID: kbID, + Name: kbID, + Description: "", + DocCount: 0, + RecentDocs: []agent.RecentDocInfo{}, + }) + continue + } + + // Get document count and recent documents + docCount := 0 + recentDocs := []agent.RecentDocInfo{} + + // Get recent documents using paged query (first 10, assumed to be sorted by created_at desc) + pageResult, err := s.knowledgeService.ListPagedKnowledgeByKnowledgeBaseID(ctx, kbID, &types.Pagination{ + Page: 1, + PageSize: 10, + }) + + if err == nil && pageResult != nil { + docCount = int(pageResult.Total) + + // Convert to Knowledge slice + if knowledges, ok := pageResult.Data.([]*types.Knowledge); ok { + for _, k := range knowledges { + if len(recentDocs) >= 10 { + break + } + recentDocs = append(recentDocs, agent.RecentDocInfo{ + Title: k.Title, + FileName: k.FileName, + Type: k.FileType, + CreatedAt: k.CreatedAt.Format("2006-01-02"), + }) + } + } + } else { + // Fallback: use ListKnowledgeByKnowledgeBaseID + knowledges, err := s.knowledgeService.ListKnowledgeByKnowledgeBaseID(ctx, kbID) + if err == nil && knowledges != nil { + docCount = len(knowledges) + // Get up to 10 most recent (assuming the list is already sorted) + for i, k := range knowledges { + if i >= 10 { + break + } + recentDocs = append(recentDocs, agent.RecentDocInfo{ + KnowledgeID: k.ID, + Title: k.Title, + FileName: k.FileName, + FileSize: k.FileSize, + Type: k.FileType, + CreatedAt: k.CreatedAt.Format("2006-01-02"), + }) + } + } + } + + kbInfos = append(kbInfos, &agent.KnowledgeBaseInfo{ + ID: kb.ID, + Name: kb.Name, + Description: kb.Description, + DocCount: docCount, + RecentDocs: recentDocs, + }) + } + + return kbInfos, nil +} diff --git a/internal/application/service/chat_pipline/chat_completion_stream.go b/internal/application/service/chat_pipline/chat_completion_stream.go index 7f5644b4..f8d228e1 100644 --- a/internal/application/service/chat_pipline/chat_completion_stream.go +++ b/internal/application/service/chat_pipline/chat_completion_stream.go @@ -2,6 +2,7 @@ package chatpipline import ( "context" + "errors" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/types" @@ -55,6 +56,10 @@ func (p *PluginChatCompletionStream) OnEvent(ctx context.Context, logger.Errorf(ctx, "Failed to call chat stream model: %v", err) return ErrModelCall.WithError(err) } + if responseChan == nil { + logger.Error(ctx, "Chat stream returned nil channel") + return ErrModelCall.WithError(errors.New("chat stream returned nil channel")) + } logger.Info(ctx, "Chat stream initiated successfully") chatManage.ResponseChan = responseChan diff --git a/internal/application/service/chunk.go b/internal/application/service/chunk.go index b82a4bd2..8fb06af3 100644 --- a/internal/application/service/chunk.go +++ b/internal/application/service/chunk.go @@ -73,19 +73,14 @@ func (s *chunkService) CreateChunks(ctx context.Context, chunks []*types.Chunk) // Returns: // - *types.Chunk: Retrieved chunk if found // - error: Any error encountered during retrieval -func (s *chunkService) GetChunkByID(ctx context.Context, knowledgeID string, id string) (*types.Chunk, error) { - logger.Info(ctx, "Start getting chunk by ID") - logger.Infof(ctx, "Getting chunk, ID: %s, knowledge ID: %s", id, knowledgeID) - +func (s *chunkService) GetChunkByID(ctx context.Context, id string) (*types.Chunk, error) { tenantID := ctx.Value(types.TenantIDContextKey).(uint) - logger.Infof(ctx, "Tenant ID: %d", tenantID) - + logger.Infof(ctx, "Getting chunk by ID, ID: %s, tenant ID: %d", id, tenantID) chunk, err := s.chunkRepository.GetChunkByID(ctx, tenantID, id) if err != nil { logger.ErrorWithFields(ctx, err, map[string]interface{}{ - "chunk_id": id, - "knowledge_id": knowledgeID, - "tenant_id": tenantID, + "chunk_id": id, + "tenant_id": tenantID, }) return nil, err } diff --git a/internal/application/service/context_manager.go b/internal/application/service/context_manager.go new file mode 100644 index 00000000..613b8e0d --- /dev/null +++ b/internal/application/service/context_manager.go @@ -0,0 +1,354 @@ +package service + +import ( + "context" + "fmt" + "strings" + "sync" + + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/models/chat" + "github.com/Tencent/WeKnora/internal/types/interfaces" +) + +// sessionContext holds the context for a single session +type sessionContext struct { + Messages []chat.Message + mu sync.RWMutex +} + +// contextManager implements the ContextManager interface +type contextManager struct { + sessions map[string]*sessionContext + mu sync.RWMutex + compressionStrategy interfaces.CompressionStrategy + maxTokens int // Maximum tokens allowed in context +} + +// NewContextManager creates a new context manager +func NewContextManager(compressionStrategy interfaces.CompressionStrategy, maxTokens int) interfaces.ContextManager { + return &contextManager{ + sessions: make(map[string]*sessionContext), + compressionStrategy: compressionStrategy, + maxTokens: maxTokens, + } +} + +// getOrCreateSession gets or creates a session context +func (cm *contextManager) getOrCreateSession(sessionID string) *sessionContext { + cm.mu.Lock() + defer cm.mu.Unlock() + + if session, exists := cm.sessions[sessionID]; exists { + return session + } + + session := &sessionContext{ + Messages: make([]chat.Message, 0), + } + cm.sessions[sessionID] = session + return session +} + +// AddMessage adds a message to the session context +func (cm *contextManager) AddMessage(ctx context.Context, sessionID string, message chat.Message) error { + logger.Infof(ctx, "[ContextManager][Session-%s] Adding message: role=%s, content_length=%d", + sessionID, message.Role, len(message.Content)) + logger.Debugf(ctx, "Adding message to context, session: %s, role: %s", sessionID, message.Role) + + // Log message content preview + contentPreview := message.Content + if len(contentPreview) > 200 { + contentPreview = contentPreview[:200] + "..." + } + logger.Debugf(ctx, "[ContextManager][Session-%s] Message content preview: %s", sessionID, contentPreview) + + session := cm.getOrCreateSession(sessionID) + session.mu.Lock() + defer session.mu.Unlock() + + beforeCount := len(session.Messages) + session.Messages = append(session.Messages, message) + logger.Debugf(ctx, "[ContextManager][Session-%s] Messages count: %d -> %d", sessionID, beforeCount, len(session.Messages)) + + // Check if compression is needed + tokenCount := cm.compressionStrategy.EstimateTokens(session.Messages) + logger.Debugf(ctx, "[ContextManager][Session-%s] Current token count: %d (max: %d)", + sessionID, tokenCount, cm.maxTokens) + + if tokenCount > cm.maxTokens { + logger.Infof(ctx, "[ContextManager][Session-%s] Context exceeds max tokens (%d > %d), applying compression", + sessionID, tokenCount, cm.maxTokens) + beforeCompressionCount := len(session.Messages) + compressed, err := cm.compressionStrategy.Compress(ctx, session.Messages, cm.maxTokens) + if err != nil { + logger.Errorf(ctx, "[ContextManager][Session-%s] Failed to compress context: %v", sessionID, err) + return fmt.Errorf("failed to compress context: %w", err) + } + session.Messages = compressed + afterTokenCount := cm.compressionStrategy.EstimateTokens(session.Messages) + logger.Infof(ctx, "[ContextManager][Session-%s] Context compressed: %d -> %d messages, %d -> %d tokens", + sessionID, beforeCompressionCount, len(compressed), tokenCount, afterTokenCount) + } + + return nil +} + +// GetContext retrieves the current context for a session +func (cm *contextManager) GetContext(ctx context.Context, sessionID string) ([]chat.Message, error) { + logger.Infof(ctx, "[ContextManager][Session-%s] Getting context", sessionID) + logger.Debugf(ctx, "Getting context for session: %s", sessionID) + + session := cm.getOrCreateSession(sessionID) + session.mu.RLock() + defer session.mu.RUnlock() + + // Return a copy to avoid external modifications + messages := make([]chat.Message, len(session.Messages)) + copy(messages, session.Messages) + + // Calculate token estimate + tokenCount := cm.compressionStrategy.EstimateTokens(messages) + + logger.Infof(ctx, "[ContextManager][Session-%s] Retrieved %d messages (~%d tokens)", + sessionID, len(messages), tokenCount) + logger.Debugf(ctx, "Retrieved %d messages from context", len(messages)) + + // Log message role distribution + roleCount := make(map[string]int) + for _, msg := range messages { + roleCount[msg.Role]++ + } + logger.Debugf(ctx, "[ContextManager][Session-%s] Message distribution: %v", sessionID, roleCount) + + return messages, nil +} + +// ClearContext clears all context for a session +func (cm *contextManager) ClearContext(ctx context.Context, sessionID string) error { + logger.Infof(ctx, "[ContextManager][Session-%s] Clearing context", sessionID) + + cm.mu.Lock() + defer cm.mu.Unlock() + + // Check if session exists before deleting + if session, exists := cm.sessions[sessionID]; exists { + messageCount := len(session.Messages) + logger.Infof(ctx, "[ContextManager][Session-%s] Deleted %d messages", sessionID, messageCount) + } else { + logger.Debugf(ctx, "[ContextManager][Session-%s] Session not found (already cleared or never created)", + sessionID) + } + + delete(cm.sessions, sessionID) + return nil +} + +// GetContextStats returns statistics about the context +func (cm *contextManager) GetContextStats(ctx context.Context, sessionID string) (*interfaces.ContextStats, error) { + session := cm.getOrCreateSession(sessionID) + session.mu.RLock() + defer session.mu.RUnlock() + + tokenCount := cm.compressionStrategy.EstimateTokens(session.Messages) + + stats := &interfaces.ContextStats{ + MessageCount: len(session.Messages), + TokenCount: tokenCount, + IsCompressed: false, // We'd need to track this explicitly for accurate reporting + OriginalMessageCount: len(session.Messages), + } + + logger.Debugf(ctx, "Context stats for session %s: %d messages, ~%d tokens", + sessionID, stats.MessageCount, stats.TokenCount) + + return stats, nil +} + +// SlidingWindowStrategy implements a sliding window compression strategy +// It keeps the most recent N messages and discards older ones +type SlidingWindowStrategy struct { + windowSize int // Number of messages to keep +} + +// NewSlidingWindowStrategy creates a new sliding window strategy +func NewSlidingWindowStrategy(windowSize int) interfaces.CompressionStrategy { + return &SlidingWindowStrategy{ + windowSize: windowSize, + } +} + +// Compress applies sliding window compression +func (s *SlidingWindowStrategy) Compress(ctx context.Context, messages []chat.Message, maxTokens int) ([]chat.Message, error) { + if len(messages) <= s.windowSize { + return messages, nil + } + + // Keep system messages and recent messages + var compressed []chat.Message + var systemMessages []chat.Message + var otherMessages []chat.Message + + // Separate system messages + for _, msg := range messages { + if msg.Role == "system" { + systemMessages = append(systemMessages, msg) + } else { + otherMessages = append(otherMessages, msg) + } + } + + // Keep last N non-system messages + startIdx := 0 + if len(otherMessages) > s.windowSize { + startIdx = len(otherMessages) - s.windowSize + } + + // Combine system messages with recent messages + compressed = append(compressed, systemMessages...) + compressed = append(compressed, otherMessages[startIdx:]...) + + logger.Infof(ctx, "Sliding window compression: %d -> %d messages (kept %d system, %d recent)", + len(messages), len(compressed), len(systemMessages), len(compressed)-len(systemMessages)) + + return compressed, nil +} + +// EstimateTokens provides a rough token count estimation +// Uses approximately 4 characters per token as a heuristic +func (s *SlidingWindowStrategy) EstimateTokens(messages []chat.Message) int { + totalChars := 0 + for _, msg := range messages { + totalChars += len(msg.Content) + } + // Rough estimate: ~4 characters per token + return totalChars / 4 +} + +// SmartCompressionStrategy implements intelligent context compression +// It uses summarization for older messages while keeping recent ones intact +type SmartCompressionStrategy struct { + recentMessageCount int // Number of recent messages to keep intact + chatModel chat.Chat // LLM for summarization + summarizeThreshold int // Minimum messages before summarization +} + +// NewSmartCompressionStrategy creates a new smart compression strategy +func NewSmartCompressionStrategy(recentMessageCount int, chatModel chat.Chat, summarizeThreshold int) interfaces.CompressionStrategy { + return &SmartCompressionStrategy{ + recentMessageCount: recentMessageCount, + chatModel: chatModel, + summarizeThreshold: summarizeThreshold, + } +} + +// Compress applies smart compression with summarization +func (s *SmartCompressionStrategy) Compress(ctx context.Context, messages []chat.Message, maxTokens int) ([]chat.Message, error) { + logger.Infof(ctx, "[ContextManager][Compress] Smart compression started: %d messages, max_tokens=%d", + len(messages), maxTokens) + + if len(messages) <= s.recentMessageCount { + logger.Infof(ctx, "[ContextManager][Compress] No compression needed (%d <= %d)", + len(messages), s.recentMessageCount) + return messages, nil + } + + // Separate messages into system, old, and recent + var systemMessages []chat.Message + var oldMessages []chat.Message + var recentMessages []chat.Message + + for i, msg := range messages { + if msg.Role == "system" { + systemMessages = append(systemMessages, msg) + } else if i < len(messages)-s.recentMessageCount { + oldMessages = append(oldMessages, msg) + } else { + recentMessages = append(recentMessages, msg) + } + } + + logger.Infof(ctx, "[ContextManager][Compress] Message distribution: system=%d, old=%d, recent=%d", + len(systemMessages), len(oldMessages), len(recentMessages)) + + // If we have enough old messages, summarize them + var compressed []chat.Message + if len(oldMessages) >= s.summarizeThreshold && s.chatModel != nil { + logger.Infof(ctx, "[ContextManager][Compress] Summarizing %d old messages (threshold: %d)", + len(oldMessages), s.summarizeThreshold) + + // Build conversation text for summarization + var conversationText strings.Builder + for _, msg := range oldMessages { + conversationText.WriteString(fmt.Sprintf("%s: %s\n", msg.Role, msg.Content)) + } + + // Create summarization prompt + summaryPrompt := []chat.Message{ + { + Role: "system", + Content: "You are a helpful assistant that summarizes conversation history. " + + "Summarize the following conversation concisely while preserving key information and context. " + + "Keep the summary under 200 words.", + }, + { + Role: "user", + Content: conversationText.String(), + }, + } + + logger.Debugf(ctx, "[ContextManager][Compress] Conversation text length: %d chars", + conversationText.Len()) + + // Get summary from LLM + logger.Infof(ctx, "[ContextManager][Compress] Calling LLM for summarization...") + response, err := s.chatModel.Chat(ctx, summaryPrompt, &chat.ChatOptions{ + Temperature: 0.3, + }) + if err != nil { + logger.Warnf(ctx, "[ContextManager][Compress] Failed to summarize old messages: %v, falling back to truncation", + err) + // Fallback to keeping only recent messages + } else { + // Add summary as a system message + summaryContent := fmt.Sprintf("[Previous conversation summary]: %s", response.Content) + compressed = append(compressed, chat.Message{ + Role: "system", + Content: summaryContent, + }) + logger.Infof(ctx, "[ContextManager][Compress] Successfully summarized %d messages into %d chars", + len(oldMessages), len(summaryContent)) + logger.Debugf(ctx, "[ContextManager][Compress] Summary: %s", response.Content) + } + } else { + // Not enough messages to summarize, keep them as is + logger.Infof(ctx, "[ContextManager][Compress] Not enough messages to summarize (%d < %d), keeping as is", + len(oldMessages), s.summarizeThreshold) + compressed = append(compressed, oldMessages...) + } + + // Add system messages, compressed history, and recent messages + result := make([]chat.Message, 0, len(systemMessages)+len(compressed)+len(recentMessages)) + result = append(result, systemMessages...) + result = append(result, compressed...) + result = append(result, recentMessages...) + + beforeTokens := s.EstimateTokens(messages) + afterTokens := s.EstimateTokens(result) + + logger.Infof(ctx, "[ContextManager][Compress] Smart compression completed: %d -> %d messages (system: %d, compressed: %d, recent: %d), tokens: %d -> %d", + len(messages), len(result), len(systemMessages), len(compressed), len(recentMessages), + beforeTokens, afterTokens) + + return result, nil +} + +// EstimateTokens provides a rough token count estimation +func (s *SmartCompressionStrategy) EstimateTokens(messages []chat.Message) int { + totalChars := 0 + for _, msg := range messages { + totalChars += len(msg.Content) + } + // Rough estimate: ~4 characters per token + return totalChars / 4 +} diff --git a/internal/application/service/extract.go b/internal/application/service/extract.go index 06f3db35..2b691320 100644 --- a/internal/application/service/extract.go +++ b/internal/application/service/extract.go @@ -18,7 +18,6 @@ import ( func NewChunkExtractTask(ctx context.Context, client *asynq.Client, tenantID uint, chunkID string, modelID string) error { if strings.ToLower(os.Getenv("NEO4J_ENABLE")) != "true" { - logger.Debugf(ctx, "NOT SUPPORT RETRIEVE GRAPH") return nil } payload, err := json.Marshal(types.ExtractChunkPayload{ diff --git a/internal/application/service/knowledge.go b/internal/application/service/knowledge.go index 414ecc57..886866f0 100644 --- a/internal/application/service/knowledge.go +++ b/internal/application/service/knowledge.go @@ -1545,7 +1545,7 @@ func (s *knowledgeService) UpdateImageInfo(ctx context.Context, knowledgeID stri image := images[0] // Retrieve all chunks with the given parent chunk ID - chunk, err := s.chunkService.GetChunkByID(ctx, knowledgeID, chunkID) + chunk, err := s.chunkService.GetChunkByID(ctx, chunkID) if err != nil { logger.Errorf(ctx, "Failed to get chunk: %v", err) return err diff --git a/internal/application/service/model.go b/internal/application/service/model.go index 48cb7893..8fc09b21 100644 --- a/internal/application/service/model.go +++ b/internal/application/service/model.go @@ -34,9 +34,20 @@ func NewModelService(repo interfaces.ModelRepository, ollamaService *ollama.Olla // For local models, it initiates an asynchronous download process // Remote models are immediately set to active status func (s *modelService) CreateModel(ctx context.Context, model *types.Model) error { - logger.Info(ctx, "Start creating model") logger.Infof(ctx, "Creating model: %s, type: %s, source: %s", model.Name, model.Type, model.Source) + // If this model is set as default, unset other default models of the same type + if model.IsDefault { + logger.Infof(ctx, "Model is set as default, clearing other default models of type: %s", model.Type) + if err := s.clearOtherDefaultModels(ctx, model.TenantID, model.Type, ""); err != nil { + logger.ErrorWithFields(ctx, err, map[string]interface{}{ + "model_type": model.Type, + "tenant_id": model.TenantID, + }) + return err + } + } + // Handle remote models (e.g., OpenAI, Azure) if model.Source == types.ModelSourceRemote { logger.Info(ctx, "Remote model detected, setting status to active") @@ -96,11 +107,13 @@ func (s *modelService) CreateModel(ctx context.Context, model *types.Model) erro // GetModelByID retrieves a model by its ID // Returns an error if the model is not found or is in a non-active state func (s *modelService) GetModelByID(ctx context.Context, id string) (*types.Model, error) { - logger.Info(ctx, "Start getting model by ID") - logger.Infof(ctx, "Getting model with ID: %s", id) + // Check if ID is empty + if id == "" { + logger.Error(ctx, "Model ID is empty") + return nil, errors.New("model ID cannot be empty") + } tenantID := ctx.Value(types.TenantIDContextKey).(uint) - logger.Infof(ctx, "Tenant ID: %d", tenantID) // Fetch model from repository model, err := s.repo.GetByID(ctx, tenantID, id) @@ -165,6 +178,19 @@ func (s *modelService) UpdateModel(ctx context.Context, model *types.Model) erro logger.Info(ctx, "Start updating model") logger.Infof(ctx, "Updating model ID: %s, name: %s", model.ID, model.Name) + // If this model is set as default, unset other default models of the same type + if model.IsDefault { + logger.Infof(ctx, "Model is set as default, clearing other default models of type: %s", model.Type) + if err := s.clearOtherDefaultModels(ctx, model.TenantID, model.Type, model.ID); err != nil { + logger.ErrorWithFields(ctx, err, map[string]interface{}{ + "model_type": model.Type, + "tenant_id": model.TenantID, + "model_id": model.ID, + }) + return err + } + } + // Update model in repository err := s.repo.Update(ctx, model) if err != nil { @@ -204,9 +230,6 @@ func (s *modelService) DeleteModel(ctx context.Context, id string) error { // GetEmbeddingModel retrieves and initializes an embedding model instance // Takes a model ID and returns an Embedder interface implementation func (s *modelService) GetEmbeddingModel(ctx context.Context, modelId string) (embedding.Embedder, error) { - logger.Info(ctx, "Start getting embedding model") - logger.Infof(ctx, "Getting embedding model with ID: %s", modelId) - // Get the model details model, err := s.GetModelByID(ctx, modelId) if err != nil { @@ -216,8 +239,7 @@ func (s *modelService) GetEmbeddingModel(ctx context.Context, modelId string) (e return nil, err } - logger.Info(ctx, "Creating embedder instance") - logger.Infof(ctx, "Model name: %s, source: %s", model.Name, model.Source) + logger.Infof(ctx, "Getting embedding model: %s, source: %s", model.Name, model.Source) // Initialize the embedder with model configuration embedder, err := embedding.NewEmbedder(embedding.Config{ @@ -244,9 +266,6 @@ func (s *modelService) GetEmbeddingModel(ctx context.Context, modelId string) (e // GetRerankModel retrieves and initializes a reranking model instance // Takes a model ID and returns a Reranker interface implementation func (s *modelService) GetRerankModel(ctx context.Context, modelId string) (rerank.Reranker, error) { - logger.Info(ctx, "Start getting rerank model") - logger.Infof(ctx, "Getting rerank model with ID: %s", modelId) - // Get the model details model, err := s.GetModelByID(ctx, modelId) if err != nil { @@ -256,8 +275,7 @@ func (s *modelService) GetRerankModel(ctx context.Context, modelId string) (rera return nil, err } - logger.Info(ctx, "Creating reranker instance") - logger.Infof(ctx, "Model name: %s, source: %s", model.Name, model.Source) + logger.Infof(ctx, "Getting rerank model: %s, source: %s", model.Name, model.Source) // Initialize the reranker with model configuration reranker, err := rerank.NewReranker(&rerank.RerankerConfig{ @@ -282,11 +300,13 @@ func (s *modelService) GetRerankModel(ctx context.Context, modelId string) (rera // GetChatModel retrieves and initializes a chat model instance // Takes a model ID and returns a Chat interface implementation func (s *modelService) GetChatModel(ctx context.Context, modelId string) (chat.Chat, error) { - logger.Info(ctx, "Start getting chat model") - logger.Infof(ctx, "Getting chat model with ID: %s", modelId) + // Check if model ID is empty + if modelId == "" { + logger.Error(ctx, "Model ID is empty") + return nil, errors.New("model ID cannot be empty") + } tenantID := ctx.Value(types.TenantIDContextKey).(uint) - logger.Infof(ctx, "Tenant ID: %d", tenantID) // Get the model directly from repository to avoid status checks model, err := s.repo.GetByID(ctx, tenantID, modelId) @@ -303,8 +323,7 @@ func (s *modelService) GetChatModel(ctx context.Context, modelId string) (chat.C return nil, ErrModelNotFound } - logger.Info(ctx, "Creating chat model instance") - logger.Infof(ctx, "Model name: %s, source: %s", model.Name, model.Source) + logger.Infof(ctx, "Getting chat model: %s, source: %s", model.Name, model.Source) // Initialize the chat model with model configuration chatModel, err := chat.NewChat(&chat.ChatConfig{ @@ -322,6 +341,27 @@ func (s *modelService) GetChatModel(ctx context.Context, modelId string) (chat.C return nil, err } - logger.Info(ctx, "Chat model initialized successfully") return chatModel, nil } + +// clearOtherDefaultModels sets IsDefault to false for all models of the same type +// except the one with the given ID (if excludeID is not empty) +// This ensures only one default model exists per type per tenant +// Uses batch update for better performance +func (s *modelService) clearOtherDefaultModels(ctx context.Context, tenantID uint, modelType types.ModelType, excludeID string) error { + logger.Infof(ctx, "Clearing other default models for type: %s, tenant: %d, exclude: %s", modelType, tenantID, excludeID) + + // Use batch update to clear default status for all models of this type (excluding the specified ID) + err := s.repo.ClearDefaultByType(ctx, tenantID, modelType, excludeID) + if err != nil { + logger.ErrorWithFields(ctx, err, map[string]interface{}{ + "model_type": modelType, + "tenant_id": tenantID, + "exclude_id": excludeID, + }) + return err + } + + logger.Infof(ctx, "Successfully cleared other default models for type: %s", modelType) + return nil +} diff --git a/internal/application/service/session.go b/internal/application/service/session.go index a229ba3b..fed154dc 100644 --- a/internal/application/service/session.go +++ b/internal/application/service/session.go @@ -3,10 +3,12 @@ package service import ( "context" "errors" + "fmt" "strings" chatpipline "github.com/Tencent/WeKnora/internal/application/service/chat_pipline" "github.com/Tencent/WeKnora/internal/config" + "github.com/Tencent/WeKnora/internal/event" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/models/chat" "github.com/Tencent/WeKnora/internal/tracing" @@ -23,7 +25,10 @@ type sessionService struct { messageRepo interfaces.MessageRepository // Repository for message data knowledgeBaseService interfaces.KnowledgeBaseService // Service for knowledge base operations modelService interfaces.ModelService // Service for model operations + tenantService interfaces.TenantService // Service for tenant operations eventManager *chatpipline.EventManager // Event manager for chat pipeline + agentService interfaces.AgentService // Service for agent operations + contextManager interfaces.ContextManager // LLM context manager (separate from message storage) } // NewSessionService creates a new session service instance with all required dependencies @@ -32,15 +37,25 @@ func NewSessionService(cfg *config.Config, messageRepo interfaces.MessageRepository, knowledgeBaseService interfaces.KnowledgeBaseService, modelService interfaces.ModelService, + tenantService interfaces.TenantService, eventManager *chatpipline.EventManager, + agentService interfaces.AgentService, ) interfaces.SessionService { + // Create default context manager with sliding window strategy + // Default: 8192 tokens max, keep last 20 messages + defaultStrategy := NewSlidingWindowStrategy(20) + contextManager := NewContextManager(defaultStrategy, 8192) + return &sessionService{ cfg: cfg, sessionRepo: sessionRepo, messageRepo: messageRepo, knowledgeBaseService: knowledgeBaseService, modelService: modelService, + tenantService: tenantService, eventManager: eventManager, + agentService: agentService, + contextManager: contextManager, } } @@ -515,3 +530,192 @@ func (s *sessionService) SearchKnowledge(ctx context.Context, logger.Infof(ctx, "Knowledge base search completed, found %d results", len(chatManage.MergeResult)) return chatManage.MergeResult, nil } + +// AgentQA performs agent-based question answering with conversation history and streaming support +func (s *sessionService) AgentQA(ctx context.Context, session *types.Session, query string, assistantMessageID string, eventBus *event.EventBus) ( + []*types.SearchResult, error, +) { + sessionID := session.ID + tenantID := ctx.Value(types.TenantIDContextKey).(uint) + logger.Infof(ctx, "Start agent-based question answering, session ID: %s, tenant ID: %d, query: %s", sessionID, tenantID, query) + + // Get effective agent configuration (session > tenant) + var agentConfig *types.AgentConfig + + // Fall back to tenant-level agent config (global default) + tenantInfo := ctx.Value(types.TenantInfoContextKey).(*types.Tenant) + if tenantInfo.AgentConfig != nil && tenantInfo.AgentConfig.Enabled { + logger.Infof(ctx, "Using tenant-level agent config for tenant: %d", tenantInfo.ID) + agentConfig = tenantInfo.AgentConfig + } + + // Check if agent is enabled (either from session or tenant) + if agentConfig == nil || !agentConfig.Enabled { + logger.Warnf(ctx, "Agent not enabled for session: %s (neither session nor tenant has agent config)", sessionID) + return nil, errors.New("agent not enabled for this session") + } + + // Set knowledge bases for agent if not already configured + // Priority: AgentConfig.KnowledgeBases > Session.KnowledgeBaseID > All tenant knowledge bases + if len(agentConfig.KnowledgeBases) == 0 { + if session.KnowledgeBaseID != "" { + // Use session's knowledge base as fallback + agentConfig.KnowledgeBases = []string{session.KnowledgeBaseID} + logger.Infof(ctx, "Using session's knowledge base for agent: %s", session.KnowledgeBaseID) + } else { + // Default to all knowledge bases under the tenant + logger.Infof(ctx, "No knowledge bases specified, fetching all knowledge bases for tenant") + allKBs, err := s.knowledgeBaseService.ListKnowledgeBases(ctx) + if err != nil { + logger.Errorf(ctx, "Failed to list knowledge bases for tenant: %v", err) + return nil, fmt.Errorf("failed to list knowledge bases: %w", err) + } + + if len(allKBs) == 0 { + logger.Warnf(ctx, "No knowledge bases available for agent session: %s", sessionID) + return nil, errors.New("no knowledge bases available for agent") + } + + // Extract knowledge base IDs + agentConfig.KnowledgeBases = make([]string, len(allKBs)) + for i, kb := range allKBs { + agentConfig.KnowledgeBases[i] = kb.ID + } + logger.Infof(ctx, "Agent defaulting to all %d knowledge base(s) in tenant: %v", + len(agentConfig.KnowledgeBases), agentConfig.KnowledgeBases) + } + } else { + logger.Infof(ctx, "Agent configured with %d knowledge base(s): %v", len(agentConfig.KnowledgeBases), agentConfig.KnowledgeBases) + } + + // Set ThinkingModelID from session's SummaryModelID if not already set + if agentConfig.ThinkingModelID == "" && session.SummaryModelID != "" { + agentConfig.ThinkingModelID = session.SummaryModelID + logger.Infof(ctx, "Using session's SummaryModelID as ThinkingModelID: %s", session.SummaryModelID) + } + + // Create agent engine with EventBus + logger.Info(ctx, "Creating agent engine") + engine, err := s.agentService.CreateAgentEngine(ctx, agentConfig, eventBus) + if err != nil { + logger.Errorf(ctx, "Failed to create agent engine: %v", err) + return nil, err + } + + // Get LLM context from context manager + llmContext, err := s.getContextForSession(ctx, session, sessionID) + if err != nil { + logger.Warnf(ctx, "Failed to get LLM context: %v, continuing without history", err) + llmContext = []chat.Message{} + } + logger.Infof(ctx, "Loaded %d messages from LLM context manager", len(llmContext)) + + // Execute agent with streaming (asynchronously) + // Events will be emitted to EventBus and handled by the Handler layer + logger.Info(ctx, "Executing agent with streaming") + go func() { + if _, err := engine.Execute(ctx, sessionID, query, llmContext); err != nil { + logger.Errorf(ctx, "Agent execution failed: %v", err) + // Emit error event to the EventBus used by this agent + eventBus.Emit(ctx, event.Event{ + Type: event.EventError, + SessionID: sessionID, + Data: event.ErrorData{ + Error: err.Error(), + Stage: "agent_execution", + SessionID: sessionID, + }, + }) + } + }() + + // Return empty - events will be handled by Handler via EventBus subscription + return nil, nil +} + +// getContextForSession retrieves LLM context for a session +// Uses context manager which handles token limits and compression automatically +// This is separate from the message storage/conversation history +func (s *sessionService) getContextForSession(ctx context.Context, session *types.Session, sessionID string) ([]chat.Message, error) { + // Check if session has custom context configuration + var contextManager interfaces.ContextManager + + if session.ContextConfig != nil && session.ContextConfig.Enabled { + // Create custom context manager based on session configuration + logger.Infof(ctx, "Using custom context config for session %s: strategy=%s, max_tokens=%d, recent_count=%d", + sessionID, session.ContextConfig.CompressionStrategy, session.ContextConfig.MaxTokens, session.ContextConfig.RecentMessageCount) + + var strategy interfaces.CompressionStrategy + switch session.ContextConfig.CompressionStrategy { + case types.ContextCompressionSlidingWindow: + strategy = NewSlidingWindowStrategy(session.ContextConfig.RecentMessageCount) + case types.ContextCompressionSmart: + // For smart compression, we need the chat model + chatModel, err := s.modelService.GetChatModel(ctx, session.SummaryModelID) + if err != nil { + logger.Warnf(ctx, "Failed to get chat model for smart compression, falling back to sliding window: %v", err) + strategy = NewSlidingWindowStrategy(session.ContextConfig.RecentMessageCount) + } else { + strategy = NewSmartCompressionStrategy(session.ContextConfig.RecentMessageCount, chatModel, 5) + } + default: + logger.Warnf(ctx, "Unknown compression strategy %s, using sliding window", session.ContextConfig.CompressionStrategy) + strategy = NewSlidingWindowStrategy(session.ContextConfig.RecentMessageCount) + } + + contextManager = NewContextManager(strategy, session.ContextConfig.MaxTokens) + } else { + // Use default context manager + logger.Debugf(ctx, "Using default context manager for session %s", sessionID) + contextManager = s.contextManager + } + + // Get context from the context manager + history, err := contextManager.GetContext(ctx, sessionID) + if err != nil { + return nil, fmt.Errorf("failed to get context: %w", err) + } + + // Log context statistics + stats, _ := contextManager.GetContextStats(ctx, sessionID) + if stats != nil { + logger.Infof(ctx, "LLM context stats for session %s: messages=%d, tokens=~%d, compressed=%v", + sessionID, stats.MessageCount, stats.TokenCount, stats.IsCompressed) + } + + return history, nil +} + +// AddMessageToContext adds a message to the LLM context +// This should be called after saving a message to the database +// The context manager handles token limits and compression automatically +func (s *sessionService) AddMessageToContext(ctx context.Context, session *types.Session, sessionID string, message chat.Message) error { + // Determine which context manager to use + var contextManager interfaces.ContextManager + + if session.ContextConfig != nil && session.ContextConfig.Enabled { + // Create custom context manager based on session configuration + var strategy interfaces.CompressionStrategy + switch session.ContextConfig.CompressionStrategy { + case types.ContextCompressionSlidingWindow: + strategy = NewSlidingWindowStrategy(session.ContextConfig.RecentMessageCount) + case types.ContextCompressionSmart: + chatModel, err := s.modelService.GetChatModel(ctx, session.SummaryModelID) + if err != nil { + strategy = NewSlidingWindowStrategy(session.ContextConfig.RecentMessageCount) + } else { + strategy = NewSmartCompressionStrategy(session.ContextConfig.RecentMessageCount, chatModel, 5) + } + default: + strategy = NewSlidingWindowStrategy(session.ContextConfig.RecentMessageCount) + } + contextManager = NewContextManager(strategy, session.ContextConfig.MaxTokens) + } else { + contextManager = s.contextManager + } + + // Add message to context + return contextManager.AddMessage(ctx, sessionID, message) +} + +// processAgentEvents is no longer needed - events are handled directly by Handler layer via EventBus subscription diff --git a/internal/config/config.go b/internal/config/config.go index 80728135..46284ea6 100644 --- a/internal/config/config.go +++ b/internal/config/config.go @@ -23,6 +23,7 @@ type Config struct { DocReader *DocReaderConfig `yaml:"docreader" json:"docreader"` StreamManager *StreamManagerConfig `yaml:"stream_manager" json:"stream_manager"` ExtractManager *ExtractManagerConfig `yaml:"extract" json:"extract"` + Agent *AgentGlobalConfig `yaml:"agent" json:"agent"` } type DocReaderConfig struct { @@ -188,3 +189,12 @@ func LoadConfig() (*Config, error) { fmt.Printf("Using configuration file: %s\n", viper.ConfigFileUsed()) return &cfg, nil } + +// AgentGlobalConfig represents the global agent configuration +type AgentGlobalConfig struct { + Enabled bool `yaml:"enabled" json:"enabled"` + DefaultMaxIterations int `yaml:"default_max_iterations" json:"default_max_iterations"` + DefaultTemperature float64 `yaml:"default_temperature" json:"default_temperature"` + ReflectionEnabled bool `yaml:"reflection_enabled" json:"reflection_enabled"` + DefaultTools []string `yaml:"default_tools" json:"default_tools"` +} diff --git a/internal/container/container.go b/internal/container/container.go index 4a686e66..b43786f1 100644 --- a/internal/container/container.go +++ b/internal/container/container.go @@ -30,6 +30,7 @@ import ( "github.com/Tencent/WeKnora/internal/application/service/file" "github.com/Tencent/WeKnora/internal/application/service/retriever" "github.com/Tencent/WeKnora/internal/config" + "github.com/Tencent/WeKnora/internal/event" "github.com/Tencent/WeKnora/internal/handler" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/models/embedding" @@ -89,8 +90,6 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(service.NewTenantService)) must(container.Provide(service.NewKnowledgeBaseService)) must(container.Provide(service.NewKnowledgeService)) - must(container.Provide(service.NewSessionService)) - must(container.Provide(service.NewMessageService)) must(container.Provide(service.NewChunkService)) must(container.Provide(embedding.NewBatchEmbedder)) must(container.Provide(service.NewModelService)) @@ -98,6 +97,14 @@ func BuildContainer(container *dig.Container) *dig.Container { must(container.Provide(service.NewEvaluationService)) must(container.Provide(service.NewUserService)) must(container.Provide(service.NewChunkExtractService)) + must(container.Provide(service.NewMessageService)) + + // Agent service layer (requires event bus) + must(container.Provide(event.NewEventBus)) + must(container.Provide(service.NewAgentService)) + + // Session service (depends on agent service) + must(container.Provide(service.NewSessionService)) // Chat pipeline components for processing chat requests must(container.Provide(chatpipline.NewEventManager)) diff --git a/internal/errors/errors.go b/internal/errors/errors.go index c682e4a8..b43225c8 100644 --- a/internal/errors/errors.go +++ b/internal/errors/errors.go @@ -30,6 +30,12 @@ const ( ErrTenantNameRequired ErrorCode = 2003 ErrTenantInvalidStatus ErrorCode = 2004 + // Agent related error codes (2100-2199) + ErrAgentMissingThinkingModel ErrorCode = 2100 + ErrAgentMissingAllowedTools ErrorCode = 2101 + ErrAgentInvalidMaxIterations ErrorCode = 2102 + ErrAgentInvalidTemperature ErrorCode = 2103 + // Add more error codes here ) @@ -145,6 +151,39 @@ func NewTenantInactiveError() *AppError { } } +// Agent related errors +func NewAgentMissingThinkingModelError() *AppError { + return &AppError{ + Code: ErrAgentMissingThinkingModel, + Message: "启用Agent模式前,请先选择思考模型", + HTTPCode: http.StatusBadRequest, + } +} + +func NewAgentMissingAllowedToolsError() *AppError { + return &AppError{ + Code: ErrAgentMissingAllowedTools, + Message: "至少需要选择一个允许的工具", + HTTPCode: http.StatusBadRequest, + } +} + +func NewAgentInvalidMaxIterationsError() *AppError { + return &AppError{ + Code: ErrAgentInvalidMaxIterations, + Message: "最大迭代次数必须在1-20之间", + HTTPCode: http.StatusBadRequest, + } +} + +func NewAgentInvalidTemperatureError() *AppError { + return &AppError{ + Code: ErrAgentInvalidTemperature, + Message: "温度参数必须在0-2之间", + HTTPCode: http.StatusBadRequest, + } +} + // IsAppError checks if the error is an AppError type func IsAppError(err error) (*AppError, bool) { appErr, ok := err.(*AppError) diff --git a/internal/event/SUMMARY.md b/internal/event/SUMMARY.md new file mode 100644 index 00000000..1f7ee57a --- /dev/null +++ b/internal/event/SUMMARY.md @@ -0,0 +1,238 @@ +# WeKnora 事件系统总结 + +## 概述 + +已成功为 WeKnora 项目创建了一个完整的事件发送和监听机制,支持对用户查询处理流程中的各个步骤进行事件处理。 + +## 核心功能 + +### ✅ 已实现的功能 + +1. **事件总线 (EventBus)** + - `Emit(ctx, event)` - 发送事件 + - `On(eventType, handler)` - 注册事件监听器 + - `Off(eventType)` - 移除事件监听器 + - `EmitAndWait(ctx, event)` - 发送事件并等待所有处理器完成 + - 同步/异步两种模式 + +2. **事件类型** + - 查询处理事件(接收、验证、预处理、改写) + - 检索事件(开始、向量检索、关键词检索、实体检索、完成) + - 排序事件(开始、完成) + - 合并事件(开始、完成) + - 聊天生成事件(开始、完成、流式输出) + - 错误事件 + +3. **事件数据结构** + - `QueryData` - 查询数据 + - `RetrievalData` - 检索数据 + - `RerankData` - 排序数据 + - `MergeData` - 合并数据 + - `ChatData` - 聊天数据 + - `ErrorData` - 错误数据 + +4. **中间件支持** + - `WithLogging()` - 日志记录中间件 + - `WithTiming()` - 计时中间件 + - `WithRecovery()` - 错误恢复中间件 + - `Chain()` - 中间件组合 + +5. **全局事件总线** + - 单例模式的全局事件总线 + - 全局便捷函数(`On`, `Emit`, `EmitAndWait`等) + +6. **示例和测试** + - 完整的单元测试 + - 性能基准测试 + - 完整的使用示例 + - 实际场景演示 + +## 文件结构 + +``` +internal/event/ +├── event.go # 核心事件总线实现 +├── event_data.go # 事件数据结构定义 +├── middleware.go # 中间件实现 +├── global.go # 全局事件总线 +├── integration_example.go # 集成示例(监控、分析处理器) +├── example_test.go # 测试和示例 +├── demo/ +│ └── main.go # 完整的 RAG 流程演示 +├── README.md # 详细文档 +├── usage_example.md # 使用示例文档 +└── SUMMARY.md # 本文档 +``` + +## 性能指标 + +- **事件发送性能**: ~9 纳秒/次 (基准测试) +- **并发安全**: 使用 `sync.RWMutex` 保证线程安全 +- **内存开销**: 极低,只存储事件处理器函数引用 + +## 使用场景 + +### 1. 监控和指标收集 + +```go +bus.On(event.EventRetrievalComplete, func(ctx context.Context, e event.Event) error { + data := e.Data.(event.RetrievalData) + // 发送到 Prometheus 或其他监控系统 + metricsCollector.RecordRetrievalDuration(data.Duration) + return nil +}) +``` + +### 2. 日志记录 + +```go +bus.On(event.EventQueryRewritten, func(ctx context.Context, e event.Event) error { + data := e.Data.(event.QueryData) + logger.Infof(ctx, "Query rewritten: %s -> %s", + data.OriginalQuery, data.RewrittenQuery) + return nil +}) +``` + +### 3. 用户行为分析 + +```go +bus.On(event.EventQueryReceived, func(ctx context.Context, e event.Event) error { + data := e.Data.(event.QueryData) + // 发送到分析平台 + analytics.TrackQuery(data.UserID, data.OriginalQuery) + return nil +}) +``` + +### 4. 错误追踪 + +```go +bus.On(event.EventError, func(ctx context.Context, e event.Event) error { + data := e.Data.(event.ErrorData) + // 发送到错误追踪系统 + sentry.CaptureException(data.Error) + return nil +}) +``` + +## 集成方式 + +### 步骤 1: 初始化事件系统 + +在应用启动时(如 `main.go` 或 `container.go`): + +```go +import "github.com/Tencent/WeKnora/internal/event" + +func Initialize() { + // 获取全局事件总线 + bus := event.GetGlobalEventBus() + + // 设置监控和分析 + event.NewMonitoringHandler(bus) + event.NewAnalyticsHandler(bus) +} +``` + +### 步骤 2: 在各个处理阶段发送事件 + +在查询处理流程的各个插件中添加事件发送: + +```go +// 在 search.go 中 +event.Emit(ctx, event.NewEvent(event.EventRetrievalStart, event.RetrievalData{ + Query: chatManage.ProcessedQuery, + KnowledgeBaseID: chatManage.KnowledgeBaseID, + TopK: chatManage.EmbeddingTopK, +}).WithSessionID(chatManage.SessionID)) + +// 在 rerank.go 中 +event.Emit(ctx, event.NewEvent(event.EventRerankComplete, event.RerankData{ + Query: chatManage.ProcessedQuery, + InputCount: len(chatManage.SearchResult), + OutputCount: len(rerankResults), + Duration: time.Since(startTime).Milliseconds(), +}).WithSessionID(chatManage.SessionID)) +``` + +### 步骤 3: 注册自定义事件处理器 + +根据需要注册自定义处理器: + +```go +event.On(event.EventQueryRewritten, func(ctx context.Context, e event.Event) error { + // 自定义处理逻辑 + return nil +}) +``` + +## 优势 + +1. **低耦合**: 事件发送者和监听者完全解耦,便于维护和扩展 +2. **高性能**: 极低的性能开销(~9纳秒/次) +3. **灵活性**: 支持同步/异步、单个/多个监听器 +4. **可扩展**: 易于添加新的事件类型和处理器 +5. **类型安全**: 预定义的事件数据结构 +6. **中间件支持**: 便于添加横切关注点(日志、计时、错误处理等) +7. **测试友好**: 易于在测试中验证事件行为 + +## 测试结果 + +✅ 所有单元测试通过 +✅ 性能测试通过(~9纳秒/次) +✅ 异步处理测试通过 +✅ 多处理器测试通过 +✅ 完整流程演示成功 + +## 后续建议 + +### 可选的增强功能 + +1. **事件持久化**: 将关键事件保存到数据库或消息队列 +2. **事件重放**: 支持事件重放以进行调试或分析 +3. **事件过滤**: 支持更复杂的事件过滤和路由 +4. **优先级队列**: 支持事件优先级处理 +5. **分布式事件**: 通过消息队列支持跨服务事件 + +### 集成建议 + +1. **监控集成**: 集成 Prometheus 进行指标收集 +2. **日志集成**: 统一的结构化日志记录 +3. **追踪集成**: 与现有的 tracing 系统集成 +4. **告警集成**: 基于事件的告警机制 + +## 示例输出 + +运行 `go run ./internal/event/demo/main.go` 可以看到完整的 RAG 流程事件输出: + +``` +Step 1: Query Received +[MONITOR] Query received - Session: session-xxx, Query: 什么是RAG技术? +[ANALYTICS] Query tracked - User: user-123, Session: session-xxx + +Step 2: Query Rewriting +[MONITOR] Query rewrite started +[MONITOR] Query rewritten - Original: 什么是RAG技术?, Rewritten: 检索增强生成技术... +[CUSTOM] Query Transformation: ... + +Step 3: Vector Retrieval +[MONITOR] Retrieval started - Type: vector, TopK: 20 +[MONITOR] Retrieval completed - Results: 18, Duration: 301ms +[CUSTOM] Retrieval Efficiency: Rate: 90.00% + +Step 4: Result Reranking +[MONITOR] Rerank started - Input: 18 +[MONITOR] Rerank completed - Output: 5, Duration: 201ms +[CUSTOM] Rerank Statistics: Reduction: 72.22% + +Step 5: Chat Completion +[MONITOR] Chat generation started +[MONITOR] Chat generation completed - Tokens: 256, Duration: 801ms +[ANALYTICS] Chat metrics - Model: gpt-4, Tokens: 256 +``` + +## 总结 + +事件系统已完全实现并经过测试验证,可以立即集成到 WeKnora 项目中,用于监控、日志记录、分析和调试查询处理流程的各个阶段。系统设计简洁、性能优异、易于使用和扩展。 + diff --git a/internal/event/event.go b/internal/event/event.go new file mode 100644 index 00000000..9b1fa655 --- /dev/null +++ b/internal/event/event.go @@ -0,0 +1,224 @@ +package event + +import ( + "context" + "fmt" + "sync" + + "github.com/google/uuid" +) + +// EventType represents the type of event in the system +type EventType string + +const ( + // Query processing events + EventQueryReceived EventType = "query.received" // 用户查询到达 + EventQueryValidated EventType = "query.validated" // 查询验证完成 + EventQueryPreprocess EventType = "query.preprocess" // 查询预处理 + EventQueryRewrite EventType = "query.rewrite" // 查询改写 + EventQueryRewritten EventType = "query.rewritten" // 查询改写完成 + + // Retrieval events + EventRetrievalStart EventType = "retrieval.start" // 检索开始 + EventRetrievalVector EventType = "retrieval.vector" // 向量检索 + EventRetrievalKeyword EventType = "retrieval.keyword" // 关键词检索 + EventRetrievalEntity EventType = "retrieval.entity" // 实体检索 + EventRetrievalComplete EventType = "retrieval.complete" // 检索完成 + + // Rerank events + EventRerankStart EventType = "rerank.start" // 排序开始 + EventRerankComplete EventType = "rerank.complete" // 排序完成 + + // Merge events + EventMergeStart EventType = "merge.start" // 合并开始 + EventMergeComplete EventType = "merge.complete" // 合并完成 + + // Chat completion events + EventChatStart EventType = "chat.start" // 聊天生成开始 + EventChatComplete EventType = "chat.complete" // 聊天生成完成 + EventChatStream EventType = "chat.stream" // 聊天流式输出 + + // Agent events + EventAgentQuery EventType = "agent.query" // Agent 查询开始 + EventAgentPlan EventType = "agent.plan" // Agent 计划生成 + EventAgentStep EventType = "agent.step" // Agent 步骤执行 + EventAgentTool EventType = "agent.tool" // Agent 工具调用 + EventAgentComplete EventType = "agent.complete" // Agent 完成 + + // Agent streaming events (for real-time feedback) + EventAgentThought EventType = "thought" // Agent 思考过程 + EventAgentToolCall EventType = "tool_call" // 工具调用通知 + EventAgentToolResult EventType = "tool_result" // 工具结果 + EventAgentReflection EventType = "reflection" // Agent 反思 + EventAgentReferences EventType = "references" // 知识引用 + EventAgentFinalAnswer EventType = "final_answer" // 最终答案 + + // Error events + EventError EventType = "error" // 错误事件 +) + +// Event represents an event in the system +type Event struct { + ID string // 事件ID (自动生成UUID,用于流式更新追踪) + Type EventType // 事件类型 + SessionID string // 会话ID + Data interface{} // 事件数据 + Metadata map[string]interface{} // 事件元数据 + RequestID string // 请求ID +} + +// EventHandler is a function that handles events +type EventHandler func(ctx context.Context, event Event) error + +// EventBus manages event publishing and subscription +type EventBus struct { + mu sync.RWMutex + handlers map[EventType][]EventHandler + asyncMode bool // 是否异步处理事件 +} + +// NewEventBus creates a new EventBus instance +func NewEventBus() *EventBus { + return &EventBus{ + handlers: make(map[EventType][]EventHandler), + asyncMode: false, + } +} + +// NewAsyncEventBus creates a new EventBus with async mode enabled +func NewAsyncEventBus() *EventBus { + return &EventBus{ + handlers: make(map[EventType][]EventHandler), + asyncMode: true, + } +} + +// On registers an event handler for a specific event type +// Multiple handlers can be registered for the same event type +func (eb *EventBus) On(eventType EventType, handler EventHandler) { + eb.mu.Lock() + defer eb.mu.Unlock() + + eb.handlers[eventType] = append(eb.handlers[eventType], handler) +} + +// Off removes all handlers for a specific event type +func (eb *EventBus) Off(eventType EventType) { + eb.mu.Lock() + defer eb.mu.Unlock() + + delete(eb.handlers, eventType) +} + +// Emit publishes an event to all registered handlers +// Returns error if any handler fails (in sync mode) +// Automatically generates an ID for the event if not provided (from source) +func (eb *EventBus) Emit(ctx context.Context, event Event) error { + // Auto-generate ID if not provided (from source) + if event.ID == "" { + event.ID = uuid.New().String() + } + + eb.mu.RLock() + handlers, exists := eb.handlers[event.Type] + eb.mu.RUnlock() + + if !exists || len(handlers) == 0 { + // No handlers registered for this event type + return nil + } + + if eb.asyncMode { + // Async mode: fire and forget + for _, handler := range handlers { + h := handler // capture loop variable + go func() { + _ = h(ctx, event) + }() + } + return nil + } + + // Sync mode: execute handlers sequentially + for _, handler := range handlers { + if err := handler(ctx, event); err != nil { + return fmt.Errorf("event handler failed for %s: %w", event.Type, err) + } + } + + return nil +} + +// EmitAndWait publishes an event and waits for all handlers to complete +// This method works in both sync and async mode +// Automatically generates an ID for the event if not provided (from source) +func (eb *EventBus) EmitAndWait(ctx context.Context, event Event) error { + // Auto-generate ID if not provided (from source) + if event.ID == "" { + event.ID = uuid.New().String() + } + + eb.mu.RLock() + handlers, exists := eb.handlers[event.Type] + eb.mu.RUnlock() + + if !exists || len(handlers) == 0 { + return nil + } + + var wg sync.WaitGroup + errChan := make(chan error, len(handlers)) + + for _, handler := range handlers { + wg.Add(1) + h := handler // capture loop variable + + go func() { + defer wg.Done() + if err := h(ctx, event); err != nil { + errChan <- err + } + }() + } + + wg.Wait() + close(errChan) + + // Collect errors + for err := range errChan { + if err != nil { + return fmt.Errorf("event handler failed for %s: %w", event.Type, err) + } + } + + return nil +} + +// HasHandlers checks if there are any handlers registered for an event type +func (eb *EventBus) HasHandlers(eventType EventType) bool { + eb.mu.RLock() + defer eb.mu.RUnlock() + + handlers, exists := eb.handlers[eventType] + return exists && len(handlers) > 0 +} + +// GetHandlerCount returns the number of handlers for a specific event type +func (eb *EventBus) GetHandlerCount(eventType EventType) int { + eb.mu.RLock() + defer eb.mu.RUnlock() + + if handlers, exists := eb.handlers[eventType]; exists { + return len(handlers) + } + return 0 +} + +// Clear removes all event handlers +func (eb *EventBus) Clear() { + eb.mu.Lock() + defer eb.mu.Unlock() + + eb.handlers = make(map[EventType][]EventHandler) +} diff --git a/internal/event/event_data.go b/internal/event/event_data.go new file mode 100644 index 00000000..36ab645b --- /dev/null +++ b/internal/event/event_data.go @@ -0,0 +1,197 @@ +package event + +// EventData contains common event data structures for different stages + +// QueryData represents query-related event data +type QueryData struct { + OriginalQuery string `json:"original_query"` + ProcessedQuery string `json:"processed_query,omitempty"` + RewrittenQuery string `json:"rewritten_query,omitempty"` + SessionID string `json:"session_id"` + UserID string `json:"user_id,omitempty"` + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// RetrievalData represents retrieval event data +type RetrievalData struct { + Query string `json:"query"` + KnowledgeBaseID string `json:"knowledge_base_id"` + TopK int `json:"top_k"` + Threshold float64 `json:"threshold"` + RetrievalType string `json:"retrieval_type"` // vector, keyword, entity + ResultCount int `json:"result_count"` + Results interface{} `json:"results,omitempty"` + Duration int64 `json:"duration_ms,omitempty"` // 检索耗时(毫秒) + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// RerankData represents reranking event data +type RerankData struct { + Query string `json:"query"` + InputCount int `json:"input_count"` // 输入的候选数量 + OutputCount int `json:"output_count"` // 输出的结果数量 + ModelID string `json:"model_id"` + Threshold float64 `json:"threshold"` + Results interface{} `json:"results,omitempty"` + Duration int64 `json:"duration_ms,omitempty"` // 排序耗时(毫秒) + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// MergeData represents merge event data +type MergeData struct { + InputCount int `json:"input_count"` + OutputCount int `json:"output_count"` + MergeType string `json:"merge_type"` // dedup, fusion, etc. + Results interface{} `json:"results,omitempty"` + Duration int64 `json:"duration_ms,omitempty"` + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// ChatData represents chat completion event data +type ChatData struct { + Query string `json:"query"` + ModelID string `json:"model_id"` + Response string `json:"response,omitempty"` + StreamChunk string `json:"stream_chunk,omitempty"` + TokenCount int `json:"token_count,omitempty"` + Duration int64 `json:"duration_ms,omitempty"` + IsStream bool `json:"is_stream"` + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// ErrorData represents error event data +type ErrorData struct { + Error string `json:"error"` + ErrorCode string `json:"error_code,omitempty"` + Stage string `json:"stage"` // 错误发生的阶段 + SessionID string `json:"session_id"` + Query string `json:"query,omitempty"` + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// NewEvent creates a new Event with metadata +func NewEvent(eventType EventType, data interface{}) Event { + return Event{ + Type: eventType, + Data: data, + Metadata: make(map[string]interface{}), + } +} + +// WithSessionID sets the session ID for the event +func (e Event) WithSessionID(sessionID string) Event { + e.SessionID = sessionID + return e +} + +// WithRequestID sets the request ID for the event +func (e Event) WithRequestID(requestID string) Event { + e.RequestID = requestID + return e +} + +// WithMetadata adds metadata to the event +func (e Event) WithMetadata(key string, value interface{}) Event { + if e.Metadata == nil { + e.Metadata = make(map[string]interface{}) + } + e.Metadata[key] = value + return e +} + +// AgentPlanData represents agent planning event data +type AgentPlanData struct { + Query string `json:"query"` + Plan []string `json:"plan"` // Step descriptions + Duration int64 `json:"duration_ms,omitempty"` +} + +// AgentStepData represents agent step event data +type AgentStepData struct { + Iteration int `json:"iteration"` + Thought string `json:"thought"` + ToolCalls interface{} `json:"tool_calls"` // []types.ToolCall + Duration int64 `json:"duration_ms"` +} + +// AgentActionData represents agent tool execution event data +type AgentActionData struct { + Iteration int `json:"iteration"` + ToolName string `json:"tool_name"` + ToolInput map[string]interface{} `json:"tool_input"` + ToolOutput string `json:"tool_output"` + Success bool `json:"success"` + Error string `json:"error,omitempty"` + Duration int64 `json:"duration_ms"` +} + +// AgentQueryData represents agent query event data +type AgentQueryData struct { + SessionID string `json:"session_id"` + Query string `json:"query"` + RequestID string `json:"request_id,omitempty"` + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// AgentCompleteData represents agent completion event data +type AgentCompleteData struct { + SessionID string `json:"session_id"` + TotalSteps int `json:"total_steps"` + FinalAnswer string `json:"final_answer"` + KnowledgeRefs []interface{} `json:"knowledge_refs,omitempty"` // []*types.SearchResult + AgentSteps interface{} `json:"agent_steps,omitempty"` // []types.AgentStep - detailed execution steps + TotalDuration int64 `json:"total_duration_ms"` + MessageID string `json:"message_id,omitempty"` // Assistant message ID + RequestID string `json:"request_id,omitempty"` + Extra map[string]interface{} `json:"extra,omitempty"` +} + +// === Streaming Event Data Structures === +// These are used for real-time streaming feedback to clients + +// AgentThoughtData represents agent thought streaming data +type AgentThoughtData struct { + Content string `json:"content"` + Iteration int `json:"iteration"` + Done bool `json:"done"` +} + +// AgentToolCallData represents agent tool call notification data +type AgentToolCallData struct { + ToolCallID string `json:"tool_call_id"` // Tool call ID for tracking + ToolName string `json:"tool_name"` + Arguments map[string]any `json:"arguments,omitempty"` + Iteration int `json:"iteration"` +} + +// AgentToolResultData represents agent tool execution result data +type AgentToolResultData struct { + ToolCallID string `json:"tool_call_id"` // Tool call ID for tracking + ToolName string `json:"tool_name"` + Output string `json:"output"` + Error string `json:"error,omitempty"` + Success bool `json:"success"` + Duration int64 `json:"duration_ms,omitempty"` + Iteration int `json:"iteration"` + Data map[string]interface{} `json:"data,omitempty"` // Structured data from tool result (e.g., display_type, formatted results) +} + +// AgentReferencesData represents knowledge references data +type AgentReferencesData struct { + References interface{} `json:"references"` // []*types.SearchResult + Iteration int `json:"iteration"` +} + +// AgentFinalAnswerData represents final answer streaming data +type AgentFinalAnswerData struct { + Content string `json:"content"` + Done bool `json:"done"` +} + +// AgentReflectionData represents agent reflection data +type AgentReflectionData struct { + ToolCallID string `json:"tool_call_id"` // Tool call ID for tracking + Content string `json:"content"` + Iteration int `json:"iteration"` + Done bool `json:"done"` // Whether streaming is complete +} diff --git a/internal/event/example_test.go b/internal/event/example_test.go new file mode 100644 index 00000000..fea5021e --- /dev/null +++ b/internal/event/example_test.go @@ -0,0 +1,247 @@ +package event + +import ( + "context" + "fmt" + "testing" + "time" +) + +// Example: Basic usage of event system +func ExampleEventBus_basic() { + ctx := context.Background() + bus := NewEventBus() + + // Register a handler + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + fmt.Printf("Query received: %v\n", event.Data) + return nil + }) + + // Emit an event + event := NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "What is RAG?", + SessionID: "session-123", + }) + + _ = bus.Emit(ctx, event) + // Output: Query received: {What is RAG? session-123 map[]} +} + +// Example: Using middleware +func ExampleEventBus_middleware() { + ctx := context.Background() + bus := NewEventBus() + + // Create a handler with middleware + handler := func(ctx context.Context, event Event) error { + data := event.Data.(QueryData) + fmt.Printf("Processing query: %s\n", data.OriginalQuery) + return nil + } + + // Apply middleware + handlerWithMiddleware := ApplyMiddleware( + handler, + WithTiming(), + WithRecovery(), + ) + + bus.On(EventQueryReceived, handlerWithMiddleware) + + event := NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "What is RAG?", + }) + + _ = bus.Emit(ctx, event) + // Output: Processing query: What is RAG? +} + +// Example: Query processing pipeline with events +func ExampleEventBus_pipeline() { + ctx := context.Background() + bus := NewEventBus() + + // Step 1: Query received + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + data := event.Data.(QueryData) + fmt.Printf("1. Query received: %s\n", data.OriginalQuery) + return nil + }) + + // Step 2: Query rewrite + bus.On(EventQueryRewrite, func(ctx context.Context, event Event) error { + data := event.Data.(QueryData) + fmt.Printf("2. Rewriting query: %s\n", data.OriginalQuery) + return nil + }) + + // Step 3: Retrieval + bus.On(EventRetrievalStart, func(ctx context.Context, event Event) error { + data := event.Data.(RetrievalData) + fmt.Printf("3. Starting retrieval for: %s\n", data.Query) + return nil + }) + + // Step 4: Rerank + bus.On(EventRerankStart, func(ctx context.Context, event Event) error { + data := event.Data.(RerankData) + fmt.Printf("4. Starting rerank for: %s\n", data.Query) + return nil + }) + + // Simulate pipeline + sessionID := "session-123" + + _ = bus.Emit(ctx, NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "What is RAG?", + SessionID: sessionID, + })) + + _ = bus.Emit(ctx, NewEvent(EventQueryRewrite, QueryData{ + OriginalQuery: "What is RAG?", + SessionID: sessionID, + })) + + _ = bus.Emit(ctx, NewEvent(EventRetrievalStart, RetrievalData{ + Query: "What is Retrieval Augmented Generation?", + KnowledgeBaseID: "kb-1", + TopK: 10, + })) + + _ = bus.Emit(ctx, NewEvent(EventRerankStart, RerankData{ + Query: "What is Retrieval Augmented Generation?", + InputCount: 10, + OutputCount: 5, + ModelID: "rerank-model-1", + })) + + // Output: + // 1. Query received: What is RAG? + // 2. Rewriting query: What is RAG? + // 3. Starting retrieval for: What is Retrieval Augmented Generation? + // 4. Starting rerank for: What is Retrieval Augmented Generation? +} + +// Test: Multiple handlers for same event +func TestEventBus_MultipleHandlers(t *testing.T) { + ctx := context.Background() + bus := NewEventBus() + + counter := 0 + + // Register multiple handlers + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + counter++ + return nil + }) + + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + counter++ + return nil + }) + + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + counter++ + return nil + }) + + // Emit event + event := NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "test", + }) + + _ = bus.Emit(ctx, event) + + if counter != 3 { + t.Errorf("Expected 3 handlers to be called, got %d", counter) + } +} + +// Test: Async event bus +func TestEventBus_Async(t *testing.T) { + ctx := context.Background() + bus := NewAsyncEventBus() + + done := make(chan bool, 3) + + // Register handlers + for i := 0; i < 3; i++ { + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + time.Sleep(100 * time.Millisecond) + done <- true + return nil + }) + } + + // Emit event + event := NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "test", + }) + + _ = bus.Emit(ctx, event) + + // Wait for all handlers + timeout := time.After(2 * time.Second) + count := 0 + + for count < 3 { + select { + case <-done: + count++ + case <-timeout: + t.Error("Timeout waiting for async handlers") + return + } + } +} + +// Test: EmitAndWait +func TestEventBus_EmitAndWait(t *testing.T) { + ctx := context.Background() + bus := NewAsyncEventBus() + + counter := 0 + + // Register handlers + for i := 0; i < 3; i++ { + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + time.Sleep(50 * time.Millisecond) + counter++ + return nil + }) + } + + // Emit and wait + event := NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "test", + }) + + err := bus.EmitAndWait(ctx, event) + if err != nil { + t.Errorf("EmitAndWait failed: %v", err) + } + + if counter != 3 { + t.Errorf("Expected 3 handlers to complete, got %d", counter) + } +} + +// Benchmark: Event emission +func BenchmarkEventBus_Emit(b *testing.B) { + ctx := context.Background() + bus := NewEventBus() + + bus.On(EventQueryReceived, func(ctx context.Context, event Event) error { + return nil + }) + + event := NewEvent(EventQueryReceived, QueryData{ + OriginalQuery: "test", + }) + + b.ResetTimer() + for i := 0; i < b.N; i++ { + _ = bus.Emit(ctx, event) + } +} diff --git a/internal/event/global.go b/internal/event/global.go new file mode 100644 index 00000000..544417b5 --- /dev/null +++ b/internal/event/global.go @@ -0,0 +1,57 @@ +package event + +import ( + "context" + "sync" +) + +var ( + // globalEventBus is the global event bus instance + globalEventBus *EventBus + once sync.Once +) + +// GetGlobalEventBus returns the global event bus instance +// It uses singleton pattern to ensure only one instance exists +func GetGlobalEventBus() *EventBus { + once.Do(func() { + globalEventBus = NewEventBus() + }) + return globalEventBus +} + +// SetGlobalEventBus sets the global event bus instance +// This is useful for testing or custom configurations +func SetGlobalEventBus(bus *EventBus) { + globalEventBus = bus +} + +// On registers an event handler on the global event bus +func On(eventType EventType, handler EventHandler) { + GetGlobalEventBus().On(eventType, handler) +} + +// Off removes all handlers for a specific event type from the global event bus +func Off(eventType EventType) { + GetGlobalEventBus().Off(eventType) +} + +// Emit publishes an event to the global event bus +func Emit(ctx context.Context, event Event) error { + return GetGlobalEventBus().Emit(ctx, event) +} + +// EmitAndWait publishes an event to the global event bus and waits for all handlers +func EmitAndWait(ctx context.Context, event Event) error { + return GetGlobalEventBus().EmitAndWait(ctx, event) +} + +// HasHandlers checks if there are any handlers registered for an event type +func HasHandlers(eventType EventType) bool { + return GetGlobalEventBus().HasHandlers(eventType) +} + +// Clear removes all event handlers from the global event bus +func Clear() { + GetGlobalEventBus().Clear() +} diff --git a/internal/event/middleware.go b/internal/event/middleware.go new file mode 100644 index 00000000..0a80e530 --- /dev/null +++ b/internal/event/middleware.go @@ -0,0 +1,94 @@ +package event + +import ( + "context" + "fmt" + "time" + + "github.com/Tencent/WeKnora/internal/logger" +) + +// Middleware is a function that wraps an EventHandler +type Middleware func(EventHandler) EventHandler + +// WithLogging creates a middleware that logs event handling +func WithLogging() Middleware { + return func(next EventHandler) EventHandler { + return func(ctx context.Context, event Event) error { + logger.Infof(ctx, "Event triggered: type=%s, session=%s, request=%s", + event.Type, event.SessionID, event.RequestID) + + err := next(ctx, event) + + if err != nil { + logger.Errorf(ctx, "Event handler error: type=%s, error=%v", event.Type, err) + } else { + logger.Debugf(ctx, "Event handled successfully: type=%s", event.Type) + } + + return err + } + } +} + +// WithTiming creates a middleware that tracks event handling duration +func WithTiming() Middleware { + return func(next EventHandler) EventHandler { + return func(ctx context.Context, event Event) error { + start := time.Now() + err := next(ctx, event) + duration := time.Since(start) + + logger.Debugf(ctx, "Event %s took %v", event.Type, duration) + + // 将耗时添加到事件元数据中 + if event.Metadata == nil { + event.Metadata = make(map[string]interface{}) + } + event.Metadata["duration_ms"] = duration.Milliseconds() + + return err + } + } +} + +// WithRecovery creates a middleware that recovers from panics +func WithRecovery() Middleware { + return func(next EventHandler) EventHandler { + return func(ctx context.Context, event Event) (err error) { + defer func() { + if r := recover(); r != nil { + logger.Errorf(ctx, "Event handler panic: type=%s, panic=%v", event.Type, r) + err = &PanicError{Panic: r} + } + }() + + return next(ctx, event) + } + } +} + +// PanicError represents a panic that occurred in an event handler +type PanicError struct { + Panic interface{} +} + +func (e *PanicError) Error() string { + return fmt.Sprintf("panic in event handler: %v", e.Panic) +} + +// Chain combines multiple middlewares into a single middleware +func Chain(middlewares ...Middleware) Middleware { + return func(handler EventHandler) EventHandler { + // Apply middlewares in reverse order so they execute in the correct order + for i := len(middlewares) - 1; i >= 0; i-- { + handler = middlewares[i](handler) + } + return handler + } +} + +// ApplyMiddleware applies middleware to an event handler +func ApplyMiddleware(handler EventHandler, middlewares ...Middleware) EventHandler { + return Chain(middlewares...)(handler) +} diff --git a/internal/event/usage_example.md b/internal/event/usage_example.md new file mode 100644 index 00000000..a439d059 --- /dev/null +++ b/internal/event/usage_example.md @@ -0,0 +1,419 @@ +# 事件系统使用示例 + +## 在 Chat Pipeline 中集成事件系统 + +### 1. 在服务初始化时设置事件总线 + +```go +// internal/container/container.go 或 main.go + +import ( + "github.com/Tencent/WeKnora/internal/event" +) + +func InitializeEventSystem() { + // 获取全局事件总线 + bus := event.GetGlobalEventBus() + + // 注册监控处理器 + event.NewMonitoringHandler(bus) + + // 注册分析处理器 + event.NewAnalyticsHandler(bus) + + // 或者注册自定义处理器 + bus.On(event.EventQueryReceived, func(ctx context.Context, e event.Event) error { + // 自定义处理逻辑 + return nil + }) +} +``` + +### 2. 在查询处理服务中发送事件 + +#### 示例:在 search.go 中添加事件 + +```go +// internal/application/service/chat_pipline/search.go + +import ( + "github.com/Tencent/WeKnora/internal/event" + "time" +) + +func (p *PluginSearch) OnEvent( + ctx context.Context, + eventType types.EventType, + chatManage *types.ChatManage, + next func() *PluginError, +) *PluginError { + // 发送检索开始事件 + startTime := time.Now() + event.Emit(ctx, event.NewEvent(event.EventRetrievalStart, event.RetrievalData{ + Query: chatManage.ProcessedQuery, + KnowledgeBaseID: chatManage.KnowledgeBaseID, + TopK: chatManage.EmbeddingTopK, + RetrievalType: "vector", + }).WithSessionID(chatManage.SessionID)) + + // 执行检索逻辑 + results, err := p.performSearch(ctx, chatManage) + if err != nil { + // 发送错误事件 + event.Emit(ctx, event.NewEvent(event.EventError, event.ErrorData{ + Error: err.Error(), + Stage: "retrieval", + SessionID: chatManage.SessionID, + Query: chatManage.ProcessedQuery, + }).WithSessionID(chatManage.SessionID)) + return ErrSearch.WithError(err) + } + + // 发送检索完成事件 + event.Emit(ctx, event.NewEvent(event.EventRetrievalComplete, event.RetrievalData{ + Query: chatManage.ProcessedQuery, + KnowledgeBaseID: chatManage.KnowledgeBaseID, + TopK: chatManage.EmbeddingTopK, + RetrievalType: "vector", + ResultCount: len(results), + Duration: time.Since(startTime).Milliseconds(), + Results: results, + }).WithSessionID(chatManage.SessionID)) + + chatManage.SearchResult = results + return next() +} +``` + +#### 示例:在 rewrite.go 中添加事件 + +```go +// internal/application/service/chat_pipline/rewrite.go + +func (p *PluginRewriteQuery) OnEvent( + ctx context.Context, + eventType types.EventType, + chatManage *types.ChatManage, + next func() *PluginError, +) *PluginError { + // 发送改写开始事件 + event.Emit(ctx, event.NewEvent(event.EventQueryRewrite, event.QueryData{ + OriginalQuery: chatManage.Query, + SessionID: chatManage.SessionID, + }).WithSessionID(chatManage.SessionID)) + + // 执行查询改写 + rewrittenQuery, err := p.rewriteQuery(ctx, chatManage) + if err != nil { + return ErrRewrite.WithError(err) + } + + // 发送改写完成事件 + event.Emit(ctx, event.NewEvent(event.EventQueryRewritten, event.QueryData{ + OriginalQuery: chatManage.Query, + RewrittenQuery: rewrittenQuery, + SessionID: chatManage.SessionID, + }).WithSessionID(chatManage.SessionID)) + + chatManage.RewriteQuery = rewrittenQuery + return next() +} +``` + +#### 示例:在 rerank.go 中添加事件 + +```go +// internal/application/service/chat_pipline/rerank.go + +func (p *PluginRerank) OnEvent( + ctx context.Context, + eventType types.EventType, + chatManage *types.ChatManage, + next func() *PluginError, +) *PluginError { + // 发送排序开始事件 + startTime := time.Now() + inputCount := len(chatManage.SearchResult) + + event.Emit(ctx, event.NewEvent(event.EventRerankStart, event.RerankData{ + Query: chatManage.ProcessedQuery, + InputCount: inputCount, + ModelID: chatManage.RerankModelID, + }).WithSessionID(chatManage.SessionID)) + + // 执行排序 + rerankResults, err := p.performRerank(ctx, chatManage) + if err != nil { + return ErrRerank.WithError(err) + } + + // 发送排序完成事件 + event.Emit(ctx, event.NewEvent(event.EventRerankComplete, event.RerankData{ + Query: chatManage.ProcessedQuery, + InputCount: inputCount, + OutputCount: len(rerankResults), + ModelID: chatManage.RerankModelID, + Duration: time.Since(startTime).Milliseconds(), + Results: rerankResults, + }).WithSessionID(chatManage.SessionID)) + + chatManage.RerankResult = rerankResults + return next() +} +``` + +#### 示例:在 chat_completion.go 中添加事件 + +```go +// internal/application/service/chat_pipline/chat_completion.go + +func (p *PluginChatCompletion) OnEvent( + ctx context.Context, + eventType types.EventType, + chatManage *types.ChatManage, + next func() *PluginError, +) *PluginError { + // 发送聊天开始事件 + startTime := time.Now() + event.Emit(ctx, event.NewEvent(event.EventChatStart, event.ChatData{ + Query: chatManage.Query, + ModelID: chatManage.ChatModelID, + IsStream: false, + }).WithSessionID(chatManage.SessionID)) + + // 准备模型和消息 + chatModel, opt, err := prepareChatModel(ctx, p.modelService, chatManage) + if err != nil { + return ErrGetChatModel.WithError(err) + } + + chatMessages := prepareMessagesWithHistory(chatManage) + + // 调用模型 + chatResponse, err := chatModel.Chat(ctx, chatMessages, opt) + if err != nil { + event.Emit(ctx, event.NewEvent(event.EventError, event.ErrorData{ + Error: err.Error(), + Stage: "chat_completion", + SessionID: chatManage.SessionID, + Query: chatManage.Query, + }).WithSessionID(chatManage.SessionID)) + return ErrModelCall.WithError(err) + } + + // 发送聊天完成事件 + event.Emit(ctx, event.NewEvent(event.EventChatComplete, event.ChatData{ + Query: chatManage.Query, + ModelID: chatManage.ChatModelID, + Response: chatResponse.Content, + TokenCount: chatResponse.TokenCount, + Duration: time.Since(startTime).Milliseconds(), + IsStream: false, + }).WithSessionID(chatManage.SessionID)) + + chatManage.ChatResponse = chatResponse + return next() +} +``` + +### 3. 在 Handler 层发送请求接收事件 + +```go +// internal/handler/message.go + +func (h *MessageHandler) SendMessage(c *gin.Context) { + ctx := c.Request.Context() + + // 解析请求 + var req types.SendMessageRequest + if err := c.ShouldBindJSON(&req); err != nil { + c.JSON(400, gin.H{"error": err.Error()}) + return + } + + // 发送查询接收事件 + event.Emit(ctx, event.NewEvent(event.EventQueryReceived, event.QueryData{ + OriginalQuery: req.Content, + SessionID: req.SessionID, + UserID: c.GetString("user_id"), + }).WithSessionID(req.SessionID).WithRequestID(c.GetString("request_id"))) + + // 处理消息... +} +``` + +### 4. 自定义监控处理器 + +```go +// internal/monitoring/event_monitor.go + +package monitoring + +import ( + "context" + "github.com/Tencent/WeKnora/internal/event" + "github.com/prometheus/client_golang/prometheus" +) + +var ( + retrievalDuration = prometheus.NewHistogramVec( + prometheus.HistogramOpts{ + Name: "retrieval_duration_milliseconds", + Help: "Duration of retrieval operations", + }, + []string{"knowledge_base_id", "retrieval_type"}, + ) + + rerankDuration = prometheus.NewHistogramVec( + prometheus.HistogramOpts{ + Name: "rerank_duration_milliseconds", + Help: "Duration of rerank operations", + }, + []string{"model_id"}, + ) +) + +func init() { + prometheus.MustRegister(retrievalDuration) + prometheus.MustRegister(rerankDuration) +} + +func SetupEventMonitoring() { + bus := event.GetGlobalEventBus() + + // 监控检索性能 + bus.On(event.EventRetrievalComplete, func(ctx context.Context, e event.Event) error { + data := e.Data.(event.RetrievalData) + retrievalDuration.WithLabelValues( + data.KnowledgeBaseID, + data.RetrievalType, + ).Observe(float64(data.Duration)) + return nil + }) + + // 监控排序性能 + bus.On(event.EventRerankComplete, func(ctx context.Context, e event.Event) error { + data := e.Data.(event.RerankData) + rerankDuration.WithLabelValues(data.ModelID).Observe(float64(data.Duration)) + return nil + }) +} +``` + +### 5. 日志记录处理器 + +```go +// internal/logging/event_logger.go + +package logging + +import ( + "context" + "encoding/json" + "github.com/Tencent/WeKnora/internal/event" + "github.com/Tencent/WeKnora/internal/logger" +) + +func SetupEventLogging() { + bus := event.GetGlobalEventBus() + + // 对所有事件进行结构化日志记录 + logHandler := event.ApplyMiddleware( + func(ctx context.Context, e event.Event) error { + data, _ := json.Marshal(e.Data) + logger.Infof(ctx, "Event: type=%s, session=%s, request=%s, data=%s", + e.Type, e.SessionID, e.RequestID, string(data)) + return nil + }, + event.WithTiming(), + ) + + // 注册到所有关键事件 + bus.On(event.EventQueryReceived, logHandler) + bus.On(event.EventQueryRewritten, logHandler) + bus.On(event.EventRetrievalComplete, logHandler) + bus.On(event.EventRerankComplete, logHandler) + bus.On(event.EventChatComplete, logHandler) + bus.On(event.EventError, logHandler) +} +``` + +### 6. 完整的初始化流程 + +```go +// cmd/server/main.go 或 internal/container/container.go + +func Initialize() { + // 1. 初始化事件系统 + eventBus := event.GetGlobalEventBus() + + // 2. 设置监控 + event.NewMonitoringHandler(eventBus) + + // 3. 设置分析 + event.NewAnalyticsHandler(eventBus) + + // 4. 设置 Prometheus 监控(如果需要) + // monitoring.SetupEventMonitoring() + + // 5. 设置结构化日志(如果需要) + // logging.SetupEventLogging() + + // 6. 其他初始化... +} +``` + +## 测试事件系统 + +```go +// 在测试中使用独立的事件总线 +func TestMyService(t *testing.T) { + ctx := context.Background() + + // 创建测试专用的事件总线 + testBus := event.NewEventBus() + + // 注册测试监听器 + var receivedEvents []event.Event + testBus.On(event.EventQueryReceived, func(ctx context.Context, e event.Event) error { + receivedEvents = append(receivedEvents, e) + return nil + }) + + // 执行测试... + testBus.Emit(ctx, event.NewEvent(event.EventQueryReceived, event.QueryData{ + OriginalQuery: "test", + })) + + // 验证事件 + if len(receivedEvents) != 1 { + t.Errorf("Expected 1 event, got %d", len(receivedEvents)) + } +} +``` + +## 异步处理示例 + +```go +// 对于不影响主流程的事件,可以使用异步模式 +func SetupAsyncAnalytics() { + asyncBus := event.NewAsyncEventBus() + + asyncBus.On(event.EventQueryReceived, func(ctx context.Context, e event.Event) error { + // 异步发送到分析平台,不阻塞主流程 + // sendToAnalyticsPlatform(e) + return nil + }) + + // 使用异步总线发送事件 + // asyncBus.Emit(ctx, event) +} +``` + +## 性能优化建议 + +1. **避免在关键路径上使用同步事件总线**:对于不影响业务逻辑的监控、日志等,使用异步模式 +2. **合理使用中间件**:只在需要的地方使用中间件,避免不必要的开销 +3. **控制事件数据大小**:避免在事件中传递大量数据,特别是在异步模式下 +4. **使用专用的监听器**:不要在一个监听器中做太多事情,保持单一职责 + diff --git a/internal/handler/agent_stream_handler.go b/internal/handler/agent_stream_handler.go new file mode 100644 index 00000000..55df79fa --- /dev/null +++ b/internal/handler/agent_stream_handler.go @@ -0,0 +1,480 @@ +package handler + +import ( + "context" + "fmt" + "sync" + "time" + + "github.com/Tencent/WeKnora/internal/event" + "github.com/Tencent/WeKnora/internal/logger" + "github.com/Tencent/WeKnora/internal/types" + "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/gin-gonic/gin" +) + +// AgentStreamHandler handles agent events for SSE streaming +// It uses a dedicated EventBus per request to avoid SessionID filtering +type AgentStreamHandler struct { + ctx context.Context + ginContext *gin.Context + sessionID string + assistantMessageID string + requestID string + assistantMessage *types.Message + streamManager interfaces.StreamManager + + eventBus *event.EventBus + + // State tracking + knowledgeRefs []*types.SearchResult + finalAnswer string + accumulatedContent map[string]string // Accumulate content per event ID (thought, answer, reflection) + eventStartTimes map[string]time.Time // Track start time for duration calculation + mu sync.Mutex +} + +// NewAgentStreamHandler creates a new handler for agent SSE streaming +func NewAgentStreamHandler( + ctx context.Context, + c *gin.Context, + sessionID, assistantMessageID, requestID string, + assistantMessage *types.Message, + streamManager interfaces.StreamManager, + eventBus *event.EventBus, +) *AgentStreamHandler { + return &AgentStreamHandler{ + ctx: ctx, + ginContext: c, + sessionID: sessionID, + assistantMessageID: assistantMessageID, + requestID: requestID, + assistantMessage: assistantMessage, + streamManager: streamManager, + eventBus: eventBus, + knowledgeRefs: make([]*types.SearchResult, 0), + accumulatedContent: make(map[string]string), + eventStartTimes: make(map[string]time.Time), + } +} + +// Subscribe subscribes to all agent streaming events on the dedicated EventBus +// No SessionID filtering needed since we have a dedicated EventBus per request +func (h *AgentStreamHandler) Subscribe() { + // Subscribe to all agent streaming events on the dedicated EventBus + h.eventBus.On(event.EventAgentThought, h.handleThought) + h.eventBus.On(event.EventAgentToolCall, h.handleToolCall) + h.eventBus.On(event.EventAgentToolResult, h.handleToolResult) + h.eventBus.On(event.EventAgentReferences, h.handleReferences) + h.eventBus.On(event.EventAgentFinalAnswer, h.handleFinalAnswer) + h.eventBus.On(event.EventAgentReflection, h.handleReflection) + h.eventBus.On(event.EventError, h.handleError) + h.eventBus.On(event.EventAgentComplete, h.handleComplete) +} + +// handleThought handles agent thought events +func (h *AgentStreamHandler) handleThought(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentThoughtData) + if !ok { + return nil + } + + h.mu.Lock() + + // Track start time on first chunk + if _, exists := h.eventStartTimes[evt.ID]; !exists { + h.eventStartTimes[evt.ID] = time.Now() + } + + // Calculate duration if done + var metadata map[string]interface{} + if data.Done { + startTime := h.eventStartTimes[evt.ID] + duration := time.Since(startTime) + metadata = map[string]interface{}{ + "event_id": evt.ID, + "duration_ms": duration.Milliseconds(), + "completed_at": time.Now().Unix(), + } + delete(h.eventStartTimes, evt.ID) + } else { + metadata = map[string]interface{}{ + "event_id": evt.ID, + } + } + + h.mu.Unlock() + + // Send SSE response (real-time incremental) + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: types.ResponseTypeThinking, + Content: data.Content, + Done: data.Done, + Data: metadata, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // Accumulate content and replace event in stream (so refresh can see progress) + h.mu.Lock() + h.accumulateAndReplaceEventWithData(evt.ID, types.ResponseTypeThinking, data.Content, data.Done, metadata) + h.mu.Unlock() + + return nil +} + +// handleToolCall handles tool call events +func (h *AgentStreamHandler) handleToolCall(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentToolCallData) + if !ok { + return nil + } + + metadata := map[string]interface{}{ + "tool_name": data.ToolName, + "arguments": data.Arguments, + } + + // Send SSE response + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: types.ResponseTypeToolCall, + Content: fmt.Sprintf("Calling tool: %s", data.ToolName), + Done: false, + Data: metadata, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // Push event to stream for replay on refresh + if err := h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + ID: evt.ID, + Type: types.ResponseTypeToolCall, + Content: fmt.Sprintf("Calling tool: %s", data.ToolName), + Done: false, + Timestamp: time.Now(), + Data: metadata, + }); err != nil { + logger.GetLogger(h.ctx).Error("Push tool call event to stream failed", "error", err) + } + + return nil +} + +// handleToolResult handles tool result events +func (h *AgentStreamHandler) handleToolResult(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentToolResultData) + if !ok { + return nil + } + + // Send SSE response (both success and failure) + responseType := types.ResponseTypeToolResult + content := data.Output + if !data.Success { + responseType = types.ResponseTypeError + if data.Error != "" { + content = data.Error + } + } + + // Build metadata including tool result data for rich frontend rendering + metadata := map[string]interface{}{ + "tool_name": data.ToolName, + "success": data.Success, + "output": data.Output, + "error": data.Error, + "duration": data.Duration, + } + + // Merge tool result data (contains display_type, formatted results, etc.) + if data.Data != nil { + for k, v := range data.Data { + metadata[k] = v + } + } + + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: responseType, + Content: content, + Done: false, + Data: metadata, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // Push event to stream for replay on refresh + if err := h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + ID: evt.ID, + Type: responseType, + Content: content, + Done: false, + Timestamp: time.Now(), + Data: metadata, + }); err != nil { + logger.GetLogger(h.ctx).Error("Push tool result event to stream failed", "error", err) + } + + return nil +} + +// handleReferences handles knowledge references events +func (h *AgentStreamHandler) handleReferences(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentReferencesData) + if !ok { + return nil + } + + h.mu.Lock() + defer h.mu.Unlock() + + // Extract knowledge references + // Try to cast directly to []*types.SearchResult first + if searchResults, ok := data.References.([]*types.SearchResult); ok { + h.knowledgeRefs = append(h.knowledgeRefs, searchResults...) + } else if refs, ok := data.References.([]interface{}); ok { + // Fallback: convert from []interface{} + for _, ref := range refs { + if sr, ok := ref.(*types.SearchResult); ok { + h.knowledgeRefs = append(h.knowledgeRefs, sr) + } else if refMap, ok := ref.(map[string]interface{}); ok { + // Parse from map if needed + searchResult := &types.SearchResult{ + ID: getString(refMap, "id"), + Content: getString(refMap, "content"), + Score: getFloat64(refMap, "score"), + KnowledgeID: getString(refMap, "knowledge_id"), + KnowledgeTitle: getString(refMap, "knowledge_title"), + ChunkIndex: int(getFloat64(refMap, "chunk_index")), + } + + if meta, ok := refMap["metadata"].(map[string]interface{}); ok { + metadata := make(map[string]string) + for k, v := range meta { + if strVal, ok := v.(string); ok { + metadata[k] = strVal + } + } + searchResult.Metadata = metadata + } + + h.knowledgeRefs = append(h.knowledgeRefs, searchResult) + } + } + } + + // Update assistant message references + h.assistantMessage.KnowledgeReferences = h.knowledgeRefs + + // Send SSE response + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: types.ResponseTypeReferences, + KnowledgeReferences: h.knowledgeRefs, + Done: false, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // Update stream references + if err := h.streamManager.UpdateReferences( + h.ctx, h.sessionID, h.assistantMessageID, h.knowledgeRefs, + ); err != nil { + logger.GetLogger(h.ctx).Error("Update stream references failed", "error", err) + } + + // Push event to stream for replay on refresh + if err := h.streamManager.PushEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + ID: evt.ID, + Type: types.ResponseTypeReferences, + Content: "", + Done: false, + Timestamp: time.Now(), + Data: map[string]interface{}{ + "references": h.knowledgeRefs, + }, + }); err != nil { + logger.GetLogger(h.ctx).Error("Push references event to stream failed", "error", err) + } + + return nil +} + +// handleFinalAnswer handles final answer events +func (h *AgentStreamHandler) handleFinalAnswer(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentFinalAnswerData) + if !ok { + return nil + } + + h.mu.Lock() + + // Accumulate final answer (this persists and won't be reset) + h.finalAnswer += data.Content + h.assistantMessage.Content = h.finalAnswer + + // Send SSE response (real-time incremental) + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: types.ResponseTypeAnswer, + Content: data.Content, + Done: data.Done, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // Replace answer event in stream (so refresh can see progress) + h.accumulateAndReplaceEvent(evt.ID, types.ResponseTypeAnswer, data.Content, data.Done) + h.mu.Unlock() + + return nil +} + +// handleReflection handles agent reflection events +func (h *AgentStreamHandler) handleReflection(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentReflectionData) + if !ok { + return nil + } + + // Send reflection as SSE (real-time incremental) + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: "reflection", // Special type for reflection + Content: data.Content, + Done: data.Done, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + // Accumulate reflection per tool call and replace event in stream + h.mu.Lock() + h.accumulateAndReplaceEvent(evt.ID, types.ResponseTypeReflection, data.Content, data.Done) + h.mu.Unlock() + + return nil +} + +// handleError handles error events +func (h *AgentStreamHandler) handleError(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.ErrorData) + if !ok { + return nil + } + + response := types.StreamResponse{ + ID: h.requestID, + ResponseType: types.ResponseTypeError, + Content: data.Error, + Done: true, + } + + h.ginContext.SSEvent("message", response) + h.ginContext.Writer.Flush() + + return nil +} + +// handleComplete handles agent complete events +func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event) error { + data, ok := evt.Data.(event.AgentCompleteData) + if !ok { + return nil + } + + h.mu.Lock() + defer h.mu.Unlock() + + // Update assistant message with final data + if data.MessageID == h.assistantMessageID { + h.assistantMessage.Content = data.FinalAnswer + h.assistantMessage.IsCompleted = true + + // Update knowledge references if provided + if len(data.KnowledgeRefs) > 0 { + knowledgeRefs := make([]*types.SearchResult, 0, len(data.KnowledgeRefs)) + for _, ref := range data.KnowledgeRefs { + if sr, ok := ref.(*types.SearchResult); ok { + knowledgeRefs = append(knowledgeRefs, sr) + } + } + h.assistantMessage.KnowledgeReferences = knowledgeRefs + } + + // Update agent steps if provided + if data.AgentSteps != nil { + if steps, ok := data.AgentSteps.([]types.AgentStep); ok { + h.assistantMessage.AgentSteps = steps + } + } + } + + // Complete stream + if err := h.streamManager.CompleteStream(h.ctx, h.sessionID, h.assistantMessageID); err != nil { + logger.GetLogger(h.ctx).Error("Complete stream failed", "error", err) + } + + return nil +} + +// accumulateAndReplaceEvent accumulates content per event ID and replaces the event in stream +// This is a common pattern for thought, answer, and reflection events +func (h *AgentStreamHandler) accumulateAndReplaceEvent( + evtID string, + evtType types.ResponseType, + content string, + done bool, +) { + h.accumulateAndReplaceEventWithData(evtID, evtType, content, done, nil) +} + +// accumulateAndReplaceEventWithData accumulates content and replaces event with metadata +func (h *AgentStreamHandler) accumulateAndReplaceEventWithData( + evtID string, + evtType types.ResponseType, + content string, + done bool, + data map[string]interface{}, +) { + h.accumulatedContent[evtID] += content + if err := h.streamManager.ReplaceEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{ + ID: evtID, + Type: evtType, + Content: h.accumulatedContent[evtID], + Done: done, + Timestamp: time.Now(), + Data: data, + }); err != nil { + logger.GetLogger(h.ctx).Error(fmt.Sprintf("Replace %s event in stream failed", evtType), "error", err) + } + // Clean up when done + if done { + delete(h.accumulatedContent, evtID) + } +} + +// Helper functions +func getString(m map[string]interface{}, key string) string { + if val, ok := m[key].(string); ok { + return val + } + return "" +} + +func getFloat64(m map[string]interface{}, key string) float64 { + if val, ok := m[key].(float64); ok { + return val + } + if val, ok := m[key].(int); ok { + return float64(val) + } + return 0.0 +} diff --git a/internal/handler/chunk.go b/internal/handler/chunk.go index 40d7b5e6..cb321468 100644 --- a/internal/handler/chunk.go +++ b/internal/handler/chunk.go @@ -113,7 +113,7 @@ func (h *ChunkHandler) validateAndGetChunk(c *gin.Context) (*types.Chunk, string logger.Infof(ctx, "Retrieving knowledge chunk information, knowledge ID: %s, chunk ID: %s", knowledgeID, id) // Get existing chunk - chunk, err := h.service.GetChunkByID(ctx, knowledgeID, id) + chunk, err := h.service.GetChunkByID(ctx, id) if err != nil { if err == service.ErrChunkNotFound { logger.Warnf(ctx, "Chunk not found, knowledge ID: %s, chunk ID: %s", knowledgeID, id) diff --git a/internal/handler/initialization.go b/internal/handler/initialization.go index e82a0d92..a78bef0c 100644 --- a/internal/handler/initialization.go +++ b/internal/handler/initialization.go @@ -23,6 +23,7 @@ import ( "github.com/Tencent/WeKnora/internal/models/utils/ollama" "github.com/Tencent/WeKnora/internal/types" "github.com/Tencent/WeKnora/internal/types/interfaces" + "github.com/Tencent/WeKnora/internal/utils" "github.com/Tencent/WeKnora/services/docreader/src/client" "github.com/Tencent/WeKnora/services/docreader/src/proto" "github.com/gin-gonic/gin" @@ -156,14 +157,13 @@ func (h *InitializationHandler) InitializeByKB(c *gin.Context) { ctx := c.Request.Context() kbIdStr := c.Param("kbId") - logger.Infof(ctx, "Starting knowledge base configuration update, kbId: %s", kbIdStr) - var req InitializationRequest if err := c.ShouldBindJSON(&req); err != nil { logger.Error(ctx, "Failed to parse initialization request", err) c.Error(errors.NewBadRequestError(err.Error())) return } + logger.Infof(ctx, "Starting knowledge base configuration update, kbId: %s, request: %s", kbIdStr, utils.ToJSON(req)) // 获取指定知识库信息 kb, err := h.kbService.GetKnowledgeBaseByID(ctx, kbIdStr) @@ -333,9 +333,31 @@ func (h *InitializationHandler) InitializeByKB(c *gin.Context) { } } - // 检查模型是否已存在 - existingModel, err := h.modelService.GetModelByID(ctx, model.ID) - if err == nil && existingModel != nil { + // 根据模型类型从知识库获取已有的模型ID + var existingModelID string + switch modelInfo.modelType { + case types.ModelTypeEmbedding: + existingModelID = kb.EmbeddingModelID + case types.ModelTypeKnowledgeQA: + existingModelID = kb.SummaryModelID + case types.ModelTypeRerank: + existingModelID = kb.RerankModelID + case types.ModelTypeVLLM: + existingModelID = kb.VLMModelID + } + + // 如果知识库中已经有对应类型的模型ID,尝试获取并更新 + var existingModel *types.Model + if existingModelID != "" { + existingModel, err = h.modelService.GetModelByID(ctx, existingModelID) + if err != nil { + // 模型不存在或获取失败,记录日志但继续创建新模型 + logger.Warnf(ctx, "Failed to get existing model %s: %v, will create new one", existingModelID, err) + existingModel = nil + } + } + + if existingModel != nil { // 更新现有模型 existingModel.Name = model.Name existingModel.Source = model.Source @@ -740,7 +762,8 @@ func (h *InitializationHandler) ListOllamaModels(c *gin.Context) { } } - models, err := h.ollamaService.ListModels(ctx) + // 使用 ListModelsDetailed 获取包含大小等详细信息的模型列表 + models, err := h.ollamaService.ListModelsDetailed(ctx) if err != nil { logger.ErrorWithFields(ctx, err, nil) c.Error(errors.NewInternalServerError("获取模型列表失败: " + err.Error())) @@ -916,7 +939,7 @@ func (h *InitializationHandler) GetCurrentConfigByKB(c *gin.Context) { } // 构建配置响应 - config := buildConfigResponse(models, kb, hasFiles) + config := h.buildConfigResponse(ctx, models, kb, hasFiles) logger.Info(ctx, "Knowledge base configuration retrieved successfully", "kbId", kbIdStr) c.JSON(http.StatusOK, gin.H{ @@ -926,7 +949,7 @@ func (h *InitializationHandler) GetCurrentConfigByKB(c *gin.Context) { } // buildConfigResponse 构建配置响应数据 -func buildConfigResponse(models []*types.Model, +func (h *InitializationHandler) buildConfigResponse(ctx context.Context, models []*types.Model, kb *types.KnowledgeBase, hasFiles bool, ) map[string]interface{} { config := map[string]interface{}{ diff --git a/internal/handler/session.go b/internal/handler/session.go index 374a6147..5c7c7b52 100644 --- a/internal/handler/session.go +++ b/internal/handler/session.go @@ -9,10 +9,12 @@ import ( "github.com/Tencent/WeKnora/internal/config" "github.com/Tencent/WeKnora/internal/errors" + "github.com/Tencent/WeKnora/internal/event" "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/types" "github.com/Tencent/WeKnora/internal/types/interfaces" "github.com/gin-gonic/gin" + "github.com/google/uuid" ) // SessionHandler handles all HTTP requests related to conversation sessions @@ -32,13 +34,14 @@ func NewSessionHandler( config *config.Config, knowledgebaseService interfaces.KnowledgeBaseService, ) *SessionHandler { - return &SessionHandler{ + handler := &SessionHandler{ sessionService: sessionService, messageService: messageService, streamManager: streamManager, config: config, knowledgebaseService: knowledgebaseService, } + return handler } // SessionStrategy defines the configuration for a conversation session strategy @@ -73,10 +76,12 @@ type SessionStrategy struct { // CreateSessionRequest represents a request to create a new session type CreateSessionRequest struct { - // ID of the associated knowledge base - KnowledgeBaseID string `json:"knowledge_base_id" binding:"required"` + // ID of the associated knowledge base (optional in agent mode) + KnowledgeBaseID string `json:"knowledge_base_id"` // Session strategy configuration SessionStrategy *SessionStrategy `json:"session_strategy"` + // Agent configuration (optional, for agent mode) + AgentConfig *types.AgentConfig `json:"agent_config"` } // CreateSession handles the creation of a new conversation session @@ -101,24 +106,37 @@ func (h *SessionHandler) CreateSession(c *gin.Context) { return } - // Validate knowledge base ID - if request.KnowledgeBaseID == "" { - logger.Error(ctx, "Knowledge base ID is empty") - c.Error(errors.NewBadRequestError("Knowledge base cannot be empty")) + // Validate session creation request + // - Traditional RAG mode: requires KnowledgeBaseID + // - Agent mode: KnowledgeBaseID is optional + // - If AgentConfig.KnowledgeBases is specified, use those + // - If session.KnowledgeBaseID is specified, use that + // - Otherwise, default to all knowledge bases under the tenant + isAgentMode := request.AgentConfig != nil && request.AgentConfig.Enabled + hasKnowledgeBase := request.KnowledgeBaseID != "" + hasAgentKnowledgeBases := request.AgentConfig != nil && len(request.AgentConfig.KnowledgeBases) > 0 + + // In traditional RAG mode, knowledge base ID is required + if !isAgentMode && !hasKnowledgeBase { + logger.Error(ctx, "Traditional RAG mode requires knowledge_base_id") + c.Error(errors.NewBadRequestError("knowledge_base_id is required for non-agent sessions")) return } logger.Infof( ctx, - "Processing session creation request, tenant ID: %d, knowledge base ID: %s", + "Processing session creation request, tenant ID: %d, knowledge base ID: %s, agent mode: %v, agent KBs: %v", tenantID.(uint), request.KnowledgeBaseID, + isAgentMode, + hasAgentKnowledgeBases, ) // Create session object with base properties createdSession := &types.Session{ TenantID: tenantID.(uint), KnowledgeBaseID: request.KnowledgeBaseID, + AgentConfig: request.AgentConfig, // Set agent config if provided } // If summary model parameters are empty, set defaults @@ -190,24 +208,33 @@ func (h *SessionHandler) CreateSession(c *gin.Context) { logger.Debug(ctx, "Using default session strategy") } - kb, err := h.knowledgebaseService.GetKnowledgeBaseByID(ctx, request.KnowledgeBaseID) - if err != nil { - logger.Error(ctx, "Failed to get knowledge base", err) - c.Error(errors.NewInternalServerError(err.Error())) - return - } + // Only fetch knowledge base if KnowledgeBaseID is provided + // In agent mode, knowledge bases may be configured in AgentConfig instead + if request.KnowledgeBaseID != "" { + kb, err := h.knowledgebaseService.GetKnowledgeBaseByID(ctx, request.KnowledgeBaseID) + if err != nil { + logger.Error(ctx, "Failed to get knowledge base", err) + c.Error(errors.NewInternalServerError(err.Error())) + return + } - // Get model IDs from knowledge base if not provided - if createdSession.SummaryModelID == "" { - createdSession.SummaryModelID = kb.SummaryModelID - } - if createdSession.RerankModelID == "" { - createdSession.RerankModelID = kb.RerankModelID + // Use knowledge base's models if session doesn't specify them + if createdSession.RerankModelID == "" { + createdSession.RerankModelID = kb.RerankModelID + } + if createdSession.SummaryModelID == "" { + createdSession.SummaryModelID = kb.SummaryModelID + } + + logger.Debugf(ctx, "Knowledge base fetched: %s, rerank model: %s, summary model: %s", + kb.ID, kb.RerankModelID, kb.SummaryModelID) + } else { + logger.Debug(ctx, "No knowledge base ID provided, skipping knowledge base fetch (agent mode)") } // Call service to create session logger.Infof(ctx, "Calling session service to create session") - createdSession, err = h.sessionService.CreateSession(ctx, createdSession) + createdSession, err := h.sessionService.CreateSession(ctx, createdSession) if err != nil { logger.ErrorWithFields(ctx, err, nil) c.Error(errors.NewInternalServerError(err.Error())) @@ -590,29 +617,32 @@ func (h *SessionHandler) ContinueStream(c *gin.Context) { }) } - // Send existing content - if streamInfo.Content != "" { - logger.Debug(ctx, "Sending current existing content") - c.SSEvent("message", &types.StreamResponse{ - ID: message.RequestID, - ResponseType: types.ResponseTypeAnswer, - Content: streamInfo.Content, - Done: streamInfo.IsCompleted, - }) + // Replay existing events + if len(streamInfo.Events) > 0 { + logger.Debugf(ctx, "Replaying %d existing events", len(streamInfo.Events)) + for _, evt := range streamInfo.Events { + c.SSEvent("message", &types.StreamResponse{ + ID: message.RequestID, + ResponseType: evt.Type, + Content: evt.Content, + Done: evt.Done, + Data: evt.Data, + }) + } } - // Create channels to monitor content updates - contentCh := make(chan string, 10) + // Create channels to monitor event updates + eventIndexCh := make(chan int, 10) doneCh := make(chan bool, 1) - logger.Debug(ctx, "Starting content update monitoring") + logger.Debug(ctx, "Starting event update monitoring") - // Start a goroutine to monitor for content updates + // Start a goroutine to monitor for new events go func() { ticker := time.NewTicker(100 * time.Millisecond) defer ticker.Stop() - currentContent := streamInfo.Content + currentEventCount := len(streamInfo.Events) for { select { @@ -636,12 +666,11 @@ func (h *SessionHandler) ContinueStream(c *gin.Context) { return } - // Calculate new content delta - if len(latestStreamInfo.Content) > len(currentContent) { - newContent := latestStreamInfo.Content[len(currentContent):] - contentCh <- newContent - currentContent = latestStreamInfo.Content - logger.Debugf(ctx, "Sending new content: %d bytes", len(newContent)) + // Check for new events + if len(latestStreamInfo.Events) > currentEventCount { + eventIndexCh <- currentEventCount + currentEventCount = len(latestStreamInfo.Events) + logger.Debugf(ctx, "Detected %d new events", len(latestStreamInfo.Events)-currentEventCount) } case <-c.Request.Context().Done(): @@ -653,7 +682,7 @@ func (h *SessionHandler) ContinueStream(c *gin.Context) { logger.Info(ctx, "Starting stream response") - // Stream updated content to client + // Stream new events to client c.Stream(func(w io.Writer) bool { select { case <-c.Request.Context().Done(): @@ -670,14 +699,22 @@ func (h *SessionHandler) ContinueStream(c *gin.Context) { }) return false - case content := <-contentCh: - logger.Debugf(ctx, "Sending content fragment: %d bytes", len(content)) - c.SSEvent("message", &types.StreamResponse{ - ID: message.RequestID, - ResponseType: types.ResponseTypeAnswer, - Content: content, - Done: false, - }) + case startIdx := <-eventIndexCh: + // Send new events + latestStreamInfo, err := h.streamManager.GetStream(ctx, sessionID, messageID) + if err == nil && latestStreamInfo != nil { + for i := startIdx; i < len(latestStreamInfo.Events); i++ { + evt := latestStreamInfo.Events[i] + logger.Debugf(ctx, "Sending new event: %s", evt.Type) + c.SSEvent("message", &types.StreamResponse{ + ID: message.RequestID, + ResponseType: evt.Type, + Content: evt.Content, + Done: evt.Done, + Data: evt.Data, + }) + } + } return true } }) @@ -786,11 +823,25 @@ func (h *SessionHandler) KnowledgeQA(c *gin.Context) { c.Writer.Flush() if response.ResponseType == types.ResponseTypeAnswer { assistantMessage.Content += response.Content - // Update stream manager with new content - if err := h.streamManager.UpdateStream( - ctx, sessionID, assistantMessage.ID, response.Content, searchResults, + // Push event to stream for replay on refresh + if err := h.streamManager.PushEvent( + ctx, sessionID, assistantMessage.ID, interfaces.StreamEvent{ + ID: uuid.New().String(), + Type: response.ResponseType, + Content: response.Content, + Done: response.Done, + Timestamp: time.Now(), + }, ); err != nil { - logger.GetLogger(ctx).Error("Update stream content failed", "error", err) + logger.GetLogger(ctx).Error("Push answer event to stream failed", "error", err) + } + } + if response.ResponseType == types.ResponseTypeReferences { + // Update references + if err := h.streamManager.UpdateReferences( + ctx, sessionID, assistantMessage.ID, searchResults, + ); err != nil { + logger.GetLogger(ctx).Error("Update stream references failed", "error", err) } } } @@ -803,3 +854,141 @@ func (h *SessionHandler) completeAssistantMessage(ctx context.Context, assistant assistantMessage.IsCompleted = true _ = h.messageService.UpdateMessage(ctx, assistantMessage) } + +// AgentQA handles agent-based question answering with conversation history and streaming +func (h *SessionHandler) AgentQA(c *gin.Context) { + ctx := logger.CloneContext(c.Request.Context()) + + logger.Info(ctx, "Start processing agent QA request") + + // Get session ID from URL parameter + sessionID := c.Param("session_id") + if sessionID == "" { + logger.Error(ctx, "Session ID is empty") + c.Error(errors.NewBadRequestError(errors.ErrInvalidSessionID.Error())) + return + } + + // Parse request body + var request CreateKnowledgeQARequest + if err := c.ShouldBindJSON(&request); err != nil { + logger.Error(ctx, "Failed to parse request data", err) + c.Error(errors.NewBadRequestError(err.Error())) + return + } + + // Create assistant message + assistantMessage := &types.Message{ + SessionID: sessionID, + Role: "assistant", + RequestID: c.GetString(types.RequestIDContextKey.String()), + IsCompleted: false, + } + defer h.completeAssistantMessage(ctx, assistantMessage) + + // Validate query content + if request.Query == "" { + logger.Error(ctx, "Query content is empty") + c.Error(errors.NewBadRequestError("Query content cannot be empty")) + return + } + + logger.Infof(ctx, "Agent QA request, session ID: %s, query: %s", sessionID, request.Query) + + // Get session information first + session, err := h.sessionService.GetSession(ctx, sessionID) + if err != nil { + logger.Errorf(ctx, "Failed to get session, session ID: %s, error: %v", sessionID, err) + c.Error(errors.NewNotFoundError("Session not found")) + return + } + + // Emit agent query event to create user message + requestID := c.GetString(types.RequestIDContextKey.String()) + if err := event.Emit(ctx, event.Event{ + Type: event.EventAgentQuery, + SessionID: sessionID, + RequestID: requestID, + Data: event.AgentQueryData{ + SessionID: sessionID, + Query: request.Query, + RequestID: requestID, + }, + }); err != nil { + logger.Errorf(ctx, "Failed to emit agent query event: %v", err) + c.Error(errors.NewInternalServerError(err.Error())) + return + } + + // Create assistant message (response) + assistantMessage.CreatedAt = time.Now() + assistantMessagePtr, err := h.messageService.CreateMessage(ctx, assistantMessage) + if err != nil { + c.Error(errors.NewInternalServerError(err.Error())) + return + } + assistantMessage = assistantMessagePtr + + logger.Infof(ctx, "Calling agent QA service, session ID: %s", sessionID) + + // Register new stream with stream manager + if err := h.streamManager.RegisterStream(ctx, sessionID, assistantMessage.ID, request.Query); err != nil { + logger.GetLogger(ctx).Error("Register stream failed", "error", err) + } + + // Set headers for SSE + c.Header("Content-Type", "text/event-stream") + c.Header("Cache-Control", "no-cache") + c.Header("Connection", "keep-alive") + c.Header("X-Accel-Buffering", "no") + + eventBus := event.NewEventBus() + // Create stream handler with dedicated EventBus BEFORE calling AgentQA + streamHandler := NewAgentStreamHandler( + ctx, c, sessionID, assistantMessage.ID, requestID, + assistantMessage, h.streamManager, eventBus, + ) + + // Subscribe to events on the dedicated EventBus + streamHandler.Subscribe() + + // Call service to perform agent QA + go func() { + searchResults, err := h.sessionService.AgentQA(ctx, session, request.Query, assistantMessage.ID, eventBus) + if err != nil { + logger.ErrorWithFields(ctx, err, nil) + // Emit error event to dedicated EventBus + eventBus.Emit(ctx, event.Event{ + Type: event.EventError, + SessionID: sessionID, + Data: event.ErrorData{ + Error: err.Error(), + Stage: "agent_execution", + SessionID: sessionID, + }, + }) + return + } + assistantMessage.KnowledgeReferences = searchResults + }() + + // Handle events for SSE (blocking until connection is done) + h.handleAgentEventsForSSEWithHandler(ctx, c, sessionID, assistantMessage.ID) +} + +// handleAgentEventsForSSEWithHandler handles agent events for SSE streaming using an existing handler +// The handler is already subscribed to events and AgentQA is already running +func (h *SessionHandler) handleAgentEventsForSSEWithHandler( + ctx context.Context, + c *gin.Context, + sessionID, assistantMessageID string, +) { + // Wait for completion - events are already being handled by streamHandler + // The connection will be closed when the gin context is done + <-c.Request.Context().Done() + + // Complete stream when done + if err := h.streamManager.CompleteStream(ctx, sessionID, assistantMessageID); err != nil { + logger.GetLogger(ctx).Error("Complete stream failed", "error", err) + } +} diff --git a/internal/handler/tenant.go b/internal/handler/tenant.go index c8628948..8516c9b3 100644 --- a/internal/handler/tenant.go +++ b/internal/handler/tenant.go @@ -224,3 +224,173 @@ func (h *TenantHandler) ListTenants(c *gin.Context) { }, }) } + +// AgentConfigRequest represents the request body for updating agent configuration +type AgentConfigRequest struct { + Enabled bool `json:"enabled"` + MaxIterations int `json:"max_iterations"` + ReflectionEnabled bool `json:"reflection_enabled"` + AllowedTools []string `json:"allowed_tools"` + Temperature float64 `json:"temperature"` + ThinkingModelID string `json:"thinking_model_id"` + RerankModelID string `json:"rerank_model_id"` +} + +// GetTenantAgentConfig retrieves the agent configuration for a tenant +// This is the global agent configuration that applies to all sessions by default +// Tenant ID is obtained from the authentication context +func (h *TenantHandler) GetTenantAgentConfig(c *gin.Context) { + ctx := c.Request.Context() + + logger.Info(ctx, "Start retrieving tenant agent config") + + // Get tenant ID from authentication context + tenantID := c.GetUint(types.TenantIDContextKey.String()) + if tenantID == 0 { + logger.Error(ctx, "Tenant ID is empty") + c.Error(errors.NewBadRequestError("Tenant ID cannot be empty")) + return + } + + tenant, err := h.service.GetTenantByID(ctx, tenantID) + if err != nil { + if appErr, ok := errors.IsAppError(err); ok { + logger.Error(ctx, "Failed to retrieve tenant: application error", appErr) + c.Error(appErr) + } else { + logger.ErrorWithFields(ctx, err, nil) + c.Error(errors.NewInternalServerError("Failed to retrieve tenant").WithDetails(err.Error())) + } + return + } + // 定义所有可用工具及其描述(与 internal/agent/tools 注册的工具对应) + availableTools := []gin.H{ + {"name": "thinking", "label": "思考", "description": "AI 进行深度思考和推理"}, + {"name": "todo_write", "label": "制定计划", "description": "为复杂任务制定执行计划"}, + {"name": "knowledge_search", "label": "知识搜索", "description": "在知识库中搜索相关信息"}, + {"name": "get_related_chunks", "label": "获取相关片段", "description": "查找相关的知识片段"}, + {"name": "query_knowledge_graph", "label": "查询知识图谱", "description": "从知识图谱中查询关系"}, + {"name": "get_document_info", "label": "获取文档信息", "description": "查看文档元数据"}, + {"name": "database_query", "label": "查询数据库", "description": "查询数据库中的信息"}, + } + if tenant.AgentConfig == nil { + // Return default config if not set + logger.Info(ctx, "Tenant has no agent config, returning defaults") + + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": gin.H{ + "enabled": false, + "max_iterations": 5, + "reflection_enabled": false, + "allowed_tools": []string{"knowledge_search", "knowledge_search"}, + "temperature": 0.7, + "thinking_model_id": "", + "rerank_model_id": "", + "available_tools": availableTools, + }, + }) + return + } + + logger.Infof(ctx, "Retrieved tenant agent config successfully, Tenant ID: %d", tenantID) + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": gin.H{ + "enabled": tenant.AgentConfig.Enabled, + "max_iterations": tenant.AgentConfig.MaxIterations, + "reflection_enabled": tenant.AgentConfig.ReflectionEnabled, + "allowed_tools": tenant.AgentConfig.AllowedTools, + "temperature": tenant.AgentConfig.Temperature, + "thinking_model_id": tenant.AgentConfig.ThinkingModelID, + "rerank_model_id": tenant.AgentConfig.RerankModelID, + "available_tools": availableTools, + }, + }) +} + +// UpdateTenantAgentConfig updates the agent configuration for a tenant +// This sets the global agent configuration for all sessions in this tenant +// Tenant ID is obtained from the authentication context +func (h *TenantHandler) UpdateTenantAgentConfig(c *gin.Context) { + ctx := c.Request.Context() + + logger.Info(ctx, "Start updating tenant agent config") + + // Get tenant ID from authentication context + tenantID := c.GetUint(types.TenantIDContextKey.String()) + if tenantID == 0 { + logger.Error(ctx, "Tenant ID is empty") + c.Error(errors.NewBadRequestError("Tenant ID cannot be empty")) + return + } + + var req AgentConfigRequest + if err := c.ShouldBindJSON(&req); err != nil { + logger.Error(ctx, "Failed to parse request parameters", err) + c.Error(errors.NewValidationError("Invalid request data").WithDetails(err.Error())) + return + } + + // Validate configuration + if req.Enabled { + if req.MaxIterations <= 0 || req.MaxIterations > 20 { + c.Error(errors.NewAgentInvalidMaxIterationsError()) + return + } + if req.Temperature < 0 || req.Temperature > 2 { + c.Error(errors.NewAgentInvalidTemperatureError()) + return + } + // thinking_model_id 不再强制要求,允许先启用 Agent 再设置模型 + // 实际使用时会在 AgentQA 中进行验证 + if len(req.AllowedTools) == 0 { + c.Error(errors.NewAgentMissingAllowedToolsError()) + return + } + } + + // Get existing tenant + tenant, err := h.service.GetTenantByID(ctx, tenantID) + if err != nil { + if appErr, ok := errors.IsAppError(err); ok { + logger.Error(ctx, "Failed to retrieve tenant: application error", appErr) + c.Error(appErr) + } else { + logger.ErrorWithFields(ctx, err, nil) + c.Error(errors.NewInternalServerError("Failed to retrieve tenant").WithDetails(err.Error())) + } + return + } + + // Update agent configuration + tenant.AgentConfig = &types.AgentConfig{ + Enabled: req.Enabled, + MaxIterations: req.MaxIterations, + ReflectionEnabled: req.ReflectionEnabled, + AllowedTools: req.AllowedTools, + Temperature: req.Temperature, + ThinkingModelID: req.ThinkingModelID, + RerankModelID: req.RerankModelID, + KnowledgeBases: []string{}, // Will be set per session + } + + updatedTenant, err := h.service.UpdateTenant(ctx, tenant) + if err != nil { + if appErr, ok := errors.IsAppError(err); ok { + logger.Error(ctx, "Failed to update tenant: application error", appErr) + c.Error(appErr) + } else { + logger.ErrorWithFields(ctx, err, nil) + c.Error(errors.NewInternalServerError("Failed to update tenant agent config").WithDetails(err.Error())) + } + return + } + + logger.Infof(ctx, "Tenant agent config updated successfully, Tenant ID: %d", tenantID) + c.JSON(http.StatusOK, gin.H{ + "success": true, + "data": updatedTenant.AgentConfig, + "message": "Agent configuration updated successfully", + }) +} diff --git a/internal/models/chat/chat.go b/internal/models/chat/chat.go index 04d300d5..327e2c68 100644 --- a/internal/models/chat/chat.go +++ b/internal/models/chat/chat.go @@ -10,6 +10,19 @@ import ( "github.com/Tencent/WeKnora/internal/types" ) +// Tool represents a function/tool definition +type Tool struct { + Type string `json:"type"` // "function" + Function FunctionDef `json:"function"` +} + +// FunctionDef represents a function definition +type FunctionDef struct { + Name string `json:"name"` + Description string `json:"description"` + Parameters map[string]interface{} `json:"parameters"` +} + // ChatOptions 聊天选项 type ChatOptions struct { Temperature float64 `json:"temperature"` // 温度参数 @@ -20,12 +33,30 @@ type ChatOptions struct { FrequencyPenalty float64 `json:"frequency_penalty"` // 频率惩罚 PresencePenalty float64 `json:"presence_penalty"` // 存在惩罚 Thinking *bool `json:"thinking"` // 是否启用思考 + Tools []Tool `json:"tools,omitempty"` // 可用工具列表 + ToolChoice string `json:"tool_choice,omitempty"` // "auto", "required", "none", or specific tool } // Message 表示聊天消息 type Message struct { - Role string `json:"role"` // 角色:system, user, assistant - Content string `json:"content"` // 消息内容 + Role string `json:"role"` // 角色:system, user, assistant, tool + Content string `json:"content"` // 消息内容 + Name string `json:"name,omitempty"` // Function/tool name (for tool role) + ToolCallID string `json:"tool_call_id,omitempty"` // Tool call ID (for tool role) + ToolCalls []ToolCall `json:"tool_calls,omitempty"` // Tool calls (for assistant role) +} + +// ToolCall represents a tool call in a message +type ToolCall struct { + ID string `json:"id"` + Type string `json:"type"` // "function" + Function FunctionCall `json:"function"` +} + +// FunctionCall represents a function call +type FunctionCall struct { + Name string `json:"name"` + Arguments string `json:"arguments"` // JSON string } // Chat 定义了聊天接口 diff --git a/internal/models/chat/remote_api.go b/internal/models/chat/remote_api.go index 283dc14b..feba2032 100644 --- a/internal/models/chat/remote_api.go +++ b/internal/models/chat/remote_api.go @@ -8,6 +8,7 @@ import ( "net/http" "strings" + "github.com/Tencent/WeKnora/internal/logger" "github.com/Tencent/WeKnora/internal/types" "github.com/sashabaranov/go-openai" ) @@ -45,12 +46,40 @@ func NewRemoteAPIChat(chatConfig *ChatConfig) (*RemoteAPIChat, error) { // convertMessages 转换消息格式为OpenAI格式 func (c *RemoteAPIChat) convertMessages(messages []Message) []openai.ChatCompletionMessage { - openaiMessages := make([]openai.ChatCompletionMessage, len(messages)) - for i, msg := range messages { - openaiMessages[i] = openai.ChatCompletionMessage{ - Role: msg.Role, - Content: msg.Content, + openaiMessages := make([]openai.ChatCompletionMessage, 0, len(messages)) + for _, msg := range messages { + openaiMsg := openai.ChatCompletionMessage{ + Role: msg.Role, } + + // 处理内容:对于 assistant 角色,内容可能为空(当有 tool_calls 时) + if msg.Content != "" { + openaiMsg.Content = msg.Content + } + + // 处理 tool calls(assistant 角色) + if len(msg.ToolCalls) > 0 { + openaiMsg.ToolCalls = make([]openai.ToolCall, 0, len(msg.ToolCalls)) + for _, tc := range msg.ToolCalls { + toolType := openai.ToolType(tc.Type) + openaiMsg.ToolCalls = append(openaiMsg.ToolCalls, openai.ToolCall{ + ID: tc.ID, + Type: toolType, + Function: openai.FunctionCall{ + Name: tc.Function.Name, + Arguments: tc.Function.Arguments, + }, + }) + } + } + + // 处理 tool 角色消息(工具返回结果) + if msg.Role == "tool" { + openaiMsg.ToolCallID = msg.ToolCallID + openaiMsg.Name = msg.Name + } + + openaiMessages = append(openaiMessages, openaiMsg) } return openaiMessages } @@ -60,6 +89,11 @@ func (c *RemoteAPIChat) isAliyunQwen3Model() bool { return strings.HasPrefix(c.modelName, "qwen3-") && c.baseURL == "https://dashscope.aliyuncs.com/compatible-mode/v1" } +// isDeepSeekModel 检查是否为 DeepSeek 模型 +func (c *RemoteAPIChat) isDeepSeekModel() bool { + return strings.Contains(strings.ToLower(c.modelName), "deepseek") +} + // buildQwenChatCompletionRequest 构建 qwen 模型的聊天请求参数 func (c *RemoteAPIChat) buildQwenChatCompletionRequest(messages []Message, opts *ChatOptions, isStream bool, @@ -110,12 +144,68 @@ func (c *RemoteAPIChat) buildChatCompletionRequest(messages []Message, if opts.Thinking != nil { thinking = *opts.Thinking } + + // 处理 Tools(函数定义) + if len(opts.Tools) > 0 { + req.Tools = make([]openai.Tool, 0, len(opts.Tools)) + for _, tool := range opts.Tools { + toolType := openai.ToolType(tool.Type) + openaiTool := openai.Tool{ + Type: toolType, + Function: &openai.FunctionDefinition{ + Name: tool.Function.Name, + Description: tool.Function.Description, + }, + } + // 转换 Parameters (map[string]interface{} -> JSON Schema) + if tool.Function.Parameters != nil { + // Parameters 已经是 JSON Schema 格式的 map,直接使用 + openaiTool.Function.Parameters = tool.Function.Parameters + } + req.Tools = append(req.Tools, openaiTool) + } + } + + // 处理 ToolChoice + // ToolChoice 可以是字符串或 ToolChoice 对象 + // 对于 "auto", "none", "required" 直接使用字符串 + // 对于特定工具名称,使用 ToolChoice 对象 + // 注意:某些模型(如 DeepSeek)不支持 tool_choice,需要跳过设置 + if opts.ToolChoice != "" { + // DeepSeek 模型不支持 tool_choice,跳过设置(默认行为会自动使用工具) + if c.isDeepSeekModel() { + // 对于 DeepSeek,不设置 tool_choice,让 API 使用默认行为 + // 如果有 tools,DeepSeek 会自动使用 + logger.Infof(context.Background(), "deepseek model, skip tool_choice") + } else { + switch opts.ToolChoice { + case "none", "required", "auto": + // 直接使用字符串 + req.ToolChoice = opts.ToolChoice + default: + // 特定工具名称,使用 ToolChoice 对象 + req.ToolChoice = openai.ToolChoice{ + Type: "function", + Function: openai.ToolFunction{ + Name: opts.ToolChoice, + }, + } + } + } + } } req.ChatTemplateKwargs = map[string]interface{}{ "enable_thinking": thinking, } + // print req + jsonData, err := json.Marshal(req) + if err != nil { + logger.Error(context.Background(), "marshal request: %w", err) + } + logger.Infof(context.Background(), "llm request: %s", string(jsonData)) + return req } @@ -139,9 +229,10 @@ func (c *RemoteAPIChat) Chat(ctx context.Context, messages []Message, opts *Chat return nil, fmt.Errorf("no response from OpenAI") } - // 转换响应格式 - return &types.ChatResponse{ - Content: resp.Choices[0].Message.Content, + choice := resp.Choices[0] + response := &types.ChatResponse{ + Content: choice.Message.Content, + FinishReason: string(choice.FinishReason), Usage: struct { PromptTokens int `json:"prompt_tokens"` CompletionTokens int `json:"completion_tokens"` @@ -151,7 +242,24 @@ func (c *RemoteAPIChat) Chat(ctx context.Context, messages []Message, opts *Chat CompletionTokens: resp.Usage.CompletionTokens, TotalTokens: resp.Usage.TotalTokens, }, - }, nil + } + + // 转换 Tool Calls + if len(choice.Message.ToolCalls) > 0 { + response.ToolCalls = make([]types.LLMToolCall, 0, len(choice.Message.ToolCalls)) + for _, tc := range choice.Message.ToolCalls { + response.ToolCalls = append(response.ToolCalls, types.LLMToolCall{ + ID: tc.ID, + Type: string(tc.Type), + Function: types.FunctionCall{ + Name: tc.Function.Name, + Arguments: tc.Function.Arguments, + }, + }) + } + } + + return response, nil } // chatWithQwen 使用自定义请求处理 qwen 模型 @@ -201,9 +309,10 @@ func (c *RemoteAPIChat) chatWithQwen(ctx context.Context, messages []Message, op return nil, fmt.Errorf("no response from API") } - // 转换响应格式 - return &types.ChatResponse{ - Content: chatResp.Choices[0].Message.Content, + choice := chatResp.Choices[0] + response := &types.ChatResponse{ + Content: choice.Message.Content, + FinishReason: string(choice.FinishReason), Usage: struct { PromptTokens int `json:"prompt_tokens"` CompletionTokens int `json:"completion_tokens"` @@ -213,7 +322,24 @@ func (c *RemoteAPIChat) chatWithQwen(ctx context.Context, messages []Message, op CompletionTokens: chatResp.Usage.CompletionTokens, TotalTokens: chatResp.Usage.TotalTokens, }, - }, nil + } + + // 转换 Tool Calls + if len(choice.Message.ToolCalls) > 0 { + response.ToolCalls = make([]types.LLMToolCall, 0, len(choice.Message.ToolCalls)) + for _, tc := range choice.Message.ToolCalls { + response.ToolCalls = append(response.ToolCalls, types.LLMToolCall{ + ID: tc.ID, + Type: string(tc.Type), + Function: types.FunctionCall{ + Name: tc.Function.Name, + Arguments: tc.Function.Arguments, + }, + }) + } + } + + return response, nil } // ChatStream 进行流式聊天 @@ -238,20 +364,75 @@ func (c *RemoteAPIChat) ChatStream(ctx context.Context, defer close(streamChan) defer stream.Close() + var collectedToolCalls []types.LLMToolCall + for { response, err := stream.Recv() if err != nil { + // 发送最后一个响应,包含收集到的 tool calls streamChan <- types.StreamResponse{ ResponseType: types.ResponseTypeAnswer, + Content: "", Done: true, + ToolCalls: collectedToolCalls, } return } + if len(response.Choices) > 0 { - streamChan <- types.StreamResponse{ - ResponseType: types.ResponseTypeAnswer, - Content: response.Choices[0].Delta.Content, - Done: false, + delta := response.Choices[0].Delta + isDone := string(response.Choices[0].FinishReason) != "" + + // 收集 tool calls(流式响应中 tool calls 可能分多次返回) + if len(delta.ToolCalls) > 0 { + for _, tc := range delta.ToolCalls { + // 检查是否已经存在该 tool call(通过 index) + var toolCallIndex int + if tc.Index != nil { + toolCallIndex = *tc.Index + } + if toolCallIndex >= len(collectedToolCalls) { + // 新建 tool call + collectedToolCalls = append(collectedToolCalls, types.LLMToolCall{ + ID: tc.ID, + Type: string(tc.Type), + Function: types.FunctionCall{ + Name: tc.Function.Name, + Arguments: tc.Function.Arguments, + }, + }) + } else { + // 追加参数到已有的 tool call + collectedToolCalls[toolCallIndex].Function.Arguments += tc.Function.Arguments + // 更新 ID 和名称(如果提供了) + if tc.ID != "" { + collectedToolCalls[toolCallIndex].ID = tc.ID + } + if tc.Function.Name != "" { + collectedToolCalls[toolCallIndex].Function.Name = tc.Function.Name + } + } + } + } + + // 发送内容块 + if delta.Content != "" { + streamChan <- types.StreamResponse{ + ResponseType: types.ResponseTypeAnswer, + Content: delta.Content, + Done: isDone, + ToolCalls: collectedToolCalls, + } + } + + // 如果是最后一次响应,确保发送包含所有 tool calls 的响应 + if isDone && len(collectedToolCalls) > 0 { + streamChan <- types.StreamResponse{ + ResponseType: types.ResponseTypeAnswer, + Content: "", + Done: true, + ToolCalls: collectedToolCalls, + } } } } diff --git a/internal/models/utils/ollama/ollama.go b/internal/models/utils/ollama/ollama.go index 76b88ced..4cbe0229 100644 --- a/internal/models/utils/ollama/ollama.go +++ b/internal/models/utils/ollama/ollama.go @@ -8,6 +8,7 @@ import ( "os" "strings" "sync" + "time" "github.com/Tencent/WeKnora/internal/logger" "github.com/ollama/ollama/api" @@ -243,7 +244,15 @@ func (s *OllamaService) GetModelInfo(ctx context.Context, modelName string) (*ap return resp, nil } -// ListModels lists all available models +// OllamaModelInfo represents detailed information about an Ollama model +type OllamaModelInfo struct { + Name string `json:"name"` + Size int64 `json:"size"` + Digest string `json:"digest"` + ModifiedAt time.Time `json:"modified_at"` +} + +// ListModels lists all available models with basic info (names only) func (s *OllamaService) ListModels(ctx context.Context) ([]string, error) { listResp, err := s.client.List(ctx) if err != nil { @@ -258,6 +267,26 @@ func (s *OllamaService) ListModels(ctx context.Context) ([]string, error) { return modelNames, nil } +// ListModelsDetailed lists all available models with detailed information +func (s *OllamaService) ListModelsDetailed(ctx context.Context) ([]OllamaModelInfo, error) { + listResp, err := s.client.List(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get model list: %w", err) + } + + models := make([]OllamaModelInfo, len(listResp.Models)) + for i, model := range listResp.Models { + models[i] = OllamaModelInfo{ + Name: model.Name, + Size: model.Size, + Digest: model.Digest, + ModifiedAt: model.ModifiedAt, + } + } + + return models, nil +} + // DeleteModel deletes a model func (s *OllamaService) DeleteModel(ctx context.Context, modelName string) error { req := &api.DeleteRequest{ diff --git a/internal/router/router.go b/internal/router/router.go index 38785c8e..35754c63 100644 --- a/internal/router/router.go +++ b/internal/router/router.go @@ -192,6 +192,12 @@ func RegisterChatRoutes(r *gin.RouterGroup, handler *handler.SessionHandler) { knowledgeChat.POST("/:session_id", handler.KnowledgeQA) } + // Agent-based chat + agentChat := r.Group("/agent-chat") + { + agentChat.POST("/:session_id", handler.AgentQA) + } + // 新增知识检索接口,不需要session_id knowledgeSearch := r.Group("/knowledge-search") { @@ -209,6 +215,11 @@ func RegisterTenantRoutes(r *gin.RouterGroup, handler *handler.TenantHandler) { tenantRoutes.PUT("/:id", handler.UpdateTenant) tenantRoutes.DELETE("/:id", handler.DeleteTenant) tenantRoutes.GET("", handler.ListTenants) + + // Agent configuration management (tenant-level) + // Tenant ID is obtained from authentication context + tenantRoutes.GET("/agent-config", handler.GetTenantAgentConfig) + tenantRoutes.PUT("/agent-config", handler.UpdateTenantAgentConfig) } } diff --git a/internal/stream/memory_manager.go b/internal/stream/memory_manager.go index 3210eeac..21d25666 100644 --- a/internal/stream/memory_manager.go +++ b/internal/stream/memory_manager.go @@ -14,7 +14,7 @@ type memoryStreamInfo struct { sessionID string requestID string query string - content string + events []interfaces.StreamEvent knowledgeReferences types.References lastUpdated time.Time isCompleted bool @@ -54,19 +54,61 @@ func (m *MemoryStreamManager) RegisterStream(ctx context.Context, sessionID, req return nil } -// UpdateStream 更新流内容 -func (m *MemoryStreamManager) UpdateStream(ctx context.Context, - sessionID, requestID string, content string, references types.References, +// PushEvent 推送事件到流(追加模式) +func (m *MemoryStreamManager) PushEvent(ctx context.Context, + sessionID, requestID string, event interfaces.StreamEvent, ) error { m.mu.Lock() defer m.mu.Unlock() if sessionMap, exists := m.activeStreams[sessionID]; exists { if stream, found := sessionMap[requestID]; found { - stream.content += content - if len(references) > 0 { - stream.knowledgeReferences = references + stream.events = append(stream.events, event) + stream.lastUpdated = time.Now() + } + } + return nil +} + +// ReplaceEvent 通过 ID 替换事件(用于流式进度更新) +func (m *MemoryStreamManager) ReplaceEvent(ctx context.Context, + sessionID, requestID string, event interfaces.StreamEvent, +) error { + m.mu.Lock() + defer m.mu.Unlock() + + if sessionMap, exists := m.activeStreams[sessionID]; exists { + if stream, found := sessionMap[requestID]; found { + // 通过 ID 精确查找并替换 + replaced := false + for i := range stream.events { + if stream.events[i].ID == event.ID { + // 找到了,替换 + stream.events[i] = event + replaced = true + break + } } + // 没找到,追加 + if !replaced { + stream.events = append(stream.events, event) + } + stream.lastUpdated = time.Now() + } + } + return nil +} + +// UpdateReferences 更新知识引用 +func (m *MemoryStreamManager) UpdateReferences(ctx context.Context, + sessionID, requestID string, references types.References, +) error { + m.mu.Lock() + defer m.mu.Unlock() + + if sessionMap, exists := m.activeStreams[sessionID]; exists { + if stream, found := sessionMap[requestID]; found { + stream.knowledgeReferences = references stream.lastUpdated = time.Now() } } @@ -109,7 +151,7 @@ func (m *MemoryStreamManager) GetStream(ctx context.Context, SessionID: stream.sessionID, RequestID: stream.requestID, Query: stream.query, - Content: stream.content, + Events: stream.events, KnowledgeReferences: stream.knowledgeReferences, LastUpdated: stream.lastUpdated, IsCompleted: stream.isCompleted, diff --git a/internal/stream/redis_manager.go b/internal/stream/redis_manager.go index ec4e1387..fbe4d09f 100644 --- a/internal/stream/redis_manager.go +++ b/internal/stream/redis_manager.go @@ -13,13 +13,13 @@ import ( // redisStreamInfo Redis存储的流信息 type redisStreamInfo struct { - SessionID string `json:"session_id"` - RequestID string `json:"request_id"` - Query string `json:"query"` - Content string `json:"content"` - KnowledgeReferences types.References `json:"knowledge_references"` - LastUpdated time.Time `json:"last_updated"` - IsCompleted bool `json:"is_completed"` + SessionID string `json:"session_id"` + RequestID string `json:"request_id"` + Query string `json:"query"` + Events []interfaces.StreamEvent `json:"events"` + KnowledgeReferences types.References `json:"knowledge_references"` + LastUpdated time.Time `json:"last_updated"` + IsCompleted bool `json:"is_completed"` } // RedisStreamManager 基于Redis的流管理器实现 @@ -83,8 +83,8 @@ func (r *RedisStreamManager) RegisterStream(ctx context.Context, sessionID, requ return r.client.Set(ctx, key, data, r.ttl).Err() } -// UpdateStream 更新流内容 -func (r *RedisStreamManager) UpdateStream(ctx context.Context, sessionID, requestID string, content string, references types.References) error { +// PushEvent 推送事件到流 +func (r *RedisStreamManager) PushEvent(ctx context.Context, sessionID, requestID string, event interfaces.StreamEvent) error { key := r.buildKey(sessionID, requestID) // 获取当前数据 @@ -101,11 +101,84 @@ func (r *RedisStreamManager) UpdateStream(ctx context.Context, sessionID, reques return fmt.Errorf("解析流数据失败: %w", err) } - // 更新数据 - info.Content += content - if len(references) > 0 { - info.KnowledgeReferences = references + // 追加事件 + info.Events = append(info.Events, event) + info.LastUpdated = time.Now() + + // 保存回Redis + updatedData, err := json.Marshal(info) + if err != nil { + return fmt.Errorf("序列化更新的流信息失败: %w", err) } + + return r.client.Set(ctx, key, updatedData, r.ttl).Err() +} + +// ReplaceEvent 通过 ID 替换事件(用于流式进度更新) +func (r *RedisStreamManager) ReplaceEvent(ctx context.Context, sessionID, requestID string, event interfaces.StreamEvent) error { + key := r.buildKey(sessionID, requestID) + + // 获取当前数据 + data, err := r.client.Get(ctx, key).Bytes() + if err != nil { + if err == redis.Nil { + return nil // 键不存在,可能已过期 + } + return fmt.Errorf("获取流数据失败: %w", err) + } + + var info redisStreamInfo + if err := json.Unmarshal(data, &info); err != nil { + return fmt.Errorf("解析流数据失败: %w", err) + } + + // 通过 ID 精确查找并替换 + replaced := false + for i := range info.Events { + if info.Events[i].ID == event.ID { + // 找到了,替换 + info.Events[i] = event + replaced = true + break + } + } + + // 没找到,追加 + if !replaced { + info.Events = append(info.Events, event) + } + + info.LastUpdated = time.Now() + + // 保存回Redis + updatedData, err := json.Marshal(info) + if err != nil { + return fmt.Errorf("序列化更新的流信息失败: %w", err) + } + + return r.client.Set(ctx, key, updatedData, r.ttl).Err() +} + +// UpdateReferences 更新知识引用 +func (r *RedisStreamManager) UpdateReferences(ctx context.Context, sessionID, requestID string, references types.References) error { + key := r.buildKey(sessionID, requestID) + + // 获取当前数据 + data, err := r.client.Get(ctx, key).Bytes() + if err != nil { + if err == redis.Nil { + return nil // 键不存在,可能已过期 + } + return fmt.Errorf("获取流数据失败: %w", err) + } + + var info redisStreamInfo + if err := json.Unmarshal(data, &info); err != nil { + return fmt.Errorf("解析流数据失败: %w", err) + } + + // 更新知识引用 + info.KnowledgeReferences = references info.LastUpdated = time.Now() // 保存回Redis @@ -176,7 +249,7 @@ func (r *RedisStreamManager) GetStream(ctx context.Context, sessionID, requestID SessionID: info.SessionID, RequestID: info.RequestID, Query: info.Query, - Content: info.Content, + Events: info.Events, KnowledgeReferences: info.KnowledgeReferences, LastUpdated: info.LastUpdated, IsCompleted: info.IsCompleted, diff --git a/internal/types/agent.go b/internal/types/agent.go new file mode 100644 index 00000000..21a1bfbe --- /dev/null +++ b/internal/types/agent.go @@ -0,0 +1,110 @@ +package types + +import ( + "context" + "database/sql/driver" + "encoding/json" + "time" +) + +// AgentConfig represents the configuration for an agent session +type AgentConfig struct { + Enabled bool `json:"enabled"` // Whether agent mode is enabled + MaxIterations int `json:"max_iterations"` // Maximum number of ReAct iterations + ReflectionEnabled bool `json:"reflection_enabled"` // Whether to enable reflection + AllowedTools []string `json:"allowed_tools"` // List of allowed tool names + Temperature float64 `json:"temperature"` // LLM temperature for agent + ThinkingModelID string `json:"thinking_model_id"` // Model ID for reasoning + RerankModelID string `json:"rerank_model_id"` // Model ID for reranking search results + KnowledgeBases []string `json:"knowledge_bases"` // Accessible knowledge base IDs +} + +// Value implements driver.Valuer interface for AgentConfig +func (c AgentConfig) Value() (driver.Value, error) { + return json.Marshal(c) +} + +// Scan implements sql.Scanner interface for AgentConfig +func (c *AgentConfig) Scan(value interface{}) error { + if value == nil { + return nil + } + b, ok := value.([]byte) + if !ok { + return nil + } + return json.Unmarshal(b, c) +} + +// Tool defines the interface that all agent tools must implement +type Tool interface { + // Name returns the unique identifier for this tool + Name() string + + // Description returns a human-readable description of what the tool does + Description() string + + // Parameters returns the JSON Schema for the tool's parameters + Parameters() map[string]interface{} + + // Execute runs the tool with the given arguments + Execute(ctx context.Context, args map[string]interface{}) (*ToolResult, error) +} + +// ToolResult represents the result of a tool execution +type ToolResult struct { + Success bool `json:"success"` // Whether the tool executed successfully + Output string `json:"output"` // Human-readable output + Data map[string]interface{} `json:"data,omitempty"` // Structured data for programmatic use + Error string `json:"error,omitempty"` // Error message if execution failed +} + +// ToolCall represents a single tool invocation within an agent step +type ToolCall struct { + ID string `json:"id"` // Function call ID from LLM + Name string `json:"name"` // Tool name + Args map[string]interface{} `json:"args"` // Tool arguments + Result *ToolResult `json:"result"` // Execution result (contains Output) + Reflection string `json:"reflection,omitempty"` // Agent's reflection on this tool call result (if enabled) + Duration int64 `json:"duration"` // Execution time in milliseconds +} + +// AgentStep represents one iteration of the ReAct loop +type AgentStep struct { + Iteration int `json:"iteration"` // Iteration number (0-indexed) + Thought string `json:"thought"` // LLM's reasoning/thinking (Think phase) + ToolCalls []ToolCall `json:"tool_calls"` // Tools called in this step (Act phase) + Timestamp time.Time `json:"timestamp"` // When this step occurred +} + +// GetObservations returns observations from all tool calls in this step +// This is a convenience method to maintain backward compatibility +func (s *AgentStep) GetObservations() []string { + observations := make([]string, 0, len(s.ToolCalls)) + for _, tc := range s.ToolCalls { + if tc.Result != nil && tc.Result.Output != "" { + observations = append(observations, tc.Result.Output) + } + if tc.Reflection != "" { + observations = append(observations, "Reflection: "+tc.Reflection) + } + } + return observations +} + +// AgentState tracks the execution state of an agent across iterations +type AgentState struct { + CurrentRound int `json:"current_round"` // Current round number + RoundSteps []AgentStep `json:"round_steps"` // All steps taken so far in the current round + Plan []string `json:"plan,omitempty"` // Execution plan (if planning enabled) + IsComplete bool `json:"is_complete"` // Whether agent has finished + FinalAnswer string `json:"final_answer"` // The final answer to the query + KnowledgeRefs []*SearchResult `json:"knowledge_refs"` // Collected knowledge references +} + +// FunctionDefinition represents a function definition for LLM function calling +type FunctionDefinition struct { + Name string `json:"name"` + Description string `json:"description"` + Parameters map[string]interface{} `json:"parameters"` +} diff --git a/internal/types/chat.go b/internal/types/chat.go index 3229cd3a..eb6f5383 100644 --- a/internal/types/chat.go +++ b/internal/types/chat.go @@ -5,9 +5,26 @@ import ( "encoding/json" ) +// LLMToolCall represents a function/tool call from the LLM +type LLMToolCall struct { + ID string `json:"id"` + Type string `json:"type"` // "function" + Function FunctionCall `json:"function"` +} + +// FunctionCall represents the function details +type FunctionCall struct { + Name string `json:"name"` + Arguments string `json:"arguments"` // JSON string +} + // ChatResponse chat response type ChatResponse struct { Content string `json:"content"` + // Tool calls requested by the model + ToolCalls []LLMToolCall `json:"tool_calls,omitempty"` + // Finish reason + FinishReason string `json:"finish_reason,omitempty"` // "stop", "tool_calls", "length", etc. // Usage information Usage struct { // Prompt tokens @@ -27,6 +44,16 @@ const ( ResponseTypeAnswer ResponseType = "answer" // References response type ResponseTypeReferences ResponseType = "references" + // Thinking response type (for agent thought process) + ResponseTypeThinking ResponseType = "thinking" + // Tool call response type (for agent tool invocations) + ResponseTypeToolCall ResponseType = "tool_call" + // Tool result response type (for agent tool results) + ResponseTypeToolResult ResponseType = "tool_result" + // Error response type + ResponseTypeError ResponseType = "error" + // Reflection response type (for agent reflection) + ResponseTypeReflection ResponseType = "reflection" ) // StreamResponse stream response @@ -40,7 +67,11 @@ type StreamResponse struct { // Whether the response is complete Done bool `json:"done"` // Knowledge references - KnowledgeReferences References `json:"knowledge_references"` + KnowledgeReferences References `json:"knowledge_references,omitempty"` + // Tool calls for streaming (partial) + ToolCalls []LLMToolCall `json:"tool_calls,omitempty"` + // Additional metadata for enhanced display + Data map[string]interface{} `json:"data,omitempty"` } // References references diff --git a/internal/types/interfaces/agent.go b/internal/types/interfaces/agent.go new file mode 100644 index 00000000..f704b946 --- /dev/null +++ b/internal/types/interfaces/agent.go @@ -0,0 +1,33 @@ +package interfaces + +import ( + "context" + + "github.com/Tencent/WeKnora/internal/event" + "github.com/Tencent/WeKnora/internal/models/chat" + "github.com/Tencent/WeKnora/internal/types" +) + +// AgentStreamEvent represents a streaming event from the agent +type AgentStreamEvent struct { + Type string `json:"type"` // "thought", "tool_call", "tool_result", "final_answer", "error", "references" + Content string `json:"content"` // Incremental content + Data map[string]interface{} `json:"data"` // Additional structured data + Done bool `json:"done"` // Whether this is the last event + Iteration int `json:"iteration"` // Current iteration number +} + +// AgentEngine defines the interface for agent execution engine +type AgentEngine interface { + // ExecuteStreamWithHistory executes the agent with conversation history and returns a stream of events + Execute(ctx context.Context, sessionID, query string, llmContext []chat.Message) (*types.AgentState, error) +} + +// AgentService defines the interface for agent-related operations +type AgentService interface { + // CreateAgentEngine creates an agent engine with the given configuration and EventBus + CreateAgentEngine(ctx context.Context, config *types.AgentConfig, eventBus *event.EventBus) (AgentEngine, error) + + // ValidateConfig validates an agent configuration + ValidateConfig(config *types.AgentConfig) error +} diff --git a/internal/types/interfaces/chunk.go b/internal/types/interfaces/chunk.go index 81ea87b5..2d346c73 100644 --- a/internal/types/interfaces/chunk.go +++ b/internal/types/interfaces/chunk.go @@ -40,7 +40,7 @@ type ChunkService interface { // CreateChunks creates chunks CreateChunks(ctx context.Context, chunks []*types.Chunk) error // GetChunkByID gets a chunk by id - GetChunkByID(ctx context.Context, knowledgeID string, id string) (*types.Chunk, error) + GetChunkByID(ctx context.Context, id string) (*types.Chunk, error) // ListChunksByKnowledgeID lists chunks by knowledge id ListChunksByKnowledgeID(ctx context.Context, knowledgeID string) ([]*types.Chunk, error) // ListPagedChunksByKnowledgeID lists paged chunks by knowledge id diff --git a/internal/types/interfaces/context_manager.go b/internal/types/interfaces/context_manager.go new file mode 100644 index 00000000..5d57b9b5 --- /dev/null +++ b/internal/types/interfaces/context_manager.go @@ -0,0 +1,49 @@ +package interfaces + +import ( + "context" + + "github.com/Tencent/WeKnora/internal/models/chat" +) + +// ContextManager manages LLM context for sessions +// It maintains conversation context separately from message storage +// and provides context compression when context window is exceeded +type ContextManager interface { + // AddMessage adds a message to the session context + // The message will be added to the context window for LLM + AddMessage(ctx context.Context, sessionID string, message chat.Message) error + + // GetContext retrieves the current context for a session + // Returns messages that fit within the context window + // May apply compression if context is too large + GetContext(ctx context.Context, sessionID string) ([]chat.Message, error) + + // ClearContext clears all context for a session + ClearContext(ctx context.Context, sessionID string) error + + // GetContextStats returns statistics about the context + GetContextStats(ctx context.Context, sessionID string) (*ContextStats, error) +} + +// ContextStats contains statistics about session context +type ContextStats struct { + // Total number of messages in context + MessageCount int `json:"message_count"` + // Estimated token count + TokenCount int `json:"token_count"` + // Whether context was compressed + IsCompressed bool `json:"is_compressed"` + // Number of original messages before compression + OriginalMessageCount int `json:"original_message_count"` +} + +// CompressionStrategy defines how context should be compressed +type CompressionStrategy interface { + // Compress compresses messages when context exceeds limits + // Returns compressed messages that fit within the limit + Compress(ctx context.Context, messages []chat.Message, maxTokens int) ([]chat.Message, error) + + // EstimateTokens estimates token count for messages + EstimateTokens(messages []chat.Message) int +} diff --git a/internal/types/interfaces/model.go b/internal/types/interfaces/model.go index 7742222c..c1f60113 100644 --- a/internal/types/interfaces/model.go +++ b/internal/types/interfaces/model.go @@ -46,4 +46,6 @@ type ModelRepository interface { Update(ctx context.Context, model *types.Model) error // Delete deletes a model Delete(ctx context.Context, tenantID uint, id string) error + // ClearDefaultByType clears the default flag for all models of a specific type, optionally excluding a specific model ID + ClearDefaultByType(ctx context.Context, tenantID uint, modelType types.ModelType, excludeID string) error } diff --git a/internal/types/interfaces/session.go b/internal/types/interfaces/session.go index 1f5c5ab2..f9453679 100644 --- a/internal/types/interfaces/session.go +++ b/internal/types/interfaces/session.go @@ -3,6 +3,7 @@ package interfaces import ( "context" + "github.com/Tencent/WeKnora/internal/event" "github.com/Tencent/WeKnora/internal/types" ) @@ -30,6 +31,9 @@ type SessionService interface { KnowledgeQAByEvent(ctx context.Context, chatManage *types.ChatManage, eventList []types.EventType) error // SearchKnowledge performs knowledge-based search, without summarization SearchKnowledge(ctx context.Context, knowledgeBaseID, query string) ([]*types.SearchResult, error) + // AgentQA performs agent-based question answering with conversation history and streaming support + // eventBus is optional - if nil, uses service's default EventBus + AgentQA(ctx context.Context, session *types.Session, query string, assistantMessageID string, eventBus *event.EventBus) ([]*types.SearchResult, error) } // SessionRepository defines the session repository interface diff --git a/internal/types/interfaces/stream_manager.go b/internal/types/interfaces/stream_manager.go index d6a26ca3..362e51dd 100644 --- a/internal/types/interfaces/stream_manager.go +++ b/internal/types/interfaces/stream_manager.go @@ -7,12 +7,22 @@ import ( "github.com/Tencent/WeKnora/internal/types" ) +// StreamEvent represents a single event in the stream +type StreamEvent struct { + ID string `json:"id"` // Unique event ID for precise replacement + Type types.ResponseType `json:"type"` // Event type (thinking, tool_call, tool_result, etc.) + Content string `json:"content"` // Event content + Done bool `json:"done"` // Whether this event is done + Timestamp time.Time `json:"timestamp"` // When this event occurred + Data map[string]interface{} `json:"data,omitempty"` // Additional event data +} + // StreamInfo stream information type StreamInfo struct { SessionID string // session ID RequestID string // request ID Query string // query content - Content string // current content + Events []StreamEvent // all events in order (for replay on refresh) KnowledgeReferences types.References // knowledge references LastUpdated time.Time // last updated time IsCompleted bool // whether completed @@ -23,12 +33,19 @@ type StreamManager interface { // RegisterStream registers a new stream RegisterStream(ctx context.Context, sessionID, requestID, query string) error - // UpdateStream updates the stream content - UpdateStream(ctx context.Context, sessionID, requestID string, content string, references types.References) error + // PushEvent pushes an event to the stream (append mode) + PushEvent(ctx context.Context, sessionID, requestID string, event StreamEvent) error + + // ReplaceEvent replaces an event by ID (for streaming progress updates) + // If no matching event exists, it will append the event + ReplaceEvent(ctx context.Context, sessionID, requestID string, event StreamEvent) error + + // UpdateReferences updates knowledge references + UpdateReferences(ctx context.Context, sessionID, requestID string, references types.References) error // CompleteStream completes the stream CompleteStream(ctx context.Context, sessionID, requestID string) error - // GetStream gets a specific stream + // GetStream gets a specific stream (for replay on refresh) GetStream(ctx context.Context, sessionID, requestID string) (*StreamInfo, error) } diff --git a/internal/types/message.go b/internal/types/message.go index 21409e25..c54490da 100644 --- a/internal/types/message.go +++ b/internal/types/message.go @@ -2,6 +2,8 @@ package types import ( + "database/sql/driver" + "encoding/json" "time" "github.com/google/uuid" @@ -34,6 +36,10 @@ type Message struct { Role string `json:"role"` // References to knowledge chunks used in the response KnowledgeReferences References `json:"knowledge_references" gorm:"type:json,column:knowledge_references"` + // Agent execution steps (only for assistant messages generated by agent) + // This contains the detailed reasoning process and tool calls made by the agent + // Stored for user history display, but NOT included in LLM context to avoid redundancy + AgentSteps AgentSteps `json:"agent_steps,omitempty" gorm:"type:json,column:agent_steps"` // Whether message generation is complete IsCompleted bool `json:"is_completed"` // Message creation timestamp @@ -44,6 +50,32 @@ type Message struct { DeletedAt gorm.DeletedAt `json:"deleted_at" gorm:"index"` } +// AgentSteps represents a collection of agent execution steps +// Used for storing agent reasoning process in database +type AgentSteps []AgentStep + +// Value implements the driver.Valuer interface for database serialization +func (a AgentSteps) Value() (driver.Value, error) { + if a == nil { + return json.Marshal([]AgentStep{}) + } + return json.Marshal(a) +} + +// Scan implements the sql.Scanner interface for database deserialization +func (a *AgentSteps) Scan(value interface{}) error { + if value == nil { + *a = make(AgentSteps, 0) + return nil + } + b, ok := value.([]byte) + if !ok { + *a = make(AgentSteps, 0) + return nil + } + return json.Unmarshal(b, a) +} + // BeforeCreate is a GORM hook that runs before creating a new message record // Automatically generates a UUID for new messages and initializes knowledge references // Parameters: @@ -56,5 +88,8 @@ func (m *Message) BeforeCreate(tx *gorm.DB) (err error) { if m.KnowledgeReferences == nil { m.KnowledgeReferences = make(References, 0) } + if m.AgentSteps == nil { + m.AgentSteps = make(AgentSteps, 0) + } return nil } diff --git a/internal/types/session.go b/internal/types/session.go index 7d209ed1..0b8f8dd0 100644 --- a/internal/types/session.go +++ b/internal/types/session.go @@ -44,6 +44,30 @@ type SummaryConfig struct { MaxCompletionTokens int `json:"max_completion_tokens"` } +// ContextCompressionStrategy represents the strategy for context compression +type ContextCompressionStrategy string + +const ( + // ContextCompressionSlidingWindow keeps the most recent N messages + ContextCompressionSlidingWindow ContextCompressionStrategy = "sliding_window" + // ContextCompressionSmart uses LLM to summarize old messages + ContextCompressionSmart ContextCompressionStrategy = "smart" +) + +// ContextConfig configures LLM context management +// This is separate from message storage and manages token limits +type ContextConfig struct { + // Maximum tokens allowed in LLM context + MaxTokens int `json:"max_tokens"` + // Compression strategy: "sliding_window" or "smart" + CompressionStrategy ContextCompressionStrategy `json:"compression_strategy"` + // For sliding_window: number of messages to keep + // For smart: number of recent messages to keep uncompressed + RecentMessageCount int `json:"recent_message_count"` + // Enable context management (default: true) + Enabled bool `json:"enabled"` +} + // Session represents the session type Session struct { // ID @@ -69,6 +93,8 @@ type Session struct { RerankThreshold float64 `json:"rerank_threshold"` // 排序阈值 SummaryModelID string `json:"summary_model_id"` // 总结模型ID SummaryParameters *SummaryConfig `json:"summary_parameters" gorm:"type:json"` // 总结模型参数 + AgentConfig *AgentConfig `json:"agent_config" gorm:"type:json"` // Agent 配置(可选) + ContextConfig *ContextConfig `json:"context_config" gorm:"type:json"` // 上下文管理配置(可选) CreatedAt time.Time `json:"created_at"` UpdatedAt time.Time `json:"updated_at"` @@ -118,3 +144,20 @@ func (c *SummaryConfig) Scan(value interface{}) error { } return json.Unmarshal(b, c) } + +// Value implements the driver.Valuer interface, used to convert ContextConfig to database value +func (c *ContextConfig) Value() (driver.Value, error) { + return json.Marshal(c) +} + +// Scan implements the sql.Scanner interface, used to convert database value to ContextConfig +func (c *ContextConfig) Scan(value interface{}) error { + if value == nil { + return nil + } + b, ok := value.([]byte) + if !ok { + return nil + } + return json.Unmarshal(b, c) +} diff --git a/internal/types/tenant.go b/internal/types/tenant.go index 20e2e143..27efc124 100644 --- a/internal/types/tenant.go +++ b/internal/types/tenant.go @@ -8,10 +8,6 @@ import ( "gorm.io/gorm" ) -const ( - InitDefaultTenantID uint = 1 -) - // Tenant represents the tenant type Tenant struct { // ID @@ -32,6 +28,8 @@ type Tenant struct { StorageQuota int64 `yaml:"storage_quota" json:"storage_quota" gorm:"default:10737418240"` // Storage used (Bytes) StorageUsed int64 `yaml:"storage_used" json:"storage_used" gorm:"default:0"` + // Global Agent configuration for this tenant (default for all sessions) + AgentConfig *AgentConfig `yaml:"agent_config" json:"agent_config" gorm:"type:json"` // Creation time CreatedAt time.Time `yaml:"created_at" json:"created_at"` // Last updated time diff --git a/internal/utils/json.go b/internal/utils/json.go new file mode 100644 index 00000000..0070b469 --- /dev/null +++ b/internal/utils/json.go @@ -0,0 +1,11 @@ +package utils + +import "encoding/json" + +func ToJSON(v interface{}) string { + json, err := json.Marshal(v) + if err != nil { + return "" + } + return string(json) +} diff --git a/migrations/README.md b/migrations/README.md new file mode 100644 index 00000000..bed60d8a --- /dev/null +++ b/migrations/README.md @@ -0,0 +1,199 @@ +# 数据库迁移说明 + +## 📋 迁移文件列表 + +### MySQL +``` +mysql/ +├── 00-init-db.sql # ❗️初始化脚本(包含后期添加的字段) +├── 02-add-agent-config-if-missing.sql # ✅ 兼容性迁移(检查并添加缺失字段) +└── 03-cleanup-unreferenced-models.sql # 🧹 清理未引用模型(维护脚本) +``` + +### ParadeDB/PostgreSQL +``` +paradedb/ +├── 01-migrate-to-paradedb.sql # ❗️ParadeDB 初始化 +├── 02-add-agent-config-if-missing.sql # ✅ 兼容性迁移(检查并添加缺失字段) +└── 03-cleanup-unreferenced-models.sql # 🧹 清理未引用模型(维护脚本) +``` + +## ⚠️ 重要说明 + +### 关于 `agent_config` 等字段 + +你可能会注意到 `agent_config`、`context_config`、`agent_steps` 这些字段**同时出现在**: +- ✅ 初始化脚本中(`00-init-db.sql`) +- ✅ 迁移脚本中(`02-add-agent-config-if-missing.sql`) + +**这不是错误!** 这是为了兼容两种场景: + +#### 场景1: 全新安装 🆕 +运行 `00-init-db.sql` 时,会直接创建包含所有字段的表(包括 `agent_config`)。 +当运行 `02-add-agent-config-if-missing.sql` 时,会检测到字段已存在,跳过添加。 + +#### 场景2: 旧版本升级 ⬆️ +如果你的数据库是从旧版本(不包含 `agent_config` 的版本)升级: +- `00-init-db.sql` 早已运行过(但那时还没有 `agent_config` 字段) +- 运行 `02-add-agent-config-if-missing.sql` 时,会检测到字段不存在,然后添加 + +### 为什么会这样? + +根据 `AGENT_CONFIG_TENANT_REFACTORING.md` 文档,`agent_config` 是后来添加的功能。理论上: + +**❌ 不应该做的(但已经做了):** +```sql +-- 00-init-db.sql 被修改了,添加了后来才加的字段 +CREATE TABLE tenants ( + agent_config JSON DEFAULT NULL, -- 这个字段是后来加的! + ... +); +``` + +**✅ 应该做的:** +```sql +-- 00-init-db.sql(保持不变) +CREATE TABLE tenants ( + -- 没有 agent_config + ... +); + +-- 02-add-agent-config.sql(新文件) +ALTER TABLE tenants ADD COLUMN agent_config JSON DEFAULT NULL; +``` + +但由于初始化脚本已经被修改,我们创建了一个**智能的兼容性迁移脚本** `02-add-agent-config-if-missing.sql`,它: +- ✅ 检查字段是否存在 +- ✅ 只在字段不存在时才添加 +- ✅ 对新旧数据库都安全 + +## 🚀 使用方法 + +### 方法1: 全新部署 + +```bash +# 直接运行所有迁移 +./scripts/migrate.sh up + +# 结果: +# - 00-init-db.sql: 创建表(包含 agent_config) +# - 02-add-agent-config-if-missing.sql: 检测到字段已存在,跳过 +``` + +### 方法2: 从旧版本升级 + +```bash +# 运行新的迁移 +docker exec -i paradedb_container psql -U postgres -d WeKnora \ + < migrations/paradedb/02-add-agent-config-if-missing.sql + +# 结果: +# - 检测到 agent_config 不存在 +# - 添加 agent_config、context_config、agent_steps 字段 +# - 创建 GIN 索引提高查询性能 +``` + +### 方法3: 验证字段是否存在 + +#### MySQL +```sql +SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE, COLUMN_DEFAULT +FROM INFORMATION_SCHEMA.COLUMNS +WHERE TABLE_SCHEMA = 'WeKnora' + AND TABLE_NAME = 'tenants' + AND COLUMN_NAME = 'agent_config'; +``` + +#### PostgreSQL +```sql +SELECT column_name, data_type, is_nullable, column_default +FROM information_schema.columns +WHERE table_name = 'tenants' + AND column_name = 'agent_config'; +``` + +## 📝 涉及的字段 + +以下字段是通过 `02-add-agent-config-if-missing.sql` 处理的: + +### `tenants` 表 +- `agent_config` (JSON/JSONB): 租户级别的 Agent 配置 + +### `sessions` 表 +- `agent_config` (JSON/JSONB): 会话级别的 Agent 配置 +- `context_config` (JSON/JSONB): LLM 上下文管理配置 + +### `messages` 表 +- `agent_steps` (JSON/JSONB): Agent 执行步骤(推理过程和工具调用) + +## 🎯 最佳实践建议 + +### 对于新字段的添加 + +如果你需要添加新字段,**不要修改 `00-init-db.sql`**!应该: + +1. 创建新的迁移文件:`03-your-feature.sql` +2. 使用 `ALTER TABLE` 添加字段 +3. 使用 `IF NOT EXISTS` 确保幂等性 + +示例: +```sql +-- 03-add-new-feature.sql +ALTER TABLE tenants +ADD COLUMN IF NOT EXISTS new_field VARCHAR(255) DEFAULT NULL; +``` + +### 对于现有字段的修改 + +```sql +-- 04-modify-field.sql +ALTER TABLE tenants +MODIFY COLUMN existing_field TEXT NULL; +``` + +## 📚 更多信息 + +详细的迁移指南请参考:[MIGRATION_GUIDE.md](./MIGRATION_GUIDE.md) + +## 🧹 维护脚本 + +### 03-cleanup-unreferenced-models.sql + +**用途**: 清理数据库中未被任何知识库引用的模型 + +**清理条件**(必须同时满足): +- ❌ 未被 `knowledge_bases` 引用(embedding/summary/rerank/vlm 模型) +- ❌ 未被 `knowledges` 引用(embedding 模型) +- ❌ 非默认模型(`is_default = FALSE`) +- ❌ 非系统模型(`tenant_id != 0`) +- ❌ 未软删除(`deleted_at IS NULL`) + +**使用步骤**: +1. 📊 运行 DRY RUN 查询查看将被删除的模型 +2. 💾 备份数据库 +3. 🔄 选择软删除(推荐)或硬删除 +4. ✅ 验证结果 + +**详细说明**: 请查看 [CLEANUP_GUIDE.md](./CLEANUP_GUIDE.md) + +**⚠️ 重要**: +- 软删除可以回滚,硬删除不可逆 +- 建议先在测试环境验证 +- 可设置定时任务自动清理 + +## 🔗 相关文档 + +- `AGENT_CONFIG_TENANT_REFACTORING.md` - Agent 配置重构说明 +- `CONTEXT_MANAGER_IMPLEMENTATION.md` - 上下文管理器实现 +- `MIGRATION_GUIDE.md` - 完整的迁移指南 +- `CLEANUP_GUIDE.md` - 模型清理指南 🆕 + +--- + +**创建时间**: 2025-11-03 +**问题发现**: Agent Config 字段既在初始化脚本中,又应该在增量迁移中 +**解决方案**: 创建智能兼容性迁移脚本,同时支持新旧数据库 + +**更新时间**: 2025-11-03 +**新增功能**: 添加未引用模型清理脚本,支持软删除和硬删除 + diff --git a/migrations/mysql/00-init-db.sql b/migrations/mysql/00-init-db.sql index 357f4885..5f500dc7 100644 --- a/migrations/mysql/00-init-db.sql +++ b/migrations/mysql/00-init-db.sql @@ -16,6 +16,7 @@ CREATE TABLE tenants ( business VARCHAR(255) NOT NULL, storage_quota BIGINT NOT NULL DEFAULT 10737418240, storage_used BIGINT NOT NULL DEFAULT 0, + agent_config JSON DEFAULT NULL COMMENT 'Tenant-level agent configuration in JSON format', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, deleted_at TIMESTAMP NULL DEFAULT NULL @@ -104,6 +105,8 @@ CREATE TABLE sessions ( rerank_threshold FLOAT NOT NULL DEFAULT 0.65, summary_model_id VARCHAR(64), summary_parameters JSON NOT NULL, + agent_config JSON DEFAULT NULL COMMENT 'Session-level agent configuration in JSON format', + context_config JSON DEFAULT NULL COMMENT 'LLM context management configuration (separate from message storage)', created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, deleted_at TIMESTAMP NULL DEFAULT NULL @@ -118,6 +121,7 @@ CREATE TABLE messages ( role VARCHAR(50) NOT NULL, content TEXT NOT NULL, knowledge_references JSON NOT NULL, + agent_steps JSON DEFAULT NULL COMMENT 'Agent execution steps (reasoning process and tool calls)', is_completed BOOLEAN NOT NULL DEFAULT FALSE, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, diff --git a/migrations/mysql/02-add-agent-config-if-missing.sql b/migrations/mysql/02-add-agent-config-if-missing.sql new file mode 100644 index 00000000..05b49ab9 --- /dev/null +++ b/migrations/mysql/02-add-agent-config-if-missing.sql @@ -0,0 +1,114 @@ +-- 增量迁移:添加 agent_config 字段(如果不存在) +-- 创建时间:2025-11-03 +-- 目的:为旧版本数据库添加 agent_config 支持 +-- 注意:新数据库可能已经有这些字段(通过00-init-db.sql),使用 IF NOT EXISTS 确保兼容 + +-- ============================================ +-- 1. 为 tenants 表添加 agent_config +-- ============================================ + +-- 检查并添加字段 +SET @dbname = DATABASE(); +SET @tablename = 'tenants'; +SET @columnname = 'agent_config'; +SET @preparedStatement = (SELECT IF( + ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE + TABLE_SCHEMA = @dbname + AND TABLE_NAME = @tablename + AND COLUMN_NAME = @columnname + ) > 0, + 'SELECT 1', -- 字段已存在,不做任何操作 + CONCAT('ALTER TABLE ', @tablename, ' ADD COLUMN ', @columnname, ' JSON DEFAULT NULL COMMENT ''Tenant-level agent configuration in JSON format''') +)); + +PREPARE alterIfNotExists FROM @preparedStatement; +EXECUTE alterIfNotExists; +DEALLOCATE PREPARE alterIfNotExists; + +-- ============================================ +-- 2. 为 sessions 表添加 agent_config +-- ============================================ + +SET @dbname = DATABASE(); +SET @tablename = 'sessions'; +SET @columnname = 'agent_config'; +SET @preparedStatement = (SELECT IF( + ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE + TABLE_SCHEMA = @dbname + AND TABLE_NAME = @tablename + AND COLUMN_NAME = @columnname + ) > 0, + 'SELECT 1', -- 字段已存在,不做任何操作 + CONCAT('ALTER TABLE ', @tablename, ' ADD COLUMN ', @columnname, ' JSON DEFAULT NULL COMMENT ''Session-level agent configuration in JSON format''') +)); + +PREPARE alterIfNotExists FROM @preparedStatement; +EXECUTE alterIfNotExists; +DEALLOCATE PREPARE alterIfNotExists; + +-- ============================================ +-- 3. 为 sessions 表添加 context_config +-- ============================================ + +SET @dbname = DATABASE(); +SET @tablename = 'sessions'; +SET @columnname = 'context_config'; +SET @preparedStatement = (SELECT IF( + ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE + TABLE_SCHEMA = @dbname + AND TABLE_NAME = @tablename + AND COLUMN_NAME = @columnname + ) > 0, + 'SELECT 1', -- 字段已存在,不做任何操作 + CONCAT('ALTER TABLE ', @tablename, ' ADD COLUMN ', @columnname, ' JSON DEFAULT NULL COMMENT ''LLM context management configuration (separate from message storage)''') +)); + +PREPARE alterIfNotExists FROM @preparedStatement; +EXECUTE alterIfNotExists; +DEALLOCATE PREPARE alterIfNotExists; + +-- ============================================ +-- 4. 为 messages 表添加 agent_steps +-- ============================================ + +SET @dbname = DATABASE(); +SET @tablename = 'messages'; +SET @columnname = 'agent_steps'; +SET @preparedStatement = (SELECT IF( + ( + SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS + WHERE + TABLE_SCHEMA = @dbname + AND TABLE_NAME = @tablename + AND COLUMN_NAME = @columnname + ) > 0, + 'SELECT 1', -- 字段已存在,不做任何操作 + CONCAT('ALTER TABLE ', @tablename, ' ADD COLUMN ', @columnname, ' JSON DEFAULT NULL COMMENT ''Agent execution steps (reasoning process and tool calls)''') +)); + +PREPARE alterIfNotExists FROM @preparedStatement; +EXECUTE alterIfNotExists; +DEALLOCATE PREPARE alterIfNotExists; + +-- ============================================ +-- 验证:显示所有表的结构 +-- ============================================ + +SELECT 'Verifying tenants table...' as status; +SHOW COLUMNS FROM tenants LIKE 'agent_config'; + +SELECT 'Verifying sessions table...' as status; +SHOW COLUMNS FROM sessions LIKE 'agent_config'; +SHOW COLUMNS FROM sessions LIKE 'context_config'; + +SELECT 'Verifying messages table...' as status; +SHOW COLUMNS FROM messages LIKE 'agent_steps'; + +SELECT 'Migration completed successfully!' as status; + diff --git a/migrations/mysql/03-cleanup-unreferenced-models.sql b/migrations/mysql/03-cleanup-unreferenced-models.sql new file mode 100644 index 00000000..d40986f8 --- /dev/null +++ b/migrations/mysql/03-cleanup-unreferenced-models.sql @@ -0,0 +1,137 @@ +-- ============================================================================ +-- Migration: Cleanup Unreferenced Models +-- Description: Remove models that are not referenced by any knowledge base +-- Created: 2025-11-03 +-- ============================================================================ + +-- This script removes models from the models table that meet ALL of these conditions: +-- 1. Not referenced by any knowledge_bases (embedding_model_id, summary_model_id, rerank_model_id, vlm_model_id) +-- 2. Not referenced by any knowledges (embedding_model_id) +-- 3. Not a default model (is_default = false) +-- 4. Not a system model (tenant_id != 0) +-- 5. Not soft-deleted (deleted_at IS NULL) + +-- WARNING: This operation is irreversible. Make sure to backup your database before running. +-- Recommended: Run the SELECT query first to review which models will be deleted. + +-- ============================================================================ +-- Step 1: Review models that will be deleted (DRY RUN) +-- ============================================================================ +SELECT + m.id, + m.tenant_id, + m.name, + m.type, + m.source, + m.is_default, + m.status, + m.created_at +FROM models m +WHERE m.deleted_at IS NULL + AND m.is_default = FALSE + AND m.tenant_id != 0 + AND m.id NOT IN ( + -- Models referenced by knowledge_bases + SELECT DISTINCT embedding_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' + UNION + SELECT DISTINCT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' + UNION + SELECT DISTINCT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' + UNION + SELECT DISTINCT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' + UNION + -- Models referenced by knowledges + SELECT DISTINCT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' + ) +ORDER BY m.created_at DESC; + +-- ============================================================================ +-- Step 2: Soft delete unreferenced models (set deleted_at timestamp) +-- ============================================================================ +-- Uncomment the following line to perform soft delete: +-- UPDATE models m +-- SET deleted_at = CURRENT_TIMESTAMP +-- WHERE m.deleted_at IS NULL +-- AND m.is_default = FALSE +-- AND m.tenant_id != 0 +-- AND m.id NOT IN ( +-- SELECT DISTINCT embedding_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' +-- UNION +-- SELECT DISTINCT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' +-- UNION +-- SELECT DISTINCT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' +-- UNION +-- SELECT DISTINCT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' +-- UNION +-- SELECT DISTINCT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +-- ); + +-- ============================================================================ +-- Step 3: Hard delete unreferenced models (PERMANENT DELETION) +-- ============================================================================ +-- WARNING: This is permanent and cannot be undone! +-- Only use this if you're sure you want to permanently remove the records. +-- Uncomment the following line to perform hard delete: +-- DELETE FROM models +-- WHERE deleted_at IS NULL +-- AND is_default = FALSE +-- AND tenant_id != 0 +-- AND id NOT IN ( +-- SELECT DISTINCT embedding_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' +-- UNION +-- SELECT DISTINCT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' +-- UNION +-- SELECT DISTINCT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' +-- UNION +-- SELECT DISTINCT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' +-- UNION +-- SELECT DISTINCT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +-- ); + +-- ============================================================================ +-- Additional Queries for Statistics +-- ============================================================================ + +-- Count total models by type +SELECT + type, + COUNT(*) as total_count, + SUM(CASE WHEN is_default = TRUE THEN 1 ELSE 0 END) as default_count, + SUM(CASE WHEN deleted_at IS NULL THEN 1 ELSE 0 END) as active_count +FROM models +GROUP BY type; + +-- Count models referenced by knowledge bases +SELECT + 'embedding_model' as model_type, + COUNT(DISTINCT embedding_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND embedding_model_id != '' +UNION ALL +SELECT + 'summary_model' as model_type, + COUNT(DISTINCT summary_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND summary_model_id != '' +UNION ALL +SELECT + 'rerank_model' as model_type, + COUNT(DISTINCT rerank_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND rerank_model_id != '' +UNION ALL +SELECT + 'vlm_model' as model_type, + COUNT(DISTINCT vlm_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND vlm_model_id != ''; + +-- ============================================================================ +-- Rollback Strategy +-- ============================================================================ +-- If you performed a soft delete and need to rollback: +-- UPDATE models +-- SET deleted_at = NULL +-- WHERE deleted_at > 'YOUR_DELETION_TIMESTAMP'; +-- ============================================================================ + diff --git a/migrations/paradedb/00-init-db.sql b/migrations/paradedb/00-init-db.sql index 403f188a..1fa350ea 100644 --- a/migrations/paradedb/00-init-db.sql +++ b/migrations/paradedb/00-init-db.sql @@ -16,11 +16,14 @@ CREATE TABLE IF NOT EXISTS tenants ( business VARCHAR(255) NOT NULL, storage_quota BIGINT NOT NULL DEFAULT 10737418240, -- 默认10GB配额(Bytes) storage_used BIGINT NOT NULL DEFAULT 0, -- 已使用的存储空间(Bytes) + agent_config JSONB DEFAULT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, deleted_at TIMESTAMP WITH TIME ZONE ); +COMMENT ON COLUMN tenants.agent_config IS 'Tenant-level agent configuration in JSON format'; + -- Set the starting value for tenants id sequence ALTER SEQUENCE tenants_id_seq RESTART WITH 10000; @@ -122,11 +125,16 @@ CREATE TABLE IF NOT EXISTS sessions ( rerank_threshold FLOAT NOT NULL DEFAULT 0.65, summary_model_id VARCHAR(64), summary_parameters JSONB NOT NULL DEFAULT '{}', + agent_config JSONB DEFAULT NULL, + context_config JSONB DEFAULT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, deleted_at TIMESTAMP WITH TIME ZONE ); +COMMENT ON COLUMN sessions.agent_config IS 'Session-level agent configuration in JSON format'; +COMMENT ON COLUMN sessions.context_config IS 'LLM context management configuration (separate from message storage)'; + -- Create Index for sessions CREATE INDEX IF NOT EXISTS idx_sessions_tenant_id ON sessions(tenant_id); @@ -139,12 +147,15 @@ CREATE TABLE IF NOT EXISTS messages ( role VARCHAR(50) NOT NULL, content TEXT NOT NULL, knowledge_references JSONB NOT NULL DEFAULT '[]', + agent_steps JSONB DEFAULT NULL, is_completed BOOLEAN NOT NULL DEFAULT false, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, deleted_at TIMESTAMP WITH TIME ZONE ); +COMMENT ON COLUMN messages.agent_steps IS 'Agent execution steps (reasoning process and tool calls)'; + -- Create Index for messages CREATE INDEX IF NOT EXISTS idx_messages_session_id ON messages(session_id); diff --git a/migrations/paradedb/02-add-agent-config-if-missing.sql b/migrations/paradedb/02-add-agent-config-if-missing.sql new file mode 100644 index 00000000..5421163e --- /dev/null +++ b/migrations/paradedb/02-add-agent-config-if-missing.sql @@ -0,0 +1,173 @@ +-- 增量迁移:添加 agent_config 字段(如果不存在) +-- 创建时间:2025-11-03 +-- 目的:为旧版本数据库添加 agent_config 支持 +-- 注意:新数据库可能已经有这些字段(通过01-migrate-to-paradedb.sql),使用 IF NOT EXISTS 确保兼容 + +-- ============================================ +-- 1. 为 tenants 表添加 agent_config +-- ============================================ + +DO $$ +BEGIN + IF NOT EXISTS ( + SELECT 1 + FROM information_schema.columns + WHERE table_name = 'tenants' + AND column_name = 'agent_config' + ) THEN + ALTER TABLE tenants + ADD COLUMN agent_config JSONB DEFAULT NULL; + + COMMENT ON COLUMN tenants.agent_config IS 'Tenant-level agent configuration in JSON format'; + + RAISE NOTICE 'Added agent_config column to tenants table'; + ELSE + RAISE NOTICE 'agent_config column already exists in tenants table'; + END IF; +END $$; + +-- ============================================ +-- 2. 为 sessions 表添加 agent_config +-- ============================================ + +DO $$ +BEGIN + IF NOT EXISTS ( + SELECT 1 + FROM information_schema.columns + WHERE table_name = 'sessions' + AND column_name = 'agent_config' + ) THEN + ALTER TABLE sessions + ADD COLUMN agent_config JSONB DEFAULT NULL; + + COMMENT ON COLUMN sessions.agent_config IS 'Session-level agent configuration in JSON format'; + + RAISE NOTICE 'Added agent_config column to sessions table'; + ELSE + RAISE NOTICE 'agent_config column already exists in sessions table'; + END IF; +END $$; + +-- ============================================ +-- 3. 为 sessions 表添加 context_config +-- ============================================ + +DO $$ +BEGIN + IF NOT EXISTS ( + SELECT 1 + FROM information_schema.columns + WHERE table_name = 'sessions' + AND column_name = 'context_config' + ) THEN + ALTER TABLE sessions + ADD COLUMN context_config JSONB DEFAULT NULL; + + COMMENT ON COLUMN sessions.context_config IS 'LLM context management configuration (separate from message storage)'; + + RAISE NOTICE 'Added context_config column to sessions table'; + ELSE + RAISE NOTICE 'context_config column already exists in sessions table'; + END IF; +END $$; + +-- ============================================ +-- 4. 为 messages 表添加 agent_steps +-- ============================================ + +DO $$ +BEGIN + IF NOT EXISTS ( + SELECT 1 + FROM information_schema.columns + WHERE table_name = 'messages' + AND column_name = 'agent_steps' + ) THEN + ALTER TABLE messages + ADD COLUMN agent_steps JSONB DEFAULT NULL; + + COMMENT ON COLUMN messages.agent_steps IS 'Agent execution steps (reasoning process and tool calls)'; + + RAISE NOTICE 'Added agent_steps column to messages table'; + ELSE + RAISE NOTICE 'agent_steps column already exists in messages table'; + END IF; +END $$; + +-- ============================================ +-- 5. 为 JSON 字段添加 GIN 索引(提高查询性能) +-- ============================================ + +DO $$ +BEGIN + -- 为 tenants.agent_config 添加索引 + IF NOT EXISTS ( + SELECT 1 FROM pg_indexes + WHERE tablename = 'tenants' + AND indexname = 'idx_tenants_agent_config' + ) THEN + CREATE INDEX idx_tenants_agent_config ON tenants USING GIN (agent_config); + RAISE NOTICE 'Created index idx_tenants_agent_config'; + ELSE + RAISE NOTICE 'Index idx_tenants_agent_config already exists'; + END IF; + + -- 为 sessions.agent_config 添加索引 + IF NOT EXISTS ( + SELECT 1 FROM pg_indexes + WHERE tablename = 'sessions' + AND indexname = 'idx_sessions_agent_config' + ) THEN + CREATE INDEX idx_sessions_agent_config ON sessions USING GIN (agent_config); + RAISE NOTICE 'Created index idx_sessions_agent_config'; + ELSE + RAISE NOTICE 'Index idx_sessions_agent_config already exists'; + END IF; + + -- 为 sessions.context_config 添加索引 + IF NOT EXISTS ( + SELECT 1 FROM pg_indexes + WHERE tablename = 'sessions' + AND indexname = 'idx_sessions_context_config' + ) THEN + CREATE INDEX idx_sessions_context_config ON sessions USING GIN (context_config); + RAISE NOTICE 'Created index idx_sessions_context_config'; + ELSE + RAISE NOTICE 'Index idx_sessions_context_config already exists'; + END IF; + + -- 为 messages.agent_steps 添加索引 + IF NOT EXISTS ( + SELECT 1 FROM pg_indexes + WHERE tablename = 'messages' + AND indexname = 'idx_messages_agent_steps' + ) THEN + CREATE INDEX idx_messages_agent_steps ON messages USING GIN (agent_steps); + RAISE NOTICE 'Created index idx_messages_agent_steps'; + ELSE + RAISE NOTICE 'Index idx_messages_agent_steps already exists'; + END IF; +END $$; + +-- ============================================ +-- 验证:显示所有表的字段 +-- ============================================ + +SELECT 'Verifying tenants table...' as status; +SELECT column_name, data_type, is_nullable, column_default +FROM information_schema.columns +WHERE table_name = 'tenants' AND column_name = 'agent_config'; + +SELECT 'Verifying sessions table...' as status; +SELECT column_name, data_type, is_nullable, column_default +FROM information_schema.columns +WHERE table_name = 'sessions' AND column_name IN ('agent_config', 'context_config'); + +SELECT 'Verifying messages table...' as status; +SELECT column_name, data_type, is_nullable, column_default +FROM information_schema.columns +WHERE table_name = 'messages' AND column_name = 'agent_steps'; + +SELECT 'Migration completed successfully!' as status; + diff --git a/migrations/paradedb/03-cleanup-unreferenced-models.sql b/migrations/paradedb/03-cleanup-unreferenced-models.sql new file mode 100644 index 00000000..78cdb443 --- /dev/null +++ b/migrations/paradedb/03-cleanup-unreferenced-models.sql @@ -0,0 +1,228 @@ +-- ============================================================================ +-- Migration: Cleanup Unreferenced Models (PostgreSQL/ParadeDB) +-- Description: Remove models that are not referenced by any knowledge base +-- Created: 2025-11-03 +-- ============================================================================ + +-- This script removes models from the models table that meet ALL of these conditions: +-- 1. Not referenced by any knowledge_bases (embedding_model_id, summary_model_id, rerank_model_id, vlm_model_id) +-- 2. Not referenced by any knowledges (embedding_model_id) +-- 3. Not a default model (is_default = false) +-- 4. Not a system model (tenant_id != 0) +-- 5. Not soft-deleted (deleted_at IS NULL) + +-- WARNING: This operation is irreversible. Make sure to backup your database before running. +-- Recommended: Run the SELECT query first to review which models will be deleted. + +-- ============================================================================ +-- Step 1: Review models that will be deleted (DRY RUN) +-- ============================================================================ +SELECT + m.id, + m.tenant_id, + m.name, + m.type, + m.source, + m.is_default, + m.status, + m.created_at +FROM models m +WHERE m.deleted_at IS NULL + AND m.is_default = FALSE + AND m.id NOT IN ( + -- Models referenced by knowledge_bases + SELECT DISTINCT embedding_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' + UNION + SELECT DISTINCT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' + UNION + SELECT DISTINCT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' + UNION + SELECT DISTINCT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' + UNION + -- Models referenced by knowledges + SELECT DISTINCT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' + ) +ORDER BY m.created_at DESC; + +-- ============================================================================ +-- Step 2: Soft delete unreferenced models (set deleted_at timestamp) +-- ============================================================================ +-- Uncomment the following line to perform soft delete: +-- UPDATE models m +-- SET deleted_at = CURRENT_TIMESTAMP +-- WHERE m.deleted_at IS NULL +-- AND m.is_default = FALSE +-- AND m.tenant_id != 0 +-- AND m.id NOT IN ( +-- SELECT DISTINCT embedding_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' +-- UNION +-- SELECT DISTINCT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' +-- UNION +-- SELECT DISTINCT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' +-- UNION +-- SELECT DISTINCT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' +-- UNION +-- SELECT DISTINCT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +-- ); + +-- ============================================================================ +-- Step 3: Hard delete unreferenced models (PERMANENT DELETION) +-- ============================================================================ +-- WARNING: This is permanent and cannot be undone! +-- Only use this if you're sure you want to permanently remove the records. +-- Uncomment the following line to perform hard delete: +-- DELETE FROM models +-- WHERE deleted_at IS NULL +-- AND is_default = FALSE +-- AND tenant_id != 0 +-- AND id NOT IN ( +-- SELECT DISTINCT embedding_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' +-- UNION +-- SELECT DISTINCT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' +-- UNION +-- SELECT DISTINCT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' +-- UNION +-- SELECT DISTINCT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' +-- UNION +-- SELECT DISTINCT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +-- ); + +-- ============================================================================ +-- Alternative: Using CTE for better performance (PostgreSQL specific) +-- ============================================================================ +-- This version uses Common Table Expressions for better readability and performance + +-- DRY RUN with CTE: +WITH referenced_models AS ( + SELECT embedding_model_id AS model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' + UNION + SELECT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' + UNION + SELECT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' + UNION + SELECT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' + UNION + SELECT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +) +SELECT + m.id, + m.tenant_id, + m.name, + m.type, + m.source, + m.is_default, + m.status, + m.created_at +FROM models m +WHERE m.deleted_at IS NULL + AND m.is_default = FALSE + AND m.id NOT IN (SELECT model_id FROM referenced_models) +ORDER BY m.created_at DESC; + +-- Soft delete with CTE: +WITH referenced_models AS ( + SELECT embedding_model_id AS model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' + UNION + SELECT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' + UNION + SELECT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' + UNION + SELECT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' + UNION + SELECT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +) +UPDATE models m +SET deleted_at = CURRENT_TIMESTAMP +WHERE m.deleted_at IS NULL + AND m.is_default = FALSE + AND m.id NOT IN (SELECT model_id FROM referenced_models); + +-- Hard delete with CTE: +-- WITH referenced_models AS ( +-- SELECT embedding_model_id AS model_id FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' +-- UNION +-- SELECT summary_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' +-- UNION +-- SELECT rerank_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' +-- UNION +-- SELECT vlm_model_id FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' +-- UNION +-- SELECT embedding_model_id FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +-- ) +-- DELETE FROM models +-- WHERE deleted_at IS NULL +-- AND is_default = FALSE +-- AND tenant_id != 0 +-- AND id NOT IN (SELECT model_id FROM referenced_models); + +-- ============================================================================ +-- Additional Queries for Statistics +-- ============================================================================ + +-- Count total models by type +SELECT + type, + COUNT(*) as total_count, + SUM(CASE WHEN is_default = TRUE THEN 1 ELSE 0 END) as default_count, + SUM(CASE WHEN deleted_at IS NULL THEN 1 ELSE 0 END) as active_count +FROM models +GROUP BY type; + +-- Count models referenced by knowledge bases +SELECT + 'embedding_model' as model_type, + COUNT(DISTINCT embedding_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND embedding_model_id != '' +UNION ALL +SELECT + 'summary_model' as model_type, + COUNT(DISTINCT summary_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND summary_model_id != '' +UNION ALL +SELECT + 'rerank_model' as model_type, + COUNT(DISTINCT rerank_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND rerank_model_id != '' +UNION ALL +SELECT + 'vlm_model' as model_type, + COUNT(DISTINCT vlm_model_id) as referenced_count +FROM knowledge_bases +WHERE deleted_at IS NULL AND vlm_model_id != ''; + +-- List all referenced models with their reference count +WITH model_references AS ( + SELECT embedding_model_id AS model_id, 'embedding' AS ref_type FROM knowledge_bases WHERE deleted_at IS NULL AND embedding_model_id != '' + UNION ALL + SELECT summary_model_id, 'summary' FROM knowledge_bases WHERE deleted_at IS NULL AND summary_model_id != '' + UNION ALL + SELECT rerank_model_id, 'rerank' FROM knowledge_bases WHERE deleted_at IS NULL AND rerank_model_id != '' + UNION ALL + SELECT vlm_model_id, 'vlm' FROM knowledge_bases WHERE deleted_at IS NULL AND vlm_model_id != '' + UNION ALL + SELECT embedding_model_id, 'knowledge_embedding' FROM knowledges WHERE deleted_at IS NULL AND embedding_model_id IS NOT NULL AND embedding_model_id != '' +) +SELECT + m.id, + m.name, + m.type, + STRING_AGG(DISTINCT mr.ref_type, ', ' ORDER BY mr.ref_type) AS referenced_as, + COUNT(*) AS reference_count +FROM models m +INNER JOIN model_references mr ON m.id = mr.model_id +WHERE m.deleted_at IS NULL +GROUP BY m.id, m.name, m.type +ORDER BY reference_count DESC, m.name; + +-- ============================================================================ +-- Rollback Strategy +-- ============================================================================ +-- If you performed a soft delete and need to rollback: +-- UPDATE models +-- SET deleted_at = NULL +-- WHERE deleted_at > 'YOUR_DELETION_TIMESTAMP'; +-- ============================================================================ + diff --git a/scripts/migrate.sh b/scripts/migrate.sh old mode 100644 new mode 100755 diff --git a/test_agent_config.sh b/test_agent_config.sh new file mode 100755 index 00000000..e355e75d --- /dev/null +++ b/test_agent_config.sh @@ -0,0 +1,148 @@ +#!/bin/bash + +# Agent 配置功能测试脚本 + +set -e + +echo "=========================================" +echo "Agent 配置功能测试" +echo "=========================================" +echo "" + +# 颜色定义 +GREEN='\033[0;32m' +RED='\033[0;31m' +YELLOW='\033[1;33m' +NC='\033[0m' # No Color + +# 配置 +API_BASE_URL="http://localhost:8080" +KB_ID="kb-00000001" # 修改为你的知识库ID +TENANT_ID="1" + +echo "配置信息:" +echo " API地址: ${API_BASE_URL}" +echo " 知识库ID: ${KB_ID}" +echo " 租户ID: ${TENANT_ID}" +echo "" + +# 测试 1:获取当前配置 +echo -e "${YELLOW}测试 1: 获取当前配置${NC}" +echo "GET ${API_BASE_URL}/api/v1/initialization/config/${KB_ID}" +RESPONSE=$(curl -s -X GET "${API_BASE_URL}/api/v1/initialization/config/${KB_ID}") +echo "响应:" +echo "$RESPONSE" | jq '.data.agent' || echo "$RESPONSE" +echo "" + +# 测试 2:保存 Agent 配置 +echo -e "${YELLOW}测试 2: 保存 Agent 配置${NC}" +echo "POST ${API_BASE_URL}/api/v1/initialization/initialize/${KB_ID}" + +# 准备测试数据(需要包含完整的配置) +TEST_DATA='{ + "llm": { + "source": "local", + "modelName": "qwen3:0.6b", + "baseUrl": "", + "apiKey": "" + }, + "embedding": { + "source": "local", + "modelName": "nomic-embed-text:latest", + "baseUrl": "", + "apiKey": "", + "dimension": 768 + }, + "rerank": { + "enabled": false + }, + "multimodal": { + "enabled": false + }, + "documentSplitting": { + "chunkSize": 512, + "chunkOverlap": 100, + "separators": ["\n\n", "\n", "。", "!", "?", ";", ";"] + }, + "nodeExtract": { + "enabled": false + }, + "agent": { + "enabled": true, + "maxIterations": 8, + "temperature": 0.8, + "thinkingModelId": "", + "allowedTools": ["knowledge_search", "multi_kb_search", "list_knowledge_bases"] + } +}' + +RESPONSE=$(curl -s -X POST "${API_BASE_URL}/api/v1/initialization/initialize/${KB_ID}" \ + -H "Content-Type: application/json" \ + -d "$TEST_DATA") + +if echo "$RESPONSE" | grep -q '"success":true'; then + echo -e "${GREEN}✓ Agent 配置保存成功${NC}" + echo "$RESPONSE" | jq '.' || echo "$RESPONSE" +else + echo -e "${RED}✗ Agent 配置保存失败${NC}" + echo "$RESPONSE" +fi +echo "" + +# 等待一下,确保数据已保存 +sleep 1 + +# 测试 3:验证配置已保存 +echo -e "${YELLOW}测试 3: 验证配置已保存${NC}" +echo "GET ${API_BASE_URL}/api/v1/initialization/config/${KB_ID}" +RESPONSE=$(curl -s -X GET "${API_BASE_URL}/api/v1/initialization/config/${KB_ID}") +AGENT_CONFIG=$(echo "$RESPONSE" | jq '.data.agent') + +echo "Agent 配置:" +echo "$AGENT_CONFIG" | jq '.' + +# 检查配置是否正确 +ENABLED=$(echo "$AGENT_CONFIG" | jq -r '.enabled') +MAX_ITER=$(echo "$AGENT_CONFIG" | jq -r '.maxIterations') +TEMP=$(echo "$AGENT_CONFIG" | jq -r '.temperature') + +if [ "$ENABLED" == "true" ] && [ "$MAX_ITER" == "8" ] && [ "$TEMP" == "0.8" ]; then + echo -e "${GREEN}✓ 配置验证成功 - 所有值正确${NC}" +else + echo -e "${RED}✗ 配置验证失败${NC}" + echo " enabled: $ENABLED (期望: true)" + echo " maxIterations: $MAX_ITER (期望: 8)" + echo " temperature: $TEMP (期望: 0.8)" +fi +echo "" + +# 测试 4:使用 Tenant API 获取配置 +echo -e "${YELLOW}测试 4: 使用 Tenant API 获取配置${NC}" +echo "GET ${API_BASE_URL}/api/v1/tenants/${TENANT_ID}/agent-config" +RESPONSE=$(curl -s -X GET "${API_BASE_URL}/api/v1/tenants/${TENANT_ID}/agent-config") +echo "响应:" +echo "$RESPONSE" | jq '.' || echo "$RESPONSE" +echo "" + +# 测试 5:数据库验证(如果可以访问) +echo -e "${YELLOW}测试 5: 数据库验证${NC}" +echo "提示: 请手动运行以下 SQL 查询验证数据:" +echo "" +echo "MySQL:" +echo " mysql -u root -p weknora -e \"SELECT id, agent_config FROM tenants WHERE id = ${TENANT_ID};\"" +echo "" +echo "PostgreSQL:" +echo " psql -U postgres -d weknora -c \"SELECT id, agent_config FROM tenants WHERE id = ${TENANT_ID};\"" +echo "" + +echo "=========================================" +echo "测试完成!" +echo "=========================================" +echo "" +echo "如果所有测试都通过,Agent 配置功能已正常工作。" +echo "如果有测试失败,请检查:" +echo " 1. 后端服务是否正在运行" +echo " 2. 数据库迁移是否已执行" +echo " 3. 知识库ID是否正确" +echo "" +