Skip to main content

๐Ÿช„ Filter Function: Modify Inputs and Outputs

Welcome to the comprehensive guide on Filter Functions in Open WebUI! Filters are a flexible and powerful plugin system for modifying data before it's sent to the Large Language Model (LLM) (input) or after itโ€™s returned from the LLM (output). Whether youโ€™re transforming inputs for better context or cleaning up outputs for improved readability, Filter Functions let you do it all.

This guide will break down what Filters are, how they work, their structure, and everything you need to know to build powerful and user-friendly filters of your own. Letโ€™s dig in, and donโ€™t worryโ€”Iโ€™ll use metaphors, examples, and tips to make everything crystal clear! ๐ŸŒŸ


๐ŸŒŠ What Are Filters in Open WebUI?โ€‹

Imagine Open WebUI as a stream of water flowing through pipes:

  • User inputs and LLM outputs are the water.
  • Filters are the water treatment stages that clean, modify, and adapt the water before it reaches the final destination.

Filters sit in the middle of the flowโ€”like checkpointsโ€”where you decide what needs to be adjusted.

Hereโ€™s a quick summary of what Filters do:

  1. Modify User Inputs (Inlet Function): Tweak the input data before it reaches the AI model. This is where you enhance clarity, add context, sanitize text, or reformat messages to match specific requirements.
  2. Intercept Model Outputs (Stream Function): Capture and adjust the AIโ€™s responses as theyโ€™re generated by the model. This is useful for real-time modifications, like filtering out sensitive information or formatting the output for better readability.
  3. Modify Model Outputs (Outlet Function): Adjust the AI's response after itโ€™s processed, before showing it to the user. This can help refine, log, or adapt the data for a cleaner user experience.

Key Concept: Filters are not standalone models but tools that enhance or transform the data traveling to and from models.

Filters are like translators or editors in the AI workflow: you can intercept and change the conversation without interrupting the flow.


๐Ÿ—บ๏ธ Structure of a Filter Function: The Skeletonโ€‹

Let's start with the simplest representation of a Filter Function. Don't worry if some parts feel technical at firstโ€”weโ€™ll break it all down step by step!

๐Ÿฆด Basic Skeleton of a Filterโ€‹

from pydantic import BaseModel
from typing import Optional

class Filter:
# Valves: Configuration options for the filter
class Valves(BaseModel):
pass

def __init__(self):
# Initialize valves (optional configuration for the Filter)
self.valves = self.Valves()

def inlet(self, body: dict) -> dict:
# This is where you manipulate user inputs.
print(f"inlet called: {body}")
return body

def stream(self, event: dict) -> dict:
# This is where you modify streamed chunks of model output.
print(f"stream event: {event}")
return event

def outlet(self, body: dict) -> None:
# This is where you manipulate model outputs.
print(f"outlet called: {body}")

๐Ÿ†• ๐Ÿงฒ Toggle Filter Example: Adding Interactivity and Icons (New in Open WebUI 0.6.10)โ€‹

Filters can do more than simply modify textโ€”they can expose UI toggles and display custom icons. For instance, you might want a filter that can be turned on/off with a user interface button, and displays a special icon in Open WebUIโ€™s message input UI.

Hereโ€™s how you could create such a toggle filter:

from pydantic import BaseModel, Field
from typing import Optional

class Filter:
class Valves(BaseModel):
pass

def __init__(self):
self.valves = self.Valves()
self.toggle = True # IMPORTANT: This creates a switch UI in Open WebUI
# TIP: Use SVG Data URI!
self.icon = """data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCAyNCAyNCIgc3Ryb2tlLXdpZHRoPSIxLjUiIHN0cm9rZT0iY3VycmVudENvbG9yIiBjbGFzcz0ic2l6ZS02Ij4KICA8cGF0aCBzdHJva2UtbGluZWNhcD0icm91bmQiIHN0cm9rZS1saW5lam9pbj0icm91bmQiIGQ9Ik0xMiAxOHYtNS4yNW0wIDBhNi4wMSA2LjAxIDAgMCAwIDEuNS0uMTg5bS0xLjUuMTg5YTYuMDEgNi4wMSAwIDAgMS0xLjUtLjE4OW0zLjc1IDcuNDc4YTEyLjA2IDEyLjA2IDAgMCAxLTQuNSAwbTMuNzUgMi4zODNhMTQuNDA2IDE0LjQwNiAwIDAgMS0zIDBNMTQuMjUgMTh2LS4xOTJjMC0uOTgzLjY1OC0xLjgyMyAxLjUwOC0yLjMxNmE3LjUgNy41IDAgMSAwLTcuNTE3IDBjLjg1LjQ5MyAxLjUwOSAxLjMzMyAxLjUwOSAyLjMxNlYxOCIgLz4KPC9zdmc+Cg=="""
pass

async def inlet(
self, body: dict, __event_emitter__, __user__: Optional[dict] = None
) -> dict:
await __event_emitter__(
{
"type": "status",
"data": {
"description": "Toggled!",
"done": True,
"hidden": False,
},
}
)
return body

