agentic_huge_data_base / wiki
页面 Open WebUI · 4.6 变量替换系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 4.6

4.6 · 变量替换系统（Variable Substitution System）

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

项目Open WebUI 章节4.6 状态全文译文 模块工具、记忆与模型调用、界面与交互、认证、权限与安全、系统架构
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Variable Substitution System 上一章4.5 下一章5
源码线索
  • backend/open_webui/internal/db.py
  • backend/open_webui/migrations/env.py
  • backend/open_webui/models/oauth_sessions.py
  • backend/open_webui/retrieval/loaders/mistral.py
  • backend/open_webui/routers/configs.py
  • backend/open_webui/utils/webhook.py
  • src/lib/apis/configs/index.ts
  • src/lib/apis/tools/index.ts
  • src/lib/apis/users/index.ts
  • src/lib/components/chat/Chat.svelte
模块标签
  • 工具、记忆与模型调用
  • 界面与交互
  • 认证、权限与安全
  • 系统架构
  • 接口与服务契约

中文译文

变量替换系统（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/4.6-variable-substitution-system
翻译时间：2026-06-09T16:08:18.428Z
翻译模型：deepseek-chat
原文字符数：11246
项目：Open WebUI (open-webui)

---

变量替换系统

相关源文件

以下文件为本 wiki 页面的生成提供了上下文：

  • backend/open_webui/internal/db.py
  • backend/open_webui/migrations/env.py
  • backend/open_webui/models/oauth_sessions.py
  • backend/open_webui/retrieval/loaders/mistral.py
  • backend/open_webui/routers/configs.py
  • backend/open_webui/utils/webhook.py
  • src/lib/apis/configs/index.ts
  • src/lib/apis/tools/index.ts
  • src/lib/apis/users/index.ts
  • src/lib/components/chat/Chat.svelte
  • src/lib/components/chat/MessageInput.svelte
  • src/lib/components/chat/MessageInput/InputMenu.svelte
  • src/lib/components/chat/MessageInput/IntegrationsMenu.svelte
  • src/lib/components/chat/Messages.svelte
  • src/lib/components/chat/Messages/Message.svelte
  • src/lib/components/chat/Messages/MultiResponseMessages.svelte
  • src/lib/components/chat/Messages/ResponseMessage.svelte
  • src/lib/components/chat/Messages/UserMessage.svelte
  • src/lib/utils/index.ts
  • src/lib/utils/onedrive-file-picker.ts

概述

Open WebUI 中的变量替换系统允许用户使用双花括号语法（{{VARIABLE_NAME}}）将动态内容插入聊天消息。该系统支持常见数据插入（如当前日期或用户资料信息）的自动化，并通过自定义输入变量支持交互式模板。

系统将替换分为三种主要类型：

  1. 内置变量：预定义的系统变量（例如 {{USER_NAME}}、{{CURRENT_DATE}}），可自动解析。src/lib/components/chat/MessageInput.svelte:205-303
  2. 自定义输入变量：用户定义的占位符，会触发交互式模态框供用户输入值。src/lib/components/chat/MessageInput.svelte:185-203
  3. 模板令牌：用于角色名称或文件引用的服务器端或渲染时令牌（例如 {{char}}、{{VIDEO_FILE_ID_...}}）。src/lib/utils/index.ts:55-83

---

变量处理流程

处理主要发生在 MessageInput.svelte 组件中，在提交提示词之前。它涉及一个两阶段处理管道：用于自动化系统变量的 textVariableHandler 和用于交互式用户变量的 inputVariableHandler。

变量处理时序图

