khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-01-03 10:20:09 +07:00
Code Issues Packages Projects Releases Wiki Activity

env vars

Browse Source
This commit is contained in:
DrMelone
2026-01-01 14:03:45 +01:00
parent b1579f203d
commit 5f84f77720
5 changed files with 119 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
docs/features/image-generation-and-editing/usage.md
View File

@@ -7,21 +7,13 @@ Before you can use image generation, you must ensure that the **Image Generation
## Using Image Generation
### Method 1
1. Toggle the `Image Generation` switch to on.
2. Enter your image generation prompt.
3. Click `Send`.
![Image Generation Tutorial](/images/tutorial_image_generation_2.png)
### Method 2
![Image Generation Tutorial](/images/tutorial_image_generation.png)
1. First, use a text generation model to write a prompt for image generation.
2. After the response has finished, you can click the Picture icon to generate an image.
3. After the image has finished generating, it will be returned automatically in chat.
:::tip

4
docs/features/web-search/jina.md
View File

@@ -57,7 +57,8 @@ To enable the Jina web search integration, follow these steps in the Open WebUI
2. **Navigate to Web Search Settings:** Go to the **Admin Panel**, then click on **Settings** > **Web Search**.
3. **Select Jina as the Search Engine:** In the "Web Search Engine" dropdown menu, select **Jina**.
4. **Enter Your API Key:** Paste your Jina API key into the **Jina API Key** input field.
5. **Save Changes:** Scroll down and click the **Save** button to apply the changes.
5. **(Optional) Enter Jina API Base URL:** If you need to use a specific endpoint (e.g., for EU data processing), enter it in the **Jina API Base URL** field. Default is `https://s.jina.ai/`.
6. **Save Changes:** Scroll down and click the **Save** button to apply the changes.
### 3. Environment Variable Configuration
@@ -66,6 +67,7 @@ For Docker-based deployments, you can configure the Jina integration using an en
Set the following environment variable for your Open WebUI instance:
- `JINA_API_KEY`: Your Jina API key.
- `JINA_API_BASE_URL`: (Optional) Custom Jina API endpoint.
**Example Docker `run` command:**

47
docs/getting-started/env-configuration.mdx
View File

