⚡ Technical Documentation

Openwebui Filters: The Ultimate Guide

Technical guide covering openwebui filters: the ultimate guide

👤
Author
Cosmic Lounge AI Team
📅
Updated
6/1/2025
⏱️
Read Time
14 min
Topics
#llm #ai #model #fine-tuning #api #configuration #openwebui #guide #design

📖 Reading Mode

📖 Table of Contents

🌌 OpenWebUI Filters: The Ultimate Guide

Filters in OpenWebUI are incredibly powerful tools that allow you to manipulate and modify the flow of data between the user interface and the language model (LLM). They act as “hooks” within the OpenWebUI workflow, providing the ability to pre-process user inputs and post-process model outputs.

🌟 Structure of a Filter

A filter in OpenWebUI is essentially a Python class with a specific structure. This structure consists of three main components:

  • Valves: This optional component allows for the configuration of filter behavior. It defines settings that can be adjusted by either the administrator or the end-user to customize the filter’s actions. Think of it like the control panel for your filter, where you can tweak settings to fine-tune its operation. Both the inlet and outlet functions take a dictionary (dict) as input and return a dictionary (dict) as output1.

  • inlet Function: This function pre-processes the user’s input before it’s sent to the LLM. It’s like a gatekeeper that intercepts the user’s message and can perform actions such as cleaning up the input, adding context, or formatting it to meet specific requirements1.

  • outlet Function: This function post-processes the LLM’s output before it’s displayed to the user. It acts like an editor, refining the model’s response by adjusting the tone, cleaning up the output, or formatting it into a desired style1. To better visualize this structure, consider the following diagram:

+---------------------+ | Valves | (Optional Configuration) +---------------------+ | V +---------------------+ | inlet() | (Pre-processes User Input) +---------------------+ | V +---------------------+ | outlet() | (Post-processes Model Output) +---------------------+

🌟 Valves: Fine-tuning Your Filter

The Valves class within a filter allows you to define configurable options that influence how the filter operates. These options can be modified by administrators and end-users to tailor the filter’s behavior to specific needs2. For instance, if you’re building a filter to convert the model’s output to uppercase, you could include a valve like TRANSFORM_UPPERCASE: bool = True/False. This would give users the ability to toggle whether the output is fully capitalized or not1. Here’s an example of how to define a Valves class:

Python

from pydantic import BaseModel

class Filter: class Valves(BaseModel): TRANSFORM_UPPERCASE: bool = True

🌌 Add more valves as needed

🌟 inlet Function: Pre-processing User Input

The inlet function is responsible for preparing the user’s input before it reaches the LLM. It takes the raw input from OpenWebUI, which is typically in the form of a chat-completion request, and can modify it in various ways. Here’s a table summarizing common use cases for the inlet function:

Use CaseDescriptionExample
Adding ContextAutomatically append relevant information to the user’s input, especially if it’s vague or incomplete.Add “You are a friendly assistant” to every user query.
Formatting DataTransform the input into a specific format, such as JSON or Markdown.Convert user input to JSON before sending it to the LLM.
Sanitizing InputRemove unwanted characters, strip potentially harmful symbols, or replace sensitive information.Remove excessive whitespace or emojis from the user’s input.
Streamlining User InputInject clarifying instructions to improve the model’s understanding.Add instructions like “Provide a concise summary” to user queries.

Here’s an example of an inlet function that adds a system message to every user query:

Python

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

🌟 outlet Function: Post-processing Model Output

The outlet function takes the LLM’s response and modifies it before it’s presented to the user. It can perform a variety of actions, such as:

  • Cleaning Up Output: You can remove unnecessary characters, format the output, or adjust the tone of the response1.

  • Logging: You can use the outlet function to log the model’s responses for debugging or analytics purposes1.

  • Converting to Different Formats: You can convert the output to Markdown, JSON, or other formats as needed1. Here’s an example of an outlet function that highlights the model’s response using Markdown:

Python

class Filter: def outlet(self, body: dict, __user__: Optional = None) -> dict: for message in body[“messages”]: if message[“role”] == “assistant”: message[“content”] = f”**{message[‘content’]}**” return body

🌟 Returning a JSON Outlet

To return a JSON output from your filter, you can simply modify the outlet function to return a JSON-formatted string. Here’s an example from the libretranslate_filter_pipeline.py script: 3

Python

import json

class Filter: def outlet(self, body: dict, __user__: Optional = None) -> dict:

🌌 … your processing logic …

output = { “response”: “This is the model’s response.”,

🌌 … other data …

} return json.dumps(output)

This script also includes a translate() function that utilizes the libretranslate_url valve to send a translation request with the specified source and target languages. The function constructs a JSON payload containing the text to be translated and sends a POST request to the LibreTranslate API. The translated text is then extracted from the API response and returned3.

