RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.
Go agent-harnessagent-native-databaseagentic-aiagentic-retrievalagentic-searchaiai-agentscontext-enginecontext-engineeringcontext-managementharness-engineeringknowledge-compilationragretrieval-augmented-generationretrieval-harnesssearch-harness
fix(bot): align chatbot completion final frame and history persistence with python (#18526)
euvre4c7846a4497f
diff --git a/internal/service/bot_completion.go b/internal/service/bot_completion.goindex 57243a1134..120b14e8a9 100644--- a/internal/service/bot_completion.go+++ b/internal/service/bot_completion.go@@ -434,14 +434,46 @@ func (s *BotService) ChatbotCompletion(// Sending accumulated full text on every frame interacts badly with// the front-end's start_to_think/end_to_think marker append, causing// reasoning content to leak into the visible answer.+ return s.streamChatbotTurn(ctx, session, req.Question, messageID, results), common.CodeSuccess, nil+}++// streamChatbotTurn translates pipeline results into python-shaped+// chatbot SSE frames and persists the finished turn. It mirrors+// conversation_service.py structure_answer:+//+// - Every non-final frame forwards only its own delta with an empty+// reference object; only the final frame carries the retrieval+// reference.+// - The final frame's `answer` is empty whenever text was already+// streamed as deltas (python async_chat sets final["answer"] = ""),+// so accumulating consumers do not double the text. The full text+// is sent when nothing was streamed (single-shot results such as+// the structured-SQL path) and on error finals, so a mid-stream+// pipeline failure still reaches the wire after partial deltas.+// - The persisted assistant turn is the raw streamed text, NOT the+// decorated final answer. The decorated text carries server-side+// [ID:n] citation markers; persisting it feeds fabricated markers+// back into the next turn's prompt, and models that imitate the+// history format then emit markers for turns whose retrieval+// returned nothing — which the widget renders as a citation icon+// with "Reference unavailable".+func (s *BotService) streamChatbotTurn(+ ctx context.Context,+ session *entity.API4Conversation,+ question, messageID string,+ results <-chan AsyncChatResult,+) <-chan ChatbotSSEFrame {out := make(chan ChatbotSSEFrame, 16)go func() {defer close(out)- var (- fullAnswer string- finalRef map[string]any- errored bool- )+ // rawAnswer is the accumulated wire text (deltas plus the+ // <think>/</think> tags the marker frames stand for), i.e. what+ // the client already rendered. fullAnswer additionally tracks+ // the decorated final answer for error detection and the+ // no-delta fallback.+ var rawAnswer, fullAnswer string+ var finalRef map[string]any+ var errored boolfor res := range results {if res.Final {if res.Answer != "" {@@ -459,8 +491,17 @@ func (s *BotService) ChatbotCompletion(if strings.HasPrefix(fullAnswer, "**ERROR**") {errored = true}+ finalData := ""+ if rawAnswer == "" || errored {+ // The final frame is the only carrier of the text+ // when nothing was streamed as deltas; on a+ // pipeline-level error it must still carry the+ // error text even after partial deltas, or the+ // client would see a silently truncated answer.+ finalData = fullAnswer+ }out <- ChatbotSSEFrame{- Data: fullAnswer,+ Data: finalData,Reference: referenceOrEmpty(finalRef),SessionID: session.ID,Final: true,@@ -470,6 +511,11 @@ func (s *BotService) ChatbotCompletion(if res.StartToThink || res.EndToThink {// Marker frames carry no text; the front-end appends// <think> / </think> to the accumulated answer.+ if res.StartToThink {+ rawAnswer += "<think>"+ } else {+ rawAnswer += "</think>"+ }out <- ChatbotSSEFrame{Data: "",Reference: map[string]any{},@@ -479,7 +525,24 @@ func (s *BotService) ChatbotCompletion(}continue}- fullAnswer += res.Answer+ // Reasoning text arrives through two delivery modes: the+ // plain streaming path emits it as Answer deltas between+ // the StartToThink/EndToThink markers (chat_pipeline.go+ // think-state machine), while the tool path+ // (chat_pipeline.go ChatStreamlyWithTools callback) routes+ // in-think text through the Reasoning field so the+ // OpenAI-compat SSE handler can map it to+ // delta.reasoning_content. Python delivers reasoning as+ // <think>-wrapped answer stream text in both modes+ // (rag/llm/chat_model.py), so forward it as stream text+ // here; dropping it would leave the widget's think block+ // empty and persist history without the reasoning.+ delta := res.Answer+ if delta == "" {+ delta = res.Reasoning+ }+ rawAnswer += delta+ fullAnswer += deltaif len(res.Reference) > 0 {// The pipeline only populates Reference on the final// result today; tracking it here keeps finalRef@@ -491,7 +554,7 @@ func (s *BotService) ChatbotCompletion(finalRef = res.Reference}out <- ChatbotSSEFrame{- Data: res.Answer,+ Data: delta,Reference: map[string]any{},SessionID: session.ID,}@@ -504,18 +567,32 @@ func (s *BotService) ChatbotCompletion(// stream — the answer has already been produced. On a// pipeline-level error ("**ERROR**" answer) nothing is// persisted, matching the python exception path.+ persisted := rawAnswer+ if persisted == "" {+ // No-delta finals never carry server-inserted [ID:n]+ // citation markers: the structured-SQL path returns its+ // markdown table (with ##N$$ source markers the frontend+ // resolves client-side, same as python use_sql) before+ // decorateAnswer runs, the empty_response fallback yields+ // the user-configured text undecorated, and the streaming+ // path always streams the full visible text as deltas+ // before its decorated final (so rawAnswer is non-empty+ // whenever the final was decorated). Falling back to+ // fullAnswer here is therefore marker-free.+ persisted = fullAnswer+ }if !errored {- if pErr := s.persistChatbotTurn(ctx, session, req.Question, fullAnswer, messageID, finalRef); pErr != nil {+ if pErr := s.persistChatbotTurn(ctx, session, question, persisted, messageID, finalRef); pErr != nil {common.Error("bot: ChatbotCompletion session update failed",pErr,- zap.String("dialog_id", dialogID),+ zap.String("dialog_id", session.DialogID),zap.String("session_id", session.ID),)}}out <- ChatbotSSEFrame{Done: true}}()- return out, common.CodeSuccess, nil+ return out}// buildChatbotPipelineMessages projects the session.Message JSONdiff --git a/internal/service/bot_completion_history_test.go b/internal/service/bot_completion_history_test.goindex d3bb217d5f..2703006d28 100644--- a/internal/service/bot_completion_history_test.go+++ b/internal/service/bot_completion_history_test.go@@ -31,6 +31,7 @@ import ("errors""fmt""net/http"+ "reflect""strings""sync""testing"@@ -636,3 +637,282 @@ func (r *recordingResponseWriter) Write(b []byte) (int, error) {return r.body.Write(b)}func (r *recordingResponseWriter) WriteHeader(_ int) {}++// seedStreamTurnSession creates a persisted api_4_conversation row the+// streamChatbotTurn tests can append to.+func seedStreamTurnSession(t *testing.T, id string) {+ t.Helper()+ sess := &entity.API4Conversation{ID: id, DialogID: "dlg-s1", UserID: "tenant-1"}+ if err := dao.NewAPI4ConversationDAO().Create(t.Context(), dao.DB, sess); err != nil {+ t.Fatalf("seed session: %v", err)+ }+}++// TestStreamChatbotTurn_FinalFrameAndPersistenceUseRawStreamText pins+// the python iframe wire contract for the final SSE frame and the+// persisted turn:+//+// - The final frame carries the retrieval reference but an empty+// `answer` whenever text was already streamed as deltas (python+// async_chat sets final["answer"] = "").+// - The persisted assistant turn is the raw streamed text, NOT the+// decorated final answer. Persisting the decorated text leaks the+// server-inserted [ID:n] markers into the next turn's prompt+// history; models that imitate the history format then emit+// citation markers on turns whose retrieval returned nothing, and+// the widget renders those as "Reference unavailable" icons.+func TestStreamChatbotTurn_FinalFrameAndPersistenceUseRawStreamText(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)++ seedStreamTurnSession(t, "sess-s1")+ svc := NewBotService(nil, nil)++ ref := map[string]any{+ "chunks": []any{map[string]any{"chunk_id": "c1"}, map[string]any{"chunk_id": "c2"}},+ "doc_aggs": []any{},+ }+ results := make(chan AsyncChatResult, 5)+ results <- AsyncChatResult{Answer: "答案", Reference: map[string]any{}}+ results <- AsyncChatResult{Answer: "第一段", Reference: map[string]any{}}+ // Decorated final answer with server-inserted markers — must not+ // reach the wire (deltas exist) nor the persisted history.+ results <- AsyncChatResult{Answer: "答案第一段 [ID:0][ID:1]", Reference: ref, Final: true}+ close(results)++ sess := &entity.API4Conversation{ID: "sess-s1", DialogID: "dlg-s1", UserID: "tenant-1"}+ var frames []ChatbotSSEFrame+ for f := range svc.streamChatbotTurn(t.Context(), sess, "q1", "msg-s1", results) {+ frames = append(frames, f)+ }++ if len(frames) != 4 || !frames[3].Done {+ t.Fatalf("want 3 frames + done, got %+v", frames)+ }+ final := frames[2]+ if !final.Final {+ t.Fatalf("frame 2 must be final: %+v", final)+ }+ if final.Data != "" {+ t.Errorf("final frame answer = %q, want empty (deltas already streamed)", final.Data)+ }+ if !reflect.DeepEqual(final.Reference, ref) {+ t.Errorf("final frame reference = %+v, want the retrieval reference", final.Reference)+ }+ if frames[0].Data != "答案" || frames[1].Data != "第一段" {+ t.Errorf("delta frames must forward their own delta: %+v %+v", frames[0], frames[1])+ }++ row, err := dao.NewAPI4ConversationDAO().GetBySessionID(t.Context(), dao.DB, "sess-s1", "dlg-s1")+ if err != nil || row == nil {+ t.Fatalf("re-read session: row=%v err=%v", row, err)+ }+ turns := parseChatbotTurns(row.Message)+ if len(turns) != 2 || turns[1]["role"] != "assistant" {+ t.Fatalf("want user+assistant pair, got %+v", turns)+ }+ if got := turns[1]["content"]; got != "答案第一段" {+ t.Errorf("persisted assistant content = %v, want raw streamed text without server-inserted markers", got)+ }+}++// TestStreamChatbotTurn_ThinkMarkersPersistedAsTags ensures the raw+// stream text keeps the <think>/</think> tags the marker frames stand+// for, matching python structure_answer's accumulation.+func TestStreamChatbotTurn_ThinkMarkersPersistedAsTags(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)++ seedStreamTurnSession(t, "sess-s2")+ svc := NewBotService(nil, nil)++ results := make(chan AsyncChatResult, 5)+ results <- AsyncChatResult{StartToThink: true}+ results <- AsyncChatResult{Answer: "思考中", Reference: map[string]any{}}+ results <- AsyncChatResult{EndToThink: true}+ results <- AsyncChatResult{Answer: "结论", Reference: map[string]any{}}+ results <- AsyncChatResult{Answer: "<think>思考中</think>结论", Final: true}+ close(results)++ sess := &entity.API4Conversation{ID: "sess-s2", DialogID: "dlg-s1", UserID: "tenant-1"}+ for range svc.streamChatbotTurn(t.Context(), sess, "q2", "msg-s2", results) {+ }++ row, err := dao.NewAPI4ConversationDAO().GetBySessionID(t.Context(), dao.DB, "sess-s2", "dlg-s1")+ if err != nil || row == nil {+ t.Fatalf("re-read session: row=%v err=%v", row, err)+ }+ turns := parseChatbotTurns(row.Message)+ if len(turns) != 2 {+ t.Fatalf("want user+assistant pair, got %+v", turns)+ }+ if got := turns[1]["content"]; got != "<think>思考中</think>结论" {+ t.Errorf("persisted assistant content = %v, want <think>思考中</think>结论", got)+ }+}++// TestStreamChatbotTurn_SingleShotFinalKeepsText covers finals that+// arrive without any streamed delta (e.g. the structured-SQL path):+// the final frame is the only carrier of the text and must keep it,+// and it is what gets persisted.+func TestStreamChatbotTurn_SingleShotFinalKeepsText(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)++ seedStreamTurnSession(t, "sess-s3")+ svc := NewBotService(nil, nil)++ ref := map[string]any{"chunks": []any{}, "doc_aggs": []any{}}+ results := make(chan AsyncChatResult, 1)+ results <- AsyncChatResult{Answer: "sql result", Reference: ref, Final: true}+ close(results)++ sess := &entity.API4Conversation{ID: "sess-s3", DialogID: "dlg-s1", UserID: "tenant-1"}+ var frames []ChatbotSSEFrame+ for f := range svc.streamChatbotTurn(t.Context(), sess, "q3", "msg-s3", results) {+ frames = append(frames, f)+ }+ if len(frames) != 2 || !frames[1].Done {+ t.Fatalf("want final + done, got %+v", frames)+ }+ if frames[0].Data != "sql result" {+ t.Errorf("single-shot final must carry the text, got %q", frames[0].Data)+ }++ row, err := dao.NewAPI4ConversationDAO().GetBySessionID(t.Context(), dao.DB, "sess-s3", "dlg-s1")+ if err != nil || row == nil {+ t.Fatalf("re-read session: row=%v err=%v", row, err)+ }+ turns := parseChatbotTurns(row.Message)+ if len(turns) != 2 || turns[1]["content"] != "sql result" {+ t.Errorf("persisted turns = %+v, want assistant content 'sql result'", turns)+ }+}++// TestStreamChatbotTurn_ErrorKeptOnWireAndNotPersisted mirrors the+// python exception path: the error text must stay visible on the wire+// (it was never streamed as a delta) but nothing is persisted.+func TestStreamChatbotTurn_ErrorKeptOnWireAndNotPersisted(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)++ seedStreamTurnSession(t, "sess-s4")+ svc := NewBotService(nil, nil)++ results := make(chan AsyncChatResult, 1)+ results <- AsyncChatResult{Answer: "**ERROR**: boom", Final: true}+ close(results)++ sess := &entity.API4Conversation{ID: "sess-s4", DialogID: "dlg-s1", UserID: "tenant-1"}+ var frames []ChatbotSSEFrame+ for f := range svc.streamChatbotTurn(t.Context(), sess, "q4", "msg-s4", results) {+ frames = append(frames, f)+ }+ if len(frames) != 2 || !frames[1].Done {+ t.Fatalf("want final + done, got %+v", frames)+ }+ if frames[0].Data != "**ERROR**: boom" {+ t.Errorf("error final must carry the text, got %q", frames[0].Data)+ }++ row, err := dao.NewAPI4ConversationDAO().GetBySessionID(t.Context(), dao.DB, "sess-s4", "dlg-s1")+ if err != nil || row == nil {+ t.Fatalf("re-read session: row=%v err=%v", row, err)+ }+ if turns := parseChatbotTurns(row.Message); len(turns) != 0 {+ t.Errorf("error turns must not persist, got %+v", turns)+ }+}++// TestStreamChatbotTurn_ErrorAfterDeltasKeptOnWire covers a pipeline-level+// failure that arrives AFTER partial deltas were already streamed+// (chat_pipeline.go reports a mid-stream driver error as a final+// "**ERROR**" result): the final frame must still carry the error text —+// dropping it would leave the client with a silently truncated partial+// answer — and nothing is persisted.+func TestStreamChatbotTurn_ErrorAfterDeltasKeptOnWire(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)++ seedStreamTurnSession(t, "sess-s5")+ svc := NewBotService(nil, nil)++ results := make(chan AsyncChatResult, 2)+ results <- AsyncChatResult{Answer: "partial", Reference: map[string]any{}}+ results <- AsyncChatResult{Answer: "**ERROR**: boom", Final: true}+ close(results)++ sess := &entity.API4Conversation{ID: "sess-s5", DialogID: "dlg-s1", UserID: "tenant-1"}+ var frames []ChatbotSSEFrame+ for f := range svc.streamChatbotTurn(t.Context(), sess, "q5", "msg-s5", results) {+ frames = append(frames, f)+ }+ if len(frames) != 3 || !frames[2].Done {+ t.Fatalf("want delta + final + done, got %+v", frames)+ }+ if frames[0].Data != "partial" {+ t.Errorf("delta frame = %q, want partial", frames[0].Data)+ }+ if !frames[1].Final || frames[1].Data != "**ERROR**: boom" {+ t.Errorf("error final after deltas must carry the error text, got %+v", frames[1])+ }++ row, err := dao.NewAPI4ConversationDAO().GetBySessionID(t.Context(), dao.DB, "sess-s5", "dlg-s1")+ if err != nil || row == nil {+ t.Fatalf("re-read session: row=%v err=%v", row, err)+ }+ if turns := parseChatbotTurns(row.Message); len(turns) != 0 {+ t.Errorf("error turns must not persist, got %+v", turns)+ }+}++// TestStreamChatbotTurn_ReasoningFieldForwardedAsStreamText covers the+// tool-path delivery mode: chat_pipeline.go's ChatStreamlyWithTools+// callback routes in-think text through the Reasoning field (so the+// OpenAI-compat SSE handler can map it to delta.reasoning_content)+// instead of Answer deltas. Python delivers the same reasoning as+// <think>-wrapped answer stream text (rag/llm/chat_model.py), so the+// iframe wire and the persisted history must carry it too — dropping it+// would leave the widget's think block empty.+func TestStreamChatbotTurn_ReasoningFieldForwardedAsStreamText(t *testing.T) {+ db := setupServiceTestDB(t)+ pushServiceDB(t, db)++ seedStreamTurnSession(t, "sess-s6")+ svc := NewBotService(nil, nil)++ results := make(chan AsyncChatResult, 5)+ results <- AsyncChatResult{StartToThink: true}+ results <- AsyncChatResult{Reasoning: "推理中", Reference: map[string]any{}}+ results <- AsyncChatResult{EndToThink: true}+ results <- AsyncChatResult{Answer: "结论", Reference: map[string]any{}}+ results <- AsyncChatResult{Answer: "<think>推理中</think>结论", Final: true}+ close(results)++ sess := &entity.API4Conversation{ID: "sess-s6", DialogID: "dlg-s1", UserID: "tenant-1"}+ var frames []ChatbotSSEFrame+ for f := range svc.streamChatbotTurn(t.Context(), sess, "q6", "msg-s6", results) {+ frames = append(frames, f)+ }+ if len(frames) != 6 || !frames[5].Done {+ t.Fatalf("want think + reasoning + think + delta + final + done, got %+v", frames)+ }+ if frames[1].Data != "推理中" {+ t.Errorf("reasoning frame must forward the reasoning text, got %+v", frames[1])+ }+ if frames[4].Final && frames[4].Data != "" {+ t.Errorf("final frame answer = %q, want empty (deltas already streamed)", frames[4].Data)+ }++ row, err := dao.NewAPI4ConversationDAO().GetBySessionID(t.Context(), dao.DB, "sess-s6", "dlg-s1")+ if err != nil || row == nil {+ t.Fatalf("re-read session: row=%v err=%v", row, err)+ }+ turns := parseChatbotTurns(row.Message)+ if len(turns) != 2 {+ t.Fatalf("want user+assistant pair, got %+v", turns)+ }+ if got := turns[1]["content"]; got != "<think>推理中</think>结论" {+ t.Errorf("persisted assistant content = %v, want <think>推理中</think>结论", got)+ }+}diff --git a/web/src/components/floating-chat-widget-markdown.module.less b/web/src/components/floating-chat-widget-markdown.module.lessindex 9fa5466354..934aca56c4 100644--- a/web/src/components/floating-chat-widget-markdown.module.less+++ b/web/src/components/floating-chat-widget-markdown.module.less@@ -16,6 +16,11 @@/* floating-chat-widget-markdown.less */+.referenceIcon {+ cursor: help;+ vertical-align: -0.125em;+}+.widget-citation-popover {max-width: 90vw;/* Use viewport width for better responsiveness */diff --git a/web/src/components/floating-chat-widget-markdown.tsx b/web/src/components/floating-chat-widget-markdown.tsxindex 8c1a7f1538..07d2878df8 100644--- a/web/src/components/floating-chat-widget-markdown.tsx+++ b/web/src/components/floating-chat-widget-markdown.tsx@@ -42,7 +42,6 @@ import DOMPurify from 'dompurify';import 'katex/dist/katex.min.css';import { omit } from 'lodash';import pipe from 'lodash/fp/pipe';-import { Info } from 'lucide-react';import { useCallback, useEffect, useMemo } from 'react';import { useTranslation } from 'react-i18next';import Markdown from 'react-markdown';@@ -69,6 +68,7 @@ const FloatingChatWidgetMarkdown = ({reference,clickDocumentButton,content,+ loading,}: {content: string;loading: boolean;@@ -269,9 +269,11 @@ const FloatingChatWidgetMarkdown = ({return (<Tooltip key={`err-tooltip-${i}`}><TooltipTrigger asChild>- <Info className={styles.referenceIcon} />+ <InfoCircleOutlined className={styles.referenceIcon} /></TooltipTrigger>- <TooltipContent>Reference unavailable</TooltipContent>+ <TooltipContent>+ {loading ? t('chat.searching') : 'Reference unavailable'}+ </TooltipContent></Tooltip>);}@@ -312,7 +314,7 @@ const FloatingChatWidgetMarkdown = ({);});},- [getPopoverContent, getReferenceInfo, handleDocumentButtonClick],+ [getPopoverContent, getReferenceInfo, handleDocumentButtonClick, loading, t],);const dir = getDirAttribute(content.replace(citationMarkerReg, ''));diff --git a/web/src/components/floating-chat-widget.tsx b/web/src/components/floating-chat-widget.tsxindex 8c038a5ce3..fac5f0deb6 100644--- a/web/src/components/floating-chat-widget.tsx+++ b/web/src/components/floating-chat-widget.tsx@@ -678,7 +678,11 @@ const FloatingChatWidget = () => {) : (<div className="space-y-2"><FloatingChatWidgetMarkdown- loading={false}+ loading={+ enableStreaming &&+ sendLoading &&+ index === displayMessages.length - 1+ }content={message.content}reference={findReferenceByMessageId?.(message.id) ||@@ -893,7 +897,11 @@ const FloatingChatWidget = () => {) : (<div className="space-y-2"><FloatingChatWidgetMarkdown- loading={false}+ loading={+ enableStreaming &&+ sendLoading &&+ index === displayMessages.length - 1+ }content={message.content}reference={findReferenceByMessageId?.(message.id) ||