⛑️ 이벤트: Open WebUI에서 `__event_emitter`와 `event_call__` 사용법

Open WebUI의 플러그인 아키텍처는 단순히 입력을 처리하고 출력을 생성하는 것을 넘어, UI와 사용자와의 실시간 상호작용을 가능하게 합니다. Tools, Functions, 및 Pipes를 더욱 동적으로 만들기 위해 Open WebUI는 __event_emitter__ 및 __event_call__ 헬퍼를 통해 내장된 이벤트 시스템을 제공합니다.

이 가이드는 이벤트가 무엇인지, 코드에서 이를 트리거하는 방법, 그리고 활용 가능한 이벤트 종류들의 전체 카탈로그에 대해 설명합니다 (단순히 "input" 이상의 내용을 포함).

🌊 이벤트란 무엇인가?

이벤트는 백엔드 코드(Tool 또는 Function)에서 웹 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에 알림("토스트") 표시	`{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": "1단계/3단계: 데이터를 가져오는 중...",
            "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__는 사용자로부터 응답이 필요한 경우(input, execute, confirmation)에 사용됩니다.

💡 팁 및 고급 정보

메시지당 여러 유형: 하나의 메시지에 대해 다양한 유형의 이벤트를 생성할 수 있습니다—예를 들어, status 업데이트를 표시한 후 chat:message:delta로 스트리밍하고 chat:message로 완료합니다.
커스텀 이벤트 유형: 위 목록은 표준이지만, 커스텀 UI 코드에서 감지하고 처리할 수 있는 자체 유형을 사용할 수 있습니다.
확장성: 이벤트 시스템은 발전할 수 있도록 설계되었습니다—항상 가장 최신 리스트와 고급 사용법은 Open WebUI 문서를 확인하세요.

🧐 FAQ

질문: 사용자에게 알림을 어떻게 트리거합니까?

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"를 적합하게 사용하십시오.

질문: 사용자에게 스트림 응답(부분 토큰)을 제공할 수 있습니까?

예—"chat:message:delta" 이벤트를 루프에서 방출한 뒤 "chat:message"로 완료하십시오.

📝 결론

이벤트는 Open WebUI 내에서 실시간, 상호작용 가능한 슈퍼파워를 제공합니다. 이를 통해 코드가 콘텐츠를 업데이트하고, 알림을 트리거하며, 사용자 입력을 요청하고, 결과를 스트림 처리하며, 코드를 처리하고, 기타 다수의 작업을 수행할 수 있습니다—뒷단의 인텔리전스를 채팅 UI에 매끄럽게 연결합니다.

__event_emitter__를 사용하여 한 방향 상태/콘텐츠 업데이트를 수행하세요.
__event_call__를 사용하여 사용자 후속 작업(입력, 확인, 실행)이 필요한 상호작용을 처리하세요.

일반적인 이벤트 유형 및 구조는 이 문서를 참조하고, Open WebUI 소스 코드 또는 문서를 통해 충격적 업데이트나 사용자 정의 이벤트를 탐구하세요!

Open WebUI에서 이벤트 기반 코딩을 행복하게 즐기세요! 🚀

🌊 이벤트란 무엇인가?​

🧰 기본 사용법​

이벤트 보내기​

상호작용 이벤트​

📜 이벤트 페이로드 구조​

🗂 이벤트 유형 전체 목록​

❗ 특정 이벤트 유형 상세 정보​

status​

chat:message:delta 또는 message​

chat:message 또는 replace​

files 또는 chat:message:files​

chat:title​

chat:tags​

source 또는 citation (및 코드 실행)​

notification​

confirmation (__event_call__ 필요)​

input (__event_call__ 필요)​

execute (__event_call__ 필요)​

🏗️ 이벤트를 사용할 시점 및 위치​

💡 팁 및 고급 정보​

🧐 FAQ​

질문: 사용자에게 알림을 어떻게 트리거합니까?​

질문: 사용자에게 입력을 요청하고 그 답변을 얻는 방법은?​

질문: __event_call__에서 사용할 수 있는 이벤트 유형은 무엇입니까?​

질문: 메시지에 첨부된 파일을 업데이트할 수 있습니까?​

질문: 대화 제목이나 태그를 업데이트할 수 있나요?​

질문: 사용자에게 스트림 응답(부분 토큰)을 제공할 수 있습니까?​

📝 결론​