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
Feature: chat to store and display prompt, usage and time information (#21681)
Wang Qi3e03753fc284
diff --git a/docs/references/http_api_reference.md b/docs/references/http_api_reference.mdindex 08561b0fa2..dc496e46cb 100644--- a/docs/references/http_api_reference.md+++ b/docs/references/http_api_reference.md@@ -3516,6 +3516,14 @@ Failure:Gets a specific session of a specified chat assistant, including its messages, references, and avatar.+Completed assistant entries in `messages` include the recorded `prompt` (string),+`usage` (object with `prompt_tokens`, `completion_tokens`, and `total_tokens`), and+`elapsed_ms` (number, in milliseconds). These fields are also returned by the+session list when history is included. Older messages and turns without recorded+usage or timing omit the unavailable fields. They are used for displaying answer+details and are excluded from history passed to the LLM for subsequent turns.+Agentic answers store and return `usage` and `elapsed_ms` without a `prompt`.+#### Request- Method: GETdiff --git a/internal/dao/conversation_history.go b/internal/dao/conversation_history.goindex dbdb8c1d75..b27a673f79 100644--- a/internal/dao/conversation_history.go+++ b/internal/dao/conversation_history.go@@ -266,6 +266,7 @@ func flattenMessage(item json.RawMessage) (entity.ConversationMessageFields, errfor key, target := range map[string]interface{}{"id": &fields.MessageID, "role": &fields.Role, "status": &fields.Status,"thumbup": &fields.ThumbUp, "feedback": &fields.Feedback, "created_at": &fields.CreatedAt,+ "prompt": &fields.Prompt, "usage": &fields.Usage, "elapsed_ms": &fields.ElapsedMs,} {if value, ok := metadata[key]; ok && !bytes.Equal(bytes.TrimSpace(value), []byte("null")) {if err := json.Unmarshal(value, target); err == nil {@@ -324,6 +325,7 @@ func messageValues(fields entity.ConversationMessageFields) map[string]interfacereturn map[string]interface{}{"message_id": fields.MessageID, "role": fields.Role, "content": fields.Content, "content_type": fields.ContentType,"status": fields.Status, "thumb_up": fields.ThumbUp, "feedback": fields.Feedback, "created_at": fields.CreatedAt, "metadata": fields.Metadata,+ "prompt": fields.Prompt, "usage": fields.Usage, "elapsed_ms": fields.ElapsedMs,}}diff --git a/internal/dao/conversation_history_migration_test.go b/internal/dao/conversation_history_migration_test.goindex ce68d4985f..a055e84e4a 100644--- a/internal/dao/conversation_history_migration_test.go+++ b/internal/dao/conversation_history_migration_test.go@@ -108,6 +108,46 @@ func writeDatabaseVersion(t *testing.T, db *gorm.DB, version string) {}}+func TestConversationMessageDetailsSchemaMigration(t *testing.T) {+ for _, model := range []interface{}{&entity.ConversationMessage{}, &entity.API4ConversationMessage{}} {+ t.Run(fmt.Sprintf("%T", model), func(t *testing.T) {+ db := setupConversationHistoryMigrationDB(t, false)+ table, parent := conversationMessageTable, "conversation"+ if _, ok := model.(*entity.API4ConversationMessage); ok {+ table, parent = apiConversationMessageTable, "api_4_conversation"+ }+ for _, column := range []string{"prompt", "usage", "elapsed_ms"} {+ if err := db.Migrator().DropColumn(model, column); err != nil {+ t.Fatal(err)+ }+ }+ insertConversation(t, db, parent, "session-1")+ if err := db.Table(table).Create(map[string]interface{}{+ "conversation_id": "session-1", "position": 0, "role": "assistant", "content": "old answer",+ }).Error; err != nil {+ t.Fatal(err)+ }+ for range 2 {+ if err := autoMigrateSafely(t.Context(), db, model); err != nil {+ t.Fatal(err)+ }+ }+ for _, column := range []string{"prompt", "usage", "elapsed_ms"} {+ if !db.Migrator().HasColumn(model, column) {+ t.Fatalf("missing column %s", column)+ }+ }+ var row entity.ConversationMessage+ if err := db.Table(table).Where("conversation_id = ?", "session-1").Take(&row).Error; err != nil {+ t.Fatal(err)+ }+ if row.Content == nil || *row.Content != "old answer" || row.Prompt != nil || len(row.Usage) != 0 || row.ElapsedMs != nil {+ t.Fatalf("migration changed old answer: %+v", row)+ }+ })+ }+}+func TestMigrateConversationHistorySplitsPayloads(t *testing.T) {message := `[{"role":"user","content":"hi","id":"m1"},{"role":"assistant","content":"<think>reasoning</think>hello","id":"m2","reference":[{"chunk-0":{"content":"chunk"}}]}]`reference := `[{"chunks":["a"],"doc_aggs":[]},{"chunks":["b"],"doc_aggs":[]}]`diff --git a/internal/dao/conversation_history_test.go b/internal/dao/conversation_history_test.goindex 2b643e9ad9..f87363be37 100644--- a/internal/dao/conversation_history_test.go+++ b/internal/dao/conversation_history_test.go@@ -13,6 +13,9 @@ import (func TestFlattenMessageRoundTrip(t *testing.T) {for _, item := range []string{+ `{"role":"assistant","content":"agentic answer","usage":{"prompt_tokens":896,"completion_tokens":71,"total_tokens":967},"elapsed_ms":4168.774506}`,+ `{"role":"assistant","content":"answer","prompt":"system prompt","usage":{"prompt_tokens":896,"completion_tokens":71,"total_tokens":967},"elapsed_ms":4168.774506}`,+ `{"role":"assistant","prompt":"","usage":null,"elapsed_ms":0}`,`{"id":"turn-1","role":"assistant","content":"你好\nanswer","status":"completed","thumbup":false,"feedback":"","created_at":123.25,"attachments":[{"id":"file-1"}]}`,`{"role":"user","content":[{"type":"text","text":"question"},{"type":"image_url","image_url":{"url":"test"}}],"tool_calls":[]}`,`{"id":null,"role":null,"content":null,"thumbup":null,"created_at":null,"feedback":null}`,@@ -62,7 +65,7 @@ func TestFlattenedMessagePersistence(t *testing.T) {if err := db.Table(parent).Create(values).Error; err != nil {t.Fatal(err)}- raw := json.RawMessage(`[{"id":"turn-1","role":"assistant","content":"searchable content","thumbup":false,"feedback":"bad","created_at":123.25,"attachment":"file-1"}]`)+ raw := json.RawMessage(`[{"id":"turn-1","role":"assistant","content":"searchable content","thumbup":false,"feedback":"bad","created_at":123.25,"attachment":"file-1","prompt":"system prompt","usage":{"prompt_tokens":896,"completion_tokens":71,"total_tokens":967},"elapsed_ms":4168.774506},{"id":"turn-2","role":"assistant","content":"agentic answer","usage":{"prompt_tokens":896,"completion_tokens":71,"total_tokens":967},"elapsed_ms":4168.774506}]`)if err := createHistory(t.Context(), db, table, "message", "session-1", raw); err != nil {t.Fatal(err)}@@ -76,6 +79,19 @@ func TestFlattenedMessagePersistence(t *testing.T) {if string(row.Metadata) != `{"attachment":"file-1"}` {t.Fatalf("metadata contains flattened fields: %s", row.Metadata)}+ if row.Prompt == nil || *row.Prompt != "system prompt" || row.ElapsedMs == nil || *row.ElapsedMs != 4168.774506 {+ t.Fatalf("missing answer details: %+v", row.ConversationMessageFields)+ }+ if row.Usage["total_tokens"] != float64(967) || row.Usage["prompt_tokens"] != float64(896) || row.Usage["completion_tokens"] != float64(71) {+ t.Fatalf("unexpected usage: %v", row.Usage)+ }+ var agenticRow entity.ConversationMessage+ if err := db.Table(table).Where("conversation_id = ? AND position = ?", "session-1", 1).Take(&agenticRow).Error; err != nil {+ t.Fatal(err)+ }+ if agenticRow.Prompt != nil || !reflect.DeepEqual(agenticRow.Usage, row.Usage) || agenticRow.ElapsedMs == nil || *agenticRow.ElapsedMs != *row.ElapsedMs || agenticRow.Metadata != "{}" {+ t.Fatalf("unexpected agentic answer details: %+v", agenticRow.ConversationMessageFields)+ }histories, err := loadHistory(t.Context(), db, table, "message", []string{"session-1"})if err != nil {t.Fatal(err)diff --git a/internal/entity/conversation_history.go b/internal/entity/conversation_history.goindex 9534b82eaa..dde3226f8b 100644--- a/internal/entity/conversation_history.go+++ b/internal/entity/conversation_history.go@@ -28,6 +28,9 @@ type ConversationMessageFields struct {ThumbUp *bool `gorm:"column:thumb_up" json:"thumbup,omitempty"`Feedback *string `gorm:"column:feedback;type:longtext" json:"feedback,omitempty"`CreatedAt *float64 `gorm:"column:created_at" json:"created_at,omitempty"`+ Prompt *string `gorm:"column:prompt;type:longtext" json:"prompt,omitempty"`+ Usage JSONMap `gorm:"column:usage;type:longtext" json:"usage,omitempty"`+ ElapsedMs *float64 `gorm:"column:elapsed_ms" json:"elapsed_ms,omitempty"`Metadata string `gorm:"column:metadata;type:longtext" json:"-"`}diff --git a/internal/service/agentic_pipeline.go b/internal/service/agentic_pipeline.goindex aa094ebb0e..60abec0511 100644--- a/internal/service/agentic_pipeline.go+++ b/internal/service/agentic_pipeline.go@@ -128,9 +128,8 @@ func (s *ChatPipelineService) agenticRag(}// Per-turn token accounting. Every LLM call inside the run records its// usage into this sink (models.EinoChatModel does it for both the- // non-streaming and streaming paths), which is the only place the cost of- // an agentic turn exists: chat completions carries no usage field, so a- // caller cannot recover it from the answer.+ // non-streaming and streaming paths). Its totals are emitted on the final+ // result and stored with the assistant message.runCtx = tokenizer.WithRunUsage(runCtx)runCtx = tokenizer.WithRunAttrs(runCtx, &tokenizer.RunAttrs{UserID: userID})turnStarted := time.Now()@@ -346,11 +345,10 @@ func (s *ChatPipelineService) agenticRag(// agenticUsageFields renders a turn's LLM cost as structured log fields.//-// The chat-completions response carries no usage, and conversation storage has-// no token column, so this log line is the only per-question cost record: it is-// what a benchmark run aggregates and what a support investigation greps. The-// per-call breakdown goes to the debug log to keep the INFO line one line per-// turn.+// The final response and stored message carry token totals. The log also records+// call counts and per-phase totals for benchmarks and support investigations.+// The per-call breakdown goes to the debug log to keep the INFO line one line+// per turn.//// usage_missing_calls counts calls whose provider reported no usable split.// They are counted rather than silently folded into the totals, so "cheap"diff --git a/internal/service/chat_session.go b/internal/service/chat_session.goindex 1ee4e79917..453796f6c3 100644--- a/internal/service/chat_session.go+++ b/internal/service/chat_session.go@@ -1332,7 +1332,13 @@ func (s *ChatSessionService) ChatCompletions(}s.appendAssistantToSession(session, content, messageID)if ctx.Err() == nil {- s.updateSessionMessages(ctx, session, s.getSessionMessagesAsSlice(session), reference)+ messages := s.getSessionMessagesAsSlice(session)+ message := messages[len(messages)-1]+ if result.Prompt != "" {+ message["prompt"] = result.Prompt+ }+ attachTurnCost(message, result)+ s.updateSessionMessages(ctx, session, messages, reference)}}if result.AnswerIsAuthoritative {@@ -1596,6 +1602,9 @@ func (s *ChatSessionService) normalizeCompletionMessages(for _, msg := range messages {message := make(map[string]interface{}, len(msg))for key, value := range msg {+ if key == "prompt" || key == "usage" || key == "elapsed_ms" {+ continue+ }message[key] = value}requestMsg = append(requestMsg, message)@@ -1764,7 +1773,14 @@ func (s *ChatSessionService) filterSystemAndLeadingAssistant(session *entity.Chaif role == "assistant" && len(result) == 0 {continue}- result = append(result, msg)+ message := make(map[string]interface{}, len(msg))+ for key, value := range msg {+ if key == "prompt" || key == "usage" || key == "elapsed_ms" {+ continue+ }+ message[key] = value+ }+ result = append(result, message)}return result}@@ -2156,6 +2172,14 @@ func (s *ChatSessionService) structureAnswerWithConv(session *entity.ChatSessionlastMsg["id"] = messageIDmessages[lastIdx] = lastMsg}+ if prompt, _ := ans["prompt"].(string); prompt != "" {+ messages[len(messages)-1]["prompt"] = prompt+ }+ for _, key := range []string{"usage", "elapsed_ms"} {+ if value, ok := ans[key]; ok {+ messages[len(messages)-1][key] = value+ }+ }session.Message, _ = json.Marshal(messages)diff --git a/internal/service/chat_session_test.go b/internal/service/chat_session_test.goindex ed0707ce2e..95a5a2d915 100644--- a/internal/service/chat_session_test.go+++ b/internal/service/chat_session_test.go@@ -339,6 +339,110 @@ func makeResultChan(results ...AsyncChatResult) <-chan AsyncChatResult {return ch}+func TestChatCompletionsPersistsAnswerDetailsForHistory(t *testing.T) {+ for _, mode := range []struct {+ name string+ stream bool+ legacy bool+ agentic bool+ }{+ {name: "non-stream"},+ {name: "stream", stream: true},+ {name: "legacy stream", stream: true, legacy: true},+ {name: "agentic non-stream", agentic: true},+ {name: "agentic stream", stream: true, agentic: true},+ {name: "agentic legacy stream", stream: true, legacy: true, agentic: true},+ } {+ for _, withCost := range []bool{true, false} {+ t.Run(fmt.Sprintf("%s/cost=%t", mode.name, withCost), func(t *testing.T) {+ store := newFakeSessionStore()+ store.sessions["session-1"] = &entity.ChatSession{+ ID: "session-1", DialogID: "chat-1", UserID: strPtr("user-1"),+ Message: json.RawMessage(`[{"role":"assistant","content":"Welcome"},{"role":"user","content":"old question","id":"old"},{"role":"assistant","content":"old answer","id":"old","prompt":"old prompt","usage":{"prompt_tokens":1,"completion_tokens":2,"total_tokens":3},"elapsed_ms":123}]`),+ }+ store.dialogs["chat-1"] = &entity.Chat{ID: "chat-1", TenantID: "user-1", LLMID: "chat@factory"}+ store.dialogExists["user-1|chat-1"] = true+ final := AsyncChatResult{Answer: "new answer", Prompt: "system prompt", Final: true}+ if mode.agentic {+ final.Answer = "<think>agent reasoning</think>new answer"+ final.Prompt = ""+ final.AnswerIsAuthoritative = true+ }+ if withCost {+ final.Usage = &ChatTurnUsage{PromptTokens: 896, CompletionTokens: 71, TotalTokens: 967}+ final.ElapsedMs = 4168.774506+ }+ pipeline := &fakePipeline{resultChan: makeResultChan(+ AsyncChatResult{Answer: "new answer", Prompt: "intermediate prompt", ElapsedMs: 1}, final,+ )}+ svc := &ChatSessionService{chatSessionDAO: store, permissionChecker: store, pipeline: pipeline}+ streamChan := make(chan string, 8)+ if _, err := svc.ChatCompletions(t.Context(), "user-1", "chat-1", "session-1", nil, "new question", nil, "", nil, nil, mode.legacy, mode.stream, streamChan); err != nil {+ t.Fatal(err)+ }+ if len(pipeline.messages) != 3 || pipeline.messages[1]["content"] != "old answer" {+ t.Fatalf("unexpected LLM history: %v", pipeline.messages)+ }+ for _, message := range pipeline.messages {+ for _, key := range []string{"prompt", "usage", "elapsed_ms"} {+ if _, ok := message[key]; ok {+ t.Fatalf("LLM history contains %s: %v", key, message)+ }+ }+ }+ payload, code, err := svc.GetSession(t.Context(), "user-1", "chat-1", "session-1")+ if err != nil || code != common.CodeSuccess {+ t.Fatalf("GetSession: code=%v err=%v", code, err)+ }+ if payload.Messages[2]["prompt"] != "old prompt" {+ t.Fatalf("old answer details changed: %v", payload.Messages[2])+ }+ answer := payload.Messages[len(payload.Messages)-1]+ if answer["content"] != final.Answer {+ t.Fatalf("missing stored answer details: %v", answer)+ }+ if mode.agentic {+ if _, ok := answer["prompt"]; ok {+ t.Fatalf("agentic answer stored a prompt: %v", answer)+ }+ } else if answer["prompt"] != final.Prompt {+ t.Fatalf("missing stored prompt: %v", answer)+ }+ if withCost {+ usage, ok := answer["usage"].(map[string]interface{})+ if !ok || usage["prompt_tokens"] != float64(896) || usage["completion_tokens"] != float64(71) || usage["total_tokens"] != float64(967) || answer["elapsed_ms"] != final.ElapsedMs {+ t.Fatalf("unexpected stored cost: %v", answer)+ }+ } else {+ for _, key := range []string{"usage", "elapsed_ms"} {+ if _, ok := answer[key]; ok {+ t.Fatalf("stored intermediate %s: %v", key, answer)+ }+ }+ }+ })+ }+ }+}++func TestNormalizeCompletionMessagesExcludesAnswerDetails(t *testing.T) {+ messages := []map[string]interface{}{+ {"role": "assistant", "content": "answer", "prompt": "system prompt", "usage": map[string]int{"total_tokens": 3}, "elapsed_ms": 123.0},+ {"role": "user", "content": "question", "id": "turn-1"},+ }+ svc := &ChatSessionService{}+ got, _, err := svc.normalizeCompletionMessages(messages, "", nil, false)+ if err != nil {+ t.Fatal(err)+ }+ if !reflect.DeepEqual(got[0], map[string]interface{}{"role": "assistant", "content": "answer"}) {+ t.Fatalf("unexpected LLM message: %v", got[0])+ }+ if messages[0]["prompt"] != "system prompt" {+ t.Fatal("normalization mutated supplied history")+ }+}+type fakeChatModelConfigResolver struct {tenantID stringllmID stringdiff --git a/web/src/components/message-item/history-details.test.tsx b/web/src/components/message-item/history-details.test.tsxnew file mode 100644index 0000000000..00b456cb64--- /dev/null+++ b/web/src/components/message-item/history-details.test.tsx@@ -0,0 +1,91 @@+import { render, screen } from '@testing-library/react';+import { MessageType } from '@/constants/chat';+import { buildMessageListWithUuid } from '@/utils/chat';+import MessageItem from './index';++jest.mock('../theme-provider', () => ({+ useTheme: () => ({ theme: 'light' }),+}));+jest.mock('../markdown-content', () => ({+ __esModule: true,+ default: ({ content }: { content: string }) => <div>{content}</div>,+}));+jest.mock('../svg-icon', () => ({+ __esModule: true,+ default: () => null,+}));+jest.mock('../ragflow-avatar', () => ({ RAGFlowAvatar: () => null }));+jest.mock('../document-download-button', () => ({+ DocumentDownloadButton: () => null,+}));+jest.mock('../next-message-item/reference-image-list', () => ({+ ReferenceImageList: () => null,+}));+jest.mock('../next-message-item/uploaded-message-files', () => ({+ UploadedMessageFiles: () => null,+}));+jest.mock('./group-button', () => ({+ AssistantGroupButton: ({ prompt }: { prompt?: string }) => (+ <div data-testid="prompt-details">{prompt}</div>+ ),+ UserGroupButton: () => null,+}));+jest.mock('react-i18next', () => ({+ useTranslation: () => ({+ t: (key: string, values: Record<string, number | string>) =>+ key === 'tokensSpent'+ ? `${values.total} tokens (${values.prompt} input, ${values.completion} output)`+ : `${values.seconds} seconds`,+ }),+}));++describe('History answer details', () => {+ it('preserves API message details for the prompt action and usage footer', () => {+ const [message] = buildMessageListWithUuid([+ {+ id: 'turn-1',+ role: MessageType.Assistant,+ content: 'Saved answer',+ prompt: 'Saved system prompt',+ usage: {+ prompt_tokens: 896,+ completion_tokens: 71,+ total_tokens: 967,+ },+ elapsed_ms: 4168.774506,+ },+ ]);++ render(+ <MessageItem+ item={message}+ reference={{ chunks: [], doc_aggs: [], total: 0 }}+ index={2}+ />,+ );++ expect(screen.getByTestId('prompt-details')).toHaveTextContent(+ 'Saved system prompt',+ );+ expect(screen.getByTestId('turn-usage')).toHaveTextContent(+ '967 tokens (896 input, 71 output) · 4.2 seconds',+ );+ });++ it('renders old answers without a usage footer', () => {+ render(+ <MessageItem+ item={{+ id: 'old-turn',+ role: MessageType.Assistant,+ content: 'Old answer',+ }}+ reference={{ chunks: [], doc_aggs: [], total: 0 }}+ index={2}+ />,+ );++ expect(screen.getByText('Old answer')).toBeInTheDocument();+ expect(screen.queryByTestId('turn-usage')).not.toBeInTheDocument();+ });+});diff --git a/web/src/components/message-item/turn-usage.tsx b/web/src/components/message-item/turn-usage.tsxindex b7ea40c452..77cd856dbf 100644--- a/web/src/components/message-item/turn-usage.tsx+++ b/web/src/components/message-item/turn-usage.tsx@@ -21,10 +21,8 @@ import { ITurnUsage } from '@/interfaces/database/chat';* The one-line cost footer under an answer: tokens spent and how long the turn* took.*- * It renders only when the turn actually reported a cost. The final SSE chunk- * carries it, an answer restored from history does not — there is nowhere in the- * message row to keep it — so showing a placeholder for those would advertise a- * measurement that was never taken.+ * It renders only when the turn reported a cost, either in the final SSE chunk+ * or in a message restored from history.*/export function TurnUsage({usage,diff --git a/web/src/interfaces/database/chat.ts b/web/src/interfaces/database/chat.tsindex a498446e5d..00d4906896 100644--- a/web/src/interfaces/database/chat.ts+++ b/web/src/interfaces/database/chat.ts@@ -179,7 +179,7 @@ export interface IReferenceObject {doc_aggs: Record<string, Docagg>;}-/** One turn's token cost, as reported by the final SSE chunk. */+/** One turn's token cost, reported by a final response or a history message. */export interface ITurnUsage {prompt_tokens: number;completion_tokens: number;@@ -197,7 +197,7 @@ export interface IAnswer {audio_binary?: string;data?: any;chatBoxId?: string;- /** Present on the final chunk only; absent for answers restored from history. */+ /** Present when the final response reports token usage. */usage?: ITurnUsage;elapsed_ms?: number;}