๐Ÿ–ผ๏ธ Whatโ€™s happening?โ€‹

  • toggle = True creates a switch UI in Open WebUIโ€”users can manually enable or disable the filter in real time.
  • icon (with a Data URI) will show up as a little image next to the filterโ€™s name. You can use any SVG as long as itโ€™s Data URI encoded!
  • The inlet function uses the __event_emitter__ special argument to broadcast feedback/status to the UI, such as a little toast/notification that reads "Toggled!"

Toggle Filter

You can use these mechanisms to make your filters dynamic, interactive, and visually unique within Open WebUIโ€™s plugin ecosystem.


๐ŸŽฏ Key Components Explainedโ€‹

1๏ธโƒฃ Valves Class (Optional Settings)โ€‹

Think of Valves as the knobs and sliders for your filter. If you want to give users configurable options to adjust your Filterโ€™s behavior, you define those here.

class Valves(BaseModel):
OPTION_NAME: str = "Default Value"

For example:
If you're creating a filter that converts responses into uppercase, you might allow users to configure whether every output gets totally capitalized via a valve like TRANSFORM_UPPERCASE: bool = True/False.


2๏ธโƒฃ inlet Function (Input Pre-Processing)โ€‹

The inlet function is like prepping food before cooking. Imagine youโ€™re a chef: before the ingredients go into the recipe (the LLM in this case), you might wash vegetables, chop onions, or season the meat. Without this step, your final dish could lack flavor, have unwashed produce, or simply be inconsistent.

In the world of Open WebUI, the inlet function does this important prep work on the user input before itโ€™s sent to the model. It ensures the input is as clean, contextual, and helpful as possible for the AI to handle.

