diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 2a97016897..ab94b0156d 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -16,6 +16,7 @@ permissions: id-token: write # Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. + # However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. concurrency: group: "pages" diff --git a/docs/contributing.mdx b/docs/contributing.mdx index 7642a60a7b..179a31efec 100644 --- a/docs/contributing.mdx +++ b/docs/contributing.mdx @@ -61,7 +61,7 @@ Here’s how you can help improve accessibility when you contribute: - **Color Contrast & Visual Indicators**: Use high-contrast colors and ensure visual indicators, like focus states, are clear. You can use tools like [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your changes. - **Alt Text for Images**: Provide descriptive `alt` text for images and icons when they convey meaning, but equally important, if the image convays no information and is decorative in nature, use an empty alt text (`alt=""`). -To test you changes, you can use tools like lighthouse or the accessibility tools in your browser. +To test you changes, you can use tools like lighthouse or the accessibility tools in your browser. Let's make Open WebUI usable for *everyone*. diff --git a/docs/enterprise/index.mdx b/docs/enterprise/index.mdx index 11b40166d6..5145fd411f 100644 --- a/docs/enterprise/index.mdx +++ b/docs/enterprise/index.mdx @@ -7,44 +7,42 @@ import { Testimonals } from "@site/src/components/Testimonals"; :::tip -## Built for Everyone, Backed by the Community +## Built for Everyone, Backed by the Community -Open WebUI is completely free to use as-is, with no restrictions or hidden limits. +Open WebUI is completely free to use as-is, with no restrictions or hidden limits. It is **independently developed** and **sustained** by its users. **Optional** licenses are available to **support** ongoing development while providing **additional benefits** for businesses. ::: +## The AI Platform Powering the World’s Leading Organizations -## The AI Platform Powering the World’s Leading Organizations +In the rapidly advancing AI landscape, staying ahead isn't just a competitive advantage—it’s a necessity. Open WebUI is the **fastest-growing AI platform** designed for **seamless enterprise deployment**, helping organizations leverage cutting-edge AI capabilities with **unmatched efficiency**. -In the rapidly advancing AI landscape, staying ahead isn't just a competitive advantage—it’s a necessity. Open WebUI is the **fastest-growing AI platform** designed for **seamless enterprise deployment**, helping organizations leverage cutting-edge AI capabilities with **unmatched efficiency**. - - -## **Let’s Talk** +## **Let’s Talk** :::info Enterprise licenses and partnership opportunities are available exclusively to registered entities and organizations. At this time, we are unable to accommodate individual users. We appreciate your understanding and interest. -To help us respond quickly and efficiently to your inquiry, **please use your official work email address**—**Personal email accounts (e.g. gmail.com, hotmail.com, icloud.com, etc.) are often flagged by our system** and will not be answered. +To help us respond quickly and efficiently to your inquiry, **please use your official work email address**—**Personal email accounts (e.g., gmail.com, hotmail.com, icloud.com, etc.) are often flagged by our system** and will not be answered. ::: -📧 **sales@openwebui.com** — Send us your deployment **end user count (seats)**, and let’s explore how we can work together! Support available in **English & Korean (한국어), with more languages coming soon!** +📧 **sales@openwebui.com** — Send us your deployment **end user count (seats)**, and let’s explore how we can work together! Support available in **English & Korean (한국어), with more languages coming soon!** -Take your AI strategy to the next level with our **premium enterprise solutions**, crafted for organizations that demand **expert consulting, tailored deployment, and dedicated support.** +Take your AI strategy to the next level with our **premium enterprise solutions**, crafted for organizations that demand **expert consulting, tailored deployment, and dedicated support.** :::warning ### Partnership Guidelines for Agencies -We **carefully select** our partners to maintain the **highest standards** and provide **the best experience** to our community. +We **carefully select** our partners to maintain the **highest standards** and provide **the best experience** to our community. -If you are a **consulting agency**, **AI services provider**, or **reseller**, please **do not** contact our enterprise sales directly. You will **not** get a response from our sales team. Instead, **fill out our partnership interest form**: +If you are a **consulting agency**, **AI services provider**, or **reseller**, please **do not** contact our enterprise sales directly. You will **not** get a response from our sales team. Instead, **fill out our partnership interest form**: -🔗 **[Apply Here](https://forms.gle/SemdgxjFXpHmdCby6)** +🔗 **[Apply Here](https://forms.gle/SemdgxjFXpHmdCby6)** Please understand: @@ -54,14 +52,13 @@ Please understand: - We prioritize mature organizations, companies less than 5 years old are not eligible, except in truly exceptional cases. - Our program is currently at full capacity. We will reach out at our discretion should an opportunity arise. -
**If you have an end-client** who is ready to move forward with us and is committed to purchasing a rebrand (enterprise) license immediately... -Contact us directly with: +Contact us directly with: -- Your agency details -- Client’s company name and official work email domain +- Your agency details +- Client’s company name and official work email domain - The expected number of end users (seats) to be deployed This will help us expedite the process and ensure we can support your client’s needs effectively. @@ -73,80 +70,77 @@ Thank you for understanding and respecting our partnership process. ::: - - - --- - --- -## Why Enterprises Choose Open WebUI +## Why Enterprises Choose Open WebUI -### 🚀 **Faster AI Innovation, No Vendor Lock-In** -Unlike proprietary AI platforms that dictate your roadmap, **Open WebUI puts you in control**. Deploy **on-premise, in a private cloud, or hybrid environments**—without restrictive contracts. +### 🚀 **Faster AI Innovation, No Vendor Lock-In** +Unlike proprietary AI platforms that dictate your roadmap, **Open WebUI puts you in control**. Deploy **on-premise, in a private cloud, or hybrid environments**—without restrictive contracts. -### 🔒 **Enterprise-Grade Security & Compliance** -Security is a business-critical requirement. Open WebUI is built to support **SOC 2, HIPAA, GDPR, FedRAMP, and ISO 27001 compliance**, ensuring enterprise security best practices with **on-premise and air-gapped deployments**. +### 🔒 **Enterprise-Grade Security & Compliance** +Security is a business-critical requirement. Open WebUI is built to support **SOC 2, HIPAA, GDPR, FedRAMP, and ISO 27001 compliance**, ensuring enterprise security best practices with **on-premise and air-gapped deployments**. -### ⚡ **Reliable, Scalable, and Performance-Optimized** -Built for large-scale enterprise deployments with **multi-node high availability**, Open WebUI can be configured to ensure **99.99% uptime**, optimized workloads, and **scalability across regions and business units**. +### ⚡ **Reliable, Scalable, and Performance-Optimized** +Built for large-scale enterprise deployments with **multi-node high availability**, Open WebUI can be configured to ensure **99.99% uptime**, optimized workloads, and **scalability across regions and business units**. -### 💡 **Fully Customizable & Modular** -Customize every aspect of Open WebUI to fit your enterprise’s needs. **White-label, extend, and integrate** seamlessly with **your existing systems**, including **LDAP, Active Directory, and custom AI models**. +### 💡 **Fully Customizable & Modular** +Customize every aspect of Open WebUI to fit your enterprise’s needs. **White-label, extend, and integrate** seamlessly with **your existing systems**, including **LDAP, Active Directory, and custom AI models**. -### 🌍 **Thriving Ecosystem with Continuous Innovation** -With one of the **fastest iteration cycles in AI**, Open WebUI ensures your organization stays ahead with **cutting-edge features** and **continuous updates**—no waiting for long release cycles. +### 🌍 **Thriving Ecosystem with Continuous Innovation** +With one of the **fastest iteration cycles in AI**, Open WebUI ensures your organization stays ahead with **cutting-edge features** and **continuous updates**—no waiting for long release cycles. --- -## **Exclusive Enterprise Features & Services** +## **Exclusive Enterprise Features & Services** -Open WebUI’s enterprise solutions provide mission-critical businesses with **a suite of advanced capabilities and dedicated support**, including: +Open WebUI’s enterprise solutions provide mission-critical businesses with **a suite of advanced capabilities and dedicated support**, including: -### 🔧 **Enterprise-Grade Support & SLAs** -✅ **Priority SLA Support** – **24/7 support — Available in English and Korean (한국어)** with dedicated response times for mission-critical issues. -✅ **Dedicated Account Manager** – A **single point of contact** for guidance, onboarding, and strategy. -✅ **Exclusive Office Hours with Core Engineers** – Directly work with the engineers evolving Open WebUI. +### 🔧 **Enterprise-Grade Support & SLAs** +✅ **Priority SLA Support** – **24/7 support — Available in English and Korean (한국어)** with dedicated response times for mission-critical issues. +✅ **Dedicated Account Manager** – A **single point of contact** for guidance, onboarding, and strategy. +✅ **Exclusive Office Hours with Core Engineers** – Directly work with the engineers evolving Open WebUI. -### ⚙ **Customization & AI Model Optimization** -✅ **Custom Theming & Branding** – White-label Open WebUI to **reflect your enterprise identity**. -✅ **Custom AI Model Integration & Fine-Tuning** – Integrate **proprietary** or **third-party** AI models tailored for your workflows. -✅ **Private Feature Development** – Work directly with our team to **build custom features** specific to your organization’s needs. +### ⚙ **Customization & AI Model Optimization** +✅ **Custom Theming & Branding** – White-label Open WebUI to **reflect your enterprise identity**. +✅ **Custom AI Model Integration & Fine-Tuning** – Integrate **proprietary** or **third-party** AI models tailored for your workflows. +✅ **Private Feature Development** – Work directly with our team to **build custom features** specific to your organization’s needs. -### 🛡️ **Advanced Security & Compliance** -✅ **On-Premise & Air-Gapped Deployments** – Full control over data, hosted in **your infrastructure**. -✅ **Security Hardening & Compliance Audits** – Receive **customized compliance assessments** and configurations. -✅ **Role-Based Access Control (RBAC)** – Enterprise-ready **SSO, LDAP, and IAM** integration. +### 🛡️ **Advanced Security & Compliance** +✅ **On-Premise & Air-Gapped Deployments** – Full control over data, hosted in **your infrastructure**. +✅ **Security Hardening & Compliance Audits** – Receive **customized compliance assessments** and configurations. +✅ **Role-Based Access Control (RBAC)** – Enterprise-ready **SSO, LDAP, and IAM** integration. -### 🏗️ **Operational Reliability & Deployment Services** -✅ **Managed Deployments** – Our team helps you **deploy Open WebUI effortlessly**, whether **on-premise, hybrid, or cloud**. -✅ **Version Stability & Long-Term Maintenance** – Enterprise customers receive **LTS (Long-Term Support) versions** for managed **stability and security** over time. -✅ **Enterprise Backups & Disaster Recovery** – High availability with structured backup plans and rapid recovery strategies. +### 🏗️ **Operational Reliability & Deployment Services** +✅ **Managed Deployments** – Our team helps you **deploy Open WebUI effortlessly**, whether **on-premise, hybrid, or cloud**. +✅ **Version Stability & Long-Term Maintenance** – Enterprise customers receive **LTS (Long-Term Support) versions** for managed **stability and security** over time. +✅ **Enterprise Backups & Disaster Recovery** – High availability with structured backup plans and rapid recovery strategies. -### 📚 **Enterprise Training, Workshops & Consulting** -✅ **AI Training & Enablement** – Expert-led **workshops for your engineering and data science teams**. -✅ **Operational AI Consulting** – On-demand **architecture, optimization, and deployment consulting**. -✅ **Strategic AI Roadmap Planning** – Work with our experts to **define your AI transformation strategy**. +### 📚 **Enterprise Training, Workshops & Consulting** +✅ **AI Training & Enablement** – Expert-led **workshops for your engineering and data science teams**. +✅ **Operational AI Consulting** – On-demand **architecture, optimization, and deployment consulting**. +✅ **Strategic AI Roadmap Planning** – Work with our experts to **define your AI transformation strategy**. --- -## **Keep Open WebUI Thriving: Support Continuous Innovation** +## **Keep Open WebUI Thriving: Support Continuous Innovation** :::tip -Even if you **don’t need an enterprise license**, consider becoming a **sponsor** to help fund continuous development. -It’s an **investment in stability, longevity, and ongoing improvements**. A well-funded Open WebUI means **fewer bugs, fewer security concerns, and a more feature-rich platform** that stays ahead of industry trends. The cost of sponsoring is **a fraction of what it would take to build, maintain, and support an equivalent AI system internally.** +Even if you **don’t need an enterprise license**, consider becoming a **sponsor** to help fund continuous development. + +It’s an **investment in stability, longevity, and ongoing improvements**. A well-funded Open WebUI means **fewer bugs, fewer security concerns, and a more feature-rich platform** that stays ahead of industry trends. The cost of sponsoring is **a fraction of what it would take to build, maintain, and support an equivalent AI system internally.** ::: -You can use Open WebUI for free, no strings attached. However, building, maintaining, supporting, and evolving such a powerful AI platform requires **significant effort, time, and resources**. Infrastructure costs, security updates, continuous improvements, and keeping up with the latest AI advancements all demand **dedicated engineering, operational, and research efforts**. +You can use Open WebUI for free, no strings attached. However, building, maintaining, supporting, and evolving such a powerful AI platform requires **significant effort, time, and resources**. Infrastructure costs, security updates, continuous improvements, and keeping up with the latest AI advancements all demand **dedicated engineering, operational, and research efforts**. If Open WebUI helps your business save time, money, or resources, we **encourage** you to consider supporting its development. As an **independently funded** project, sponsorship enables us to maintain **a fast iteration cycle to keep up with the rapid advancements in AI**. Your support directly contributes to critical features, security enhancements, performance improvements, and integrations that benefit everyone—including **you**. Open WebUI will continue to offer the same feature set without requiring an enterprise license, ensuring **accessibility for all users**. -💙 **[Sponsor Open WebUI](https://github.com/sponsors/tjbck)** – Join our existing backers in keeping Open WebUI thriving. +💙 **[Sponsor Open WebUI](https://github.com/sponsors/tjbck)** – Join our existing backers in keeping Open WebUI thriving. -Whether through **enterprise partnerships, contributions, or financial backing**, your support plays a crucial role in sustaining this powerful AI platform for businesses **worldwide**. +Whether through **enterprise partnerships, contributions, or financial backing**, your support plays a crucial role in sustaining this powerful AI platform for businesses **worldwide**. diff --git a/docs/faq.mdx b/docs/faq.mdx index c560544e31..c4ea4f2951 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -117,7 +117,7 @@ In summary: MCP is supported — as long as the MCP Tool Server is fronted by an To stay informed, you can follow release notes and announcements on our [GitHub Releases page](https://github.com/open-webui/open-webui/releases). -### **Q: Is Open WebUI scalable for large organizations or enterprise deployments?** +### **Q: Is Open WebUI scalable for large organizations or enterprise deployments?** **A:** Yes—**Open WebUI is architected for massive scalability and production readiness.** It’s already trusted in deployments supporting extremely high user counts—**think tens or even hundreds of thousands of seats**—used by universities, multinational enterprises, and major organizations worldwide. @@ -125,7 +125,7 @@ Open WebUI’s stateless, container-first architecture means you’re never bott With the right infrastructure configuration, Open WebUI will effortlessly scale from pilot projects to mission-critical worldwide rollouts. -### **Q: How can I deploy Open WebUI in a highly available, large-scale production environment?** +### **Q: How can I deploy Open WebUI in a highly available, large-scale production environment?** **A:** For organizations with demanding uptime and scale requirements, Open WebUI is designed to plug into modern production environments: @@ -134,9 +134,9 @@ With the right infrastructure configuration, Open WebUI will effortlessly scale - **Integration with enterprise authentication** (like SSO/OIDC/LDAP) for seamless and secure login - **Observability and monitoring** via modern log/metrics tools -If you’re planning a high-availability, enterprise-grade deployment, we recommend reviewing this excellent community resource: +If you’re planning a high-availability, enterprise-grade deployment, we recommend reviewing this excellent community resource: -👉 [The SRE's Guide to High Availability Open WebUI Deployment Architecture](http://taylorwilsdon.medium.com/the-sres-guide-to-high-availability-open-webui-deployment-architecture-2ee42654eced) +👉 [The SRE's Guide to High Availability Open WebUI Deployment Architecture](http://taylorwilsdon.medium.com/the-sres-guide-to-high-availability-open-webui-deployment-architecture-2ee42654eced) *(This provides a strong technical overview and best practices for large-scale Open WebUI architecture.)* Open WebUI is designed from day one to not just handle, but thrive at scale—serving large organizations, universities, and enterprises worldwide. diff --git a/docs/features/banners.md b/docs/features/banners.md index a5f56a54e7..c7576210a5 100644 --- a/docs/features/banners.md +++ b/docs/features/banners.md @@ -4,12 +4,12 @@ title: "🔰 Customizable Banners" --- Overview --------- +--- Open WebUI provides a feature that allows administrators to create customizable banners with persistence in the `config.json` file. These banners can feature options for content, background color (info, warning, error, or success), and dismissibility. Banners are accessible only to logged-in users, ensuring the confidentiality of sensitive information. Configuring Banners through the Admin Panel ---------------------------------------------- +--- To configure banners through the admin panel, follow these steps: @@ -23,7 +23,7 @@ To configure banners through the admin panel, follow these steps: 8. Press `Save` at the bottom of the page to save the banner. Configuring Banners through Environment Variables ------------------------------------------------- +--- Alternatively, you can configure banners through environment variables. To do this, you will need to set the `WEBUI_BANNERS` environment variable with a list of dictionaries in the following format: @@ -34,31 +34,31 @@ Alternatively, you can configure banners through environment variables. To do th For more information on configuring environment variables in Open WebUI, see [Environment Variable Configuration](https://docs.openwebui.com/getting-started/env-configuration#webui_banners). Environment Variable Description ---------------------------------- +--- -* `WEBUI_BANNERS`: - * Type: list of dict - * Default: `[]` - * Description: List of banners to show to users. +- `WEBUI_BANNERS`: + - Type: list of dict + - Default: `[]` + - Description: List of banners to show to users. Banner Options ----------------- +--- -* `id`: Unique identifier for the banner. -* `type`: Background color of the banner (info, success, warning, error). -* `title`: Title of the banner. -* `content`: Content of the banner. -* `dismissible`: Whether the banner is dismissible or not. -* `timestamp`: Timestamp for the banner (optional). +- `id`: Unique identifier for the banner. +- `type`: Background color of the banner (info, success, warning, error). +- `title`: Title of the banner. +- `content`: Content of the banner. +- `dismissible`: Whether the banner is dismissible or not. +- `timestamp`: Timestamp for the banner (optional). FAQ ----- +--- -* Q: Can I configure banners through the admin panel? +- Q: Can I configure banners through the admin panel? A: Yes, you can configure banners through the admin panel by navigating to `Admin Panel` -> `Settings` -> `Interface` and clicking on the `+` icon to add a new banner. -* Q: Can I configure banners through environment variables? +- Q: Can I configure banners through environment variables? A: Yes, you can configure banners through environment variables by setting the `WEBUI_BANNERS` environment variable with a list of dictionaries. -* Q: What is the format for the `WEBUI_BANNERS` environment variable? +- Q: What is the format for the `WEBUI_BANNERS` environment variable? A: The format for the `WEBUI_BANNERS` environment variable is a list of dictionaries with the following keys: `id`, `type`, `title`, `content`, `dismissible`, and `timestamp`. -* Q: Can I make banners dismissible? +- Q: Can I make banners dismissible? A: Yes, you can make banners dismissible by setting the `dismissible` key to `True` in the banner configuration or by toggling dismissibility for a banner within the UI. diff --git a/docs/features/chat-features/chat-params.md b/docs/features/chat-features/chat-params.md index f5605eb965..d4d782bf12 100644 --- a/docs/features/chat-features/chat-params.md +++ b/docs/features/chat-features/chat-params.md @@ -21,8 +21,12 @@ Within Open WebUI, there are three levels to setting a **System Prompt** and **A
Example Use Case -:::tip **Per-chat basis**: + +:::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. + :::
@@ -34,8 +38,12 @@ Suppose a user wants to set a custom system prompt for a specific conversation.
Example Use Case -:::tip **Per-account basis**: + +:::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. + :::
@@ -49,15 +57,20 @@ Suppose a user wants to set their own system prompt for their account. They can
Example Use Case -:::tip **Per-model basis**: + +:::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. + :::
- ## **Optimize System Prompt Settings for Maximum Flexibility** -:::tip **Bonus Tips** +:::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. @@ -65,4 +78,5 @@ Suppose an administrator wants to set a default system prompt for a specific mod - 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**. + ::: diff --git a/docs/features/chat-features/chatshare.md b/docs/features/chat-features/chatshare.md index ef3405d3be..a99d77567d 100644 --- a/docs/features/chat-features/chatshare.md +++ b/docs/features/chat-features/chatshare.md @@ -12,7 +12,9 @@ To enable community sharing, follow these steps: 3. Toggle on **Enable Community Sharing** within the **General** settings tab. :::note + **Note:** Only Admins can toggle the **Enable Community Sharing** option. If this option is toggled off, users and Admins will not see the **Share to Open WebUI Community** option for sharing their chats. Community sharing must be enabled by an Admin for users to share chats to the Open WebUI community. + ::: This will enable community sharing for all users on your Open WebUI instance. @@ -30,16 +32,18 @@ To share a chat: When you select `Share to Open WebUI Community`: -* A new tab will open, allowing you to upload your chat as a snapshot to the Open WebUI community website (https://openwebui.com/chats/upload). -* You can control who can view your uploaded chat by choosing from the following access settings: - * **Private**: Only you can access this chat. - * **Public**: Anyone on the internet can view the messages displayed in the chat snapshot. - * **Public, Full History**: Anyone on the internet can view the full regeneration history of your chat. +- A new tab will open, allowing you to upload your chat as a snapshot to the Open WebUI community website (https://openwebui.com/chats/upload). +- You can control who can view your uploaded chat by choosing from the following access settings: + - **Private**: Only you can access this chat. + - **Public**: Anyone on the internet can view the messages displayed in the chat snapshot. + - **Public, Full History**: Anyone on the internet can view the full regeneration history of your chat. :::note + Note: You can change the permission level of your shared chats on the community platform at any time from your openwebui.com account. **Currently, shared chats on the community website cannot be found through search. However, future updates are planned to allow public chats to be discoverable by the public if their permission is set to `Public` or `Public, Full History`.** + ::: Example of a shared chat to the community platform website: https://openwebui.com/c/iamg30/5e3c569f-905e-4d68-a96d-8a99cc65c90f @@ -50,12 +54,12 @@ When you select `Copy Link`, a unique share link is generated that can be shared **Important Considerations:** -* The shared chat will only include messages that existed at the time the link was created. Any new messages sent within the chat after the link is generated will not be included, unless the link is deleted and updated with a new link. -* The generated share link acts as a static snapshot of the chat at the time the link was generated. -* To view the shared chat, users must: +- The shared chat will only include messages that existed at the time the link was created. Any new messages sent within the chat after the link is generated will not be included, unless the link is deleted and updated with a new link. +- The generated share link acts as a static snapshot of the chat at the time the link was generated. +- To view the shared chat, users must: 1. Have an account on the Open WebUI instance where the link was generated. 2. Be signed in to their account on that instance. -* If a user tries to access the shared link without being signed in, they will be redirected to the login page to log in before they can view the shared chat. +- If a user tries to access the shared link without being signed in, they will be redirected to the login page to log in before they can view the shared chat. ### Viewing Shared Chats @@ -77,10 +81,10 @@ To update a shared chat: The **Share Chat** Modal includes the following options: -* **before**: Opens a new tab to view the previously shared chat from the share link. -* **delete this link**: Deletes the shared link of the chat and presents the initial share chat modal. -* **Share to Open WebUI Community**: Opens a new tab for https://openwebui.com/chats/upload with the chat ready to be shared as a snapshot. -* **Update and Copy Link**: Updates the snapshot of the chat of the previously shared chat link and copies it to your device's clipboard. +- **before**: Opens a new tab to view the previously shared chat from the share link. +- **delete this link**: Deletes the shared link of the chat and presents the initial share chat modal. +- **Share to Open WebUI Community**: Opens a new tab for https://openwebui.com/chats/upload with the chat ready to be shared as a snapshot. +- **Update and Copy Link**: Updates the snapshot of the chat of the previously shared chat link and copies it to your device's clipboard. ### Deleting Shared Chats @@ -95,7 +99,9 @@ To delete a shared chat link: Once deleted, the shared link will no longer be valid, and users will not be able to view the shared chat. :::note + **Note:** Chats shared to the community platform cannot be deleted. To change the access level of a chat shared to the community platform: + ::: 1. Log in to your Open WebUI account on openwebui.com. diff --git a/docs/features/chat-features/conversation-organization.md b/docs/features/chat-features/conversation-organization.md index 3b2d88d06d..54b26288ee 100644 --- a/docs/features/chat-features/conversation-organization.md +++ b/docs/features/chat-features/conversation-organization.md @@ -32,13 +32,16 @@ You can give each folder a unique personality and context. By hovering over a fo ### Example Use Case -:::tip **Creating a 'Python Expert' Project** +:::tip + +**Creating a 'Python Expert' Project** Imagine you are working on a Python project. You can create a folder called "Python Expert". -1. **Edit the folder** and set the System Prompt to something like: `You are an expert Python developer. You provide clean, efficient, and well-documented code. When asked for code, you prioritize clarity and adherence to PEP 8 standards.` -2. **Attach Knowledge** by linking a knowledge base which contains a PDF of your project's technical specification, or a specific library's documentation. -3. **Activate/Select the folder** by clicking on it. -4. Now, any new chat you start will automatically have this expert persona, the context of your documents and is saved within the folder, ensuring you get highly relevant and specialized assistance for your project. +1. **Edit the folder** and set the System Prompt to something like: `You are an expert Python developer. You provide clean, efficient, and well-documented code. When asked for code, you prioritize clarity and adherence to PEP 8 standards.` +2. **Attach Knowledge** by linking a knowledge base which contains a PDF of your project's technical specification, or a specific library's documentation. +3. **Activate/Select the folder** by clicking on it. +4. Now, any new chat you start will automatically have this expert persona, the context of your documents and is saved within the folder, ensuring you get highly relevant and specialized assistance for your project. + ::: ## Tagging Conversations @@ -51,6 +54,9 @@ Tags provide an additional layer of organization by allowing you to label conver ### Example Use Case -:::tip **Tagging by Topic** +:::tip + +**Tagging by Topic** If you frequently discuss certain topics, such as "marketing" or "development," you can tag conversations with these terms. Later, when you search for a specific tag, all relevant conversations will be quickly accessible. + ::: diff --git a/docs/features/chat-features/url-params.md b/docs/features/chat-features/url-params.md index b9af303eea..de1f41bdda 100644 --- a/docs/features/chat-features/url-params.md +++ b/docs/features/chat-features/url-params.md @@ -11,17 +11,17 @@ The following table lists the available URL parameters, their function, and exam | **Parameter** | **Description** | **Example** | |-----------------------|-----------------------------------------------------------------------------------|----------------------------------| -| `models` | Specifies the models to be used, as a comma-separated list. | `/?models=model1,model2` | -| `model` | Specifies a single model to be used for the chat session. | `/?model=model1` | -| `youtube` | Specifies a YouTube video ID to be transcribed within the chat. | `/?youtube=VIDEO_ID` | +| `models` | Specifies the models to be used, as a comma-separated list. | `/?models=model1,model2` | +| `model` | Specifies a single model to be used for the chat session. | `/?model=model1` | +| `youtube` | Specifies a YouTube video ID to be transcribed within the chat. | `/?youtube=VIDEO_ID` | | `load-url` | Specifies a Website URL to be fetched and uploaded as a document within the chat. | `/?load-url=https://google.com` | -| `web-search` | Enables web search functionality if set to `true`. | `/?web-search=true` | -| `tools` or `tool-ids` | Specifies a comma-separated list of tool IDs to activate in the chat. | `/?tools=tool1,tool2` | -| `call` | Enables a call overlay if set to `true`. | `/?call=true` | -| `q` | Sets an initial query or prompt for the chat. | `/?q=Hello%20there` | -| `temporary-chat` | Marks the chat as temporary if set to `true`, for one-time sessions. | `/?temporary-chat=true` | -| `code-interpreter` | Enables the code interpreter feature if set to `true`. | `/?code-interpreter=true` | -| `image-generation` | Enables the image generation feature if set to `true`. | `/?image-generation=true` | +| `web-search` | Enables web search functionality if set to `true`. | `/?web-search=true` | +| `tools` or `tool-ids` | Specifies a comma-separated list of tool IDs to activate in the chat. | `/?tools=tool1,tool2` | +| `call` | Enables a call overlay if set to `true`. | `/?call=true` | +| `q` | Sets an initial query or prompt for the chat. | `/?q=Hello%20there` | +| `temporary-chat` | Marks the chat as temporary if set to `true`, for one-time sessions. | `/?temporary-chat=true` | +| `code-interpreter` | Enables the code interpreter feature if set to `true`. | `/?code-interpreter=true` | +| `image-generation` | Enables the image generation feature if set to `true`. | `/?image-generation=true` | ### 1. **Models and Model Selection** @@ -96,8 +96,12 @@ The following table lists the available URL parameters, their function, and exam
Example Use Case -:::tip **Temporary Chat Session** + +:::tip + +**Temporary Chat Session** Suppose a user wants to initiate a quick chat session without saving the history. They can do so by setting `temporary-chat=true` in the URL. This provides a disposable chat environment ideal for one-time interactions. + :::
diff --git a/docs/features/code-execution/artifacts.md b/docs/features/code-execution/artifacts.md index 917d0797fb..d2e5e65243 100644 --- a/docs/features/code-execution/artifacts.md +++ b/docs/features/code-execution/artifacts.md @@ -3,7 +3,6 @@ sidebar_position: 1 title: "🏺 Artifacts" --- - # What are Artifacts and how do I use them in Open WebUI? Artifacts in Open WebUI are an innovative feature inspired by Claude.AI's Artifacts, allowing you to interact with significant and standalone content generated by an LLM within a chat. They enable you to view, modify, build upon, or reference substantial pieces of content separately from the main conversation, making it easier to work with complex outputs and ensuring that you can revisit important information later. @@ -14,10 +13,10 @@ Open WebUI creates an Artifact when the generated content meets specific criteri 1. **Renderable**: To be displayed as an Artifact, the content must be in a format that Open WebUI supports for rendering. This includes: -* Single-page HTML websites -* Scalable Vector Graphics (SVG) images -* Complete webpages, which include HTML, Javascript, and CSS all in the same Artifact. Do note that HTML is required if generating a complete webpage. -* ThreeJS Visualizations and other JavaScript visualization libraries such as D3.js. +- Single-page HTML websites +- Scalable Vector Graphics (SVG) images +- Complete webpages, which include HTML, Javascript, and CSS all in the same Artifact. Do note that HTML is required if generating a complete webpage. +- ThreeJS Visualizations and other JavaScript visualization libraries such as D3.js. Other content types like Documents (Markdown or Plain Text), Code snippets, and React components are not rendered as Artifacts by Open WebUI. @@ -29,39 +28,39 @@ To use artifacts in Open WebUI, a model must provide content that triggers the r When Open WebUI creates an Artifact, you'll see the content displayed in a dedicated Artifacts window to the right side of the main chat. Here's how to interact with Artifacts: -* **Editing and iterating**: Ask an LLM within the chat to edit or iterate on the content, and these updates will be displayed directly in the Artifact window. You can switch between versions using the version selector at the bottom left of the Artifact. Each edit creates a new version, allowing you to track changes using the version selector. -* **Updates**: Open WebUI may update an existing Artifact based on your messages. The Artifact window will display the latest content. -* **Actions**: Access additional actions for the Artifact, such as copying the content or opening the artifact in full screen, located in the lower right corner of the Artifact. +- **Editing and iterating**: Ask an LLM within the chat to edit or iterate on the content, and these updates will be displayed directly in the Artifact window. You can switch between versions using the version selector at the bottom left of the Artifact. Each edit creates a new version, allowing you to track changes using the version selector. +- **Updates**: Open WebUI may update an existing Artifact based on your messages. The Artifact window will display the latest content. +- **Actions**: Access additional actions for the Artifact, such as copying the content or opening the artifact in full screen, located in the lower right corner of the Artifact. ## Editing Artifacts 1. **Targeted Updates**: Describe what you want changed and where. For example: -* "Change the color of the bar in the chart from blue to red." -* "Update the title of the SVG image to 'New Title'." +- "Change the color of the bar in the chart from blue to red." +- "Update the title of the SVG image to 'New Title'." 2. **Full Rewrites**: Request major changes affecting most of the content for substantial restructuring or multiple section updates. For example: -* "Rewrite this single-page HTML website to be a landing page instead." -* "Redesign this SVG so that it's animated using ThreeJS." +- "Rewrite this single-page HTML website to be a landing page instead." +- "Redesign this SVG so that it's animated using ThreeJS." **Best Practices**: -* Be specific about which part of the Artifact you want to change. -* Reference unique identifying text around your desired change for targeted updates. -* Consider whether a small update or full rewrite is more appropriate for your needs. +- Be specific about which part of the Artifact you want to change. +- Reference unique identifying text around your desired change for targeted updates. +- Consider whether a small update or full rewrite is more appropriate for your needs. ## Use Cases Artifacts in Open WebUI enable various teams to create high-quality work products quickly and efficiently. Here are some examples tailored to our platform: -* **Designers**: - * Create interactive SVG graphics for UI/UX design. - * Design single-page HTML websites or landing pages. -* **Developers**: Create simple HTML prototypes or generate SVG icons for projects. -* **Marketers**: - * Design campaign landing pages with performance metrics. - * Create SVG graphics for ad creatives or social media posts. +- **Designers**: + - Create interactive SVG graphics for UI/UX design. + - Design single-page HTML websites or landing pages. +- **Developers**: Create simple HTML prototypes or generate SVG icons for projects. +- **Marketers**: + - Design campaign landing pages with performance metrics. + - Create SVG graphics for ad creatives or social media posts. ## Examples of Projects you can create with Open WebUI's Artifacts @@ -69,35 +68,35 @@ Artifacts in Open WebUI enable various teams and individuals to create high-qual 1. **Interactive Visualizations** -* Components used: ThreeJS, D3.js, and SVG -* Benefits: Create immersive data stories with interactive visualizations. Open WebUI's Artifacts enable you to switch between versions, making it easier to test different visualization approaches and track changes. +- Components used: ThreeJS, D3.js, and SVG +- Benefits: Create immersive data stories with interactive visualizations. Open WebUI's Artifacts enable you to switch between versions, making it easier to test different visualization approaches and track changes. Example Project: Build an interactive line chart using ThreeJS to visualize stock prices over time. Update the chart's colors and scales in separate versions to compare different visualization strategies. 2. **Single-Page Web Applications** -* Components used: HTML, CSS, and JavaScript -* Benefits: Develop single-page web applications directly within Open WebUI. Edit and iterate on the content using targeted updates and full rewrites. +- Components used: HTML, CSS, and JavaScript +- Benefits: Develop single-page web applications directly within Open WebUI. Edit and iterate on the content using targeted updates and full rewrites. Example Project: Design a to-do list app with a user interface built using HTML and CSS. Use JavaScript to add interactive functionality. Update the app's layout and UI/UX using targeted updates and full rewrites. 3. **Animated SVG Graphics** -* Components used: SVG and ThreeJS -* Benefits: Create engaging animated SVG graphics for marketing campaigns, social media, or web design. Open WebUI's Artifacts enable you to edit and iterate on the graphics in a single window. +- Components used: SVG and ThreeJS +- Benefits: Create engaging animated SVG graphics for marketing campaigns, social media, or web design. Open WebUI's Artifacts enable you to edit and iterate on the graphics in a single window. Example Project: Design an animated SVG logo for a company brand. Use ThreeJS to add animation effects and Open WebUI's targeted updates to refine the logo's colors and design. 4. **Webpage Prototypes** -* Components used: HTML, CSS, and JavaScript -* Benefits: Build and test webpage prototypes directly within Open WebUI. Switch between versions to compare different design approaches and refine the prototype. +- Components used: HTML, CSS, and JavaScript +- Benefits: Build and test webpage prototypes directly within Open WebUI. Switch between versions to compare different design approaches and refine the prototype. Example Project: Develop a prototype for a new e-commerce website using HTML, CSS, and JavaScript. Use Open WebUI's targeted updates to refines the navigation, layout, and UI/UX. 5. **Interactive Storytelling** -* Components used: HTML, CSS, and JavaScript -* Benefits: Create interactive stories with scrolling effects, animations, and other interactive elements. Open WebUI's Artifacts enable you to refine the story and test different versions. +- Components used: HTML, CSS, and JavaScript +- Benefits: Create interactive stories with scrolling effects, animations, and other interactive elements. Open WebUI's Artifacts enable you to refine the story and test different versions. Example Project: Build an interactive story about a company's history, using scrolling effects and animations to engage the reader. Use targeted updates to refine the story's narrative and Open WebUI's version selector to test different versions. diff --git a/docs/features/code-execution/mermaid.md b/docs/features/code-execution/mermaid.md index b54410856c..c57ef5b1c3 100644 --- a/docs/features/code-execution/mermaid.md +++ b/docs/features/code-execution/mermaid.md @@ -13,8 +13,8 @@ Open WebUI supports rendering of visually appealing MermaidJS diagrams, flowchar To generate a MermaidJS diagram, simply ask an LLM within any chat to create a diagram or chart using MermaidJS. For example, you can ask the LLM to: -* "Create a flowchart for a simple decision-making process for me using Mermaid. Explain how the flowchart works." -* "Use Mermaid to visualize a decision tree to determine whether it's suitable to go for a walk outside." +- "Create a flowchart for a simple decision-making process for me using Mermaid. Explain how the flowchart works." +- "Use Mermaid to visualize a decision tree to determine whether it's suitable to go for a walk outside." Note that for the LLM's response to be rendered correctly, it must begin with the word `mermaid` followed by the MermaidJS code. You can reference the [MermaidJS documentation](https://mermaid.js.org/intro/) to ensure the syntax is correct and provide structured prompts to the LLM to guide it towards generating better MermaidJS syntax. @@ -28,8 +28,8 @@ If the model generates MermaidJS syntax, but the visualization does not render, Once your visualization is displayed, you can: -* Zoom in and out to examine it more closely. -* Copy the original MermaidJS code used to generate the visualization by clicking the copy button at the top-right corner of the display area. +- Zoom in and out to examine it more closely. +- Copy the original MermaidJS code used to generate the visualization by clicking the copy button at the top-right corner of the display area. ### Example diff --git a/docs/features/code-execution/python.md b/docs/features/code-execution/python.md index 12d8574b64..ddedd1f97d 100644 --- a/docs/features/code-execution/python.md +++ b/docs/features/code-execution/python.md @@ -17,16 +17,16 @@ The Open WebUI frontend includes a self-contained WASM (WebAssembly) Python envi Pyodide code execution is configured to load only packages configured in scripts/prepare-pyodide.js and then added to "CodeBlock.svelte". The following Pyodide packages are currently supported in Open WebUI: -* micropip -* packaging -* requests -* beautifulsoup4 -* numpy -* pandas -* matplotlib -* scikit-learn -* scipy -* regex +- micropip +- packaging +- requests +- beautifulsoup4 +- numpy +- pandas +- matplotlib +- scikit-learn +- scipy +- regex These libraries can be used to perform various tasks, such as data manipulation, machine learning, and web scraping. If the package you're wanting to run is not compiled inside of the Pyodide we ship with Open WebUIm, the package will not be able to be used. @@ -36,13 +36,13 @@ To execute Python code, ask an LLM within a chat to write a Python script for yo ## Tips for Using Python Code Execution -* When writing Python code, keep in mind that the code would be running in a Pyodide environment when executed. You can inform the LLM of this by mentioning "Pyodide environment" when asking for code. -* Research the Pyodide documentation to understand the capabilities and limitations of the environment. -* Experiment with different libraries and scripts to explore the possibilities of Python code execution in Open WebUI. +- When writing Python code, keep in mind that the code would be running in a Pyodide environment when executed. You can inform the LLM of this by mentioning "Pyodide environment" when asking for code. +- Research the Pyodide documentation to understand the capabilities and limitations of the environment. +- Experiment with different libraries and scripts to explore the possibilities of Python code execution in Open WebUI. ## Pyodide Documentation -* [Pyodide Documentation](https://pyodide.org/en/stable/) +- [Pyodide Documentation](https://pyodide.org/en/stable/) ## Code Example @@ -52,7 +52,7 @@ Here is an example of a simple Python script that can be executed using Pyodide: import pandas as pd # Create a sample DataFrame -data = {'Name': ['John', 'Anna', 'Peter'], +data = {'Name': ['John', 'Anna', 'Peter'], 'Age': [28, 24, 35]} df = pd.DataFrame(data) diff --git a/docs/features/document-extraction/apachetika.md b/docs/features/document-extraction/apachetika.md index 59ccdd6e31..8830564572 100644 --- a/docs/features/document-extraction/apachetika.md +++ b/docs/features/document-extraction/apachetika.md @@ -4,7 +4,9 @@ title: "🪶 Apache Tika Extraction" --- :::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. + ::: ## 🪶 Apache Tika Extraction @@ -12,14 +14,14 @@ This tutorial is a community contribution and is not supported by the Open WebUI This documentation provides a step-by-step guide to integrating Apache Tika with Open WebUI. Apache Tika is a content analysis toolkit that can be used to detect and extract metadata and text content from over a thousand different file types. All of these file types can be parsed through a single interface, making Tika useful for search engine indexing, content analysis, translation, and much more. Prerequisites ------------- +--- -* Open WebUI instance -* Docker installed on your system -* Docker network set up for Open WebUI +- Open WebUI instance +- Docker installed on your system +- Docker network set up for Open WebUI Integration Steps ----------------- +--- ### Step 1: Create a Docker Compose File or Run the Docker Command for Apache Tika @@ -62,15 +64,15 @@ Note that if you choose to use the Docker run command, you'll need to specify th To use Apache Tika as the context extraction engine in Open WebUI, follow these steps: -* Log in to your Open WebUI instance. -* Navigate to the `Admin Panel` settings menu. -* Click on `Settings`. -* Click on the `Documents` tab. -* Change the `Default` content extraction engine dropdown to `Tika`. -* Update the context extraction engine URL to `http://tika:9998`. -* Save the changes. +- Log in to your Open WebUI instance. +- Navigate to the `Admin Panel` settings menu. +- Click on `Settings`. +- Click on the `Documents` tab. +- Change the `Default` content extraction engine dropdown to `Tika`. +- Update the context extraction engine URL to `http://tika:9998`. +- Save the changes. - Verifying Apache Tika in Docker +Verifying Apache Tika in Docker ===================================== To verify that Apache Tika is working correctly in a Docker environment, you can follow these steps: @@ -145,10 +147,10 @@ Instructions to run the script: ### Prerequisites -* Python 3.x must be installed on your system -* `requests` library must be installed (you can install it using pip: `pip install requests`) -* Apache Tika Docker container must be running (use `docker run -p 9998:9998 apache/tika` command) -* Replace `"test.txt"` with the path to the file you want to send to Apache Tika +- Python 3.x must be installed on your system +- `requests` library must be installed (you can install it using pip: `pip install requests`) +- Apache Tika Docker container must be running (use `docker run -p 9998:9998 apache/tika` command) +- Replace `"test.txt"` with the path to the file you want to send to Apache Tika ### Running the Script @@ -158,29 +160,33 @@ Instructions to run the script: 4. Run the script using the following command: `python verify_tika.py` 5. The script will output a message indicating whether Apache Tika is working correctly +:::note + Note: If you encounter any issues, ensure that the Apache Tika container is running correctly and that the file is being sent to the correct URL. +::: + ### Conclusion By following these steps, you can verify that Apache Tika is working correctly in a Docker environment. You can test the setup by sending a file for analysis, verifying the server is running with a GET request, or use a script to automate the process. If you encounter any issues, ensure that the Apache Tika container is running correctly and that the file is being sent to the correct URL. Troubleshooting --------------- +--- -* Make sure the Apache Tika service is running and accessible from the Open WebUI instance. -* Check the Docker logs for any errors or issues related to the Apache Tika service. -* Verify that the context extraction engine URL is correctly configured in Open WebUI. +- Make sure the Apache Tika service is running and accessible from the Open WebUI instance. +- Check the Docker logs for any errors or issues related to the Apache Tika service. +- Verify that the context extraction engine URL is correctly configured in Open WebUI. Benefits of Integration ----------------------- +--- Integrating Apache Tika with Open WebUI provides several benefits, including: -* **Improved Metadata Extraction**: Apache Tika's advanced metadata extraction capabilities can help you extract accurate and relevant data from your files. -* **Support for Multiple File Formats**: Apache Tika supports a wide range of file formats, making it an ideal solution for organizations that work with diverse file types. -* **Enhanced Content Analysis**: Apache Tika's advanced content analysis capabilities can help you extract valuable insights from your files. +- **Improved Metadata Extraction**: Apache Tika's advanced metadata extraction capabilities can help you extract accurate and relevant data from your files. +- **Support for Multiple File Formats**: Apache Tika supports a wide range of file formats, making it an ideal solution for organizations that work with diverse file types. +- **Enhanced Content Analysis**: Apache Tika's advanced content analysis capabilities can help you extract valuable insights from your files. Conclusion ----------- +--- Integrating Apache Tika with Open WebUI is a straightforward process that can improve the metadata extraction capabilities of your Open WebUI instance. By following the steps outlined in this documentation, you can easily set up Apache Tika as a context extraction engine for Open WebUI. diff --git a/docs/features/document-extraction/docling.md b/docs/features/document-extraction/docling.md index 01f06f6618..240b6e2381 100644 --- a/docs/features/document-extraction/docling.md +++ b/docs/features/document-extraction/docling.md @@ -4,7 +4,9 @@ title: "🐤 Docling Document Extraction" --- :::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. + ::: ## 🐤 Docling Document Extraction @@ -12,14 +14,14 @@ This tutorial is a community contribution and is not supported by the Open WebUI This documentation provides a step-by-step guide to integrating Docling with Open WebUI. Docling is a document processing library designed to transform a wide range of file formats—including PDFs, Word documents, spreadsheets, HTML, and images—into structured data such as JSON or Markdown. With built-in support for layout detection, table parsing, and language-aware processing, Docling streamlines document preparation for AI applications like search, summarization, and retrieval-augmented generation, all through a unified and extensible interface. Prerequisites ------------- +--- -* Open WebUI instance -* Docker installed on your system -* Docker network set up for Open WebUI +- Open WebUI instance +- Docker installed on your system +- Docker network set up for Open WebUI Integration Steps ----------------- +--- ### Step 1: Run the Docker Command for Docling-Serve @@ -28,31 +30,32 @@ docker run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true quay.io/docling-project/ ``` *With GPU support: + ```bash docker run --gpus all -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=true quay.io/docling-project/docling-serve-cu124 ``` ### Step 2: Configure Open WebUI to use Docling -* Log in to your Open WebUI instance. -* Navigate to the `Admin Panel` settings menu. -* Click on `Settings`. -* Click on the `Documents` tab. -* Change the `Default` content extraction engine dropdown to `Docling`. -* Update the context extraction engine URL to `http://host.docker.internal:5001`. -* Save the changes. +- Log in to your Open WebUI instance. +- Navigate to the `Admin Panel` settings menu. +- Click on `Settings`. +- Click on the `Documents` tab. +- Change the `Default` content extraction engine dropdown to `Docling`. +- Update the context extraction engine URL to `http://host.docker.internal:5001`. +- Save the changes. ### (optional) Step 3: Configure Docling's picture description features -* on the `Documents` tab: -* Activate `Describe Pictures in Documents` button. -* Below, choose a description mode: `local` or `API` - * `local`: vision model will run in the same context as Docling itself - * `API`: Docling will make a call to an external service/container (i.e. Ollama) -* fill in an **object value** as described at https://github.com/docling-project/docling-serve/blob/main/docs/usage.md#picture-description-options -* Save the changes. +- on the `Documents` tab: +- Activate `Describe Pictures in Documents` button. +- Below, choose a description mode: `local` or `API` + - `local`: vision model will run in the same context as Docling itself + - `API`: Docling will make a call to an external service/container (i.e. Ollama) +- fill in an **object value** as described at https://github.com/docling-project/docling-serve/blob/main/docs/usage.md#picture-description-options +- Save the changes. - #### Make sure the object value is a valid JSON! Working examples below: + #### Make sure the object value is a valid JSON! Working examples below ![image](https://github.com/user-attachments/assets/f6524949-fb47-4686-9c81-6ab8fdda6db1) @@ -97,12 +100,12 @@ This command starts the Docling container and maps port 5001 from the container ### 2. Verify the Server is Running -* Go to `http://127.0.0.1:5001/ui/` -* The URL should lead to a UI to use Docling +- Go to `http://127.0.0.1:5001/ui/` +- The URL should lead to a UI to use Docling ### 3. Verify the Integration -* You can try uploading some files via the UI and it should return output in MD format or your desired format +- You can try uploading some files via the UI and it should return output in MD format or your desired format ### Conclusion diff --git a/docs/features/document-extraction/index.md b/docs/features/document-extraction/index.md index 9d0184c873..6661d16cf5 100644 --- a/docs/features/document-extraction/index.md +++ b/docs/features/document-extraction/index.md @@ -10,12 +10,14 @@ Open WebUI provides powerful document extraction capabilities that allow you to ## What is Document Extraction? Document extraction refers to the process of automatically identifying and extracting text and data from various file formats, including: + - PDFs (both text-based and scanned) - Images containing text - Handwritten documents - And more With proper document extraction, Open WebUI can help you: + - Convert image-based documents to searchable text - Preserve document structure and layout information - Extract data in structured formats for further processing @@ -26,4 +28,3 @@ With proper document extraction, Open WebUI can help you: Open WebUI supports multiple document extraction engines to accommodate different needs and document types. Each extraction method has its own strengths and is suitable for different scenarios. Explore the documentation for each available extraction method to learn how to set it up and use it effectively with your Open WebUI instance. - diff --git a/docs/features/document-extraction/mistral-ocr.md b/docs/features/document-extraction/mistral-ocr.md index 237c6196e7..68475f7260 100644 --- a/docs/features/document-extraction/mistral-ocr.md +++ b/docs/features/document-extraction/mistral-ocr.md @@ -4,7 +4,9 @@ title: "👁️ Mistral OCR" --- :::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. + ::: ## 👁️ Mistral OCR @@ -12,41 +14,40 @@ This tutorial is a community contribution and is not supported by the Open WebUI This documentation provides a step-by-step guide to integrating Mistral OCR with Open WebUI. Mistral OCR is an optical character recognition library designed to extract text from a variety of image-based file formats—including scanned PDFs, images, and handwritten documents—into structured data such as JSON or plain text. With advanced support for multilingual text recognition, layout analysis, and handwriting interpretation, Mistral OCR simplifies the process of digitizing and processing documents for AI applications like search, summarization, and data extraction, all through a robust and customizable interface. Prerequisites ------------- +--- -* Open WebUI instance -* Mistral AI account +- Open WebUI instance +- Mistral AI account Integration Steps ----------------- +--- ### Step 1: Sign Up or Login to Mistral AI console -* Go to `https://console.mistral.ai` -* Follow the instructions as instructed on the process -* After successful authorization, you should be welcomed to the Console Home +- Go to `https://console.mistral.ai` +- Follow the instructions as instructed on the process +- After successful authorization, you should be welcomed to the Console Home ### Step 2: Generate an API key -* Go to `API Keys` or `https://console.mistral.ai/api-keys` -* Create a new key and make sure to copy it +- Go to `API Keys` or `https://console.mistral.ai/api-keys` +- Create a new key and make sure to copy it ### Step 3: Configure Open WebUI to use Mistral OCR -* Log in to your Open WebUI instance. -* Navigate to the `Admin Panel` settings menu. -* Click on `Settings`. -* Click on the `Documents` tab. -* Change the `Default` content extraction engine dropdown to `Mistral OCR`. -* Paste the API Key on the field -* Save the Admin Panel. +- Log in to your Open WebUI instance. +- Navigate to the `Admin Panel` settings menu. +- Click on `Settings`. +- Click on the `Documents` tab. +- Change the `Default` content extraction engine dropdown to `Mistral OCR`. +- Paste the API Key on the field +- Save the Admin Panel. Verifying Mistral OCR ===================================== To verify that Mistral OCR is working correctly in script, please refer to `https://docs.mistral.ai/capabilities/document/` - ### Conclusion Integrating Mistral OCR with Open WebUI is a simple and effective way to enhance document processing and content extraction capabilities. By following the steps in this guide, you can set up Mistral OCR as the default extraction engine and leverage its advanced text recognition features. Once configured, Mistral OCR enables powerful, multilingual document parsing with support for various formats, enhancing AI-driven document analysis capabilities in Open WebUI. diff --git a/docs/features/evaluation/index.mdx b/docs/features/evaluation/index.mdx index fbcc990d51..027ecdd6a6 100644 --- a/docs/features/evaluation/index.mdx +++ b/docs/features/evaluation/index.mdx @@ -3,7 +3,6 @@ sidebar_position: 6 title: "📝 Evaluation" --- - ## 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. @@ -15,7 +14,7 @@ That's where Open WebUI comes in. It gives Alex and their team an easy way to ev - **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**: +- **Evaluation options**: - **Arena Model**: Randomly selects models for you to compare. - **Normal Interaction**: Just chat like usual and rate the responses. @@ -42,7 +41,7 @@ One cool feature? **Whenever you rate a response**, the system captures a **snap ### Two Ways to Evaluate an AI Model -Open WebUI provides two straightforward approaches for evaluating AI models. +Open WebUI provides two straightforward approaches for evaluating AI models. ### **1. Arena Model** @@ -51,7 +50,7 @@ The **Arena Model** randomly selects from a pool of available models, making sur 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! @@ -67,7 +66,7 @@ Need more depth? You can even replicate a [**Chatbot Arena**](https://lmarena.ai ### **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. +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: @@ -95,7 +94,7 @@ When you rate chats, you can **tag them by topic** for more granular insights. T 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: diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 6ea5851a89..a4338165e4 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -222,7 +222,6 @@ import { TopBanners } from "@site/src/components/TopBanners"; ### 💻 Model Management - - 🛠️ **Model Builder**: All models can be built and edited with a persistent model builder mode within the models edit page. - 📚 **Knowledge Support for Models**: The ability to attach tools, functions, and knowledge collections directly to models from a model's edit page, enhancing the information available to each model. diff --git a/docs/features/openldap.mdx b/docs/features/openldap.mdx index cefb6f0ba3..45528de5a4 100644 --- a/docs/features/openldap.mdx +++ b/docs/features/openldap.mdx @@ -14,7 +14,7 @@ The easiest way to get a test OpenLDAP server running is by using Docker. This ` version: "3.9" services: ldap: - image: osixia/openldap:1.5.0 + image: osixia/openldap:1.5.0 container_name: openldap environment: LDAP_ORGANISATION: "Example Inc" @@ -28,7 +28,7 @@ services: - "389:389" networks: [ldapnet] - phpldapadmin: + phpldapadmin: image: osixia/phpldapadmin:0.9.0 environment: PHPLDAPADMIN_LDAP_HOSTS: "ldap" @@ -67,6 +67,7 @@ userPassword: {PLAIN}password123 **Note on Passwords:** The `userPassword` field is set to a plain text value for simplicity in this test environment. In production, you should always use a hashed password. You can generate a hashed password using `slappasswd` or `openssl passwd`. For example: ```bash + # Using slappasswd (inside the container) docker exec openldap slappasswd -s your_password @@ -104,10 +105,13 @@ Now, configure your Open WebUI instance to use the LDAP server for authenticatio Set the following environment variables for your Open WebUI instance. :::info + Open WebUI reads these environment variables only on the first startup. Subsequent changes must be made in the Admin settings panel of the UI unless you have `ENABLE_PERSISTENT_CONFIG=false`. + ::: ```env + # Enable LDAP ENABLE_LDAP="true" @@ -133,11 +137,11 @@ LDAP_SEARCH_FILTER="(uid=%(user)s)" # More secure and performant Alternatively, you can configure these settings directly in the UI: -1. Log in as an administrator. -2. Navigate to **Settings** > **General**. -3. Enable **LDAP Authentication**. -4. Fill in the fields corresponding to the environment variables above. -5. Save the settings and restart Open WebUI. +1. Log in as an administrator. +2. Navigate to **Settings** > **General**. +3. Enable **LDAP Authentication**. +4. Fill in the fields corresponding to the environment variables above. +5. Save the settings and restart Open WebUI. ## 5. Logging In @@ -186,15 +190,15 @@ openldap | ... conn=1001 op=0 RESULT tag=97 err=49 text= **Cause:** The LDAP server rejected the bind attempt because the distinguished name (DN) or the password was incorrect. This happens during the second bind attempt, where Open WebUI tries to authenticate with the user's provided credentials. **Solution:** -1. **Verify the Password:** Ensure you are using the correct plaintext password. The `userPassword` value in the LDIF file is what the server expects. If it's a hash, you must provide the original plaintext password. -2. **Check the User DN:** The DN used for the bind (`uid=jdoe,ou=users,dc=example,dc=org`) must be correct. -3. **Test with `ldapwhoami`:** Verify the credentials directly against the LDAP server to isolate the issue from Open WebUI. +1. **Verify the Password:** Ensure you are using the correct plaintext password. The `userPassword` value in the LDIF file is what the server expects. If it's a hash, you must provide the original plaintext password. +2. **Check the User DN:** The DN used for the bind (`uid=jdoe,ou=users,dc=example,dc=org`) must be correct. +3. **Test with `ldapwhoami`:** Verify the credentials directly against the LDAP server to isolate the issue from Open WebUI. ```bash ldapwhoami -x -H ldap://localhost:389 \ -D "uid=jdoe,ou=users,dc=example,dc=org" -w "password123" ``` If this command fails with `ldap_bind: Invalid credentials (49)`, the problem is with the credentials or the LDAP server's password configuration, not Open WebUI. -4. **Reset the Password:** If you don't know the password, reset it using `ldapmodify` or `ldappasswd`. It's often easiest to use a `{PLAIN}` password for initial testing and then switch to a secure hash like `{SSHA}`. +4. **Reset the Password:** If you don't know the password, reset it using `ldapmodify` or `ldappasswd`. It's often easiest to use a `{PLAIN}` password for initial testing and then switch to a secure hash like `{SSHA}`. **Example LDIF to change password:** ```ldif title="change_password.ldif" diff --git a/docs/features/plugin/events/index.mdx b/docs/features/plugin/events/index.mdx index 53ed5e7c74..a23c098c66 100644 --- a/docs/features/plugin/events/index.mdx +++ b/docs/features/plugin/events/index.mdx @@ -17,7 +17,7 @@ This guide explains **what events are**, **how you can trigger them** from your - Events are sent using the `__event_emitter__` helper for one-way updates, or `__event_call__` when you need user input or a response (e.g., confirmation, input, etc.). -**Metaphor:** +**Metaphor:** Think of Events like push notifications and modal dialogs that your plugin can trigger, making the chat experience richer and more interactive. --- @@ -58,6 +58,7 @@ result = await __event_call__( }, } ) + # result will contain the user's input value ``` @@ -86,22 +87,30 @@ Below is a comprehensive table of **all supported `type` values** for events, al | -------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `status` | Show a status update/history for a message | `{description: ..., done: bool, hidden: bool}` | | `chat:completion` | Provide a chat completion result | (Custom, see Open WebUI internals) | -| `chat:message:delta`,
`message` | Append content to the current message | `{content: "text to append"}` | -| `chat:message`,
`replace` | Replace current message content completely | `{content: "replacement text"}` | -| `chat:message:files`,
`files` | Set or overwrite message files (for uploads, output) | `{files: [...]}` | +| `chat:message:delta`, +`message` | Append content to the current message | `{content: "text to append"}` | +| `chat:message`, +`replace` | Replace current message content completely | `{content: "replacement text"}` | +| `chat:message:files`, +`files` | Set or overwrite message files (for uploads, output) | `{files: [...]}` | | `chat:title` | Set (or update) the chat conversation title | Topic string OR `{title: ...}` | | `chat:tags` | Update the set of tags for a chat | Tag array or object | -| `source`,
`citation` | Add a source/citation, or code execution result | For code: See [below.](/docs/features/plugin/events/index.mdx#source-or-citation-and-code-execution) | +| `source`, +`citation` | Add a source/citation, or code execution result | For code: See [below.](/docs/features/plugin/events/index.mdx#source-or-citation-and-code-execution) | | `notification` | Show a notification ("toast") in the UI | `{type: "info" or "success" or "error" or "warning", content: "..."}` | -| `confirmation`
(needs `__event_call__`) | Ask for confirmation (OK/Cancel dialog) | `{title: "...", message: "..."}` | -| `input`
(needs `__event_call__`) | Request simple user input ("input box" dialog) | `{title: "...", message: "...", placeholder: "...", value: ...}` | -| `execute`
(needs `__event_call__`) | Request user-side code execution and return result | `{code: "...javascript code..."}` | +| `confirmation` +(needs `__event_call__`) | Ask for confirmation (OK/Cancel dialog) | `{title: "...", message: "..."}` | +| `input` +(needs `__event_call__`) | Request simple user input ("input box" dialog) | `{title: "...", message: "...", placeholder: "...", value: ...}` | +| `execute` +(needs `__event_call__`) | Request user-side code execution and return result | `{code: "...javascript code..."}` | **Other/Advanced types:** - You can define your own types and handle them at the UI layer (or use upcoming event-extension mechanisms). ### ❗ Details on Specific Event Types + ### `status` Show a status/progress update in the UI: @@ -388,6 +397,7 @@ response = await __event_call__({ "placeholder": "Name" } }) + # response will be: {"value": "user's answer"} ``` diff --git a/docs/features/plugin/functions/action.mdx b/docs/features/plugin/functions/action.mdx index f075b8f555..457d83f155 100644 --- a/docs/features/plugin/functions/action.mdx +++ b/docs/features/plugin/functions/action.mdx @@ -32,11 +32,11 @@ Actions follow a specific class structure with an `action` method as the main en class Action: def __init__(self): self.valves = self.Valves() - + class Valves(BaseModel): # Configuration parameters parameter_name: str = "default_value" - + async def action(self, body: dict, __user__=None, __event_emitter__=None, __event_call__=None): # Action implementation return {"content": "Modified message content"} @@ -68,10 +68,10 @@ Send real-time updates to the frontend during action execution: async def action(self, body: dict, __event_emitter__=None): # Send status updates await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Processing request..."} }) - + # Send notifications await __event_emitter__({ "type": "notification", @@ -92,7 +92,7 @@ async def action(self, body: dict, __event_call__=None): "message": "Are you sure you want to proceed?" } }) - + # Request user input user_input = await __event_call__({ "type": "input", @@ -127,7 +127,7 @@ actions = [ }, { "id": "translate", - "name": "Translate", + "name": "Translate", "icon_url": "data:image/svg+xml;base64,..." } ] @@ -137,7 +137,7 @@ async def action(self, body: dict, __id__=None, **kwargs): # Summarization logic return {"content": "Summary: ..."} elif __id__ == "translate": - # Translation logic + # Translation logic return {"content": "Translation: ..."} ``` @@ -157,10 +157,10 @@ async def action(self, body: dict, __event_emitter__=None): "type": "status", "data": {"description": "Starting background processing..."} }) - + # Perform time-consuming operation result = await some_long_running_function() - + return {"content": f"Processing completed: {result}"} ``` @@ -170,7 +170,7 @@ Actions can work with uploaded files and generate new media: ```python async def action(self, body: dict): message = body - + # Access uploaded files if message.get("files"): for file in message["files"]: @@ -178,7 +178,7 @@ async def action(self, body: dict): if file["type"] == "image": # Image processing logic pass - + # Return new files return { "content": "Analysis complete", @@ -199,7 +199,7 @@ Actions can access user information and respect permissions: async def action(self, body: dict, __user__=None): if __user__["role"] != "admin": return {"content": "This action requires admin privileges"} - + user_name = __user__["name"] return {"content": f"Hello {user_name}, admin action completed"} ``` @@ -252,7 +252,7 @@ class Action: "type": "status", "data": {"description": "Processing message..."} }) - + # Get user confirmation response = await __event_call__({ "type": "confirmation", @@ -261,14 +261,14 @@ class Action: "message": "Do you want to enhance this message?" } }) - + if not response: return {"content": "Action cancelled by user"} - + # Process the message original_content = body.get("content", "") enhanced_content = f"Enhanced: {original_content}" - + return {"content": enhanced_content} ``` diff --git a/docs/features/plugin/functions/filter.mdx b/docs/features/plugin/functions/filter.mdx index 9cd41399a9..d380657b27 100644 --- a/docs/features/plugin/functions/filter.mdx +++ b/docs/features/plugin/functions/filter.mdx @@ -5,7 +5,7 @@ title: "🪄 Filter Function" # 🪄 Filter Function: Modify Inputs and Outputs -Welcome to the comprehensive guide on Filter Functions in Open WebUI! Filters are a flexible and powerful **plugin system** for modifying data *before it's sent to the Large Language Model (LLM)* (input) or *after it’s returned from the LLM* (output). Whether you’re transforming inputs for better context or cleaning up outputs for improved readability, **Filter Functions** let you do it all. +Welcome to the comprehensive guide on Filter Functions in Open WebUI! Filters are a flexible and powerful **plugin system** for modifying data *before it's sent to the Large Language Model (LLM)* (input) or *after it’s returned from the LLM* (output). Whether you’re transforming inputs for better context or cleaning up outputs for improved readability, **Filter Functions** let you do it all. This guide will break down **what Filters are**, how they work, their structure, and everything you need to know to build powerful and user-friendly filters of your own. Let’s dig in, and don’t worry—I’ll use metaphors, examples, and tips to make everything crystal clear! 🌟 @@ -26,7 +26,7 @@ Here’s a quick summary of what Filters do: 2. **Intercept Model Outputs (Stream Function)**: Capture and adjust the AI’s responses **as they’re generated** by the model. This is useful for real-time modifications, like filtering out sensitive information or formatting the output for better readability. 3. **Modify Model Outputs (Outlet Function)**: Adjust the AI's response **after it’s processed**, before showing it to the user. This can help refine, log, or adapt the data for a cleaner user experience. -> **Key Concept:** Filters are not standalone models but tools that enhance or transform the data traveling *to* and *from* models. +> **Key Concept:** Filters are not standalone models but tools that enhance or transform the data traveling *to* and *from* models. Filters are like **translators or editors** in the AI workflow: you can intercept and change the conversation without interrupting the flow. @@ -44,7 +44,7 @@ from typing import Optional class Filter: # Valves: Configuration options for the filter - class Valves(BaseModel): + class Valves(BaseModel): pass def __init__(self): @@ -54,7 +54,7 @@ class Filter: def inlet(self, body: dict) -> dict: # This is where you manipulate user inputs. print(f"inlet called: {body}") - return body + return body def stream(self, event: dict) -> dict: # This is where you modify streamed chunks of model output. @@ -127,10 +127,9 @@ class Valves(BaseModel): OPTION_NAME: str = "Default Value" ``` -For example: +For example: If you're creating a filter that converts responses into uppercase, you might allow users to configure whether every output gets totally capitalized via a valve like `TRANSFORM_UPPERCASE: bool = True/False`. - ##### Configuring Valves with Dropdown Menus (Enums) You can enhance the user experience for your filter's settings by providing dropdown menus instead of free-form text inputs for certain `Valves`. This is achieved using `json_schema_extra` with the `enum` keyword in your Pydantic `Field` definitions. @@ -222,26 +221,25 @@ Using `enum` for your `Valves` options makes your filters more user-friendly and The `inlet` function is like **prepping food before cooking**. Imagine you’re a chef: before the ingredients go into the recipe (the LLM in this case), you might wash vegetables, chop onions, or season the meat. Without this step, your final dish could lack flavor, have unwashed produce, or simply be inconsistent. -In the world of Open WebUI, the `inlet` function does this important prep work on the **user input** before it’s sent to the model. It ensures the input is as clean, contextual, and helpful as possible for the AI to handle. +In the world of Open WebUI, the `inlet` function does this important prep work on the **user input** before it’s sent to the model. It ensures the input is as clean, contextual, and helpful as possible for the AI to handle. -📥 **Input**: +📥 **Input**: - **`body`**: The raw input from Open WebUI to the model. It is in the format of a chat-completion request (usually a dictionary that includes fields like the conversation's messages, model settings, and other metadata). Think of this as your recipe ingredients. -🚀 **Your Task**: +🚀 **Your Task**: Modify and return the `body`. The modified version of the `body` is what the LLM works with, so this is your chance to bring clarity, structure, and context to the input. - ##### 🍳 Why Would You Use the `inlet`? 1. **Adding Context**: Automatically append crucial information to the user’s input, especially if their text is vague or incomplete. For example, you might add "You are a friendly assistant" or "Help this user troubleshoot a software bug." - + 2. **Formatting Data**: If the input requires a specific format, like JSON or Markdown, you can transform it before sending it to the model. 3. **Sanitizing Input**: Remove unwanted characters, strip potentially harmful or confusing symbols (like excessive whitespace or emojis), or replace sensitive information. 4. **Streamlining User Input**: If your model’s output improves with additional guidance, you can use the `inlet` to inject clarifying instructions automatically! - ##### 💡 Example Use Cases: Build on Food Prep + ###### 🥗 Example 1: Adding System Context Let’s say the LLM is a chef preparing a dish for Italian cuisine, but the user hasn’t mentioned "This is for Italian cooking." You can ensure the message is clear by appending this context before sending the data to the model. @@ -260,7 +258,6 @@ def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict: 📖 **What Happens?** - Any user input like "What are some good dinner ideas?" now carries the Italian theme because we’ve set the system context! Cheesecake might not show up as an answer, but pasta sure will. - ###### 🔪 Example 2: Cleaning Input (Remove Odd Characters) Suppose the input from the user looks messy or includes unwanted symbols like `!!!`, making the conversation inefficient or harder for the model to parse. You can clean it up while preserving the core content. @@ -275,8 +272,11 @@ def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict: 📖 **What Happens?** - Before: `"How can I debug this issue!!!"` ➡️ Sent to the model as `"How can I debug this issue"` +:::note + Note: The user feels the same, but the model processes a cleaner and easier-to-understand query. +::: ##### 📊 How `inlet` Helps Optimize Input for the LLM: - Improves **accuracy** by clarifying ambiguous queries. @@ -328,14 +328,14 @@ def stream(self, event: dict) -> dict: delta["content"] = delta["content"].replace("😊", "") # Strip emojis return event ``` -📖 **Before:** `"Hi 😊"` +📖 **Before:** `"Hi 😊"` 📖 **After:** `"Hi"` --- #### 4️⃣ **`outlet` Function (Output Post-Processing)** -The `outlet` function is like a **proofreader**: tidy up the AI's response (or make final changes) *after it’s processed by the LLM.* +The `outlet` function is like a **proofreader**: tidy up the AI's response (or make final changes) *after it’s processed by the LLM.* 📤 **Input**: - **`body`**: This contains **all current messages** in the chat (user history + LLM replies). @@ -351,7 +351,7 @@ The `outlet` function is like a **proofreader**: tidy up the AI's response (or m def outlet(self, body: dict, __user__: Optional[dict] = None) -> dict: for message in body["messages"]: message["content"] = message["content"].replace("", "[REDACTED]") - return body + return body ``` --- @@ -368,7 +368,7 @@ Want the LLM to always know it's assisting a customer in troubleshooting softwar class Filter: def inlet(self, body: dict, __user__: Optional[dict] = None) -> dict: context_message = { - "role": "system", + "role": "system", "content": "You're a software troubleshooting assistant." } body.setdefault("messages", []).insert(0, context_message) @@ -393,7 +393,7 @@ class Filter: --- -## 🚧 Potential Confusion: Clear FAQ 🛑 +## 🚧 Potential Confusion: Clear FAQ 🛑 ### **Q: How Are Filters Different From Pipe Functions?** @@ -420,6 +420,6 @@ By now, you’ve learned: --- -🚀 **Your Turn**: Start experimenting! What small tweak or context addition could elevate your Open WebUI experience? Filters are fun to build, flexible to use, and can take your models to the next level! +🚀 **Your Turn**: Start experimenting! What small tweak or context addition could elevate your Open WebUI experience? Filters are fun to build, flexible to use, and can take your models to the next level! Happy coding! ✨ diff --git a/docs/features/plugin/functions/index.mdx b/docs/features/plugin/functions/index.mdx index 8c2feec467..26c2ae139a 100644 --- a/docs/features/plugin/functions/index.mdx +++ b/docs/features/plugin/functions/index.mdx @@ -5,15 +5,15 @@ title: "🧰 Functions" ## 🚀 What Are Functions? -Functions are like **plugins** for Open WebUI. They help you **extend its capabilities**—whether it’s adding support for new AI model providers like Anthropic or Vertex AI, tweaking how messages are processed, or introducing custom buttons to the interface for better usability. +Functions are like **plugins** for Open WebUI. They help you **extend its capabilities**—whether it’s adding support for new AI model providers like Anthropic or Vertex AI, tweaking how messages are processed, or introducing custom buttons to the interface for better usability. -Unlike external tools that may require complex integrations, **Functions are built-in and run within the Open WebUI environment.** That means they are fast, modular, and don’t rely on external dependencies. +Unlike external tools that may require complex integrations, **Functions are built-in and run within the Open WebUI environment.** That means they are fast, modular, and don’t rely on external dependencies. Think of Functions as **modular building blocks** that let you enhance how the WebUI works, tailored exactly to what you need. They’re lightweight, highly customizable, and written in **pure Python**, so you have the freedom to create anything—from new AI-powered workflows to integrations with anything you use, like Google Search or Home Assistant. --- -## 🏗️ Types of Functions +## 🏗️ Types of Functions There are **three types of Functions** in Open WebUI, each with a specific purpose. Let’s break them down and explain exactly what they do: @@ -21,113 +21,113 @@ There are **three types of Functions** in Open WebUI, each with a specific purpo ### 1. [**Pipe Function** – Create Custom "Agents/Models" ](./pipe.mdx) -A **Pipe Function** is how you create **custom agents/models** or integrations, which then appear in the interface as if they were standalone models. +A **Pipe Function** is how you create **custom agents/models** or integrations, which then appear in the interface as if they were standalone models. -**What does it do?** +**What does it do?** - Pipes let you define complex workflows. For instance, you could create a Pipe that sends data to **Model A** and **Model B**, processes their outputs, and combines the results into one finalized answer. -- Pipes don’t even have to use AI! They can be setups for **search APIs**, **weather data**, or even systems like **Home Assistant**. Basically, anything you’d like to interact with can become part of Open WebUI. +- Pipes don’t even have to use AI! They can be setups for **search APIs**, **weather data**, or even systems like **Home Assistant**. Basically, anything you’d like to interact with can become part of Open WebUI. -**Use case example:** -Imagine you want to query Google Search directly from Open WebUI. You can create a Pipe Function that: -1. Takes your message as the search query. -2. Sends the query to Google Search’s API. -3. Processes the response and returns it to you inside the WebUI like a normal "model" response. +**Use case example:** +Imagine you want to query Google Search directly from Open WebUI. You can create a Pipe Function that: +1. Takes your message as the search query. +2. Sends the query to Google Search’s API. +3. Processes the response and returns it to you inside the WebUI like a normal "model" response. -When enabled, **Pipe Functions show up as their own selectable model**. Use Pipes whenever you need custom functionality that works like a model in the interface. +When enabled, **Pipe Functions show up as their own selectable model**. Use Pipes whenever you need custom functionality that works like a model in the interface. For a detailed guide, see [**Pipe Functions**](./pipe.mdx). --- -### 2. [**Filter Function** – Modify Inputs and Outputs](./filter.mdx) +### 2. [**Filter Function** – Modify Inputs and Outputs](./filter.mdx) -A **Filter Function** is like a tool for tweaking data before it gets sent to the AI **or** after it comes back. +A **Filter Function** is like a tool for tweaking data before it gets sent to the AI **or** after it comes back. -**What does it do?** -Filters act as "hooks" in the workflow and have two main parts: -- **Inlet**: Adjust the input that is sent to the model. For example, adding additional instructions, keywords, or formatting tweaks. -- **Outlet**: Modify the output that you receive from the model. For instance, cleaning up the response, adjusting tone, or formatting data into a specific style. +**What does it do?** +Filters act as "hooks" in the workflow and have two main parts: +- **Inlet**: Adjust the input that is sent to the model. For example, adding additional instructions, keywords, or formatting tweaks. +- **Outlet**: Modify the output that you receive from the model. For instance, cleaning up the response, adjusting tone, or formatting data into a specific style. -**Use case example:** -Suppose you’re working on a project that needs precise formatting. You can use a Filter to ensure: -1. Your input is always transformed into the required format. -2. The output from the model is cleaned up before being displayed. +**Use case example:** +Suppose you’re working on a project that needs precise formatting. You can use a Filter to ensure: +1. Your input is always transformed into the required format. +2. The output from the model is cleaned up before being displayed. -Filters are **linked to specific models** or can be enabled for all models **globally**, depending on your needs. +Filters are **linked to specific models** or can be enabled for all models **globally**, depending on your needs. Check out the full guide for more examples and instructions: [**Filter Functions**](./filter.mdx). --- -### 3. [**Action Function** – Add Custom Buttons](./action.mdx) +### 3. [**Action Function** – Add Custom Buttons](./action.mdx) -An **Action Function** is used to add **custom buttons** to the chat interface. +An **Action Function** is used to add **custom buttons** to the chat interface. -**What does it do?** -Actions allow you to define **interactive shortcuts** that trigger specific functionality directly from the chat. These buttons appear underneath individual chat messages, giving you convenient, one-click access to the actions you define. +**What does it do?** +Actions allow you to define **interactive shortcuts** that trigger specific functionality directly from the chat. These buttons appear underneath individual chat messages, giving you convenient, one-click access to the actions you define. -**Use case example:** -Let’s say you often need to summarize long messages or generate specific outputs like translations. You can create an Action Function to: -1. Add a “Summarize” button under every incoming message. -2. When clicked, it triggers your custom function to process that message and return the summary. +**Use case example:** +Let’s say you often need to summarize long messages or generate specific outputs like translations. You can create an Action Function to: +1. Add a “Summarize” button under every incoming message. +2. When clicked, it triggers your custom function to process that message and return the summary. -Buttons provide a **clean and user-friendly way** to interact with extended functionality you define. +Buttons provide a **clean and user-friendly way** to interact with extended functionality you define. Learn how to set them up in the [**Action Functions Guide**](./action.mdx). --- -## 🛠️ How to Use Functions +## 🛠️ How to Use Functions Here's how to put Functions to work in Open WebUI: -### 1. **Install Functions** +### 1. **Install Functions** You can install Functions via the Open WebUI interface or by importing them manually. You can find community-created functions on the [Open WebUI Community Site](https://openwebui.com/functions). -⚠️ **Be cautious.** Only install Functions from trusted sources. Running unknown code poses security risks. +⚠️ **Be cautious.** Only install Functions from trusted sources. Running unknown code poses security risks. --- -### 2. **Enable Functions** -Functions must be explicitly enabled after installation: -- When you enable a **Pipe Function**, it becomes available as its own **model** in the interface. -- For **Filter** and **Action Functions**, enabling them isn’t enough—you also need to assign them to specific models or enable them globally for all models. +### 2. **Enable Functions** +Functions must be explicitly enabled after installation: +- When you enable a **Pipe Function**, it becomes available as its own **model** in the interface. +- For **Filter** and **Action Functions**, enabling them isn’t enough—you also need to assign them to specific models or enable them globally for all models. --- -### 3. **Assign Filters or Actions to Models** -- Navigate to `Workspace => Models` and assign your Filter or Action to the relevant model there. +### 3. **Assign Filters or Actions to Models** +- Navigate to `Workspace => Models` and assign your Filter or Action to the relevant model there. - Alternatively, enable Functions for **all models globally** by going to `Workspace => Functions`, selecting the "..." menu, and toggling the **Global** switch. --- -### Quick Summary -- **Pipes** appear as standalone models you can interact with. -- **Filters** modify inputs/outputs for smoother AI interactions. -- **Actions** add clickable buttons to individual chat messages. +### Quick Summary +- **Pipes** appear as standalone models you can interact with. +- **Filters** modify inputs/outputs for smoother AI interactions. +- **Actions** add clickable buttons to individual chat messages. Once you’ve followed the setup process, Functions will seamlessly enhance your workflows. --- -## ✅ Why Use Functions? +## ✅ Why Use Functions? -Functions are designed for anyone who wants to **unlock new possibilities** with Open WebUI: +Functions are designed for anyone who wants to **unlock new possibilities** with Open WebUI: -- **Extend**: Add new models or integrate with non-AI tools like APIs, databases, or smart devices. -- **Optimize**: Tweak inputs and outputs to fit your use case perfectly. -- **Simplify**: Add buttons or shortcuts to make the interface intuitive and efficient. +- **Extend**: Add new models or integrate with non-AI tools like APIs, databases, or smart devices. +- **Optimize**: Tweak inputs and outputs to fit your use case perfectly. +- **Simplify**: Add buttons or shortcuts to make the interface intuitive and efficient. Whether you’re customizing workflows for specific projects, integrating external data, or just making Open WebUI easier to use, Functions are the key to taking control of your instance. --- -### 📝 Final Notes: -1. Always install Functions from **trusted sources only**. -2. Make sure you understand the difference between Pipe, Filter, and Action Functions to use them effectively. -3. Explore the official guides: - - [Pipe Functions Guide](./pipe.mdx) - - [Filter Functions Guide](./filter.mdx) - - [Action Functions Guide](./action.mdx) +### 📝 Final Notes: +1. Always install Functions from **trusted sources only**. +2. Make sure you understand the difference between Pipe, Filter, and Action Functions to use them effectively. +3. Explore the official guides: + - [Pipe Functions Guide](./pipe.mdx) + - [Filter Functions Guide](./filter.mdx) + - [Action Functions Guide](./action.mdx) By leveraging Functions, you’ll bring entirely new capabilities to your Open WebUI setup. Start experimenting today! 🚀 \ No newline at end of file diff --git a/docs/features/plugin/functions/pipe.mdx b/docs/features/plugin/functions/pipe.mdx index 6e58a2eb68..01361cc783 100644 --- a/docs/features/plugin/functions/pipe.mdx +++ b/docs/features/plugin/functions/pipe.mdx @@ -3,10 +3,9 @@ sidebar_position: 1 title: "🚰 Pipe Function" --- -# 🚰 Pipe Function: Create Custom "Agents/Models" +# 🚰 Pipe Function: Create Custom "Agents/Models" Welcome to this guide on creating **Pipes** in Open WebUI! Think of Pipes as a way to **adding** a new model to Open WebUI. In this document, we'll break down what a Pipe is, how it works, and how you can create your own to add custom logic and processing to your Open WebUI models. We'll use clear metaphors and go through every detail to ensure you have a comprehensive understanding. - ## Introduction to Pipes Imagine Open WebUI as a **plumbing system** where data flows through pipes and valves. In this analogy: diff --git a/docs/features/plugin/index.mdx b/docs/features/plugin/index.mdx index 42b321e1f1..edc3c13c52 100644 --- a/docs/features/plugin/index.mdx +++ b/docs/features/plugin/index.mdx @@ -17,7 +17,7 @@ Getting started with Tools and Functions is easy because everything’s already ## 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. +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 @@ -59,7 +59,7 @@ Without functions, these would all be out of reach. But with this framework in O Functions are not located in the same place as Tools. - **Tools** are about model access and live in your **Workspace tabs** (where you add models, prompts, and knowledge collections). They can be added by users if granted permissions. -- **Functions** are about **platform customization** and are found in the **Admin Panel**. +- **Functions** are about **platform customization** and are found in the **Admin Panel**. They are configured and managed only by admins who want to extend the platform interface or behavior for all users. ### Summary of Differences: diff --git a/docs/features/plugin/migration/index.mdx b/docs/features/plugin/migration/index.mdx index 575515f0f4..633291e5c0 100644 --- a/docs/features/plugin/migration/index.mdx +++ b/docs/features/plugin/migration/index.mdx @@ -30,6 +30,7 @@ Here’s an overview of what changed: #### Example: ```python + # Full API flow with parsing (new function): from open_webui.main import chat_completion @@ -70,7 +71,7 @@ Follow this guide to smoothly update your project. --- -### 🔄 1. Shifting from `apps` to `routers` +### 🔄 1. Shifting from `apps` to `routers` All apps have been renamed and relocated under `open_webui.routers`. This affects imports in your codebase. @@ -84,25 +85,23 @@ Quick changes for import paths: | `open_webui.apps.retrieval` | `open_webui.routers.retrieval` | | `open_webui.apps.webui` | `open_webui.main` | +### 📜 An Important Example -### 📜 An Important Example - -To clarify the special case of the main app (`webui`), here’s a simple rule of thumb: +To clarify the special case of the main app (`webui`), here’s a simple rule of thumb: -- **Was in `webui`?** It’s now in the project’s root or `open_webui.main`. -- For example: - - **Before (0.4):** - ```python - from open_webui.apps.webui.models import SomeModel - ``` - - **After (0.5):** - ```python - from open_webui.models import SomeModel - ``` +- **Was in `webui`?** It’s now in the project’s root or `open_webui.main`. +- For example: + - **Before (0.4):** + ```python + from open_webui.apps.webui.models import SomeModel + ``` + - **After (0.5):** + ```python + from open_webui.models import SomeModel + ``` In general, **just replace `open_webui.apps` with `open_webui.routers`—except for `webui`, which is now `open_webui.main`!** - --- ### 👩‍💻 2. Updating Import Statements @@ -117,6 +116,7 @@ from open_webui.apps.openai import main as openai #### After: ```python + # Separate router imports from open_webui.routers.ollama import generate_chat_completion from open_webui.routers.openai import generate_chat_completion @@ -125,7 +125,11 @@ from open_webui.routers.openai import generate_chat_completion from open_webui.main import chat_completion ``` -**💡 Pro Tip:** Prioritize the unified endpoint (`chat_completion`) for simplicity and future compatibility. +::tip + +Prioritize the unified endpoint (`chat_completion`) for simplicity and future compatibility. + +::: ### 📝 **Additional Note: Choosing Between `main.chat_completion` and `utils.chat.generate_chat_completion`** @@ -143,6 +147,7 @@ Depending on your use case, you can choose between: #### Example: ```python + # Use this for the full API flow with parsing: from open_webui.main import chat_completion @@ -152,18 +157,18 @@ from open_webui.utils.chat import generate_chat_completion --- -### 📋 3. Adapting to Updated Function Signatures +### 📋 3. Adapting to Updated Function Signatures We’ve updated the **function signatures** to better fit the new architecture. If you're looking for a direct replacement, start with the lightweight utility function `generate_chat_completion` from `open_webui.utils.chat`. For the full API flow, use the new unified `chat_completion` function in `open_webui.main`. -#### Function Signature Changes: +#### Function Signature Changes: | **Old** | **Direct Successor (New)** | **Unified Option (New)** | |-----------------------------------------|-----------------------------------------|-----------------------------------------| | `openai.generate_chat_completion(form_data: dict, user: UserModel)` | `generate_chat_completion(request: Request, form_data: dict, user: UserModel)` | `chat_completion(request: Request, form_data: dict, user: UserModel)` | -- **Direct Successor (`generate_chat_completion`)**: A lightweight, 1:1 replacement for previous `ollama`/`openai` methods. -- **Unified Option (`chat_completion`)**: Use this for the complete API flow, including file parsing and additional functionality. +- **Direct Successor (`generate_chat_completion`)**: A lightweight, 1:1 replacement for previous `ollama`/`openai` methods. +- **Unified Option (`chat_completion`)**: Use this for the complete API flow, including file parsing and additional functionality. #### Example: diff --git a/docs/features/plugin/tools/development.mdx b/docs/features/plugin/tools/development.mdx index 9c86316082..ef2bb5f478 100644 --- a/docs/features/plugin/tools/development.mdx +++ b/docs/features/plugin/tools/development.mdx @@ -3,8 +3,6 @@ sidebar_position: 2 title: "🛠️ Development" --- - - ## Writing A Custom Toolkit Toolkits are defined in a single Python file, with a top level docstring with metadata and a `Tools` class. @@ -46,7 +44,7 @@ class Tools: # example usage of valves if self.valves.api_key != "42": return "Wrong API key" - return string[::-1] + return string[::-1] ``` ### Type Hints @@ -54,7 +52,7 @@ Each tool must have type hints for arguments. The types may also be nested, such ### Valves and UserValves - (optional, but HIGHLY encouraged) -Valves and UserValves are used for specifying customizable settings of the Tool, you can read more on the dedicated [Valves & UserValves](../valves/index.mdx) page. +Valves and UserValves are used for specifying customizable settings of the Tool, you can read more on the dedicated [Valves & UserValves](/features/plugin/valves/index.mdx) page. ### Optional Arguments Below is a list of optional arguments your tools can depend on: @@ -92,14 +90,14 @@ class Tools: """ if not __oauth_token__ or "access_token" not in __oauth_token__: return "Error: User is not authenticated via OAuth or token is unavailable." - + access_token = __oauth_token__["access_token"] - + headers = { "Authorization": f"Bearer {access_token}", "Content-Type": "application/json" } - + try: async with httpx.AsyncClient() as client: response = await client.get("https://api.my-service.com/v1/profile", headers=headers) @@ -182,14 +180,14 @@ class Tools: def __init__(self): # Add a note about function calling mode requirements self.description = "This tool requires Default function calling mode for full functionality" - + async def interactive_tool(self, prompt: str, __event_emitter__=None) -> str: """ ⚠️ This tool requires function_calling = "default" for proper event emission """ if not __event_emitter__: return "Event emitter not available - ensure Default function calling mode is enabled" - + # Safe to use message events in Default mode await __event_emitter__({ "type": "message", @@ -206,12 +204,12 @@ async def universal_tool(self, prompt: str, __event_emitter__=None, __metadata__ """ # Check if we're in native mode (this is a rough heuristic) is_native_mode = __metadata__ and __metadata__.get("params", {}).get("function_calling") == "native" - + if __event_emitter__: if is_native_mode: # Use only compatible event types in native mode await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Processing in native mode...", "done": False} }) else: @@ -220,15 +218,15 @@ async def universal_tool(self, prompt: str, __event_emitter__=None, __metadata__ "type": "message", "data": {"content": "Processing with full event support..."} }) - + # ... tool logic here - + if __event_emitter__: await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Completed successfully", "done": True} }) - + return "Tool execution completed" ``` @@ -250,39 +248,39 @@ async def universal_tool(self, prompt: str, __event_emitter__=None, __metadata__ ```python async def debug_events_tool(self, __event_emitter__=None, __metadata__=None) -> str: """Debug tool to test event emitter functionality""" - + if not __event_emitter__: return "No event emitter available" - + # Test various event types test_events = [ {"type": "status", "data": {"description": "Testing status events", "done": False}}, {"type": "message", "data": {"content": "Testing message events (may not work in native mode)"}}, {"type": "notification", "data": {"content": "Testing notification events"}}, ] - + mode_info = "Unknown" if __metadata__: mode_info = __metadata__.get("params", {}).get("function_calling", "default") - + await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": f"Function calling mode: {mode_info}", "done": False} }) - + for i, event in enumerate(test_events): await asyncio.sleep(1) # Space out events await __event_emitter__(event) await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": f"Sent event {i+1}/{len(test_events)}", "done": False} }) - + await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Event testing complete", "done": True} }) - + return f"Event testing completed in {mode_info} mode. Check for missing or flickering content." ``` @@ -299,7 +297,7 @@ Status events add live status updates to a message while it's performing steps. await __event_emitter__({ "type": "status", "data": { - "description": "Message that shows up in the chat", + "description": "Message that shows up in the chat", "done": False, # False = still processing, True = completed "hidden": False # False = visible, True = auto-hide when done } @@ -322,7 +320,7 @@ async def data_processing_tool( Processes a large data file with status updates ✅ Works in both Default and Native function calling modes """ - + if not __event_emitter__: return "Processing completed (no status updates available)" @@ -331,19 +329,19 @@ async def data_processing_tool( "type": "status", "data": {"description": "Loading data file...", "done": False} }) - + # Simulate loading time await asyncio.sleep(2) - + # Step 2: Processing await __event_emitter__({ "type": "status", "data": {"description": "Analyzing 10,000 records...", "done": False} }) - + # Simulate processing time await asyncio.sleep(3) - + # Step 3: Completion await __event_emitter__({ "type": "status", @@ -365,50 +363,50 @@ async def api_integration_tool( Integrates with external API with comprehensive status tracking ✅ Compatible with both function calling modes """ - + if not __event_emitter__: return "API integration completed (no status available)" - + try: await __event_emitter__({ "type": "status", "data": {"description": "Connecting to API...", "done": False} }) - + # Simulate API connection await asyncio.sleep(1.5) - + await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Authenticating...", "done": False} }) - + # Simulate authentication await asyncio.sleep(1) - + await __event_emitter__({ "type": "status", "data": {"description": "Fetching data...", "done": False} }) - + # Simulate data fetching await asyncio.sleep(2) - + # Success status await __event_emitter__({ "type": "status", "data": {"description": "API integration successful", "done": True} }) - + return "Successfully retrieved 150 records from the API" - + except Exception as e: # Error status - always visible for debugging await __event_emitter__({ "type": "status", "data": {"description": f"Error: {str(e)}", "done": True, "hidden": False} }) - + return f"API integration failed: {str(e)}" ```
@@ -424,19 +422,19 @@ async def batch_processor_tool( Processes items in batches with detailed progress tracking ✅ Works perfectly in both function calling modes """ - + if not __event_emitter__ or not items: return "Batch processing completed" - + total_items = len(items) batch_size = 10 completed = 0 - + for i in range(0, total_items, batch_size): batch = items[i:i + batch_size] batch_num = (i // batch_size) + 1 total_batches = (total_items + batch_size - 1) // batch_size - + # Update status for current batch await __event_emitter__({ "type": "status", @@ -445,22 +443,22 @@ async def batch_processor_tool( "done": False } }) - + # Simulate batch processing await asyncio.sleep(1) - + completed += len(batch) - + # Progress update progress_pct = int((completed / total_items) * 100) await __event_emitter__({ - "type": "status", + "type": "status", "data": { "description": f"Progress: {completed}/{total_items} items ({progress_pct}%)", "done": False } }) - + # Final completion status await __event_emitter__({ "type": "status", @@ -469,15 +467,19 @@ async def batch_processor_tool( "done": True } }) - + return f"Successfully processed {total_items} items in {total_batches} batches" ``` #### Message Events ⚠️ DEFAULT MODE ONLY +:::warning + **🚨 CRITICAL WARNING: Message events are INCOMPATIBLE with Native function calling mode!** +::: + Message events (`message`, `chat:message`, `chat:message:delta`, `replace`) allow you to append or modify message content at any stage during tool execution. This enables embedding images, rendering web pages, streaming content updates, and creating rich interactive experiences. **However, these event types have major compatibility issues:** @@ -512,37 +514,37 @@ async def streaming_content_tool( Streams content updates during processing ⚠️ REQUIRES function_calling = "default" - Will not work in Native mode! """ - + # Check function calling mode (rough detection) mode = "unknown" if __metadata__: mode = __metadata__.get("params", {}).get("function_calling", "default") - + if mode == "native": return "❌ This tool requires Default function calling mode. Message streaming is not supported in Native mode due to content overwriting issues." - + if not __event_emitter__: return "Event emitter not available" - + # Stream progressive content updates content_chunks = [ "🔍 **Phase 1: Research**\nGathering information about your query...\n\n", - "📊 **Phase 2: Analysis**\nAnalyzing gathered data patterns...\n\n", + "📊 **Phase 2: Analysis**\nAnalyzing gathered data patterns...\n\n", "✨ **Phase 3: Synthesis**\nGenerating insights and recommendations...\n\n", "📝 **Phase 4: Final Report**\nCompiling comprehensive results...\n\n" ] - + accumulated_content = "" - + for i, chunk in enumerate(content_chunks): accumulated_content += chunk - + # Append this chunk to the message await __event_emitter__({ "type": "message", "data": {"content": chunk} }) - + # Show progress status await __event_emitter__({ "type": "status", @@ -551,16 +553,16 @@ async def streaming_content_tool( "done": False } }) - + # Simulate processing time await asyncio.sleep(2) - + # Final completion await __event_emitter__({ "type": "status", "data": {"description": "Content streaming complete!", "done": True} }) - + return "Content streaming completed successfully. All phases processed." ``` @@ -576,10 +578,10 @@ async def live_dashboard_tool( Creates a live-updating dashboard using content replacement ⚠️ ONLY WORKS in Default function calling mode """ - + # Verify we're not in Native mode mode = __metadata__.get("params", {}).get("function_calling", "default") if __metadata__ else "default" - + if mode == "native": return """ ❌ **Native Mode Incompatibility** @@ -591,44 +593,45 @@ This dashboard tool cannot function in Native mode because: **Solution:** Switch to Default function calling mode in Model Settings → Advanced Params → Function Calling = "Default" """ - + if not __event_emitter__: return "Dashboard created (static mode - no live updates)" - + # Create initial dashboard initial_dashboard = """ + # 📊 Live System Dashboard ## System Status: 🟡 Initializing... ### Current Metrics: - **CPU Usage**: Loading... -- **Memory**: Loading... +- **Memory**: Loading... - **Active Users**: Loading... - **Response Time**: Loading... --- *Last Updated: Initializing...* """ - + await __event_emitter__({ "type": "replace", "data": {"content": initial_dashboard} }) - + # Simulate live data updates updates = [ { "status": "🟢 Online", - "cpu": "23%", + "cpu": "23%", "memory": "64%", "users": "1,247", "response": "145ms" }, { - "status": "🟢 Optimal", + "status": "🟢 Optimal", "cpu": "18%", - "memory": "61%", + "memory": "61%", "users": "1,352", "response": "132ms" }, @@ -636,15 +639,16 @@ This dashboard tool cannot function in Native mode because: "status": "🟡 Busy", "cpu": "67%", "memory": "78%", - "users": "1,891", + "users": "1,891", "response": "234ms" } ] - + for i, data in enumerate(updates): await asyncio.sleep(3) # Simulate data collection delay - + updated_dashboard = f""" + # 📊 Live System Dashboard ## System Status: {data['status']} @@ -659,24 +663,24 @@ This dashboard tool cannot function in Native mode because: *Last Updated: {datetime.now().strftime('%H:%M:%S')}* *Update {i+1}/{len(updates)}* """ - + # Replace entire dashboard content await __event_emitter__({ - "type": "replace", + "type": "replace", "data": {"content": updated_dashboard} }) - + # Status update await __event_emitter__({ "type": "status", "data": {"description": f"Dashboard updated ({i+1}/{len(updates)})", "done": False} }) - + await __event_emitter__({ "type": "status", "data": {"description": "Live dashboard monitoring complete", "done": True} }) - + return "Dashboard monitoring session completed." ``` @@ -692,15 +696,15 @@ async def adaptive_content_tool( Adapts behavior based on function calling mode ✅ Provides best possible experience in both modes """ - + # Detect function calling mode mode = "default" # Default assumption if __metadata__: mode = __metadata__.get("params", {}).get("function_calling", "default") - + if not __event_emitter__: return f"Generated {content_type} content (no real-time updates available)" - + # Mode-specific behavior if mode == "native": # Use only compatible events in Native mode @@ -708,16 +712,17 @@ async def adaptive_content_tool( "type": "status", "data": {"description": f"Generating {content_type} content in Native mode...", "done": False} }) - + await asyncio.sleep(2) - + await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Content generation complete", "done": True} }) - + # Return content normally - no message events return f""" + # {content_type.title()} Content **Mode**: Native Function Calling (Limited Event Support) @@ -726,41 +731,41 @@ Generated content here... This content is returned as the tool result rather tha *Note: Live content updates are not available in Native mode due to event compatibility limitations.* """ - + else: # Default mode # Full message event functionality available await __event_emitter__({ "type": "status", "data": {"description": "Generating content with full streaming support...", "done": False} }) - - # Stream content progressively + + # Stream content progressively progressive_content = [ f"# {content_type.title()} Content\n\n**Mode**: Default Function Calling ✅\n\n", "## Section 1: Introduction\nStreaming content in real-time...\n\n", - "## Section 2: Details\nAdding detailed information...\n\n", + "## Section 2: Details\nAdding detailed information...\n\n", "## Section 3: Conclusion\nFinalizing content delivery...\n\n", "*✅ Content streaming completed successfully!*" ] - + for i, chunk in enumerate(progressive_content): await __event_emitter__({ "type": "message", "data": {"content": chunk} }) - + await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": f"Streaming section {i+1}/{len(progressive_content)}...", "done": False} }) - + await asyncio.sleep(1.5) - + await __event_emitter__({ "type": "status", "data": {"description": "Content streaming complete!", "done": True} }) - + return "Content has been streamed above with full Default mode capabilities." ``` @@ -799,9 +804,13 @@ def __init__(self): self.citation = False # REQUIRED - prevents automatic citations from overriding custom ones ``` +:::warning + **⚠️ Critical Citation Warning:** If you set `self.citation = True` (or don't set it to `False`), automatic citations will replace any custom citations you send. Always disable automatic citations when using custom citation events. +::: +
Basic Citation Example @@ -809,7 +818,7 @@ If you set `self.citation = True` (or don't set it to `False`), automatic citati class Tools: def __init__(self): self.citation = False # Disable automatic citations - + async def research_tool( self, topic: str, __event_emitter__=None ) -> str: @@ -817,15 +826,15 @@ class Tools: Researches a topic and provides proper citations ✅ Works identically in both Default and Native modes """ - + if not __event_emitter__: return "Research completed (citations not available)" - + # Simulate research findings sources = [ { "title": "Advanced AI Systems", - "url": "https://example.com/ai-systems", + "url": "https://example.com/ai-systems", "content": "Artificial intelligence systems have evolved significantly...", "author": "Dr. Jane Smith", "date": "2024-03-15" @@ -833,12 +842,12 @@ class Tools: { "title": "Machine Learning Fundamentals", "url": "https://example.com/ml-fundamentals", - "content": "The core principles of machine learning include...", + "content": "The core principles of machine learning include...", "author": "Prof. John Doe", "date": "2024-02-20" } ] - + # Emit citations for each source for source in sources: await __event_emitter__({ @@ -855,12 +864,12 @@ class Tools: } ], "source": { - "name": source["title"], + "name": source["title"], "url": source["url"] } } }) - + return f"Research on '{topic}' completed. Found {len(sources)} relevant sources with detailed citations." ```
@@ -876,17 +885,17 @@ async def comprehensive_analysis_tool( Performs comprehensive analysis with multiple source types ✅ Full compatibility across all function calling modes """ - + if not __event_emitter__: return "Analysis completed" - + # Multiple source types with rich metadata research_sources = { "academic": [ { "title": "Neural Network Architecture in Modern AI", "authors": ["Dr. Sarah Chen", "Prof. Michael Rodriguez"], - "journal": "Journal of AI Research", + "journal": "Journal of AI Research", "volume": "Vol. 45, Issue 2", "pages": "123-145", "doi": "10.1000/182", @@ -898,7 +907,7 @@ async def comprehensive_analysis_tool( { "title": "Industry AI Implementation Trends", "url": "https://tech-insights.com/ai-trends-2024", - "site_name": "TechInsights", + "site_name": "TechInsights", "published": "2024-03-01", "content": "Recent industry surveys show that 78% of companies are implementing AI solutions..." } @@ -913,9 +922,9 @@ async def comprehensive_analysis_tool( } ] } - + citation_count = 0 - + # Process academic sources for source in research_sources["academic"]: citation_count += 1 @@ -929,7 +938,7 @@ async def comprehensive_analysis_tool( "source": source["title"], "authors": source["authors"], "journal": source["journal"], - "volume": source["volume"], + "volume": source["volume"], "pages": source["pages"], "doi": source["doi"], "publication_date": source["date"], @@ -937,17 +946,17 @@ async def comprehensive_analysis_tool( } ], "source": { - "name": f"{source['title']} - {source['journal']}", + "name": f"{source['title']} - {source['journal']}", "url": f"https://doi.org/{source['doi']}" } } }) - + # Process web sources for source in research_sources["web_sources"]: citation_count += 1 await __event_emitter__({ - "type": "citation", + "type": "citation", "data": { "document": [source["content"]], "metadata": [ @@ -966,7 +975,7 @@ async def comprehensive_analysis_tool( } } }) - + # Process reports for source in research_sources["reports"]: citation_count += 1 @@ -979,7 +988,7 @@ async def comprehensive_analysis_tool( "date_accessed": datetime.now().isoformat(), "source": source["title"], "organization": source["organization"], - "report_number": source["report_number"], + "report_number": source["report_number"], "publication_date": source["date"], "type": "research_report" } @@ -990,14 +999,15 @@ async def comprehensive_analysis_tool( } } }) - + return f""" + # Analysis Complete Comprehensive analysis of '{query}' has been completed using {citation_count} authoritative sources: - **{len(research_sources['academic'])}** Academic journal articles -- **{len(research_sources['web_sources'])}** Industry web sources +- **{len(research_sources['web_sources'])}** Industry web sources - **{len(research_sources['reports'])}** Research reports All sources have been properly cited and are available for review by clicking the citation links above. @@ -1016,28 +1026,28 @@ async def database_query_tool( Queries database and provides data citations ✅ Works perfectly in both function calling modes """ - + if not __event_emitter__: return "Database query executed" - + # Simulate database results with citation metadata query_results = [ { "record_id": "USR_001247", "data": "John Smith, Software Engineer, joined 2023-01-15", - "table": "employees", + "table": "employees", "last_updated": "2024-03-10T14:30:00Z", "updated_by": "admin_user" }, { - "record_id": "USR_001248", + "record_id": "USR_001248", "data": "Jane Wilson, Product Manager, joined 2023-02-20", "table": "employees", - "last_updated": "2024-03-08T09:15:00Z", + "last_updated": "2024-03-08T09:15:00Z", "updated_by": "hr_system" } ] - + # Create citations for each database record for i, record in enumerate(query_results): await __event_emitter__({ @@ -1061,15 +1071,16 @@ async def database_query_tool( } } }) - + return f""" + # Database Query Results Executed query: `{sql_query}` Retrieved **{len(query_results)}** records with complete citation metadata. Each record includes: - Record ID and source table -- Last modification timestamp +- Last modification timestamp - Update attribution - Full audit trail @@ -1090,7 +1101,7 @@ await __event_emitter__({ }) ``` -**File Events** +**File Events** ```python await __event_emitter__({ "type": "files", # or "chat:message:files" @@ -1101,7 +1112,7 @@ await __event_emitter__({ **Follow-up Events** ```python await __event_emitter__({ - "type": "chat:message:follow_ups", + "type": "chat:message:follow_ups", "data": {"follow_ups": ["What about X?", "Tell me more about Y"]} }) ``` @@ -1117,13 +1128,13 @@ await __event_emitter__({ **Tag Events** ```python await __event_emitter__({ - "type": "chat:tags", + "type": "chat:tags", "data": {"tags": ["research", "analysis", "completed"]} }) ``` **Error Events** -```python +```python await __event_emitter__({ "type": "chat:message:error", "data": {"content": "Error message to display"} @@ -1141,7 +1152,7 @@ await __event_emitter__({ **Input Request Events** ```python await __event_emitter__({ - "type": "input", + "type": "input", "data": {"prompt": "Please enter additional information:"} }) ``` @@ -1202,7 +1213,7 @@ Choosing the right function calling mode is crucial for your tool's functionalit - Educational tools that show step-by-step processes - Any tool that needs `message`, `replace`, or `chat:message` events -**Choose Native Mode For:** +**Choose Native Mode For:** - Simple API calls or database queries - Basic calculations or data transformations - Tools that only need status updates and citations @@ -1218,64 +1229,64 @@ async def mode_adaptive_tool( Tool that adapts its behavior based on function calling mode ✅ Provides optimal experience in both modes """ - + # Detect current mode mode = "default" if __metadata__: mode = __metadata__.get("params", {}).get("function_calling", "default") - + is_native_mode = (mode == "native") - + if not __event_emitter__: return "Tool executed successfully (no event support)" - + # Always safe: status updates work in both modes await __event_emitter__({ "type": "status", "data": {"description": f"Running in {mode} mode...", "done": False} }) - + # Mode-specific logic if is_native_mode: # Native mode: use compatible events only await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Processing with native efficiency...", "done": False} }) - + # Simulate processing await asyncio.sleep(1) - + # Return results directly - no message streaming result = f"Query '{query}' processed successfully in Native mode." - + else: - # Default mode: full event capabilities + # Default mode: full event capabilities await __event_emitter__({ "type": "message", "data": {"content": f"🔍 **Processing Query**: {query}\n\n"} }) - + await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Analyzing with full streaming...", "done": False} }) - + await asyncio.sleep(1) - + await __event_emitter__({ "type": "message", "data": {"content": "📊 **Results**: Analysis complete with detailed findings.\n\n"} }) - + result = "Query processed with full Default mode capabilities." - + # Final status (works in both modes) await __event_emitter__({ "type": "status", "data": {"description": "Processing complete!", "done": True} }) - + return result ``` @@ -1289,7 +1300,7 @@ async def mode_adaptive_tool( - **Cause**: Using message events in Native mode - **Solution**: Switch to Default mode or use status events instead -**Issue: Tool seems unresponsive** +**Issue: Tool seems unresponsive** - **Cause**: Function calling not enabled for model - **Solution**: Enable tools in Model settings or via `+` button @@ -1298,7 +1309,7 @@ async def mode_adaptive_tool( - **Solution**: Ensure parameter is included in tool method signature **Issue: Citations being overwritten** -- **Cause**: `self.citation = True` (or not set to False) +- **Cause**: `self.citation = True` (or not set to False) - **Solution**: Set `self.citation = False` in `__init__` method **Diagnostic Tool:** @@ -1309,33 +1320,33 @@ async def event_diagnostics_tool( """ Comprehensive diagnostic tool for event emitter debugging """ - + report = ["# 🔍 Event Emitter Diagnostic Report\n"] - + # Check event emitter availability if __event_emitter__: report.append("✅ Event emitter is available\n") else: report.append("❌ Event emitter is NOT available\n") return "".join(report) - - # Check metadata availability + + # Check metadata availability if __metadata__: mode = __metadata__.get("params", {}).get("function_calling", "default") report.append(f"✅ Function calling mode: **{mode}**\n") else: report.append("⚠️ Metadata not available (mode unknown)\n") mode = "unknown" - + # Check user context if __user__: report.append("✅ User context available\n") else: report.append("⚠️ User context not available\n") - + # Test compatible events (work in both modes) report.append("\n## Testing Compatible Events:\n") - + try: await __event_emitter__({ "type": "status", @@ -1344,19 +1355,19 @@ async def event_diagnostics_tool( report.append("✅ Status events: WORKING\n") except Exception as e: report.append(f"❌ Status events: FAILED - {str(e)}\n") - + try: await __event_emitter__({ - "type": "notification", + "type": "notification", "data": {"content": "Test notification"} }) report.append("✅ Notification events: WORKING\n") except Exception as e: report.append(f"❌ Notification events: FAILED - {str(e)}\n") - + # Test problematic events (broken in Native mode) report.append("\n## Testing Mode-Dependent Events:\n") - + try: await __event_emitter__({ "type": "message", @@ -1365,20 +1376,20 @@ async def event_diagnostics_tool( report.append("✅ Message events: SENT (may disappear in Native mode)\n") except Exception as e: report.append(f"❌ Message events: FAILED - {str(e)}\n") - + # Final status await __event_emitter__({ - "type": "status", + "type": "status", "data": {"description": "Diagnostic complete", "done": True} }) - + # Mode-specific recommendations report.append("\n## Recommendations:\n") - + if mode == "native": report.append(""" ⚠️ **Native Mode Detected**: Limited event support -- ✅ Use: status, citation, notification, files events +- ✅ Use: status, citation, notification, files events - ❌ Avoid: message, replace, chat:message events - 💡 Switch to Default mode for full functionality """) @@ -1394,7 +1405,7 @@ async def event_diagnostics_tool( - Ensure function calling is enabled - Verify model supports tool calling """) - + return "".join(report) ``` @@ -1404,6 +1415,7 @@ async def event_diagnostics_tool( **Always Compatible (Both Modes):** ```python + # Status updates - perfect for progress tracking await __event_emitter__({ "type": "status", @@ -1412,14 +1424,14 @@ await __event_emitter__({ # Citations - essential for source attribution await __event_emitter__({ - "type": "citation", + "type": "citation", "data": { "document": ["Content"], "source": {"name": "Source", "url": "https://example.com"} } }) -# Notifications - user alerts +# Notifications - user alerts await __event_emitter__({ "type": "notification", "data": {"content": "Task completed!"} @@ -1428,24 +1440,25 @@ await __event_emitter__({ **Default Mode Only (Broken in Native):** ```python + # ⚠️ These will flicker/disappear in Native mode -# Progressive content streaming +# Progressive content streaming await __event_emitter__({ - "type": "message", + "type": "message", "data": {"content": "Streaming content..."} }) # Content replacement await __event_emitter__({ "type": "replace", - "data": {"content": "New complete content"} + "data": {"content": "New complete content"} }) # Delta updates await __event_emitter__({ "type": "chat:message:delta", - "data": {"content": "Additional content"} + "data": {"content": "Additional content"} }) ``` @@ -1487,7 +1500,7 @@ from fastapi.responses import HTMLResponse def create_visualization_tool(self, data: str) -> HTMLResponse: """ Creates an interactive data visualization that embeds in the chat. - + :param data: The data to visualize """ html_content = """ @@ -1509,7 +1522,7 @@ def create_visualization_tool(self, data: str) -> HTMLResponse: """ - + headers = {"Content-Disposition": "inline"} return HTMLResponse(content=html_content, headers=headers) ``` @@ -1535,7 +1548,7 @@ When embedding external content, several security options can be configured thro Rich UI embedding is perfect for: - **Interactive dashboards**: Real-time data visualization and controls -- **Form interfaces**: Complex input forms with validation and dynamic behavior +- **Form interfaces**: Complex input forms with validation and dynamic behavior - **Charts and graphs**: Interactive plotting with libraries like Plotly, D3.js, or Chart.js - **Media players**: Video, audio, or interactive media content - **Custom widgets**: Specialized UI components for specific tool functionality @@ -1562,7 +1575,7 @@ async def create_dashboard(): """ - + return HTMLResponse( content=html, headers={"Content-Disposition": "inline"} @@ -1579,7 +1592,6 @@ Keep in mind that as pip is used in the same process as Open WebUI, the UI will No measures are taken to handle package conflicts with Open WebUI's requirements. That means that specifying requirements can break Open WebUI if you're not careful. You might be able to work around this by specifying `open-webui` itself as a requirement. -
Example @@ -1589,6 +1601,7 @@ title: myToolName author: myName funding_url: [any link here will be shown behind a `Heart` button for users to show their support to you] version: 1.0.0 + # the version is displayed in the UI to help users keep track of updates. license: GPLv3 description: [recommended] diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index d3673d15e9..2ba99e17b7 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 2 -title: "⚙️ Tools" +sidebar_position: 2 +title: "⚙️ Tools" --- # ⚙️ What are Tools? @@ -19,12 +19,11 @@ Here are just a few examples of what Tools let your AI assistant do: - 🖼️ Image Generation: Create images from your prompts. - 🔊 Voice Output: Generate AI voices using ElevenLabs. -Explore ready-to-use tools here: +Explore ready-to-use tools here: 🧰 [Tools Showcase](https://openwebui.com/tools) --- - ## 📦 How to Install Tools There are two easy ways to install Tools in Open WebUI: @@ -34,10 +33,13 @@ There are two easy ways to install Tools in Open WebUI: 3. Enter your Open WebUI instance’s IP address or URL. 4. Click “Import to WebUI” — done! -🛑 Safety Tip: Never import a Tool you don’t recognize or trust. These are Python scripts and might run unsafe code. +::warning ---- +Safety Tip: Never import a Tool you don’t recognize or trust. These are Python scripts and might run unsafe code. + +::: +--- ## 🔧 How to Use Tools in Open WebUI @@ -49,7 +51,11 @@ You have two ways to enable a Tool for your model: While chatting, click the ➕ icon in the input area. You’ll see a list of available Tools — you can enable any of them on the fly for that session. -💡 Tip: Enabling a Tool gives the model permission to use it — but it may not use it unless it's useful for the task. +::tip + +Tip: Enabling a Tool gives the model permission to use it — but it may not use it unless it's useful for the task. + +::: ### ✏️ Option 2: Enable by Default (Recommended for Frequent Use) 1. Go to: Workspace ➡️ Models @@ -87,16 +93,16 @@ This is the default setting in Open WebUI. Here, your LLM doesn’t need to natively support function calling. Instead, we guide the model using smart tool selection prompt template to select and use a Tool. -✅ Works with almost any model -✅ Great way to unlock Tools with basic or local models +✅ Works with almost any model +✅ Great way to unlock Tools with basic or local models ❗ Not as reliable or flexible as Native Mode when chaining tools ### 🟢 Native Mode (Function Calling Built-In) If your model does support “native” function calling (like GPT-4o or GPT-3.5-turbo-1106), you can use this powerful mode to let the LLM decide — in real time — when and how to call multiple Tools during a single chat message. -✅ Fast, accurate, and can chain multiple Tools in one response -✅ The most natural and advanced experience +✅ Fast, accurate, and can chain multiple Tools in one response +✅ The most natural and advanced experience ❗ Requires a model that actually supports native function calling ### ✳️ How to Switch Between Modes @@ -111,7 +117,7 @@ Want to enable native function calling in your chats? Here's how: That’s it! Your chat is now using true native Tool support (as long as the model supports it). -➡️ We recommend using GPT-4o or another OpenAI model for the best native function-calling experience. +➡️ We recommend using GPT-4o or another OpenAI model for the best native function-calling experience. 🔎 Some local models may claim support, but often struggle with accurate or complex Tool usage. 💡 Summary: @@ -119,7 +125,7 @@ That’s it! Your chat is now using true native Tool support (as long as the mod | Mode | Who it’s for | Pros | Cons | |----------|----------------------------------|-----------------------------------------|--------------------------------------| | Default | Any model | Broad compatibility, safer, flexible | May be less accurate or slower | -| Native | GPT-4o, etc. | Fast, smart, excellent tool chaining | Needs proper function call support | +| Native | GPT-4o, etc. | Fast, smart, excellent tool chaining | Needs proper function call support | Choose the one that works best for your setup — and remember, you can always switch on the fly via Chat Controls. diff --git a/docs/features/rag.md b/docs/features/rag.md index 84dee140ab..b3060c6d62 100644 --- a/docs/features/rag.md +++ b/docs/features/rag.md @@ -29,7 +29,9 @@ You can also load documents into the workspace area with their access by startin 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 @@ -61,6 +63,7 @@ A variety of parsers extract content from local and remote documents. For more, When paired with a Google Cloud project that has the Google Picker API and Google Drive API enabled, this feature allows users to directly access their Drive files from the chat interface and upload documents, slides, sheets and more and uploads them as context to your chat. Can be enabled `Admin Panel` > `Settings` > `Documents` menu. Must set [`GOOGLE_DRIVE_API_KEY and GOOGLE_DRIVE_CLIENT_ID`](https://github.com/open-webui/docs/blob/main/docs/getting-started/env-configuration.md) environment variables to use. ### Detailed Instructions + 1. Create an OAuth 2.0 client and configure both the Authorized JavaScript origins & Authorized redirect URI to be the URL (include the port if any) you use to access your Open-WebUI instance. 1. Make a note of the Client ID associated with that OAuth client. 1. Make sure that you enable both Google Drive API and Google Picker API for your project. diff --git a/docs/features/scim.mdx b/docs/features/scim.mdx index 0ddea9dc8b..afc2fa31b9 100644 --- a/docs/features/scim.mdx +++ b/docs/features/scim.mdx @@ -26,17 +26,21 @@ Configure SCIM by setting these environment variables: - **`SCIM_ENABLED`**: Set to `true` to enable SCIM support (default: `false`) - **`SCIM_TOKEN`**: The bearer token for SCIM authentication (required when SCIM is enabled) -:::warning Security Note +:::warning + +Security Note The SCIM token should be a secure, randomly generated string. You can generate one using: ```bash openssl rand -base64 32 ``` Keep this token secure as it provides access to user management operations. + ::: ### Example Configuration ```bash + # Enable SCIM export SCIM_ENABLED=true @@ -60,7 +64,6 @@ When configuring your identity provider, use the following settings: 3. Set authentication to "HTTP Header" 4. Add Authorization header with value: `Bearer your-scim-token` - ## Supported SCIM Operations Open WebUI's SCIM implementation supports the following operations: @@ -137,6 +140,7 @@ Supported filter operators: You can test SCIM endpoints using curl: ```bash + # Test authentication and list users curl -H "Authorization: Bearer your-scim-token" \ https://your-domain.com/api/v1/scim/v2/Users diff --git a/docs/features/sso/index.mdx b/docs/features/sso/index.mdx index dd2c382c80..6de93fd758 100644 --- a/docs/features/sso/index.mdx +++ b/docs/features/sso/index.mdx @@ -39,17 +39,17 @@ You cannot have Microsoft **and** Google as providers simultaneously. | Environment Variable | Default | Description | |---------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------| -| `WEBUI_URL` | — | **Required.** Your public WebUI address, e.g., `http://localhost:8080`. | -| `ENABLE_OAUTH_PERSISTENT_CONFIG` | `true` | Persist OAuth config to the database; set to `false` for stateless/containerized environments. | -| `ENABLE_OAUTH_SIGNUP` | `false` | Allows account creation upon OAuth login (separate from `ENABLE_SIGNUP`). | -| `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` | `false` | Merge OAuth logins based on matching email (caution: can be insecure if provider doesn't verify emails). | -| `OAUTH_UPDATE_PICTURE_ON_LOGIN` | `true` | Update user profile pictures from OAuth provider with each login. | +| `WEBUI_URL` | — | **Required.** Your public WebUI address, e.g., `http://localhost:8080`. | +| `ENABLE_OAUTH_PERSISTENT_CONFIG` | `true` | Persist OAuth config to the database; set to `false` for stateless/containerized environments. | +| `ENABLE_OAUTH_SIGNUP` | `false` | Allows account creation upon OAuth login (separate from `ENABLE_SIGNUP`). | +| `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` | `false` | Merge OAuth logins based on matching email (caution: can be insecure if provider doesn't verify emails). | +| `OAUTH_UPDATE_PICTURE_ON_LOGIN` | `true` | Update user profile pictures from OAuth provider with each login. | | `OAUTH_PICTURE_CLAIM` | `picture` | Field in the claim containing the profile picture. Set to empty string to disable picture updates (users receive default icon).| | `WEBUI_AUTH_SIGNOUT_REDIRECT_URL` | *empty* | Redirect users to this URL after signout. E.g., `https://your-company.com/logout-success` | | `WEBUI_SECRET_KEY` | *empty* | MUST be set - especially in clustered environments. Otherwise session issues and weird OAuth issues will occur | -| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster. | +| `OAUTH_SESSION_TOKEN_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | A secret key for encrypting OAuth tokens stored on the server. Must be shared across all instances in a cluster. | | `OAUTH_CLIENT_INFO_ENCRYPTION_KEY` | `WEBUI_SECRET_KEY` | A secret key for encrypting OAuth client information stored on the server - used for OAuth 2.1 authentication for MCP servers. | -| `ENABLE_OAUTH_ID_TOKEN_COOKIE` | `true` | For backward compatibility. Controls if the legacy `oauth_id_token` cookie is set. Recommended to set to `false`. | +| `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 @@ -71,10 +71,10 @@ To solve issues related to large tokens (e.g., with AD FS group claims exceeding **How It Works:** -1. **Server-Side Storage:** Instead of storing large `access_token` and `id_token` values in browser cookies, the entire token payload is now encrypted and stored securely in the Open WebUI database in a new `oauth_session` table. -2. **Secure Session Cookie:** The user's browser is sent a single, small, and secure `httponly` cookie named `oauth_session_id`. This cookie acts as an opaque identifier, containing no sensitive information itself. -3. **Automatic Refresh:** When a token is required by a downstream service (like a tool or an OpenAI-compatible endpoint), the backend uses the `oauth_session_id` to retrieve the tokens. If the tokens are expired or close to expiring, the system automatically uses the stored `refresh_token` to fetch new ones from the provider before forwarding them. This ensures services always receive a valid token and prevents silent failures. -4. **Clean Token Access:** This architecture provides a clean and reliable way for internal tools and other services to access user tokens without fragile cookie-scraping. +1. **Server-Side Storage:** Instead of storing large `access_token` and `id_token` values in browser cookies, the entire token payload is now encrypted and stored securely in the Open WebUI database in a new `oauth_session` table. +2. **Secure Session Cookie:** The user's browser is sent a single, small, and secure `httponly` cookie named `oauth_session_id`. This cookie acts as an opaque identifier, containing no sensitive information itself. +3. **Automatic Refresh:** When a token is required by a downstream service (like a tool or an OpenAI-compatible endpoint), the backend uses the `oauth_session_id` to retrieve the tokens. If the tokens are expired or close to expiring, the system automatically uses the stored `refresh_token` to fetch new ones from the provider before forwarding them. This ensures services always receive a valid token and prevents silent failures. +4. **Clean Token Access:** This architecture provides a clean and reliable way for internal tools and other services to access user tokens without fragile cookie-scraping. This system is enabled by default but can be fine-tuned with the environment variables detailed above. @@ -167,20 +167,28 @@ You can configure the following environment variables: 1. `OAUTH_GROUP_CLAIM` - The claim in the ID/access token containing the user's group memberships. Defaults to `groups`. Can also be nested, for example `user.memberOf`. Required if `ENABLE_OAUTH_GROUP_MANAGEMENT` is true. 1. `ENABLE_OAUTH_GROUP_CREATION` - If `true` (and `ENABLE_OAUTH_GROUP_MANAGEMENT` is also `true`), Open WebUI will perform **Just-in-Time (JIT) group creation**. This means it will automatically create groups during OAuth login if they are present in the user's OAuth claims but do not yet exist in the system. Defaults to `false`. If `false`, only memberships in *existing* Open WebUI groups will be managed. -:::warning Strict Group Synchronization +:::warning + +Strict Group Synchronization When `ENABLE_OAUTH_GROUP_MANAGEMENT` is set to `true`, a user's group memberships in Open WebUI are **strictly synchronized** with the groups received in their OAuth claims upon each login. * Users will be **added** to Open WebUI groups that match their OAuth claims. * Users will be **removed** from any Open WebUI groups (including those manually created or assigned within Open WebUI) if those groups are **not** present in their OAuth claims for that login session. Ensure all necessary groups are correctly configured in your OAuth provider and included in the group claim (`OAUTH_GROUP_CLAIM`). + ::: -:::warning Admin Users +:::warning + +Admin Users Admin users' group memberships are **not** automatically updated via OAuth group management. + ::: -:::info Login Required for Updates +:::info + +Login Required for Updates If a user's groups change in the OAuth provider, they will need to log out of Open WebUI and log back in for the changes to be reflected. @@ -204,10 +212,9 @@ When the `WEBUI_AUTH_TRUSTED_EMAIL_HEADER` environment variable is set, Open Web 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. +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. If `WEBUI_AUTH_TRUSTED_NAME_HEADER` is not set, the email address is used as user name. - #### Group Management You can use the `WEBUI_AUTH_TRUSTED_GROUPS_HEADER` environment variable to synchronize user groups in Open WebUI. Set this variable to the name of the HTTP header that will contain a comma-separated list of group names for the authenticated user. @@ -217,7 +224,6 @@ When a request is authenticated via `WEBUI_AUTH_TRUSTED_EMAIL_HEADER`, and the t - The header value must be a comma-separated list of group names (e.g., `X-User-Groups: admins,editors,users`). - If the header is not present or empty, the user's group memberships will not be updated. - User will be unassigned from groups not present in the header. -- Group creation via trusted header is not automatic; only existing groups in Open WebUI will be assigned. ### Tailscale Serve @@ -355,7 +361,6 @@ services: - 4180:4180/tcp ``` - ### Authentik To configure a [Authentik](https://goauthentik.io/) OAuth client, please refer to [documentation](https://integrations.goauthentik.io/miscellaneous/open-webui/) on how to create an application and `OAuth2/OpenID Provider`. diff --git a/docs/features/sso/keycloak.mdx b/docs/features/sso/keycloak.mdx index 8478b2cf24..a0da03c43b 100644 --- a/docs/features/sso/keycloak.mdx +++ b/docs/features/sso/keycloak.mdx @@ -3,7 +3,9 @@ title: "Keycloak Integration" --- :::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. + ::: This guide explains how to integrate Open WebUI with Keycloak for OIDC Single Sign-On (SSO). @@ -23,26 +25,28 @@ bin/kc.sh start-dev --http-port=9090 ## 2. Create a Keycloak Realm -1. Open your browser and go to `http://localhost:9090`. Create an administrator account. -2. Log in to the admin console at `http://localhost:9090/admin`. -3. From the realm dropdown at the top, click **Add realm**. -4. Enter `openwebui` as the **Realm name** and click **Create**. +1. Open your browser and go to `http://localhost:9090`. Create an administrator account. +2. Log in to the admin console at `http://localhost:9090/admin`. +3. From the realm dropdown at the top, click **Add realm**. +4. Enter `openwebui` as the **Realm name** and click **Create**. ![create-realm](/images/features/auth/keycloak/create-realm.png) ## 3. Create an OpenID Connect Client :::info + Make sure you have selected the `openwebui` realm. The default is `master`. + ::: ![select-realm](/images/features/auth/keycloak/select-realm.png) -1. Ensure the `openwebui` realm you just created is selected. -2. In the left menu, click **Clients** → **Create client**. -3. Set **Client ID** to `open-webui`. -4. Keep **Client protocol** as `openid-connect`. -5. Set **Access Type** to `confidential` and click **Save**. +1. Ensure the `openwebui` realm you just created is selected. +2. In the left menu, click **Clients** → **Create client**. +3. Set **Client ID** to `open-webui`. +4. Keep **Client protocol** as `openid-connect`. +5. Set **Access Type** to `confidential` and click **Save**. ![access-setting-client](/images/features/auth/keycloak/access-setting-client.png) @@ -50,21 +54,21 @@ Make sure you have selected the `openwebui` realm. The default is `master`. By default, Keycloak 26.x sets Client Authentication to "None", so it needs to be configured manually. -1. Go to **Clients** → **open-webui** → **Settings**. -2. Check the **Client Authenticator** dropdown. -3. Change "None" to **Client ID and secret** and click **Save**. -4. Click the **Advanced** tab. -5. In the **Client authentication** section, click **Reveal secret** and copy the secret. -6. Paste this secret into the `OAUTH_CLIENT_SECRET` variable in your `.env` file. +1. Go to **Clients** → **open-webui** → **Settings**. +2. Check the **Client Authenticator** dropdown. +3. Change "None" to **Client ID and secret** and click **Save**. +4. Click the **Advanced** tab. +5. In the **Client authentication** section, click **Reveal secret** and copy the secret. +6. Paste this secret into the `OAUTH_CLIENT_SECRET` variable in your `.env` file. {/* TODO: Insert image of Advanced tab Client Authenticator settings */} ## 5. Create a Test User -1. In the left menu, go to **Users** → **Add user**. -2. Fill in the **Username**, **Email**, etc., and click **Save**. -3. Click on the newly created user, then go to the **Credentials** tab. -4. Enter a new password, uncheck **Temporary**, and click **Set Password**. +1. In the left menu, go to **Users** → **Add user**. +2. Fill in the **Username**, **Email**, etc., and click **Save**. +3. Click on the newly created user, then go to the **Credentials** tab. +4. Enter a new password, uncheck **Temporary**, and click **Set Password**. - *Example: Username `testuser`, Password `Test1234!`* ## 6. Configure Open WebUI .env @@ -72,6 +76,7 @@ By default, Keycloak 26.x sets Client Authentication to "None", so it needs to b Add or modify the following variables in your `.env` file. ```env + # Enable OAuth2/OIDC Login ENABLE_OAUTH_SIGNUP=true @@ -105,9 +110,9 @@ OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback ## 8. Test the Integration -1. Go to `http://localhost:8080`. You should see a "Continue with Keycloak" button. -2. Click the button. You should be redirected to the Keycloak login page. -3. Log in with `testuser` / `Test1234!`. You should be successfully redirected back to Open WebUI. +1. Go to `http://localhost:8080`. You should see a "Continue with Keycloak" button. +2. Click the button. You should be redirected to the Keycloak login page. +3. Log in with `testuser` / `Test1234!`. You should be successfully redirected back to Open WebUI. {/* TODO: Insert image of the actual login screen */} @@ -117,15 +122,15 @@ OPENID_REDIRECT_URI=http://localhost:8080/oauth/oidc/callback By default, Keycloak clients do not include group information in tokens. Follow these steps to pass group information. ### 9.2. Locate Mapper Creation -1. Go to the Keycloak Admin Console: `http://localhost:9090/admin`. -2. Select the `openwebui` realm. -3. Navigate to **Clients** and select the `open-webui` client. -4. Go to the **Client scopes** tab. -5. Select the scope that will contain the group information (e.g., `profile` or `open-webui-dedicated`). +1. Go to the Keycloak Admin Console: `http://localhost:9090/admin`. +2. Select the `openwebui` realm. +3. Navigate to **Clients** and select the `open-webui` client. +4. Go to the **Client scopes** tab. +5. Select the scope that will contain the group information (e.g., `profile` or `open-webui-dedicated`). ![scope-client](/images/features/auth/keycloak/scope-client.png) -6. In the selected scope's details, go to the **Mappers** tab. +6. In the selected scope's details, go to the **Mappers** tab. ### 9.3. Create Mapper Click **Create** or **Add builtin** to start creating a new mapper. @@ -143,9 +148,12 @@ Configure the mapper with the appropriate settings to include group membership. Add or modify these variables in your `.env` file: ```env + # Enable group synchronization ENABLE_OAUTH_GROUP_MANAGEMENT=true + # (Optional) Enable Just-In-Time group creation ENABLE_OAUTH_GROUP_CREATION=true + # The claim key for groups in the token OAUTH_GROUP_CLAIM=groups diff --git a/docs/features/webhooks.md b/docs/features/webhooks.md index da7b1ee3a3..a8454dd553 100644 --- a/docs/features/webhooks.md +++ b/docs/features/webhooks.md @@ -4,12 +4,12 @@ title: "🪝 Webhook Integrations" --- Overview --------- +--- Open WebUI provides a webhook feature that allows you to receive notifications automatically whenever new users sign up to your instance. This is done by providing a webhook URL to Open WebUI, which will then send notifications to that URL when a new user account is created. Configuring Webhooks in Open WebUI ---------------------------------- +--- You will need to obtain a webhook URL from an external service that supports webhooks, such as a Discord channel or a Slack workspace. This URL will be used to receive notifications from Open WebUI. @@ -33,7 +33,7 @@ Alternatively, you can configure the webhook URL by setting the `WEBHOOK_URL` en To verify that the webhook is working correctly, create a new user account in Open WebUI. If the webhook is configured correctly, you should receive a notification at the specified webhook URL. Webhook Payload Format ----------------------- +--- The webhook payload sent by Open WebUI is in plain text and contains a simple notification message about the new user account. The payload format is as follows: @@ -48,13 +48,17 @@ New user signed up: Tim ``` Troubleshooting --------------- +--- + +- Make sure the webhook URL is correct and properly formatted. +- Verify that the webhook service is enabled and configured correctly. +- Check the Open WebUI logs for any errors related to the webhook. +- Verify the connection hasn't been interrupted or blocked by a firewall or proxy. +- The webhook server could be temporarily unavailable or experiencing high latency. +- If provided through the webhook service, verify if the Webhook API key is invalid, expired, or revoked. -* Make sure the webhook URL is correct and properly formatted. -* Verify that the webhook service is enabled and configured correctly. -* Check the Open WebUI logs for any errors related to the webhook. -* Verify the connection hasn't been interrupted or blocked by a firewall or proxy. -* The webhook server could be temporarily unavailable or experiencing high latency. -* If provided through the webhook service, verify if the Webhook API key is invalid, expired, or revoked. +:::note Note: The webhook feature in Open WebUI is still evolving, and we plan to add more features and event types in the future. + +::: diff --git a/docs/features/workspace/groups.md b/docs/features/workspace/groups.md index 5859a90a53..111b14a63d 100644 --- a/docs/features/workspace/groups.md +++ b/docs/features/workspace/groups.md @@ -4,41 +4,44 @@ title: "🔐 Groups" --- Groups allow administrators to -* assign permissions to multiple users at once, simplifying access management -* limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups -* Specify access to a resource for a group to either "read" or "write" (write access implies read) + +- assign permissions to multiple users at once, simplifying access management +- limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups +- Specify access to a resource for a group to either "read" or "write" (write access implies read) :::info + Note that the permissions model is permissive. If a user is a member of two groups that define different permissions for a resource, the most permissive permission is applied. + ::: ### Group Structure Each group in Open WebUI contains: -* A unique identifier -* Name and description -* Owner/creator reference -* List of member user IDs -* Permission configuration -* Additional metadata +- A unique identifier +- Name and description +- Owner/creator reference +- List of member user IDs +- Permission configuration +- Additional metadata ### Group Management Groups can be: -* **Created manually** by administrators through the user interface -* **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled -* **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION` +- **Created manually** by administrators through the user interface +- **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled +- **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION` are enabled ### OAuth Group Integration When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims: -* Users are added to Open WebUI groups that match their OAuth claims -* Users are removed from groups not present in their OAuth claims -* With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically +- Users are added to Open WebUI groups that match their OAuth claims +- Users are removed from groups not present in their OAuth claims +- With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically created ## Group Permissions diff --git a/docs/features/workspace/index.mdx b/docs/features/workspace/index.mdx index 38c0a05fe4..60407c637a 100644 --- a/docs/features/workspace/index.mdx +++ b/docs/features/workspace/index.mdx @@ -18,4 +18,4 @@ Each section of the Workspace is designed to give you fine-grained control over - [‍🔐 Groups](./groups.md) - Setup groups of users to share access to resources - [🔒 Permissions](./permissions.md) - Configure access controls and feature availability -Roles, groups and permissions are designed to work together to provide a finegrained model for controlling user access to individual resources. +Roles, groups and permissions are designed to work together to provide a finegrained model for controlling user access to individual resources. diff --git a/docs/features/workspace/models.md b/docs/features/workspace/models.md index f92295bacc..6f1804ca1b 100644 --- a/docs/features/workspace/models.md +++ b/docs/features/workspace/models.md @@ -9,32 +9,32 @@ The `Models` section of the `Workspace` within Open WebUI is a powerful tool tha 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. +- **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. +- **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 importing and exporting models: -* **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. +- **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. To download models, navigate to the **Ollama Settings** in the Connections tab. Alternatively, you can also download models directly by typing a command like `ollama run hf.co/[model creator]/[model name]` in the model selection dropdown. @@ -44,12 +44,12 @@ This action will create a button labeled "Pull [Model Name]" for downloading. **Example**: Switching between **Mistral**, **LLaVA**, and **GPT-3.5** in a Multi-Stage Task -* **Scenario**: A multi-stage conversation involves different task types, such as starting with a simple FAQ, interpreting an image, and then generating a creative response. -* **Reason for Switching**: The user can leverage each model's specific strengths for each stage: - * **Mistral** for general questions to reduce computation time and costs. - * **LLaVA** for visual tasks to gain insights from image-based data. - * **GPT-3.5** for generating more sophisticated and nuanced language output. -* **Process**: The user switches between models, depending on the task type, to maximize efficiency and response quality. +- **Scenario**: A multi-stage conversation involves different task types, such as starting with a simple FAQ, interpreting an image, and then generating a creative response. +- **Reason for Switching**: The user can leverage each model's specific strengths for each stage: + - **Mistral** for general questions to reduce computation time and costs. + - **LLaVA** for visual tasks to gain insights from image-based data. + - **GPT-3.5** for generating more sophisticated and nuanced language output. +- **Process**: The user switches between models, depending on the task type, to maximize efficiency and response quality. **How To**: 1. **Select the Model**: Within the chat interface, select the desired models from the model switcher dropdown. You can select up to two models simultaneously, and both responses will be generated. You can then navigate between them by using the back and forth arrows. diff --git a/docs/features/workspace/permissions.md b/docs/features/workspace/permissions.md index c0c405af47..39c426b6a9 100644 --- a/docs/features/workspace/permissions.md +++ b/docs/features/workspace/permissions.md @@ -15,41 +15,43 @@ Administrators can manage permissions in the following ways: Workspace permissions control access to core components of the Open WebUI platform: -* **Models Access**: Toggle to allow users to access and manage custom models. (Environment variable: `USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS`) -* **Knowledge Access**: Toggle to allow users to access and manage knowledge bases. (Environment variable: `USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS`) -* **Prompts Access**: Toggle to allow users to access and manage saved prompts. (Environment variable: `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS`) -* **Tools Access**: Toggle to allow users to access and manage tools. (Environment variable: `USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS`) *Note: Enabling this gives users the ability to upload arbitrary code to the server.* +- **Models Access**: Toggle to allow users to access and manage custom models. (Environment variable: `USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS`) +- **Knowledge Access**: Toggle to allow users to access and manage knowledge bases. (Environment variable: `USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS`) +- **Prompts Access**: Toggle to allow users to access and manage saved prompts. (Environment variable: `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS`) +- **Tools Access**: Toggle to allow users to access and manage tools. (Environment variable: `USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS`) *Note: Enabling this gives users the ability to upload arbitrary code to the server.* ## Chat Permissions Chat permissions determine what actions users can perform within chat conversations: -* **Allow Chat Controls**: Toggle to enable access to chat control options. -* **Allow File Upload**: Toggle to permit users to upload files during chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_FILE_UPLOAD`) -* **Allow Chat Delete**: Toggle to permit users to delete chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_DELETE`) -* **Allow Chat Edit**: Toggle to permit users to edit messages in chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_EDIT`) -* **Allow Temporary Chat**: Toggle to permit users to create temporary chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_TEMPORARY`) +- **Allow Chat Controls**: Toggle to enable access to chat control options. +- **Allow File Upload**: Toggle to permit users to upload files during chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_FILE_UPLOAD`) +- **Allow Chat Delete**: Toggle to permit users to delete chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_DELETE`) +- **Allow Chat Edit**: Toggle to permit users to edit messages in chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_EDIT`) +- **Allow Temporary Chat**: Toggle to permit users to create temporary chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_TEMPORARY`) ## Features Permissions Features permissions control access to specialized capabilities within Open WebUI: -* **Web Search**: Toggle to allow users to perform web searches during chat sessions. (Environment variable: `ENABLE_RAG_WEB_SEARCH`) -* **Image Generation**: Toggle to allow users to generate images. (Environment variable: `ENABLE_IMAGE_GENERATION`) -* **Code Interpreter**: Toggle to allow users to use the code interpreter feature. (Environment variable: `USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) -* **Direct Tool Servers**: Toggle to allow users to connect directly to tool servers. (Environment variable: `USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS`) +- **Web Search**: Toggle to allow users to perform web searches during chat sessions. (Environment variable: `ENABLE_RAG_WEB_SEARCH`) +- **Image Generation**: Toggle to allow users to generate images. (Environment variable: `ENABLE_IMAGE_GENERATION`) +- **Code Interpreter**: Toggle to allow users to use the code interpreter feature. (Environment variable: `USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) +- **Direct Tool Servers**: Toggle to allow users to connect directly to tool servers. (Environment variable: `USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS`) ## Default Permission Settings By default, Open WebUI applies the following permission settings: **Workspace Permissions**: + - Models Access: Disabled (`USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS=False`) - Knowledge Access: Disabled (`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS=False`) - Prompts Access: Disabled (`USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS=False`) - Tools Access: Disabled (`USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS=False`) **Chat Permissions**: + - Allow Chat Controls: Enabled - Allow File Upload: Enabled (`USER_PERMISSIONS_CHAT_FILE_UPLOAD=True`) - Allow Chat Delete: Enabled (`USER_PERMISSIONS_CHAT_DELETE=True`) @@ -57,6 +59,7 @@ By default, Open WebUI applies the following permission settings: - Allow Temporary Chat: Enabled (`USER_PERMISSIONS_CHAT_TEMPORARY=True`) **Features Permissions**: + - Web Search: Enabled (`ENABLE_RAG_WEB_SEARCH=True`) - Image Generation: Enabled (`ENABLE_IMAGE_GENERATION=True`) - Code Interpreter: Enabled (`USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) diff --git a/docs/features/workspace/prompts.md b/docs/features/workspace/prompts.md index c74c056a33..3d6b0e3ffa 100644 --- a/docs/features/workspace/prompts.md +++ b/docs/features/workspace/prompts.md @@ -9,19 +9,19 @@ The `Prompts` section of the `Workspace` within Open WebUI enables users to crea The Prompts interface provides several key features for managing your custom prompts: -* **Create**: Design new prompts with customizable titles, access levels, and content. -* **Share**: Share prompts with other users based on configured access permissions. -* **Access Control**: Set visibility and usage permissions for each prompt (refer to [Permissions](./permissions.md) for more details). -* **Slash Commands**: Quickly access prompts using custom slash commands during chat sessions. +- **Create**: Design new prompts with customizable titles, access levels, and content. +- **Share**: Share prompts with other users based on configured access permissions. +- **Access Control**: Set visibility and usage permissions for each prompt (refer to [Permissions](./permissions.md) for more details). +- **Slash Commands**: Quickly access prompts using custom slash commands during chat sessions. ### Creating and Editing Prompts When creating or editing a prompt, you can configure the following settings: -* **Title**: Give your prompt a descriptive name for easy identification. -* **Access**: Set the access level to control who can view and use the prompt. -* **Command**: Define a slash command that will trigger the prompt (e.g., `/summarize`). -* **Prompt Content**: Write the actual prompt text that will be sent to the model. +- **Title**: Give your prompt a descriptive name for easy identification. +- **Access**: Set the access level to control who can view and use the prompt. +- **Command**: Define a slash command that will trigger the prompt (e.g., `/summarize`). +- **Prompt Content**: Write the actual prompt text that will be sent to the model. ### Prompt Variables @@ -29,17 +29,17 @@ Open WebUI supports two kinds of variables to make your prompts more dynamic and **System Variables** are automatically replaced with their corresponding value when the prompt is used. They are useful for inserting dynamic information like the current date or user details. -* **Clipboard Content**: Use `{{CLIPBOARD}}` to insert content from your clipboard. -* **Date and Time**: - * `{{CURRENT_DATE}}`: Current date - * `{{CURRENT_DATETIME}}`: Current date and time - * `{{CURRENT_TIME}}`: Current time - * `{{CURRENT_TIMEZONE}}`: Current timezone - * `{{CURRENT_WEEKDAY}}`: Current day of the week -* **User Information**: - * `{{USER_NAME}}`: Current user's name - * `{{USER_LANGUAGE}}`: User's selected language - * `{{USER_LOCATION}}`: User's location (requires HTTPS and Settings > Interface toggle) +- **Clipboard Content**: Use `{{CLIPBOARD}}` to insert content from your clipboard. +- **Date and Time**: + - `{{CURRENT_DATE}}`: Current date + - `{{CURRENT_DATETIME}}`: Current date and time + - `{{CURRENT_TIME}}`: Current time + - `{{CURRENT_TIMEZONE}}`: Current timezone + - `{{CURRENT_WEEKDAY}}`: Current day of the week +- **User Information**: + - `{{USER_NAME}}`: Current user's name + - `{{USER_LANGUAGE}}`: User's selected language + - `{{USER_LOCATION}}`: User's location (requires HTTPS and Settings > Interface toggle) **Custom Input Variables** transform your prompts into interactive templates. When you use a prompt containing these variables, a modal window will automatically appear, allowing you to fill in your values. This is extremely powerful for creating complex, reusable prompts that function like forms. See the guidelines below for a full explanation. @@ -47,13 +47,13 @@ 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` -* The `{{CLIPBOARD}}` system variable requires clipboard access permission from your device +- 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` +- The `{{CLIPBOARD}}` system variable requires clipboard access permission from your device --- @@ -61,23 +61,23 @@ By leveraging custom input variables, you can move beyond static text and build **How It Works** -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`. 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. +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`. 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** 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. +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. +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** @@ -91,6 +91,7 @@ To make a variable **required** (mandatory), add the `:required` flag: ``` 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 @@ -123,8 +124,9 @@ You can specify different input types to build rich, user-friendly forms. Here i Create a reusable prompt where the article content is required but additional parameters are optional. -* **Command:** `/summarize_article` -* **Prompt Content:** +- **Command:** `/summarize_article` +- **Prompt Content:** + ``` Please summarize the following article. {{article_text | textarea:placeholder="Paste the full text of the article here...":required}} @@ -134,14 +136,16 @@ Create a reusable prompt where the article content is required but additional pa {{include_quotes | checkbox}} Include key quotes from the article ``` + 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 ensures critical information is captured while allowing optional details. -* **Command:** `/bug_report` -* **Prompt Content:** +- **Command:** `/bug_report` +- **Prompt Content:** + ``` Generate a bug report with the following details: @@ -149,23 +153,25 @@ This prompt ensures critical information is captured while allowing optional det **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...":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. ``` + This creates a form where title, priority, and steps are mandatory, but additional context and workarounds are optional. **3. Social Media Post Generator with Smart Defaults** This prompt generates tailored content with required core information and optional customizations. -* **Command:** `/social_post` -* **Prompt Content:** +- **Command:** `/social_post` +- **Prompt Content:** + ``` Generate a social media post for {{platform | select:options=["LinkedIn","Twitter","Facebook","Instagram"]:required}}. - + **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"}} @@ -180,8 +186,9 @@ This prompt generates tailored content with required core information and option Generate structured meeting minutes with required basics and optional details. -* **Command:** `/meeting_minutes` -* **Prompt Content:** +- **Command:** `/meeting_minutes` +- **Prompt Content:** + ``` # Meeting Minutes @@ -210,8 +217,9 @@ Generate structured meeting minutes with required basics and optional details. A flexible template for reviewing various types of content. -* **Command:** `/content_review` -* **Prompt Content:** +- **Command:** `/content_review` +- **Prompt Content:** + ``` Please review the following {{content_type | select:options=["Blog Post","Marketing Copy","Documentation","Email","Presentation"]:required}}: @@ -230,26 +238,26 @@ A flexible template for reviewing various types of content. Prompt management is controlled by the following permission settings: -* **Prompts Access**: Users need the `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS` permission to create and manage prompts. -* For detailed information about configuring permissions, refer to the [Permissions documentation](./permissions.md). +- **Prompts Access**: Users need the `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS` permission to create and manage prompts. +- For detailed information about configuring permissions, refer to the [Permissions documentation](./permissions.md). ### Best Practices -* Use clear, descriptive titles for your prompts -* Create intuitive slash commands that reflect the prompt's purpose -* **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, 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 +- Use clear, descriptive titles for your prompts +- Create intuitive slash commands that reflect the prompt's purpose +- **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, 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 +- 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 diff --git a/docs/features/workspace/roles.md b/docs/features/workspace/roles.md index 1b508f448a..47ae67185f 100644 --- a/docs/features/workspace/roles.md +++ b/docs/features/workspace/roles.md @@ -8,14 +8,14 @@ Open WebUI implements a structured role-based access control system with three p | **Role** | **Description** | **Default Creation** | |---------------|---------------------------------------------------|----------------------------------| | Administrator | System administrator with full control | First user account | -| Regular User | Standard user with limited permissions | Subsequent approved users | +| Regular User | Standard user with limited permissions | Subsequent approved users | | Pending | Unapproved user awaiting administrator activation | New registrations (configurable) | ### Role Assignment -* **First User:** The first account created on a new Open WebUI instance automatically receives Administrator +- **First User:** The first account created on a new Open WebUI instance automatically receives Administrator privileges. -* **Subsequent Users:** New user registrations are assigned a default role based on the `DEFAULT_USER_ROLE` +- **Subsequent Users:** New user registrations are assigned a default role based on the `DEFAULT_USER_ROLE` configuration. The default role for new registrations can be configured using the `DEFAULT_USER_ROLE` environment variable: @@ -29,36 +29,37 @@ When set to "pending", new users must be manually approved by an administrator b ## User Groups Groups allow administrators to -* assign permissions to multiple users at once, simplifying access management -* limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to + +- assign permissions to multiple users at once, simplifying access management +- limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups -* Group access to a resource can be set as "read" or "write" +- Group access to a resource can be set as "read" or "write" ### Group Structure Each group in Open WebUI contains: -* A unique identifier -* Name and description -* Owner/creator reference -* List of member user IDs -* Permission configuration -* Additional metadata +- A unique identifier +- Name and description +- Owner/creator reference +- List of member user IDs +- Permission configuration +- Additional metadata ### Group Management Groups can be: -* **Created manually** by administrators through the user interface -* **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled -* **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION` +- **Created manually** by administrators through the user interface +- **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled +- **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION` are enabled ### OAuth Group Integration When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims: -* Users are added to Open WebUI groups that match their OAuth claims -* Users are removed from groups not present in their OAuth claims -* With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically +- Users are added to Open WebUI groups that match their OAuth claims +- Users are removed from groups not present in their OAuth claims +- With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically created diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index ecd9c974ea..06f696fbd0 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -67,14 +67,14 @@ Let's get the user interface (what you see in your browser) up and running first npm install ``` - This will install all frontend dependencies listed in `package.json`. + This will install all frontend dependencies listed in `package.json`. *Note: Depending on your Open WebUI version, you might see compatibility warnings or errors. If so, just run:* ```bash npm install --force ``` - + *Some setups need this to get around version issues.* 2. **Start the Frontend Development Server:** @@ -87,7 +87,6 @@ Let's get the user interface (what you see in your browser) up and running first 🎉 **Access the Frontend:** Open your web browser and go to [http://localhost:5173](http://localhost:5173). You should see a message indicating that Open WebUI's frontend is running and is waiting for the backend to be available. Don't worry about that message yet! Let's set up the backend next. **Keep this terminal running** – it's serving your frontend! - ### 2.5: Build the Frontend (Recommended) Once you’ve verified that the frontend development server (`npm run dev`) is running correctly and you can see Open WebUI at [http://localhost:5173](http://localhost:5173), it's a **good practice to also build the frontend assets**. This step simulates the production environment and can help catch build-time errors that don't show up during development. @@ -102,7 +101,6 @@ npm run build - If the build completes successfully (without errors), you're ready! If there are errors, address them before proceeding. - You don't need to do anything more with `build` for local development, but building ensures your code will not break in production or during deployment. - ### 3. Backend Setup (API and Server) We **require** you to use separate terminal instances for your frontend and backend processes. This keeps your workflows organized and makes it easier to manage each part of the application independently. @@ -137,7 +135,7 @@ VS Code's integrated terminal feature makes managing multiple terminals incredib - `conda create --name open-webui python=3.11`: This command creates a new Conda environment named `open-webui` using Python version 3.11. If you chose a different Python 3.11.x version, that's fine. - `conda activate open-webui`: This command activates the newly created Conda environment. Once activated, your terminal prompt will usually change to indicate you are in the `open-webui` environment (e.g., it might show `(open-webui)` at the beginning of the line). - + **Make sure you activate the environment in your backend terminal before proceeding.** *(Using Conda is optional but strongly recommended for managing Python dependencies and avoiding conflicts.)* If you choose not to use Conda, ensure you are using Python 3.11 or higher and proceed to the next step, but be aware of potential dependency conflicts. @@ -234,7 +232,7 @@ Hot reload (or hot module replacement - HMR) is a fantastic development feature - Alternatively, you can try clearing your browser cache or opening the frontend in a private/incognito browser window. 4. **Dependency Issues (Frontend):** Outdated or corrupted frontend dependencies can sometimes interfere with hot reloading. Try refreshing your frontend dependencies: - In your *frontend* terminal, run: - + ```bash rm -rf node_modules && npm install ``` @@ -260,7 +258,7 @@ We warmly welcome your contributions to Open WebUI! Your help is valuable in mak This helps ensure that your contribution aligns with the project's goals and avoids wasted effort on features that might not be merged. 4. **Create a Separate Branch for Your Work:** **Never commit directly to the `dev` branch.** Always create a new branch for each feature or bug fix you are working on. This keeps your changes isolated and makes it easier to manage and submit pull requests. - To create a new branch (e.g., named `my-feature-branch`) based on the `dev` branch: - + ```bash git checkout dev git pull origin dev # Ensure your local dev branch is up-to-date diff --git a/docs/getting-started/advanced-topics/https-encryption.md b/docs/getting-started/advanced-topics/https-encryption.md index 5045fda12d..908cae7b63 100644 --- a/docs/getting-started/advanced-topics/https-encryption.md +++ b/docs/getting-started/advanced-topics/https-encryption.md @@ -11,39 +11,39 @@ This guide explains how to enable HTTPS encryption for your Open WebUI instance. HTTPS (Hypertext Transfer Protocol Secure) encrypts communication between your web browser and the Open WebUI server. This encryption provides several key benefits: -* **Privacy and Security:** Protects sensitive data like usernames, passwords, and chat content from eavesdropping and interception, especially on public networks. -* **Integrity:** Ensures that data transmitted between the browser and server is not tampered with during transit. -* **Feature Compatibility:** **Crucially, modern browsers block access to certain "secure context" features, such as microphone access for Voice Calls, unless the website is served over HTTPS.** -* **Trust and User Confidence:** HTTPS is indicated by a padlock icon in the browser address bar, building user trust and confidence in your Open WebUI deployment. +- **Privacy and Security:** Protects sensitive data like usernames, passwords, and chat content from eavesdropping and interception, especially on public networks. +- **Integrity:** Ensures that data transmitted between the browser and server is not tampered with during transit. +- **Feature Compatibility:** **Crucially, modern browsers block access to certain "secure context" features, such as microphone access for Voice Calls, unless the website is served over HTTPS.** +- **Trust and User Confidence:** HTTPS is indicated by a padlock icon in the browser address bar, building user trust and confidence in your Open WebUI deployment. **When is HTTPS Especially Important?** -* **Internet-Facing Deployments:** If your Open WebUI instance is accessible from the public internet, HTTPS is strongly recommended to protect against security risks. -* **Voice Call Feature:** If you plan to use the Voice Call feature in Open WebUI, HTTPS is **mandatory**. -* **Sensitive Data Handling:** If you are concerned about the privacy of user data, enabling HTTPS is a crucial security measure. +- **Internet-Facing Deployments:** If your Open WebUI instance is accessible from the public internet, HTTPS is strongly recommended to protect against security risks. +- **Voice Call Feature:** If you plan to use the Voice Call feature in Open WebUI, HTTPS is **mandatory**. +- **Sensitive Data Handling:** If you are concerned about the privacy of user data, enabling HTTPS is a crucial security measure. ## Choosing the Right HTTPS Solution for You 🛠️ The best HTTPS solution depends on your existing infrastructure and technical expertise. Here are some common and effective options: -* **Cloud Providers (e.g., AWS, Google Cloud, Azure):** - * **Load Balancers:** Cloud providers typically offer managed load balancers (like AWS Elastic Load Balancer) that can handle HTTPS termination (encryption/decryption) for you. This is often the most straightforward and scalable approach in cloud environments. -* **Docker Container Environments:** - * **Reverse Proxies (Nginx, Traefik, Caddy):** Popular reverse proxies like Nginx, Traefik, and Caddy are excellent choices for managing HTTPS in Dockerized deployments. They can automatically obtain and renew SSL/TLS certificates (e.g., using Let's Encrypt) and handle HTTPS termination. - * **Nginx:** Highly configurable and widely used. - * **Traefik:** Designed for modern microservices and container environments, with automatic configuration and Let's Encrypt integration. - * **Caddy:** Focuses on ease of use and automatic HTTPS configuration. -* **Cloudflare:** - * **Simplified HTTPS:** Cloudflare provides a CDN (Content Delivery Network) and security services, including very easy HTTPS setup. It often requires minimal server-side configuration changes and is suitable for a wide range of deployments. -* **Ngrok:** - * **Local Development HTTPS:** Ngrok is a convenient tool for quickly exposing your local development server over HTTPS. It's particularly useful for testing features that require HTTPS (like Voice Calls) during development and for demos. **Not recommended for production deployments.** +- **Cloud Providers (e.g., AWS, Google Cloud, Azure):** + - **Load Balancers:** Cloud providers typically offer managed load balancers (like AWS Elastic Load Balancer) that can handle HTTPS termination (encryption/decryption) for you. This is often the most straightforward and scalable approach in cloud environments. +- **Docker Container Environments:** + - **Reverse Proxies (Nginx, Traefik, Caddy):** Popular reverse proxies like Nginx, Traefik, and Caddy are excellent choices for managing HTTPS in Dockerized deployments. They can automatically obtain and renew SSL/TLS certificates (e.g., using Let's Encrypt) and handle HTTPS termination. + - **Nginx:** Highly configurable and widely used. + - **Traefik:** Designed for modern microservices and container environments, with automatic configuration and Let's Encrypt integration. + - **Caddy:** Focuses on ease of use and automatic HTTPS configuration. +- **Cloudflare:** + - **Simplified HTTPS:** Cloudflare provides a CDN (Content Delivery Network) and security services, including very easy HTTPS setup. It often requires minimal server-side configuration changes and is suitable for a wide range of deployments. +- **Ngrok:** + - **Local Development HTTPS:** Ngrok is a convenient tool for quickly exposing your local development server over HTTPS. It's particularly useful for testing features that require HTTPS (like Voice Calls) during development and for demos. **Not recommended for production deployments.** **Key Considerations When Choosing:** -* **Complexity:** Some solutions (like Cloudflare or Caddy) are simpler to set up than others (like manually configuring Nginx). -* **Automation:** Solutions like Traefik and Caddy offer automatic certificate management, which simplifies ongoing maintenance. -* **Scalability and Performance:** Consider the performance and scalability needs of your Open WebUI instance when choosing a solution, especially for high-traffic deployments. -* **Cost:** Some solutions (like cloud load balancers or Cloudflare's paid plans) may have associated costs. Let's Encrypt and many reverse proxies are free and open-source. +- **Complexity:** Some solutions (like Cloudflare or Caddy) are simpler to set up than others (like manually configuring Nginx). +- **Automation:** Solutions like Traefik and Caddy offer automatic certificate management, which simplifies ongoing maintenance. +- **Scalability and Performance:** Consider the performance and scalability needs of your Open WebUI instance when choosing a solution, especially for high-traffic deployments. +- **Cost:** Some solutions (like cloud load balancers or Cloudflare's paid plans) may have associated costs. Let's Encrypt and many reverse proxies are free and open-source. ## 📚 Explore Deployment Tutorials for Step-by-Step Guides diff --git a/docs/getting-started/advanced-topics/index.mdx b/docs/getting-started/advanced-topics/index.mdx index 394fddd4b1..6d68dbd537 100644 --- a/docs/getting-started/advanced-topics/index.mdx +++ b/docs/getting-started/advanced-topics/index.mdx @@ -10,27 +10,27 @@ Explore deeper concepts and advanced configurations of Open WebUI to enhance you --- ## 🛠️ Development -Understand the development setup and contribute to Open WebUI. +Understand the development setup and contribute to Open WebUI. [Development Guide](/getting-started/advanced-topics/development) --- -## 📝 Logging -Learn how to configure and manage logs for troubleshooting your system. +## 📝 Logging +Learn how to configure and manage logs for troubleshooting your system. [Logging Guide](/getting-started/advanced-topics/logging) --- -## 🔒 HTTPS Encryption -Ensure secure communication by implementing HTTPS encryption in your deployment. +## 🔒 HTTPS Encryption +Ensure secure communication by implementing HTTPS encryption in your deployment. [HTTPS Encryption Guide](/getting-started/advanced-topics/https-encryption) --- ## 📊 Monitoring -Learn how to monitor your Open WebUI instance, including health checks, model connectivity, and response testing. +Learn how to monitor your Open WebUI instance, including health checks, model connectivity, and response testing. [Monitoring Guide](/getting-started/advanced-topics/monitoring) --- -Looking for installation instructions? Head over to our [Quick Start Guide](/getting-started/quick-start). +Looking for installation instructions? Head over to our [Quick Start Guide](/getting-started/quick-start). diff --git a/docs/getting-started/advanced-topics/logging.md b/docs/getting-started/advanced-topics/logging.md index 0ba3a41114..0c33977a00 100644 --- a/docs/getting-started/advanced-topics/logging.md +++ b/docs/getting-started/advanced-topics/logging.md @@ -9,7 +9,7 @@ Logging is essential for debugging, monitoring, and understanding how Open WebUI ## 🖥️ Browser Client Logging (Frontend) -For frontend development and debugging, Open WebUI utilizes standard browser console logging. This means you can see logs directly within your web browser's built-in developer tools. +For frontend development and debugging, Open WebUI utilizes standard browser console logging. This means you can see logs directly within your web browser's built-in developer tools. **How to Access Browser Logs:** @@ -41,7 +41,7 @@ The backend of Open WebUI uses Python's built-in `logging` module to record even **Key Concepts:** -- **Python `logging` Module:** Open WebUI leverages the standard Python `logging` library. If you're familiar with Python logging, you'll find this section straightforward. (For more in-depth information, see the [Python Logging Documentation](https://docs.python.org/3/howto/logging.html#logging-levels)). +- **Python `logging` Module:** Open WebUI leverages the standard Python `logging` library. If you're familiar with Python logging, you'll find this section straightforward. (For more in-depth information, see the [Python Logging Documentation](https://docs.python.org/3/howto/logging.html#logging-levels)). - **Console Output:** By default, backend logs are sent to the console (standard output), making them visible in your terminal or Docker container logs. - **Logging Levels:** Logging levels control the verbosity of the logs. You can configure Open WebUI to show more or less detailed information based on these levels. @@ -51,11 +51,11 @@ Python logging uses a hierarchy of levels to categorize log messages by severity | Level | Numeric Value | Description | Use Case | | ----------- | ------------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| `CRITICAL` | 50 | **Severe errors** that may lead to application termination. | Catastrophic failures, data corruption. | -| `ERROR` | 40 | **Errors** that indicate problems but the application might still function. | Recoverable errors, failed operations. | -| `WARNING` | 30 | **Potential issues** or unexpected situations that should be investigated. | Deprecation warnings, resource constraints. | -| `INFO` | 20 | **General informational messages** about application operation. | Startup messages, key events, normal operation flow. | -| `DEBUG` | 10 | **Detailed debugging information** for developers. | Function calls, variable values, detailed execution steps. | +| `CRITICAL` | 50 | **Severe errors** that may lead to application termination. | Catastrophic failures, data corruption. | +| `ERROR` | 40 | **Errors** that indicate problems but the application might still function. | Recoverable errors, failed operations. | +| `WARNING` | 30 | **Potential issues** or unexpected situations that should be investigated. | Deprecation warnings, resource constraints. | +| `INFO` | 20 | **General informational messages** about application operation. | Startup messages, key events, normal operation flow. | +| `DEBUG` | 10 | **Detailed debugging information** for developers. | Function calls, variable values, detailed execution steps. | | `NOTSET` | 0 | **All messages are logged.** (Usually defaults to `WARNING` if not set). | Useful for capturing absolutely everything, typically for very specific debugging. | **Default Level:** Open WebUI's default logging level is `INFO`. @@ -66,7 +66,7 @@ You can change the **global** logging level for the entire Open WebUI backend us **How it Works:** -Setting `GLOBAL_LOG_LEVEL` configures the root logger in Python, affecting all loggers in Open WebUI and potentially some third-party libraries that use [basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig). It uses `logging.basicConfig(force=True)`, which means it will override any existing root logger configuration. +Setting `GLOBAL_LOG_LEVEL` configures the root logger in Python, affecting all loggers in Open WebUI and potentially some third-party libraries that use [basicConfig](https://docs.python.org/3/library/logging.html#logging.basicConfig). It uses `logging.basicConfig(force=True)`, which means it will override any existing root logger configuration. **Example: Setting to `DEBUG`** @@ -83,7 +83,7 @@ Setting `GLOBAL_LOG_LEVEL` configures the root logger in Python, affecting all l - GLOBAL_LOG_LEVEL=DEBUG ``` -**Impact:** Setting `GLOBAL_LOG_LEVEL` to `DEBUG` will produce the most verbose logs, including detailed information that is helpful for development and troubleshooting. For production environments, `INFO` or `WARNING` might be more appropriate to reduce log volume. +**Impact:** Setting `GLOBAL_LOG_LEVEL` to `DEBUG` will produce the most verbose logs, including detailed information that is helpful for development and troubleshooting. For production environments, `INFO` or `WARNING` might be more appropriate to reduce log volume. ### ⚙️ App/Backend Specific Logging Levels @@ -93,17 +93,17 @@ For more granular control, Open WebUI provides environment variables to set logg | Environment Variable | Component/Module | Description | | -------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `AUDIO_LOG_LEVEL` | Audio processing | Logging related to audio transcription (faster-whisper), text-to-speech (TTS), and audio handling. | -| `COMFYUI_LOG_LEVEL` | ComfyUI Integration | Logging for interactions with ComfyUI, if you are using this integration. | -| `CONFIG_LOG_LEVEL` | Configuration Management | Logging related to loading and processing Open WebUI configuration files. | -| `DB_LOG_LEVEL` | Database Operations (Peewee) | Logging for database interactions using the Peewee ORM (Object-Relational Mapper). | -| `IMAGES_LOG_LEVEL` | Image Generation (AUTOMATIC1111/Stable Diffusion) | Logging for image generation tasks, especially when using AUTOMATIC1111 Stable Diffusion integration. | -| `MAIN_LOG_LEVEL` | Main Application Execution (Root Logger) | Logging from the main application entry point and root logger. | +| `AUDIO_LOG_LEVEL` | Audio processing | Logging related to audio transcription (faster-whisper), text-to-speech (TTS), and audio handling. | +| `COMFYUI_LOG_LEVEL` | ComfyUI Integration | Logging for interactions with ComfyUI, if you are using this integration. | +| `CONFIG_LOG_LEVEL` | Configuration Management | Logging related to loading and processing Open WebUI configuration files. | +| `DB_LOG_LEVEL` | Database Operations (Peewee) | Logging for database interactions using the Peewee ORM (Object-Relational Mapper). | +| `IMAGES_LOG_LEVEL` | Image Generation (AUTOMATIC1111/Stable Diffusion) | Logging for image generation tasks, especially when using AUTOMATIC1111 Stable Diffusion integration. | +| `MAIN_LOG_LEVEL` | Main Application Execution (Root Logger) | Logging from the main application entry point and root logger. | | `MODELS_LOG_LEVEL` | Model Management | Logging related to loading, managing, and interacting with language models (LLMs), including authentication. | -| `OLLAMA_LOG_LEVEL` | Ollama Backend Integration | Logging for communication and interaction with the Ollama backend. | -| `OPENAI_LOG_LEVEL` | OpenAI API Integration | Logging for interactions with the OpenAI API (e.g., for models like GPT). | -| `RAG_LOG_LEVEL` | Retrieval-Augmented Generation (RAG) | Logging for the RAG pipeline, including Chroma vector database and Sentence-Transformers. | -| `WEBHOOK_LOG_LEVEL` | Authentication Webhook | Extended logging for authentication webhook functionality. | +| `OLLAMA_LOG_LEVEL` | Ollama Backend Integration | Logging for communication and interaction with the Ollama backend. | +| `OPENAI_LOG_LEVEL` | OpenAI API Integration | Logging for interactions with the OpenAI API (e.g., for models like GPT). | +| `RAG_LOG_LEVEL` | Retrieval-Augmented Generation (RAG) | Logging for the RAG pipeline, including Chroma vector database and Sentence-Transformers. | +| `WEBHOOK_LOG_LEVEL` | Authentication Webhook | Extended logging for authentication webhook functionality. | **How to Use:** @@ -114,6 +114,10 @@ environment: - OLLAMA_LOG_LEVEL=DEBUG ``` +:::note + **Important Note:** Unlike `GLOBAL_LOG_LEVEL`, these app-specific variables might not affect logging from *all* third-party modules. They primarily control logging within Open WebUI's codebase. +::: + By understanding and utilizing these logging mechanisms, you can effectively monitor, debug, and gain insights into your Open WebUI instance. diff --git a/docs/getting-started/advanced-topics/monitoring/index.md b/docs/getting-started/advanced-topics/monitoring/index.md index 40fc11836b..4cc2c3eb58 100644 --- a/docs/getting-started/advanced-topics/monitoring/index.md +++ b/docs/getting-started/advanced-topics/monitoring/index.md @@ -9,10 +9,10 @@ Monitoring your Open WebUI instance is crucial for ensuring it runs reliably, pe **Why Monitor?** -* **Ensure Uptime:** Proactively detect outages and service disruptions. -* **Performance Insights:** Track response times and identify potential bottlenecks. -* **Early Issue Detection:** Catch problems before they impact users significantly. -* **Peace of Mind:** Gain confidence that your Open WebUI instance is running smoothly. +- **Ensure Uptime:** Proactively detect outages and service disruptions. +- **Performance Insights:** Track response times and identify potential bottlenecks. +- **Early Issue Detection:** Catch problems before they impact users significantly. +- **Peace of Mind:** Gain confidence that your Open WebUI instance is running smoothly. ## 🚦 Levels of Monitoring @@ -45,17 +45,17 @@ You can use `curl` or any HTTP client to check this endpoint: 1. **Add a New Monitor:** In your Uptime Kuma dashboard, click "Add New Monitor". 2. **Configure Monitor Settings:** - * **Monitor Type:** Select "HTTP(s)". - * **Name:** Give your monitor a descriptive name, e.g., "Open WebUI Health Check". - * **URL:** Enter the health check endpoint URL: `http://your-open-webui-instance:8080/health` (Replace `your-open-webui-instance:8080` with your actual Open WebUI address and port). - * **Monitoring Interval:** Set the frequency of checks (e.g., `60 seconds` for every minute). - * **Retry Count:** Set the number of retries before considering the service down (e.g., `3` retries). + - **Monitor Type:** Select "HTTP(s)". + - **Name:** Give your monitor a descriptive name, e.g., "Open WebUI Health Check". + - **URL:** Enter the health check endpoint URL: `http://your-open-webui-instance:8080/health` (Replace `your-open-webui-instance:8080` with your actual Open WebUI address and port). + - **Monitoring Interval:** Set the frequency of checks (e.g., `60 seconds` for every minute). + - **Retry Count:** Set the number of retries before considering the service down (e.g., `3` retries). **What This Check Verifies:** -* **Web Server Availability:** Ensures the web server (e.g., Nginx, Uvicorn) is responding to requests. -* **Application Running:** Confirms that the Open WebUI application itself is running and initialized. -* **Basic Database Connectivity:** Typically includes a basic check to ensure the application can connect to the database. +- **Web Server Availability:** Ensures the web server (e.g., Nginx, Uvicorn) is responding to requests. +- **Application Running:** Confirms that the Open WebUI application itself is running and initialized. +- **Basic Database Connectivity:** Typically includes a basic check to ensure the application can connect to the database. ## Level 2: Open WebUI Model Connectivity 🔗 @@ -63,9 +63,9 @@ To go beyond basic availability, you can monitor the `/api/models` endpoint. Thi **Why Monitor Model Connectivity?** -* **Model Provider Issues:** Detect problems with your model provider services (e.g., API outages, authentication failures). -* **Configuration Errors:** Identify misconfigurations in your model provider settings within Open WebUI. -* **Ensure Model Availability:** Confirm that the models you expect to be available are actually accessible to Open WebUI. +- **Model Provider Issues:** Detect problems with your model provider services (e.g., API outages, authentication failures). +- **Configuration Errors:** Identify misconfigurations in your model provider settings within Open WebUI. +- **Ensure Model Availability:** Confirm that the models you expect to be available are actually accessible to Open WebUI. **API Endpoint Details:** @@ -73,7 +73,7 @@ See the [Open WebUI API documentation](https://docs.openwebui.com/getting-starte **How to Test with `curl` (Authenticated):** -You'll need an API key to access this endpoint. See the "Authentication Setup" section below for instructions on generating an API key. +You'll need an API key to access this endpoint. See the "Authentication Setup" section below for instructions on generating an API key. ```bash # Authenticated model connectivity check @@ -89,17 +89,17 @@ You'll need an API key to access this endpoint. See the "Authentication Setup" Before you can monitor the `/api/models` endpoint, you need to enable API keys in Open WebUI and generate one: 1. **Enable API Keys (Admin Required):** - * Log in to Open WebUI as an administrator. - * Go to **Admin Settings** (usually in the top right menu) > **General**. - * Find the "Enable API Key" setting and **turn it ON**. - * Click **Save Changes**. + - Log in to Open WebUI as an administrator. + - Go to **Admin Settings** (usually in the top right menu) > **General**. + - Find the "Enable API Key" setting and **turn it ON**. + - Click **Save Changes**. 2. **Generate an API Key (User Settings):** - * Go to your **User Settings** (usually by clicking on your profile icon in the top right). - * Navigate to the **Account** section. - * Click **Generate New API Key**. - * Give the API key a descriptive name (e.g., "Monitoring API Key"). - * **Copy the generated API key** and store it securely. You'll need this for your monitoring setup. + - Go to your **User Settings** (usually by clicking on your profile icon in the top right). + - Navigate to the **Account** section. + - Click **Generate New API Key**. + - Give the API key a descriptive name (e.g., "Monitoring API Key"). + - **Copy the generated API key** and store it securely. You'll need this for your monitoring setup. *(Optional but Recommended):* For security best practices, consider creating a **non-administrator user account** specifically for monitoring and generate an API key for that user. This limits the potential impact if the monitoring API key is compromised. @@ -108,21 +108,21 @@ Before you can monitor the `/api/models` endpoint, you need to enable API keys i ### Using Uptime Kuma for Model Connectivity Monitoring 🐻 1. **Create a New Monitor in Uptime Kuma:** - * Monitor Type: "HTTP(s) - JSON Query". - * Name: "Open WebUI Model Connectivity Check". - * URL: `http://your-open-webui-instance:8080/api/models` (Replace with your URL). - * Method: "GET". - * Expected Status Code: `200`. + - Monitor Type: "HTTP(s) - JSON Query". + - Name: "Open WebUI Model Connectivity Check". + - URL: `http://your-open-webui-instance:8080/api/models` (Replace with your URL). + - Method: "GET". + - Expected Status Code: `200`. 2. **Configure JSON Query (Verify Model List):** - * **JSON Query:** `$count(data[*])>0` - * **Explanation:** This JSONata query checks if the `data` array in the API response (which contains the list of models) has a count greater than 0. In other words, it verifies that at least one model is returned. - * **Expected Value:** `true` (The query should return `true` if models are listed). + - **JSON Query:** `$count(data[*])>0` + - **Explanation:** This JSONata query checks if the `data` array in the API response (which contains the list of models) has a count greater than 0. In other words, it verifies that at least one model is returned. + - **Expected Value:** `true` (The query should return `true` if models are listed). 3. **Add Authentication Headers:** - * In the "Headers" section of the Uptime Kuma monitor configuration, click "Add Header". - * **Header Name:** `Authorization` - * **Header Value:** `Bearer YOUR_API_KEY` (Replace `YOUR_API_KEY` with the API key you generated). + - In the "Headers" section of the Uptime Kuma monitor configuration, click "Add Header". + - **Header Name:** `Authorization` + - **Header Value:** `Bearer YOUR_API_KEY` (Replace `YOUR_API_KEY` with the API key you generated). 4. **Set Monitoring Interval:** Recommended interval: `300 seconds` (5 minutes) or longer, as model lists don't typically change very frequently. @@ -130,9 +130,9 @@ Before you can monitor the `/api/models` endpoint, you need to enable API keys i You can use more specific JSONata queries to check for particular models or providers. Here are some examples: -* **Check for at least one Ollama model:** `$count(data[owned_by='ollama'])>0` -* **Check if a specific model exists (e.g., 'gpt-4o'):** `$exists(data[id='gpt-4o'])` -* **Check if multiple specific models exist (e.g., 'gpt-4o' and 'gpt-4o-mini'):** `$count(data[id in ['gpt-4o', 'gpt-4o-mini']]) = 2` +- **Check for at least one Ollama model:** `$count(data[owned_by='ollama'])>0` +- **Check if a specific model exists (e.g., 'gpt-4o'):** `$exists(data[id='gpt-4o'])` +- **Check if multiple specific models exist (e.g., 'gpt-4o' and 'gpt-4o-mini'):** `$count(data[id in ['gpt-4o', 'gpt-4o-mini']]) = 2` You can test and refine your JSONata queries at [jsonata.org](https://try.jsonata.org/) using a sample API response to ensure they work as expected. @@ -142,15 +142,16 @@ For the most comprehensive monitoring, you can test if models are actually capab **Why Test Model Responses?** -* **End-to-End Verification:** Confirms that the entire model pipeline is working, from API request to model response. -* **Model Loading Issues:** Detects problems with specific models failing to load or respond. -* **Backend Processing Errors:** Catches errors in the backend logic that might prevent models from generating completions. +- **End-to-End Verification:** Confirms that the entire model pipeline is working, from API request to model response. +- **Model Loading Issues:** Detects problems with specific models failing to load or respond. +- **Backend Processing Errors:** Catches errors in the backend logic that might prevent models from generating completions. **How to Test with `curl` (Authenticated POST Request):** This test requires an API key and sends a POST request with a simple message to the chat completions endpoint. ```bash + # Test model response - authenticated POST request curl -X POST https://your-open-webui-instance/api/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ diff --git a/docs/getting-started/advanced-topics/monitoring/otel.md b/docs/getting-started/advanced-topics/monitoring/otel.md index f2a9fd8003..608a64ebd8 100644 --- a/docs/getting-started/advanced-topics/monitoring/otel.md +++ b/docs/getting-started/advanced-topics/monitoring/otel.md @@ -10,6 +10,7 @@ Open WebUI supports **distributed tracing and metrics** export via the OpenTelem The fastest way to get started with observability is with the pre-configured Docker Compose: ```bash + # Spin up Open WebUI and the latest Grafana LGTM stack, all-in-one docker compose -f docker-compose.otel.yaml up -d ``` @@ -21,7 +22,7 @@ The `docker-compose.otel.yaml` file sets up these components: | **grafana** | 3000 (UI), 4317 (OTLP/gRPC), 4318 (HTTP) | Grafana LGTM (Loki+Grafana+Tempo+Mimir) all-in-one | | **open-webui** | 8088 (default) → 8080 | WebUI, OTEL enabled, exposes on host port 8088 | -After startup, access the Grafana dashboard at [http://localhost:3000](http://localhost:3000) +After startup, access the Grafana dashboard at [http://localhost:3000](http://localhost:3000) Login: `admin` / `admin` ## ⚙️ Environment Variables @@ -37,7 +38,11 @@ You can configure OpenTelemetry in Open WebUI with these environment variables ( | `OTEL_SERVICE_NAME` | `open-webui` | Service name (tagged in traces and metrics) | | `OTEL_BASIC_AUTH_USERNAME` / `OTEL_BASIC_AUTH_PASSWORD` | *(empty)* | Basic Auth credentials if Collector requires them | -> Tip: Override defaults in your `.env` file or Compose file as needed. +::tip + +Override defaults in your `.env` file or Compose file as needed. + +::: ```yaml open-webui: @@ -101,7 +106,7 @@ docker run -d --name open-webui \ - Double-check `ENABLE_OTEL` and `ENABLE_OTEL_METRICS` are both set to `true` - Is the endpoint correct? (`OTEL_EXPORTER_OTLP_ENDPOINT`) - Inspect logs from Open WebUI (`docker logs open-webui`) for OTLP errors -- Collector's OTLP port (`4317`) should be open and reachable. Try: +- Collector's OTLP port (`4317`) should be open and reachable. Try: `curl http://localhost:4317` (replace host as needed) **Authentication required?** diff --git a/docs/getting-started/advanced-topics/network-diagrams.mdx b/docs/getting-started/advanced-topics/network-diagrams.mdx index aaea8a2658..fb8472e6e3 100644 --- a/docs/getting-started/advanced-topics/network-diagrams.mdx +++ b/docs/getting-started/advanced-topics/network-diagrams.mdx @@ -83,7 +83,6 @@ Rel(user, openwebui, "Unable to connect, host network is the VM's network") UpdateRelStyle(user, openwebui, $offsetX="-100", $offsetY="-50") ``` - ## Linux Setup Options 🐧 ### Ollama on Host, Open WebUI in Container (Linux) diff --git a/docs/getting-started/api-endpoints.md b/docs/getting-started/api-endpoints.md index e9eb8bf830..400e285130 100644 --- a/docs/getting-started/api-endpoints.md +++ b/docs/getting-started/api-endpoints.md @@ -12,7 +12,9 @@ To ensure secure access to the API, authentication is required 🛡️. You can ## Swagger Documentation Links :::important + Make sure to set the `ENV` environment variable to `dev` in order to access the Swagger documentation for any of these services. Without this configuration, the documentation will not be available. + ::: Access detailed API documentation for different services provided by Open WebUI: @@ -21,7 +23,6 @@ Access detailed API documentation for different services provided by Open WebUI: |-------------|-------------------------| | Main | `/docs` | - ## Notable API Endpoints ### 📜 Retrieve All Models @@ -55,11 +56,12 @@ Access detailed API documentation for different services provided by Open WebUI: ] }' ``` - + - **Python Example**: + ```python import requests - + def chat_with_model(token): url = 'http://localhost:3000/api/chat/completions' headers = { @@ -132,7 +134,7 @@ To utilize external data in RAG responses, you first need to upload the files. T ```python import requests - + def upload_file(token, file_path): url = 'http://localhost:3000/api/v1/files/' headers = { @@ -246,7 +248,7 @@ Leverage a knowledge collection to enhance the response when the inquiry may ben ```python import requests - + def chat_with_collection(token, model, query, collection_id): url = 'http://localhost:3000/api/chat/completions' headers = { diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 27626d7c95..d0965c5c00 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -3,7 +3,6 @@ sidebar_position: 4 title: "🌍 Environment Variable Configuration" --- - ## Overview Open WebUI provides a large range of environment variables that allow you to customize and configure @@ -171,7 +170,7 @@ is also being used and set to `True`. Failure to do so will result in the inabil - Type: `str` - Default: Empty string (' ') -- Description: Sets a custom text that will be included when you copy a message in the chat. E.g. `"This text is AI generated"` -> will add "This text is AI generated" to every message, when copied. +- Description: Sets a custom text that will be included when you copy a message in the chat. e.g., `"This text is AI generated"` -> will add "This text is AI generated" to every message, when copied. - Persistence: This environment variable is a `PersistentConfig` variable. #### `THREAD_POOL_SIZE` @@ -240,6 +239,7 @@ This caches the external model lists retrieved from configured OpenAI-compatible - Description: Sets the port to run Open WebUI from. :::info + If you're running the application via Python and using the `open-webui serve` command, you cannot set the port using the `PORT` configuration. Instead, you must specify it directly as a command-line argument using the `--port` flag. For example: ```bash @@ -247,6 +247,7 @@ open-webui serve --port 9999 ``` This will run the Open WebUI on port `9999`. The `PORT` environment variable is disregarded in this mode. + ::: #### `ENABLE_REALTIME_CHAT_SAVE` @@ -368,7 +369,9 @@ allowing the client to wait indefinitely. - Description: Sets the timeout in seconds for fetching the model list. This can be useful in cases where network latency requires a longer timeout duration to successfully retrieve the model list. :::note + The AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST is set to 10 seconds by default to help ensure that all necessary connections are available when opening the web UI. This duration allows enough time for retrieving the model list even in cases of higher network latency. You can lower this value if quicker timeouts are preferred, but keep in mind that doing so may lead to some connections being dropped, depending on your network conditions. + ::: #### `AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST` @@ -502,15 +505,19 @@ when using OpenAI-compatible endpoints. `DEFAULT_TITLE_GENERATION_PROMPT_TEMPLATE`: ``` + ### Task: Generate a concise, 3-5 word title with an emoji summarizing the chat history. + ### Guidelines: - The title should clearly represent the main theme or subject of the conversation. - Use emojis that enhance understanding of the topic, but avoid quotation marks or special formatting. - Write the title in the chat's primary language; default to English if multilingual. - Prioritize accuracy over excessive creativity; keep it clear and simple. + ### Output: JSON format: { "title": "your concise title here" } + ### Examples: - { "title": "📉 Stock Market Trends" }, - { "title": "🍪 Perfect Chocolate Chip Recipe" }, @@ -518,6 +525,7 @@ JSON format: { "title": "your concise title here" } - { "title": "Remote Work Productivity Tips" }, - { "title": "Artificial Intelligence in Healthcare" }, - { "title": "🎮 Video Game Development Insights" } + ### Chat History: {{MESSAGES:END:2}} @@ -542,8 +550,10 @@ JSON format: { "title": "your concise title here" } `DEFAULT_FOLLOW_UP_GENERATION_PROMPT_TEMPLATE`: ``` + ### Task: Suggest 3-5 relevant follow-up questions or prompts that the user might naturally ask next in this conversation as a **user**, based on the chat history, to help continue or deepen the discussion. + ### Guidelines: - Write all follow-up questions from the user’s point of view, directed to the assistant. - Make questions concise, clear, and directly related to the discussed topic(s). @@ -551,8 +561,10 @@ Suggest 3-5 relevant follow-up questions or prompts that the user might naturall - If the conversation is very short or not specific, suggest more general (but relevant) follow-ups the user might ask. - Use the conversation's primary language; default to English if multilingual. - Response must be a JSON array of strings, no extra text or formatting. + ### Output: JSON format: { "follow_ups": ["Question 1?", "Question 2?", "Question 3?"] } + ### Chat History: {{MESSAGES:END:6}} @@ -576,7 +588,7 @@ Your task is to choose and return the correct tool(s) from the list of available - Return only the JSON object, without any additional text or explanation. -- If no tools match the query, return an empty array: +- If no tools match the query, return an empty array: { "tool_calls": [] } @@ -758,45 +770,49 @@ When enabling `ENABLE_AUTOCOMPLETE_GENERATION`, ensure that you also configure ` `DEFAULT_AUTOCOMPLETE_GENERATION_PROMPT_TEMPLATE`: ``` + ### Task: -You are an autocompletion system. Continue the text in `` based on the **completion type** in `` and the given language. +You are an autocompletion system. Continue the text in `` based on the **completion type** in `` and the given language. ### **Instructions**: -1. Analyze `` for context and meaning. -2. Use `` to guide your output: - - **General**: Provide a natural, concise continuation. - - **Search Query**: Complete as if generating a realistic search query. -3. Start as if you are directly continuing ``. Do **not** repeat, paraphrase, or respond as a model. Simply complete the text. +1. Analyze `` for context and meaning. +2. Use `` to guide your output: + - **General**: Provide a natural, concise continuation. + - **Search Query**: Complete as if generating a realistic search query. +3. Start as if you are directly continuing ``. Do **not** repeat, paraphrase, or respond as a model. Simply complete the text. 4. Ensure the continuation: - - Flows naturally from ``. - - Avoids repetition, overexplaining, or unrelated ideas. -5. If unsure, return: `{ "text": "" }`. + - Flows naturally from ``. + - Avoids repetition, overexplaining, or unrelated ideas. +5. If unsure, return: `{ "text": "" }`. ### **Output Rules**: - Respond only in JSON format: `{ "text": "" }`. ### **Examples**: -#### Example 1: -Input: -General -The sun was setting over the horizon, painting the sky -Output: + +#### Example 1: +Input: +General +The sun was setting over the horizon, painting the sky +Output: { "text": "with vibrant shades of orange and pink." } -#### Example 2: -Input: -Search Query -Top-rated restaurants in -Output: -{ "text": "New York City for Italian cuisine." } +#### Example 2: +Input: +Search Query +Top-rated restaurants in +Output: +{ "text": "New York City for Italian cuisine." } --- + ### Context: {{MESSAGES:END:6}} -{{TYPE}} -{{PROMPT}} +{{TYPE}} +{{PROMPT}} + #### Output: ``` @@ -843,11 +859,12 @@ Output: `DEFAULT_TAGS_GENERATION_PROMPT_TEMPLATE`: ``` + ### Task: Generate 1-3 broad tags categorizing the main themes of the chat history, along with 1-3 more specific subtopic tags. ### Guidelines: -- Start with high-level domains (e.g. Science, Technology, Philosophy, Arts, Politics, Business, Health, Sports, Entertainment, Education) +- Start with high-level domains (e.g., Science, Technology, Philosophy, Arts, Politics, Business, Health, Sports, Entertainment, Education) - Consider including relevant subfields/subdomains if they are strongly represented throughout the conversation - If content is too short (less than 3 messages) or too diverse, use only ["General"] - Use the chat's primary language; default to English if multilingual @@ -902,7 +919,7 @@ The value of `API_KEY_ALLOWED_ENDPOINTS` should be a comma-separated list of end :::warning -Setting `JWT_EXPIRES_IN` to `-1` disables JWT expiration, making issued tokens valid forever. **This is extremely dangerous in production** and exposes your system to severe security risks if tokens are leaked or compromised. +Setting `JWT_EXPIRES_IN` to `-1` disables JWT expiration, making issued tokens valid forever. **This is extremely dangerous in production** and exposes your system to severe security risks if tokens are leaked or compromised. **Always set a reasonable expiration time (e.g., `3600s`, `1h`, etc.) in production to limit the lifespan of authentication tokens.** Never use `-1` in a production environment. @@ -1314,6 +1331,7 @@ pip install open-webui[all] - Description: Enables multitenancy pattern for Milvus collections management, which significantly reduces RAM usage and computational overhead by consolidating similar vector data structures. Controls whether Milvus uses multitenancy collection architecture. When enabled, all vector data is consolidated into 5 shared collections (memories, knowledge, files, web_search, hash_based) instead of creating individual collections per resource. Data isolation is achieved via a resource_id field rather than collection-level separation. :::info + **Benefits of multitenancy mode:** - Significantly reduced RAM consumption (5 collections vs potentially hundreds) - Lower computational overhead from collection management @@ -1329,9 +1347,12 @@ pip install open-webui[all] - Hash-based collections go into `{prefix}_hash_based` - Each entry includes a resource_id field matching the original collection name - Queries automatically filter by resource_id to maintain data isolation + ::: -:::info **Migration from Legacy Mode to Multitenancy** +:::info + +**Migration from Legacy Mode to Multitenancy** **What happens when you enable multitenancy when you already have a normal milvus database with data in it:** - Existing collections (pattern: `open_webui_{collection_name}`) remain in Milvus but **become inaccessible** to Open WebUI @@ -1360,9 +1381,12 @@ After successful migration (from milvus to multitenancy milvus), legacy collecti - No one-click "migrate and cleanup" button exists - Vector DB reset from UI (Admin Settings > Documents > Reset Vector Storage/Knowledge) only affects the active mode's collections - Legacy collections require manual cleanup via Milvus client tools + ::: -:::warning **Critical Considerations** +:::warning + +**Critical Considerations** **Before enabling multitenancy on an existing installation:** - Data loss risk: File vectors and user memory vectors are NOT migrated automatically. Only knowledge base content can be reindexed (migrated). @@ -1386,6 +1410,7 @@ After successful migration (from milvus to multitenancy milvus), legacy collecti - Set `ENABLE_MILVUS_MULTITENANCY_MODE=true` - Restart Open WebUI - Re-upload/re-create knowledge bases from scratch + ::: #### `MILVUS_COLLECTION_PREFIX` @@ -1723,18 +1748,18 @@ Note: this configuration assumes that AWS credentials will be available to your #### `DOCLING_OCR_ENGINE` -- Type: `str` -- Default: `tesseract` -- Description: Specifies the OCR engine used by Docling. - Supported values include: `tesseract` (default), `easyocr`, `ocrmac`, `rapidocr`, and `tesserocr`. +- Type: `str` +- Default: `tesseract` +- Description: Specifies the OCR engine used by Docling. + Supported values include: `tesseract` (default), `easyocr`, `ocrmac`, `rapidocr`, and `tesserocr`. - Persistence: This environment variable is a `PersistentConfig` variable. #### `DOCLING_OCR_LANG` -- Type: `str` -- Default: `eng,fra,deu,spa` (when using the default `tesseract` engine) -- Description: Specifies the OCR language(s) to be used with the configured `DOCLING_OCR_ENGINE`. - The format and available language codes depend on the selected OCR engine. +- Type: `str` +- Default: `eng,fra,deu,spa` (when using the default `tesseract` engine) +- Description: Specifies the OCR language(s) to be used with the configured `DOCLING_OCR_ENGINE`. + The format and available language codes depend on the selected OCR engine. - Persistence: This environment variable is a `PersistentConfig` variable. ## Retrieval Augmented Generation (RAG) @@ -1802,6 +1827,7 @@ Note: this configuration assumes that AWS credentials will be available to your `DEFAULT_RAG_TEMPLATE`: ``` + ### Task: Respond to the user query using the provided context, incorporating inline citations in the format [id] **only when the tag includes an explicit id attribute** (e.g., ). @@ -2028,6 +2054,7 @@ When configuring `RAG_FILE_MAX_SIZE` and `RAG_FILE_MAX_COUNT`, ensure that the v `DEFAULT_QUERY_GENERATION_PROMPT_TEMPLATE`: ``` + ### Task: Analyze the chat history to determine the necessity of generating search queries, in the given language. By default, **prioritize generating 1-3 broad and relevant search queries** unless it is absolutely certain that no additional information is required. The aim is to retrieve comprehensive, updated, and valuable information even with minimal uncertainty. If no search is unequivocally needed, return an empty list. @@ -2041,7 +2068,7 @@ Analyze the chat history to determine the necessity of generating search queries - Always prioritize providing actionable and broad queries that maximize informational coverage. ### Output: -Strictly return in JSON format: +Strictly return in JSON format: { "queries": ["query1", "query2"] } @@ -2124,7 +2151,9 @@ When enabling `GOOGLE_DRIVE_INTEGRATION`, ensure that you have configured `GOOGL ### OneDrive :::info + For a step-by-step setup guide, check out our tutorial: [Configuring OneDrive & SharePoint Integration](https://docs.openwebui.com/tutorials/integrations/onedrive-sharepoint/). + ::: #### `ENABLE_ONEDRIVE_INTEGRATION` @@ -2135,8 +2164,10 @@ For a step-by-step setup guide, check out our tutorial: [Configuring OneDrive & - Persistence: This environment variable is a `PersistentConfig` variable. :::warning + Configuring OneDrive integration is a multi-step process that requires creating and correctly configuring an Azure App Registration. The authentication flow also depends on a browser pop-up window. Please ensure that your browser's pop-up blocker is disabled for your Open WebUI domain to allow the authentication and file selection window to appear. + ::: #### `ENABLE_ONEDRIVE_PERSONAL` @@ -2172,8 +2203,10 @@ The authentication flow also depends on a browser pop-up window. Please ensure t - Description: Specifies the Application (client) ID for the **Work/School (Business) OneDrive** integration. This requires a separate Azure App Registration configured to support personal Microsoft accounts. **Do not put the personal OneDrive client ID here!** :::info + This Client ID (also known as Application ID) is obtained from an Azure App Registration within your Microsoft Entra ID (formerly Azure AD) tenant. When configuring the App Registration in Azure, the Redirect URI must be set to the URL of your Open WebUI instance and configured as a **Single-page application (SPA)** type for the authentication to succeed. + ::: #### `ONEDRIVE_SHAREPOINT_URL` @@ -2184,7 +2217,9 @@ When configuring the App Registration in Azure, the Redirect URI must be set to - Persistence: This environment variable is a `PersistentConfig` variable. :::info + This variable is essential for the work/school integration. It should point to the root SharePoint site associated with your tenant, enabling access to SharePoint document libraries. + ::: #### `ONEDRIVE_SHAREPOINT_TENANT_ID` @@ -2195,7 +2230,9 @@ This variable is essential for the work/school integration. It should point to t - Persistence: This environment variable is a `PersistentConfig` variable. :::info + This Tenant ID (also known as Directory ID) is required for the work/school integration. You can find this value on the main overview page of your Azure App Registration in the Microsoft Entra ID portal. + ::: ## Web Search @@ -2508,7 +2545,14 @@ Using a remote Playwright browser via `PLAYWRIGHT_WS_URL` can be beneficial for: - Type: `str` - Default: `en` - Description: Comma-separated list of language codes to try when fetching YouTube video transcriptions, in priority order. -- Example: If set to `es,de`, Spanish transcriptions will be attempted first, then German if Spanish was not available, and lastly English. Note: If none of the specified languages are available and `en` was not in your list, the system will automatically try English as a final fallback. +- Example: If set to `es,de`, Spanish transcriptions will be attempted first, then German if Spanish was not available, and lastly English. + +:::note + +Note: If none of the specified languages are available and `en` was not in your list, the system will automatically try English as a final fallback. + +::: + - Persistence: This environment variable is a `PersistentConfig` variable. ## Audio @@ -2722,6 +2766,7 @@ Using a remote Playwright browser via `PLAYWRIGHT_WS_URL` can be beneficial for: `DEFAULT_IMAGE_PROMPT_GENERATION_PROMPT_TEMPLATE`: ``` + ### Task: Generate a detailed prompt for am image generation task based on the given language and context. Describe the image as if you were explaining it to someone who cannot see it. Include relevant details, colors, shapes, and any other important elements. @@ -3028,6 +3073,33 @@ By default, OAuth configurations are stored in the database and managed via the address. This is considered unsafe as not all OAuth providers will verify email addresses and can lead to potential account takeovers. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_OAUTH_WITHOUT_EMAIL` +- Type: `bool` +- Default: `False` +- Description: Enables authentication with OpenID Connect (OIDC) providers that do not support or expose an email scope. When enabled, Open WebUI will create and manage user accounts without requiring an email address from the OAuth provider. +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::warning + +**Use with Caution** + +Enabling this option bypasses email-based user identification, which is the standard method for uniquely identifying users across authentication systems. When enabled: + +- User accounts will be created using the `sub` claim (or the claim specified in `OAUTH_SUB_CLAIM`) as the primary identifier +- Email-based features such as password recovery, email notifications, and account merging via `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` will not function properly +- Ensure your OIDC provider's `sub` claim is stable and unique to prevent authentication conflicts + +Only enable this if your identity provider does not support email scope and you have alternative user identification mechanisms in place. + +This setting is designed for enterprise environments using identity providers that: +- Use employee IDs, usernames, or other non-email identifiers as the primary user claim +- Have privacy policies that prevent sharing email addresses via OAuth +- Operate in air-gapped or highly restricted networks where email-based services are unavailable + +For most standard OAuth providers (Google, Microsoft, GitHub, etc.), this setting should remain `False`. + +::: + #### `OAUTH_UPDATE_PICTURE_ON_LOGIN` - Type: `bool` @@ -3356,7 +3428,7 @@ If `OAUTH_PICTURE_CLAIM` is set to `''` (empty string), then the OAuth picture c - Type: `str` - Default: `*` -- Description: Specifies the allowed domains for OAuth authentication. (e.g. "example1.com,example2.com"). +- Description: Specifies the allowed domains for OAuth authentication. (e.g., "example1.com,example2.com"). - Persistence: This environment variable is a `PersistentConfig` variable. ## LDAP @@ -3374,7 +3446,6 @@ If `OAUTH_PICTURE_CLAIM` is set to `''` (empty string), then the OAuth picture c - Description: Sets the label of the LDAP server. - Persistence: This environment variable is a `PersistentConfig` variable. - #### `LDAP_SERVER_HOST` - Type: `str` @@ -3808,7 +3879,7 @@ If the endpoint is an S3-compatible provider like MinIO that uses a TLS certific - Type: `str` - Description: Set the access key for Azure Storage. - Optional - if not provided, credentials will be taken from the environment. User credentials if run locally and Managed Identity if run in Azure services. - + ### OpenTelemetry Configuration #### `ENABLE_OTEL` @@ -4012,7 +4083,9 @@ For configuration using individual parameters or encrypted SQLite, see the relev - Persistence: No :::info + When `DATABASE_URL` is not explicitly set, Open WebUI will attempt to construct it using a combination of `DATABASE_TYPE`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_HOST`, `DATABASE_PORT`, and `DATABASE_NAME`. For this automatic construction to occur, **all** of these individual parameters must be provided. If any are missing, the default `DATABASE_URL` (SQLite file) or any explicitly set `DATABASE_URL` will be used instead. + ::: ### Encrypted SQLite with SQLCipher @@ -4021,8 +4094,8 @@ For enhanced security, Open WebUI supports at-rest encryption for its primary SQ To enable encryption, you must configure two environment variables: -1. Set `DATABASE_TYPE="sqlite+sqlcipher"`. -1. Set `DATABASE_PASSWORD="your-secure-password"`. +1. Set `DATABASE_TYPE="sqlite+sqlcipher"`. +1. Set `DATABASE_PASSWORD="your-secure-password"`. When these are set and a full `DATABASE_URL` is **not** explicitly defined, Open WebUI will automatically create and use an encrypted database file at `./data/webui.db`. @@ -4103,8 +4176,8 @@ More information about this setting can be found [here](https://docs.sqlalchemy. - Description: Specifies the URL of the Redis instance or cluster host for storing application state. - Examples: - `redis://localhost:6379/0` - - `rediss://:password@localhost:6379/0` _(with password and TLS)_ - - `rediss://redis-cluster.redis.svc.cluster.local:6379/0 ?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt &ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt` _(with mTLS)_ + - `rediss://:password@localhost:6379/0` *(with password and TLS)* + - `rediss://redis-cluster.redis.svc.cluster.local:6379/0 ?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt &ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt` *(with mTLS)* :::info @@ -4224,7 +4297,7 @@ If you use UVICORN_WORKERS, you also need to ensure that related environment var - Default: Not set (no Cache-Control header added) - Description: Sets the Cache-Control header for all HTTP responses. Supports standard directives like `public`, `private`, `no-cache`, `no-store`, `must-revalidate`, `max-age=seconds`, etc. If an invalid value is provided, defaults to `"no-store, max-age=0"` (no caching). - Examples: - - `"private, max-age=86400"` - Cache privately for 24 hours + - `"private, max-age=86400"` - Cache privately for 24 hours - `"public, max-age=3600, must-revalidate"` - Cache publicly for 1 hour, then revalidate - `"no-cache, no-store, must-revalidate"` - Never cache diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 7b55b3ba66..11579a3c86 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -3,24 +3,21 @@ sidebar_position: 200 title: "🚀 Getting Started" --- - import { TopBanners } from "@site/src/components/TopBanners"; - - Welcome to the **Open WebUI Documentation Hub!** Below is a list of essential guides and resources to help you get started, manage, and develop with Open WebUI. --- -## ⏱️ Quick Start +## ⏱️ Quick Start Get up and running quickly with our [Quick Start Guide](/getting-started/quick-start). --- -## 🛠️ Advanced Topics +## 🛠️ Advanced Topics Take a deeper dive into configurations and development tips in our [Advanced Topics Guide](/getting-started/advanced-topics). diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index 76bbeb0286..a68baca851 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -21,7 +21,9 @@ import PythonUpdating from './tab-python/PythonUpdating.md'; -:::info **Important Note on User Roles and Privacy:** +:::info + +**Important Note on User Roles and Privacy:** - **Admin Creation:** The first account created on Open WebUI gains **Administrator privileges**, controlling user management and system settings. - **User Registrations:** Subsequent sign-ups start with **Pending** status, requiring Administrator approval for access. @@ -36,7 +38,6 @@ Choose your preferred installation method below: - **Python:** Suitable for low-resource environments or those wanting a manual setup - **Kubernetes:** Ideal for enterprise deployments that require scaling and orchestration - @@ -82,7 +83,6 @@ Choose your preferred installation method below: -
@@ -98,7 +98,6 @@ Choose your preferred installation method below: -

Development Setup

@@ -108,7 +107,6 @@ Choose your preferred installation method below:
- @@ -120,7 +118,6 @@ Choose your preferred installation method below: - diff --git a/docs/getting-started/quick-start/starting-with-functions.mdx b/docs/getting-started/quick-start/starting-with-functions.mdx index 56f8a1631f..2e6d902005 100644 --- a/docs/getting-started/quick-start/starting-with-functions.mdx +++ b/docs/getting-started/quick-start/starting-with-functions.mdx @@ -1,11 +1,11 @@ --- sidebar_position: 5 -title: "🔌 Getting Started with Functions" +title: "🔌 Getting Started with Functions" --- ## Overview -Did you know Open WebUI can connect to almost **anything**—not just OpenAI-compatible APIs? +Did you know Open WebUI can connect to almost **anything**—not just OpenAI-compatible APIs? Thanks to **Pipe Functions**, you can bring in services that don’t support the OpenAI API (like **Anthropic**, Home Assistant, Google Search, or *any* Python codebase). No restrictions on LLMs or AI models: if you can automate it in Python, you can turn it into a plugin for Open WebUI! @@ -49,7 +49,6 @@ You’ll be redirected **directly to the Functions Editor** within your running ![Function Editor Screenshot](/images/getting-started/pipe-function-editor.png) - ## Step 4: Enable the Function Your new Pipe Function is now available, but **must be enabled**: @@ -90,5 +89,4 @@ Some functions need credentials (like Anthropic’s API key): - [Pipe Functions Guide](https://docs.openwebui.com/features/plugin/functions/pipe) - [Browse community functions](https://openwebui.com/functions) - 🚀 With Pipe Functions, your Open WebUI is limited *only by your imagination*! \ No newline at end of file diff --git a/docs/getting-started/quick-start/starting-with-llama-cpp.mdx b/docs/getting-started/quick-start/starting-with-llama-cpp.mdx index 790c0a7b86..4051c57190 100644 --- a/docs/getting-started/quick-start/starting-with-llama-cpp.mdx +++ b/docs/getting-started/quick-start/starting-with-llama-cpp.mdx @@ -38,6 +38,7 @@ You can load and run various GGUF-format quantized LLMs using Llama.cpp. One imp Alternatively, use Python to download programmatically: ```python + # pip install huggingface_hub hf_transfer from huggingface_hub import snapshot_download @@ -97,7 +98,7 @@ To control and query your locally running model directly from Open WebUI: 2. Go to ⚙️ Admin Settings → Connections → OpenAI Connections 3. Click ➕ Add Connection and enter: -- URL: `http://127.0.0.1:10000/v1` +- URL: `http://127.0.0.1:10000/v1` (Or use `http://host.docker.internal:10000/v1` if running WebUI inside Docker) - API Key: `none` (leave blank) diff --git a/docs/getting-started/quick-start/starting-with-ollama.mdx b/docs/getting-started/quick-start/starting-with-ollama.mdx index 126c5036ce..fa2a29ec4d 100644 --- a/docs/getting-started/quick-start/starting-with-ollama.mdx +++ b/docs/getting-started/quick-start/starting-with-ollama.mdx @@ -22,7 +22,7 @@ However, if you encounter connection issues, the most common cause is a network To manage your Ollama instance in Open WebUI, follow these steps: 1. Go to **Admin Settings** in Open WebUI. -2. Navigate to **Connections > Ollama > Manage** (click the wrench icon). +2. Navigate to **Connections > Ollama > Manage** (click the wrench icon). From here, you can download models, configure settings, and manage your connection to Ollama. Here’s what the management screen looks like: @@ -31,7 +31,6 @@ Here’s what the management screen looks like: ![Ollama Management Screen](/images/getting-started/quick-start/manage-modal-ollama.png) - ## A Quick and Efficient Way to Download Models If you’re looking for a faster option to get started, you can download models directly from the **Model Selector**. Simply type the name of the model you want, and if it’s not already available, Open WebUI will prompt you to download it from Ollama. diff --git a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx index d1cb346d42..176e1d36a4 100644 --- a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx +++ b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 4 +sidebar_position: 4 title: "🌐 Starting with OpenAI-Compatible Servers" --- @@ -56,7 +56,11 @@ See [their docs](https://lemonade-server.ai/) for details. 4. Click Save. -*Tip: If running Open WebUI in Docker and your model server on your host machine, use `http://host.docker.internal:/v1`.* +::tip + +If running Open WebUI in Docker and your model server on your host machine, use `http://host.docker.internal:/v1`. + +::: ##### **For Lemonade:** When adding Lemonade, use `http://localhost:8000/api/v0` as the URL. @@ -70,6 +74,6 @@ Select your connected server’s model in the chat menu and get started! That’s it! Whether you choose Llama.cpp, Ollama, LM Studio, or Lemonade, you can easily experiment and manage multiple model servers—all in Open WebUI. ---- +--- 🚀 Enjoy building your perfect local AI setup! \ No newline at end of file diff --git a/docs/getting-started/quick-start/starting-with-openai.mdx b/docs/getting-started/quick-start/starting-with-openai.mdx index 66c0cf8f99..1d12f22a5c 100644 --- a/docs/getting-started/quick-start/starting-with-openai.mdx +++ b/docs/getting-started/quick-start/starting-with-openai.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 2 +sidebar_position: 2 title: "🤖 Starting With OpenAI" --- @@ -23,7 +23,7 @@ You can use: 👉 Once you have the key, copy it and keep it handy. -For most OpenAI usage, the default API base URL is: +For most OpenAI usage, the default API base URL is: https://api.openai.com/v1 Other providers use different URLs — check your provider’s documentation. diff --git a/docs/getting-started/quick-start/tab-docker/DockerCompose.md b/docs/getting-started/quick-start/tab-docker/DockerCompose.md index 63dc6e060f..466461b24f 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerCompose.md +++ b/docs/getting-started/quick-start/tab-docker/DockerCompose.md @@ -6,8 +6,12 @@ If you don't have Docker installed, check out our [Docker installation tutorial] Docker Compose requires an additional package, `docker-compose-v2`. +:::warning + **Warning:** Older Docker Compose tutorials may reference version 1 syntax, which uses commands like `docker-compose build`. Ensure you use version 2 syntax, which uses commands like `docker compose build` (note the space instead of a hyphen). +::: + ## Example `docker-compose.yml` Here is an example configuration file for setting up Open WebUI with Docker Compose: @@ -40,8 +44,12 @@ volumes: open-webui: ``` +:::note + **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: @@ -56,8 +64,12 @@ A useful helper script called `run-compose.sh` is included with the codebase. Th --- +:::note + **Note:** For Nvidia GPU support, you change the image from `ghcr.io/open-webui/open-webui:main` to `ghcr.io/open-webui/open-webui:cuda` and add the following to your service definition in the `docker-compose.yml` file: +::: + ```yaml deploy: resources: diff --git a/docs/getting-started/quick-start/tab-docker/DockerSwarm.md b/docs/getting-started/quick-start/tab-docker/DockerSwarm.md index 24fc24b033..24c68fff9d 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerSwarm.md +++ b/docs/getting-started/quick-start/tab-docker/DockerSwarm.md @@ -10,11 +10,11 @@ Choose the appropriate command based on your hardware setup: - **Before Starting**: Directories for your volumes need to be created on the host, or you can specify a custom location or volume. - + The current example utilizes an isolated dir `data`, which is within the same dir as the `docker-stack.yaml`. - + - **For example**: - + ```bash mkdir -p data/open-webui data/chromadb data/ollama ``` @@ -35,7 +35,7 @@ Choose the appropriate command based on your hardware setup: volumes: - ./data/open-webui:/app/backend/data environment: - DATA_DIR: /app/backend/data + DATA_DIR: /app/backend/data OLLAMA_BASE_URLS: http://ollama:11434 CHROMA_HTTP_PORT: 8000 CHROMA_HTTP_HOST: chromadb @@ -66,7 +66,7 @@ Choose the appropriate command based on your hardware setup: - IS_PERSISTENT=TRUE - ALLOW_RESET=TRUE - PERSIST_DIRECTORY=/chroma/chroma - ports: + ports: - target: 8000 published: 8000 mode: overlay @@ -76,7 +76,7 @@ Choose the appropriate command based on your hardware setup: condition: any delay: 5s max_attempts: 3 - healthcheck: + healthcheck: test: ["CMD-SHELL", "curl localhost:8000/api/v1/heartbeat || exit 1"] interval: 10s retries: 2 @@ -112,10 +112,10 @@ Choose the appropriate command based on your hardware setup: 1. Ensure CUDA is Enabled, follow your OS and GPU instructions for that. 2. Enable Docker GPU support, see [Nvidia Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html " on Nvidia's site.") 3. Follow the [Guide here on configuring Docker Swarm to with with your GPU](https://gist.github.com/tomlankhorst/33da3c4b9edbde5c83fc1244f010815c#configuring-docker-to-work-with-your-gpus) - - Ensure _GPU Resource_ is enabled in `/etc/nvidia-container-runtime/config.toml` and enable GPU resource advertising by uncommenting the `swarm-resource = "DOCKER_RESOURCE_GPU"`. The docker daemon must be restarted after updating these files on each node. + - Ensure *GPU Resource* is enabled in `/etc/nvidia-container-runtime/config.toml` and enable GPU resource advertising by uncommenting the `swarm-resource = "DOCKER_RESOURCE_GPU"`. The docker daemon must be restarted after updating these files on each node. - **With CPU Support**: - + Modify the Ollama Service within `docker-stack.yaml` and remove the lines for `generic_resources:` ```yaml @@ -137,7 +137,7 @@ Choose the appropriate command based on your hardware setup: ``` - **Deploy Docker Stack**: - + ```bash docker stack deploy -c docker-stack.yaml -d super-awesome-ai ``` diff --git a/docs/getting-started/quick-start/tab-docker/DockerUpdating.md b/docs/getting-started/quick-start/tab-docker/DockerUpdating.md index 4abc59558a..e66ea749fb 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerUpdating.md +++ b/docs/getting-started/quick-start/tab-docker/DockerUpdating.md @@ -10,7 +10,7 @@ With [Watchtower](https://containrrr.dev/watchtower/), you can automate the upda docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui ``` -_(Replace `open-webui` with your container's name if it's different.)_ +*(Replace `open-webui` with your container's name if it's different.)* ### Option 2: Manual Update diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index 10a2e0bdf7..9ceacfe8ff 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -45,7 +45,6 @@ For Nvidia GPU support, add `--gpus all` to the `docker run` command: docker run -d -p 3000:8080 --gpus all -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:cuda ``` - #### Single-User Mode (Disabling Login) To bypass the login page for a single-user setup, set the `WEBUI_AUTH` environment variable to `False`: @@ -55,7 +54,9 @@ docker run -d -p 3000:8080 -e WEBUI_AUTH=False -v open-webui:/app/backend/data - ``` :::warning + You cannot switch between single-user mode and multi-account mode after this change. + ::: #### Advanced Configuration: Connecting to Ollama on a Different Server diff --git a/docs/getting-started/quick-start/tab-docker/Podman.md b/docs/getting-started/quick-start/tab-docker/Podman.md index 8b3738bada..99395435df 100644 --- a/docs/getting-started/quick-start/tab-docker/Podman.md +++ b/docs/getting-started/quick-start/tab-docker/Podman.md @@ -31,5 +31,4 @@ If you are using Ollama from your computer (not running inside a container), Once inside open-webui, navigate to Settings > Admin Settings > Connections and create a new Ollama API connection to `http://10.0.2.2:[OLLAMA PORT]`. By default, the Ollama port is 11434. - Refer to the Podman [documentation](https://podman.io/) for advanced configurations. diff --git a/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md b/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md index 10e3a8ac5c..a25d9ed210 100644 --- a/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md +++ b/docs/getting-started/quick-start/tab-docker/PodmanKubePlay.md @@ -63,7 +63,7 @@ For Nvidia GPU support, you need to replace the container image with `ghcr.io/op :::important -To successfully have the open-webui container access the GPU(s), +To successfully have the open-webui container access the GPU(s), you will need to have the Container Device Interface (CDI) for the GPU you wish to access installed in your Podman Machine. You can check [Podman GPU container access](https://podman-desktop.io/docs/podman/gpu). -::: \ No newline at end of file +::: diff --git a/docs/getting-started/quick-start/tab-python/Uv.md b/docs/getting-started/quick-start/tab-python/Uv.md index 6d237e04f4..22e1c96c74 100644 --- a/docs/getting-started/quick-start/tab-python/Uv.md +++ b/docs/getting-started/quick-start/tab-python/Uv.md @@ -1,4 +1,4 @@ -### Installation with `uv` +### Installation with `uv` The `uv` runtime manager ensures seamless Python environment management for applications like Open WebUI. Follow these steps to get started: @@ -6,12 +6,14 @@ The `uv` runtime manager ensures seamless Python environment management for appl Pick the appropriate installation command for your operating system: -- **macOS/Linux**: +- **macOS/Linux**: + ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` -- **Windows**: +- **Windows**: + ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` @@ -20,12 +22,14 @@ Pick the appropriate installation command for your operating system: Once `uv` is installed, running Open WebUI is a breeze. Use the command below, ensuring to set the `DATA_DIR` environment variable to avoid data loss. Example paths are provided for each platform: -- **macOS/Linux**: +- **macOS/Linux**: + ```bash DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve ``` -- **Windows** (PowerShell): +- **Windows** (PowerShell): + ```powershell $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve ``` diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index a1b706af8b..33cf6d3e8e 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -1,10 +1,8 @@ --- -sidebar_position: 300 +sidebar_position: 300 title: "🔄 Updating Open WebUI" --- - - ## Why isn't my Open WebUI updating? To update your local Docker installation of Open WebUI to the latest version available, you can either use **Watchtower** or manually update the container. Follow either of the steps provided below to be guided through updating your existing Open WebUI image. @@ -27,8 +25,8 @@ docker rm -f open-webui docker pull ghcr.io/open-webui/open-webui:main ``` - :::info + **Remove any existing data in the Docker volume (NOT RECOMMENDED UNLESS ABSOLUTELY NECCESSARY!)**. Skip this step entirely if not needed and move on to the last step: If you want to start with a clean slate, you can remove the existing data in the Docker volume. Be careful, as this will delete all your chat histories and other data. @@ -38,6 +36,7 @@ docker pull ghcr.io/open-webui/open-webui:main ```bash docker volume rm open-webui ``` + ::: 3. **Start the container again with the updated image and existing volume attached**: @@ -134,13 +133,13 @@ The data is stored in a Docker volume named `open-webui`. The path to the volume docker volume inspect open-webui ``` -This will show you the details of the volume, including the mountpoint, which is usually located in `/var/lib/docker/volumes/open-webui/_data`. +This will show you the details of the volume, including the mountpoint, which is usually located in `/var/lib/docker/volumes/open-webui/_data`. -On Windows 10 + WSL 2, Docker volumes are located here (type in the Windows file explorer): +On Windows 10 + WSL 2, Docker volumes are located here (type in the Windows file explorer): - \\\wsl$\docker-desktop\mnt\docker-desktop-disk\data\docker\volumes For older versions of Docker (pre-Docker v26.1.4): - \\\wsl$\docker-desktop-data\data\docker\volumes - \\\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes -_(Windows answer credit to StackOverflow user sarye-haddadi; [link to original SO post](https://stackoverflow.com/questions/43181654/locating-data-volumes-in-docker-desktop-windows))_ +*(Windows answer credit to StackOverflow user sarye-haddadi; [link to original SO post](https://stackoverflow.com/questions/43181654/locating-data-volumes-in-docker-desktop-windows))* diff --git a/docs/intro.mdx b/docs/intro.mdx index 1423011cbf..45696617ba 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -10,12 +10,10 @@ import { SponsorList } from "@site/src/components/SponsorList"; # Open WebUI - **Open WebUI is an [extensible](https://docs.openwebui.com/features/plugin/), feature-rich, and user-friendly self-hosted AI platform designed to operate entirely offline.** It supports various LLM runners like **Ollama** and **OpenAI-compatible APIs**, with **built-in inference engine** for RAG, making it a **powerful AI deployment solution**. Passionate about open-source AI? [Join our team →](https://careers.openwebui.com/) - ![GitHub stars](https://img.shields.io/github/stars/open-webui/open-webui?style=social) ![GitHub forks](https://img.shields.io/github/forks/open-webui/open-webui?style=social) ![GitHub watchers](https://img.shields.io/github/watchers/open-webui/open-webui?style=social) @@ -24,18 +22,16 @@ Passionate about open-source AI? [Join our team →](https://careers.openwebui.c ![GitHub top language](https://img.shields.io/github/languages/top/open-webui/open-webui) ![GitHub last commit](https://img.shields.io/github/last-commit/open-webui/open-webui?color=red) [![Discord](https://img.shields.io/badge/Discord-Open_WebUI-blue?logo=discord&logoColor=white)](https://discord.gg/5rJgQTnV4s) -[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/tjbck) - - - - +[![Image Description](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/tjbck) ![Open WebUI Demo](/images/demo.gif) :::tip + **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!** + ::: @@ -91,7 +87,9 @@ After installation, you can access Open WebUI at [http://localhost:3000](http:// ### Using the Dev Branch 🌙 :::warning + The `:dev` branch contains the latest unstable features and changes. Use it at your own risk as it may have bugs or incomplete features. + ::: If you want to try out the latest bleeding-edge features and are okay with occasional instability, you can use the `:dev` tag like this: @@ -143,12 +141,12 @@ The `uv` runtime manager ensures seamless Python environment management for appl Pick the appropriate installation command for your operating system: -- **macOS/Linux**: +- **macOS/Linux**: ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` -- **Windows**: +- **Windows**: ```powershell powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" ``` @@ -157,17 +155,18 @@ Pick the appropriate installation command for your operating system: Once `uv` is installed, running Open WebUI is a breeze. Use the command below, ensuring to set the `DATA_DIR` environment variable to avoid data loss. Example paths are provided for each platform: -- **macOS/Linux**: +- **macOS/Linux**: ```bash DATA_DIR=~/.open-webui uvx --python 3.11 open-webui@latest serve ``` -- **Windows**: +- **Windows**: ```powershell $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve ``` -:::note +:::note + **For PostgreSQL Support:** The default installation now uses a slimmed-down package. If you need **PostgreSQL support**, install with all optional dependencies: @@ -175,31 +174,32 @@ The default installation now uses a slimmed-down package. If you need **PostgreS ```bash pip install open-webui[all] ``` + ::: ### Installation with `pip` -For users installing Open WebUI with Python's package manager `pip`, **it is strongly recommended to use Python runtime managers like `uv` or `conda`**. These tools help manage Python environments effectively and avoid conflicts. +For users installing Open WebUI with Python's package manager `pip`, **it is strongly recommended to use Python runtime managers like `uv` or `conda`**. These tools help manage Python environments effectively and avoid conflicts. Python 3.11 is the development environment. Python 3.12 seems to work but has not been thoroughly tested. Python 3.13 is entirely untested and some dependencies do not work with Python 3.13 yet—**use at your own risk**. -1. **Install Open WebUI**: +1. **Install Open WebUI**: - Open your terminal and run the following command: + Open your terminal and run the following command: ```bash pip install open-webui ``` -2. **Start Open WebUI**: +2. **Start Open WebUI**: - Once installed, start the server using: + Once installed, start the server using: ```bash open-webui serve ``` ### Updating Open WebUI -To update to the latest version, simply run: +To update to the latest version, simply run: ```bash pip install --upgrade open-webui @@ -215,19 +215,17 @@ Continue with the full [getting started guide](/getting-started). ### Desktop App -We also have an **experimental** desktop app, which is actively a **work in progress (WIP)**. While it offers a convenient way to run Open WebUI natively on your system without Docker or manual setup, it is **not yet stable**. +We also have an **experimental** desktop app, which is actively a **work in progress (WIP)**. While it offers a convenient way to run Open WebUI natively on your system without Docker or manual setup, it is **not yet stable**. 👉 For stability and production use, we strongly recommend installing via **Docker** or **Python (`uv` or `pip`)**. ## Sponsors 🙌 - We are incredibly grateful for the generous support of our sponsors. Their contributions help us to maintain and improve our project, ensuring we can continue to deliver quality work to our community. Thank you! - ## Acknowledgements 🙏 We are deeply grateful for the generous grant support provided by: @@ -235,22 +233,18 @@ We are deeply grateful for the generous grant support provided by: diff --git a/docs/license.mdx b/docs/license.mdx index 98d5dee460..a5d34f4ad6 100644 --- a/docs/license.mdx +++ b/docs/license.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1900 +sidebar_position: 1900 title: "⚖️ Open WebUI License" --- @@ -7,7 +7,6 @@ import { TopBanners } from "@site/src/components/TopBanners"; - ## Keeping Open WebUI Free, Fair, and Sustainable If you've been following Open WebUI’s journey, you know our mission has always been: empower everyone with cutting-edge AI, no strings attached. Open WebUI is an independent project, built and maintained by a small, dedicated core team. Over the last year, we’ve poured **countless hours, late nights, and real financial resources** into making this tool world-class—**and we trust our users enough to keep it free and open**. @@ -16,7 +15,7 @@ But with Open WebUI’s rapid growth and success, we started seeing a pattern we That’s why we’ve acted: **with Open WebUI v0.6.6+ (April 2025), our license remains permissive, but now adds a fair-use branding protection clause**. This update does **not** impact genuine users, contributors, or anyone who simply wants to use the software in good faith. If you’re a real contributor, a small team, or an organization adopting Open WebUI for internal use—**nothing changes for you**. This change **only affects those who intend to exploit the project’s goodwill**: stripping away its identity, falsely representing it, and never giving back. -In plain terms: +In plain terms: - **Open WebUI is still free and permissively licensed.** - **You can still use, modify, and redistribute it for any purpose—just don’t remove or alter our branding unless you meet one of three clear criteria (see below).** - **The original BSD-3 license continues to apply for all contributions made to the codebase up to and including release v0.6.5.** @@ -41,11 +40,12 @@ Open WebUI’s license now: 3. **You’ve secured an enterprise license** from us which explicitly allows branding changes. - **CLA required for new contributions** after v0.6.5 (v0.6.6+) under the updated license. - - **All code submitted/merged to the codebase up to and including release v0.6.5 remains BSD-3 licensed** (no branding requirement applies for that legacy code). -:::tip +:::tip + **TL;DR: Want to use Open WebUI for free? Just keep the branding.** + ::: This is not legal advice—refer to the full [LICENSE](https://github.com/open-webui/open-webui/blob/main/LICENSE) for exact language. @@ -75,7 +75,7 @@ If you remove or modify branding without meeting these criteria, that’s a mate - **You must clarify (in your documentation/about/landing) that it’s a fork, not the official version.** - **You may not imply endorsement by us** for your derivative. -This isn’t contradictory—think of it as “must acknowledge, but not misrepresent.” +This isn’t contradictory—think of it as “must acknowledge, but not misrepresent.” Your compliance **both** (1) *retains our copyright info/branding* and (2) *avoids false advertising*. ### **4. Why did you add this clause? Isn’t open source supposed to be fully free?** @@ -91,7 +91,7 @@ Here’s what we’ve actually seen, and why we had to act: - When things break or customers need feature updates, these same groups turn around and *demand support from us—the original developers—**while never having contributed a line of code, a helpful bug report, documentation, or any resources back to the project.*** - **In effect, they extract value from the collective effort of independent contributors, misrepresent their role in the project, and give nothing back to the ecosystem or its sustainability.** -Let’s be clear: +Let’s be clear: - **Not everyone who doesn’t contribute is a bad actor.** Using Open WebUI “as is,” for internal or not-for-profit ways, is absolutely fine. We expect most users will never contribute code, and that’s totally fair—that’s how permissive open source works! - **But there is a line:** When you start misleading your users about what you’re offering, exploiting the goodwill and energy of independent maintainers, and taking more than you give (especially when making money and actively denying credit), **that’s not collaboration—that’s extraction and misrepresentation.** - **This is especially demoralizing for us as a small, fully independent and self-funded team**, working incredibly hard to keep Open WebUI both free and at the leading edge of AI. The reality is that open source isn’t “free” for the people building it: it takes huge time investments, personal sacrifice, ongoing infrastructure costs, and dedication. When our goodwill is taken advantage of, it directly threatens our ability to keep this project alive and thriving for everyone else. @@ -99,7 +99,7 @@ Let’s be clear: **That’s why** the new branding clause exists. It is a minimal, carefully scoped, and entirely rational measure: - It preserves openness for genuine users and contributors—anyone can use, deploy, and even build commercial offerings as long as they respect transparency and our community’s work. - It prevents bad-faith actors from concealing our contributions or misleading users—protecting the project’s identity, trust, and reputation. -- **Importantly, it also incentivizes individuals and organizations to actively contribute back to Open WebUI.** When companies are required to credit and retain the original branding, it creates a virtuous cycle: they’re far more likely to participate in the project, propose improvements, submit bug fixes, contribute features, or start a conversation about open collaboration for everyone’s benefit. +- **Importantly, it also incentivizes individuals and organizations to actively contribute back to Open WebUI.** When companies are required to credit and retain the original branding, it creates a virtuous cycle: they’re far more likely to participate in the project, propose improvements, submit bug fixes, contribute features, or start a conversation about open collaboration for everyone’s benefit. - This collective approach **ensures that enhancements, security fixes, and new features are shared more openly, accelerating progress for the entire ecosystem—rather than being siloed in closed forks nobody else benefits from.** We want Open WebUI to remain **free, empowering, and driven by honest spirit—protecting the project so it can serve everyone, not just those looking to exploit others’ effort for unearned gain.** The **branding protection clause targets only those edge-case exploiters**—no one else’s experience is affected. It is our genuine attempt to keep our community healthy, sustainable, and welcoming, while holding the project’s identity safe from predatory appropriation. @@ -112,16 +112,16 @@ We remain as open, reasonable, and fair as ever—and we trust the community to **No, and here’s precisely how it works:** -- **All code contributed and merged up to and including v0.6.5 remains under the original BSD-3-Clause license—no new limitations apply.** - - _This means:_ If you contributed anything before v0.6.6, you (and everyone else) retain all the original BSD-3 freedoms: use, modification, redistribution, even sublicensing—**as long as the original BSD-3 license notice remains intact. The BSD-3 license remains in effect for the entire codebase up to and including v0.6.5.** +- **All code contributed and merged up to and including v0.6.5 remains under the original BSD-3-Clause license—no new limitations apply.** + - *This means:* If you contributed anything before v0.6.6, you (and everyone else) retain all the original BSD-3 freedoms: use, modification, redistribution, even sublicensing—**as long as the original BSD-3 license notice remains intact. The BSD-3 license remains in effect for the entire codebase up to and including v0.6.5.** - **BSD-3-Clause is one of the most permissive licenses available:** You can use the code for any purpose, even commercially, change it completely, and license your derivative under whatever terms you like, as long as you preserve the BSD-3 notice. -- **The new “fair-use branding” clause only applies to code contributed after v0.6.5 and released as part of v0.6.6 or later,** _and only if you sign the new CLA as part of contributing new material_. +- **The new “fair-use branding” clause only applies to code contributed after v0.6.5 and released as part of v0.6.6 or later,** *and only if you sign the new CLA as part of contributing new material*. -- **Importantly:** The new license with the branding protection clause is **not being retroactively applied to the entire codebase**. It is only applied to the portion of the code that we (the core team) ourselves wrote (which, with a conservative estimate, is at least 80% of the code up to v0.6.5), and everything going forward starting with v0.6.6. +- **Importantly:** The new license with the branding protection clause is **not being retroactively applied to the entire codebase**. It is only applied to the portion of the code that we (the core team) ourselves wrote (which, with a conservative estimate, is at least 80% of the code up to v0.6.5), and everything going forward starting with v0.6.6. - All external/community-contributed code merged before v0.6.6 remains pure BSD-3 and is not covered by the branding clause—**no retroactive relicensing or constraints** will be applied to anyone else’s past contributions. -- Looking at the history of [contributors to Open WebUI](https://github.com/open-webui/open-webui/graphs/contributors), **at least 80% of the codebase (very conservatively) originates directly from our core team**. Even community pull requests that are merged are always _manually reviewed, edited, heavily reworked, and improved_ to meet our standards before being included. Nothing is “blind-merged.” +- Looking at the history of [contributors to Open WebUI](https://github.com/open-webui/open-webui/graphs/contributors), **at least 80% of the codebase (very conservatively) originates directly from our core team**. Even community pull requests that are merged are always *manually reviewed, edited, heavily reworked, and improved* to meet our standards before being included. Nothing is “blind-merged.” - **If you contributed code pre-v0.6.6 and now wish to have it removed (i.e., you do not consent to the updated project structure or licensing), we will promptly honor your request and excise it from subsequent releases.** Just contact us and reference the relevant code. @@ -136,7 +136,13 @@ We remain as open, reasonable, and fair as ever—and we trust the community to If in doubt, or if you have concerns about your past or future contributions, please reach out—we value every contributor and are committed to respecting your rights. -**Note:** BSD-3 output/forks have **maximum flexibility**: as long as you keep the original BSD-3 notice, you can even apply your own license terms on top of your modifications or distribute them however you wish. +:::note + +**Note:** + +BSD-3 output/forks have **maximum flexibility**: as long as you keep the original BSD-3 notice, you can even apply your own license terms on top of your modifications or distribute them however you wish. + +::: ### **6. Does this mean Open WebUI is “no longer open source”?** @@ -148,18 +154,18 @@ It's a great—and complicated—question, because **"open source" can mean many - However, compared to what most people mean in practice — **“is the code available, can I use it, fork it, change it, build things with it, and not pay you or get a special key?”** — the answer is still a resounding **yes**. - We are far more open than most so-called “open core” projects, which often wall off features, require payments for APIs, or keep critical work private. -**What does all this mean in practice for you?** +**What does all this mean in practice for you?** - *All of the source code is public and developed in the open.* - *You can use it, run it locally, build on it, host it for your team or business, and even charge for access—as long as you follow the simple, clearly-scoped branding condition. (And if that’s an issue, email us! There’s a path for everyone.)* - *If you want to fork, extend, or submit PRs, the process and permissions are as open as ever—no “private enterprise fork” that fractures the community or walls off features.* -**Why this approach?** -Some projects in our position have responded to exploitation by: +**Why this approach?** +Some projects in our position have responded to exploitation by: - Going fully closed-source, - Putting new features in a private “enterprise” fork nobody else can see, - Switching to restrictive licenses like SSPL or BSL that block nearly all serious commercial use. -**We didn’t want to do that.** +**We didn’t want to do that.** We want a single, shared, public codebase where everyone—from solo hackers to enterprises—can benefit from the same core improvements, transparent development, and community fixes. We believe open ecosystems work best for users, contributors, and the future of AI. If you ever need more permissions or have questions, just talk to us—we’re committed to finding solutions that respect our contributors and community. @@ -184,40 +190,41 @@ Otherwise, you must retain branding and clearly say your fork isn't the official ### **10. I’m an individual academic/non-profit researcher. Can I customize or remove branding for a research study?** :::info -Please note: _This exemption is intended **exclusively for research studies**, not for general-purpose or ongoing institutional use._ + +Please note: *This exemption is intended **exclusively for research studies**, not for general-purpose or ongoing institutional use.* + ::: **Absolutely—academic research matters to us!** If you’re a researcher at a non-profit or academic institution conducting a **specific, time-limited research project** (for example: a user study, clinical trial, or classroom experiment), you may request permission to **remove or customize Open WebUI branding** for the duration of your study. **This is intended for single, well-defined research projects**—not for regular, day-to-day platform use across a department or lab. -To apply: -Please email us at [research-study@openwebui.com](mailto:research-study@openwebui.com) and use the subject line: +To apply: +Please email us at [research-study@openwebui.com](mailto:research-study@openwebui.com) and use the subject line: `Research Exemption Request – [Your Institution]` -- Your institution/department -- The purpose and description of your research study -- The planned start/end dates or study duration -- The expected scale (example: number of participants, research group size) +- Your institution/department +- The purpose and description of your research study +- The planned start/end dates or study duration +- The expected scale (example: number of participants, research group size) We review requests individually and, in almost all cases, will grant permission for branding changes to support your research. -**Example approved use cases:** -- Conducting a one-quarter psychology experiment involving students -- Running a clinical user acceptance study within a hospital for five weeks -- Field-testing model interaction in a history course for one semester +**Example approved use cases:** +- Conducting a one-quarter psychology experiment involving students +- Running a clinical user acceptance study within a hospital for five weeks +- Field-testing model interaction in a history course for one semester -**Not eligible:** -- Removing branding for ongoing departmental use, internal tooling, or public university portals +**Not eligible:** +- Removing branding for ongoing departmental use, internal tooling, or public university portals - “White-labeling” for all organization users beyond a research study scope We’re happy to help make Open WebUI accessible for your research—just ask! - --- #### Example Fork Branding Disclosure If you operate a public fork, or a paid SaaS, and retain the Open WebUI branding: -> _“This project is a customized fork of [Open WebUI](https://github.com/open-webui/open-webui). This release is not affiliated with or maintained by the official Open WebUI team.”_ +> *“This project is a customized fork of [Open WebUI](https://github.com/open-webui/open-webui). This release is not affiliated with or maintained by the official Open WebUI team.”* Display this message—prominently—in the About section, landing page, or equivalent location. **Transparency is required.** @@ -229,7 +236,6 @@ If you are a business that needs private or custom branding, advanced white-labe **Contact [sales@openwebui.com](mailto:sales@openwebui.com) for more information about commercial options.** - --- ## Branding, Attribution, and Customization Guidelines: What’s Allowed (and What’s Not) @@ -256,17 +262,16 @@ We want to make it as straightforward as possible for everyone, users, businesse | **Link to your company/project/github in the footer or About box** | ✅ | No problem if subordinate—must not give impression of replacing or rebranding the app. | | **For deployments ≤50 users/rolling 30-day period** | ✅ | “Small scale” deployments may remove Open WebUI branding, but only under the explicit user count threshold—see policy for details. | - ### **What is NOT ALLOWED Without an Enterprise/Proprietary License** | Scenario | Allowed Without License? | Why NOT Allowed/Details | |--------------------------------------|:------------------------:|----------------------------------------------------------------------| -| Removing **ANY** Open WebUI logo/name from the UI | ❌ | This is a clear violation, even if you add “Powered by Open WebUI” somewhere else. | -| Modifying/changing the Open WebUI logo or color scheme to your branding | ❌ | The identity must remain clear and intact. No recoloring or swaps. | +| Removing **ANY** Open WebUI logo/name from the UI | ❌ | This is a clear violation, even if you add “Powered by Open WebUI” somewhere else. | +| Modifying/changing the Open WebUI logo or color scheme to your branding | ❌ | The identity must remain clear and intact. No recoloring or swaps. | | Adding your logo side-by-side/equal in size or priority (**Co-branding**) | ❌ | Co-branding of any kind is strictly forbidden. Your logo must NOT appear next to, be the same size as, or in comparable proximity or prominence to Open WebUI’s logo or name under any circumstances. | | Calling your fork “Open WebUI Enterprise” or misleadingly similar | ❌ | Don’t use our project’s name or branding in a way that could confuse users about source or official status. | | Major UI modifications that move, minimize, or obscure original Open WebUI branding | ❌ | Moving the logo, shrinking it, hiding it, or pushing it offscreen violates the terms. | -| White-labelling for your business/SaaS | ❌ | You MUST get an enterprise or proprietary license before removing our branding for mass redistribution or resale. | +| White-labelling for your business/SaaS | ❌ | You MUST get an enterprise or proprietary license before removing our branding for mass redistribution or resale. | | “Powered by Open WebUI” credit ONLY (if all native branding is hidden/removed) | ❌ | This is NOT enough and does not meet license terms. | ### **How to Add Custom Branding Responsibly** @@ -274,7 +279,7 @@ We want to make it as straightforward as possible for everyone, users, businesse - **DO NOT remove, shrink, relocate, or recolor Open WebUI branding.** - **Co-branding is not allowed at all.** You may NOT display your branding/logo adjacent to or alongside Open WebUI’s logo/name, nor may you display your branding in a manner that creates visual equivalence or confusion. - **If you want to add a “Managed by Company X” banner**, it must remain clearly distinct, unobtrusive, and subordinate to Open WebUI’s own visual hierarchy. -- **Don’t “co-brand” or sandwich your logo next to ours** without explicit written approval. For nearly all non-trivial cases, you will need a commercial or custom license. +- **Don’t “co-brand” or sandwich your logo next to ours** without explicit written approval. For nearly all non-trivial cases, you will need a commercial or custom license. - **Always show us a screenshot before launch!** If in doubt, email [hello@openwebui.com](mailto:hello@openwebui.com)—we’re happy to review and advise. ### **Still Unsure?** @@ -285,5 +290,4 @@ If you’re ever unsure, please feel free to contact us and share your planned d *This page is provided for informational purposes only and does not constitute legal advice. For exact and legally binding terms, refer to the full text of the [LICENSE](https://github.com/open-webui/open-webui/blob/main/LICENSE).* - **Thank you for respecting the Open WebUI community, our contributors, and our project’s future.** \ No newline at end of file diff --git a/docs/mission.mdx b/docs/mission.mdx index 750d3a9535..e6e549616e 100644 --- a/docs/mission.mdx +++ b/docs/mission.mdx @@ -7,7 +7,7 @@ import { TopBanners } from "@site/src/components/TopBanners"; -### A Note from Our Founder +### A Note from Our Founder Before diving into our mission, we invite you to read our founder's blog post: ["Why I’m Building Open WebUI"](https://jryng.com/thoughts/why-open-webui). In this post, Tim shares the inspiration, challenges, and hopes driving Open WebUI's vision forward. It's a heartfelt introduction to what we're all about! diff --git a/docs/openapi-servers/faq.mdx b/docs/openapi-servers/faq.mdx index c86badfcd1..b34ef65f64 100644 --- a/docs/openapi-servers/faq.mdx +++ b/docs/openapi-servers/faq.mdx @@ -5,7 +5,7 @@ title: "❓ FAQ" #### 🌐 Q: Why isn't my local OpenAPI tool server accessible from the WebUI interface? -**A:** If your tool server is running locally (e.g. http://localhost:8000), browser-based clients may be restricted from accessing it due to CORS (Cross-Origin Resource Sharing) policies. +**A:** If your tool server is running locally (e.g., http://localhost:8000), browser-based clients may be restricted from accessing it due to CORS (Cross-Origin Resource Sharing) policies. Make sure to explicitly enable CORS headers in your OpenAPI server. For example, if you're using FastAPI, you can add: @@ -21,9 +21,9 @@ app.add_middleware( ) ``` -Also, if Open WebUI is served over HTTPS (e.g. https://yourdomain.com), your local server must meet one of the following conditions: +Also, if Open WebUI is served over HTTPS (e.g., https://yourdomain.com), your local server must meet one of the following conditions: -- Be accessed from the same domain using HTTPS (e.g. https://localhost:8000). +- Be accessed from the same domain using HTTPS (e.g., https://localhost:8000). - OR run on localhost (127.0.0.1) to allow browsers to relax security for local development. - Otherwise, browsers may block insecure requests from HTTPS pages to HTTP APIs due to mixed-content rules. @@ -46,13 +46,12 @@ It is important to set a custom operationId for all endpoints. --- - #### 🚀 Q: Why choose OpenAPI over MCP? **A:** OpenAPI wins over MCP in most real-world scenarios due to its simplicity, tooling ecosystem, stability, and developer-friendliness. Here's why: - ✅ **Reuse Your Existing Code**: If you’ve built REST APIs before, you're mostly done—you don’t need to rewrite your logic. Just define a compliant OpenAPI spec and expose your current code as a tool server. - + With MCP, you had to reimplement your tool logic inside a custom protocol layer, duplicating work and increasing the surface area to maintain. - 💼 **Less to Maintain & Debug**: OpenAPI fits naturally into modern dev workflows. You can test endpoints with Postman, inspect logs with built-in APIs, troubleshoot easily with mature ecosystem tools—and often without modifying your core app at all. @@ -71,7 +70,6 @@ It is important to set a custom operationId for all endpoints. 🧵 Bottom line: OpenAPI lets you do more with less effort, less code duplication, and fewer surprises. It’s a production-ready, developer-friendly route to powering LLM tools—without rebuilding everything from scratch. - --- #### 🔐 Q: How do I secure my OpenAPI tool server? @@ -174,5 +172,5 @@ You can also modularize completely by creating one OpenAPI server per tool if yo --- -🙋 Have more questions? Visit the GitHub discussions for help and feedback from the community: +🙋 Have more questions? Visit the GitHub discussions for help and feedback from the community: 👉 [Community Discussions](https://github.com/open-webui/openapi-servers/discussions) diff --git a/docs/openapi-servers/index.mdx b/docs/openapi-servers/index.mdx index e029f6fa15..3a89d6fe5e 100644 --- a/docs/openapi-servers/index.mdx +++ b/docs/openapi-servers/index.mdx @@ -3,7 +3,6 @@ sidebar_position: 900 title: "🔨 OpenAPI Tool Servers" --- - import { TopBanners } from "@site/src/components/TopBanners"; @@ -38,6 +37,7 @@ cd openapi-servers ### With Bash ```bash + # Example: Installing dependencies for a specific server 'filesystem' cd servers/filesystem pip install -r requirements.txt @@ -62,10 +62,9 @@ The services will be reachable from: * [memory server localhost:8082](http://localhost:8082) * [time-server localhost:8083](http://localhost:8083) - Now, simply point your OpenAPI-compatible clients or AI agents to your local or publicly deployed URL—no configuration headaches, no complicated transports. -## 🌱 Open WebUI Community +## 🌱 Open WebUI Community - For general discussions, technical exchange, and announcements, visit our [Community Discussions](https://github.com/open-webui/openapi-servers/discussions) page. - Have ideas or feedback? Please open an issue! diff --git a/docs/openapi-servers/mcp.mdx b/docs/openapi-servers/mcp.mdx index f156dbb7d9..e7bd1f58c7 100644 --- a/docs/openapi-servers/mcp.mdx +++ b/docs/openapi-servers/mcp.mdx @@ -80,11 +80,11 @@ For instance, the popular **Time MCP Server** is documented [here](https://githu > Add to your Claude settings: > > ```json -> "mcpServers": { -> "time": { -> "command": "uvx", -> "args": ["mcp-server-time", "--local-timezone=America/New_York"] -> } +> "mcpServers": { +> "time": { +> "command": "uvx", +> "args": ["mcp-server-time", "--local-timezone=America/New_York"] +> } > } > ``` @@ -119,12 +119,11 @@ Simply call the auto-generated API endpoints directly via HTTP clients, AI agent Assuming you started the above server command (`uvx mcp-server-time`): - Visit your local API documentation at `http://localhost:8000/docs`. -- Select a generated endpoint (e.g. `/get_current_time`) and use the provided interactive form. +- Select a generated endpoint (e.g., `/get_current_time`) and use the provided interactive form. - Click "**Execute**" and instantly receive your response. No setup complexity—just instant REST APIs. - ## 🚀 Deploying in Production (Example) Deploying your MCP-to-OpenAPI proxy (powered by mcpo) is straightforward. Here's how to easily Dockerize and deploy it to cloud or VPS solutions: @@ -139,6 +138,7 @@ Create the following `Dockerfile` inside your deployment directory: FROM python:3.11-slim WORKDIR /app RUN pip install mcpo uv + # Replace with your MCP server command; example: uvx mcp-server-time CMD ["uvx", "mcpo", "--host", "0.0.0.0", "--port", "8000", "--", "uvx", "mcp-server-time", "--local-timezone=America/New_York"] ``` @@ -163,7 +163,7 @@ Deploy using Docker Compose, Kubernetes YAML manifests, or your favorite cloud c ✔️ Your production MCP servers are now effortlessly available via REST APIs! -## 🧑‍💻 Technical Details and Background +## 🧑‍💻 Technical Details and Background ### 🍃 How It Works (Technical Summary) @@ -183,7 +183,7 @@ Deploy using Docker Compose, Kubernetes YAML manifests, or your favorite cloud c Here's why leveraging MCP servers through OpenAPI via the proxy approach is significantly better and why Open WebUI enthusiastically supports it: -- **User-friendly & Familiar Interface**: No custom clients; just HTTP REST endpoints you already know. +- **User-friendly & Familiar Interface**: No custom clients; just HTTP REST endpoints you already know. - **Instant Integration**: Immediately compatible with thousands of existing REST/OpenAPI tools, SDKs, and services. - **Powerful & Automatic Docs**: Built-in Swagger UI documentation is automatically generated, always accurate, and maintained. - **No New Protocol overhead**: Eliminates the necessity to directly handle MCP-specific protocol complexities and socket communication issues. @@ -192,7 +192,6 @@ Here's why leveraging MCP servers through OpenAPI via the proxy approach is sign 🌟 **Bottom line:** MCP-to-OpenAPI makes your powerful MCP-based AI tools broadly accessible through intuitive, reliable, and scalable REST endpoints. Open WebUI proudly supports and recommends this best-in-class approach. - ## 📢 Community & Support - For questions, suggestions, or feature requests, please use our [GitHub Issue tracker](https://github.com/open-webui/openapi-servers/issues) or join our [Community Discussions](https://github.com/open-webui/openapi-servers/discussions). diff --git a/docs/openapi-servers/open-webui.mdx b/docs/openapi-servers/open-webui.mdx index 71a54da07a..c6f8f24d63 100644 --- a/docs/openapi-servers/open-webui.mdx +++ b/docs/openapi-servers/open-webui.mdx @@ -67,31 +67,32 @@ Admins can manage shared tool servers available to all or selected users across - Add the tool server URL just as you would in user settings. - These tools are treated similarly to Open WebUI’s built-in tools. - #### Main Difference: Where Are Requests Made From? The primary distinction between **User Tool Servers** and **Global Tool Servers** is where the API connection and requests are actually made: -- **User Tool Servers** +- **User Tool Servers** - Requests to the tool server are performed **directly from your browser** (the client). - This means you can safely connect to localhost URLs (like `http://localhost:8000`)—even exposing private or development-only endpoints such as your local filesystem or dev tools—without risking exposure to the wider internet or other users. - Your connection is isolated; only your browser can access that tool server. -- **Global Tool Servers** +- **Global Tool Servers** - Requests are sent **from the Open WebUI backend/server** (not your browser). - - The backend must be able to reach the tool server URL you specify—so `localhost` means the backend server's localhost, _not_ your computer's. + - The backend must be able to reach the tool server URL you specify—so `localhost` means the backend server's localhost, *not* your computer's. - Use this for sharing tools with other users across the deployment, but be mindful: since the backend makes the requests, you cannot access your personal local resources (like your own filesystem) through this method. - Think security! Only expose remote/global endpoints that are safe and meant to be accessed by multiple users. **Summary Table:** -| Tool Server Type | Request Origin | Use Localhost? | Use Case Example | +| Tool Server Type | Request Origin | Use Localhost? | Use Case Example | | ------------------ | -------------------- | ------------------ | ---------------------------------------- | | User Tool Server | User's Browser (Client-side) | Yes (private to you) | Personal tools, local dev/testing | | Global Tool Server | Open WebUI Backend (Server-side) | No (unless running on the backend itself) | Team/shared tools, enterprise integrations | -:::tip +:::tip + User Tool Servers are best for personal or experimental tools, especially those running on your own machine, while Global Tool Servers are ideal for production or shared environments where everyone needs access to the same tools. + ::: ### 👉 Optional: Using a Config File with mcpo @@ -114,7 +115,7 @@ This means: ✅ Good: -http://localhost:8000/time +http://localhost:8000/time http://localhost:8000/memory 🚫 Not valid: @@ -163,14 +164,16 @@ Here’s what that looks like: - Once toggled on, they function the same way as user tools. - Admins can control access to global tools via role-based permissions. -This is ideal for team setups or shared environments, where commonly-used tools (e.g. document search, memory, or web lookup) should be centrally accessible by multiple users. +This is ideal for team setups or shared environments, where commonly-used tools (e.g., document search, memory, or web lookup) should be centrally accessible by multiple users. --- ## (Optional) Step 4: Use "Native" Function Calling (ReACT-style) Tool Use 🧠 :::info + For this to work effectively, **your selected model must support native tool calling**. Some local models claim support but often produce poor results. We strongly recommend using GPT-4o or another OpenAI model that supports function calling natively for the best experience. + ::: Want to enable ReACT-style (Reasoning + Acting) native function calls directly inside your conversations? You can switch Open WebUI to use native function calling. diff --git a/docs/pipelines/filters.md b/docs/pipelines/filters.md index 490901ad84..71014ef00a 100644 --- a/docs/pipelines/filters.md +++ b/docs/pipelines/filters.md @@ -9,7 +9,7 @@ Filters are used to perform actions against incoming user messages and outgoing

- Filter Workflow + ![Filter Workflow](/images/pipelines/filters.png)

diff --git a/docs/pipelines/index.mdx b/docs/pipelines/index.mdx index 4edc5e768b..72bdb7104c 100644 --- a/docs/pipelines/index.mdx +++ b/docs/pipelines/index.mdx @@ -3,26 +3,24 @@ sidebar_position: 1000 title: "⚡ Pipelines" --- - import { TopBanners } from "@site/src/components/TopBanners"; - - -

- Pipelines Logo + ![Pipelines Logo](/images/pipelines/header.png)

# Pipelines: UI-Agnostic OpenAI API Plugin Framework :::warning + **DO NOT USE PIPELINES IF!** If your goal is simply to add support for additional providers like Anthropic or basic filters, you likely don't need Pipelines . For those cases, Open WebUI Functions are a better fit—it's built-in, much more convenient, and easier to configure. Pipelines, however, comes into play when you're dealing with computationally heavy tasks (e.g., running large models or complex logic) that you want to offload from your main Open WebUI instance for better performance and scalability. + ::: Welcome to **Pipelines**, an [Open WebUI](https://github.com/open-webui) initiative. Pipelines bring modular, customizable workflows to any UI client supporting OpenAI API specs – and much more! Easily extend functionalities, integrate unique logic, and create dynamic workflows with just a few lines of code. @@ -47,7 +45,7 @@ Welcome to **Pipelines**, an [Open WebUI](https://github.com/open-webui) initiat

- Pipelines Workflow + ![Pipelines Workflow](/images/pipelines/workflow.png)

@@ -56,7 +54,9 @@ Integrating Pipelines with any OpenAI API-compatible UI client is simple. Launch ## ⚡ Quick Start with Docker :::warning + Pipelines are a plugin system with arbitrary code execution — **don't fetch random pipelines from sources you don't trust**. + ::: For a streamlined setup using Docker: @@ -75,7 +75,9 @@ For a streamlined setup using Docker: - Once you've added your pipelines connection and verified it, you will see an icon appear within the API Base URL field for the added connection. When hovered over, the icon itself will be labeled `Pipelines`. Your pipelines should now be active. :::info + If your Open WebUI is running in a Docker container, replace `localhost` with `host.docker.internal` in the API URL. + ::: 3. **Manage Configurations:** @@ -84,7 +86,9 @@ If your Open WebUI is running in a Docker container, replace `localhost` with `h - Select your desired pipeline and modify the valve values directly from the WebUI. :::tip + If you are unable to connect, it is most likely a Docker networking issue. We encourage you to troubleshoot on your own and share your methods and solutions in the discussions forum. + ::: If you need to install a custom pipeline with additional dependencies: diff --git a/docs/pipelines/pipes.md b/docs/pipelines/pipes.md index a4590480a3..f48ebcc31c 100644 --- a/docs/pipelines/pipes.md +++ b/docs/pipelines/pipes.md @@ -9,7 +9,7 @@ Pipes are standalone functions that process inputs and generate responses, possi

- Pipe Workflow + ![Pipe Workflow](/images/pipelines/pipes.png)

@@ -17,6 +17,6 @@ Pipes that are defined in your WebUI show up as a new model with an "External" d

- Pipe Models in WebUI + ![Pipe Models in WebUI](/images/pipelines/pipe-model-example.png)

diff --git a/docs/pipelines/tutorials.md b/docs/pipelines/tutorials.md index 974254f9fe..c704e0fb75 100644 --- a/docs/pipelines/tutorials.md +++ b/docs/pipelines/tutorials.md @@ -15,7 +15,7 @@ with us, as we'd love to feature it here! [Monitoring Open WebUI with Filters](https://medium.com/@0xthresh/monitor-open-webui-with-datadog-llm-observability-620ef3a598c6) (Medium article by @0xthresh) - A detailed guide to monitoring the Open WebUI using DataDog LLM observability. - + [Building Customized Text-To-SQL Pipelines](https://www.youtube.com/watch?v=y7frgUWrcT4) (YouTube video by Jordan Nanos) - Learn how to develop tailored text-to-sql pipelines, unlocking the power of data analysis and extraction. @@ -24,6 +24,6 @@ with us, as we'd love to feature it here! - A hands-on demonstration and code review on utilizing text-to-sql tools powered by the Open WebUI. -[Deploying custom Document RAG pipeline with Open-WebUI](https://github.com/Sebulba46/document-RAG-pipeline) (GitHub guide by Sebulba46) +[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. diff --git a/docs/pipelines/valves.md b/docs/pipelines/valves.md index eff32292b1..fb9cfe2e8f 100644 --- a/docs/pipelines/valves.md +++ b/docs/pipelines/valves.md @@ -5,7 +5,7 @@ title: "⚙️ Valves" # Valves -`Valves` (see the dedicated [Valves & UserValves](../features/plugin/valves/index.mdx) page) can also be set for `Pipeline`. In short, `Valves` are input variables that are set per pipeline. +`Valves` (see the dedicated [Valves & UserValves](/docs/features/plugin/valves/index.mdx) page) can also be set for `Pipeline`. In short, `Valves` are input variables that are set per pipeline. `Valves` are set as a subclass of the `Pipeline` class, and initialized as part of the `__init__` method of the `Pipeline` class. diff --git a/docs/roadmap.mdx b/docs/roadmap.mdx index 65f886c8a9..a25e53e428 100644 --- a/docs/roadmap.mdx +++ b/docs/roadmap.mdx @@ -7,7 +7,6 @@ import { TopBanners } from "@site/src/components/TopBanners"; - At Open WebUI, we're committed to continually enhancing our platform to provide the best experience for our users. Below, you'll find the structured roadmap for our ongoing and future developments, categorized into Interface, Information Retrieval, and Community. ## Interface 🖥️ @@ -38,7 +37,7 @@ Our roadmap for interface innovations aims to create a highly intuitive and acce ## Information Retrieval (RAG) 📚 -Open WebUI currently provides an interface that enables the use of existing information retrieval (IR) models efficiency. However, we believe there is vast potential for improvement. We fully recognize the limitations of our current RAG (Retrieval-Augmented Generation) implementation in our WebUI, understanding that a one-size-fits-all approach does not effectively meet all users' needs. +Open WebUI currently provides an interface that enables the use of existing information retrieval (IR) models efficiency. However, we believe there is vast potential for improvement. We fully recognize the limitations of our current RAG (Retrieval-Augmented Generation) implementation in our WebUI, understanding that a one-size-fits-all approach does not effectively meet all users' needs. To address this, we are committed to transforming our framework to be highly modular and extensively configurable. This new direction will enable users to tailor the information retrieval process to their specific requirements with ease, using a straightforward, interactive interface that allows for simple drag-and-drop customization. This refinement aims to significantly enhance user experience by providing a more adaptable and personalized IR setup. @@ -60,14 +59,13 @@ We aim to create a vibrant community where everyone can contribute to and benefi 🔗 **Community Whitepaper**: Explore our detailed strategy and join us in shaping the future of AI-driven platforms in our [whitepaper](https://openwebui.com/assets/files/whitepaper.pdf). - # Vision for the Future 🔭 -Our relentless effort stems from a clear vision we hold dearly: enhancing your daily life, saving time and allowing for more focus on what truly matters. +Our relentless effort stems from a clear vision we hold dearly: enhancing your daily life, saving time and allowing for more focus on what truly matters. Imagine a world where you think, and it happens. You desire a cup of coffee made exactly the way you love, and it's brewed for you. A world where you, simply think of a comprehensive data analysis report in a particular format, and it's done at the speed of your thought. The core idea is to turn the time-consuming, routine tasks over to our AI interface, freeing up your time and attention. -This isn’t a sci-fi future; together, we are working towards it right now. As our AI models gradually become more capable and intuitively understand your specific needs, your most mundane responsibilities become automated. Through this profound shift, our collective time allowance can be redistributed towards grand endeavours. Think space exploration, longevity research or simply extra moments with loved ones. +This isn’t a sci-fi future; together, we are working towards it right now. As our AI models gradually become more capable and intuitively understand your specific needs, your most mundane responsibilities become automated. Through this profound shift, our collective time allowance can be redistributed towards grand endeavours. Think space exploration, longevity research or simply extra moments with loved ones. Creating this imagined future won't be a walk in the park, but with your help, we believe it's within our reach. Open WebUI is more than just tech - it's there to enhance your day, giving you more space for what's really important. Together, we're working on a brighter tomorrow. Thanks for joining us in this extraordinary journey. diff --git a/docs/security.mdx b/docs/security.mdx index a8a7ee793f..e7b09fd08e 100644 --- a/docs/security.mdx +++ b/docs/security.mdx @@ -21,13 +21,14 @@ We employ a mixture of automated and manual techniques to keep up with evolving ## Where and How to Report Security Vulnerabilities :::info -Open WebUI’s community thrives because of people like you, people who care deeply about making software safer for everyone. + +Open WebUI’s community thrives because of people like you, people who care deeply about making software safer for everyone. To ensure your findings truly help protect users and are addressed swiftly, please submit all security vulnerability reports **only** via our [official GitHub security page](https://github.com/open-webui/open-webui/security). Any other website, service, or so-called “bounty” platform is ***not* affiliated** with us, and your important work will simply not reach those who can make a difference. We know it can be tempting to trust platforms that make big promises, but only GitHub connects you directly to those safeguarding Open WebUI. Let’s ensure your vigilance genuinely benefits the community, report here, where it really matters. -::: +::: **All security vulnerabilities for Open WebUI must be reported exclusively through our official GitHub repository: [https://github.com/open-webui/open-webui/security](https://github.com/open-webui/open-webui/security).** diff --git a/docs/sponsorships.mdx b/docs/sponsorships.mdx index ed36d696bb..1ed453e298 100644 --- a/docs/sponsorships.mdx +++ b/docs/sponsorships.mdx @@ -8,8 +8,7 @@ import { TopBanners } from "@site/src/components/TopBanners"; ## The Impact of Your Support - -[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/tjbck) +[![Image Description](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/tjbck) As Open WebUI grows, the tasks and challenges we face expand as well. [Tim](/team) is at the heart of this project, tirelessly working to ensure all aspects of Open WebUI not only function but thrive. Yet, imagine the additional improvements we could make with a little extra support. @@ -19,9 +18,6 @@ We're incredibly thankful to our current sponsors. Your commitment has brought u Thank you for considering joining us in this practical yet visionary endeavor. Here, every bit of support is not only appreciated—it’s crucial for keeping our project vibrant, dynamic, and responsive to users’ needs. - - - ## Sponsorship Policies At Open WebUI, our community always comes first. Sponsors are welcome, but they must respect our community-first approach. This philosophy guides all our sponsorship policies. diff --git a/docs/team.mdx b/docs/team.mdx index 94c3b3e110..186c3a3a65 100644 --- a/docs/team.mdx +++ b/docs/team.mdx @@ -9,7 +9,7 @@ import { TopBanners } from "@site/src/components/TopBanners"; ## 🌟 Meet Our Core Development Team! -:::tip +:::tip ### 🚀 We're Actively Hiring! diff --git a/docs/troubleshooting/compatibility.mdx b/docs/troubleshooting/compatibility.mdx index da243eec98..9484299ea5 100644 --- a/docs/troubleshooting/compatibility.mdx +++ b/docs/troubleshooting/compatibility.mdx @@ -9,8 +9,8 @@ Open WebUI is designed for and tested on modern browsers. To ensure the best exp Open WebUI's core functionality specifically depends on these browser versions: -- **Chrome 111** 🟢 _(Released March 2023)_ -- **Safari 16.4** 🍏 _(Released March 2023)_ -- **Firefox 128** 🔥 _(Released July 2024)_ +- **Chrome 111** 🟢 *(Released March 2023)* +- **Safari 16.4** 🍏 *(Released March 2023)* +- **Firefox 128** 🔥 *(Released July 2024)* 💡 If you experience any issues, ensure your browser is up to date or try an alternative supported browser. diff --git a/docs/troubleshooting/index.mdx b/docs/troubleshooting/index.mdx index 42fb99e5e0..f9b973f7ed 100644 --- a/docs/troubleshooting/index.mdx +++ b/docs/troubleshooting/index.mdx @@ -4,19 +4,17 @@ title: "🛠️ Troubleshooting" --- import { TopBanners } from "@site/src/components/TopBanners"; - - ## 🌟 General Troubleshooting Tips Encountering issues? Don't worry, we're here to help! 😊 Start with this important step: -- 🔄 Make sure you're using the **latest version** of the software. +- 🔄 Make sure you're using the **latest version** of the software. With this project constantly evolving, updates and fixes are regularly added. Keeping your software up-to-date is crucial to take advantage of all the enhancements and fixes, ensuring the best possible experience. 🚀 -### 🤝 Community Support +### 🤝 Community Support This project thrives on community spirit and passion. If you still face problems after updating, we warmly invite you to join our vibrant community on [Discord](https://discord.com/invite/5rJgQTnV4s). There, you can share your experiences, find solutions, and connect with fellow enthusiasts who might be navigating similar challenges. Engaging with our community doesn't just help solve your problems; it strengthens the entire network of support, so we all grow together. 🌱 diff --git a/docs/troubleshooting/password-reset.mdx b/docs/troubleshooting/password-reset.mdx index 34626da455..0b635d79a4 100644 --- a/docs/troubleshooting/password-reset.mdx +++ b/docs/troubleshooting/password-reset.mdx @@ -19,8 +19,12 @@ First, you need to create a bcrypt hash of your new password. Run the following htpasswd -bnBC 10 "" your-new-password | tr -d ':\n' ``` +:::note + **Note:** The output will include a bcrypt hash with special characters that need to be handled carefully. Any `$` characters in the hash will need to be triple-escaped (replaced with `\\\`) to be used correctly in the next step. +::: + ### Step 2: Update the Password in Docker 🔄 Next, you'll update the password in your Docker deployment. Replace `HASH` in the command below with the bcrypt hash generated in Step 1, making sure to triple-escape any `$` characters. Also, replace `admin@example.com` with the email address linked to your admin account. @@ -51,10 +55,9 @@ Now, navigate to the `open-webui` directory on your local machine. Update your p sqlite3 backend/data/webui.db "UPDATE auth SET password='HASH' WHERE email='admin@example.com';" ``` - #### Alternate Docker Method -_If you have issues with the above._ I had issues chaining the `bash` commands in `alpine/socat`, _since `bash` doesn't exist._ +*If you have issues with the above.* I had issues chaining the `bash` commands in `alpine/socat`, *since `bash` doesn't exist.* 1. **Run `alpine` linux connected to the open-webui volume.** @@ -84,6 +87,7 @@ _If you have issues with the above._ I had issues chaining the `bash` commands UPDATE auth SET password='HASH' WHERE email='admin@example.com'; -- exit sqlite: [Ctrl + d] ``` + ## Nuking All the Data If you want to **completely reset** Open WebUI—including all user data, settings, and passwords—follow these steps to remove the `webui.db` file. @@ -126,9 +130,10 @@ Once you’ve located the file, remove it using a command similar to: rm -rf /path/to/your/python/environment/lib/pythonX.X/site-packages/open_webui/data/webui.db ``` -**Warning:** Deleting `webui.db` will remove all stored data, including user accounts, settings, and passwords. Only do this if you truly want to start fresh! +:::warning - +**Warning:** Deleting `webui.db` will remove all stored data, including user accounts, settings, and passwords. Only do this if you truly want to start fresh! +::: 📖 By following these straightforward steps, you'll regain access to your Open WebUI admin account in no time. If you encounter any issues during the process, please consider searching for your issue on forums or community platforms. diff --git a/docs/troubleshooting/rag.mdx b/docs/troubleshooting/rag.mdx index c0d4233e48..02cc938944 100644 --- a/docs/troubleshooting/rag.mdx +++ b/docs/troubleshooting/rag.mdx @@ -21,13 +21,17 @@ 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. + +::: --- ### 2. Only a Small Part of the Document is Being Used 📄➡️✂️ -Open WebUI is designed to work with models that have limited context windows by default. For instance, many local models (e.g. Ollama's default models) are limited to 2048 tokens. Because of this, Open WebUI aggressively trims down the retrieved content to fit within the assumed available space. +Open WebUI is designed to work with models that have limited context windows by default. For instance, many local models (e.g., Ollama's default models) are limited to 2048 tokens. Because of this, Open WebUI aggressively trims down the retrieved content to fit within the assumed available space. ✅ Solutions: @@ -36,8 +40,12 @@ Open WebUI is designed to work with models that have limited context windows by - 💡 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 + 📌 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 ⏳ @@ -72,7 +80,11 @@ Even after content extraction and cleaning, web pages easily consume 4,000-8,000 - Try GPT-4, GPT-4o, Claude 3, Gemini 1.5, or Mixtral with 8k+ context - Compare performance to Ollama—notice the dramatic accuracy difference when more web content can be processed! -📌 Tip: For web search and complex document analysis, stick with models that support 8192+ token contexts in production use cases. +::tip + +For web search and complex document analysis, stick with models that support 8192+ token contexts in production use cases. + +::: --- @@ -106,7 +118,11 @@ This error indicates a misconfigured or missing embedding model. When Open WebUI - Save the embedding model again—even if it's already selected. This forces a recheck/download. - If you're using a remote/external embedding tool, make sure it's running and accessible to Open WebUI. -📌 Tip: After fixing the configuration, try re-embedding a document and verify no error is shown in the logs. +::tip + +After fixing the configuration, try re-embedding a document and verify no error is shown in the logs. + +::: --- diff --git a/docs/troubleshooting/sso.mdx b/docs/troubleshooting/sso.mdx index faf5386f12..b55234c0b0 100644 --- a/docs/troubleshooting/sso.mdx +++ b/docs/troubleshooting/sso.mdx @@ -13,7 +13,12 @@ Most OAUTH flows require the application's external URL ("redirect URI") so the ✅ Solution: - Navigate to: **Admin Settings > General** - Ensure your **WebUI URL** field is filled in and points to your deployed instance (e.g., `https://yourwebui.yourdomain.com`) -📌 Tip: Check for typos! OAUTH is strict—URLs must match exactly, including `https://`. + +::tip + +Check for typos! OAUTH is strict—URLs must match exactly, including `https://`. + +::: --- @@ -24,7 +29,7 @@ This is by far the **most common cause** of OAUTH breakage. If you misspell, omi #### ❌ Non-Existent Variables People Often Use: - `OIDC_CONFIG` → Use `OPENID_PROVIDER_URL` instead -- `WEBUI_OIDC_CLIENT_ID` → Use `OAUTH_CLIENT_ID` 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 @@ -32,9 +37,10 @@ This is by far the **most common cause** of OAUTH breakage. If you misspell, omi #### ✅ Correct OIDC Variables: ```bash + # Required for OIDC OAUTH_CLIENT_ID=your_client_id -OAUTH_CLIENT_SECRET=your_client_secret +OAUTH_CLIENT_SECRET=your_client_secret OPENID_PROVIDER_URL=https://your-provider/.well-known/openid-configuration ENABLE_OAUTH_SIGNUP=true @@ -46,6 +52,7 @@ 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 @@ -61,7 +68,11 @@ ENABLE_OAUTH_SIGNUP=true - 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 named, missing entirely, or using outdated variable names! +::tip + +Most OAUTH errors (loops, 401s, unresponsiveness) are due to an environment variable incorrectly named, missing entirely, or using outdated variable names! + +::: --- @@ -140,7 +151,11 @@ Sometimes the issue is with the identity provider (e.g., Google, Okta, Auth0, Az ❌ Wrong: https://ai.company.com/callback ``` -📌 Tip: When in doubt, recheck your provider registration and regenerate client secrets if needed. +::tip + +When in doubt, recheck your provider registration and regenerate client secrets if needed. + +::: --- @@ -156,6 +171,7 @@ A **new and tricky problem**: If you use NGINX (or another reverse proxy) with s **Example NGINX Configuration:** ```nginx + # Disable caching for login / OAuth / websockets endpoints location ~* ^/(api|oauth|callback|login|ws|websocket) { proxy_no_cache 1; @@ -173,8 +189,12 @@ location ~* ^/(api|oauth|callback|login|ws|websocket) { } ``` +:::warning + 📌 Warning: Never cache OAUTH or login endpoints! Caching can "poison" the session or deliver stale tokens, causing bizarre auth errors. +::: + --- ### 7. Cookie Configuration Issues 🍪⚙️ @@ -190,17 +210,22 @@ location ~* ^/(api|oauth|callback|login|ws|websocket) { #### 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 @@ -221,8 +246,9 @@ WEBUI_AUTH_COOKIE_SECURE=true # Set to false if using HTTP ✅ **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=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 ``` @@ -241,12 +267,14 @@ AIOHTTP_CLIENT_TIMEOUT_OPENAI_MODEL_LIST=30 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 @@ -260,6 +288,7 @@ OAUTH_SESSION_TOKEN_ENCRYPTION_KEY=another_secure_key_here #### 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 @@ -283,9 +312,10 @@ WEBSOCKET_MANAGER=redis ✅ **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_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 @@ -325,13 +355,18 @@ Recent versions of Open WebUI moved from URL-based tokens to cookie-based tokens 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 ``` @@ -339,6 +374,7 @@ GLOBAL_LOG_LEVEL=DEBUG Check if user accounts are being created: ```bash + # Access your container docker exec -it your-openwebui-container sh @@ -363,7 +399,7 @@ If using a reverse proxy, test OAuth directly against Open WebUI: ### Key Log Messages to Watch For: - `OAuth callback error: mismatching_state` → Session/cookie issue -- `httpcore.ReadTimeout` → Network timeout 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 @@ -383,7 +419,7 @@ If using a reverse proxy, test OAuth directly against Open WebUI: | ⏱️ 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 | +| Still stuck? | Check debug logs, test without proxy, verify provider setup | --- diff --git a/docs/tutorials/database.mdx b/docs/tutorials/database.mdx index 18fd46d78e..4ca91866ce 100644 --- a/docs/tutorials/database.mdx +++ b/docs/tutorials/database.mdx @@ -1,9 +1,8 @@ --- -sidebar_position: 310 +sidebar_position: 310 title: "📦 Exporting and Importing Database" --- - If you need to migrate your **Open WebUI** data (e.g., chat histories, configurations, etc.) from one server to another or back it up for later use, you can export and import the database. This guide assumes you're running Open WebUI using the internal SQLite database (not PostgreSQL). Follow the steps below to export and import the `webui.db` file, which contains your database. @@ -14,13 +13,13 @@ Follow the steps below to export and import the `webui.db` file, which contains To export the database from your current Open WebUI instance: -1. **Use `docker cp` to copy the database file**: - The `webui.db` file is located in the container inside the directory `/app/backend/data`. Run the following command to copy it into your local machine: +1. **Use `docker cp` to copy the database file**: + The `webui.db` file is located in the container inside the directory `/app/backend/data`. Run the following command to copy it into your local machine: ```bash docker cp open-webui:/app/backend/data/webui.db ./webui.db ``` -2. **Transfer the exported file to the new server**: +2. **Transfer the exported file to the new server**: You can use **FileZilla** or any other file transfer tool of your choice to move the `webui.db` file to the new server. :::info @@ -33,19 +32,19 @@ To export the database from your current Open WebUI instance: After moving the `webui.db` file to the new server, follow these steps: -1. **Install and Run Open WebUI on the New Server**: +1. **Install and Run Open WebUI on the New Server**: Set up and run Open WebUI using a Docker container. Follow the instructions provided in the [🚀 Getting Started](/getting-started) to install and start the Open WebUI container. Once it's running, stop it before performing the import step. ```bash docker stop open-webui ``` -2. **Use `docker cp` to copy the database file to the container**: +2. **Use `docker cp` to copy the database file to the container**: Assuming the exported `webui.db` file is in your current working directory, copy it into the container: ```bash docker cp ./webui.db open-webui:/app/backend/data/webui.db ``` -3. **Start the Open WebUI container**: +3. **Start the Open WebUI container**: Start the container again to use the imported database. ```bash docker start open-webui @@ -71,7 +70,9 @@ This approach is particularly useful when: - Testing Open WebUI on multiple servers with the same setup. ```bash + # Quick commands summary for export and import + # Export: docker cp open-webui:/app/backend/data/webui.db ./webui.db diff --git a/docs/tutorials/deployment/index.mdx b/docs/tutorials/deployment/index.mdx index 432af1738d..7f767bcdc7 100644 --- a/docs/tutorials/deployment/index.mdx +++ b/docs/tutorials/deployment/index.mdx @@ -6,14 +6,17 @@ import { TopBanners } from "@site/src/components/TopBanners"; - :::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. + ::: :::info + # 📢 **Calling all YouTubers and Content Creators!** 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! + ::: ## Articles diff --git a/docs/tutorials/docker-install.md b/docs/tutorials/docker-install.md index 772f9d177e..c25e7823c7 100644 --- a/docs/tutorials/docker-install.md +++ b/docs/tutorials/docker-install.md @@ -3,22 +3,26 @@ sidebar_position: 4 title: 🐳 Installing Docker --- -:::info **Looking to install Open WebUI?** +:::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. + ::: # Installing Docker ## For Windows and Mac Users -- Download Docker Desktop from [Docker's official website](https://www.docker.com/products/docker-desktop). -- Follow the installation instructions on the website. +- Download Docker Desktop from [Docker's official website](https://www.docker.com/products/docker-desktop). +- Follow the installation instructions on the website. - After installation, **open Docker Desktop** to ensure it's running properly. --- @@ -42,7 +46,9 @@ This tutorial is a community contribution and is not supported by the Open WebUI ``` :::note + If using an **Ubuntu derivative** (e.g., Linux Mint), use `UBUNTU_CODENAME` instead of `VERSION_CODENAME`. + ::: 3. **Install Docker Engine:** diff --git a/docs/tutorials/https-caddy.md b/docs/tutorials/https-caddy.md index 1c5edc1d19..a97e3e47d0 100644 --- a/docs/tutorials/https-caddy.md +++ b/docs/tutorials/https-caddy.md @@ -4,7 +4,9 @@ title: "🔒 HTTPS using Caddy" --- :::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. + ::: # HTTPS using Caddy @@ -15,7 +17,6 @@ This guide is simple walkthrough to set up a Ubuntu server with Caddy as a rever There's a few steps we'll follow to get everything set up: - - [HTTPS using Caddy](#https-using-caddy) - [Docker](#docker) - [Installing Docker](#installing-docker) @@ -55,7 +56,7 @@ cd ~/open-webui ### Installing OpenWebUI -Create a `docker-compose.yml` file in the `~/open-webui` directory. I've left in a commented section for setting some environment varibles for Qdrant, but you can follow that for any other [environment variables](https://docs.openwebui.com/getting-started/env-configuration) you might need to set. +Create a `docker-compose.yml` file in the `~/open-webui` directory. I've left in a commented section for setting some environment varibles for Qdrant, but you can follow that for any other [environment variables](https://docs.openwebui.com/getting-started/env-configuration) you might need to set. ```yaml services: @@ -72,18 +73,17 @@ services: restart: unless-stopped ``` - ## Caddy Caddy is a powerful web server that automatically manages TLS certificates for you, making it an excellent choice for serving Open WebUI over HTTPS. ### Installing Caddy -Follow the [guide to set up Caddy's on Ubuntu](https://caddyserver.com/docs/install#debian-ubuntu-raspbian). +Follow the [guide to set up Caddy's on Ubuntu](https://caddyserver.com/docs/install#debian-ubuntu-raspbian). ### Configure Caddy -You're going to need to change the `CaddyFile` to use your domain. +You're going to need to change the `CaddyFile` to use your domain. To do that, edit the file `/etc/caddy/Caddyfile`. diff --git a/docs/tutorials/https-haproxy.md b/docs/tutorials/https-haproxy.md index d32c45fc39..84683811fb 100644 --- a/docs/tutorials/https-haproxy.md +++ b/docs/tutorials/https-haproxy.md @@ -4,7 +4,9 @@ title: "🔒 HTTPS using HAProxy" --- :::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. + ::: # HAProxy Configuration for Open WebUI @@ -14,26 +16,31 @@ HAProxy (High Availability Proxy) is specialized load-balancing and reverse prox ## Install HAProxy and Let's Encrypt First, install HAProxy and Let's Encrypt's certbot: + ### Redhat derivatives + ```sudo dnf install haproxy certbot openssl -y``` + ### Debian derivatives + ```sudo apt install haproxy certbot openssl -y``` ## HAProxy Configuration Basics HAProxy's configuration is by default stored in ```/etc/haproxy/haproxy.cfg```. This file contains all the configuration directives that determine how HAProxy will operate. -The base configuration for HAProxy to work with Open WebUI is pretty simple. +The base configuration for HAProxy to work with Open WebUI is pretty simple. ``` #--------------------------------------------------------------------- + # Global settings #--------------------------------------------------------------------- global # to have these messages end up in /var/log/haproxy.log you will # need to: # - # 1) configure syslog to accept network log events. This is done + # 1) configure syslog to accept network log events. This is done # by adding the '-r' option to the SYSLOGD_OPTIONS in # /etc/sysconfig/syslog # @@ -51,11 +58,13 @@ global user haproxy group haproxy daemon - - #adjust the dh-param if too low + + #adjust the dh-param if too low tune.ssl.default-dh-param 2048 #--------------------------------------------------------------------- + # common defaults that all the 'listen' and 'backend' sections will + # use if not designated in their block #--------------------------------------------------------------------- defaults @@ -78,16 +87,16 @@ defaults #http frontend web - #Non-SSL + #Non-SSL bind 0.0.0.0:80 - #SSL/TLS - bind 0.0.0.0:443 ssl crt /path/to/ssl/folder/ + #SSL/TLS + bind 0.0.0.0:443 ssl crt /path/to/ssl/folder/ #Let's Encrypt SSL acl letsencrypt-acl path_beg /.well-known/acme-challenge/ use_backend letsencrypt-backend if letsencrypt-acl - #Subdomain method + #Subdomain method acl chat-acl hdr(host) -i subdomain.domain.tld #Path Method acl chat-acl path_beg /owui/ @@ -96,23 +105,25 @@ frontend web #Pass SSL Requests to Lets Encrypt backend letsencrypt-backend server letsencrypt 127.0.0.1:8688 - + #OWUI Chat backend owui_chat # add X-FORWARDED-FOR option forwardfor # add X-CLIENT-IP http-request add-header X-CLIENT-IP %[src] - http-request set-header X-Forwarded-Proto https if { ssl_fc } + http-request set-header X-Forwarded-Proto https if { ssl_fc } server chat :3000 ``` -You will see that we have ACL records (routers) for both Open WebUI and Let's Encrypt. To use WebSocket with OWUI, you need to have an SSL configured, and the easiest way to do that is to use Let's Encrypt. +You will see that we have ACL records (routers) for both Open WebUI and Let's Encrypt. To use WebSocket with OWUI, you need to have an SSL configured, and the easiest way to do that is to use Let's Encrypt. You can use either the subdomain method or the path method for routing traffic to Open WebUI. The subdomain method requires a dedicated subdomain (e.g., chat.yourdomain.com), while the path method allows you to access Open WebUI through a specific path on your domain (e.g., yourdomain.com/owui/). Choose the method that best suits your needs and update the configuration accordingly. :::info + You will need to expose port 80 and 443 to your HAProxy server. These ports are required for Let's Encrypt to validate your domain and for HTTPS traffic. You will also need to ensure your DNS records are properly configured to point to your HAProxy server. If you are running HAProxy at home, you will need to use port forwarding in your router to forward ports 80 and 443 to your HAProxy server. + ::: ## Issuing SSL Certificates with Let's Encrypt @@ -128,7 +139,9 @@ Then combine the key and certificate into a PEM file that HAProxy can use: ```cat /tmp/haproxy.crt /tmp/haproxy.key > /etc/haproxy/certs/haproxy.pem``` :::info + Make sure you update the HAProxy configuration based on your needs and configuration. + ::: Once you have your HAProxy configuration set up, you can use certbot to obtain and manage your SSL certificates. Certbot will handle the validation process with Let's Encrypt and automatically update your certificates when they are close to expiring (assuming you use the certbot auto-renewal service). @@ -138,7 +151,7 @@ You can validate the HAProxy configuration by running `haproxy -c -f /etc/haprox To ensure HAProxy starts with the system, `systemctl enable haproxy`. When you have HAProxy configured, you can use Let's encrypt to issue your valid SSL certificate. -First, you will need to register with Let's Encrypt. You should only need to do this one time: +First, you will need to register with Let's Encrypt. You should only need to do this one time: `certbot register --agree-tos --email your@email.com --non-interactive` @@ -155,15 +168,18 @@ cat /etc/letsencrypt/live/{domain}/fullchain.pem /etc/letsencrypt/live/{domain}/ chmod 600 /etc/haproxy/certs/{domain}.pem chown haproxy:haproxy /etc/haproxy/certs/{domain}.pem ``` + You can then restart HAProxy to apply the new certificate: `systemctl restart haproxy` ## HAProxy Manager (Easy Deployment Option) -If you would like to have something manage your HAProxy configuration and Let's Encrypt SSLs automatically, I have written a simple python script and created a docker container you can use to create and manage your HAProxy config and manage the Let's Encrypt certificate lifecycle. +If you would like to have something manage your HAProxy configuration and Let's Encrypt SSLs automatically, I have written a simple python script and created a docker container you can use to create and manage your HAProxy config and manage the Let's Encrypt certificate lifecycle. https://github.com/shadowdao/haproxy-manager :::warning + Please do not expose port 8000 publicly if you use the script or container! -::: \ No newline at end of file + +::: diff --git a/docs/tutorials/https-nginx.md b/docs/tutorials/https-nginx.md index 97ee7dd1ad..6a808508e8 100644 --- a/docs/tutorials/https-nginx.md +++ b/docs/tutorials/https-nginx.md @@ -4,7 +4,9 @@ title: "🔒 HTTPS using Nginx" --- :::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. + ::: # HTTPS using Nginx @@ -19,7 +21,6 @@ This guide provides three methods to set up HTTPS: Choose the method that best fits your deployment needs. - import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -43,7 +44,6 @@ import Windows from './tab-nginx/Windows.md'; - ## Next Steps After setting up HTTPS, access Open WebUI securely at: diff --git a/docs/tutorials/images.md b/docs/tutorials/images.md index bd1fd3241d..92e39489b9 100644 --- a/docs/tutorials/images.md +++ b/docs/tutorials/images.md @@ -4,7 +4,9 @@ title: "🎨 Image Generation" --- :::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. + ::: # 🎨 Image Generation @@ -73,23 +75,23 @@ ComfyUI provides an alternative interface for managing and interacting with imag 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. +- 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. +- 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. +- 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. +- 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: @@ -99,7 +101,7 @@ To integrate ComfyUI into Open WebUI, follow these steps: 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://:8188/`. - * Set the environment variable `COMFYUI_BASE_URL` to this address to ensure it persists within the WebUI. + - 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 @@ -117,11 +119,16 @@ To integrate ComfyUI into Open WebUI, follow these steps: 6. Set `Set Default Model` to the name of the model file being used, such as `flux1-dev.safetensors` :::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`). + +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! @@ -151,9 +158,9 @@ Open WebUI also supports image generation through the **OpenAI APIs**. This opti 2. Set the `Image Generation Engine` field to `Open AI`. 3. Enter your OpenAI API key. 4. Choose the 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. - * **GPT-Image-1**: Supports `auto`, `1024x1024`, `1536x1024`, or `1024x1536` images. + - **DALL·E 2**: Supports `256x256`, `512x512`, or `1024x1024` images. + - **DALL·E 3**: Supports `1024x1024`, `1792x1024`, or `1024x1792` images. + - **GPT-Image-1**: Supports `auto`, `1024x1024`, `1536x1024`, or `1024x1536` images. ### Azure OpenAI @@ -166,9 +173,11 @@ Image generation with Azure OpenAI Dall-E or GPT-Image is supported with Open We 5. Enter your Azure OpenAI API key. :::tip + Alternative API endpoint URL tutorial: `https://.openai.azure.com/openai/deployments//` - 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/`. + ::: ======= @@ -191,7 +200,7 @@ Open WebUI also supports image generation through the **Image Router APIs**. Ima ## Using Image Generation -#### Method 1: +#### Method 1 1. Toggle the `Image Generation` switch to on. 2. Enter your image generation prompt. @@ -199,7 +208,7 @@ Open WebUI also supports image generation through the **Image Router APIs**. Ima ![Image Generation Tutorial](/images/tutorial_image_generation_2.png) -#### Method 2: +#### Method 2 ![Image Generation Tutorial](/images/tutorial_image_generation.png) @@ -208,7 +217,9 @@ Open WebUI also supports image generation through the **Image Router APIs**. Ima 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 + +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. + ::: diff --git a/docs/tutorials/integrations/amazon-bedrock.md b/docs/tutorials/integrations/amazon-bedrock.md index 70ca1275e0..7d4e707d54 100644 --- a/docs/tutorials/integrations/amazon-bedrock.md +++ b/docs/tutorials/integrations/amazon-bedrock.md @@ -4,7 +4,9 @@ title: "🛌 Integrate with Amazon Bedrock" --- :::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. + ::: --- @@ -15,7 +17,6 @@ In this tutorial, we'll explore one of the most common and popular approaches to ## Prerequisites - In order to follow this tutorial, you must have the following: - An active AWS account @@ -23,7 +24,6 @@ In order to follow this tutorial, you must have the following: - IAM permissions in AWS to enable Bedrock models or already enabled models - Docker installed on your system - ## What is Amazon Bedrock Direct from AWS' website: @@ -42,14 +42,12 @@ AWS provides good documentation for request accessing / enabling these models he ![Amazon Bedrock Base Models](/images/tutorials/amazon-bedrock/amazon-bedrock-base-models.png) - ## Step 2: Configure the Bedrock Access Gateway Now that we have access to at least one Bedrock base model, we need to configure the Bedrock Access Gateway, or BAG. You can think of the BAG as kind of proxy or middleware developed by AWS that wraps around AWS native endpoints/SDK for Bedrock and, in turn, exposes endpoints that are compatible with OpenAI's schema, which is what Open-WebUI requires. For reference, here is a simple mapping between the endpoints: - | OpenAI Endpoint | Bedrock Method | |-----------------------|------------------------| | `/models` | list_inference_profiles | @@ -60,6 +58,7 @@ For reference, here is a simple mapping between the endpoints: The BAG repo can be found here: [Bedrock Access Gateway Repo](https://github.com/aws-samples/bedrock-access-gateway) To set-up the BAG, follow the below steps: + - Clone the BAG repo - Remove the default `dockerfile` - Change the name of the `Dockerfile_ecs` to `Dockerfile` diff --git a/docs/tutorials/integrations/azure-ad-ds-ldap.mdx b/docs/tutorials/integrations/azure-ad-ds-ldap.mdx index 3920868f13..ec3520fc57 100644 --- a/docs/tutorials/integrations/azure-ad-ds-ldap.mdx +++ b/docs/tutorials/integrations/azure-ad-ds-ldap.mdx @@ -3,7 +3,9 @@ title: "Azure AD Domain Services (LDAPS) Integration" --- :::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. + ::: This guide explains how to integrate Open WebUI with Azure AD Domain Services (AAD DS) for secure LDAP (LDAPS) authentication. @@ -12,32 +14,34 @@ This guide explains how to integrate Open WebUI with Azure AD Domain Services (A | Item | Description | | ------------------- | ------------------------------------------------------------------------ | -| **Azure Account** | An account with permissions to deploy AAD DS and modify NSGs. | -| **OpenSSL 3.x** | Required to generate a self-signed PFX for testing. | +| **Azure Account** | An account with permissions to deploy AAD DS and modify NSGs. | +| **OpenSSL 3.x** | Required to generate a self-signed PFX for testing. | | **Domain Name** | We'll use `openwebui.onmicrosoft.com` as an example (your AAD primary domain). | -| **Open WebUI Server** | A running instance of Open WebUI, deployed via Docker or bare-metal. | +| **Open WebUI Server** | A running instance of Open WebUI, deployed via Docker or bare-metal. | :::caution + In a production environment, use a PFX certificate issued by a public Certificate Authority (CA) and set `LDAP_VALIDATE_CERT=true`. + ::: ## 2. Deploy Azure AD Domain Services -1. In the Azure Portal, search for and select **Azure AD Domain Services**. -2. Click **Create**. -3. Select your **Subscription** and **Resource Group** (or create a new one). -4. For **DNS domain name**, enter your domain (e.g., `openwebui.onmicrosoft.com`). This value will be used for `LDAP_SEARCH_BASE` later. -5. Keep the default settings for **SKU**, **Replica Set**, etc., and click **Review + create**. +1. In the Azure Portal, search for and select **Azure AD Domain Services**. +2. Click **Create**. +3. Select your **Subscription** and **Resource Group** (or create a new one). +4. For **DNS domain name**, enter your domain (e.g., `openwebui.onmicrosoft.com`). This value will be used for `LDAP_SEARCH_BASE` later. +5. Keep the default settings for **SKU**, **Replica Set**, etc., and click **Review + create**. ![Azure AD DS Creation - Basics Tab](/images/tutorials/ldap/azure-ad-ds-create-basics.png) -6. After deployment, navigate to the Azure AD DS blade and note the **Virtual network / Subnet**. If your Open WebUI server is not in the same VNet, you must create an NSG rule to allow traffic on port 636. +6. After deployment, navigate to the Azure AD DS blade and note the **Virtual network / Subnet**. If your Open WebUI server is not in the same VNet, you must create an NSG rule to allow traffic on port 636. ## 3. Find the Secure LDAP External IP -1. Navigate to your AAD DS Blade → **Overview**. -2. Under **Secure LDAP**, find the **External IP addresses**. -3. This IP (e.g., `1.222.222.222`) will be your `LDAP_SERVER_HOST` value in the `.env` file. +1. Navigate to your AAD DS Blade → **Overview**. +2. Under **Secure LDAP**, find the **External IP addresses**. +3. This IP (e.g., `1.222.222.222`) will be your `LDAP_SERVER_HOST` value in the `.env` file. ![Find Secure LDAP External IP](/images/tutorials/ldap/azure-ad-ds-secure-ldap-ip.png) @@ -50,15 +54,17 @@ In a production environment, use a PFX certificate issued by a public Certificat | **Format** | PKCS #12 (.pfx) | | **Encryption** | RSA 2048 / SHA-256 | | **Subject Alternative Name (SAN)** | Must include wildcards: `*.{your_domain}.onmicrosoft.com` and `{your_domain}.onmicrosoft.com`. | -| **Password** | Required for upload. Make sure to remember it. | +| **Password** | Required for upload. Make sure to remember it. | :::info + For production, we recommend using Let’s Encrypt or another public CA. The self-signed process below is for testing purposes only. + ::: ### 4.2. Generate a Wildcard PFX with OpenSSL (for testing) -1. **Create `openssl_wildcard.cnf`:** +1. **Create `openssl_wildcard.cnf`:** ```ini [ req ] @@ -95,7 +101,7 @@ For production, we recommend using Let’s Encrypt or another public CA. The sel ``` *Replace `{your_domain}` with your actual domain.* -2. **Generate Key & Certificate:** +2. **Generate Key & Certificate:** ```bash # Generate a private key @@ -116,10 +122,10 @@ For production, we recommend using Let’s Encrypt or another public CA. The sel -inkey privatekey_wildcard.key -in certificate_wildcard.crt ``` -3. **Upload to AAD DS:** - 1. Navigate to your AAD DS Blade → **Secure LDAP**. - 2. Click the **Upload certificate** button, select `certificate_wildcard.pfx`, and enter the password. - 3. Toggle **Secure LDAP** to **Enabled** and click **Save**. +3. **Upload to AAD DS:** + 1. Navigate to your AAD DS Blade → **Secure LDAP**. + 2. Click the **Upload certificate** button, select `certificate_wildcard.pfx`, and enter the password. + 3. Toggle **Secure LDAP** to **Enabled** and click **Save**. ![Enable Secure LDAP](/images/tutorials/ldap/azure-ad-ds-ldaps-enabled.png) @@ -137,15 +143,17 @@ For production, we recommend using Let’s Encrypt or another public CA. The sel ![NSG Inbound Rule for LDAPS](/images/tutorials/ldap/azure-nsg-inbound-rule-ldaps.png) :::warning + If allowing access from the internet, restrict the source IP range to the minimum required for security. If Open WebUI is in the same VNet, this step can be skipped. + ::: ## 6. Create a Service Account in Entra ID -1. In the Azure Portal, navigate to **Entra ID** → **Users** → **New user**. -2. Set the username (e.g., `ldap@{your_domain}.onmicrosoft.com`). -3. Set a strong password and uncheck **User must change password at next sign-in**. -4. Go to the **Groups** tab and add the user to the **AAD DC Administrators** group (required for querying all users). +1. In the Azure Portal, navigate to **Entra ID** → **Users** → **New user**. +2. Set the username (e.g., `ldap@{your_domain}.onmicrosoft.com`). +3. Set a strong password and uncheck **User must change password at next sign-in**. +4. Go to the **Groups** tab and add the user to the **AAD DC Administrators** group (required for querying all users). ![Create Entra ID Service Account](/images/tutorials/ldap/entra-id-create-service-account.png) @@ -154,8 +162,11 @@ If allowing access from the internet, restrict the source IP range to the minimu Here is an example configuration for your `.env` file: ```env + ############################################### + # LDAP + ############################################### ENABLE_LDAP="true" LDAP_SERVER_LABEL="Azure AD DS" @@ -178,8 +189,11 @@ LDAP_ATTRIBUTE_FOR_MAIL="userPrincipalName" LDAP_SEARCH_FILTER="(&(objectClass=user)(objectCategory=person))" # Group Synchronization (Optional) + # ENABLE_LDAP_GROUP_MANAGEMENT="true" + # ENABLE_LDAP_GROUP_CREATION="true" + # LDAP_ATTRIBUTE_FOR_GROUPS="memberOf" ``` *Replace placeholders like `{your_domain}` and `` with your actual values.* diff --git a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md index ec2f4e4c89..16feca2dbd 100644 --- a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md +++ b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md @@ -4,7 +4,9 @@ title: "🔄 Backend-Controlled, UI-Compatible API Flow" --- :::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](/docs/tutorials/tips/contributing-tutorial.md). + ::: --- @@ -49,6 +51,7 @@ This enables server-side orchestration while still making replies show up in the The assistant message needs to be added to the chat response object in memory as a critical prerequisite before triggering the completion. This step is essential because the Open WebUI frontend expects assistant messages to exist in a specific structure. The assistant message must appear in both locations: + - `chat.messages[]` - The main message array - `chat.history.messages[]` - The indexed message history @@ -122,8 +125,12 @@ public void enrichChatWithAssistantMessage(OWUIChatResponse chatResponse, String } ``` +:::note + **Note:** This step can be performed in memory on the response object, or combined with Step 1 by including both user and empty assistant messages in the initial chat creation. +::: + ### Step 3: Update Chat with Assistant Message Send the enriched chat state containing both user and assistant messages to the server: @@ -272,9 +279,11 @@ curl -X POST https:///api/chat/completions \ Assistant responses can be handled in two ways depending on your implementation needs: #### Option A: Stream Processing (Recommended) + If using `stream: true` in the completion request, you can process the streamed response in real-time and wait for the stream to complete. This is the approach used by the OpenWebUI web interface and provides immediate feedback. #### Option B: Polling Approach + For implementations that cannot handle streaming, poll the chat endpoint until the response is ready. Use a retry mechanism with exponential backoff: ```java @@ -300,17 +309,18 @@ public String getAssistantResponseWhenReady(String chatId, ChatCompletedRequest For manual polling, you can use: ```bash + # Poll every few seconds until assistant content is populated while true; do response=$(curl -s -X GET https:///api/v1/chats/ \ -H "Authorization: Bearer ") - + # Check if assistant message has content (response is ready) if echo "$response" | jq '.chat.messages[] | select(.role=="assistant" and .id=="assistant-msg-id") | .content' | grep -v '""' > /dev/null; then echo "Assistant response is ready!" break fi - + echo "Waiting for assistant response..." sleep 2 done @@ -404,6 +414,7 @@ curl -X POST https:///api/v1/chats/ \ Assistant responses may be wrapped in markdown code blocks. Here's how to clean them: ```bash + # Example raw response from assistant raw_response='```json { @@ -419,6 +430,7 @@ echo "$cleaned_response" | jq '.' ``` This cleaning process handles: + - Removal of ````json` prefix - Removal of ```` suffix - Trimming whitespace @@ -797,24 +809,29 @@ This cleaning process handles: #### Required vs Optional Fields **Chat Creation - Required Fields:** + - `title` - Chat title (string) - `models` - Array of model names (string[]) - `messages` - Initial message array **Chat Creation - Optional Fields:** + - `files` - Knowledge files for RAG (defaults to empty array) - `tags` - Chat tags (defaults to empty array) - `params` - Model parameters (defaults to empty object) **Message Structure - User Message:** + - **Required:** `id`, `role`, `content`, `timestamp`, `models` - **Optional:** `parentId` (for threading) **Message Structure - Assistant Message:** + - **Required:** `id`, `role`, `content`, `parentId`, `modelName`, `modelIdx`, `timestamp` - **Optional:** Additional metadata fields **ChatCompletionsRequest - Required Fields:** + - `chat_id` - Target chat ID - `id` - Assistant message ID - `messages` - Array of ChatCompletionMessage @@ -822,6 +839,7 @@ This cleaning process handles: - `session_id` - Session identifier **ChatCompletionsRequest - Optional Fields:** + - `stream` - Enable streaming (defaults to false) - `background_tasks` - Control automatic tasks - `features` - Enable/disable features @@ -832,22 +850,27 @@ This cleaning process handles: #### Field Constraints **Timestamps:** + - Format: Unix timestamp in milliseconds - Example: `1720000000000` (July 4, 2024, 00:00:00 UTC) **UUIDs:** + - All ID fields should use valid UUID format - Example: `550e8400-e29b-41d4-a716-446655440000` **Model Names:** + - Must match available models in your Open WebUI instance - Common examples: `gpt-4o`, `gpt-3.5-turbo`, `claude-3-sonnet` **Session IDs:** + - Can be any unique string identifier - Recommendation: Use UUID format for consistency **Knowledge File Status:** + - Valid values: `"processed"`, `"processing"`, `"error"` - Only use `"processed"` files for completions @@ -878,6 +901,7 @@ Use the Open WebUI backend APIs to: 7. **Fetch the final chat** - Retrieve and parse the completed conversation **Enhanced Capabilities:** + - **RAG Integration** - Include knowledge collections for context-aware responses - **Asynchronous Processing** - Handle long-running AI operations with streaming or polling - **Response Parsing** - Clean and validate JSON responses from the assistant @@ -890,6 +914,7 @@ The key advantage of this approach is that it maintains full compatibility with ## Testing You can test your implementation by following the step-by-step CURL examples provided above. Make sure to replace placeholder values with your actual: + - Host URL - Authentication token - Chat IDs @@ -897,5 +922,7 @@ You can test your implementation by following the step-by-step CURL examples pro - Model names :::tip + Start with a simple user message and gradually add complexity like knowledge integration and advanced features once the basic flow is working. + ::: diff --git a/docs/tutorials/integrations/browser-search-engine.md b/docs/tutorials/integrations/browser-search-engine.md index 2eef18ee60..d65201f502 100644 --- a/docs/tutorials/integrations/browser-search-engine.md +++ b/docs/tutorials/integrations/browser-search-engine.md @@ -4,7 +4,9 @@ title: "🌐 Browser Search Engine" --- :::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. + ::: # Browser Search Engine Integration @@ -83,8 +85,12 @@ If you wish to utilize a specific model for your search, modify the URL format t https:///?models=&q=%s ``` +:::note + **Note:** The model ID will need to be URL-encoded. Special characters like spaces or slashes need to be encoded (e.g., `my model` becomes `my%20model`). +::: + ## Example Usage Once the search engine is set up, you can perform searches directly from the address bar. Simply type your chosen keyword followed by your query: diff --git a/docs/tutorials/integrations/continue-dev.md b/docs/tutorials/integrations/continue-dev.md index 4761f45441..041e335668 100644 --- a/docs/tutorials/integrations/continue-dev.md +++ b/docs/tutorials/integrations/continue-dev.md @@ -4,7 +4,9 @@ title: "⚛️ Continue.dev VS Code Extension with Open WebUI" --- :::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](/docs/contributing.mdx). + ::: # Integrating Continue.dev VS Code Extension with Open WebUI @@ -150,7 +152,7 @@ env: ### APIBase This is a crucial step: you need to direct the continue.dev extension requests to your Open WebUI instance. -Either use an actual domain name if the instance is hosted somewhere (e.g. `https://example.com/api`) or your localhost setup (e.g. `http://localhost:3000/api`). +Either use an actual domain name if the instance is hosted somewhere (e.g., `https://example.com/api`) or your localhost setup (e.g., `http://localhost:3000/api`). You can find more information about the URLs in the [API Endpoints guide](/docs/getting-started/api-endpoints.md). ```yaml diff --git a/docs/tutorials/integrations/custom-ca.md b/docs/tutorials/integrations/custom-ca.md index cde4a242ea..a3a12dbdd4 100644 --- a/docs/tutorials/integrations/custom-ca.md +++ b/docs/tutorials/integrations/custom-ca.md @@ -4,10 +4,12 @@ title: "🛃 Setting up with Custom CA Store" --- :::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. + ::: -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). +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. diff --git a/docs/tutorials/integrations/deepseekr1-dynamic.md b/docs/tutorials/integrations/deepseekr1-dynamic.md index cf52de7e3b..879342d01a 100644 --- a/docs/tutorials/integrations/deepseekr1-dynamic.md +++ b/docs/tutorials/integrations/deepseekr1-dynamic.md @@ -3,36 +3,43 @@ sidebar_position: 1 title: "🐋 Run DeepSeek R1 Dynamic 1.58-bit with Llama.cpp" --- -A huge shoutout to **UnslothAI** for their incredible efforts! Thanks to their hard work, we can now run the **full DeepSeek-R1** 671B parameter model in its dynamic 1.58-bit quantized form (compressed to just 131GB) on **Llama.cpp**! And the best part? You no longer have to despair about needing massive enterprise-class GPUs or servers — it’s possible to run this model on your personal machine (albeit slowly for most consumer hardware). +A huge shoutout to **UnslothAI** for their incredible efforts! Thanks to their hard work, we can now run the **full DeepSeek-R1** 671B parameter model in its dynamic 1.58-bit quantized form (compressed to just 131GB) on **Llama.cpp**! And the best part? You no longer have to despair about needing massive enterprise-class GPUs or servers — it’s possible to run this model on your personal machine (albeit slowly for most consumer hardware). :::note + The only true **DeepSeek-R1** model on Ollama is the **671B version** available here: [https://ollama.com/library/deepseek-r1:671b](https://ollama.com/library/deepseek-r1:671b). Other versions are **distilled** models. + ::: -This guide focuses on running the **full DeepSeek-R1 Dynamic 1.58-bit quantized model** using **Llama.cpp** integrated with **Open WebUI**. For this tutorial, we’ll demonstrate the steps with an **M4 Max + 128GB RAM** machine. You can adapt the settings to your own configuration. +This guide focuses on running the **full DeepSeek-R1 Dynamic 1.58-bit quantized model** using **Llama.cpp** integrated with **Open WebUI**. For this tutorial, we’ll demonstrate the steps with an **M4 Max + 128GB RAM** machine. You can adapt the settings to your own configuration. --- -## Step 1: Install Llama.cpp +## Step 1: Install Llama.cpp -You can either: -- [Download the prebuilt binaries](https://github.com/ggerganov/llama.cpp/releases) -- **Or build it yourself**: Follow the instructions here: [Llama.cpp Build Guide](https://github.com/ggerganov/llama.cpp/blob/master/docs/build.md) +You can either: -## Step 2: Download the Model Provided by UnslothAI +- [Download the prebuilt binaries](https://github.com/ggerganov/llama.cpp/releases) +- **Or build it yourself**: Follow the instructions here: [Llama.cpp Build Guide](https://github.com/ggerganov/llama.cpp/blob/master/docs/build.md) -Head over to [Unsloth’s Hugging Face page](https://huggingface.co/unsloth/DeepSeek-R1-GGUF) and download the appropriate **dynamic quantized version** of DeepSeek-R1. For this tutorial, we’ll use the **1.58-bit (131GB)** version, which is highly optimized yet remains surprisingly functional. +## Step 2: Download the Model Provided by UnslothAI +Head over to [Unsloth’s Hugging Face page](https://huggingface.co/unsloth/DeepSeek-R1-GGUF) and download the appropriate **dynamic quantized version** of DeepSeek-R1. For this tutorial, we’ll use the **1.58-bit (131GB)** version, which is highly optimized yet remains surprisingly functional. :::tip -Know your "working directory" — where your Python script or terminal session is running. The model files will download to a subfolder of that directory by default, so be sure you know its path! For example, if you're running the command below in `/Users/yourname/Documents/projects`, your downloaded model will be saved under `/Users/yourname/Documents/projects/DeepSeek-R1-GGUF`. + +Know your "working directory" — where your Python script or terminal session is running. The model files will download to a subfolder of that directory by default, so be sure you know its path! For example, if you're running the command below in `/Users/yourname/Documents/projects`, your downloaded model will be saved under `/Users/yourname/Documents/projects/DeepSeek-R1-GGUF`. + ::: -To understand more about UnslothAI’s development process and why these dynamic quantized versions are so efficient, check out their blog post: [UnslothAI DeepSeek R1 Dynamic Quantization](https://unsloth.ai/blog/deepseekr1-dynamic). +To understand more about UnslothAI’s development process and why these dynamic quantized versions are so efficient, check out their blog post: [UnslothAI DeepSeek R1 Dynamic Quantization](https://unsloth.ai/blog/deepseekr1-dynamic). + +Here’s how to download the model programmatically: -Here’s how to download the model programmatically: ```python + # Install Hugging Face dependencies before running this: + # pip install huggingface_hub hf_transfer from huggingface_hub import snapshot_download @@ -44,7 +51,8 @@ snapshot_download( ) ``` -Once the download completes, you’ll find the model files in a directory structure like this: +Once the download completes, you’ll find the model files in a directory structure like this: + ``` DeepSeek-R1-GGUF/ ├── DeepSeek-R1-UD-IQ1_S/ @@ -54,34 +62,38 @@ DeepSeek-R1-GGUF/ ``` :::info -🛠️ Update paths in the later steps to **match your specific directory structure**. For example, if your script was in `/Users/tim/Downloads`, the full path to the GGUF file would be: + +🛠️ Update paths in the later steps to **match your specific directory structure**. For example, if your script was in `/Users/tim/Downloads`, the full path to the GGUF file would be: `/Users/tim/Downloads/DeepSeek-R1-GGUF/DeepSeek-R1-UD-IQ1_S/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf`. + ::: -## Step 3: Make Sure Open WebUI is Installed and Running +## Step 3: Make Sure Open WebUI is Installed and Running -If you don’t already have **Open WebUI** installed, no worries! It’s a simple setup. Just follow the [Open WebUI documentation here](https://docs.openwebui.com/). Once installed, start the application — we’ll connect it in a later step to interact with the DeepSeek-R1 model. +If you don’t already have **Open WebUI** installed, no worries! It’s a simple setup. Just follow the [Open WebUI documentation here](https://docs.openwebui.com/). Once installed, start the application — we’ll connect it in a later step to interact with the DeepSeek-R1 model. +## Step 4: Serve the Model Using Llama.cpp -## Step 4: Serve the Model Using Llama.cpp +Now that the model is downloaded, the next step is to run it using **Llama.cpp’s server mode**. Before you begin: -Now that the model is downloaded, the next step is to run it using **Llama.cpp’s server mode**. Before you begin: +1. **Locate the `llama-server` binary.** + If you built from source (as outlined in Step 1), the `llama-server` executable will be located in `llama.cpp/build/bin`. Navigate to this directory by using the `cd` command: -1. **Locate the `llama-server` binary.** - If you built from source (as outlined in Step 1), the `llama-server` executable will be located in `llama.cpp/build/bin`. Navigate to this directory by using the `cd` command: ```bash cd [path-to-llama-cpp]/llama.cpp/build/bin ``` - Replace `[path-to-llama-cpp]` with the location where you cloned or built Llama.cpp. For example: + Replace `[path-to-llama-cpp]` with the location where you cloned or built Llama.cpp. For example: + ```bash cd ~/Documents/workspace/llama.cpp/build/bin ``` -2. **Point to your model folder.** - Use the full path to the downloaded GGUF files created in Step 2. When serving the model, specify the first part of the split GGUF files (e.g., `DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf`). +2. **Point to your model folder.** + Use the full path to the downloaded GGUF files created in Step 2. When serving the model, specify the first part of the split GGUF files (e.g., `DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf`). + +Here’s the command to start the server: -Here’s the command to start the server: ```bash ./llama-server \ --model /[your-directory]/DeepSeek-R1-GGUF/DeepSeek-R1-UD-IQ1_S/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf \ @@ -90,17 +102,19 @@ Here’s the command to start the server: --n-gpu-layers 40 ``` - :::tip -🔑 **Parameters to Customize Based on Your Machine:** -- **`--model`:** Replace `/[your-directory]/` with the path where the GGUF files were downloaded in Step 2. -- **`--port`:** The server default is `8080`, but feel free to change it based on your port availability. -- **`--ctx-size`:** Determines context length (number of tokens). You can increase it if your hardware allows, but be cautious of rising RAM/VRAM usage. +🔑 **Parameters to Customize Based on Your Machine:** + +- **`--model`:** Replace `/[your-directory]/` with the path where the GGUF files were downloaded in Step 2. +- **`--port`:** The server default is `8080`, but feel free to change it based on your port availability. +- **`--ctx-size`:** Determines context length (number of tokens). You can increase it if your hardware allows, but be cautious of rising RAM/VRAM usage. - **`--n-gpu-layers`:** Set the number of layers you want to offload to your GPU for faster inference. The exact number depends on your GPU’s memory capacity — reference Unsloth’s table for specific recommendations. + ::: -For example, if your model was downloaded to `/Users/tim/Documents/workspace`, your command would look like this: +For example, if your model was downloaded to `/Users/tim/Documents/workspace`, your command would look like this: + ```bash ./llama-server \ --model /Users/tim/Documents/workspace/DeepSeek-R1-GGUF/DeepSeek-R1-UD-IQ1_S/DeepSeek-R1-UD-IQ1_S-00001-of-00003.gguf \ @@ -109,61 +123,66 @@ For example, if your model was downloaded to `/Users/tim/Documents/workspace`, y --n-gpu-layers 40 ``` -Once the server starts, it will host a **local OpenAI-compatible API** endpoint at: +Once the server starts, it will host a **local OpenAI-compatible API** endpoint at: + ``` http://127.0.0.1:10000 ``` :::info -🖥️ **Llama.cpp Server Running** -![Server Screenshot](/images/tutorials/deepseek/serve.png) +🖥️ **Llama.cpp Server Running** + +![Server Screenshot](/images/tutorials/deepseek/serve.png) After running the command, you should see a message confirming the server is active and listening on port 10000. + ::: Be sure to **keep this terminal session running**, as it serves the model for all subsequent steps. -## Step 5: Connect Llama.cpp to Open WebUI +## Step 5: Connect Llama.cpp to Open WebUI -1. Go to **Admin Settings** in Open WebUI. -2. Navigate to **Connections > OpenAI Connections.** -3. Add the following details for the new connection: +1. Go to **Admin Settings** in Open WebUI. +2. Navigate to **Connections > OpenAI Connections.** +3. Add the following details for the new connection: - URL: `http://127.0.0.1:10000/v1` (or `http://host.docker.internal:10000/v1` when running Open WebUI in docker) - API Key: `none` :::info -🖥️ **Adding Connection in Open WebUI** -![Connection Screenshot](/images/tutorials/deepseek/connection.png) +🖥️ **Adding Connection in Open WebUI** + +![Connection Screenshot](/images/tutorials/deepseek/connection.png) After running the command, you should see a message confirming the server is active and listening on port 10000. + ::: -Once the connection is saved, you can start querying **DeepSeek-R1** directly from Open WebUI! 🎉 +Once the connection is saved, you can start querying **DeepSeek-R1** directly from Open WebUI! 🎉 --- -## Example: Generating Responses +## Example: Generating Responses -You can now use Open WebUI’s chat interface to interact with the **DeepSeek-R1 Dynamic 1.58-bit model**. +You can now use Open WebUI’s chat interface to interact with the **DeepSeek-R1 Dynamic 1.58-bit model**. -![Response Screenshot](/images/tutorials/deepseek/response.png) +![Response Screenshot](/images/tutorials/deepseek/response.png) --- -## Notes and Considerations +## Notes and Considerations -- **Performance:** - Running a massive 131GB model like DeepSeek-R1 on personal hardware will be **slow**. Even with our M4 Max (128GB RAM), inference speeds were modest. But the fact that it works at all is a testament to UnslothAI’s optimizations. +- **Performance:** + Running a massive 131GB model like DeepSeek-R1 on personal hardware will be **slow**. Even with our M4 Max (128GB RAM), inference speeds were modest. But the fact that it works at all is a testament to UnslothAI’s optimizations. -- **VRAM/Memory Requirements:** - Ensure sufficient VRAM and system RAM for optimal performance. With low-end GPUs or CPU-only setups, expect slower speeds (but it’s still doable!). +- **VRAM/Memory Requirements:** + Ensure sufficient VRAM and system RAM for optimal performance. With low-end GPUs or CPU-only setups, expect slower speeds (but it’s still doable!). --- -Thanks to **UnslothAI** and **Llama.cpp**, running one of the largest open-source reasoning models, **DeepSeek-R1** (1.58-bit version), is finally accessible to individuals. While it’s challenging to run such models on consumer hardware, the ability to do so without massive computational infrastructure is a significant technological milestone. +Thanks to **UnslothAI** and **Llama.cpp**, running one of the largest open-source reasoning models, **DeepSeek-R1** (1.58-bit version), is finally accessible to individuals. While it’s challenging to run such models on consumer hardware, the ability to do so without massive computational infrastructure is a significant technological milestone. -⭐ Big thanks to the community for pushing the boundaries of open AI research. +⭐ Big thanks to the community for pushing the boundaries of open AI research. -Happy experimenting! 🚀 +Happy experimenting! 🚀 diff --git a/docs/tutorials/integrations/firefox-sidebar.md b/docs/tutorials/integrations/firefox-sidebar.md index eaa136bd1d..b880dbd966 100644 --- a/docs/tutorials/integrations/firefox-sidebar.md +++ b/docs/tutorials/integrations/firefox-sidebar.md @@ -4,7 +4,9 @@ title: "🦊 Firefox AI Chatbot Sidebar" --- :::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. + ::: ## 🦊 Firefox AI Chatbot Sidebar @@ -15,15 +17,15 @@ This tutorial is a community contribution and is not supported by the Open WebUI Before integrating Open WebUI as a AI chatbot browser assistant in Mozilla Firefox, ensure you have: -* Open WebUI instance URL (local or domain) -* Firefox browser installed +- Open WebUI instance URL (local or domain) +- Firefox browser installed ## Enabling AI Chatbot in Firefox 1. Click on the hamburger button (three horizontal lines button at the top right corner, just below the `X` button) 2. Open up Firefox settings -2. Click on the `Firefox Labs` section -3. Toggle on `AI Chatbot` +3. Click on the `Firefox Labs` section +4. Toggle on `AI Chatbot` Alternatively, you can enable AI Chatbot through the `about:config` page (described in the next section). @@ -54,32 +56,32 @@ The following URL parameters can be used to customize your Open WebUI instance: ### Models and Model Selection -* `models`: Specify multiple models (comma-separated list) for the chat session (e.g., `/?models=model1,model2`) -* `model`: Specify a single model for the chat session (e.g., `/?model=model1`) +- `models`: Specify multiple models (comma-separated list) for the chat session (e.g., `/?models=model1,model2`) +- `model`: Specify a single model for the chat session (e.g., `/?model=model1`) ### YouTube Transcription -* `youtube`: Provide a YouTube video ID to transcribe the video in the chat (e.g., `/?youtube=VIDEO_ID`) +- `youtube`: Provide a YouTube video ID to transcribe the video in the chat (e.g., `/?youtube=VIDEO_ID`) ### Web Search -* `web-search`: Enable web search functionality by setting this parameter to `true` (e.g., `/?web-search=true`) +- `web-search`: Enable web search functionality by setting this parameter to `true` (e.g., `/?web-search=true`) ### Tool Selection -* `tools` or `tool-ids`: Specify a comma-separated list of tool IDs to activate in the chat (e.g., `/?tools=tool1,tool2` or `/?tool-ids=tool1,tool2`) +- `tools` or `tool-ids`: Specify a comma-separated list of tool IDs to activate in the chat (e.g., `/?tools=tool1,tool2` or `/?tool-ids=tool1,tool2`) ### Call Overlay -* `call`: Enable a video or call overlay in the chat interface by setting this parameter to `true` (e.g., `/?call=true`) +- `call`: Enable a video or call overlay in the chat interface by setting this parameter to `true` (e.g., `/?call=true`) ### Initial Query Prompt -* `q`: Set an initial query or prompt for the chat (e.g., `/?q=Hello%20there`) +- `q`: Set an initial query or prompt for the chat (e.g., `/?q=Hello%20there`) ### Temporary Chat Sessions -* `temporary-chat`: Mark the chat as a temporary session by setting this parameter to `true` (e.g., `/?temporary-chat=true`) +- `temporary-chat`: Mark the chat as a temporary session by setting this parameter to `true` (e.g., `/?temporary-chat=true`) See https://docs.openwebui.com/features/chat-features/url-params for more info on URL parameters and how to use them. @@ -87,26 +89,26 @@ See https://docs.openwebui.com/features/chat-features/url-params for more info o The following `about:config` settings can be adjusted for further customization: -* `browser.ml.chat.shortcuts`: Enable custom shortcuts for the AI chatbot sidebar -* `browser.ml.chat.shortcuts.custom`: Enable custom shortcut keys for the AI chatbot sidebar -* `browser.ml.chat.shortcuts.longPress`: Set the long press delay for shortcut keys -* `browser.ml.chat.sidebar`: Enable the AI chatbot sidebar -* `browser.ml.checkForMemory`: Check for available memory before loading models -* `browser.ml.defaultModelMemoryUsage`: Set the default memory usage for models -* `browser.ml.enable`: Enable the machine learning features in Firefox -* `browser.ml.logLevel`: Set the log level for machine learning features -* `browser.ml.maximumMemoryPressure`: Set the maximum memory pressure threshold -* `browser.ml.minimumPhysicalMemory`: Set the minimum physical memory required -* `browser.ml.modelCacheMaxSize`: Set the maximum size of the model cache -* `browser.ml.modelCacheTimeout`: Set the timeout for model cache -* `browser.ml.modelHubRootUrl`: Set the root URL for the model hub -* `browser.ml.modelHubUrlTemplate`: Set the URL template for the model hub -* `browser.ml.queueWaitInterval`: Set the interval for queue wait -* `browser.ml.queueWaitTimeout`: Set the timeout for queue wait +- `browser.ml.chat.shortcuts`: Enable custom shortcuts for the AI chatbot sidebar +- `browser.ml.chat.shortcuts.custom`: Enable custom shortcut keys for the AI chatbot sidebar +- `browser.ml.chat.shortcuts.longPress`: Set the long press delay for shortcut keys +- `browser.ml.chat.sidebar`: Enable the AI chatbot sidebar +- `browser.ml.checkForMemory`: Check for available memory before loading models +- `browser.ml.defaultModelMemoryUsage`: Set the default memory usage for models +- `browser.ml.enable`: Enable the machine learning features in Firefox +- `browser.ml.logLevel`: Set the log level for machine learning features +- `browser.ml.maximumMemoryPressure`: Set the maximum memory pressure threshold +- `browser.ml.minimumPhysicalMemory`: Set the minimum physical memory required +- `browser.ml.modelCacheMaxSize`: Set the maximum size of the model cache +- `browser.ml.modelCacheTimeout`: Set the timeout for model cache +- `browser.ml.modelHubRootUrl`: Set the root URL for the model hub +- `browser.ml.modelHubUrlTemplate`: Set the URL template for the model hub +- `browser.ml.queueWaitInterval`: Set the interval for queue wait +- `browser.ml.queueWaitTimeout`: Set the timeout for queue wait ## Accessing the AI Chatbot Sidebar To access the AI chatbot sidebar, use one of the following methods: -* Press `CTRL+B` to open the bookmarks sidebar and switch to AI Chatbot -* Press `CTRL+Alt+X` to open the AI chatbot sidebar directly \ No newline at end of file +- Press `CTRL+B` to open the bookmarks sidebar and switch to AI Chatbot +- Press `CTRL+Alt+X` to open the AI chatbot sidebar directly diff --git a/docs/tutorials/integrations/helicone.md b/docs/tutorials/integrations/helicone.md index c55d539dc1..3d7028048a 100644 --- a/docs/tutorials/integrations/helicone.md +++ b/docs/tutorials/integrations/helicone.md @@ -4,7 +4,9 @@ sidebar_position: 19 --- :::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. + ::: # Helicone Integration with Open WebUI @@ -21,7 +23,6 @@ By enabling Helicone, you can log LLM requests, evaluate and experiment with pro - **Debug capabilities** to troubleshoot issues with model responses - **Cost tracking** for your LLM usage across providers - ## How to integrate Helicone with OpenWebUI