khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-01-02 17:59:41 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'open-webui:main' into getting-started-fixes

Browse Source
This commit is contained in:
mhand
2024-11-07 06:40:54 +11:00
committed by GitHub
parent b00b27b031 1d5b291422
commit 6aafbf5ba5
35 changed files with 117 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/tutorials/deployment/index.mdx
View File

@@ -6,6 +6,11 @@ import { TopBanners } from "@site/src/components/TopBanners";
<TopBanners />
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
:::info
# 📢 **Calling all YouTubers!**
We're looking for talented individuals to create videos showcasing Open WebUI's features. If you make a video, we'll feature it at the top of our guide section!

126
docs/tutorials/evaluation/index.mdx
View File

@@ -1,126 +0,0 @@
---
sidebar_position: 2
title: "📝 Evaluation"
---
import { TopBanners } from "@site/src/components/TopBanners";
<TopBanners />
## Why Should I Evaluate Models?
Meet **Alex**, a machine learning engineer at a mid-sized company. Alex knows there are numerous AI models out there—GPTs, LLaMA, and many more—but which one works best for the job at hand? They all sound impressive on paper, but Alex can’t just rely on public leaderboards. These models perform differently depending on the context, and some models may have been trained on the evaluation dataset (sneaky!). Plus, the way these models write can sometimes feel … off.
That's where Open WebUI comes in. It gives Alex and their team an easy way to evaluate models based on their actual needs. No convoluted math. No heavy lifting. Just thumbs up or thumbs down while interacting with the models.
### TL;DR
- **Why evaluations matter**: Too many models, but not all fit your specific needs. General public leaderboards can't always be trusted.
- **How to solve it**: Open WebUI offers a built-in evaluation system. Use a thumbs up/down to rate model responses.
- **What happens behind the scenes**: Ratings adjust your personalized leaderboard, and snapshots from rated chats will be used for future model fine-tuning!
- **Evaluation options**:
- **Arena Model**: Randomly selects models for you to compare.
- **Normal Interaction**: Just chat like usual and rate the responses.
---
### Why Is Public Evaluation Not Enough?
- Public leaderboards aren’t tailored to **your** specific use case.
- Some models are trained on evaluation datasets, affecting the fairness of the results.
- A model may perform well overall, but its communication style or responses just don’t fit the “vibe” you want.
### The Solution: Personalized Evaluation with Open WebUI
Open WebUI has a built-in evaluation feature that lets you and your team discover the model best suited for your particular needs—all while interacting with the models.
How does it work? Simple!
- **During chats**, leave a thumbs up if you like a response, or a thumbs down if you don’t. If the message has a **sibling message** (like a regenerated response or part of a side-by-side model comparison), you’re contributing to your **personal leaderboard**.
- **Leaderboards** are easily accessible in the Admin section, helping you track which models are performing best according to your team.
One cool feature? **Whenever you rate a response**, the system captures a **snapshot of that conversation**, which will later be used to refine models or even power future model training. (Do note, this is still being developed!)
---
### Two Ways to Evaluate an AI Model
Open WebUI provides two straightforward approaches for evaluating AI models.
### **1. Arena Model**
The **Arena Model** randomly selects from a pool of available models, making sure the evaluation is fair and unbiased. This helps in removing a potential flaw in manual comparison: **ecological validity** – ensuring you don’t knowingly or unknowingly favor one model.
How to use it:
- Select a model from the Arena Model selector.
- Use it like you normally would, but now you’re in “arena mode.”
For your feedback to affect the leaderboard, you need what’s called a **sibling message**. What's a sibling message? A sibling message is just any alternative response generated by the same query (think of message regenerations or having multiple models generating responses side-by-side). This way, you’re comparing responses **head-to-head**.
- **Scoring tip**: When you thumbs up one response, the other will automatically get a thumbs down. So, be mindful and only upvote the message you believe is genuinely the best!
- Once you rate the responses, you can check out the leaderboard to see how models are stacking up.
Here’s a sneak peek at how the Arena Model interface works:
![Arena Model Example](/img/evaluation/arena.png)
Need more depth? You can even replicate a [**Chatbot Arena**](https://lmarena.ai/)-style setup!
![Chatbot Arena Example](/img/evaluation/arena-many.png)
### **2. Normal Interaction**
No need to switch to “arena mode” if you don't want to. You can use Open WebUI normally and rate the AI model responses as you would in everyday operations. Just thumbs up/down the model responses, whenever you feel like it. However, **if you want your feedback to be used for ranking on the leaderboard**, you'll need to **swap out the model and interact with a different one**. This ensures there's a **sibling response** to compare it with – only comparisons between two different models will influence rankings.
For instance, this is how you can rate during a normal interaction:
![Normal Model Rating Interface](/img/evaluation/normal.png)
And here's an example of setting up a multi-model comparison, similar to an arena:
![Multi-Model Comparison](/img/evaluation/normal-many.png)
---
## Leaderboard
After rating, check out the **Leaderboard** under the Admin Panel. This is where you’ll visually see how models are performing, ranked using an **Elo rating system** (think chess rankings!) You’ll get a real view of which models are truly standing out during the evaluations.
This is a sample leaderboard layout:
![Leaderboard Example](/img/evaluation/leaderboard.png)
### Topic-Based Reranking
When you rate chats, you can **tag them by topic** for more granular insights. This is especially useful if you’re working in different domains like **customer service, creative writing, technical support**, etc.
#### Automatic Tagging
Open WebUI tries to **automatically tag chats** based on the conversation topic. However, depending on the model you're using, the automatic tagging feature might **sometimes fail** or misinterpret the conversation. When this happens, it’s best practice to **manually tag your chats** to ensure the feedback is accurate.
- **How to manually tag**: When you rate a response, you'll have the option to add your own tags based on the conversation's context.
Don't skip this! Tagging is super powerful because it allows you to **re-rank models based on specific topics**. For instance, you might want to see which model performs best for answering technical support questions versus general customer inquiries.
Here’s an example of how re-ranking looks:
![Reranking Leaderboard by Topic](/img/evaluation/leaderboard-reranked.png)
---
### Side Note: Chat Snapshots for Model Fine-Tuning
Whenever you rate a model’s response, Open WebUI *captures a snapshot of that chat*. These snapshots can eventually be used to **fine-tune your own models**—so your evaluations feed into the continuous improvement of the AI.
*(Stay tuned for more updates on this feature, it's actively being developed!)*
---
## Summary
**In a nutshell**, Open WebUI’s evaluation system has two clear goals:
1. Help you **easily compare models**.
2. Ultimately, find the model that meshes best with your individual needs.
At its heart, the system is all about making AI model evaluation **simple, transparent, and customizable** for every user. Whether it's through the Arena Model or Normal Chat Interaction, **you’re in full control of determining which AI model works best for your specific use case**!
**As always**, all of your data stays securely on **your instance**, and nothing is shared unless you specifically **opt-in for community sharing**. Your privacy and data autonomy are always prioritized.

67
docs/tutorials/features/chat-params.md
View File

@@ -1,67 +0,0 @@
---
sidebar_position: 1
title: "Chat Parameters"
---
Within Open WebUI, there are three levels to setting a **System Prompt** and **Advanced Parameters**: per-chat basis, per-model basis, and per-account basis. This hierarchical system allows for flexibility while maintaining structured administration and control.
## System Prompt and Advanced Parameters Hierarchy Chart
| **Level** | **Definition** | **Modification Permissions** | **Override Capabilities** |
| --- | --- | --- | --- |
| **Per-Chat** | System prompt and advanced parameters for a specific chat instance | Users can modify, but cannot override model-specific settings | Restricted from overriding model-specific settings |
| **Per-Model** | Default system prompt and advanced parameters for a specific model | Administrators can set, Users cannot modify | Admin-specific settings take precedence, User settings can be overridden |
| **Per-Account** | Default system prompt and advanced parameters for a specific user account | Users can set, but may be overridden by model-specific settings | User settings can be overridden by model-specific settings |
### 1. **Per-chat basis:**
- **Description**: The per-chat basis setting refers to the system prompt and advanced parameters configured for a specific chat instance. These settings are only applicable to the current conversation and do not affect future chats.
- **How to set**: Users can modify the system prompt and advanced parameters for a specific chat instance within the right-hand sidebar's **Chat Controls** section in Open WebUI.
- **Override capabilities**: Users are restricted from overriding the **System Prompt** or specific **Advanced Parameters** already set by an administrator on a per-model basis (**#2**). This ensures consistency and adherence to model-specific settings.
<details>
<summary>Example Use Case</summary>
:::tip **Per-chat basis**:
Suppose a user wants to set a custom system prompt for a specific conversation. They can do so by accessing the **Chat Controls** section and modifying the **System Prompt** field. These changes will only apply to the current chat session.
:::
</details>
### 2. **Per-model basis:**
- **Description**: The per-model basis setting refers to the default system prompt and advanced parameters configured for a specific model. These settings are applicable to all chat instances using that model.
- **How to set**: Administrators can set the default system prompt and advanced parameters for a specific model within the **Models** section of the **Workspace** in Open WebUI.
- **Override capabilities**: **User** accounts are restricted from modifying the **System Prompt** or specific **Advanced Parameters** on a per-model basis (**#3**). This restriction prevents users from inappropriately altering default settings.
- **Context length preservation:** When a model's **System Prompt** or specific **Advanced Parameters** are set manually in the **Workspace** section by an Admin, said **System Prompt** or manually set **Advanced Parameters** cannot be overridden or adjusted on a per-account basis within the **General** settings or **Chat Controls** section by a **User** account. This ensures consistency and prevents excessive reloading of the model whenever a user's context length setting changes.
- **Model precedence:** If a model's **System Prompt** or specific **Advanced Parameters** value is pre-set in the Workspace section by an Admin, any context length changes made by a **User** account in the **General** settings or **Chat Controls** section will be disregarded, maintaining the pre-configured value for that model. Be advised that parameters left untouched by an **Admin** account can still be manually adjusted by a **User** account on a per-account or per-chat basis.
<details>
<summary>Example Use Case</summary>
:::tip **Per-model basis**:
Suppose an administrator wants to set a default system prompt for a specific model. They can do so by accessing the **Models** section and modifying the **System Prompt** field for the corresponding model. Any chat instances using this model will automatically use the model's system prompt and advanced parameters.
:::
</details>
### 3. **Per-account basis:**
- **Description**: The per-account basis setting refers to the default system prompt and advanced parameters configured for a specific user account. Any user-specific changes can serve as a fallback in situations where lower-level settings aren't defined.
- **How to set**: Users can set their own system prompt and advanced parameters for their account within the **General** section of the **Settings** menu in Open WebUI.
- **Override capabilities**: Users have the ability to set their own system prompt on their account, but they must be aware that such parameters can still be overridden if an administrator has already set the **System Prompt** or specific **Advanced Parameters** on a per-model basis for the particular model being used.
<details>
<summary>Example Use Case</summary>
:::tip **Per-account basis**:
Suppose a user wants to set their own system prompt for their account. They can do so by accessing the **Settings** menu and modifying the **System Prompt** field.
:::
</details>
## **Optimize System Prompt Settings for Maximum Flexibility**
:::tip **Bonus Tips**
**This tip applies for both administrators and user accounts. To achieve maximum flexibility with your system prompts, we recommend considering the following setup:**
* Assign your primary System Prompt (**i.e., to give an LLM a defining character**) you want to use in your **General** settings **System Prompt** field. This sets it on a per-account level and allows it to work as the system prompt across all your LLMs without requiring adjustments within a model from the **Workspace** section.
* For your secondary System Prompt (**i.e, to give an LLM a task to perform**), choose whether to place it in the **System Prompt** field within the **Chat Controls** sidebar (on a per-chat basis) or the **Models** section of the **Workspace** section (on a per-model basis) for Admins, allowing you to set them directly. This allows your account-level system prompt to work in conjunction with either the per-chat level system prompt provided by **Chat Controls**, or the per-model level system prompt provided by **Models**.
* As an administrator, you should assign your LLM parameters on a per-model basis using **Models** section for optimal flexibility. For both of these secondary System Prompts, ensure to set them in a manner that maximizes flexibility and minimizes required adjustments across different per-account or per-chat instances. It is essential for both your Admin account as well as all User accounts to understand the priority order by which system prompts within **Chat Controls** and the **Models** section will be applied to the **LLM**.
:::

150
docs/tutorials/features/images.md
View File

@@ -1,150 +0,0 @@
---
sidebar_position: 6
title: "Image Generation"
---
# Image Generation
Open WebUI supports image generation through three backends: **AUTOMATIC1111**, **ComfyUI**, and **OpenAI DALL·E**. This guide will help you set up and use either of these options.
## AUTOMATIC1111
Open WebUI supports image generation through the **AUTOMATIC1111** [API](https://github.com/AUTOMATIC1111/stable-diffusion-webui/wiki/API). Here are the steps to get started:
### Initial Setup
1. Ensure that you have [AUTOMATIC1111](https://github.com/AUTOMATIC1111/stable-diffusion-webui) installed.
2. Launch AUTOMATIC1111 with additional flags to enable API access:
```
./webui.sh --api --listen
```
3. For Docker installation of WebUI with the environment variables preset, use the following command:
```
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -e AUTOMATIC1111_BASE_URL=http://host.docker.internal:7860/ -e ENABLE_IMAGE_GENERATION=True -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```
### Setting Up Open WebUI with AUTOMATIC1111
1. In Open WebUI, navigate to the **Admin Panel** > **Settings** > **Images** menu.
2. Set the `Image Generation Engine` field to `Default (Automatic1111)`.
3. In the API URL field, enter the address where AUTOMATIC1111's API is accessible:
```
http://<your_automatic1111_address>:7860/
```
If you're running a Docker installation of Open WebUI and AUTOMATIC1111 on the same host, use `http://host.docker.internal:7860/` as your address.
## ComfyUI
ComfyUI provides an alternative interface for managing and interacting with image generation models. Learn more or download it from its [GitHub page](https://github.com/comfyanonymous/ComfyUI). Below are the setup instructions to get ComfyUI running alongside your other tools.
### Initial Setup
1. Download and extract the ComfyUI software package from [GitHub](https://github.com/comfyanonymous/ComfyUI) to your desired directory.
2. To start ComfyUI, run the following command:
```
python main.py
```
For systems with low VRAM, launch ComfyUI with additional flags to reduce memory usage:
```
python main.py --lowvram
```
3. For Docker installation of WebUI with the environment variables preset, use the following command:
```
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -e COMFYUI_BASE_URL=http://host.docker.internal:7860/ -e ENABLE_IMAGE_GENERATION=True -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```
### Setting Up Open WebUI with ComfyUI
#### Setting Up FLUX.1 Models:
1. **Model Checkpoints**:
* Download either the `FLUX.1-schnell` or `FLUX.1-dev` model from the [black-forest-labs HuggingFace page](https://huggingface.co/black-forest-labs).
* Place the model checkpoint(s) in both the `models/checkpoints` and `models/unet` directories of ComfyUI. Alternatively, you can create a symbolic link between `models/checkpoints` and `models/unet` to ensure both directories contain the same model checkpoints.
2. **VAE Model**:
* Download `ae.safetensors` VAE from [here](https://huggingface.co/black-forest-labs/FLUX.1-schnell/blob/main/ae.safetensors).
* Place it in the `models/vae` ComfyUI directory.
3. **CLIP Model**:
* Download `clip_l.safetensors` from [here](https://huggingface.co/comfyanonymous/flux_text_encoders/tree/main).
* Place it in the `models/clip` ComfyUI directory.
4. **T5XXL Model**:
* Download either the `t5xxl_fp16.safetensors` or `t5xxl_fp8_e4m3fn.safetensors` model from [here](https://huggingface.co/comfyanonymous/flux_text_encoders/tree/main).
* Place it in the `models/clip` ComfyUI directory.
To integrate ComfyUI into Open WebUI, follow these steps:
#### Step 1: Configure Open WebUI Settings
1. Navigate to the **Admin Panel** in Open WebUI.
2. Click on **Settings** and then select the **Images** tab.
3. In the `Image Generation Engine` field, choose `ComfyUI`.
4. In the **API URL** field, enter the address where ComfyUI's API is accessible, following this format: `http://<your_comfyui_address>:8188/`.
- Set the environment variable `COMFYUI_BASE_URL` to this address to ensure it persists within the WebUI.
#### Step 2: Verify the Connection and Enable Image Generation
1. Ensure ComfyUI is running and that you've successfully verified the connection to Open WebUI. You won't be able to proceed without a successful connection.
2. Once the connection is verified, toggle on **Image Generation (Experimental)**. More options will be presented to you.
3. Continue to step 3 for the final configuration steps.
#### Step 3: Configure ComfyUI Settings and Import Workflow
1. Enable developer mode within ComfyUI. To do this, look for the gear icon above the **Queue Prompt** button within ComfyUI and enable the `Dev Mode` toggle.
2. Export the desired workflow from ComfyUI in `API format` using the `Save (API Format)` button. The file will be downloaded as `workflow_api.json` if done correctly.
3. Return to Open WebUI and click the **Click here to upload a workflow.json file** button.
4. Select the `workflow_api.json` file to import the exported workflow from ComfyUI into Open WebUI.
5. After importing the workflow, you must map the `ComfyUI Workflow Nodes` according to the imported workflow node IDs.
:::info
You may need to adjust an `Input Key` or two within Open WebUI's `ComfyUI Workflow Nodes` section to match a node within your workflow.
For example, `seed` may need to be renamed to `noise_seed` to match a node ID within your imported workflow.
:::
:::tip
Some workflows, such as ones that use any of the Flux models, may utilize multiple nodes IDs that is necessary to fill in for their node entry fields within Open WebUI. If a node entry field requires multiple IDs, the node IDs should be comma separated (e.g. `1` or `1, 2`).
:::
6. Click `Save` to apply the settings and enjoy image generation with ComfyUI integrated into Open WebUI!
After completing these steps, your ComfyUI setup should be integrated with Open WebUI, and you can use the Flux.1 models for image generation.
### Configuring with SwarmUI
SwarmUI utilizes ComfyUI as its backend. In order to get Open WebUI to work with SwarmUI you will have to append `ComfyBackendDirect` to the `ComfyUI Base URL`. Additionally, you will want to setup SwarmUI with LAN access. After aforementioned adjustments, setting up SwarmUI to work with Open WebUI will be the same as [Step one: Configure Open WebUI Settings](https://github.com/open-webui/docs/edit/main/docs/tutorials/features/images.md#step-1-configure-open-webui-settings) as outlined above.
![Install SwarmUI with LAN Access](https://github.com/user-attachments/assets/a6567e13-1ced-4743-8d8e-be526207f9f6)
#### SwarmUI API URL
The address you will input as the ComfyUI Base URL will look like: `http://<your_swarmui_address>:7801/ComfyBackendDirect`
## OpenAI DALL·E
Open WebUI also supports image generation through the **OpenAI DALL·E APIs**. This option includes a selector for choosing between DALL·E 2 and DALL·E 3, each supporting different image sizes.
### Initial Setup
1. Obtain an [API key](https://platform.openai.com/api-keys) from OpenAI.
### Configuring Open WebUI
1. In Open WebUI, navigate to the **Admin Panel** > **Settings** > **Images** menu.
2. Set the `Image Generation Engine` field to `Open AI (Dall-E)`.
3. Enter your OpenAI API key.
4. Choose the DALL·E model you wish to use. Note that image size options will depend on the selected model:
- **DALL·E 2**: Supports `256x256`, `512x512`, or `1024x1024` images.
- **DALL·E 3**: Supports `1024x1024`, `1792x1024`, or `1024x1792` images.
### Azure OpenAI
Using Azure OpenAI Dall-E directly is unsupported, but you can [set up a LiteLLM proxy](https://litellm.vercel.app/docs/image_generation) which is compatible with the `Open AI (Dall-E)` Image Generation Engine.
## Using Image Generation
![Image Generation Tutorial](/img/tutorial_image_generation.png)
1. First, use a text generation model to write a prompt for image generation.
2. After the response has finished, you can click the Picture icon to generate an image.
3. After the image has finished generating, it will be returned automatically in chat.
:::tip
You can also edit the LLM's response and enter your image generation prompt as the message
to send off for image generation instead of using the actual response provided by the
LLM.
:::

4
docs/tutorials/features/index.mdx
View File

@@ -1,4 +0,0 @@
---
sidebar_position: 1
title: "✨ Features"
---

52
docs/tutorials/features/ollama.md
View File

@@ -1,52 +0,0 @@
---
sidebar_position: 3
title: "Ollama Load Balancing"
---
# Ollama Load Balancing Setup
This guide demonstrates how to configure Open WebUI to connect to multiple Ollama instances for load balancing within your deployment. This approach enables you to distribute processing loads across several nodes, enhancing both performance and reliability. The configuration leverages environment variables to manage connections between container updates, rebuilds, or redeployments seamlessly.
## Docker Run
To connect to multiple Ollama instances with Docker, use the following example command:
```bash
docker run -d -p 3000:8080 \
-v open-webui:/app/backend/data \
-e OLLAMA_BASE_URLS="http://ollama-one:11434;http://ollama-two:11434" \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
```
This command configures your Docker container with these key environment variables:
- `OLLAMA_BASE_URLS`: Specifies the base URLs for each Ollama instance, separated by semicolons (`;`). This example uses two instances, but you can adjust this to fit your setup.
Ensure both Ollama instances are of the same version and have matching tags for each model they share. Discrepancies in model versions or tags across instances can lead to errors due to how WebUI de-duplicates and merges model lists.
## Docker Compose
For those preferring `docker-compose`, here's an abridged version of a `docker-compose.yaml` file:
```yaml
services:
open-webui:
environment:
- OLLAMA_BASE_URLS=http://ollama-one:11434;http://ollama-two:11434
```
To further streamline this setup, you can define `OLLAMA_BASE_URLS` in an `.env` file located in the same directory as your `docker-compose.yaml`. Your `.env` file might look like this:
```ini
OLLAMA_BASE_URLS="http://ollama-one:11434;http://ollama-two:11434"
```
## Ensuring Model Consistency
Both Ollama instances must run identical versions and tags for each shared model to prevent issues. The system allows for models to be present on one server and not the other, smartly routing requests to the server containing the requested model. However, having different versions or hashes for the same model tag across instances can cause inconsistencies.
Utilize the `Update All Models` button beside the server selector drop-down within the **Settings > Models** screen to keep models synchronized across instances.
By following these steps, you can effectively distribute the computational load across multiple Ollama instances, ensuring a robust and efficient deployment with Open WebUI.

41
docs/tutorials/features/openai.md
View File

@@ -1,41 +0,0 @@
---
sidebar_position: 2
title: "OpenAI Connections"
---
In this tutorial, we will demonstrate how to configure multiple OpenAI (or compatible) API endpoints using environment variables. This setup allows you to easily switch between different API providers or use multiple providers simultaneously, while keeping your configuration between container updates, rebuilds or redeployments.
## Docker Run
Here's an example `docker run` command similar to what you might use for Open WebUI:
```bash
docker run -d -p 3000:8080 \
-v open-webui:/app/backend/data \
-e OPENAI_API_BASE_URLS="https://api.openai.com/v1;https://api.mistral.ai/v1" \
-e OPENAI_API_KEYS="<OPENAI_API_KEY_1>;<OPENAI_API_KEY_2>" \
--name open-webui \
--restart always \
ghcr.io/open-webui/open-webui:main
```
This command sets the following environment variables:
* `OPENAI_API_BASE_URLS`: A list of API base URLs separated by semicolons (;). In this example, we use OpenAI and Mistral.
* `OPENAI_API_KEYS`: A list of API keys corresponding to the base URLs specified in `OPENAI_API_BASE_URLS`. Make sure to replace `<OPENAI_API_KEY_1>` and `<OPENAI_API_KEY_2>` with your actual API keys.
You can adapt this command to your own needs, and add even more endpoint/key pairs, but make sure to include the environment variables as shown above.
## Docker Compose
Alternatively, you can use a `docker-compose.yaml` file to define and run the Open WebUI container. Here's an abridged version of what that might look like:
```yaml
services:
open-webui:
environment:
- 'OPENAI_API_BASE_URLS=${OPENAI_API_BASE_URLS}'
- 'OPENAI_API_KEYS=${OPENAI_API_KEYS}'
```
You can edit the `${VARIABLES}` directly, or optionally define the values of these variables in an `.env` file, which should be placed in the same directory as the `docker-compose.yaml` file:
```ini
OPENAI_API_BASE_URLS="https://api.openai.com/v1;https://api.mistral.ai/v1"
OPENAI_API_KEYS="<OPENAI_API_KEY_1>;<OPENAI_API_KEY_2>"
```

46
docs/tutorials/features/rag.md
View File

@@ -1,46 +0,0 @@
---
sidebar_position: 4
title: "Retrieval Augmented Generation (RAG)"
---
# Retrieval Augmented Generation (RAG)
Retrieval Augmented Generation (RAG) is a a cutting-edge technology that enhances the conversational capabilities of chatbots by incorporating context from diverse sources. It works by retrieving relevant information from a wide range of sources such as local and remote documents, web content, and even multimedia sources like YouTube videos. The retrieved text is then combined with a predefined RAG template and prefixed to the user's prompt, providing a more informed and contextually relevant response.
One of the key advantages of RAG is its ability to access and integrate information from a variety of sources, making it an ideal solution for complex conversational scenarios. For instance, when a user asks a question related to a specific document or web page, RAG can retrieve and incorporate the relevant information from that source into the chat response. RAG can also retrieve and incorporate information from multimedia sources like YouTube videos. By analyzing the transcripts or captions of these videos, RAG can extract relevant information and incorporate it into the chat response.
## Local and Remote RAG Integration
Local documents must first be uploaded via the Documents section of the Workspace area to access them using the `#` symbol before a query. Click on the formatted URL in the that appears above the chat box. Once selected, a document icon appears above `Send a message`, indicating successful retrieval.
## Web Search for RAG
For web content integration, start a query in a chat with `#`, followed by the target URL. Click on the formatted URL in the box that appears above the chat box. Once selected, a document icon appears above `Send a message`, indicating successful retrieval. Open WebUI fetches and parses information from the URL if it can.
:::tip
Web pages often contain extraneous information such as navigation and footer. For better results, link to a raw or reader-friendly version of the page.
:::
## RAG Template Customization
Customize the RAG template from the `Admin Panel` > `Settings` > `Documents` menu.
## RAG Embedding Support
Change the RAG embedding model directly in the `Admin Panel` > `Settings` > `Documents` menu. This feature supports Ollama and OpenAI models, enabling you to enhance document processing according to your requirements.
## Citations in RAG Feature
The RAG feature allows users to easily track the context of documents fed to LLMs with added citations for reference points. This ensures transparency and accountability in the use of external sources within your chats.
## Enhanced RAG Pipeline
The togglable hybrid search sub-feature for our RAG embedding feature enhances RAG functionality via `BM25`, with re-ranking powered by `CrossEncoder`, and configurable relevance score thresholds. This provides a more precise and tailored RAG experience for your specific use case.
## YouTube RAG Pipeline
The dedicated RAG pipeline for summarizing YouTube videos via video URLs enables smooth interaction with video transcriptions directly. This innovative feature allows you to incorporate video content into your chats, further enriching your conversation experience.
## Document Parsing
A variety of parsers extract content from local and remote documents. For more, see the [`get_loader`](https://github.com/open-webui/open-webui/blob/2fa94956f4e500bf5c42263124c758d8613ee05e/backend/apps/rag/main.py#L328) function.

254
docs/tutorials/features/sso.md
View File

@@ -1,254 +0,0 @@
---
sidebar_position: 9
title: "SSO: Federated Authentication Support"
---
# Federated Authentication Support
Open WebUI supports several forms of federated authentication:
1. OAuth2
1. Google
1. Microsoft
1. OIDC
1. Trusted Header
## OAuth
There are several global configuration options for OAuth:
1. `ENABLE_OAUTH_SIGNUP` - if `true`, allows accounts to be created when logging in with OAuth. Distinct from `ENABLE_SIGNUP`.
1. `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` - allows logging into an account that matches the email address provided by the OAuth provider.
- This is considered insecure as not all OAuth providers verify email addresses, and may allow accounts to be hijacked.
### Google
To configure a Google OAuth client, please refer to [Google's documentation](https://support.google.com/cloud/answer/6158849) on how to create a Google OAuth client for a **web application**.
The allowed redirect URI should include `<open-webui>/oauth/google/callback`.
The following environment variables are required:
1. `GOOGLE_CLIENT_ID` - Google OAuth client ID
1. `GOOGLE_CLIENT_SECRET` - Google OAuth client secret
### Microsoft
To configure a Microsoft OAuth client, please refer to [Microsoft's documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) on how to create a Microsoft OAuth client for a **web application**.
The allowed redirect URI should include `<open-webui>/oauth/microsoft/callback`.
Support for Microsoft OAuth is currently limited to a single tenant, that is a single Entra organization or personal Microsoft accounts.
The following environment variables are required:
1. `MICROSOFT_CLIENT_ID` - Microsoft OAuth client ID
1. `MICROSOFT_CLIENT_SECRET` - Microsoft OAuth client secret
1. `MICROSOFT_CLIENT_TENANT_ID` - Microsoft tenant ID - use `9188040d-6c67-4c5b-b112-36a304b66dad` for personal accounts
### OIDC
Any authentication provider that supports OIDC can be configured.
The `email` claim is required.
`name` and `picture` claims are used if available.
The allowed redirect URI should include `<open-webui>/oauth/oidc/callback`.
The following environment variables are used:
1. `OAUTH_CLIENT_ID` - OIDC client ID
1. `OAUTH_CLIENT_SECRET` - OIDC client secret
1. `OPENID_PROVIDER_URL` - OIDC well known URL, for example `https://accounts.google.com/.well-known/openid-configuration`
1. `OAUTH_PROVIDER_NAME` - Name of the provider to show on the UI, defaults to SSO
1. `OAUTH_SCOPES` - Scopes to request. Defaults to `openid email profile`
### OAuth Role Management
Any OAuth provider that can be configured to return roles in the access token can be used to manage roles in Open WebUI.
To use this feature set `ENABLE_OAUTH_ROLE_MANAGEMENT` to `true`.
You can configure the following environment variables to match the roles returned by the OAuth provider:
1. `OAUTH_ROLES_CLAIM` - The claim that contains the roles. Defaults to `roles`. Can also be nested, for example `user.roles`.
1. `OAUTH_ALLOWED_ROLES` - A comma-separated list of roles that are allowed to log in (receive open webui role `user`).
1. `OAUTH_ADMIN_ROLES` - A comma-separated list of roles that are allowed to log in as an admin (receive open webui role `admin`).
:::info If changing the role of a logged in user, they will need to log out and log back in to receive the new role. :::
## Trusted Header
Open WebUI is able to delegate authentication to an authenticating reverse proxy that passes in the user's details in HTTP headers.
There are several example configurations that are provided in this page.
:::danger
Incorrect configuration can allow users to authenticate as any user on your Open WebUI instance.
Make sure to allow only the authenticating proxy access to Open WebUI, such as setting `HOST=127.0.0.1` to only listen on the loopback interface.
:::
### Generic Configuration
When the `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` environment variable is set, Open WebUI will use the value of the header specified as the email address of the user, handling automatic registration and login.
For example, setting `WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-User-Email` and passing a HTTP header of `X-User-Email: example@example.com` would authenticate the request with the email `example@example.com`.
Optionally, you can also define the `WEBUI_AUTH_TRUSTED_NAME_HEADER` to determine the name of any user being created using trusted headers. This has no effect if the user already exists.
### Tailscale Serve
[Tailscale Serve](https://tailscale.com/kb/1242/tailscale-serve) allows you to share a service within your tailnet, and Tailscale will set the header `Tailscale-User-Login` with the email address of the requester.
Below is an example serve config with a corresponding Docker Compose file that starts a Tailscale sidecar, exposing Open WebUI to the tailnet with the tag `open-webui` and hostname `open-webui`, and can be reachable at `https://open-webui.TAILNET_NAME.ts.net`.
You will need to create an OAuth client with device write permission to pass into the Tailscale container as `TS_AUTHKEY`.
```json title="tailscale/serve.json"
{
"TCP": {
"443": {
"HTTPS": true
}
},
"Web": {
"${TS_CERT_DOMAIN}:443": {
"Handlers": {
"/": {
"Proxy": "http://open-webui:8080"
}
}
}
}
}
```
```yaml title="docker-compose.yaml"
---
services:
open-webui:
image: ghcr.io/open-webui/open-webui:main
volumes:
- open-webui:/app/backend/data
environment:
- HOST=127.0.0.1
- WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Tailscale-User-Login
- WEBUI_AUTH_TRUSTED_NAME_HEADER=Tailscale-User-Name
restart: unless-stopped
tailscale:
image: tailscale/tailscale:latest
environment:
- TS_AUTH_ONCE=true
- TS_AUTHKEY=${TS_AUTHKEY}
- TS_EXTRA_ARGS=--advertise-tags=tag:open-webui
- TS_SERVE_CONFIG=/config/serve.json
- TS_STATE_DIR=/var/lib/tailscale
- TS_HOSTNAME=open-webui
volumes:
- tailscale:/var/lib/tailscale
- ./tailscale:/config
- /dev/net/tun:/dev/net/tun
cap_add:
- net_admin
- sys_module
restart: unless-stopped
volumes:
open-webui: {}
tailscale: {}
```
:::warning
If you run Tailscale in the same network context as Open WebUI, then by default users will be able to directly reach out to Open WebUI without going through the Serve proxy.
You will need use Tailscale's ACLs to restrict access to only port 443.
:::
### Cloudflare Tunnel with Cloudflare Access
[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-remote-tunnel/) can be used with [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/policies/access/) to protect Open WebUI with SSO.
This is barely documented by Cloudflare, but `Cf-Access-Authenticated-User-Email` is set with the email address of the authenticated user.
Below is an example Docker Compose file that sets up a Cloudflare sidecar.
Configuration is done via the dashboard.
From the dashboard, get a tunnel token, set the tunnel backend to `http://open-webui:8080`, and ensure that "Protect with Access" is checked and configured.
```yaml title="docker-compose.yaml"
---
services:
open-webui:
image: ghcr.io/open-webui/open-webui:main
volumes:
- open-webui:/app/backend/data
environment:
- HOST=127.0.0.1
- WEBUI_AUTH_TRUSTED_EMAIL_HEADER=Cf-Access-Authenticated-User-Email
restart: unless-stopped
cloudflared:
image: cloudflare/cloudflared:latest
environment:
- TUNNEL_TOKEN=${TUNNEL_TOKEN}
command: tunnel run
restart: unless-stopped
volumes:
open-webui: {}
```
### oauth2-proxy
[oauth2-proxy](https://oauth2-proxy.github.io/oauth2-proxy/) is an authenticating reverse proxy that implements social OAuth providers and OIDC support.
Given the large number of potential configurations, below is an example of a potential setup with Google OAuth.
Please refer to `oauth2-proxy`'s documentation for detailed setup and any potential security gotchas.
```yaml title="docker-compose.yaml"
services:
open-webui:
image: ghcr.io/open-webui/open-webui:main
volumes:
- open-webui:/app/backend/data
environment:
- 'HOST=127.0.0.1'
- 'WEBUI_AUTH_TRUSTED_EMAIL_HEADER=X-Forwarded-Email'
- 'WEBUI_AUTH_TRUSTED_NAME_HEADER=X-Forwarded-User'
restart: unless-stopped
oauth2-proxy:
image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
environment:
OAUTH2_PROXY_HTTP_ADDRESS: 0.0.0.0:4180
OAUTH2_PROXY_UPSTREAMS: http://open-webui:8080/
OAUTH2_PROXY_PROVIDER: google
OAUTH2_PROXY_CLIENT_ID: REPLACEME_OAUTH_CLIENT_ID
OAUTH2_PROXY_CLIENT_SECRET: REPLACEME_OAUTH_CLIENT_ID
OAUTH2_PROXY_EMAIL_DOMAINS: REPLACEME_ALLOWED_EMAIL_DOMAINS
OAUTH2_PROXY_REDIRECT_URL: REPLACEME_OAUTH_CALLBACK_URL
OAUTH2_PROXY_COOKIE_SECRET: REPLACEME_COOKIE_SECRET
OAUTH2_PROXY_COOKIE_SECURE: "false"
restart: unless-stopped
ports:
- 4180:4180/tcp
```
### Authentik
To configure a [Authentik](https://goauthentik.io/) OAuth client, please refer to [documentation](https://docs.goauthentik.io/docs/applications) on how to create an application and `OAuth2/OpenID Provider`.
The allowed redirect URI should include `<open-webui>/oauth/oidc/callback`.
While creating provider, please note `App-name`, `Client-ID` and `Client-Secret` and use it for open-webui environment variables:
```
- 'ENABLE_OAUTH_SIGNUP=true'
- 'OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true'
- 'OAUTH_PROVIDER_NAME=Authentik'
- 'OPENID_PROVIDER_URL=https://<authentik-url>/application/o/<App-name>/.well-known/openid-configuration'
- 'OAUTH_CLIENT_ID=<Client-ID>'
- 'OAUTH_CLIENT_SECRET=<Client-Secret>'
- 'OAUTH_SCOPES=openid email profile'
- 'OPENID_REDIRECT_URI=https://<open-webui>/oauth/oidc/callback'
```
### Authelia
[Authelia](https://www.authelia.com/) can be configured to return a header for use with trusted header authentication.
Documentation is available [here](https://www.authelia.com/integration/trusted-header-sso/introduction/).
No example configs are provided due to the complexity of deploying Authelia.

256
docs/tutorials/features/web_search.md
View File

@@ -1,256 +0,0 @@
---
sidebar_position: 5
title: "Web Search"
---
# Web Search
## Overview
This guide provides instructions on how to set up web search capabilities in Open WebUI using various search engines.
## SearXNG (Docker)
SearXNG is a metasearch engine that aggregates results from multiple search engines.
### 1. SearXNG Configuration
Create a folder named `searxng` in the same directory as your compose files. This folder will contain your Searxng configuration files. Refer to the [Searxng documentation](https://docs.searxng.org/) for configuration instructions.
#### Configuration Files:
<details>
<summary>searxng/settings.yml</summary>
```yaml
# see https://docs.searxng.org/admin/settings/settings.html#settings-use-default-settings
use_default_settings: true
server:
secret_key: "f9e603d4191caab069b021fa0568391a33c8a837b470892c64461b5dd12464f4"
limiter: false
image_proxy: true
port: 8080
bind_address: "0.0.0.0"
ui:
static_use_hash: true
search:
safe_search: 0
autocomplete: ""
default_lang: ""
formats:
- html
- json
```
</details>
<details>
<summary>searxng/limiter.toml</summary>
```toml
[botdetection.ip_limit]
# activate link_token method in the ip_limit method
link_token = true
```
</details>
<details>
<summary>searxng/uwsgi.ini</summary>
```ini
[uwsgi]
# Who will run the code
uid = searxng
gid = searxng
# Number of workers (usually CPU count)
# default value: %k (= number of CPU core, see Dockerfile)
workers = %k
# Number of threads per worker
# default value: 4 (see Dockerfile)
threads = 4
# The right granted on the created socket
chmod-socket = 666
# Plugin to use and interpreter config
single-interpreter = true
master = true
plugin = python3
lazy-apps = true
enable-threads = 4
# Module to import
module = searx.webapp
# Virtualenv and python path
pythonpath = /usr/local/searxng/
chdir = /usr/local/searxng/searx/
# automatically set processes name to something meaningful
auto-procname = true
# Disable request logging for privacy
disable-logging = true
log-5xx = true
# Set the max size of a request (request-body excluded)
buffer-size = 8192
# No keep alive
# See https://github.com/searx/searx-docker/issues/24
add-header = Connection: close
# uwsgi serves the static files
static-map = /static=/usr/local/searxng/searx/static
# expires set to one day
static-expires = /* 86400
static-gzip-all = True
offload-threads = 4
```
</details>
### 2. Docker Compose Setup
Add the following to a file named `docker-compose.searxng.yaml` alongside your existing `docker-compose.yaml`:
```yaml
services:
open-webui:
environment:
ENABLE_RAG_WEB_SEARCH: True
RAG_WEB_SEARCH_ENGINE: "searxng"
RAG_WEB_SEARCH_RESULT_COUNT: 3
RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10
SEARXNG_QUERY_URL: "http://searxng:8080/search?q=<query>"
searxng:
image: searxng/searxng:latest
container_name: searxng
ports:
- "8080:8080"
volumes:
- ./searxng:/etc/searxng
restart: always
```
Launch your updated stack with:
```bash
docker compose -f docker-compose.yaml -f docker-compose.searxng.yaml up -d
```
Alternatively, you can run SearXNG directly using `docker run`:
```bash
docker run -d --name searxng -p 8080:8080 -v ./searxng:/etc/searxng --restart always searxng/searxng:latest
```
### 3. GUI Configuration
1. Navigate to: `Admin Panel` -> `Settings` -> `Web Search`
2. Toggle `Enable Web Search`
3. Set `Web Search Engine` from dropdown menu to `searxng`
4. Set `Searxng Query URL` to examples given: `https://<search.domain.com>/search?q=<query>` or `http://<searxng.local>/search?q=<query>`. **Do note the `/search?q=<query>` part is mandatory.**
5. Adjust the `Search Result Count` and `Concurrent Requests` values accordingly
6. Save changes
![SearXNG GUI Configuration](/img/tutorial_searxng_config.png)
### 4. Using Web Search in a Chat
To access Web Search, Click on the + next to the message input field.
Here you can toggle Web Search On/Off.
![Web Search UI Toggle](/img/web_search_toggle.png)
#### Note
You will have to explicitly toggle this On/Off in a chat.
This is enabled on a per session basis eg. reloading the page, changing to another chat will toggle off.
## SearchApi API
[SearchApi](https://searchapi.io) is a collection of real-time SERP APIs. Any existing or upcoming SERP engine that returns `organic_results` is supported. The default web search engine is `google`, but it can be changed to `bing`, `baidu`, `google_news`, `bing_news`, `google_scholar`, `google_patents`, and others.
### Setup
1. Go to [SearchApi](https://searchapi.io), and log on or create a new account.
2. Go to `Dashboard` and copy the API key.
3. With `API key`, open `Open WebUI Admin panel` and click `Settings` tab, and then click `Web Search`.
4. Enable `Web search` and set `Web Search Engine` to `searchapi`.
5. Fill `SearchApi API Key` with the `API key` that you copied in step 2 from [SearchApi](https://www.searchapi.io/) dashboard.
6. [Optional] Enter the `SearchApi engine` name you want to query. Example, `google`, `bing`, `baidu`, `google_news`, `bing_news`, `google_videos`, `google_scholar` and `google_patents.` By default, it is set to `google`.
7. Click `Save`.
![Open WebUI Admin panel](/img/tutorial_searchapi_search.png)
#### Note
You have to enable `Web search` in the prompt field, using plus (`+`) button to search the web using [SearchApi](https://www.searchapi.io/) engines.
![enable Web search](/img/enable_web_search.png)
## Google PSE API
### Setup
1. Go to Google Developers, use [Programmable Search Engine](https://developers.google.com/custom-search), and log on or create account.
2. Go to [control panel](https://programmablesearchengine.google.com/controlpanel/all) and click `Add` button
3. Enter a search engine name, set the other properties to suit your needs, verify you're not a robot and click `Create` button.
4. Generate `API key` and get the `Search engine ID`. (Available after the engine is created)
5. With `API key` and `Search engine ID`, open `Open WebUI Admin panel` and click `Settings` tab, and then click `Web Search`
6. Enable `Web search` and Set `Web Search Engine` to `google_pse`
7. Fill `Google PSE API Key` with the `API key` and `Google PSE Engine Id` (# 4)
8. Click `Save`
![Open WebUI Admin panel](/img/tutorial_google_pse1.png)
#### Note
You have to enable `Web search` in the prompt field, using plus (`+`) button.
Search the web ;-)
![enable Web search](/img/tutorial_google_pse2.png)
## Brave API
### Docker Compose Setup
Add the following to a file named `docker-compose.yaml`:
```yaml
services:
open-webui:
environment:
ENABLE_RAG_WEB_SEARCH: True
RAG_WEB_SEARCH_ENGINE: "brave"
BRAVE_SEARCH_API_KEY: "YOUR_API_KEY"
RAG_WEB_SEARCH_RESULT_COUNT: 3
RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10
```
## Serpstack API
Coming Soon
## Serper API
Coming Soon
## Serply API
Coming Soon
## DuckDuckGo API
Coming Soon
## Tavily API
Coming Soon
## Jina API
Coming Soon

27
docs/tutorials/features/whitelist.md
View File

@@ -1,27 +0,0 @@
---
sidebar_position: 8
title: "Model Whitelisting"
---
# Model Whitelisting
Open WebUI allows you to filter specific models for use in your instance. This feature is especially useful for administrators who want to control which models are available to users. Filtering can be done through the WebUI or by adding environment variables to the backend.
## Filtering via WebUI
![Model Filter Configuration](/img/tutorial_model_filter.png)
1. Go to **Admin Panel > Settings > Users**.
2. In the **Manage Models** section, you can enable or disable the model whitelisting feature, and add or remove models from the whitelist.
3. Click **Save** to apply your changes.
## Filtering via Environment Variables
You can also whitelist models by adding environment variables to the backend. This method is useful for automated deployments and can be done by adding the following environment variables to your `docker run` command:
```bash
-e ENABLE_MODEL_FILTER=True \
-e MODEL_FILTER_LIST="llama2:13b;mistral:latest;gpt-3.5-turbo" \
```
In this example, the `ENABLE_MODEL_FILTER` variable is set to `True` to enable the feature, and the `MODEL_FILTER_LIST` variable lists the models to be whitelisted. The format for the `MODEL_FILTER_LIST` variable is `model_name:version;model_name:version;...`.

4
docs/tutorials/features/workspace/index.mdx
View File

@@ -1,4 +0,0 @@
---
sidebar_position: 0
title: "🖥️ Workspace"
---

41
docs/tutorials/features/workspace/models.md
View File

@@ -1,41 +0,0 @@
---
sidebar_position: 16
title: "Models"
---
**Models**
=======================
The `Models` section of the `Workspace` within Open WebUI is a powerful tool that allows you to create and manage custom models tailored to specific purposes. This section serves as a central hub for all your modelfiles, providing a range of features to edit, clone, share, export, and hide your models.
### Modelfile Management
From the `Models` section, you can perform the following actions on your modelfiles:
* **Edit**: Dive into the details of your modelfile and make changes to its character and more.
* **Clone**: Create a copy of a modelfile, which will be appended with `-clone` to the cloned `Model ID`. Note that you cannot clone a base model; you must create a model first before cloning it.
* **Share**: Share your modelfile with the Open WebUI community by clicking the `Share` button, which will redirect you to [https://openwebui.com/models/create](https://openwebui.com/models/create).
* **Export**: Download the modelfile's `.json` export to your PC.
* **Hide**: Hide the modelfile from the model selector dropdown within chats.
### Modelfile Editing
When editing a modelfile, you can customize the following settings:
* **Avatar Photo**: Upload an avatar photo to represent your modelfile.
* **Model Name**: Change the name of your modelfile.
* **System Prompt**: Provide an optional system prompt for your modelfile.
* **Model Parameters**: Adjust the parameters of your modelfile.
* **Prompt Suggestions**: Add prompts that will be displayed on a fresh new chat page.
* **Documents**: Add documents to the modelfile (always RAG [Retrieval Augmented Generation]).
* **Tools, Filters, and Actions**: Select the tools, filters, and actions that will be available to the modelfile.
* **Vision**: Toggle to enable `Vision` for multi-modals.
* **Tags**: Add tags to the modelfile that will be displayed beside the model name in the model selector dropdown.
### Model Discovery and Import/Export
The `Models` section also includes features for discovering, importing, and exporting models:
* **Discover a Model**: Click this button to explore and download model presets from the Open WebUI community.
* **Import Models**: Use this button to import models from a `.json` file or other sources.
* **Export Models**: Use this button to export all your modelfiles in a single `.json` file.

5
docs/tutorials/integrations/apache.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 7
title: "Hosting UI and Models separately"
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
# Hosting UI and Models separately
:::note

5
docs/tutorials/integrations/browser-search-engine.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 16
title: "Browser Search Engine"
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
# Browser Search Engine Integration
Open WebUI allows you to integrate directly into your web browser. This tutorial will guide you through the process of setting up Open WebUI as a custom search engine, enabling you to execute queries easily from your browser's address bar.

6
docs/tutorials/integrations/continue-dev.md
View File

@@ -3,6 +3,12 @@ sidebar_position: 13
title: "Continue.dev VSCode Extension with Open WebUI"
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
# Integrating Continue.dev VSCode Extension with Open WebUI
### Download Extension

5
docs/tutorials/integrations/custom-ca.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 14
title: Setting up with custom CA store
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
If you get an `[SSL: CERTIFICATE_VERIFY_FAILED]` error when trying to run OI, most likely the issue is that you are on a network which intercepts HTTPS traffic (e.g. a corporate network).
To fix this, you will need to add the new cert into OI's truststore.

5
docs/tutorials/integrations/docker-install.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 2
title: Installing Docker
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
# Installing Docker
## For Windows and Mac Users

5
docs/tutorials/integrations/ipex_llm.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 11
title: "Local LLM Setup with IPEX-LLM on Intel GPU"
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
:::note
This guide is verified with Open WebUI setup through [Manual Installation](/getting-started/index.md).
:::

5
docs/tutorials/integrations/openai-edge-tts-integration.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 18
title: "Edge TTS"
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
# Integrating `openai-edge-tts` 🗣️ with Open WebUI
## What is `openai-edge-tts`, and how is it different from `openedai-speech`?

5
docs/tutorials/integrations/openedai-speech-integration.md
View File

@@ -3,6 +3,11 @@ sidebar_position: 12
title: "TTS - OpenedAI-Speech using Docker"
---
:::warning
This tutorial is a community contribution and is not supported by the OpenWebUI team. It serves only as a demonstration on how to customize OpenWebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
:::
**Integrating `openedai-speech` into Open WebUI using Docker**
==============================================================

20
docs/tutorials/plugin/functions/actions.md
View File

@@ -1,20 +0,0 @@
---
sidebar_position: 6
title: "Actions"
---
# Actions
Action functions allow you to write custom buttons to the message toolbar for end users to interact
with. This feature enables more interactive messaging, enabling users to grant permission before a
task is performed, generate visualizations of structured data, download an audio snippet of chats,
and many other use cases.
A scaffold of Action code can be found [in the community section](https://openwebui.com/f/hub/custom_action/).
An example of a graph visualization Action can be seen in the video below.
<p align="center">
<a href="#">
<img src="/img/pipelines/graph-viz-action.gif" alt="Graph Visualization Action" />
</a>
</p>

363
docs/tutorials/plugin/functions/index.mdx
View File

@@ -1,363 +0,0 @@
---
sidebar_position: 1
title: "Functions"
---
## What are Functions?
Functions are modular operations that allow users to enhance the capabilities of the AI by embedding specific logic or actions directly into workflows. Unlike tools, which operate as external utilities, functions run natively within the OpenWebUI environment and handle tasks such as data processing, visualization, and interactive messaging. Functions are lightweight and designed to execute efficiently on the same server as the WebUI, enabling quick responses without the need for external dependencies.
## How can I use Functions?
Functions can be used, [once installed](#how-to-install-functions), by assigning them to an LLM or enabling them globally. Some function types will always be enabled globally, such as manifolds. To assign a function to a model, you simply need to navigate to Workspace => Models. Here you can select the model for which you’d like to enable any Functinos.
Once you click the pencil icon to edit the model settings, scroll down to the Functions section and check any Functions you wish to enable. Once done you must click save.
You also have the ability to enable Functions globally for ALL models. In order to do this, navigate to Workspace => Functions and click the "..." menu. Once the menu opens, simply enable the "Global" switch and your function will be enabled for every model in your OpenWebUI instance.
## How to install Functions
The Functions import process is quite simple. You will have two options:
### Download and import manually
Navigate to the community site: https://openwebui.com/functions/
1) Click on the Function you wish to import
2) Click the blue “Get” button in the top right-hand corner of the page
3) Click “Download as JSON export”
4) You can now upload the Funtion into OpenWebUI by navigating to Workspace => Functions and clicking “Import Functions
### Import via your OpenWebUI URL
1) Navigate to the community site: https://openwebui.com/functions/
2) Click on the Function you wish to import
3) Click the blue “Get” button in the top right-hand corner of the page
4) Enter the IP address of your OpenWebUI instance and click “Import to WebUI” which will automatically open your instance and allow you to import the Function.
Note: You can install your own Function and other Functions not tracked on the community site using the manual import method. Please do not import Functions you do not understand or are not from a trustworthy source. Running unknown code is ALWAYS a risk.
## What are the support types of functions
### Filter
Filters are used to manipulate the user input and/or the LLM output to add, remove, format, or otherwise adjust the content of the body object.
Filters have a few main components:
#### Inlet Function
The inlet is user to pre-process a user input before it is send to the LLM for processing.
#### Outlet Function
The outlet is used to post-process the output from the LLM. It is important to note that when you perform actions such as stripping/replacing content, this will happen after the output is rendered to the UI.
<details>
<summary>Example</summary>
```
class Filter:
# Define and Valves
class Valves(BaseModel):
priority: int = Field(
default=0, description="Priority level for the filter operations."
)
test_valve: int = Field(
default=4, description="A valve controlling a numberical value"
)
pass
# Define any UserValves
class UserValves(BaseModel):
test_user_valve: bool = Field(
default=False, description="A user valve controlling a True/False (on/off) switch"
)
pass
def __init__(self):
self.valves = self.Valves()
pass
def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
print(f"inlet:{__name__}")
print(f"inlet:body:{body}")
print(f"inlet:user:{__user__}")
# Pre-processing logic here
return body
def outlet(self, body: dict, __user__: Optional[dict] = None) -> dict:
print(f"outlet:{__name__}")
print(f"outlet:body:{body}")
print(f"outlet:user:{__user__}")
# Post-processing logic here
return body
```
</details>
### Action
Actions are used to create a button in the Message UI (the small buttons found directly underneath individual chat messages).
Actions have a single main component called an action function. This component takes an object defining the type of action and the data being processed.
<details>
<summary>Example</summary>
```
async def action(
self,
body: dict,
__user__=None,
__event_emitter__=None,
__event_call__=None,
) -> Optional[dict]:
print(f"action:{__name__}")
response = await __event_call__(
{
"type": "input",
"data": {
"title": "write a message",
"message": "here write a message to append",
"placeholder": "enter your message",
},
}
)
print(response)
```
</details>
#### Pipes
#### Pipe
A Pipe is used to create a "Model" with custom logic and processing. A Pipe will always show up as it's own singular model in the OpenWebUI interface and will, much like a filter
A Pipe has a single main component called a pipe function. This component encapsulates all of the primary logic that the Pipe will perform.
<details>
<summary>Example</summary>
```
class Pipe:
class Valves(BaseModel):
RANDOM_CONFIG_OPTION: str = Field(default="")
def __init__(self):
self.type = "pipe"
self.id = "blah"
self.name = "Testing"
self.valves = self.Valves(
**{"RANDOM_CONFIG_OPTION": os.getenv("RANDOM_CONFIG_OPTION", "")}
)
pass
def get_provider_models(self):
return [
{"id": "model_id_1", "name": "model_1"},
{"id": "model_id_2", "name": "model_2"},
{"id": "model_id_3", "name": "model_3"},
]
def pipe(self, body: dict) -> Union[str, Generator, Iterator]:
# Logic goes here
return body
```
</details>
#### Manifold
A Manifold is used to create a collection of Pipes. If a Pipe creates a singular "Model", a Manifold creates a set of "Models." Manifolds are typically used to create integrations with other providers.
A Manifold has two main components:
##### Pipes Function
This is used to simply initiate a dictionary to hold all of the Pipes created by the manifold
##### Pipe Function
As referenced above, this component encapsulates all of the primary logic that the Pipe will perform.
<details>
<summary>Example</summary>
```
class Pipe:
class Valves(BaseModel):
PROVIDER_API_KEY: str = Field(default="")
def __init__(self):
self.type = "manifold"
self.id = "blah"
self.name = "Testing"
self.valves = self.Valves(
**{"PROVIDER_API_KEY": os.getenv("PROVIDER_API_KEY", "")}
)
pass
def get_provider_models(self):
return [
{"id": "model_id_1", "name": "model_1"},
{"id": "model_id_2", "name": "model_2"},
{"id": "model_id_3", "name": "model_3"},
]
def pipes(self) -> List[dict]:
return self.get_provider_models()
def pipe(self, body: dict) -> Union[str, Generator, Iterator]:
# Logic goes here
return body
```
</details>
Note: To differentiate between a Pipe and a Manifold you will need to specify the type in def init:
```
def __init__(self):
self.type = "pipe"
self.id = "blah"
self.name = "Testing"
pass
```
or
```
def __init__(self):
self.type = "manifold"
self.id = "blah"
self.name = "Testing/"
pass
```
## Shared Function Components
### Valves and UserValves - (optional, but HIGHLY encouraged)
Valves and UserValves are used to allow users to provide dyanmic details such as an API key or a configuration option. These will create a fillable field or a bool switch in the GUI menu for the given function.
Valves are configurable by admins alone and UserValves are configurable by any users.
<details>
<summary>Example</summary>
```
# Define and Valves
class Valves(BaseModel):
priority: int = Field(
default=0, description="Priority level for the filter operations."
)
test_valve: int = Field(
default=4, description="A valve controlling a numberical value"
)
pass
# Define any UserValves
class UserValves(BaseModel):
test_user_valve: bool = Field(
default=False, description="A user valve controlling a True/False (on/off) switch"
)
pass
def __init__(self):
self.valves = self.Valves()
pass
```
</details>
### Event Emitters
Event Emitters are used to add additional information to the chat interface. Similarly to Filter Outlets, Event Emitters are capable of appending content to the chat. Unlike Filter Outlets, they are not capable of stripping information. Additionally, emitters can be activated at any stage during the function.
There are two different types of Event Emitters:
#### Status
This is used to add statuses to a message while it is performing steps. These can be done at any stage during the Function. These statuses appear right above the message content. These are very useful for Functions that delay the LLM response or process large amounts of information. This allows you to inform users what is being processed in real-time.
```
await __event_emitter__(
{
"type": "status", # We set the type here
"data": {"description": "Message that shows up in the chat", "done": False},
# Note done is False here indicating we are still emitting statuses
}
)
```
<details>
<summary>Example</summary>
```
async def test_function(
self, prompt: str, __user__: dict, __event_emitter__=None
) -> str:
"""
This is a demo
:param test: this is a test parameter
"""
await __event_emitter__(
{
"type": "status", # We set the type here
"data": {"description": "Message that shows up in the chat", "done": False},
# Note done is False here indicating we are still emitting statuses
}
)
# Do some other logic here
await __event_emitter__(
{
"type": "status",
"data": {"description": "Completed a task message", "done": True},
# Note done is True here indicating we are done emitting statuses
}
)
except Exception as e:
await __event_emitter__(
{
"type": "status",
"data": {"description": f"An error occured: {e}", "done": True},
}
)
return f"Tell the user: {e}"
```
</details>
#### Message
This type is used to append a message to the LLM at any stage in the Function. This means that you can append messages, embed images, and even render web pages before, or after, or during the LLM response.
```
await __event_emitter__(
{
"type": "message", # We set the type here
"data": {"content": "This message will be appended to the chat."},
# Note that with message types we do NOT have to set a done condition
}
)
```
<details>
<summary>Example</summary>
```
async def test_function(
self, prompt: str, __user__: dict, __event_emitter__=None
) -> str:
"""
This is a demo
:param test: this is a test parameter
"""
await __event_emitter__(
{
"type": "message", # We set the type here
"data": {"content": "This message will be appended to the chat."},
# Note that with message types we do NOT have to set a done condition
}
)
except Exception as e:
await __event_emitter__(
{
"type": "status",
"data": {"description": f"An error occured: {e}", "done": True},
}
)
return f"Tell the user: {e}"
```
</details>

80
docs/tutorials/plugin/index.mdx
View File

@@ -1,80 +0,0 @@
---
sidebar_position: 2
title: "🛠️ Tools & Functions"
---
# 🛠️ Tools & Functions
Imagine you've just stumbled upon Open WebUI, or maybe you're already using it, but you're a bit lost with all the talk about "Tools", "Functions", and "Pipelines". Everything sounds like some mysterious tech jargon, right? No worries! Let's break it down piece by piece, super clearly, step by step. By the end of this, you'll have a solid understanding of what these terms mean, how they work, and why know it's not as complicated as it seems.
## TL;DR
- **Tools** extend the abilities of LLMs, allowing them to collect real-world, real-time data like weather, stock prices, etc.
- **Functions** extend the capabilities of the Open WebUI itself, enabling you to add new AI model support (like Anthropic or Vertex AI) or improve usability (like creating custom buttons or filters).
- **Pipelines** are more for advanced users who want to transform Open WebUI features into API-compatible workflows—mainly for offloading heavy processing.
Getting started with Tools and Functions is easy because everything’s already built into the core system! You just **click a button** and **import these features directly from the community**, so there’s no coding or deep technical work required.
## What are "Tools" and "Functions"?
Let's start by thinking of **Open WebUI** as a "base" software that can do many tasks related to using Large Language Models (LLMs). But sometimes, you need extra features or abilities that don't come *out of the box*—this is where **tools** and **functions** come into play.
### Tools
**Tools** are an exciting feature because they allow LLMs to do more than just process text. They provide **external abilities** that LLMs wouldn't otherwise have on their own.
#### Example of a Tool:
Imagine you're chatting with an LLM and you want it to give you the latest weather update or stock prices in real time. Normally, the LLM can't do that because it's just working on pre-trained knowledge. This is where **tools** come in!
- **Tools are like plugins** that the LLM can use to gather **real-world, real-time data**. So, with a "weather tool" enabled, the model can go out on the internet, gather live weather data, and display it in your conversation.
Tools are essentially **abilities** you’re giving your AI to help it interact with the outside world. By adding these, the LLM can "grab" useful information or perform specialized tasks based on the context of the conversation.
#### Examples of Tools (extending LLM’s abilities):
1. **Real-time weather predictions** 🛰️.
2. **Stock price retrievers** 📈.
3. **Flight tracking information** ✈️.
### Functions
While **tools** are used by the AI during a conversation, **functions** help extend or customize the capabilities of Open WebUI itself. Imagine tools are like adding new ingredients to a dish, and functions are the process you use to control the kitchen! 🚪
#### Let's break that down:
- **Functions** give you the ability to tweak or add **features** inside **Open WebUI** itself.
- You’re not giving new abilities to the LLM, but instead, you’re extending the **interface, behavior, or logic** of the platform itself!
For instance, maybe you want to:
1. Add a new AI model like **Anthropic** to the WebUI.
2. Create a custom button in your toolbar that performs a frequently used command.
3. Implement a better **filter** function that catches inappropriate or **spammy messages** from the incoming text.
Without functions, these would all be out of reach. But with this framework in Open WebUI, you can easily extend these features!
### Summary of Differences:
- **Tools** are things that allow LLMs to **do more things** outside their default abilities (such as retrieving live info or performing custom tasks based on external data).
- **Functions** help the WebUI itself **do more things**, like adding new AI models or creating smarter ways to filter data.
Both are designed to be **pluggable**, meaning you can easily import them into your system with just one click from the community! 🎉 You won’t have to spend hours coding or tinkering with them.
## What are Pipelines?
And then, we have **Pipelines**… Here’s where things start to sound pretty technical—but don’t despair.
**Pipelines** are part of an Open WebUI initiative focused on making every piece of the WebUI **inter-operable with OpenAI’s API system**. Essentially, they extend what both **Tools** and **Functions** can already do, but now with even more flexibility. They allow you to turn features into OpenAI API-compatible formats. 🧠
### But here’s the thing…
You likely **won't need** pipelines unless you're dealing with super-advanced setups.
- **Who are pipelines for?** Typically, **experts** or people running more complicated use cases.
- **When do you need them?** If you're trying to offload processing from your primary Open WebUI instance to a different machine (so you don’t overload your primary system).
In most cases, as a beginner or even an intermediate user, you won’t have to worry about pipelines. Just focus on enjoying the benefits that **tools** and **functions** bring to your Open WebUI experience!
## Want to Try? 🚀
Jump into Open WebUI, head over to the community section, and try importing a tool like **weather updates** or maybe adding a new feature to the toolbar with a function. Exploring these tools will show you how powerful and flexible Open WebUI can be!
🌟 There's always more to learn, so stay curious and keep experimenting!

187
docs/tutorials/plugin/tools/index.mdx
View File

@@ -1,187 +0,0 @@
---
sidebar_position: 0
title: "Tools"
---
## What are Tools?
Tools are python scripts that are provided to an LLM at the time of the request. Tools allow LLMs to perform actions and receive additional context as a result. Generally speaking, your LLM of choice will need to support function calling for tools to be reliably utilized.
Tools enable many use cases for chats, including web search, web scraping, and API interactions within the chat.
Many Tools are available to use on the [Community Website](https://openwebui.com/tools) and can easily be imported into your Open WebUI instance.
## How can I use Tools?
[Once installed](#how-to-install-tools), Tools can be used by assigning them to any LLM that supports function calling and then enabling that Tool. To assign a Tool to a model, you need to navigate to Workspace => Models. Here you can select the model for which you’d like to enable any Tools.
Once you click the pencil icon to edit the model settings, scroll down to the Tools section and check any Tools you wish to enable. Once done you must click save.
Now that Tools are enabled for the model, you can click the “+” icon when chatting with an LLM to use various Tools. Please keep in mind that enabling a Tool does not force it to be used. It means the LLM will be provided the option to call this Tool.
Lastly, we do provide a filter function on the community site that allows LLMs to autoselect Tools without you needing to enable them in the “+” icon menu: https://openwebui.com/f/hub/autotool_filter/
Please note: when using the AutoTool Filter, you will still need to take the steps above to enable the Tools per model.
## How to install Tools
The Tools import process is quite simple. You will have two options:
### Download and import manually
Navigate to the community site: https://openwebui.com/tools/
1) Click on the Tool you wish to import
2) Click the blue “Get” button in the top right-hand corner of the page
3) Click “Download as JSON export”
4) You can now upload the Tool into OpenWebUI by navigating to Workspace => Tools and clicking “Import Tools”
### Import via your OpenWebUI URL
1) Navigate to the community site: https://openwebui.com/tools/
2) Click on the Tool you wish to import
3) Click the blue “Get” button in the top right-hand corner of the page
4) Enter the IP address of your OpenWebUI instance and click “Import to WebUI” which will automatically open your instance and allow you to import the Tool.
Note: You can install your own Tools and other Tools not tracked on the community site using the manual import method. Please do not import Tools you do not understand or are not from a trustworthy source. Running unknown code is ALWAYS a risk.
## What sorts of things can Tools do?
Tools enable diverse use cases for interactive conversations by providing a wide range of functionality such as:
- [**Web Search**](https://openwebui.com/t/constliakos/web_search/): Perform live web searches to fetch real-time information.
- [**Image Generation**](https://openwebui.com/t/justinrahb/image_gen/): Generate images based on the user prompt
- [**External Voice Synthesis**](https://openwebui.com/t/justinrahb/elevenlabs_tts/): Make API requests within the chat to integrate external voice synthesis service ElevenLabs and generate audio based on the LLM output.
## Important Tools Components
### Valves and UserValves - (optional, but HIGHLY encouraged)
Valves and UserValves are used to allow users to provide dyanmic details such as an API key or a configuration option. These will create a fillable field or a bool switch in the GUI menu for the given Tool.
Valves are configurable by admins alone and UserValves are configurable by any users.
<details>
<summary>Example</summary>
```
# Define and Valves
class Valves(BaseModel):
priority: int = Field(
default=0, description="Priority level for the filter operations."
)
test_valve: int = Field(
default=4, description="A valve controlling a numberical value"
)
pass
# Define any UserValves
class UserValves(BaseModel):
test_user_valve: bool = Field(
default=False, description="A user valve controlling a True/False (on/off) switch"
)
pass
def __init__(self):
self.valves = self.Valves()
pass
```
</details>
### Event Emitters
Event Emitters are used to add additional information to the chat interface. Similarly to Filter Outlets, Event Emitters are capable of appending content to the chat. Unlike Filter Outlets, they are not capable of stripping information. Additionally, emitters can be activated at any stage during the Tool.
There are two different types of Event Emitters:
#### Status
This is used to add statuses to a message while it is performing steps. These can be done at any stage during the Tool. These statuses appear right above the message content. These are very useful for Tools that delay the LLM response or process large amounts of information. This allows you to inform users what is being processed in real-time.
```
await __event_emitter__(
{
"type": "status", # We set the type here
"data": {"description": "Message that shows up in the chat", "done": False},
# Note done is False here indicating we are still emitting statuses
}
)
```
<details>
<summary>Example</summary>
```
async def test_function(
self, prompt: str, __user__: dict, __event_emitter__=None
) -> str:
"""
This is a demo
:param test: this is a test parameter
"""
await __event_emitter__(
{
"type": "status", # We set the type here
"data": {"description": "Message that shows up in the chat", "done": False},
# Note done is False here indicating we are still emitting statuses
}
)
# Do some other logic here
await __event_emitter__(
{
"type": "status",
"data": {"description": "Completed a task message", "done": True},
# Note done is True here indicating we are done emitting statuses
}
)
except Exception as e:
await __event_emitter__(
{
"type": "status",
"data": {"description": f"An error occured: {e}", "done": True},
}
)
return f"Tell the user: {e}"
```
</details>
#### Message
This type is used to append a message to the LLM at any stage in the Tool. This means that you can append messages, embed images, and even render web pages before, or after, or during the LLM response.
```
await __event_emitter__(
{
"type": "message", # We set the type here
"data": {"content": "This message will be appended to the chat."},
# Note that with message types we do NOT have to set a done condition
}
)
```
<details>
<summary>Example</summary>
```
async def test_function(
self, prompt: str, __user__: dict, __event_emitter__=None
) -> str:
"""
This is a demo
:param test: this is a test parameter
"""
await __event_emitter__(
{
"type": "message", # We set the type here
"data": {"content": "This message will be appended to the chat."},
# Note that with message types we do NOT have to set a done condition
}
)
except Exception as e:
await __event_emitter__(
{
"type": "status",
"data": {"description": f"An error occured: {e}", "done": True},
}
)
return f"Tell the user: {e}"
```
</details>