agentic_huge_data_base / wiki
页面 RAGFlow · 7.6 聊天与会话 API·DeepWiki 中文全文译文
DeepWiki 中文译文 / RAGFlow / 7.6

7.6 · 聊天与会话 API（Chat and Conversation APIs）

复杂文档理解与引用检索 · 聚焦本章的模块关系、源码依据与实现要点。

项目RAGFlow 章节7.6 状态全文译文 模块界面与交互、检索、召回与索引、配置治理、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录RAGFlow DeepWiki 原始章节Chat and Conversation APIs 上一章7.5 下一章7.7
源码线索
  • api/apps/restful_apis/chat_api.py
  • api/apps/restful_apis/search_api.py
  • common/data_source/moodle_connector.py
  • test/testcases/test_http_api/test_chat_assistant_management/conftest.py
  • test/testcases/test_http_api/test_chat_assistant_management/test_chat_sdk_routes_unit.py
  • test/testcases/test_sdk_api/test_session_management/conftest.py
  • test/testcases/test_sdk_api/test_session_management/test_delete_sessions_with_chat_assistant.py
  • test/testcases/test_web_api/test_search_app/test_search_routes_unit.py
  • web/src/components/large-model-form-field.tsx
  • web/src/components/llm-select/next.tsx
模块标签
  • 界面与交互
  • 检索、召回与索引
  • 配置治理
  • 文档对象与元数据
  • 系统架构

章节正文

聊天与会话 API

原始 DeepWiki 页面https://deepwiki.com/infiniflow/ragflow/7.6-chat-and-conversation-apis

聊天与会话 API

相关源文件

本章引用的主要源码文件：

  • api/apps/restful_apis/chat_api.py
  • api/apps/restful_apis/search_api.py
  • common/data_source/moodle_connector.py
  • test/testcases/test_http_api/test_chat_assistant_management/conftest.py
  • test/testcases/test_http_api/test_chat_assistant_management/test_chat_sdk_routes_unit.py
  • test/testcases/test_sdk_api/test_session_management/conftest.py
  • test/testcases/test_sdk_api/test_session_management/test_delete_sessions_with_chat_assistant.py
  • test/testcases/test_web_api/test_search_app/test_search_routes_unit.py
  • web/src/components/large-model-form-field.tsx
  • web/src/components/llm-select/next.tsx
  • web/src/components/llm-setting-items/next.tsx
  • web/src/components/message-item/group-button.tsx
  • web/src/components/message-item/hooks.ts
  • web/src/components/message-item/index.tsx
  • web/src/components/next-message-item/uploaded-message-files.tsx
  • web/src/components/originui/select-with-search.tsx
  • web/src/hooks/logic-hooks.ts
  • web/src/hooks/use-chat-request.ts
  • web/src/interfaces/database/chat.ts
  • web/src/pages/next-chats/chat/app-settings/chat-basic-settings.tsx
  • web/src/pages/next-chats/chat/app-settings/chat-model-settings.tsx
  • web/src/pages/next-chats/chat/app-settings/chat-prompt-engine.tsx
  • web/src/pages/next-chats/chat/app-settings/chat-settings.tsx
  • web/src/pages/next-chats/chat/app-settings/dynamic-variable.tsx
  • web/src/pages/next-chats/chat/app-settings/use-chat-setting-schema.tsx
  • web/src/pages/next-chats/chat/chat-box/single-chat-box.tsx
  • web/src/pages/next-chats/chat/index.tsx
  • web/src/pages/next-chats/chat/sessions.tsx
  • web/src/pages/next-chats/hooks/use-send-chat-message.ts
  • web/src/pages/next-chats/hooks/use-upload-file.ts
  • web/src/utils/chat.ts
  • web/src/utils/tests/chat.test.ts

本文档介绍了 RAGFlow 中的聊天补全和会话管理 API，涵盖基于检索增强生成（RAG）的标准聊天助手和基于 Agent 的对话。内容包括会话生命周期管理、RAG 检索管线、带引用的响应生成以及与 OpenAI 兼容的端点。

架构总览

RAGFlow 提供两种主要的对话模式：聊天助手（基于 RAG）和 Agent（基于工作流）。两者都采用基于会话的架构，将对话组织成会话，每个会话维护各自的消息历史和上下文。

聊天系统组件

下图展示了自然语言交互空间与处理它们的核心 Python 类和数据库实体之间的关联。

RAGFlow · 聊天系统组件 · 图 1
RAGFlow · 聊天系统组件 · 图 1

来源： api/apps/restful_apis/chat_api.py:1-50, web/src/pages/next-chats/chat/chat-box/single-chat-box.tsx:26-30, web/src/hooks/logic-hooks.ts:203-213, web/src/pages/next-chats/hooks/use-send-chat-message.ts:45-45, web/src/interfaces/database/chat.ts:53-80