sequenceDiagram
    participant User as "用户"
    participant MessageInput as "MessageInput.svelte"
    participant TextHandler as "textVariableHandler()"
    participant InputHandler as "inputVariableHandler()"
    participant Modal as "InputVariablesModal.svelte"
    participant Editor as "RichTextInput.svelte"

    User->>MessageInput: 提交 "Hi {{USER_NAME}}, fill {{task}}"
    MessageInput->>TextHandler: 解析系统变量
    TextHandler->>TextHandler: 将 {{USER_NAME}} 替换为 "Alice"
    TextHandler-->>MessageInput: "Hi Alice, fill {{task}}"

    MessageInput->>InputHandler: 检测自定义变量
    InputHandler->>InputHandler: extractInputVariables() 找到 "task"

    alt 检测到自定义变量
        InputHandler->>Modal: 设置 showInputVariablesModal = true
        Modal->>User: 提示输入 "task" 的值
        User->>Modal: 输入 "Report"
        Modal->>InputHandler: inputVariablesModalCallback({task: "Report"})
        InputHandler->>Editor: replaceVariables({task: "Report"})
        Editor-->>MessageInput: "Hi Alice, fill Report"
    end

    MessageInput->>MessageInput: 最终提交提示词

来源： src/lib/components/chat/MessageInput.svelte:185-333、src/lib/components/chat/Chat.svelte:249-261

---

代码实体架构

该系统将前端 UI 组件与用于字符串解析和 API 数据检索的工具逻辑连接起来。

变量替换系统组件

graph TB
    subgraph "前端组件"
        MI["MessageInput.svelte"]
        IVM["InputVariablesModal.svelte"]
        RTI["RichTextInput.svelte"]
    end

    subgraph "核心逻辑_MessageInput_svelte"
        TVH["textVariableHandler()<br/>第 205 行"]
        IVH["inputVariableHandler()<br/>第 185 行"]
        RV["replaceVariables()<br/>第 315 行"]
    end

    subgraph "工具层_utils_index_ts"
        EIV["extractInputVariables()"]
        ECBW["extractCurlyBraceWords()"]
        RT["replaceTokens()<br/>第 55 行"]
        ROC["replaceOutsideCode()<br/>第 46 行"]
    end

    subgraph "数据提供者"
        AU["auths.ts: getSessionUser()"]
        UP["utils/index.ts: getUserPosition()"]
        CL["浏览器: navigator.clipboard"]
    end

    MI --> TVH
    MI --> IVH
    TVH --> AU
    TVH --> UP
    TVH --> CL

    IVH --> EIV
    EIV --> ECBW
    IVH --> IVM
    IVM -- "回调" --> RV
    RV --> RTI

    RT --> ROC

来源： src/lib/components/chat/MessageInput.svelte:153-324、src/lib/utils/index.ts:46-83、src/lib/utils/index.ts:55-69

---

内置变量

这些变量在 textVariableHandler 中使用本地状态、浏览器 API 或缓存的用户数据同步解析。

用户信息变量

用户数据通过 getSessionUser 获取并存储在 _user 存储中。src/lib/components/chat/MessageInput.svelte:59、src/lib/components/chat/MessageInput.svelte:235-279

变量实现方式来源
{{USER_NAME}}sessionUser?.namesrc/lib/components/chat/MessageInput.svelte:237
{{USER_EMAIL}}sessionUser?.emailsrc/lib/components/chat/MessageInput.svelte:243
{{USER_BIO}}sessionUser?.biosrc/lib/components/chat/MessageInput.svelte:251
{{USER_AGE}}getAge(sessionUser?.date_of_birth)src/lib/components/chat/MessageInput.svelte:274
{{USER_LANGUAGE}}localStorage.getItem('locale')src/lib/components/chat/MessageInput.svelte:285
日期和时间变量

格式化通过 $lib/utils 中的 dayjs 包装器处理。src/lib/utils/index.ts:6-15

变量工具函数来源
{{CURRENT_DATE}}getFormattedDate()src/lib/components/chat/MessageInput.svelte:290
{{CURRENT_TIME}}getFormattedTime()src/lib/components/chat/MessageInput.svelte:295
{{CURRENT_DATETIME}}getCurrentDateTime()src/lib/components/chat/MessageInput.svelte:300
{{CURRENT_WEEKDAY}}getWeekday()src/lib/components/chat/MessageInput.svelte:310
上下文变量

