跳到主要内容

⛑️ 事件：在 Open WebUI 中使用 __event_emitter__ 和 __event_call__

Open WebUI 的插件架构不仅仅是处理输入和产生输出——它关乎与 UI 和用户的实时、交互式通信。为了使您的工具（Tools）、函数（Functions）和管道（Pipes）更具动态性，Open WebUI 通过 __event_emitter__ 和 __event_call__ 助手提供了一个内置的事件系统。

本指南将解释什么是事件、如何从您的代码中触发事件，以及您可以使用的事件类型完整目录（包括远不止 "input"）。

🌊 什么是事件？​

事件是从您的后端代码（工具或函数）发送到 Web UI 的实时通知或交互请求。它们允许您更新聊天、显示通知、请求确认、运行 UI 流程等等。

  • 事件通过 __event_emitter__ 助手发送用于单向更新，或者在您需要用户输入或响应（例如，确认、输入等）时使用 __event_call__。

比喻
可以将事件想象成您的插件可以触发的推送通知和模态对话框，使聊天体验更丰富、更具互动性。

🧰 基本用法​

发送事件​

您可以在工具（Tool）或函数（Function）内的任何位置通过调用以下代码触发事件：

await __event_emitter__(
    {
        "type": "status",  # See the event types list below
        "data": {
            "description": "Processing started!",
            "done": False,
            "hidden": False,
        },
    }
)

您无需手动添加 chat_id 或 message_id 等字段——这些由 Open WebUI 自动处理。

交互式事件​

当您需要暂停执行直到用户响应时（例如，确认/取消对话框、代码执行或输入），请使用 __event_call__：

result = await __event_call__(
    {
        "type": "input",  # Or "confirmation", "execute"
        "data": {
            "title": "Please enter your password",
            "message": "Password is required for this action",
            "placeholder": "Your password here",
        },
    }
)
# result will contain the user's input value

📜 事件负载结构​

当您触发或调用一个事件时，其基本结构是：

{
  "type": "event_type",   // See full list below
  "data": { ... }         // Event-specific payload
}

大多数情况下，您只需要设置 "type" 和 "data"。Open WebUI 会自动填充路由信息。

🗂 事件类型完整列表​

下面是一个全面的表格，列出了所有支持的事件 type 值，以及它们的预期效果和数据结构。（这基于对 Open WebUI 事件处理逻辑的最新分析。）

类型何时使用数据负载结构（示例）
status显示消息的状态更新/历史记录{description: ..., done: bool, hidden: bool}
chat:completion提供聊天完成结果（自定义，详见 Open WebUI 内部实现）
chat:message:delta,
message		向当前消息追加内容{content: "要追加的文本"}
chat:message,
replace		完全替换当前消息内容{content: "替换文本"}
chat:message:files,
files		设置或覆盖消息文件（用于上传、输出）{files: [...]}
chat:title设置（或更新）聊天对话标题主题字符串 或 {title: ...}
chat:tags更新聊天的标签集标签数组或对象
source,
citation		添加来源/引用，或代码执行结果对于代码：请参阅下方。
notification在 UI 中显示通知（"toast" 提示）{type: "info" 或 "success" 或 "error" 或 "warning", content: "..."}
confirmation
（需要 __event_call__）		请求确认（确定/取消对话框）{title: "...", message: "..."}
input
（需要 __event_call__）		请求简单用户输入（"输入框" 对话框）{title: "...", message: "...", placeholder: "...", value: ...}
execute
（需要 __event_call__）		请求用户侧代码执行并返回结果{code: "...javascript 代码..."}

其他/高级类型

  • 您可以定义自己的类型并在 UI 层处理它们（或使用即将推出的事件扩展机制）。

❗ 特定事件类型详情​

status​

在 UI 中显示状态/进度更新

await __event_emitter__(
    {
        "type": "status",
        "data": {
            "description": "Step 1/3: Fetching data...",
            "done": False,
            "hidden": False,
        },
    }
)

chat:message:delta 或 message​

流式输出（追加文本）

await __event_emitter__(
    {
        "type": "chat:message:delta",  # or simply "message"
        "data": {
            "content": "Partial text, "
        },
    }
)

# Later, as you generate more:
await __event_emitter__(
    {
        "type": "chat:message:delta",
        "data": {
            "content": "next chunk of response."
        },
    }
)

chat:message 或 replace​

设置（或替换）整个消息内容

await __event_emitter__(
    {
        "type": "chat:message",  # or "replace"
        "data": {
            "content": "Final, complete response."
        },
    }
)

files 或 chat:message:files​

附加或更新文件

await __event_emitter__(
    {
        "type": "files",  # or "chat:message:files"
        "data": {
            "files": [
               # Open WebUI File Objects
            ]
        },
    }
)

chat:title​

更新聊天的标题

