6.2 · 聊天中间件与请求流（Chat Middleware and Request Flow）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节6.2 状态全文译文模块工具、记忆与模型调用、接口与服务契约、频道、笔记与协作、检索、召回与知识系统

项目要点页2.5 参考项目项目章节目录Open WebUI DeepWiki 原始章节Chat Middleware and Request Flow 上一章6.1 下一章6.3

源码线索

backend/open_webui/functions.py
backend/open_webui/migrations/versions/c1d2e3f4a5b6_add_shared_chat_table.py
backend/open_webui/models/shared_chats.py
backend/open_webui/tools/builtin.py
backend/open_webui/utils/access_control/__init__.py
backend/open_webui/utils/access_control/files.py
backend/open_webui/utils/chat.py
backend/open_webui/utils/filter.py
backend/open_webui/utils/middleware.py
backend/open_webui/utils/models.py

模块标签

工具、记忆与模型调用
接口与服务契约
频道、笔记与协作
检索、召回与知识系统
界面与交互

中文译文

聊天中间件与请求流（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/6.2-chat-middleware-and-request-flow

翻译时间：2026-06-09T16:08:58.609Z

翻译模型：deepseek-chat

原文字符数：17592

项目：Open WebUI (open-webui)

---

聊天中间件与请求流程

目的与范围

本文档详细介绍了在 backend/open_webui/utils/middleware.py 中实现的聊天中间件编排层，具体包括 process_chat_payload 函数及其关联的处理程序序列。该中间件位于 FastAPI 端点与 LLM 生成之间，负责为请求增加记忆、网络搜索结果、RAG 上下文、工具执行和图像生成等能力。

关于 FastAPI 应用初始化和路由，请参见 6.1 FastAPI 应用核心。关于中间件调用的具体子系统，请参见 6.3 工具执行系统、6.4 记忆与上下文管理、6.5 网络搜索集成 和 6.6 图像生成集成。

来源： backend/open_webui/utils/middleware.py:1-2400

---

请求流程概述

中间件通过一个顺序管道处理聊天请求，在将负载传递给 LLM 生成之前，在每个阶段对其进行丰富。该流程由 process_chat_payload 在 backend/open_webui/utils/middleware.py:1467-1678 中协调，在聊天补全请求期间执行。

高层请求流程图

graph TB
    Request["POST /api/chat/completions<br/>(routers/openai.py)"]
    ProcessPayload["process_chat_payload()<br/>(middleware.py)"]

    InletFilter["管道入口过滤器<br/>process_pipeline_inlet_filter()"]
    MemoryHandler["chat_memory_handler()<br/>查询用户记忆"]
    WebSearchHandler["chat_web_search_handler()<br/>若启用则搜索网络"]
    FilesHandler["处理文件与 RAG<br/>query_doc() / query_collection()"]
    ImageGenHandler["chat_image_generation_handler()<br/>检测并生成图像"]
    ToolsHandler["chat_completion_tools_handler()<br/>执行函数调用"]

    ApplyContext["apply_source_context_to_messages()<br/>注入 RAG 模板"]
    LLMGen["generate_chat_completion()<br/>(utils/chat.py)"]
    OutletFilter["管道出口过滤器<br/>process_pipeline_outlet_filter()"]

    Response["StreamingResponse<br/>返回客户端"]

    Request --> ProcessPayload
    ProcessPayload --> InletFilter
    InletFilter --> MemoryHandler
    MemoryHandler --> WebSearchHandler
    WebSearchHandler --> FilesHandler
    FilesHandler --> ApplyContext
    ApplyContext --> ImageGenHandler
    ImageGenHandler --> ToolsHandler
    ToolsHandler --> LLMGen
    LLMGen --> OutletFilter
    OutletFilter --> Response

来源： backend/open_webui/utils/middleware.py:1467-1678, backend/open_webui/utils/chat.py:158-220

---

主入口点：process_chat_payload

backend/open_webui/utils/middleware.py:1467-1678 中的 process_chat_payload 函数是主要的编排器。它接收聊天补全请求体，并在 LLM 生成之前协调所有丰富处理程序。

函数签名与核心流程

