Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

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.go
index 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 bool
for 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 += delta
if 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 JSON
diff --git a/internal/service/bot_completion_history_test.go b/internal/service/bot_completion_history_test.go
index 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.less
index 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.tsx
index 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.tsx
index 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) ||