mirror of
https://github.com/open-webui/docs.git
synced 2026-01-04 10:46:26 +07:00
Merge pull request #695 from open-webui/dev
0.6.29 docs PR merge dev to main
This commit is contained in:
Classic298
@@ -5,18 +5,19 @@ title: "🔎 Retrieval Augmented Generation (RAG)"
|
||||
|
||||
:::warning
|
||||
|
||||
If you're using **Ollama**, note that it **defaults to a 2048-token context length**. This means that retrieved data may **not be used at all** because it doesn’t fit within the available context window. To improve **Retrieval-Augmented Generation (RAG) performance**, you should **increase the context length** to **8192+ tokens** in your Ollama model settings.
|
||||
If you're using **Ollama**, note that it **defaults to a 2048-token context length**. This severely limits **Retrieval-Augmented Generation (RAG) performance**, especially for web search, because retrieved data may **not be used at all** or only partially processed.
|
||||
|
||||
**Why This Is Critical for Web Search:**
|
||||
Web pages typically contain 4,000-8,000+ tokens even after content extraction, including main content, navigation elements, headers, footers, and metadata. With only 2048 tokens available, you're getting less than half the page content, often missing the most relevant information. Even 4096 tokens is frequently insufficient for comprehensive web content analysis.
|
||||
|
||||
**To Fix This:** Navigate to **Admin Panel > Models > Settings** (of your Ollama model) > **Advanced Parameters** and **increase the context length to 8192+ (or rather, more than 16000) tokens**. This setting specifically applies to Ollama models. For OpenAI and other integrated models, ensure you're using a model with sufficient built-in context length (e.g., GPT-4 Turbo with 128k tokens).
|
||||
|
||||
:::
|
||||
|
||||
|
||||
Retrieval Augmented Generation (RAG) is 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.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
sidebar_position: 19
|
||||
title: "🔒 SSO: Federated Authentication Support"
|
||||
title: "🔐 SSO: Federated Authentication Support"
|
||||
---
|
||||
|
||||
# Federated Authentication Support
|
||||
@@ -21,6 +21,13 @@ It is highly recommended to check the environment variable page, to get more det
|
||||
|
||||
:::
|
||||
|
||||
:::tip
|
||||
|
||||
Need help with troubleshooting your SSO setup?
|
||||
Check out our [troubleshooting guide](https://docs.openwebui.com/troubleshooting/sso)
|
||||
|
||||
:::
|
||||
|
||||
:::danger
|
||||
|
||||
Right now, you can only configure one OAUTH provider at a time.
|
||||
@@ -42,6 +49,20 @@ You cannot have Microsoft **and** Google as providers simultaneously.
|
||||
| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | **Required.** A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster. |
|
||||
| `ENABLE_OAUTH_ID_TOKEN_COOKIE` | `true` | For backward compatibility. Controls if the legacy `oauth_id_token` cookie is set. Recommended to set to `false`. |
|
||||
|
||||
:::warning
|
||||
|
||||
**Critical Configuration Notes:**
|
||||
|
||||
1. **WEBUI_URL Must Be Set First**: Configure `WEBUI_URL` in the Admin Panel before enabling OAuth, as it's used for redirect URIs.
|
||||
|
||||
2. **Persistent Config Behavior**: When `ENABLE_OAUTH_PERSISTENT_CONFIG=true` (default), OAuth settings are stored in the database after first launch. To change environment variables after initial setup, either:
|
||||
- Set `ENABLE_OAUTH_PERSISTENT_CONFIG=false` to always read from environment variables
|
||||
- Update settings through the Admin Panel instead of environment variables
|
||||
|
||||
3. **Required Variables**: Always verify you're using the exact variable names from the [environment configuration documentation](https://docs.openwebui.com/getting-started/env-configuration/). Common mistakes include using non-existent variables like `OIDC_CONFIG`.
|
||||
|
||||
:::
|
||||
|
||||
### Server-Side OAuth Session Management
|
||||
|
||||
To solve issues related to large tokens (e.g., with AD FS group claims exceeding cookie size limits) and to enable automatic token refreshing, Open WebUI now supports a robust server-side session management system.
|
||||
@@ -104,11 +125,20 @@ 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. `OPENID_PROVIDER_URL` - **Required.** 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`
|
||||
1. `OPENID_REDIRECT_URI` - The redirect URI configured in your OIDC application. This must be set to `<open-webui>/oauth/oidc/callback`.
|
||||
|
||||
:::warning
|
||||
|
||||
**Common OIDC Mistakes:**
|
||||
- Using non-existent environment variables like `OIDC_CONFIG` or `WEBUI_OIDC_CLIENT_ID`
|
||||
- Forgetting to set `OPENID_PROVIDER_URL` (this is mandatory for OIDC)
|
||||
- Using incorrect redirect URI format - must be exactly `<your-domain>/oauth/oidc/callback`
|
||||
|
||||
:::
|
||||
|
||||
### 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.
|
||||
|
||||
@@ -48,6 +48,8 @@ By leveraging custom input variables, you can move beyond static text and build
|
||||
### Variable Usage Guidelines
|
||||
|
||||
* Enclose all variables with double curly braces: `{{variable}}`
|
||||
* **All custom input variables are optional by default** - users can leave fields blank when filling out the form
|
||||
* Use the `:required` flag to make specific variables mandatory when necessary
|
||||
* The `{{USER_LOCATION}}` system variable requires:
|
||||
* A secure HTTPS connection
|
||||
* Enabling the feature in `Settings` > `Interface`
|
||||
@@ -62,7 +64,7 @@ By leveraging custom input variables, you can move beyond static text and build
|
||||
1. **Create a prompt** with one or more custom variables using the syntax below.
|
||||
2. **Use the prompt's slash command** in the chat input.
|
||||
3. An **"Input Variables" popup window** will appear with a form field for each variable you defined.
|
||||
4. **Fill out the form** and click `Save`.
|
||||
4. **Fill out the form** and click `Save`. Note that by default, all fields are optional unless explicitly marked as required.
|
||||
5. The variables in your prompt will be replaced with your input, and the final prompt will be sent to the model.
|
||||
|
||||
**Syntax**
|
||||
@@ -71,9 +73,27 @@ There are two ways to define a custom variable:
|
||||
|
||||
1. **Simple Input**: `{{variable_name}}`
|
||||
* This creates a standard, single-line `text` type input field in the popup window.
|
||||
* The field will be optional by default.
|
||||
|
||||
2. **Typed Input**: `{{variable_name | [type][:property="value"]}}`
|
||||
* This allows you to specify the type of input field (e.g., a dropdown, a date picker) and configure its properties.
|
||||
* The field will be optional by default unless you add the `:required` flag.
|
||||
|
||||
**Required vs Optional Variables**
|
||||
|
||||
By default, all custom input variables are **optional**, meaning users can leave them blank when filling out the form. This flexible approach allows for versatile prompt templates where some information might not always be needed.
|
||||
|
||||
To make a variable **required** (mandatory), add the `:required` flag:
|
||||
|
||||
```
|
||||
{{mandatory_field | text:required}}
|
||||
{{optional_field | text}}
|
||||
```
|
||||
|
||||
When a field is marked as required:
|
||||
- The form will display a visual indicator (asterisk) next to the field label
|
||||
- Users cannot submit the form without providing a value
|
||||
- Browser validation will prevent form submission if required fields are empty
|
||||
|
||||
**Input Types Overview**
|
||||
|
||||
@@ -81,96 +101,131 @@ You can specify different input types to build rich, user-friendly forms. Here i
|
||||
|
||||
| Type | Description | Available Properties | Syntax Example |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **text** | A standard single-line text input field, perfect for capturing short pieces of information like names, titles, or single-sentence summaries. This is the **default type if no other is specified**. | `placeholder`, `default` | `{{name \| text:placeholder="Enter name"}}` |
|
||||
| **textarea**| A multi-line text area designed for capturing longer blocks of text, such as detailed descriptions, article content, or code snippets. | `placeholder`, `default` | `{{description \| textarea}}` |
|
||||
| **select** | A dropdown menu that presents a predefined list of choices. This is ideal for ensuring consistent input for things like status, priority, or categories. | `options` (JSON array), `default` | `{{priority \| select:options=["High","Low"]}}` |
|
||||
| **number** | An input field that is restricted to numerical values only. Useful for quantities, ratings, or any other numeric data. | `placeholder`, `default` | `{{count \| number:default=5}}` |
|
||||
| **checkbox**| A simple checkbox that represents a true or false (boolean) value. It's perfect for on/off toggles, like 'Include a conclusion?' or 'Mark as urgent?'. | `default` (boolean) | `{{include_details \| checkbox}}` |
|
||||
| **date** | A calendar-based date picker that allows users to easily select a specific day, month, and year, ensuring a standardized date format. | `default` (YYYY-MM-DD) | `{{start_date \| date}}` |
|
||||
| **datetime-local**| A specialized picker that allows users to select both a specific date and a specific time. Great for scheduling appointments or logging event timestamps. | `default` | `{{appointment \| datetime-local}}` |
|
||||
| **color** | A visual color picker that allows the user to select a color or input a standard hex code (e.g., #FF5733). Useful for design and branding prompts. | `default` (hex code) | `{{brand_color \| color:default="#FFFFFF"}}` |
|
||||
| **email** | An input field specifically formatted and validated for email addresses, ensuring the user provides a correctly structured email. | `placeholder`, `default` | `{{recipient_email \| email}}` |
|
||||
| **month** | A picker that allows users to select a specific month and year, without needing to choose a day. Useful for billing cycles, reports, or timelines. | `default` | `{{billing_month \| month}}` |
|
||||
| **range** | A slider control that allows the user to select a numerical value from within a defined minimum and maximum range. Ideal for satisfaction scores or percentage adjustments. | `min`, `max`, `step`, `default` | `{{satisfaction \| range}}` |
|
||||
| **tel** | An input field designed for telephone numbers. It semantically indicates the expected input type for browsers and devices. | `placeholder`, `default` | `{{phone_number \| tel}}` |
|
||||
| **time** | A picker for selecting a time. Useful for scheduling meetings, logging events, or setting reminders without an associated date. | `default` | `{{meeting_time \| time}}` |
|
||||
| **url** | An input field for web addresses (URLs). It helps ensure that the user provides a link, which can be useful for prompts that analyze websites or reference online sources. | `placeholder`, `default` | `{{website \| url}}` |
|
||||
| **map** | **(Experimental)** An interactive map interface that lets users click to select geographic coordinates. This is a powerful tool for location-based prompts. | `default` (e.g., "51.5,-0.09") | `{{location \| map}}` |
|
||||
|
||||
| **text** | A standard single-line text input field, perfect for capturing short pieces of information like names, titles, or single-sentence summaries. This is the **default type if no other is specified**. | `placeholder`, `default`, `required` | `{{name \| text:placeholder="Enter name":required}}` |
|
||||
| **textarea**| A multi-line text area designed for capturing longer blocks of text, such as detailed descriptions, article content, or code snippets. | `placeholder`, `default`, `required` | `{{description \| textarea:required}}` |
|
||||
| **select** | A dropdown menu that presents a predefined list of choices. This is ideal for ensuring consistent input for things like status, priority, or categories. | `options` (JSON array), `default`, `required` | `{{priority \| select:options=["High","Medium","Low"]:required}}` |
|
||||
| **number** | An input field that is restricted to numerical values only. Useful for quantities, ratings, or any other numeric data. | `placeholder`, `default`, `required` | `{{count \| number:default=5}}` |
|
||||
| **checkbox**| A simple checkbox that represents a true or false (boolean) value. It's perfect for on/off toggles, like 'Include a conclusion?' or 'Mark as urgent?'. | `default` (boolean), `required` | `{{include_details \| checkbox}}` |
|
||||
| **date** | A calendar-based date picker that allows users to easily select a specific day, month, and year, ensuring a standardized date format. | `default` (YYYY-MM-DD), `required` | `{{start_date \| date:required}}` |
|
||||
| **datetime-local**| A specialized picker that allows users to select both a specific date and a specific time. Great for scheduling appointments or logging event timestamps. | `default`, `required` | `{{appointment \| datetime-local}}` |
|
||||
| **color** | A visual color picker that allows the user to select a color or input a standard hex code (e.g., #FF5733). Useful for design and branding prompts. | `default` (hex code), `required` | `{{brand_color \| color:default="#FFFFFF"}}` |
|
||||
| **email** | An input field specifically formatted and validated for email addresses, ensuring the user provides a correctly structured email. | `placeholder`, `default`, `required` | `{{recipient_email \| email:required}}` |
|
||||
| **month** | A picker that allows users to select a specific month and year, without needing to choose a day. Useful for billing cycles, reports, or timelines. | `default`, `required` | `{{billing_month \| month}}` |
|
||||
| **range** | A slider control that allows the user to select a numerical value from within a defined minimum and maximum range. Ideal for satisfaction scores or percentage adjustments. | `min`, `max`, `step`, `default`, `required` | `{{satisfaction \| range:min=1:max=10}}` |
|
||||
| **tel** | An input field designed for telephone numbers. It semantically indicates the expected input type for browsers and devices. | `placeholder`, `default`, `required` | `{{phone_number \| tel}}` |
|
||||
| **time** | A picker for selecting a time. Useful for scheduling meetings, logging events, or setting reminders without an associated date. | `default`, `required` | `{{meeting_time \| time}}` |
|
||||
| **url** | An input field for web addresses (URLs). It helps ensure that the user provides a link, which can be useful for prompts that analyze websites or reference online sources. | `placeholder`, `default`, `required` | `{{website \| url:required}}` |
|
||||
| **map** | **(Experimental)** An interactive map interface that lets users click to select geographic coordinates. This is a powerful tool for location-based prompts. | `default` (e.g., "51.5,-0.09"), `required` | `{{location \| map}}` |
|
||||
|
||||
#### Example Use Cases
|
||||
|
||||
**1. Simple Article Summarizer**
|
||||
**1. Flexible Article Summarizer**
|
||||
|
||||
Create a reusable prompt to summarize any article.
|
||||
Create a reusable prompt where the article content is required but additional parameters are optional.
|
||||
|
||||
* **Command:** `/summarize_article`
|
||||
* **Prompt Content:**
|
||||
```
|
||||
Please summarize the following article in three key bullet points. Be concise and clear.
|
||||
Please summarize the following article. {{article_text | textarea:placeholder="Paste the full text of the article here...":required}}
|
||||
|
||||
Article:
|
||||
{{article_text | textarea:placeholder="Paste the full text of the article here..."}}
|
||||
{{summary_length | select:options=["Brief (3 bullets)","Detailed (5 bullets)","Executive Summary"]:default="Brief (3 bullets)"}}
|
||||
|
||||
{{focus_area | text:placeholder="Any specific aspect to focus on? (optional)"}}
|
||||
|
||||
{{include_quotes | checkbox}} Include key quotes from the article
|
||||
```
|
||||
When you type `/summarize_article`, a modal will appear with a large text area, prompting you to paste the article text.
|
||||
When you type `/summarize_article`, a modal will appear with a required text area for the article, and optional fields for customizing the summary style.
|
||||
|
||||
**2. Advanced Bug Report Generator**
|
||||
|
||||
This prompt acts as a structured form to ensure all necessary details for a bug report are captured.
|
||||
This prompt ensures critical information is captured while allowing optional details.
|
||||
|
||||
* **Command:** `/bug_report`
|
||||
* **Prompt Content:**
|
||||
```
|
||||
Generate a bug report with the following details:
|
||||
|
||||
**Summary:** {{summary | text:placeholder="A brief summary of the issue"}}
|
||||
**Priority:** {{priority | select:options=["High", "Medium", "Low"]:default="Medium"}}
|
||||
**Summary:** {{summary | text:placeholder="A brief summary of the issue":required}}
|
||||
**Priority:** {{priority | select:options=["Critical","High","Medium","Low"]:default="Medium":required}}
|
||||
**Steps to Reproduce:**
|
||||
{{steps | textarea:placeholder="1. Go to...\n2. Click on...\n3. See error..."}}
|
||||
{{steps | textarea:placeholder="1. Go to...\n2. Click on...\n3. See error...":required}}
|
||||
|
||||
**Additional Context:** {{additional_context | textarea:placeholder="Browser version, OS, screenshots, etc. (optional)"}}
|
||||
**Workaround:** {{workaround | textarea:placeholder="Any temporary solutions found (optional)"}}
|
||||
|
||||
Please format this into a clear and complete bug report document.
|
||||
```
|
||||
When used, this prompt generates a form with a text input, a dropdown menu, and two text areas.
|
||||
This creates a form where title, priority, and steps are mandatory, but additional context and workarounds are optional.
|
||||
|
||||
**3. Social Media Post Generator**
|
||||
**3. Social Media Post Generator with Smart Defaults**
|
||||
|
||||
This prompt generates tailored content for different social media platforms.
|
||||
This prompt generates tailored content with required core information and optional customizations.
|
||||
|
||||
* **Command:** `/social_post`
|
||||
* **Prompt Content:**
|
||||
```
|
||||
Generate a social media post for the {{platform}} platform.
|
||||
Generate a social media post for {{platform | select:options=["LinkedIn","Twitter","Facebook","Instagram"]:required}}.
|
||||
|
||||
**Topic:** {{topic | text:placeholder="e.g., New feature launch"}}
|
||||
**Key Message:** {{key_message | textarea:placeholder="What are the essential points to communicate?"}}
|
||||
**Tone of Voice:** {{tone | select:options=["Professional", "Casual", "Humorous", "Inspirational"]:default="Professional"}}
|
||||
**Topic:** {{topic | text:placeholder="e.g., New feature launch":required}}
|
||||
**Key Message:** {{key_message | textarea:placeholder="What are the essential points to communicate?":required}}
|
||||
**Tone of Voice:** {{tone | select:options=["Professional","Casual","Humorous","Inspirational"]:default="Professional"}}
|
||||
**Call to Action:** {{cta | text:placeholder="e.g., 'Learn more', 'Sign up today'"}}
|
||||
**Character Limit:** {{char_limit | number:placeholder="Leave blank for platform default"}}
|
||||
**Include Hashtags:** {{include_hashtags | checkbox:default=true}}
|
||||
|
||||
Please include relevant hashtags.
|
||||
Please create an engaging post optimized for the selected platform.
|
||||
```
|
||||
|
||||
**4. Meeting Minutes Assistant**
|
||||
**4. Meeting Minutes Assistant with Flexible Structure**
|
||||
|
||||
Quickly generate structured meeting minutes by filling out a simple form.
|
||||
Generate structured meeting minutes with required basics and optional details.
|
||||
|
||||
* **Command:** `/meeting_minutes`
|
||||
* **Prompt Content:**
|
||||
```
|
||||
# Meeting Minutes
|
||||
|
||||
**Date:** {{meeting_date | date}}
|
||||
**Time:** {{meeting_time | time}}
|
||||
**Attendees:** {{attendees | text:placeholder="Comma-separated list of names"}}
|
||||
**Date:** {{meeting_date | date:required}}
|
||||
**Time:** {{meeting_time | time:required}}
|
||||
**Meeting Title:** {{title | text:placeholder="e.g., Weekly Team Sync":required}}
|
||||
**Attendees:** {{attendees | text:placeholder="Comma-separated list of names":required}}
|
||||
|
||||
## Agenda / Key Discussion Points
|
||||
{{agenda_items | textarea:placeholder="Paste the agenda or list the key topics discussed."}}
|
||||
{{agenda_items | textarea:placeholder="Paste the agenda or list the key topics discussed.":required}}
|
||||
|
||||
## Decisions Made
|
||||
{{decisions | textarea:placeholder="Key decisions and outcomes (optional)"}}
|
||||
|
||||
## Action Items
|
||||
{{action_items | textarea:placeholder="List each action item, who it is assigned to, and the deadline."}}
|
||||
|
||||
## Next Meeting
|
||||
**Date:** {{next_meeting | date}}
|
||||
**Topics:** {{next_topics | text:placeholder="Items to discuss next time"}}
|
||||
|
||||
Please format the above information into a clean and professional meeting summary.
|
||||
```
|
||||
|
||||
**5. Content Review Template**
|
||||
|
||||
A flexible template for reviewing various types of content.
|
||||
|
||||
* **Command:** `/content_review`
|
||||
* **Prompt Content:**
|
||||
```
|
||||
Please review the following {{content_type | select:options=["Blog Post","Marketing Copy","Documentation","Email","Presentation"]:required}}:
|
||||
|
||||
**Content Title:** {{title | text:required}}
|
||||
**Content:** {{content | textarea:placeholder="Paste the content to be reviewed":required}}
|
||||
|
||||
**Review Focus:** {{focus | select:options=["Grammar & Style","Technical Accuracy","Brand Voice","SEO Optimization","General Feedback"]:default="General Feedback"}}
|
||||
**Target Audience:** {{audience | text:placeholder="Who is this content for?"}}
|
||||
**Specific Concerns:** {{concerns | textarea:placeholder="Any particular areas you'd like me to focus on?"}}
|
||||
**Word Count Target:** {{word_count | number:placeholder="Target word count (if relevant)"}}
|
||||
|
||||
Please provide detailed feedback and suggestions for improvement.
|
||||
```
|
||||
|
||||
### Access Control and Permissions
|
||||
|
||||
Prompt management is controlled by the following permission settings:
|
||||
@@ -182,7 +237,19 @@ Prompt management is controlled by the following permission settings:
|
||||
|
||||
* Use clear, descriptive titles for your prompts
|
||||
* Create intuitive slash commands that reflect the prompt's purpose
|
||||
* For custom variables, use clear names (e.g., `{{your_name}}` instead of `{{var1}}`) and descriptive `placeholder` text to make templates easy to understand.
|
||||
* **Design with flexibility in mind**: Mark only truly essential fields as required, leaving optional fields for enhanced customization
|
||||
* For custom variables, use clear names (e.g., `{{your_name}}` instead of `{{var1}}`) and descriptive `placeholder` text to make templates easy to understand
|
||||
* **Provide sensible defaults** for optional fields where appropriate to speed up form completion
|
||||
* **Use the required flag strategically** - only require information that is absolutely necessary for the prompt to function properly
|
||||
* Document any specific requirements or expected inputs in the prompt description
|
||||
* Test prompts with different variable combinations to ensure they work as intended
|
||||
* Consider access levels carefully when sharing prompts with other users - public sharing means that it will appear automatically for all users when they hit `/` in a chat, so you want to avoid creating too many.
|
||||
* Test prompts with different variable combinations, including scenarios where optional fields are left blank
|
||||
* Consider access levels carefully when sharing prompts with other users - public sharing means that it will appear automatically for all users when they hit `/` in a chat, so you want to avoid creating too many
|
||||
* **Consider user workflows**: Think about which information users will always have versus what they might want to customize occasionally
|
||||
|
||||
### Migration Notes
|
||||
|
||||
If you have existing prompts created before this update, they will continue to work as before. However, note that:
|
||||
|
||||
* All existing variables are now treated as optional by default
|
||||
* If you want to maintain required behavior for critical fields, edit your prompts to add the `:required` flag to those variables
|
||||
* This change provides better user experience by allowing flexible usage of prompt templates
|
||||
|
||||
@@ -720,6 +720,14 @@ The format for the JSON response is strictly:
|
||||
- Description: Enables or disables direct connections.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
#### `TOOL_SERVER_CONNECTIONS`
|
||||
|
||||
- Type: `str` (JSON array)
|
||||
- Default: `[]`
|
||||
- Description: Specifies a JSON array of tool server connection configurations. Each connection should define the necessary parameters to connect to external tool servers that implement the OpenAPI/MCPO protocol. The JSON must be properly formatted or it will fallback to an empty array.
|
||||
- Example: `'[{"name": "example-server", "url": "https://api.example.com", "api_key": "your-key"}]'`
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
### Autocomplete
|
||||
|
||||
#### `ENABLE_AUTOCOMPLETE_GENERATION`
|
||||
@@ -1730,6 +1738,7 @@ Provide a clear and direct response to the user's query, including inline citati
|
||||
- Options:
|
||||
- `character`
|
||||
- `token`
|
||||
- `markdown_header`
|
||||
- Default: `character`
|
||||
- Description: Sets the text splitter for RAG models.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
@@ -1977,6 +1986,18 @@ When enabling `GOOGLE_DRIVE_INTEGRATION`, ensure that you have configured `GOOGL
|
||||
- Description: Enables or disables OneDrive integration.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
#### `ENABLE_ONEDRIVE_PERSONAL`
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `True`
|
||||
- Description: Controls whether the personal OneDrive option appears in the attachment menu. When enabled, users can upload files from their personal Microsoft OneDrive accounts.
|
||||
|
||||
#### `ENABLE_ONEDRIVE_BUSINESS`
|
||||
|
||||
- Type: `bool`
|
||||
- Default: `True`
|
||||
- Description: Controls whether the work/school OneDrive option appears in the attachment menu. When enabled, users can upload files from their organizational OneDrive/SharePoint accounts.
|
||||
|
||||
#### `ONEDRIVE_CLIENT_ID`
|
||||
|
||||
- Type: `str`
|
||||
@@ -2982,6 +3003,35 @@ You must also set `OPENID_PROVIDER_URL` or otherwise logout may not work.
|
||||
- Description: Sets the redirect URI for GitHub OAuth.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
### Feishu
|
||||
|
||||
See https://open.feishu.cn/document/sso/web-application-sso/login-overview
|
||||
|
||||
#### `FEISHU_CLIENT_ID`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Sets the client ID for Feishu OAuth.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
#### `FEISHU_CLIENT_SECRET`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Sets the client secret for Feishu OAuth.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
#### `FEISHU_CLIENT_SCOPE`
|
||||
|
||||
- Type: `str`
|
||||
- Default: `contact:user.base:readonly`
|
||||
- Description: Specifies the scope for Feishu OAuth authentication.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
#### `FEISHU_CLIENT_REDIRECT_URI`
|
||||
|
||||
- Type: `str`
|
||||
- Description: Sets the redirect URI for Feishu OAuth.
|
||||
- Persistence: This environment variable is a `PersistentConfig` variable.
|
||||
|
||||
### OpenID (OIDC)
|
||||
|
||||
#### `OAUTH_CLIENT_ID`
|
||||
|
||||
@@ -24,6 +24,24 @@ volumes:
|
||||
open-webui:
|
||||
```
|
||||
|
||||
### Using Slim Images
|
||||
|
||||
For environments with limited storage or bandwidth, you can use the slim image variant that excludes pre-bundled models:
|
||||
|
||||
```yaml
|
||||
services:
|
||||
openwebui:
|
||||
image: ghcr.io/open-webui/open-webui:main-slim
|
||||
ports:
|
||||
- "3000:8080"
|
||||
volumes:
|
||||
- open-webui:/app/backend/data
|
||||
volumes:
|
||||
open-webui:
|
||||
```
|
||||
|
||||
**Note:** Slim images download required models (whisper, embedding models) on first use, which may result in longer initial startup times but significantly smaller image sizes.
|
||||
|
||||
## Starting the Services
|
||||
|
||||
To start your services, run the following command:
|
||||
|
||||
@@ -10,6 +10,14 @@ Start by pulling the latest Open WebUI Docker image from the GitHub Container Re
|
||||
docker pull ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
### Slim Image Variant
|
||||
|
||||
For environments with limited storage or bandwidth, Open WebUI offers slim image variants that exclude pre-bundled models. These images are significantly smaller but download required models (whisper, embedding models) on first use.
|
||||
|
||||
```bash
|
||||
docker pull ghcr.io/open-webui/open-webui:main-slim
|
||||
```
|
||||
|
||||
## Step 2: Run the Container
|
||||
|
||||
Run the container with default settings. This command includes a volume mapping to ensure persistent data storage.
|
||||
@@ -18,6 +26,12 @@ Run the container with default settings. This command includes a volume mapping
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
|
||||
```
|
||||
|
||||
To use the slim variant instead:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main-slim
|
||||
```
|
||||
|
||||
### Important Flags
|
||||
|
||||
- **Volume Mapping (`-v open-webui:/app/backend/data`)**: Ensures persistent storage of your data. This prevents data loss between container restarts.
|
||||
|
||||
@@ -33,7 +33,7 @@ Passionate about open-source AI? [Join our team →](https://careers.openwebui.c
|
||||
|
||||
|
||||
:::tip
|
||||
**Looking for an [Enterprise Plan](https://docs.openwebui.com/enterprise)?** – **[Speak with Our Sales Team Today!](mailto:sales@openwebui.com)**
|
||||
**Looking for an [Enterprise Plan](https://docs.openwebui.com/enterprise)?** — **[Speak with Our Sales Team Today!](mailto:sales@openwebui.com)**
|
||||
|
||||
Get **enhanced capabilities**, including **custom theming and branding**, **Service Level Agreement (SLA) support**, **Long-Term Support (LTS) versions**, and **more!**
|
||||
:::
|
||||
@@ -60,6 +60,14 @@ docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-
|
||||
docker run -d -p 3000:8080 --gpus all --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:cuda
|
||||
```
|
||||
|
||||
### Slim Image Variants
|
||||
|
||||
For environments with limited storage or bandwidth, Open WebUI offers slim image variants that exclude pre-bundled models. These images are significantly smaller but download required models on first use:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main-slim
|
||||
```
|
||||
|
||||
### Open WebUI Bundled with Ollama
|
||||
|
||||
This installation method uses a single container image that bundles Open WebUI with Ollama, allowing for a streamlined setup via a single command. Choose the appropriate command based on your hardware setup:
|
||||
@@ -94,6 +102,12 @@ If you want to try out the latest bleeding-edge features and are okay with occas
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev
|
||||
```
|
||||
|
||||
For the slim variant of the dev branch:
|
||||
|
||||
```bash
|
||||
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:dev-slim
|
||||
```
|
||||
|
||||
### Updating Open WebUI
|
||||
|
||||
To update Open WebUI container easily, follow these steps:
|
||||
|
||||
@@ -26,4 +26,8 @@ with us, as we'd love to feature it here!
|
||||
|
||||
[Deploying custom Document RAG pipeline with Open-WebUI](https://github.com/Sebulba46/document-RAG-pipeline) (GitHub guide by Sebulba46)
|
||||
|
||||
- Step by step guide to deploy Open-WebUI and pipelines containers and creating your own document RAG with local LLM API.
|
||||
- Step by step guide to deploy Open-WebUI and pipelines containers and creating your own document RAG with local LLM API.
|
||||
|
||||
[Deploy Your Own Open WebUI Interface with HTTPS Security](https://henrynavarro.org/deploy-your-own-open-webui-interface-with-https-security-53a6ea2609d7?sk=a5876acd56b44ea60f10f9b13aa24aee) (Medium article by @hdnh2006)
|
||||
|
||||
- Learn how to deploy Open WebUI 100% secure through https.
|
||||
|
||||
@@ -3,15 +3,15 @@ sidebar_position: 3
|
||||
title: "🧠 Troubleshooting RAG (Retrieval-Augmented Generation)"
|
||||
---
|
||||
|
||||
Retrieval-Augmented Generation (RAG) enables language models to reason over external content—documents, knowledge bases, and more—by retrieving relevant info and feeding it into the model. But when things don’t work as expected (e.g., the model "hallucinates" or misses relevant info), it's often not the model's fault—it's a context issue.
|
||||
Retrieval-Augmented Generation (RAG) enables language models to reason over external content—documents, knowledge bases, and more—by retrieving relevant info and feeding it into the model. But when things don't work as expected (e.g., the model "hallucinates" or misses relevant info), it's often not the model's fault—it's a context issue.
|
||||
|
||||
Let’s break down the common causes and solutions so you can supercharge your RAG accuracy! 🚀
|
||||
Let's break down the common causes and solutions so you can supercharge your RAG accuracy! 🚀
|
||||
|
||||
## Common RAG Issues and How to Fix Them 🛠️
|
||||
|
||||
### 1. The Model "Can’t See" Your Content 👁️❌
|
||||
### 1. The Model "Can't See" Your Content 👁️❌
|
||||
|
||||
This is the most common problem—and it's typically caused by issues during your content ingestion process. The model doesn’t hallucinate because it’s wrong, it hallucinates because it was never given the right content in the first place.
|
||||
This is the most common problem—and it's typically caused by issues during your content ingestion process. The model doesn't hallucinate because it's wrong, it hallucinates because it was never given the right content in the first place.
|
||||
|
||||
✅ Solution: Check your content extraction settings
|
||||
|
||||
@@ -21,7 +21,7 @@ This is the most common problem—and it's typically caused by issues during you
|
||||
- Docling
|
||||
- Custom extractors (depending on your document types)
|
||||
|
||||
📌 Tip: Try uploading a document and preview the extracted content. If it’s blank or missing key sections, you need to adjust your extractor settings or use a different engine.
|
||||
📌 Tip: Try uploading a document and preview the extracted content. If it's blank or missing key sections, you need to adjust your extractor settings or use a different engine.
|
||||
|
||||
---
|
||||
|
||||
@@ -33,33 +33,46 @@ Open WebUI is designed to work with models that have limited context windows by
|
||||
|
||||
- Go to **Admin Settings > Documents**
|
||||
- Either:
|
||||
- 💡 Enable “Bypass Embedding and Retrieval” — This sends full content directly without applying strict retrieval filters.
|
||||
- 🔍 Toggle on “Full Context Mode” — This injects more comprehensive content into the model prompt.
|
||||
- 💡 Enable "Bypass Embedding and Retrieval" — This sends full content directly without applying strict retrieval filters.
|
||||
- 🔍 Toggle on "Full Context Mode" — This injects more comprehensive content into the model prompt.
|
||||
|
||||
📌 Warning: Be mindful of context limits—if your model can’t handle more tokens, it will still get cut off.
|
||||
📌 Warning: Be mindful of context limits—if your model can't handle more tokens, it will still get cut off.
|
||||
|
||||
---
|
||||
|
||||
### 3. Token Limit is Too Short ⏳
|
||||
|
||||
Even if retrieval works, your model might still not process all the content it receives—because it simply can’t.
|
||||
Even if retrieval works, your model might still not process all the content it receives—because it simply can't.
|
||||
|
||||
By default, many models (especially Ollama-hosted LLMs) are limited to a 2048-token context window. That means only a fraction of your retrieved data will actually be used.
|
||||
|
||||
**Why Web Search Especially Needs Larger Context Windows:**
|
||||
Web pages are particularly challenging for small context windows because they contain far more content than typical documents. A single web page often includes:
|
||||
- Main content (the actual information you want)
|
||||
- Navigation menus, headers, and footers
|
||||
- Sidebar content and advertisements
|
||||
- Comments sections and related links
|
||||
- Metadata and embedded scripts
|
||||
|
||||
Even after content extraction and cleaning, web pages easily consume 4,000-8,000+ tokens of context. With a 2048-token limit, you're getting less than half the content, often missing the most relevant information that appears later in the page. Even 4096 tokens is frequently insufficient for comprehensive web content analysis.
|
||||
|
||||
✅ Solutions:
|
||||
|
||||
- 🛠️ Extend the model’s context length:
|
||||
- Navigate to the **Model Editor or Chat Controls**
|
||||
- Modify the context length (e.g., increase to 8192+ tokens if supported)
|
||||
- 🛠️ **For Ollama Models**: Extend the model's context length:
|
||||
- Navigate to: **Admin Panel > Models > Settings** (of the model you want to edit)
|
||||
- Go to **Advanced Parameters**
|
||||
- Modify the context length (e.g., increase to 8192+ or ideally beyond 16000 tokens if supported by your model)
|
||||
|
||||
ℹ️ Note: The 2048-token default is a big limiter. For better RAG results, we recommend using models that support longer contexts.
|
||||
- 🌐 **For OpenAI and Other Integrated Models**: These models typically have their own context limits that cannot be modified through Open WebUI settings. Ensure you're using a model with sufficient context length.
|
||||
|
||||
ℹ️ Note: The 2048-token default is a big limiter for web search. For better RAG results with web content, we strongly recommend using at least 8192 tokens, with 16384+ being ideal for complex web pages.
|
||||
|
||||
✅ Alternative: Use an external LLM with larger context capacity
|
||||
|
||||
- Try GPT-4, GPT-4o, Claude 3, Gemini 1.5, or Mixtral with 8k+ context
|
||||
- Compare performance to Ollama—notice the accuracy difference when more content can be injected!
|
||||
- Compare performance to Ollama—notice the dramatic accuracy difference when more web content can be processed!
|
||||
|
||||
📌 Tip: Stick with external models for better RAG performance in production use cases.
|
||||
📌 Tip: For web search and complex document analysis, stick with models that support 8192+ token contexts in production use cases.
|
||||
|
||||
---
|
||||
|
||||
@@ -80,10 +93,10 @@ Bad embeddings = bad retrieval. If the vector representation of your content is
|
||||
|
||||
### 5. ❌ 400: 'NoneType' object has no attribute 'encode'
|
||||
|
||||
This error indicates a misconfigured or missing embedding model. When Open WebUI tries to create embeddings but doesn’t have a valid model loaded, it can’t process the text—and the result is this cryptic error.
|
||||
This error indicates a misconfigured or missing embedding model. When Open WebUI tries to create embeddings but doesn't have a valid model loaded, it can't process the text—and the result is this cryptic error.
|
||||
|
||||
💥 Cause:
|
||||
- Your embedding model isn’t set up properly.
|
||||
- Your embedding model isn't set up properly.
|
||||
- It might not have downloaded completely.
|
||||
- Or if you're using an external embedding model, it may not be accessible.
|
||||
|
||||
@@ -99,7 +112,7 @@ This error indicates a misconfigured or missing embedding model. When Open WebUI
|
||||
|
||||
## 🧪 Pro Tip: Test with GPT-4o or GPT-4
|
||||
|
||||
If you’re not sure whether the issue is with retrieval, token limits, or embedding—try using GPT-4o temporarily (e.g., via OpenAI API). If the results suddenly become more accurate, it's a strong signal that your local model’s context limit (2048 by default in Ollama) is the bottleneck.
|
||||
If you're not sure whether the issue is with retrieval, token limits, or embedding—try using GPT-4o temporarily (e.g., via OpenAI API). If the results suddenly become more accurate, it's a strong signal that your local model's context limit (2048 by default in Ollama) is the bottleneck.
|
||||
|
||||
- GPT-4o handles larger inputs (128k tokens!)
|
||||
- Provides a great benchmark to evaluate your system's RAG reliability
|
||||
@@ -110,12 +123,12 @@ If you’re not sure whether the issue is with retrieval, token limits, or embed
|
||||
|
||||
| Problem | Fix |
|
||||
|--------|------|
|
||||
| 🤔 Model can’t “see” content | Check document extractor settings |
|
||||
| 🤔 Model can't "see" content | Check document extractor settings |
|
||||
| 🧹 Only part of content used | Enable Full Context Mode or Bypass Embedding |
|
||||
| ⏱ Limited by 2048 token cap | Increase model context length or use large-context LLM |
|
||||
| ⏱ Limited by 2048 token cap | Increase model context length (Admin Panel > Models > Settings > Advanced Parameters for Ollama) or use large-context LLM |
|
||||
| 📉 Inaccurate retrieval | Switch to a better embedding model, then reindex |
|
||||
| Still confused? | Test with GPT-4o and compare outputs |
|
||||
|
||||
---
|
||||
|
||||
By optimizing these areas—extraction, embedding, retrieval, and model context—you can dramatically improve how accurately your LLM works with your documents. Don’t let a 2048-token window or weak retrieval pipeline hold back your AI’s power 🎯.
|
||||
By optimizing these areas—extraction, embedding, retrieval, and model context—you can dramatically improve how accurately your LLM works with your documents. Don't let a 2048-token window or weak retrieval pipeline hold back your AI's power 🎯.
|
||||
|
||||
@@ -3,12 +3,12 @@ sidebar_position: 4
|
||||
title: "🔐 Troubleshooting OAUTH / SSO Issues"
|
||||
---
|
||||
|
||||
OAUTH or Single Sign-On (SSO) lets you secure Open WebUI with modern authentication, but when users encounter login problems, the solution is often simple—if you know where to look. Most of the time, one of these key issues below is the culprit. Here’s how to hunt them down and fix SSO headaches fast! 🚦
|
||||
OAUTH or Single Sign-On (SSO) lets you secure Open WebUI with modern authentication, but when users encounter login problems, the solution is often simple—if you know where to look. Most of the time, one of these key issues below is the culprit. Here's how to hunt them down and fix SSO headaches fast! 🚦
|
||||
|
||||
## Common OAUTH/SSO Issues and How to Fix Them 🛠️
|
||||
|
||||
### 1. WebUI URL Not Configured in Admin Panel 🚪🔒
|
||||
Most OAUTH flows require the application’s external URL (“redirect URI”) so the provider knows where to send users after login. If this is missing, OAUTH won’t be able to complete!
|
||||
Most OAUTH flows require the application's external URL ("redirect URI") so the provider knows where to send users after login. If this is missing, OAUTH won't be able to complete!
|
||||
|
||||
✅ Solution:
|
||||
- Navigate to: **Admin Settings > General**
|
||||
@@ -18,43 +18,341 @@ Most OAUTH flows require the application’s external URL (“redirect URI”) s
|
||||
---
|
||||
|
||||
### 2. Incorrect Environment Variable Configuration 📝🚫
|
||||
This is by far the **most common cause** of OAUTH breakage. If you misspell, omit, or set the wrong environment variable (especially for OIDC/OAUTH config), authentication can’t work.
|
||||
This is by far the **most common cause** of OAUTH breakage. If you misspell, omit, or set the wrong environment variable (especially for OIDC/OAUTH config), authentication can't work.
|
||||
|
||||
**Common Environment Variable Mistakes:**
|
||||
|
||||
#### ❌ Non-Existent Variables People Often Use:
|
||||
- `OIDC_CONFIG` → Use `OPENID_PROVIDER_URL` instead
|
||||
- `WEBUI_OIDC_CLIENT_ID` → Use `OAUTH_CLIENT_ID` instead
|
||||
- `WEBUI_ENABLE_SSO` → Use `ENABLE_OAUTH_SIGNUP` instead
|
||||
- `WEBUI_AUTH_TYPE` → This doesn't exist - configure provider-specific variables instead
|
||||
- `OPENID_CLIENT_ID` → Use `OAUTH_CLIENT_ID` instead
|
||||
- `OPENID_CLIENT_SECRET` → Use `OAUTH_CLIENT_SECRET` instead
|
||||
|
||||
#### ✅ Correct OIDC Variables:
|
||||
```bash
|
||||
# Required for OIDC
|
||||
OAUTH_CLIENT_ID=your_client_id
|
||||
OAUTH_CLIENT_SECRET=your_client_secret
|
||||
OPENID_PROVIDER_URL=https://your-provider/.well-known/openid-configuration
|
||||
ENABLE_OAUTH_SIGNUP=true
|
||||
|
||||
# Optional but recommended
|
||||
OAUTH_PROVIDER_NAME=Your Provider Name
|
||||
OAUTH_SCOPES=openid email profile
|
||||
OPENID_REDIRECT_URI=https://your-domain/oauth/oidc/callback
|
||||
```
|
||||
|
||||
#### ✅ Correct Microsoft Variables:
|
||||
```bash
|
||||
# Use these for Microsoft Entra ID
|
||||
MICROSOFT_CLIENT_ID=your_client_id
|
||||
MICROSOFT_CLIENT_SECRET=your_client_secret
|
||||
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
|
||||
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
|
||||
ENABLE_OAUTH_SIGNUP=true
|
||||
```
|
||||
|
||||
✅ Solutions:
|
||||
- **Always reference the official [environment configuration documentation](https://docs.openwebui.com/getting-started/env-configuration/)** for exact variable names
|
||||
- Double-check your deployment environment:
|
||||
- Ensure all required environment variables are set (see docs for names like `OIDC_CONFIG`, `OAUTH_CLIENT_ID`, etc.)
|
||||
- If self-hosting, confirm these variables are present in your Docker Compose, Kubernetes manifest, or `.env` file.
|
||||
- Restart your backend/app after changing variables so the new values are loaded.
|
||||
- Ensure all required environment variables are set exactly as documented
|
||||
- If self-hosting, confirm these variables are present in your Docker Compose, Kubernetes manifest, or `.env` file
|
||||
- Restart your backend/app after changing variables so the new values are loaded
|
||||
|
||||
📌 Tip: Most OAUTH errors (loops, 401s, unresponsiveness) are due to an environment variable incorrectly set or missing entirely!
|
||||
📌 Tip: Most OAUTH errors (loops, 401s, unresponsiveness) are due to an environment variable incorrectly named, missing entirely, or using outdated variable names!
|
||||
|
||||
---
|
||||
|
||||
### 3. OAUTH Misconfiguration on the Provider Side 🏢🔗
|
||||
Sometimes the issue is with the identity provider (e.g., Google, Okta, Auth0, Azure AD) not aligning with your WebUI’s setup.
|
||||
### 3. Missing Required Variables 🚨⚠️
|
||||
|
||||
#### OPENID_PROVIDER_URL is Mandatory for OIDC
|
||||
Many users forget this critical variable. Without it, OIDC authentication cannot work.
|
||||
|
||||
✅ **For Microsoft Entra ID:**
|
||||
```bash
|
||||
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
✅ **For Google:**
|
||||
```bash
|
||||
OPENID_PROVIDER_URL=https://accounts.google.com/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
✅ **For Authentik:**
|
||||
```bash
|
||||
OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-name/.well-known/openid-configuration
|
||||
```
|
||||
|
||||
#### Other Required Variables by Provider:
|
||||
- **All OAuth providers:** `WEBUI_URL`, `ENABLE_OAUTH_SIGNUP=true`
|
||||
- **Microsoft:** `MICROSOFT_CLIENT_ID`, `MICROSOFT_CLIENT_SECRET`, `MICROSOFT_CLIENT_TENANT_ID`
|
||||
- **Google:** `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
|
||||
- **OIDC:** `OAUTH_CLIENT_ID`, `OAUTH_CLIENT_SECRET`, `OPENID_PROVIDER_URL`
|
||||
|
||||
---
|
||||
|
||||
### 4. Persistent Configuration Conflicts 🔄💾
|
||||
|
||||
**New Issue:** Many users don't realize that OAuth settings are stored in the database after the first launch when `ENABLE_OAUTH_PERSISTENT_CONFIG=true` (default).
|
||||
|
||||
#### Symptoms:
|
||||
- Changes to environment variables don't take effect after restart
|
||||
- Authentication worked once but broke after configuration changes
|
||||
- "No token found in localStorage" errors after reconfiguration
|
||||
|
||||
✅ **Solutions:**
|
||||
1. **For Development/Testing:** Set `ENABLE_OAUTH_PERSISTENT_CONFIG=false` to always read from environment variables
|
||||
2. **For Production:** Either:
|
||||
- Configure settings through Admin Panel instead of environment variables, OR
|
||||
- Temporarily set `ENABLE_OAUTH_PERSISTENT_CONFIG=false`, restart to apply new env vars, then set back to `true`
|
||||
3. **Fresh Start:** Delete the database volume and restart with correct configuration
|
||||
|
||||
📌 **Example for Docker Compose:**
|
||||
```yaml
|
||||
environment:
|
||||
- ENABLE_OAUTH_PERSISTENT_CONFIG=false # Forces reading from env vars
|
||||
- OAUTH_CLIENT_ID=your_client_id
|
||||
- OAUTH_CLIENT_SECRET=your_secret
|
||||
- OPENID_PROVIDER_URL=your_provider_url
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. OAUTH Misconfiguration on the Provider Side 🏢🔗
|
||||
Sometimes the issue is with the identity provider (e.g., Google, Okta, Auth0, Azure AD) not aligning with your WebUI's setup.
|
||||
|
||||
✅ Solutions:
|
||||
- Verify your application is correctly registered with the OAUTH provider. Confirm:
|
||||
- Redirect URIs exactly match your deployed WebUI address
|
||||
- **Redirect URIs exactly match your deployed WebUI address**
|
||||
- OIDC: `https://your-domain/oauth/oidc/callback`
|
||||
- Microsoft: `https://your-domain/oauth/microsoft/callback`
|
||||
- Google: `https://your-domain/oauth/google/callback`
|
||||
- Client ID and secret match the values given in your environment settings
|
||||
- Scopes and allowed grant types (e.g., `authorization_code`) are set as required by Open WebUI
|
||||
- Check the provider’s logs—misconfigured apps will often show clear error messages there.
|
||||
- Check the provider's logs—misconfigured apps will often show clear error messages there
|
||||
|
||||
📌 **Redirect URI Format Examples:**
|
||||
```
|
||||
✅ Correct: https://ai.company.com/oauth/oidc/callback
|
||||
❌ Wrong: https://ai.company.com/oauth/callback/oidc
|
||||
❌ Wrong: https://ai.company.com/callback
|
||||
```
|
||||
|
||||
📌 Tip: When in doubt, recheck your provider registration and regenerate client secrets if needed.
|
||||
|
||||
---
|
||||
|
||||
### 4. Server-Side Caching (A Hidden Trouble Spot!) 🧊🚦
|
||||
A **new and tricky problem**: If you use NGINX (or another reverse proxy) with server-side caching, OAUTH endpoints can misbehave. The result isn’t always a total failure—often, users experience random or “weird” login bugs that are almost impossible to debug.
|
||||
### 6. Server-Side Caching (A Hidden Trouble Spot!) 🧊🚦
|
||||
A **new and tricky problem**: If you use NGINX (or another reverse proxy) with server-side caching, OAUTH endpoints can misbehave. The result isn't always a total failure—often, users experience random or "weird" login bugs that are almost impossible to debug.
|
||||
|
||||
✅ Solutions:
|
||||
- In your NGINX (or proxy) configuration:
|
||||
- Make sure to **exclude** the following endpoints from server-side caching:
|
||||
- `/api`, `/oauth`, `/callback`, `/login`, `/ws`, `/websocket`
|
||||
- Any critical login/auth endpoint must remain uncached!
|
||||
- Reload the proxy config after making changes.
|
||||
- Reload the proxy config after making changes
|
||||
|
||||
📌 Warning: Never cache OAUTH or login endpoints! Caching can “poison” the session or deliver stale tokens, causing bizarre auth errors.
|
||||
**Example NGINX Configuration:**
|
||||
```nginx
|
||||
# Disable caching for login / OAuth / websockets endpoints
|
||||
location ~* ^/(api|oauth|callback|login|ws|websocket) {
|
||||
proxy_no_cache 1;
|
||||
proxy_cache_bypass 1;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "upgrade";
|
||||
proxy_read_timeout 3600s;
|
||||
proxy_send_timeout 3600s;
|
||||
proxy_set_header Accept-Encoding "";
|
||||
}
|
||||
```
|
||||
|
||||
📌 Warning: Never cache OAUTH or login endpoints! Caching can "poison" the session or deliver stale tokens, causing bizarre auth errors.
|
||||
|
||||
---
|
||||
|
||||
### 7. Cookie Configuration Issues 🍪⚙️
|
||||
|
||||
**Common Problem:** Reverse proxy cookie settings can interfere with OAuth authentication, especially the `HttpOnly` and `SameSite` settings.
|
||||
|
||||
#### Symptoms:
|
||||
- "No token found in localStorage" errors
|
||||
- Redirect loops after successful authentication
|
||||
- Authentication works but immediately redirects to login page
|
||||
|
||||
✅ **Solutions:**
|
||||
|
||||
#### For NGINX Proxy Manager:
|
||||
```nginx
|
||||
# Remove or adjust problematic cookie settings
|
||||
# ❌ Problematic:
|
||||
# proxy_cookie_path / "/; Secure; HttpOnly; SameSite=None";
|
||||
|
||||
# ✅ Better:
|
||||
proxy_cookie_flags ~ secure samesite=lax;
|
||||
# or remove cookie manipulation entirely
|
||||
```
|
||||
|
||||
#### Environment Variable Cookie Settings:
|
||||
```bash
|
||||
# Recommended cookie settings for OAuth
|
||||
WEBUI_SESSION_COOKIE_SAME_SITE=lax
|
||||
WEBUI_AUTH_COOKIE_SAME_SITE=lax
|
||||
WEBUI_SESSION_COOKIE_SECURE=true # Set to false if using HTTP
|
||||
WEBUI_AUTH_COOKIE_SECURE=true # Set to false if using HTTP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 8. Network Timeout Issues ⏱️🌐
|
||||
|
||||
**New Issue:** OAuth providers may be slow to respond, causing timeout errors during the authentication handshake.
|
||||
|
||||
#### Symptoms:
|
||||
- `httpcore.ReadTimeout` errors in logs
|
||||
- `CSRF Warning! State not equal in request and response` errors
|
||||
- OAuth login fails intermittently
|
||||
|
||||
✅ **Solutions:**
|
||||
```bash
|
||||
# Increase OAuth timeouts
|
||||
AIOHTTP_CLIENT_TIMEOUT=600 # Very high number is needed here, since model responses that take a lot of time also rely on this timeout variable (e.g. a model that is reasoning for 5+ minutes)
|
||||
AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST=30
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 9. Session State Mismatch (CSRF Errors) 🔐❌
|
||||
|
||||
**Advanced Issue:** Session cookies not being properly maintained across OAuth redirect flow.
|
||||
|
||||
#### Symptoms:
|
||||
- `CSRF Warning! State not equal in request and response`
|
||||
- `mismatching_state` errors in logs
|
||||
- Authentication appears successful but redirects to login
|
||||
|
||||
✅ **Solutions:**
|
||||
|
||||
1. **Check Cookie Domain Configuration:**
|
||||
```bash
|
||||
# Ensure cookies are set for the correct domain
|
||||
WEBUI_URL=https://your-exact-domain.com # Must match exactly - check if you have a different value set in the admin panel
|
||||
```
|
||||
|
||||
2. **Session Configuration:**
|
||||
```bash
|
||||
# Ensure session handling is properly configured
|
||||
WEBUI_SECRET_KEY=your_very_secure_random_key_here
|
||||
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=another_secure_key_here
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 10. Load Balancer and Multi-Instance Issues 🔀⚖️
|
||||
|
||||
**Enterprise Issue:** In multi-instance deployments, OAuth sessions can fail if not properly synchronized.
|
||||
|
||||
#### Required Configuration for Clusters:
|
||||
```bash
|
||||
# Redis for session synchronization (required for multi-instance)
|
||||
REDIS_URL=redis://your-redis:6379/0
|
||||
WEBSOCKET_REDIS_URL=redis://your-redis:6379/0
|
||||
|
||||
# Shared secrets across all instances
|
||||
WEBUI_SECRET_KEY=same_on_all_instances
|
||||
OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=same_on_all_instances
|
||||
|
||||
# WebSocket support for clusters
|
||||
ENABLE_WEBSOCKET_SUPPORT=true
|
||||
WEBSOCKET_MANAGER=redis
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 11. Provider-Specific Configuration Issues 🏢📋
|
||||
|
||||
#### Microsoft Entra ID Common Issues:
|
||||
|
||||
**Problem:** Using generic OIDC variables instead of Microsoft-specific ones.
|
||||
|
||||
✅ **Correct Microsoft Setup:**
|
||||
```bash
|
||||
# Use Microsoft-specific variables, not generic OIDC
|
||||
MICROSOFT_CLIENT_ID=your_azure_app_id
|
||||
MICROSOFT_CLIENT_SECRET=your_azure_app_secret
|
||||
MICROSOFT_CLIENT_TENANT_ID=your_tenant_id
|
||||
MICROSOFT_OAUTH_SCOPE=openid email profile
|
||||
MICROSOFT_REDIRECT_URI=https://your-domain/oauth/microsoft/callback
|
||||
|
||||
# Also required for a working Microsoft setup
|
||||
OPENID_PROVIDER_URL=https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration
|
||||
ENABLE_OAUTH_SIGNUP=true
|
||||
```
|
||||
|
||||
#### Authentik Common Issues:
|
||||
|
||||
**Problem:** Incorrect provider URL format.
|
||||
|
||||
✅ **Correct Authentik Setup:**
|
||||
```bash
|
||||
OAUTH_CLIENT_ID=your_authentik_client_id
|
||||
OAUTH_CLIENT_SECRET=your_authentik_client_secret
|
||||
OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-slug/.well-known/openid-configuration
|
||||
OAUTH_PROVIDER_NAME=Authentik
|
||||
OAUTH_SCOPES=openid email profile
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Advanced Troubleshooting Tips
|
||||
|
||||
### Check Token Storage Method
|
||||
Recent versions of Open WebUI moved from URL-based tokens to cookie-based tokens. If you have authentication issues:
|
||||
|
||||
1. **Clear browser cookies and cache completely**
|
||||
2. **Check browser Developer Tools:**
|
||||
- Look for `oauth_session_id` cookie (new method)
|
||||
- Check for any `oauth_id_token` cookie (legacy method)
|
||||
- Verify cookies have correct domain and path settings
|
||||
|
||||
### Debugging OAuth Flow
|
||||
Enable debug logging and trace the OAuth flow:
|
||||
|
||||
```bash
|
||||
# Enable detailed logging
|
||||
GLOBAL_LOG_LEVEL=DEBUG
|
||||
|
||||
# Check logs for these key steps:
|
||||
# 1. GET /oauth/{provider}/login - Should return 302 redirect
|
||||
# 2. User authenticates with provider
|
||||
# 3. GET /oauth/{provider}/callback?code=... - Should return 200 or redirect
|
||||
# 4. User should be logged in
|
||||
```
|
||||
|
||||
### Database Debugging
|
||||
Check if user accounts are being created:
|
||||
|
||||
```bash
|
||||
# Access your container
|
||||
docker exec -it your-openwebui-container sh
|
||||
|
||||
# Check if users are created (adjust path to your data directory)
|
||||
ls -la /app/backend/data/
|
||||
```
|
||||
|
||||
### Test Without Reverse Proxy
|
||||
If using a reverse proxy, test OAuth directly against Open WebUI:
|
||||
|
||||
1. Temporarily expose Open WebUI port directly
|
||||
2. Update OAuth provider redirect URI to point to direct port
|
||||
3. Test authentication without proxy
|
||||
4. If it works, the issue is in your proxy configuration
|
||||
|
||||
---
|
||||
|
||||
@@ -63,6 +361,12 @@ A **new and tricky problem**: If you use NGINX (or another reverse proxy) with s
|
||||
- Look at backend logs and browser network errors. The first error usually points to the misconfiguration (redirect URI mismatch, missing/invalid variable, provider-side error, or caching).
|
||||
- If unsure which side is the problem, try logging in from an incognito browser window and watch for any blocked or failed requests.
|
||||
|
||||
### Key Log Messages to Watch For:
|
||||
- `OAuth callback error: mismatching_state` → Session/cookie issue
|
||||
- `httpcore.ReadTimeout` → Network timeout issue
|
||||
- `The email or password provided is incorrect` → Often means OAuth completed but session wasn't established
|
||||
- `404` on callback URLs → Redirect URI misconfiguration
|
||||
|
||||
---
|
||||
|
||||
## Summary Checklist ✅
|
||||
@@ -70,11 +374,17 @@ A **new and tricky problem**: If you use NGINX (or another reverse proxy) with s
|
||||
| Problem | Fix |
|
||||
|-------------------------------|------------------------------------------------------------|
|
||||
| 🔗 WebUI URL missing or wrong | Set correct WebUI URL in admin panel |
|
||||
| 📝 Env var typo or missing | Double-check and set all OAUTH/SSO env variables |
|
||||
| 📝 Env var typo or missing | Double-check against official docs - avoid non-existent vars like `OIDC_CONFIG` |
|
||||
| 🚨 Missing OPENID_PROVIDER_URL | Always required for OIDC - set to provider's `.well-known/openid-configuration` |
|
||||
| 🔄 Persistent config conflicts | Set `ENABLE_OAUTH_PERSISTENT_CONFIG=false` or use admin panel |
|
||||
| 🏢 Provider misconfigured | Confirm app registration, URIs & client IDs/secrets |
|
||||
| 🧊 Proxy caching interfering | Exclude OAUTH endpoints from all server-side caches |
|
||||
| Still stuck? | Review logs and test without caches |
|
||||
| 🧊 Proxy caching interfering | Exclude OAuth endpoints from all server-side caches |
|
||||
| 🍪 Cookie configuration issues | Check reverse proxy cookie settings and env vars |
|
||||
| ⏱️ Timeout problems | Increase `AIOHTTP_CLIENT_TIMEOUT` values |
|
||||
| 🔐 CSRF/session issues | Verify `WEBUI_SECRET_KEY` and session configuration |
|
||||
| 🔀 Multi-instance problems | Configure Redis and shared secrets |
|
||||
| Still stuck? | Check debug logs, test without proxy, verify provider setup |
|
||||
|
||||
---
|
||||
|
||||
By carefully configuring BOTH your OAUTH provider and your WebUI environment—and keeping critical login endpoints immune to caching—you’ll eliminate nearly all SSO/OAUTH login problems. Don’t let a typo or a hidden cache block your users from seamless, secure AI access! 🦾
|
||||
By carefully configuring BOTH your OAuth provider and your WebUI environment—and keeping critical login endpoints immune to caching—you'll eliminate nearly all SSO/OAuth login problems. Don't let a typo, missing variable, or a hidden cache block your users from seamless, secure AI access! 🦾
|
||||
|
||||
@@ -145,3 +145,13 @@ We're looking for talented individuals to create videos showcasing Open WebUI's
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
<iframe
|
||||
width="560"
|
||||
height="315"
|
||||
src="https://www.youtube-nocookie.com/embed/CcGrI9YkUJI?si=YGdmDlz268MAxmkn"
|
||||
title="YouTube video player"
|
||||
frameborder="0"
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
|
||||
@@ -3,6 +3,12 @@ sidebar_position: 4
|
||||
title: 🐳 Installing Docker
|
||||
---
|
||||
|
||||
:::info **Looking to install Open WebUI?**
|
||||
|
||||
This page covers Docker installation only. For **Open WebUI installation instructions via Docker**, please visit our [Quick Start Guide](https://docs.openwebui.com/getting-started/quick-start/) which provides comprehensive setup instructions.
|
||||
|
||||
:::
|
||||
|
||||
:::warning
|
||||
This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial.
|
||||
:::
|
||||
@@ -21,7 +27,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI
|
||||
|
||||
1. **Open your terminal.**
|
||||
|
||||
2. **Set up Docker’s apt repository:**
|
||||
2. **Set up Docker's apt repository:**
|
||||
|
||||
```bash
|
||||
sudo apt-get update
|
||||
|
||||
@@ -157,7 +157,7 @@ Open WebUI also supports image generation through the **OpenAI APIs**. This opti
|
||||
|
||||
### Azure OpenAI
|
||||
|
||||
Image generation with a Azure OpenAI Dall-E or GPT-Image is supported with OpenWeb UI. Configure the Image Generation as follows:
|
||||
Image generation with Azure OpenAI Dall-E or GPT-Image is supported with Open WebUI. Configure the Image Generation as follows:
|
||||
|
||||
1. In Open WebUI, navigate to the **Admin Panel** > **Settings** > **Images** menu.
|
||||
2. Set the `Image Generation Engine` field to `Open AI` (Azure OpenAI uses the same syntax as OpenAI).
|
||||
@@ -165,6 +165,13 @@ Image generation with a Azure OpenAI Dall-E or GPT-Image is supported with OpenW
|
||||
4. Configure the API version to the value you find in the settings of the Azure AI Fountry.
|
||||
5. Enter your Azure OpenAI API key.
|
||||
|
||||
:::tip
|
||||
Alternative API endpoint URL tutorial: `https://<endpoint name>.openai.azure.com/openai/deployments/<model name>/` - you can find your endpoint name on https://ai.azure.com/resource/overview, and model name on https://ai.azure.com/resource/deployments.
|
||||
You can also copy Target URI from your deployment detailed page, but remember to delete strings after model name.
|
||||
For example, if your Target URI is `https://test.openai.azure.com/openai/deployments/gpt-image-1/images/generations?api-version=2025-04-01-preview`, the API endpoint URL in Open WebUI should be `https://test.openai.azure.com/openai/deployments/gpt-image-1/`.
|
||||
:::
|
||||
|
||||
=======
|
||||
|
||||
## Image Router
|
||||
|
||||
|
||||
@@ -316,6 +316,50 @@ docker compose up -d
|
||||
On the first run, you must remove `cap_drop: - ALL` from the `docker-compose.yaml` file for the `searxng` service to successfully create `/etc/searxng/uwsgi`.ini. This is necessary because the `cap_drop: - ALL` directive removes all capabilities, including those required for the creation of the `uwsgi.ini` file. After the first run, you should re-add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.
|
||||
:::
|
||||
|
||||
**Configure SearXNG for Open WebUI Integration**
|
||||
|
||||
After starting the container, you need to configure SearXNG to support JSON format queries from Open WebUI:
|
||||
|
||||
1. Stop the container after about 30 seconds to allow initial configuration files to be generated:
|
||||
|
||||
```bash
|
||||
docker compose down
|
||||
```
|
||||
|
||||
2. Navigate to the `./searxng` folder and edit the `settings.yml` file:
|
||||
|
||||
```bash
|
||||
cd searxng
|
||||
```
|
||||
|
||||
3. Open the `settings.yml` file in your preferred text editor and locate the `search` section. Add `json` to the formats list:
|
||||
|
||||
```yaml
|
||||
search:
|
||||
safe_search: 0
|
||||
autocomplete: ""
|
||||
default_lang: ""
|
||||
formats:
|
||||
- html
|
||||
- json # Add this line to enable JSON format support for Open WebUI
|
||||
```
|
||||
|
||||
Alternatively, you can use the following command to automatically add JSON support:
|
||||
|
||||
```bash
|
||||
sed -i '/formats:/,/]/s/html/html\n - json/' searxng/settings.yml
|
||||
```
|
||||
|
||||
4. Save the file and restart the container:
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
:::warning
|
||||
Without adding JSON format support, SearXNG will block queries from Open WebUI and you'll encounter `403 Client Error: Forbidden` errors in your Open WebUI logs.
|
||||
:::
|
||||
|
||||
Alternatively, you can run SearXNG directly using `docker run`:
|
||||
|
||||
```bash
|
||||
|
||||
Reference in New Issue
Block a user