graph LR
    Input["form_data: dict<br/>user: UserModel<br/>extra_params: dict"]
    ProcessPayload["process_chat_payload()"]

    Metadata["metadata = extra_params['__metadata__']<br/>event_emitter = extra_params['__event_emitter__']<br/>event_call = extra_params['__event_call__']"]

    Handlers["顺序调用处理程序：<br/>1. 管道入口过滤器<br/>2. 记忆处理程序<br/>3. 网络搜索处理程序<br/>4. 文件/RAG 处理<br/>5. 图像生成<br/>6. 工具执行"]

    Output["修改后的 form_data<br/>准备用于 LLM 生成"]

    Input --> ProcessPayload
    ProcessPayload --> Metadata
    Metadata --> Handlers
    Handlers --> Output

该函数使用 extra_params 传递事件发射器以实现实时状态更新，以及关于聊天/消息上下文的元数据。所有处理程序都通过 get_event_emitter backend/open_webui/socket/main.py:35 接收这些参数，用于 WebSocket 通信。

来源： backend/open_webui/utils/middleware.py:1467-1678, backend/open_webui/socket/main.py:33-36

---

处理程序执行顺序

处理程序按特定顺序执行，以确保依赖关系得到满足（例如，在 RAG 上下文注入之前，网络搜索结果可用）。每个处理程序可以修改 form_data["messages"] 或向 form_data["files"] 添加条目。

处理程序调用顺序

顺序	处理程序函数	用途	修改内容
1	`process_pipeline_inlet_filter`	执行自定义管道入口过滤器 `backend/open_webui/routers/pipelines.py:56`	`form_data`
2	`chat_memory_handler`	查询并注入用户记忆	`form_data["messages"]`（系统消息）
3	`chat_web_search_handler`	生成查询并搜索网络	`form_data["files"]`（添加搜索结果）
4	文件处理 + RAG	查询向量集合以获取文件上下文	来源列表（内部）
5	`apply_source_context_to_messages`	注入带来源的 RAG 模板	`form_data["messages"]`
6	`chat_image_generation_handler`	检测图像请求并生成	通过 WebSocket 发射文件
7	`chat_completion_tools_handler`	执行工具/函数调用	将工具结果添加到来源
8	`generate_chat_completion`	使用丰富上下文调用 LLM `backend/open_webui/utils/chat.py:158`	不适用（生成）
9	`process_pipeline_outlet_filter`	执行自定义管道出口过滤器 `backend/open_webui/routers/pipelines.py:57`	响应

来源： backend/open_webui/utils/middleware.py:1467-1678, backend/open_webui/routers/pipelines.py:55-58

---

记忆集成：chat_memory_handler

backend/open_webui/utils/middleware.py:914-955 中的 chat_memory_handler 函数查询用户的记忆向量数据库以检索相关的历史上下文，并将其作为系统消息注入。

记忆检索流程

sequenceDiagram
    participant Middleware as chat_memory_handler()
    participant QueryMemory as query_memory()<br/>(routers/memories.py)
    participant VectorDB as ASYNC_VECTOR_DB_CLIENT
    participant Messages as form_data["messages"]

    Middleware->>QueryMemory: QueryMemoryForm(content=user_message, k=3)
    QueryMemory->>VectorDB: 搜索记忆集合 user-memory-{user_id}
    VectorDB-->>QueryMemory: results.documents, results.metadatas
    QueryMemory-->>Middleware: 带时间戳的记忆文档

    Middleware->>Middleware: 格式化为"用户上下文"字符串
    Middleware->>Messages: add_or_update_system_message(context, append=True)

处理程序将记忆格式化为包含创建日期的形式："1. [2024-01-15] 用户偏好简洁回复\n..."。此上下文通过 add_or_update_system_message backend/open_webui/utils/misc.py:88 追加到系统消息中。

来源： backend/open_webui/utils/middleware.py:914-955, backend/open_webui/tools/builtin.py:26-33, backend/open_webui/utils/misc.py:88-90

---

网络搜索集成：chat_web_search_handler

backend/open_webui/utils/middleware.py:751-911 中的 chat_web_search_handler 函数通过从对话中生成搜索查询并使用配置的搜索引擎执行它们来编排网络搜索。

网络搜索管道

graph TB
    Handler["chat_web_search_handler()"]
    GenQueries["generate_queries()<br/>(routers/tasks.py)"]
    LLM["任务模型<br/>生成 1-3 个查询"]

    ProcessSearch["process_web_search()<br/>(routers/retrieval.py)"]
    SearchEngine["搜索引擎<br/>(brave, duckduckgo 等)"]
    WebLoader["网络加载器<br/>(playwright, firecrawl 等)"]

    VectorDB["向量数据库<br/>(可选)"]

    Files["form_data['files']<br/>添加搜索结果"]

    Handler --> GenQueries
    GenQueries --> LLM
    LLM --> ProcessSearch
    ProcessSearch --> SearchEngine
    SearchEngine --> WebLoader
    WebLoader --> VectorDB
    VectorDB --> Files