๐Ÿ“ฅ Input:

  • body: The raw input from Open WebUI to the model. It is in the format of a chat-completion request (usually a dictionary that includes fields like the conversation's messages, model settings, and other metadata). Think of this as your recipe ingredients.

๐Ÿš€ Your Task:
Modify and return the body. The modified version of the body is what the LLM works with, so this is your chance to bring clarity, structure, and context to the input.

๐Ÿณ Why Would You Use the inlet?โ€‹
  1. Adding Context: Automatically append crucial information to the userโ€™s input, especially if their text is vague or incomplete. For example, you might add "You are a friendly assistant" or "Help this user troubleshoot a software bug."

  2. Formatting Data: If the input requires a specific format, like JSON or Markdown, you can transform it before sending it to the model.

  3. Sanitizing Input: Remove unwanted characters, strip potentially harmful or confusing symbols (like excessive whitespace or emojis), or replace sensitive information.

  4. Streamlining User Input: If your modelโ€™s output improves with additional guidance, you can use the inlet to inject clarifying instructions automatically!

๐Ÿ’ก Example Use Cases: Build on Food Prepโ€‹
๐Ÿฅ— Example 1: Adding System Contextโ€‹

Letโ€™s say the LLM is a chef preparing a dish for Italian cuisine, but the user hasnโ€™t mentioned "This is for Italian cooking." You can ensure the message is clear by appending this context before sending the data to the model.

def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
# Add system message for Italian context in the conversation
context_message = {
"role": "system",
"content": "You are helping the user prepare an Italian meal."
}
# Insert the context at the beginning of the chat history
body.setdefault("messages", []).insert(0, context_message)
return body

๐Ÿ“– What Happens?

  • Any user input like "What are some good dinner ideas?" now carries the Italian theme because weโ€™ve set the system context! Cheesecake might not show up as an answer, but pasta sure will.
๐Ÿ”ช Example 2: Cleaning Input (Remove Odd Characters)โ€‹

Suppose the input from the user looks messy or includes unwanted symbols like !!!, making the conversation inefficient or harder for the model to parse. You can clean it up while preserving the core content.

def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
# Clean the last user input (from the end of the 'messages' list)
last_message = body["messages"][-1]["content"]
body["messages"][-1]["content"] = last_message.replace("!!!", "").strip()
return body

๐Ÿ“– What Happens?

  • Before: "How can I debug this issue!!!" โžก๏ธ Sent to the model as "How can I debug this issue"

Note: The user feels the same, but the model processes a cleaner and easier-to-understand query.

๐Ÿ“Š How inlet Helps Optimize Input for the LLM:โ€‹
  • Improves accuracy by clarifying ambiguous queries.
  • Makes the AI more efficient by removing unnecessary noise like emojis, HTML tags, or extra punctuation.
  • Ensures consistency by formatting user input to match the modelโ€™s expected patterns or schemas (like, say, JSON for a specific use case).

๐Ÿ’ญ Think of inlet as the sous-chef in your kitchenโ€”ensuring everything that goes into the model (your AI "recipe") has been prepped, cleaned, and seasoned to perfection. The better the input, the better the output!


๐Ÿ†• 3๏ธโƒฃ stream Hook (New in Open WebUI 0.5.17)โ€‹

๐Ÿ”„ What is the stream Hook?โ€‹

The stream function is a new feature introduced in Open WebUI 0.5.17 that allows you to intercept and modify streamed model responses in real time.

Unlike outlet, which processes an entire completed response, stream operates on individual chunks as they are received from the model.

๐Ÿ› ๏ธ When to Use the Stream Hook?โ€‹
  • Modify streaming responses before they are displayed to users.
  • Implement real-time censorship or cleanup.
  • Monitor streamed data for logging/debugging.
๐Ÿ“œ Example: Logging Streaming Chunksโ€‹

Hereโ€™s how you can inspect and modify streamed LLM responses:

def stream(self, event: dict) -> dict:
print(event) # Print each incoming chunk for inspection
return event

Example Streamed Events:

{"id": "chatcmpl-B4l99MMaP3QLGU5uV7BaBM0eDS0jb","choices": [{"delta": {"content": "Hi"}}]}
{"id": "chatcmpl-B4l99MMaP3QLGU5uV7BaBM0eDS0jb","choices": [{"delta": {"content": "!"}}]}
{"id": "chatcmpl-B4l99MMaP3QLGU5uV7BaBM0eDS0jb","choices": [{"delta": {"content": " ๐Ÿ˜Š"}}]}

๐Ÿ“– What Happens?

  • Each line represents a small fragment of the model's streamed response.
  • The delta.content field contains the progressively generated text.
๐Ÿ”„ Example: Filtering Out Emojis from Streamed Dataโ€‹
def stream(self, event: dict) -> dict:
for choice in event.get("choices", []):
delta = choice.get("delta", {})
if "content" in delta:
delta["content"] = delta["content"].replace("๐Ÿ˜Š", "") # Strip emojis
return event

๐Ÿ“– Before: "Hi ๐Ÿ˜Š"
๐Ÿ“– After: "Hi"


4๏ธโƒฃ outlet Function (Output Post-Processing)โ€‹

The outlet function is like a proofreader: tidy up the AI's response (or make final changes) after itโ€™s processed by the LLM.

๐Ÿ“ค Input:

  • body: This contains all current messages in the chat (user history + LLM replies).

๐Ÿš€ Your Task: Modify this body. You can clean, append, or log changes, but be mindful of how each adjustment impacts the user experience.

๐Ÿ’ก Best Practices:

  • Prefer logging over direct edits in the outlet (e.g., for debugging or analytics).
  • If heavy modifications are needed (like formatting outputs), consider using the pipe function instead.

๐Ÿ’ก Example Use Case: Strip out sensitive API responses you don't want the user to see:

def outlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
for message in body["messages"]:
message["content"] = message["content"].replace("<API_KEY>", "[REDACTED]")
return body

๐ŸŒŸ Filters in Action: Building Practical Examplesโ€‹

Letโ€™s build some real-world examples to see how youโ€™d use Filters!

๐Ÿ“š Example #1: Add Context to Every User Inputโ€‹

Want the LLM to always know it's assisting a customer in troubleshooting software bugs? You can add instructions like "You're a software troubleshooting assistant" to every user query.

class Filter:
def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
context_message = {
"role": "system",
"content": "You're a software troubleshooting assistant."
}
body.setdefault("messages", []).insert(0, context_message)
return body

๐Ÿ“š Example #2: Highlight Outputs for Easy Readingโ€‹

Returning output in Markdown or another formatted style? Use the outlet function!

class Filter:
def outlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
# Add "highlight" markdown for every response
for message in body["messages"]:
if message["role"] == "assistant": # Target model response
message["content"] = f"**{message['content']}**" # Highlight with Markdown
return body

๐Ÿšง Potential Confusion: Clear FAQ ๐Ÿ›‘โ€‹

Q: How Are Filters Different From Pipe Functions?โ€‹

Filters modify data going to and coming from models but do not significantly interact with logic outside of these phases. Pipes, on the other hand:

  • Can integrate external APIs or significantly transform how the backend handles operations.
  • Expose custom logic as entirely new "models."

Q: Can I Do Heavy Post-Processing Inside outlet?โ€‹

You can, but itโ€™s not the best practice.:

  • Filters are designed to make lightweight changes or apply logging.
  • If heavy modifications are required, consider a Pipe Function instead.

๐ŸŽ‰ Recap: Why Build Filter Functions?โ€‹

By now, youโ€™ve learned:

  1. Inlet manipulates user inputs (pre-processing).
  2. Stream intercepts and modifies streamed model outputs (real-time).
  3. Outlet tweaks AI outputs (post-processing).
  4. Filters are best for lightweight, real-time alterations to the data flow.
  5. With Valves, you empower users to configure Filters dynamically for tailored behavior.

๐Ÿš€ Your Turn: Start experimenting! What small tweak or context addition could elevate your Open WebUI experience? Filters are fun to build, flexible to use, and can take your models to the next level!

Happy coding! โœจ