Merge pull request #1128 from open-webui/dev

docs/features/ai-knowledge/models.md

@@ -147,13 +147,33 @@ These tools are specifically designed to help administrators quickly manage exte
 
 Administrators can set **global default metadata and parameters** that apply as a baseline to all models. This eliminates the need to manually configure capabilities and inference settings for every model individually.
 
-- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Sets baseline capabilities (vision, web search, code interpreter, etc.) and other model metadata for all models. For capabilities, defaults and per-model values are merged — per-model overrides always win on conflicts. For other metadata fields, the global default is only applied when a model has no value set.
-- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Sets baseline inference parameters (temperature, top_p, max_tokens, seed, etc.) for all models. Per-model parameter overrides always take precedence.
+- **Default Model Metadata** (`DEFAULT_MODEL_METADATA`): Sets baseline capabilities (vision, web search, file context, code interpreter, builtin tools, etc.) and other model metadata for all models. For capabilities, defaults and per-model values are merged — per-model overrides always win on conflicts. For other metadata fields, the global default is only applied when a model has no value set.
+- **Default Model Params** (`DEFAULT_MODEL_PARAMS`): Sets baseline inference parameters (temperature, top_p, max_tokens, seed, function_calling, etc.) for all models. Per-model parameter overrides always take precedence — but only when a per-model value is explicitly set.
 