await __event_emitter__(
    {
        "type": "chat:title",
        "data": {
            "title": "Market Analysis Bot Session"
        },
    }
)

chat:tags​

更新聊天的标签

await __event_emitter__(
    {
        "type": "chat:tags",
        "data": {
            "tags": ["finance", "AI", "daily-report"]
        },
    }
)

source 或 citation（和代码执行）​

添加引用/来源

await __event_emitter__(
    {
        "type": "source",  # or "citation"
        "data": {
            # Open WebUI Source (Citation) Object
        }
    }
)

用于代码执行（跟踪执行状态）

await __event_emitter__(
    {
        "type": "source",
        "data": {
            # Open WebUI Code Source (Citation) Object
        }
    }
)

notification​

显示通知提示

await __event_emitter__(
    {
        "type": "notification",
        "data": {
            "type": "info",  # "success", "warning", "error"
            "content": "The operation completed successfully!"
        }
    }
)

confirmation（需要 __event_call__）​

显示确认对话框并获取用户响应

result = await __event_call__(
    {
        "type": "confirmation",
        "data": {
            "title": "Are you sure?",
            "message": "Do you really want to proceed?"
        }
    }
)

if result:  # or check result contents
    await __event_emitter__({
        "type": "notification",
        "data": {"type": "success", "content": "User confirmed operation."}
    })
else:
    await __event_emitter__({
        "type": "notification",
        "data": {"type": "warning", "content": "User cancelled."}
    })

input（需要 __event_call__）​

提示用户进行文本输入

result = await __event_call__(
    {
        "type": "input",
        "data": {
            "title": "Enter your name",
            "message": "We need your name to proceed.",
            "placeholder": "Your full name"
        }
    }
)

user_input = result
await __event_emitter__(
    {
        "type": "notification",
        "data": {"type": "info", "content": f"You entered: {user_input}"}
    }
)

execute（需要 __event_call__）​

在用户端动态运行代码

result = await __event_call__(
    {
        "type": "execute",
        "data": {
            "code": "print(40 + 2);",
        }
    }
)

await __event_emitter__(
    {
        "type": "notification",
        "data": {
            "type": "info",
            "content": f"Code executed, result: {result}"
        }
    }
)

🏗️ 何时何地使用事件​

  • 在 Open WebUI 中的任何工具（Tool）或函数（Function）中。
  • 用于流式传输响应、显示进度、请求用户数据、更新 UI 或显示补充信息/文件。
  • await __event_emitter__ 用于单向消息（触发即忘）。
  • await __event_call__ 用于需要用户响应的交互（输入、执行、确认）。

💡 提示与高级注意事项​

  • 每条消息支持多种类型： 您可以为一条消息触发多个不同类型的事件——例如，先显示 status 更新，然后用 chat:message:delta 进行流式传输，最后用 chat:message 完成。
  • 自定义事件类型： 尽管上述列表是标准类型，但您可以使用自己的类型并在自定义 UI 代码中检测/处理它们。
  • 可扩展性： 事件系统设计为可演进——请始终查阅 Open WebUI 文档 以获取最新列表和高级用法。

🧐 常见问题解答​

问：如何为用户触发通知？​

使用 notification 类型

await __event_emitter__({
    "type": "notification",
    "data": {"type": "success", "content": "Task complete"}
})

问：如何提示用户输入并获取他们的答案？​

使用

response = await __event_call__({
    "type": "input",
    "data": {
        "title": "What's your name?",
        "message": "Please enter your preferred name:",
        "placeholder": "Name"
    }
})
# response will be: {"value": "user's answer"}

问：__event_call__ 可用哪些事件类型？​

  • "input"：输入框对话框
  • "confirmation"：是/否、确定/取消对话框
  • "execute"：在客户端运行提供的代码并返回结果

问：我可以更新附加到消息的文件吗？​

是的——使用 "files" 或 "chat:message:files" 事件类型，并附带 {files: [...]} 负载。

问：我可以更新对话标题或标签吗？​

当然可以：相应地使用 "chat:title" 或 "chat:tags"。

问：我可以向用户流式传输响应（部分令牌）吗？​

是的——在循环中触发 "chat:message:delta" 事件，然后以 "chat:message" 结束。

📝 总结​

事件赋予您 Open WebUI 内部的实时交互式超能力。它们让您的代码能够更新内容、触发通知、请求用户输入、流式传输结果、处理代码等等——将您的后端智能无缝地接入聊天 UI。

  • 使用 __event_emitter__ 进行单向状态/内容更新。
  • 使用 __event_call__ 进行需要用户后续操作的交互（输入、确认、执行）。

请参阅本文档以了解常见事件类型和结构，并查阅 Open WebUI 源代码或文档以获取最新更新或自定义事件！

祝您在 Open WebUI 中事件驱动的编码愉快！🚀