处理程序通过 __event_emitter__ 发射状态事件以实现实时 UI 更新 backend/open_webui/utils/middleware.py:754：

"web_search" - 正在搜索网络（done: false）
"web_search_queries_generated" - 查询已生成
"web_search" - 搜索完成，包含 URL（done: true）

搜索结果以类型 "web_search" 添加到 form_data["files"]。

来源： backend/open_webui/utils/middleware.py:751-911, backend/open_webui/routers/tasks.py:38, backend/open_webui/routers/retrieval.py:45

---

文件与 RAG 上下文处理

文件处理在网络搜索和记忆处理程序完成后执行。中间件使用 query_doc 或 query_collection_with_hybrid_search 查询附加到消息的文件的向量集合。

文件处理与上下文聚合

graph TB
    Files["form_data.get('files', [])"]

    CheckType{"文件类型？"}

    Collection["存在 collection_name"]
    DirectDocs["存在 docs<br/>(绕过模式)"]

    QueryVector["query_doc()<br/>或 query_collection_with_hybrid_search()"]
    VectorDB["VECTOR_DB_CLIENT"]

    Rerank["重新排序<br/>(若启用)"]

    Sources["sources = []<br/>聚合结果"]

    ApplyContext["apply_source_context_to_messages()<br/>注入 RAG 模板"]

    Files --> CheckType
    CheckType --> Collection
    CheckType --> DirectDocs

    Collection --> QueryVector
    QueryVector --> VectorDB
    VectorDB --> Rerank
    Rerank --> Sources

    DirectDocs --> Sources

    Sources --> ApplyContext

关键配置变量：

RAG_FULL_CONTEXT - 包含所有文档块与仅包含 top-k backend/open_webui/config.py:121
RAG_TOP_K - 检索的块数量 backend/open_webui/config.py:121
RAG_RELEVANCE_THRESHOLD - 最低相关性分数 backend/open_webui/config.py:121

来源： backend/open_webui/utils/middleware.py:289-337, backend/open_webui/retrieval/utils.py:1-100

---

来源上下文应用：apply_source_context_to_messages

backend/open_webui/utils/middleware.py:289-337 中的 apply_source_context_to_messages 函数获取聚合的来源并使用 RAG 模板进行格式化。

RAG 模板应用

graph LR
    Sources["sources: list[dict]<br/>每个包含 'source', 'document', 'metadata'"]

    BuildContext["构建 context_string：<br/>&lt;source id='1' name='file.pdf'&gt;内容&lt;/source&gt;"]

    Template["rag_template()<br/>(utils/task.py)"]
    RAGTemplate["RAG_TEMPLATE 配置<br/>默认：使用上下文来回答"]

    Inject{"RAG_SYSTEM_CONTEXT?"}

    SystemMsg["add_or_update_system_message()<br/>追加到系统消息"]
    UserMsg["add_or_update_user_message()<br/>前置到用户消息"]

    Sources --> BuildContext
    BuildContext --> Template
    Template --> RAGTemplate
    RAGTemplate --> Inject

    Inject -->|True| SystemMsg
    Inject -->|False| UserMsg

上下文字符串使用带有引用 ID 的 XML 风格标签。rag_template backend/open_webui/utils/task.py:81 函数将其与 RAG_TEMPLATE 配置结合。

来源： backend/open_webui/utils/middleware.py:289-337, backend/open_webui/utils/task.py:81, backend/open_webui/env.py:136

---

工具执行：chat_completion_tools_handler

backend/open_webui/utils/middleware.py:482-709 中的 chat_completion_tools_handler 函数通过识别要调用的工具并执行它们来编排工具调用。它支持内置工具 backend/open_webui/tools/builtin.py:1-101 和通过 get_tools backend/open_webui/utils/tools.py:164 加载的自定义工具。

工具执行流程