🌟 Formatting and Conversion

OpenWebUI provides built-in support for Markdown and LaTeX, allowing you to format the model’s output in various ways. You can use Markdown to add headings, lists, links, and other formatting elements to enhance readability4. You can also utilize LaTeX for mathematical expressions and scientific notation4. To convert the output to other formats, you can use libraries like markdownify to convert Markdown to HTML or pandoc to convert between various formats.

🌟 Event Emitters in Filters

Event emitters can be used within filters to provide real-time feedback or display status messages to the user. For example, you can use an event emitter to show the number of tokens used in the user’s input and the model’s output5. Here’s an example of a filter that uses an event emitter to display token counts:

Python

from open_webui.utils.event_emitter import EventEmitter

class Filter: def __init__(self): self.token_message = "" self.event_emitter = EventEmitter()

async def inlet(self, body: dict, __user__: Optional = None) -> dict:

🌌 … token counting logic for user input …

await self.event_emitter.emit( “status”, {“message”: f”Input tokens: {self.token_message}”} ) return body

async def outlet(self, body: dict, __user__: Optional = None) -> dict:

🌌 … token counting logic for model output …

await self.event_emitter.emit( “status”, {“message”: f”{self.token_message}, Output tokens: {token_count}”} ) return body

🌟 Filters and Pipelines

Filters can be integrated into Pipelines, which are a more advanced feature in OpenWebUI. Pipelines allow for complex workflows and integrations with external services. When a filter is part of a pipeline, it acts as a processing step within the pipeline’s overall workflow6. The general workflow of a filter within a pipeline is as follows:

1. The user’s input is passed to the inlet function of the filter. 2. The filter performs its pre-processing actions on the input. 3. The processed input is then sent to the LLM for generating a response. 4. The LLM’s output is passed to the outlet function of the filter. 5. The filter performs its post-processing actions on the output. 6. The final processed output is displayed to the user.

🌟 Filters vs. Pipes

While both filters and pipes extend the functionality of OpenWebUI, they serve different purposes. Filters are designed for lightweight modifications of inputs and outputs, acting as “hooks” within the existing workflow. They are ideal for tasks like adding context, cleaning up text, or formatting data1. Pipes, on the other hand, are more powerful and allow for complex logic and integrations with external APIs or services. They can be used to create entirely new models or agents within OpenWebUI1.

🌟 Updated Inlet and Outlet Functions

While this research did not find specific information about updated inlet and outlet functions with parameters like user, event, and model, it’s important to stay updated with the latest official documentation for any changes to function signatures and available parameters. OpenWebUI is constantly evolving, and new features and improvements are frequently introduced1.

🌟 Conclusion

Filters in OpenWebUI are versatile tools that empower you to customize and enhance your interactions with LLMs. By understanding their structure and key components, such as Valves, inlet, and outlet functions, you can leverage filters to pre-process user inputs, post-process model outputs, and format the data in various ways. This guide has provided a comprehensive overview of filters, equipping you with the knowledge to create your own filters and unlock the full potential of OpenWebUI. Key takeaways from this guide include:

  • Filters consist of three main components: Valves, inlet function, and outlet function.

  • Valves allow for customization of filter behavior by both administrators and end-users.

  • The inlet function pre-processes user input, while the outlet function post-processes model output.

  • Filters can be used for a variety of tasks, such as adding context, formatting data, and cleaning up output.

  • Filters can be integrated into Pipelines for more complex workflows.

  • It’s crucial to stay updated with the latest official documentation for any changes or new features. By mastering filters, you can fine-tune your OpenWebUI experience and tailor it to your specific needs and preferences.

🔧 Works cited

1. Filter Function: Modify Inputs and Outputs - Open WebUI, accessed on February 12, 2025, https://docs.openwebui.com/features/plugin/functions/filter/

2. Open WebUI, Tools, Functions, Filters, Pipelines, and Valves, with a lot of demos - YouTube, accessed on February 12, 2025, https://www.youtube.com/watch?v=Jxt-coDVbR4

3. Functions | Open WebUI, accessed on February 12, 2025, https://docs.openwebui.com/features/plugin/functions/

4. Features | Open WebUI, accessed on February 12, 2025, https://docs.openwebui.com/features/

5. Open WebUI Filters with Event Emitter-Count Input and Output Tokens - YouTube, accessed on February 12, 2025, https://www.youtube.com/watch?v=cRLsrdxNE-c

6. Filters - Open WebUI, accessed on February 12, 2025, https://docs.openwebui.com/pipelines/filters/

Back to Knowledge Base Explore More Knowledge