⛑️ 事件：在 Open WebUI 中使用 __event_emitter__ 和 __event_call__
Open WebUI 的插件架構不僅僅是處理輸入並生成輸出——它更是與使用者介面和用戶的即時互動交流。為了讓您的 Tools、Functions 和 Pipes 更加動態，Open WebUI 通過 __event_emitter__ 和 __event_call__ 提供內建事件系統。
本指南將解釋什麼是事件，如何從您的代碼觸發它們，以及您可以使用的事件類型完整目錄（內容遠超僅僅是 "input"）。
🌊 什麼是事件？
事件是從您的後端代碼（Tool 或 Function）發送到 Web UI 的即時通知或互動請求。它們允許您更新聊天、顯示通知、請求確認、運行 UI 流程等等。
- 事件使用
__event_emitter__助手發送以進行單向更新，或者使用__event_call__當您需要用戶輸入或回應（例如確認、輸入等）。
比喻： 可以把事件看作您的插件可以觸發的推送通知和模態對話框，使聊天體驗更豐富、更具互動性。
🧰 基本用法
發送事件
您可以在 Tool 或 Function 的任意位置調用以下代碼來觸發事件：
await __event_emitter__(
{
"type": "status", # 請參考下文中的事件類型列表
"data": {
"description": "處理開始！",
"done": False,
"hidden": False,
},
}
)
您不需要手動添加像 chat_id 或 message_id 等字段——這些將由 Open WebUI 自動處理。
互動事件
當您需要在用戶回應之前暫停執行（例如確認/取消對話框、代碼執行或輸入）時，請使用 __event_call__：
result = await __event_call__(
{
"type": "input", # 或者 "confirmation", "execute"
"data": {
"title": "請輸入您的密碼",
"message": "此操作需要密碼",
"placeholder": "在此輸入您的密碼",
},
}
)
# result 將包含用戶輸入的值
📜 事件載荷結構
當您發出或調用事件時，基本結構如下：
{
"type": "event_type", // 請參考下文完整列表
"data": { ... } // 特定事件的數據載荷
}
大多數情況下，您只需設置 "type" 和 "data"。Open WebUI 將自動填充路由。
🗂 事件類型完整列表
以下是 所有支援的 type 值 的詳盡列表，包括其預期效果和數據結構。（基於對 Open WebUI 事件處理邏輯的最新分析。）
| type | 使用情景 | 數據載荷結構（示例） |
|---|---|---|
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" or "success" or "error" or "warning", content: "..."} |
confirmation (需要 __event_call__) | 請求確認（確定/取消對話框） | {title: "...", message: "..."} |
input (需要 __event_call__) | 請求用戶簡單輸入（"輸入框"對話框） | {title: "...", message: "...", placeholder: "...", value: ...} |
execute (需要 __event_call__) | 請求使用者端執行程式碼並返回結果 | {code: "...javascript code..."} |
其他/進階類型：
- 您可以自定義自己的類型並在UI層處理它們（或使用即將推出的事件擴展機制）。
❗ 特定事件類型的詳細資訊
status
在UI中顯示狀態/進度更新：
await __event_emitter__(
{
"type": "status",
"data": {
"description": "第一步/共三步：正在獲取資料...",
"done": False,
"hidden": False,
},
}
)
chat:message:delta 或 message
流式輸出（追加文字）：
await __event_emitter__(
{
"type": "chat:message:delta", # 或簡單地使用 "message"
"data": {
"content": "部分文字, "
},
}
)
# 稍後，隨著您生成更多內容：
await __event_emitter__(
{
"type": "chat:message:delta",
"data": {
"content": "下一段回應內容。"
},
}
)
chat:message 或 replace
設定（或取代）整個訊息內容：
await __event_emitter__(
{
"type": "chat:message", # 或 "replace"
"data": {
"content": "最終完整的回應內容。"
},
}
)
files 或 chat:message:files
附加或更新文件：
await __event_emitter__(
{
"type": "files", # 或 "chat:message:files"
"data": {
"files": [
# Open WebUI 文件物件
]
},
}
)
chat:title
更新聊天的標題：
await __event_emitter__(
{
"type": "chat:title",
"data": {
"title": "市場分析機器人會話"
},
}
)
chat:tags
更新聊天的標籤：
await __event_emitter__(
{
"type": "chat:tags",
"data": {
"tags": ["金融", "AI", "每日報告"]
},
}
)
source 或 citation （以及程式碼執行）
添加引用/文獻：
await __event_emitter__(
{
"type": "source", # 或 "citation"
"data": {
# Open WebUI 引用（文獻）物件
}
}
)
對於程式碼執行（追蹤執行狀態）：
await __event_emitter__(
{
"type": "source",
"data": {
# Open WebUI 程式碼來源（引用）物件
}
}
)
notification
顯示提示通知：
await __event_emitter__(
{
"type": "notification",
"data": {
"type": "info", # "success", "warning", "error"
"content": "操作已成功完成！"
}
}
)
confirmation (需要 __event_call__)
顯示確認對話框並獲取使用者回應：
result = await __event_call__(
{
"type": "confirmation",
"data": {
"title": "您確定嗎？",
"message": "您確定要繼續嗎？"
}
}
)
if result: # 或檢查結果內容
await __event_emitter__({
"type": "notification",
"data": {"type": "success", "content": "使用者已確認操作。"}
})
else:
await __event_emitter__({
"type": "notification",
"data": {"type": "warning", "content": "使用者取消了操作。"}
})
input (需要 __event_call__)
提示使用者輸入文字：
result = await __event_call__(
{
"type": "input",
"data": {
"title": "輸入您的姓名",
"message": "我們需要您的姓名以繼續。",
"placeholder": "您的全名"
}
}
)
user_input = result
await __event_emitter__(
{
"type": "notification",
"data": {"type": "info", "content": f"您輸入的是：{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"程式碼已執行，結果：{result}"
}
}
)
🏗️ 什麼時 候以及在哪裡使用事件
- 從任何工具或函數在 Open WebUI 中執行。
- 用於流式回應、顯示進度、請求使用者資料、更新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": "任務完成"}
})
問: 我如何提示使用者輸入並獲得他們的回答？
使用：
response = await __event_call__({
"type": "input",
"data": {
"title": "你叫什麼名字？",
"message": "請輸入您喜歡的名字：",
"placeholder": "名字"
}
})
# response 將是: {"value": "使用者的回答"}
問: __event_call__ 有哪些可用的事件類型？
"input": 輸入框對話"confirmation": 是/否、確定/取消對話"execute": 在客戶端運行提供的代碼並返回結果
問: 我能更新消息附件的文件嗎？
可以—使用 "files" 或 "chat:message:files" 事件類型和 {files: [...]} 負載。
問: 我能更新會話的標題或標籤嗎？
當然可以：相應使用 "chat:title" 或 "chat:tags"。
問: 我能將流式回應（部分 tokens）傳送給使用者嗎？
可以—在迴圈中發出 "chat:message:delta" 事件，然後以 "chat:message" 完成。
📝 結論
事件讓您可以在 Open WebUI 中實現即時交互的超能力。它們使您的代碼能夠更新內容、觸發通知、請求使用者輸入、傳送流式結果、處理代碼等等—無縫地將後端智慧集成到聊天界面中。
- 使用
__event_emitter__實現單向的狀態/內容更新。 - 使用
__event_call__實現需要使用者後續反饋的交互（輸入、確認、執行）。
參考本文檔以了解常見事件類型和結構，並探索 Open WebUI 源代碼或文件以獲取最新更新或自定義事件！
祝您在 Open WebUI 中愉快地進行事件驅動編程！🚀