sequenceDiagram
    participant Handler as chat_completion_tools_handler()
    participant TaskModel as 任务模型<br/>(get_task_model_id)
    participant ToolRegistry as tools 字典<br/>(get_tools)
    participant EventCaller as event_caller<br/>("execute:tool" 事件)
    participant ProcessResult as process_tool_result()
    participant Sources as sources 列表

    Handler->>Handler: 构建 tools_function_calling_prompt
    Handler->>TaskModel: 生成函数调用 JSON
    TaskModel-->>Handler: 函数调用响应

    loop 对于每个工具调用
        alt 直接工具（MCP/外部）
            Handler->>EventCaller: emit("execute:tool", tool_params)
            EventCaller-->>Handler: tool_result
        else 内部工具
            Handler->>ToolRegistry: tool_function(**params)
            ToolRegistry-->>Handler: tool_result
        end

        Handler->>ProcessResult: process_tool_result()
        Handler->>Sources: 将工具结果追加为来源
    end

来源： backend/open_webui/utils/middleware.py:482-709, backend/open_webui/utils/tools.py:164-210, backend/open_webui/utils/task.py:80

---

工具结果引用生成

工具结果通过 get_citation_source_from_tool_result backend/open_webui/utils/middleware.py:221-287 转换为引用来源。

工具特定来源解析

工具名称	来源格式	元数据字段
`search_web`	搜索结果数组	`title`, `link`, `snippet`, `url`
`view_knowledge_file`	单个文件内容	`filename`, `file_id`, `knowledge_name`
`query_knowledge_files`	按来源分组的多个块	`file_id`, `note_id`, `source`, `type`

来源： backend/open_webui/utils/middleware.py:221-287

---

图像生成：chat_image_generation_handler

backend/open_webui/utils/middleware.py:1001-1144 中的 chat_image_generation_handler 检测图像生成请求并触发相应的路由器函数。

图像生成流程

graph TB
    Handler["chat_image_generation_handler()"]
    CheckImages{"存在图像？"}
    EditFlow["image_edits()<br/>(routers/images.py)"]
    GenFlow["image_generations()<br/>(routers/images.py)"]
    EmitFiles["emit('files', 生成的图像)"]

    Handler --> CheckImages
    CheckImages -->|是| EditFlow
    CheckImages -->|否| GenFlow
    EditFlow --> EmitFiles
    GenFlow --> EmitFiles

来源： backend/open_webui/utils/middleware.py:1001-1144, backend/open_webui/routers/images.py:49-54

---

响应处理：process_chat_response

在 LLM 生成之后，process_chat_response backend/open_webui/utils/middleware.py:1147-1464 处理流，处理推理标签和代码解释器块。

响应处理管道

graph LR
    Stream["LLM 响应流"]
    ProcessResponse["process_chat_response()"]
    ExtractReasoning["提取推理块<br/>think/thought 标签"]
    ExtractCode["提取代码块<br/>code_interpreter 标签"]
    ExecuteCode["execute_code_jupyter()"]
    StreamBack["产出块"]

    Stream --> ProcessResponse
    ProcessResponse --> ExtractReasoning
    ExtractReasoning --> ExtractCode
    ExtractCode --> ExecuteCode
    ExecuteCode --> StreamBack

支持的推理标签： 定义在 DEFAULT_REASONING_TAGS backend/open_webui/utils/middleware.py:153-162 中。

来源： backend/open_webui/utils/middleware.py:1147-1464, backend/open_webui/utils/middleware.py:153-162

---

事件发射器与实时状态

事件通过 extra_params 中传递的 __event_emitter__ 函数发射，该函数从 get_event_emitter backend/open_webui/socket/main.py:35 获取。

事件类型	数据字段	用途
`status`	`action`, `description`, `done`	通用状态更新
`files`	`files`	发射生成/处理的文件
`embeds`	`embeds`	从工具发射 UI 嵌入

来源： backend/open_webui/utils/middleware.py:754-882, backend/open_webui/socket/main.py:33-36

---

配置变量

变量	位置	用途
`ENABLE_WEB_SEARCH`	`backend/open_webui/env.py:1-150`	启用网络搜索处理程序
`ENABLE_REALTIME_CHAT_SAVE`	`backend/open_webui/env.py:134`	实时保存聊天状态
`CHAT_RESPONSE_MAX_TOOL_CALL_RETRIES`	`backend/open_webui/env.py:132`	工具失败的最大重试次数
`RAG_SYSTEM_CONTEXT`	`backend/open_webui/env.py:136`	将 RAG 注入为系统消息与用户消息

来源： backend/open_webui/env.py:1-150