Skip to content

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

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.md
index 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: GET
diff --git a/internal/dao/conversation_history.go b/internal/dao/conversation_history.go
index 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, err
for 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]interface
return 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.go
index 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.go
index 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.go
index 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.go
index 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.go
index 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.Cha
if 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.ChatSession
lastMsg["id"] = messageID
messages[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.go
index 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 string
llmID string
diff --git a/web/src/components/message-item/history-details.test.tsx b/web/src/components/message-item/history-details.test.tsx
new file mode 100644
index 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.tsx
index 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.ts
index 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;
}