会话管理

会话将特定聊天助手或 Agent 的相关消息分组。每个会话维护各自的消息历史，可以独立创建、更新和检索。

会话生命周期与 UI 交互

前端通过自定义钩子管理会话状态，支持临时的"新"会话和持久化的历史会话。

RAGFlow · 会话生命周期与 UI 交互 · 图 2
RAGFlow · 会话生命周期与 UI 交互 · 图 2

来源： web/src/pages/next-chats/chat/sessions.tsx:44-50, web/src/utils/chat.ts:34-36, web/src/pages/next-chats/chat/index.tsx:49-59, web/src/hooks/logic-hooks.ts:173-201

批量操作

系统支持批量删除会话。Sessions 组件使用 Set<string> 跟踪 selectedIds，并调用 removeSessions 与后端通信以清除 Conversation 记录 web/src/pages/next-chats/chat/sessions.tsx:58-60, web/src/pages/next-chats/chat/sessions.tsx:97-123。

聊天补全流程

聊天补全端点处理核心的 RAG 逻辑，结合检索和生成。

标准聊天补全

主要的交互通过 useSendMessageWithSse 钩子进行，该钩子管理用于流取消的 AbortController 和用于处理传入数据块的 EventSourceParserStream web/src/hooks/logic-hooks.ts:203-213。

  1. 初始化：initializeSseRef 创建一个新的 AbortController web/src/hooks/logic-hooks.ts:211-213。
  2. 请求：向聊天端点发送带有 Authorization 请求头的 POST 请求 web/src/hooks/logic-hooks.ts:245-251。
  3. 流式传输：响应体通过 EventSourceParserStream 管道处理，以处理服务器发送事件 web/src/hooks/logic-hooks.ts:265-270。
配置与提示引擎

聊天行为由 PromptConfig 和 LlmSetting 控制 web/src/interfaces/database/chat.ts:11-51。

  • 系统提示词：在 prompt_config.system 中定义 web/src/interfaces/database/chat.ts:15。
  • 空响应：当未找到上下文时可配置的文本 web/src/interfaces/database/chat.ts:12。
  • RAG 控制：包括 quote（引用）、keyword（关键词搜索）和 use_kg（知识图谱）的开关 web/src/interfaces/database/chat.ts:17-20。

来源： web/src/pages/next-chats/chat/app-settings/chat-settings.tsx:41-74, web/src/pages/next-chats/chat/app-settings/chat-basic-settings.tsx:75-130, web/src/interfaces/database/chat.ts:11-29

检索与 RAG 流程

检索过程在聊天补全期间触发，为大语言模型（LLM）提供上下文。

引用与元数据

RAGFlow 通过为每个助手响应提供详细的引用来强调透明度。

  • 引用对象：每个助手消息包含一个 IReference，其中包含 chunks（单个文本片段）和 doc_aggs（聚合的文档信息）web/src/interfaces/database/chat.ts:136-140。
  • 元数据过滤：用户可以定义手动元数据过滤器（键、运算符、值），将检索限制到特定的文档子集 web/src/interfaces/database/chat.ts:82-91。
  • 片段元数据：如果通过 reference_metadata.include 启用，文档存储中的特定字段会与检索到的文本一起显示 web/src/pages/next-chats/chat/app-settings/chat-basic-settings.tsx:131-155。
响应预处理

前端在渲染之前对 LLM 输出应用了多个基于正则表达式的转换：

  • LaTeX：通过 preprocessLaTeX 预处理，确保与 KaTeX 分隔符兼容 web/src/utils/chat.ts:58-79。
  • 思考块：<think> 标签被转换为可展开的 HTML <details> 组件 web/src/utils/chat.ts:81-87。
  • 检索块：<retrieving> 标签被类似地转换，以显示后台的 RAG 活动 web/src/utils/chat.ts:89-95。

来源： web/src/utils/chat.ts:58-95, web/src/components/message-item/index.tsx:156-166, web/src/interfaces/database/chat.ts:121-134

消息渲染

MessageItem 组件是显示聊天历史的主要单元 web/src/components/message-item/index.tsx:39-53。

功能实现方式
Markdown通过支持引用的 MarkdownContent 渲染 web/src/components/message-item/index.tsx:148-154
引用在 ReferenceDocumentList 和 ReferenceImageList 中显示 web/src/components/message-item/index.tsx:156-166
TTS通过 AssistantGroupButton 和 useSpeech 钩子处理 web/src/components/message-item/group-button.tsx:65-85
反馈点赞/点踩按钮触发 useSendFeedback web/src/components/message-item/group-button.tsx:86-106

来源： web/src/components/message-item/index.tsx:77-187, web/src/components/message-item/group-button.tsx:35-52