这些变量利用浏览器级别的权限。

  • {{CLIPBOARD}}：使用 navigator.clipboard.readText()。它还会尝试通过 navigator.clipboard.read() 读取 clipboardItems；如果找到图像 blob，则会自动将其处理为 File 对象。src/lib/components/chat/MessageInput.svelte:206-231
  • {{USER_LOCATION}}：使用 getUserPosition()，该函数封装了 Geolocation API。它以 lat, long 格式返回坐标。src/lib/components/chat/MessageInput.svelte:235-241

---

自定义输入变量

自定义变量允许实现类似模板的行为，UI 通过模态框提示用户输入特定值。

检测与交互

extractInputVariables 函数识别 {{}} 内不属于保留内置列表的单词。src/lib/components/chat/MessageInput.svelte:46

  1. 触发：使用提示词文本调用 inputVariableHandler。src/lib/components/chat/MessageInput.svelte:185
  2. 模态框：如果存在自定义变量，则将 showInputVariablesModal 设置为 true。src/lib/components/chat/MessageInput.svelte:194
  3. 持久化：inputVariableValues 对象存储用户的输入，允许值在替换之间持久存在。src/lib/components/chat/MessageInput.svelte:156-197
  4. 编辑器更新：用户保存模态框后，调用 replaceVariables 在 RichTextInput 组件中执行文本替换。src/lib/components/chat/MessageInput.svelte:315-324

---

模板令牌（服务器端与渲染端）

模板令牌由 utils/index.ts 中的 replaceTokens 处理。这些令牌通常在渲染响应或准备负载时进行处理。src/lib/utils/index.ts:55-83

代码块保护

为防止系统意外替换代码块内的变量，使用 replaceOutsideCode 工具分割内容，仅对文本段应用替换器。src/lib/utils/index.ts:46-53

代码保护逻辑

graph LR
    Input["原始内容"] --> Split["按 Markdown 代码块分割<br/>(反引号)"]
    Split --> Filter{"是否为代码段？"}
    Filter -- "是" --> Preserve["保持不变"]
    Filter -- "否" --> Replace["应用 replaceTokens()"]
    Preserve --> Join["合并段"]
    Replace --> Join
    Join --> Output["渲染后的消息"]
支持的令牌
令牌替换内容来源
{{char}}角色名称src/lib/utils/index.ts:58
{{user}}用户名称src/lib/utils/index.ts:59
{{VIDEO_FILE_ID_...}}渲染一个包含文件内容 URL 的 HTML5 <video> 标签。src/lib/utils/index.ts:61-64
{{HTML_FILE_ID_...}}渲染一个自定义 <file type="html" /> 标签。src/lib/utils/index.ts:66-68

来源： src/lib/utils/index.ts:46-83

---

与聊天组件的集成

变量替换系统与 Chat.svelte 和 Messages.svelte 中的消息生命周期集成。

  • 聊天导航：在聊天之间导航时，Chat.svelte 中的 navigateHandler 会重置提示词并清除消息输入状态。src/lib/components/chat/Chat.svelte:183-238
  • 消息编辑：当用户编辑消息时（UserMessage.svelte），会调用 editMessage 处理程序，允许内容更新和重新替换。src/lib/components/chat/Messages/UserMessage.svelte:94-105
  • 历史重建：聊天历史的结构性更改（例如分支）会通过 buildMessages 触发消息列表重建，确保替换后的变量在 UI 中正确反映。src/lib/components/chat/Messages.svelte:186-205

来源： src/lib/components/chat/Chat.svelte:183-246、src/lib/components/chat/Messages/UserMessage.svelte:94-105、src/lib/components/chat/Messages.svelte:186-205