feat(backend): add RAG pipeline progress events

Emit query-understanding and knowledge-search progress over SSE, emit
references before stream completion, and wire progress into session QA.
This commit is contained in:
wizardchen
2026-06-16 00:49:20 +08:00
committed by lyingbug
parent 2906c6656e
commit 9e916839ef
5 changed files with 372 additions and 70 deletions
@@ -0,0 +1,209 @@
package chatpipeline
import (
"context"
"fmt"
"time"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/types"
"github.com/google/uuid"
)
const (
retrievalProgressTool = "knowledge_search"
queryUnderstandProgressTool = "query_understand"
)
// StageProgress tracks an in-flight pipeline progress tool_call.
type StageProgress struct {
toolCallID string
toolName string
}
// ShouldEmitQueryUnderstandProgress reports whether the query-understand stage
// will actually run (rewrite enabled or images attached).
func ShouldEmitQueryUnderstandProgress(chatManage *types.ChatManage) bool {
if chatManage == nil {
return false
}
return chatManage.EnableRewrite || len(chatManage.Images) > 0
}
// IsConsolidatedRetrievalStage reports whether a pipeline stage belongs to the
// single user-visible "knowledge search" progress window (search → rerank → merge).
func IsConsolidatedRetrievalStage(stage types.EventType, chatManage *types.ChatManage) bool {
if chatManage == nil {
return false
}
switch stage {
case types.CHUNK_SEARCH_PARALLEL, types.CHUNK_RERANK, types.CHUNK_MERGE, types.FILTER_TOP_K:
return chatManage.NeedsRetrieval()
case types.WEB_FETCH:
return chatManage.WebSearchEnabled
case types.DATA_ANALYSIS:
return chatManage.DataAnalysisEnabled && chatManage.NeedsRetrieval()
default:
return false
}
}
// LastConsolidatedRetrievalStage returns the last retrieval-related stage in the
// assembled pipeline, or empty when none apply.
func LastConsolidatedRetrievalStage(eventList []types.EventType, chatManage *types.ChatManage) types.EventType {
var last types.EventType
for _, stage := range eventList {
if IsConsolidatedRetrievalStage(stage, chatManage) {
last = stage
}
}
return last
}
// BeginRetrievalProgress emits a single pending knowledge_search tool_call.
func BeginRetrievalProgress(ctx context.Context, chatManage *types.ChatManage) *StageProgress {
if chatManage == nil || chatManage.EventBus == nil {
return nil
}
toolCallID := uuid.New().String()
args := map[string]any{}
if chatManage.RewriteQuery != "" {
args["query"] = chatManage.RewriteQuery
} else if chatManage.Query != "" {
args["query"] = chatManage.Query
}
_ = chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolCall),
SessionID: chatManage.SessionID,
Data: event.AgentToolCallData{
ToolCallID: toolCallID,
ToolName: retrievalProgressTool,
Arguments: args,
},
})
return &StageProgress{toolCallID: toolCallID, toolName: retrievalProgressTool}
}
// BeginQueryUnderstandProgress emits a pending query_understand tool_call.
func BeginQueryUnderstandProgress(ctx context.Context, chatManage *types.ChatManage) *StageProgress {
if chatManage == nil || chatManage.EventBus == nil || !ShouldEmitQueryUnderstandProgress(chatManage) {
return nil
}
toolCallID := uuid.New().String()
args := map[string]any{}
if chatManage.Query != "" {
args["query"] = chatManage.Query
}
if len(chatManage.Images) > 0 {
args["has_images"] = true
}
_ = chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolCall),
SessionID: chatManage.SessionID,
Data: event.AgentToolCallData{
ToolCallID: toolCallID,
ToolName: queryUnderstandProgressTool,
Arguments: args,
},
})
return &StageProgress{toolCallID: toolCallID, toolName: queryUnderstandProgressTool}
}
// EndQueryUnderstandProgress emits the matching tool_result for query understanding.
func EndQueryUnderstandProgress(
ctx context.Context,
chatManage *types.ChatManage,
progress *StageProgress,
start time.Time,
stageErr *PluginError,
) {
if progress == nil || chatManage == nil || chatManage.EventBus == nil {
return
}
success := stageErr == nil
output := ""
if success {
output = "已完成问题理解"
}
var errMsg string
if !success && stageErr != nil && stageErr.Err != nil {
errMsg = stageErr.Err.Error()
}
_ = chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolResult),
SessionID: chatManage.SessionID,
Data: event.AgentToolResultData{
ToolCallID: progress.toolCallID,
ToolName: queryUnderstandProgressTool,
Output: output,
Error: errMsg,
Success: success,
Duration: time.Since(start).Milliseconds(),
},
})
}
// EndRetrievalProgress emits the matching tool_result for the consolidated retrieval window.
func EndRetrievalProgress(
ctx context.Context,
chatManage *types.ChatManage,
progress *StageProgress,
start time.Time,
stageErr *PluginError,
) {
if progress == nil || chatManage == nil || chatManage.EventBus == nil {
return
}
count := retrievalResultCount(chatManage)
success := stageErr == nil || stageErr == ErrSearchNothing
output := ""
if success {
if count == 0 {
output = "未检索到相关内容"
} else {
output = fmt.Sprintf("检索到 %d 条相关内容", count)
}
}
var errMsg string
if !success && stageErr != nil && stageErr.Err != nil {
errMsg = stageErr.Err.Error()
}
_ = chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolResult),
SessionID: chatManage.SessionID,
Data: event.AgentToolResultData{
ToolCallID: progress.toolCallID,
ToolName: retrievalProgressTool,
Output: output,
Error: errMsg,
Success: success,
Duration: time.Since(start).Milliseconds(),
Data: map[string]interface{}{
"count": count,
},
},
})
}
func retrievalResultCount(chatManage *types.ChatManage) int {
switch {
case len(chatManage.MergeResult) > 0:
return len(chatManage.MergeResult)
case len(chatManage.RerankResult) > 0:
return len(chatManage.RerankResult)
default:
return len(chatManage.SearchResult)
}
}
@@ -0,0 +1,103 @@
package chatpipeline
import (
"context"
"testing"
"time"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
type recordingEventBus struct {
events []types.Event
}
func (b *recordingEventBus) On(types.EventType, types.EventHandler) {}
func (b *recordingEventBus) Emit(_ context.Context, evt types.Event) error {
b.events = append(b.events, evt)
return nil
}
func TestIsConsolidatedRetrievalStage(t *testing.T) {
cm := &types.ChatManage{}
assert.True(t, IsConsolidatedRetrievalStage(types.CHUNK_SEARCH_PARALLEL, cm))
assert.False(t, IsConsolidatedRetrievalStage(types.QUERY_UNDERSTAND, cm))
assert.False(t, IsConsolidatedRetrievalStage(types.LOAD_HISTORY, cm))
}
func TestLastConsolidatedRetrievalStage(t *testing.T) {
cm := &types.ChatManage{}
pipeline := []types.EventType{
types.LOAD_HISTORY,
types.QUERY_UNDERSTAND,
types.CHUNK_SEARCH_PARALLEL,
types.CHUNK_RERANK,
types.CHUNK_MERGE,
types.FILTER_TOP_K,
types.INTO_CHAT_MESSAGE,
types.CHAT_COMPLETION_STREAM,
}
assert.Equal(t, types.FILTER_TOP_K, LastConsolidatedRetrievalStage(pipeline, cm))
}
func TestShouldEmitQueryUnderstandProgress(t *testing.T) {
cm := &types.ChatManage{PipelineRequest: types.PipelineRequest{EnableRewrite: true}}
assert.True(t, ShouldEmitQueryUnderstandProgress(cm))
cm.EnableRewrite = false
assert.False(t, ShouldEmitQueryUnderstandProgress(cm))
cm.Images = []string{"data:image/png;base64,abc"}
assert.True(t, ShouldEmitQueryUnderstandProgress(cm))
}
func TestQueryUnderstandProgressEmitsToolCallAndResult(t *testing.T) {
bus := &recordingEventBus{}
cm := &types.ChatManage{
PipelineRequest: types.PipelineRequest{SessionID: "sess-1", EnableRewrite: true},
PipelineContext: types.PipelineContext{EventBus: bus},
}
start := time.Now()
progress := BeginQueryUnderstandProgress(context.Background(), cm)
require.NotNil(t, progress)
EndQueryUnderstandProgress(context.Background(), cm, progress, start, nil)
require.Len(t, bus.events, 2)
callData, ok := bus.events[0].Data.(event.AgentToolCallData)
require.True(t, ok)
assert.Equal(t, "query_understand", callData.ToolName)
}
func TestRetrievalProgressEmitsSingleToolCallAndResult(t *testing.T) {
bus := &recordingEventBus{}
cm := &types.ChatManage{
PipelineRequest: types.PipelineRequest{SessionID: "sess-1"},
PipelineContext: types.PipelineContext{EventBus: bus},
PipelineState: types.PipelineState{
MergeResult: []*types.SearchResult{{ID: "r1"}, {ID: "r2"}, {ID: "r3"}},
},
}
start := time.Now()
progress := BeginRetrievalProgress(context.Background(), cm)
require.NotNil(t, progress)
EndRetrievalProgress(context.Background(), cm, progress, start, nil)
require.Len(t, bus.events, 2)
assert.Equal(t, types.EventType(event.EventAgentToolCall), bus.events[0].Type)
assert.Equal(t, types.EventType(event.EventAgentToolResult), bus.events[1].Type)
callData, ok := bus.events[0].Data.(event.AgentToolCallData)
require.True(t, ok)
assert.Equal(t, "knowledge_search", callData.ToolName)
resultData, ok := bus.events[1].Data.(event.AgentToolResultData)
require.True(t, ok)
assert.True(t, resultData.Success)
assert.Equal(t, 3, resultData.Data["count"])
}
@@ -6,14 +6,11 @@ import (
"fmt"
"regexp"
"strings"
"time"
"github.com/Tencent/WeKnora/internal/config"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
"github.com/google/uuid"
)
// PluginQueryUnderstand performs query rewriting and intent classification.
@@ -115,23 +112,8 @@ func (p *PluginQueryUnderstand) OnEvent(ctx context.Context,
maxTokens = 500
}
// --- Emit progress event for image analysis ---
var toolCallID string
if useImages && chatManage.EventBus != nil {
toolCallID = uuid.New().String()
chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolCall),
SessionID: chatManage.SessionID,
Data: event.AgentToolCallData{
ToolCallID: toolCallID,
ToolName: "image_analysis",
},
})
}
// --- Call model ---
thinking := false
vlmStart := time.Now()
response, err := rewriteModel.Chat(ctx, []chat.Message{
{Role: "system", Content: systemContent},
userMsg,
@@ -141,19 +123,6 @@ func (p *PluginQueryUnderstand) OnEvent(ctx context.Context,
Thinking: &thinking,
})
if err != nil {
if toolCallID != "" && chatManage.EventBus != nil {
chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolResult),
SessionID: chatManage.SessionID,
Data: event.AgentToolResultData{
ToolCallID: toolCallID,
ToolName: "image_analysis",
Output: "图片分析失败",
Success: false,
Duration: time.Since(vlmStart).Milliseconds(),
},
})
}
pipelineError(ctx, "QueryUnderstand", "model_call", map[string]interface{}{
"session_id": chatManage.SessionID,
"error": err.Error(),
@@ -161,21 +130,6 @@ func (p *PluginQueryUnderstand) OnEvent(ctx context.Context,
return next()
}
// --- Emit completion event for image analysis ---
if toolCallID != "" && chatManage.EventBus != nil {
chatManage.EventBus.Emit(ctx, types.Event{
Type: types.EventType(event.EventAgentToolResult),
SessionID: chatManage.SessionID,
Data: event.AgentToolResultData{
ToolCallID: toolCallID,
ToolName: "image_analysis",
Output: "已分析图片内容",
Success: true,
Duration: time.Since(vlmStart).Milliseconds(),
},
})
}
// --- Parse structured output ---
p.parseOutput(chatManage, response.Content)
@@ -216,21 +216,6 @@ func (s *sessionService) KnowledgeQA(
return err
}
// Emit references event if we have search results
if len(chatManage.MergeResult) > 0 {
logger.Infof(ctx, "Emitting references event with %d results", len(chatManage.MergeResult))
if err := eventBus.Emit(ctx, event.Event{
ID: generateEventID("references"),
Type: event.EventAgentReferences,
SessionID: req.Session.ID,
Data: event.AgentReferencesData{
References: chatManage.MergeResult,
},
}); err != nil {
logger.Errorf(ctx, "Failed to emit references event: %v", err)
}
}
// Note: Answer events are now emitted directly by chat_completion_stream plugin
// Completion event will be emitted when the last answer event has Done=true
// We can optionally add a completion watcher here if needed, but for now
@@ -553,6 +538,11 @@ func (s *sessionService) KnowledgeQAByEvent(ctx context.Context,
logger.Infof(ctx, "Trigger event list: %v", methods)
pipelineStart := time.Now()
lastRetrievalStage := chatpipeline.LastConsolidatedRetrievalStage(eventList, chatManage)
var retrievalProgress *chatpipeline.StageProgress
var retrievalStart time.Time
var understandProgress *chatpipeline.StageProgress
var understandStart time.Time
for _, eventType := range eventList {
stageStart := time.Now()
// Wrap each pipeline stage in a Langfuse span so the trace timeline
@@ -578,7 +568,30 @@ func (s *sessionService) KnowledgeQAByEvent(ctx context.Context,
},
})
}
if eventType == types.QUERY_UNDERSTAND && chatpipeline.ShouldEmitQueryUnderstandProgress(chatManage) {
understandStart = stageStart
understandProgress = chatpipeline.BeginQueryUnderstandProgress(stageCtx, chatManage)
}
if chatpipeline.IsConsolidatedRetrievalStage(eventType, chatManage) && retrievalProgress == nil {
retrievalStart = stageStart
retrievalProgress = chatpipeline.BeginRetrievalProgress(stageCtx, chatManage)
}
// Emit references before answer streaming so the SSE client receives
// them while the connection is still open. Previously references were
// emitted after the pipeline returned — by then the `complete` event had
// already closed the stream, so the frontend only saw citations on refresh.
if eventType == types.CHAT_COMPLETION_STREAM {
emitKnowledgeReferencesEvent(ctx, chatManage)
}
err := s.eventManager.Trigger(stageCtx, eventType, chatManage)
if understandProgress != nil && eventType == types.QUERY_UNDERSTAND {
chatpipeline.EndQueryUnderstandProgress(stageCtx, chatManage, understandProgress, understandStart, err)
understandProgress = nil
}
if retrievalProgress != nil && eventType == lastRetrievalStage {
chatpipeline.EndRetrievalProgress(stageCtx, chatManage, retrievalProgress, retrievalStart, err)
retrievalProgress = nil
}
stageDuration := time.Since(stageStart)
var spanErr error
if err != nil && err != chatpipeline.ErrSearchNothing {
@@ -989,6 +1002,26 @@ func (s *sessionService) consumeFallbackStream(
}
}
// emitKnowledgeReferencesEvent streams retrieved chunks to the client as a
// `references` SSE event. Must run before CHAT_COMPLETION_STREAM so citations
// arrive while the connection is still open (complete closes the stream).
func emitKnowledgeReferencesEvent(ctx context.Context, chatManage *types.ChatManage) {
if chatManage == nil || chatManage.EventBus == nil || len(chatManage.MergeResult) == 0 {
return
}
logger.Infof(ctx, "Emitting references event with %d results (pre-answer)", len(chatManage.MergeResult))
if err := chatManage.EventBus.Emit(ctx, types.Event{
ID: generateEventID("references"),
Type: types.EventType(event.EventAgentReferences),
SessionID: chatManage.SessionID,
Data: event.AgentReferencesData{
References: chatManage.MergeResult,
},
}); err != nil {
logger.Errorf(ctx, "Failed to emit references event: %v", err)
}
}
// emitFallbackAnswer emits fallback answer event
func (s *sessionService) emitFallbackAnswer(ctx context.Context, chatManage *types.ChatManage, content string) {
if chatManage.EventBus == nil {
@@ -8,6 +8,7 @@ import (
"sync"
"time"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/types"
@@ -227,10 +228,10 @@ func (h *AgentStreamHandler) handleToolResult(ctx context.Context, evt event.Eve
// Send SSE response (both success and failure)
responseType := types.ResponseTypeToolResult
content := data.Output
content := agenttools.StreamContentForToolResult(data.ToolName, data.Success, data.Error, data.Data)
if !data.Success {
responseType = types.ResponseTypeError
if data.Error != "" {
if content == "" && data.Error != "" {
content = data.Error
}
}
@@ -239,17 +240,19 @@ func (h *AgentStreamHandler) handleToolResult(ctx context.Context, evt event.Eve
metadata := map[string]interface{}{
"tool_name": data.ToolName,
"success": data.Success,
"output": data.Output,
"error": data.Error,
"duration_ms": durationMs,
"tool_call_id": data.ToolCallID,
}
// Merge tool result data (contains display_type, formatted results, etc.)
if data.Data != nil {
for k, v := range data.Data {
metadata[k] = v
}
clientData := agenttools.SanitizeToolResultForClient(data.ToolName, &types.ToolResult{
Success: data.Success,
Output: data.Output,
Error: data.Error,
Data: data.Data,
})
for k, v := range clientData {
metadata[k] = v
}
// Append event to stream
@@ -573,7 +576,7 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
// Update agent steps if provided
if data.AgentSteps != nil {
if steps, ok := data.AgentSteps.([]types.AgentStep); ok {
h.assistantMessage.AgentSteps = steps
h.assistantMessage.AgentSteps = agenttools.SanitizeAgentStepsForStorage(steps)
}
}
}