-These settings are accessible via **Admin Settings → Models** and are persisted via `PersistentConfig`. See [`DEFAULT_MODEL_METADATA`](/reference/env-configuration#default_model_metadata) and [`DEFAULT_MODEL_PARAMS`](/reference/env-configuration#default_model_params) for details.
+These settings are accessible via **Admin Settings → Models → ⚙️ (gear icon)** and are persisted via `PersistentConfig`. See [`DEFAULT_MODEL_METADATA`](/reference/env-configuration#default_model_metadata) and [`DEFAULT_MODEL_PARAMS`](/reference/env-configuration#default_model_params) for details.
+
+#### Merge Behavior
+
+Understanding how defaults combine with per-model settings is important:
+
+| Setting Type | Merge Strategy | Example |
+|---|---|---|
+| **Capabilities** (metadata) | Deep merge: `{...global, ...per_model}` | Global sets `file_context: false`, model sets `vision: true` → model gets both |
+| **Other metadata** (description, tags, etc.) | Fill-only: global applied when model value is `None` | Global sets `description: "Default"`, model has no description → model gets "Default" |
+| **Parameters** | Simple merge: `{...global, ...per_model}` | Global sets `temperature: 0.7`, model sets `temperature: 0.3` → model gets `0.3` |
+
+The key subtlety: **if a model doesn't explicitly set a parameter, the global default is the only value**. This is especially important for `function_calling` — see the warning below.
+
+:::warning Knowledge Base + Function Calling Interaction
+Setting `function_calling: native` in Global Model Params changes how **all** models handle attached Knowledge Bases. In native mode, model-attached KBs are **not** auto-injected via RAG — instead, the model must autonomously call builtin tools to retrieve knowledge. If a model doesn't explicitly override `function_calling` in its own Advanced Params, it inherits the global value silently.
+
+Additionally, if `file_context` is disabled in Global Model Capabilities, the RAG retrieval handler is skipped for all models that don't explicitly enable it — meaning attached files and KBs produce no results.
+
+If your models' attached Knowledge Bases are not working, check global defaults first. See [Knowledge Base Attached to Model Not Working](/troubleshooting/rag#13-knowledge-base-attached-to-model-not-working) for detailed troubleshooting steps.
+:::
 
 :::tip
-Global defaults are ideal for enforcing organizational policies — for example, disabling code interpreter by default across all models, or setting a consistent temperature for all models.
+Global defaults are ideal for enforcing organizational policies — for example, disabling code interpreter by default across all models, or setting a consistent temperature for all models. However, be cautious with `function_calling` and capability toggles, as they can have unexpected effects on Knowledge Base behavior.
 :::
 
 ## Model Switching in Chat

docs/features/extensibility/plugin/development/events.mdx

@@ -147,6 +147,38 @@ await __event_emitter__(
 )
 ```
 
+#### The `done` Field
+
+The `done` field controls the **shimmer animation** on the status text in the UI:
+
+| `done` value | Visual effect |
+|---|---|
+| `false` (or omitted) | Status text has a **shimmer/loading animation** — indicates ongoing processing |
+| `true` | Status text appears **static** — indicates the step is complete |
+
+The backend does not inspect `done` at all — it simply saves the value and forwards it to the frontend. The shimmer effect is purely a frontend visual cue.
+
+:::warning Always Emit a Final `done: True`
+If you emit status events, always send at least one with `done: True` at the end of your status sequence. Without it, the last status item keeps its shimmer animation indefinitely, making it look like processing never finished — even after the response is complete.
+
+```python
+# ✅ Correct pattern
+await __event_emitter__({"type": "status", "data": {"description": "Fetching data...", "done": False}})
+# ... do work ...
+await __event_emitter__({"type": "status", "data": {"description": "Complete!", "done": True}})
+
+# ⚠️ Broken pattern — shimmer never stops
+await __event_emitter__({"type": "status", "data": {"description": "Fetching data...", "done": False}})
+# ... do work, return result, but never sent done: True
+```
+:::
+
+#### The `hidden` Field
+
+When `hidden` is `true`, the status is saved to `statusHistory` but **not shown** in the current status display. This is useful for internal status tracking that shouldn't be visible to the user.
+
+Additionally, when `message.content` is empty and the last status has `hidden: true` (or no status exists at all), the frontend shows a skeleton loader instead of the status bar — so hidden statuses don't replace the loading indicator.
+
 ---
 
 ### `chat:message:delta` or `message`
@@ -312,6 +344,10 @@ await __event_emitter__(
 **What this does exactly:**
 This event forces the Open WebUI frontend to update the "favorite" state of a message in its local cache. Without this emitter, if an **Action Function** modifies the `message.favorite` field in the database directly, the frontend (which maintains its own state) might overwrite your change during its next auto-save cycle. This emitter ensures the UI and database stay perfectly in sync.
 
+:::note Designed for Actions
+While this event can technically be emitted from any plugin type (tools, pipes, filters), it is **designed for and meaningful in Actions**. Actions operate on existing messages and can modify the database directly. From a pipe or tool, emitting this event would update the frontend state temporarily, but unless the plugin also wrote to the database, the change would be lost on the next chat auto-save.
+:::
+
 **Where it appears:**
 *   **Message Toolbar**: When set to `True`, the "Heart" icon beneath the message will fill in, indicating it is favorited.
 *   **Chat Overview**: Favorited messages (pins) are highlighted in the conversation overview, making it easier for users to locate key information later.
@@ -543,6 +579,12 @@ Because `execute` runs unsandboxed JavaScript in the user's browser session, it
 - `await __event_call__` is for when you need a response from the user (input, confirmation) or a return value from client-side code (execute).
 - The `execute` event is unique: it works with **both** helpers. Use `__event_call__` when you need the JS return value, or `__event_emitter__` for fire-and-forget execution (e.g., triggering downloads).
 
+:::warning Pipes: Return Value vs Events
+For Pipes, be careful about mixing content delivery methods. If your `pipe()` method **returns a string**, that string becomes the final message content. If it **yields** (generator), the yielded chunks are streamed. If you also emit `chat:message:delta` events during execution, both the return/yield content and the event-based content are processed and can conflict.
+
+**Recommendation**: Either use return/yield for content delivery, **or** use `chat:message:delta`/`chat:message` events, but avoid using both simultaneously.
+:::
+
 ---
 
 ## 💡 Tips & Advanced Notes

docs/troubleshooting/rag.mdx

@@ -436,19 +436,30 @@ If you want to prevent a model from accessing **any** knowledge base in native m
 
 ✅ **Solutions (check in order):**
 
-1. **Ensure Built-in Tools are enabled for the model**:
+1. **Check Global Model Settings first**:
+   - Go to **Admin Panel > Settings > Models > ⚙️ (gear icon)**
+   - Expand **Model Parameters** and check if **Function Calling** is set to `native`
+   - If it is, this **overrides all models** that don't explicitly set their own `function_calling` parameter — even if you never intended for a specific model to use native mode
+   - Either change the global setting to `default`, or explicitly set `function_calling` in the per-model **Advanced Params** to override the global value
+   - Also check the **Model Capabilities** section — if **File Context** is disabled globally, RAG won't process files for any model that doesn't explicitly enable it
+
+:::warning Global Settings Override
+The most common cause of this issue is a global `Function Calling: native` setting in **Admin Panel > Settings > Models > ⚙️ > Model Parameters**. This silently applies to **every model** that doesn't explicitly set its own `function_calling` parameter. Per-model settings in **Workspace > Models > Edit > Advanced Params** will override the global default, but only if explicitly set — a model that simply doesn't have `function_calling` configured will inherit the global value.
+:::
+
+2. **Ensure Built-in Tools are enabled for the model** (if using native mode):
    - Go to **Workspace > Models > Edit** for your model
    - Under **Builtin Tools**, make sure the **Knowledge Base** category is enabled (it is by default)
    - If this is disabled, the model has no way to query attached knowledge bases
 
-2. **Add a system prompt hint**:
+3. **Add a system prompt hint** (if using native mode):
    - Some models need explicit guidance to use their tools. Add something like:
      > "When users ask questions, first use list_knowledge_bases to see what knowledge is available, then use query_knowledge_bases to search for relevant information before answering."
 
-3. **Or disable Native Function Calling** for that model:
+4. **Or disable Native Function Calling** for that model:
    - In the model settings, disable Native Function Calling to restore the classic auto-injection RAG behavior from earlier versions
 
-4. **Or use Full Context mode**:
+5. **Or use Full Context mode**:
    - Click on the attached knowledge base and select **"Use Entire Document"**
    - This bypasses RAG entirely and always injects the full content, regardless of native function calling settings
 

docs/troubleshooting/sso.mdx

@@ -74,6 +74,22 @@ Most OAUTH errors (loops, 401s, unresponsiveness) are due to an environment vari
 
 :::
 
+:::warning
+
+**Kubernetes/YAML users:** Watch out for **trailing spaces in environment variable names!** In YAML, quoting a key like `'OAUTH_CLIENT_ID '` (with a trailing space inside the quotes) will set a variable named `OAUTH_CLIENT_ID ` (with a space at the end), which Open WebUI will **not** recognize. Always ensure your env var names have no trailing whitespace:
+
+```yaml
+# ❌ Wrong — trailing space inside quotes:
+- name: 'OAUTH_CLIENT_ID '
+  value: your_client_id
+
+# ✅ Correct — no trailing space:
+- name: OAUTH_CLIENT_ID
+  value: your_client_id
+```
+
+:::
+
 ---
 
 ### 3. Missing Required Variables 🚨⚠️
@@ -106,7 +122,12 @@ OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-name/.w
 
 ### 4. Persistent Configuration Conflicts 🔄💾
 
-**New Issue:** Many users don't realize that OAuth settings are stored in the database after the first launch when `ENABLE_OAUTH_PERSISTENT_CONFIG=true` (default).
+**Important:** Open WebUI has **two** persistence settings that affect OAuth:
+
+1. **`ENABLE_PERSISTENT_CONFIG`** (defaults to **`true`**) — Controls whether *all* settings (including OAuth) are loaded from the database rather than environment variables, once they've been saved to the DB.
+2. **`ENABLE_OAUTH_PERSISTENT_CONFIG`** (defaults to **`false`**) — An *additional* gate specifically for OAuth settings. When set to `false`, OAuth settings with a config path starting with `oauth.` are **not** loaded from the database, even if `ENABLE_PERSISTENT_CONFIG` is `true`.
+
+By default, OAuth env vars **will** take priority over database values because `ENABLE_OAUTH_PERSISTENT_CONFIG` defaults to `false`. However, if you previously configured OAuth through the Admin Panel, those DB values may have been saved, and they will be loaded if `ENABLE_OAUTH_PERSISTENT_CONFIG` is later set to `true`.
 
 #### Symptoms:
 - Changes to environment variables don't take effect after restart
@@ -114,16 +135,16 @@ OPENID_PROVIDER_URL=https://your-authentik-domain/application/o/your-app-name/.w
 - "No token found in localStorage" errors after reconfiguration
 
 ✅ **Solutions:**
-1. **For Development/Testing:** Set `ENABLE_OAUTH_PERSISTENT_CONFIG=false` to always read from environment variables
+1. **For Development/Testing:** Ensure `ENABLE_OAUTH_PERSISTENT_CONFIG=false` (this is already the default) to always read from environment variables
 2. **For Production:** Either:
    - Configure settings through Admin Panel instead of environment variables, OR
-   - Temporarily set `ENABLE_OAUTH_PERSISTENT_CONFIG=false`, restart to apply new env vars, then set back to `true`
+   - Keep `ENABLE_OAUTH_PERSISTENT_CONFIG=false` (default) so that env vars always take priority for OAuth settings
 3. **Fresh Start:** Delete the database volume and restart with correct configuration
 
 📌 **Example for Docker Compose:**
 ```yaml
 environment:
-  - ENABLE_OAUTH_PERSISTENT_CONFIG=false  # Forces reading from env vars
+  - ENABLE_OAUTH_PERSISTENT_CONFIG=false  # Forces reading from env vars (this is the default)
   - OAUTH_CLIENT_ID=your_client_id
   - OAUTH_CLIENT_SECRET=your_secret
   - OPENID_PROVIDER_URL=your_provider_url