@@ -165,6 +165,13 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b
- Description: Enables or disables the folders feature, allowing users to organize their chats into folders in the sidebar.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `FOLDER_MAX_FILE_COUNT`
- Type: `int`
- Default: `100`
- Description: Sets the maximum number of files processing allowed per folder.
- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > General > Folder Max File Count**.
#### `ENABLE_NOTES`
- Type: `bool`
@@ -504,7 +511,7 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model-
- Type: `bool`
- Default: `True`
- Description: Controls SSL/TLS verification for AIOHTTP client sessions when connecting to external APIs.
- Description: Controls SSL/TLS verification for AIOHTTP client sessions when connecting to external APIs (e.g., Ollama Embeddings).
#### `AIOHTTP_CLIENT_TIMEOUT_TOOL_SERVER_DATA`
@@ -518,6 +525,12 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model-
- Default: `True`
- Description: Controls SSL/TLS verification specifically for tool server connections via AIOHTTP client.
#### `REQUESTS_VERIFY`
- Type: `bool`
- Default: `True`
- Description: Controls SSL/TLS verification for synchronous `requests` (e.g., Tika, External Reranker). Set to `False` to bypass certificate verification for self-signed certificates.
### Directories
#### `DATA_DIR`
@@ -551,6 +564,18 @@ See the [Model List Loading Issues](/troubleshooting/connection-error#️-model-
- Default: `INFO`
- Description: Sets the global logging level for all Open WebUI components. Valid values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`.
#### `ENABLE_AUDIT_STDOUT`
- Type: `bool`
- Default: `False`
- Description: Controls whether audit logs are output to stdout (console). Useful for containerized environments where logs are collected from stdout.
#### `ENABLE_AUDIT_LOGS_FILE`
- Type: `bool`
- Default: `True`
- Description: Controls whether audit logs are written to a file. When enabled, logs are written to the location specified by `AUDIT_LOGS_FILE_PATH`.
#### `AUDIT_LOGS_FILE_PATH`
- Type: `str`
@@ -2741,6 +2766,12 @@ If you are embedding externally via API, ensure your rate limits are high enough
- Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `SENTENCE_TRANSFORMERS_CROSS_ENCODER_SIGMOID_ACTIVATION_FUNCTION`
- Type: `bool`
- Default: `True`
- Description: When enabled (default), applies sigmoid normalization to local CrossEncoder reranking scores to ensure they fall within the 0-1 range. This allows the relevance threshold setting to work correctly with models like MS MARCO that output raw logits.
#### `RAG_EXTERNAL_RERANKER_TIMEOUT`
- Type: `str`
@@ -3184,6 +3215,13 @@ Brave's free tier enforces a rate limit of 1 request per second. Open WebUI auto
- Description: Sets the API key for Jina.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `JINA_API_BASE_URL`
- Type: `str`
- Default: `https://s.jina.ai/`
- Description: Sets the Base URL for Jina Search API. Useful for specifying custom or regional endpoints (e.g., `https://eu-s-beta.jina.ai/`).
- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > Web Search > Jina API Base URL**.
#### `BING_SEARCH_V7_ENDPOINT`
- Type: `str`
@@ -3416,6 +3454,13 @@ Using a remote Playwright browser via `PLAYWRIGHT_WS_URL` can be beneficial for:
- Description: Sets the API key for Firecrawl API.
- Persistence: This environment variable is a `PersistentConfig` variable.
#### `FIRECRAWL_TIMEOUT`
- Type: `int`
- Default: `None`
- Description: Specifies the timeout in milliseconds for Firecrawl requests. If not set, the default Firecrawl timeout is used.
- Persistence: This environment variable is a `PersistentConfig` variable. It can be configured in the **Admin Panel > Settings > Web Search > Firecrawl Timeout**.
#### `PLAYWRIGHT_TIMEOUT`
- Type: `int`

54
docs/troubleshooting/connection-error.mdx
View File

@@ -231,6 +231,35 @@ Encountered an SSL error? It could be an issue with the Hugging Face server. Her
docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
```
## 🔐 SSL Certificate Issues with Internal Tools
If you are using external tools like Tika, Ollama (for embeddings), or an external reranker with self-signed certificates, you might encounter SSL verification errors.
### Common Symptoms
- Logs show `[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate`
- Tika document ingestion fails
- Embedding generation fails with SSL errors
- Reranking fails with SSL errors
### Solution
You can disable SSL verification for these internal tool connections using the following environment variables:
1. **For synchronous requests (Tika, External Reranker):**
```bash
REQUESTS_VERIFY=false
```
2. **For asynchronous requests (Ollama Embeddings):**
```bash
AIOHTTP_CLIENT_SESSION_SSL=false
```
:::warning
Disabling SSL verification reduces security. Only do this if you trust the network and the services you are connecting to (e.g., functioning within a secure internal network).
:::
## 🍏 Podman on MacOS
Running on MacOS with Podman? Here’s how to ensure connectivity:
@@ -255,17 +284,32 @@ If you are having trouble connecting to MCP tools (e.g. "Failed to connect to MC
See the [MCP Feature Documentation](/features/mcp#troubleshooting) for detailed troubleshooting steps.
## 🔐 SSL/TLS Errors with Web Search (Proxy Issues)
## 🔐 SSL/TLS Errors with Web Search
If you are encountering SSL errors while using the Web Search feature, they usually fall into two categories: Proxy configuration issues or Certificate verification issues.
### Certificate Verification Issues
If you are seeing SSL verification errors when Open WebUI tries to fetch content from websites (Web Loader):
- **Symptom**: `[SSL: CERTIFICATE_VERIFY_FAILED]` when loading search results.
- **Solution**: You can disable SSL verification for the Web Loader (scraper) specifically.
```bash
ENABLE_WEB_LOADER_SSL_VERIFICATION=false
```
> **Note**: This setting applies to the *fetching* of web pages. If you are having SSL issues with the Search Engine itself (e.g., local SearXNG) or subsequent steps (Embedding/Reranking), see the sections below.
### Proxy Configuration Issues
If you're seeing SSL errors like `UNEXPECTED_EOF_WHILE_READING` or `Max retries exceeded` when using web search providers (Bocha, Tavily, etc.):
### Common Symptoms
#### Common Symptoms
- `SSLError(SSLEOFError(8, '[SSL: UNEXPECTED_EOF_WHILE_READING]'))`
- `Max retries exceeded with url: /v1/web-search`
- Web search works in standalone Python scripts but fails in Open WebUI
### Cause: HTTP Proxy Configured for HTTPS Traffic
#### Cause: HTTP Proxy Configured for HTTPS Traffic
This typically happens when you have an **HTTP proxy** configured for **HTTPS traffic**. The HTTP proxy cannot properly handle TLS connections, causing SSL handshake failures.
@@ -275,7 +319,7 @@ Check your environment for these variables:
If your `https_proxy` points to `http://...` (HTTP) instead of `https://...` (HTTPS), SSL handshakes will fail because the proxy terminates the connection unexpectedly.
### Solutions
#### Solutions
1. **Fix proxy configuration**: Use an HTTPS-capable proxy for HTTPS traffic, or configure your HTTP proxy to properly support CONNECT tunneling for SSL
2. **Bypass proxy for specific hosts**: Set `NO_PROXY` environment variable:
@@ -284,6 +328,6 @@ If your `https_proxy` points to `http://...` (HTTP) instead of `https://...` (HT
```
3. **Disable proxy if not needed**: Unset the proxy environment variables entirely
### Why Standalone Scripts Work
#### Why Standalone Scripts Work
When you run a Python script directly, it may not inherit the same proxy environment variables that your Open WebUI service is using. The service typically inherits environment variables from systemd, Docker, or your shell profile, which may have different proxy settings.

22
docs/troubleshooting/rag.mdx
View File

@@ -133,9 +133,28 @@ If you're not sure whether the issue is with retrieval, token limits, or embeddi
- GPT-4o handles larger inputs (128k tokens!)
- Provides a great benchmark to evaluate your system's RAG reliability
---
### 6. Upload Limits and Restrictions 🛑
Open WebUI implements various limits to ensure system stability and prevent abuse. It is important to understand how these limits apply to different upload methods:
* **Chat Uploads:** Subject to global file size and count limits.
* **Max File Size:** Controlled by `RAG_FILE_MAX_SIZE` (default: Unlimited). Configurable in **Admin Panel > Settings > Documents > General > Max Upload Size**.
* **Max File Count:** Controlled by `RAG_FILE_MAX_COUNT` (default: Unlimited). Configurable in **Admin Panel > Settings > Documents > General > Max Upload Count**.
* **Allowed File Extensions:** Controlled by `RAG_ALLOWED_FILE_EXTENSIONS` (default: All). Configurable in **Admin Panel > Settings > Documents > General > Allowed File Extensions**.
* **Folder Uploads:** Subject to the `FOLDER_MAX_FILE_COUNT` [environment variable](/getting-started/env-configuration/#folder_max_file_count) (defaults to 100). This limit applies to the number of files directly associated with a folder.
* **Knowledge Base Uploads:**
* **File Limit:** Subject to the same `RAG_FILE_MAX_SIZE` limit as chats, but **not** subject to the `RAG_FILE_MAX_COUNT` limit, allowing for unlimited file uploads.
* **RAG Enforcement:** All files uploaded to a Knowledge Base are automatically indexed. However, similar to chat uploads, Knowledge Bases can also be used in **Full Context Mode** (accessible in chat settings), which feeds the full document content to the model instead of using vector search retrieval.
:::info
By separating these limits, administrators can better manage resource usage across different features. For example, you might want to allow larger uploads in a curated Knowledge Base while restricting the number of files in ad-hoc Folder uploads.
:::
---
## Summary Checklist ✅
| Problem | Fix |
|--------|------|
@@ -143,6 +162,7 @@ If you're not sure whether the issue is with retrieval, token limits, or embeddi
| 🧹 Only part of content used | Enable Full Context Mode or Bypass Embedding |
| ⏱ Limited by 2048 token cap | Increase model context length (Admin Panel > Models > Settings > Advanced Parameters for Ollama) or use large-context LLM |
| 📉 Inaccurate retrieval | Switch to a better embedding model, then reindex |
| ❌ Upload limits bypass | Use Folder uploads (with `FOLDER_MAX_FILE_COUNT`) but note that Knowledge Base limits are separate |
| Still confused? | Test with GPT-4o and compare outputs |
---