diff --git a/docs/faq.mdx b/docs/faq.mdx index 5dbd620f..9c2954be 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -130,19 +130,7 @@ docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host ### Q: Why are my reasoning model's thinking blocks showing as raw text instead of being hidden? -**A:** If you're using a reasoning/thinking model (like **DeepSeek-R1**, **Qwen3**, or similar) and the `...` content is displaying as raw text instead of being properly parsed and hidden, you need to configure Ollama with the correct **reasoning parser**. - -Start Ollama with the `--reasoning-parser` flag: - -```bash -ollama serve --reasoning-parser deepseek_r1 -``` - -This enables proper parsing of thinking blocks so they display in a collapsible section rather than as raw text in the response. The `deepseek_r1` parser works for most reasoning models. - -**Note:** This issue is most common with **non-streaming** requests (`stream: false`). Streaming mode typically handles reasoning blocks better by default. - -For detailed troubleshooting steps, see our [Reasoning Models Troubleshooting Guide](/troubleshooting/reasoning-models). +**A:** This happens if the model's thinking tags are not recognized by Open WebUI. You can customize the tags in the model's Advanced Parameters. For more details, see the **[Reasoning & Thinking Models](./features/chat-features/reasoning-models.mdx)** guide and our **[Reasoning Models Troubleshooting Guide](/troubleshooting/reasoning-models)**. ### Q: RAG with Open WebUI is very bad or not working at all. Why? diff --git a/docs/features/chat-features/index.mdx b/docs/features/chat-features/index.mdx index a2e7c2e2..93f191b8 100644 --- a/docs/features/chat-features/index.mdx +++ b/docs/features/chat-features/index.mdx @@ -22,3 +22,5 @@ Open WebUI provides a comprehensive set of chat features designed to enhance you - **[🔍 History & Search](./history-search.mdx)**: Navigate and search your previous conversations, or allow models to search them autonomously via native tools. - **[🕒 Temporal Awareness](./temporal-awareness.mdx)**: How models understand time and date, including native tools for precise time calculations. + +- **[🧠 Reasoning & Thinking Models](./reasoning-models.mdx)**: Specialized support for models that generate internal chains of thought using thinking tags. diff --git a/docs/features/chat-features/reasoning-models.mdx b/docs/features/chat-features/reasoning-models.mdx new file mode 100644 index 00000000..66824c28 --- /dev/null +++ b/docs/features/chat-features/reasoning-models.mdx @@ -0,0 +1,49 @@ +--- +sidebar_position: 10 +title: "Reasoning & Thinking Models" +--- + +# Reasoning & Thinking Models + +Open WebUI provides first-class support for models that exhibit "thinking" or "reasoning" behaviors (such as DeepSeek R1, OpenAI o1, and others). These models often generate internal chains of thought before providing a final answer. + +## How Thinking Tags Work + +When a model generates reasoning content, it typically wraps that content in specific XML-like tags (e.g., `...` or `...`). + +Open WebUI automatically: +1. **Detects** these tags in the model's output stream. +2. **Extracts** the content between the tags. +3. **Renders** the extracted content in a collapsible UI element labeled "Thought" or "Thinking". + +This keeps the main chat interface clean while still giving you access to the model's internal processing. + +## The `reasoning_tags` Parameter + +You can customize which tags Open WebUI should look for using the `reasoning_tags` parameter. This can be set on a **per-chat** or **per-model** basis. + +### Default Tags +By default, Open WebUI looks for several common reasoning tag pairs: +- ``, `` +- ``, `` +- ``, `` +- ``, `` +- ``, `` +- `<|begin_of_thought|>`, `<|end_of_thought|>` + +### Customization +If your model uses different tags, you can provide a list of tag pairs in the `reasoning_tags` parameter. Each pair is a tuple or list of the opening and closing tag. + +## Configuration & Behavior + +- **Stripping from Payload**: The `reasoning_tags` parameter itself is an Open WebUI-specific control and is **stripped** from the payload before being sent to the LLM backend (OpenAI, Ollama, etc.). This ensures compatibility with providers that do not recognize this parameter. +- **Chat History**: Thinking tags are **not** stripped from the chat history. If previous messages in a conversation contain thinking blocks, they are sent back to the model as part of the context, allowing the model to "remember" its previous reasoning steps. +- **UI Rendering**: Internally, reasoning blocks are processed and rendered using a specialized UI component. When saved or exported, they may be represented as HTML `
` tags. + +## Frequently Asked Questions + +### Why is the thinking block showing as raw text? +If the model uses tags that are not in the default list and have not been configured in `reasoning_tags`, Open WebUI will treat them as regular text. You can fix this by adding the correct tags to the `reasoning_tags` parameter in the Model Settings or Chat Controls. For more advanced issues, see the **[Reasoning Models Troubleshooting Guide](/troubleshooting/reasoning-models)**. + +### Does the model see its own thinking? +Generally, **no**. Because Open WebUI typically extracts the reasoning content into a separate field and removes the tags from the message's main `content` before it is saved or sent back as history, the model does not see its own previous reasoning in subsequent turns. This follows the design of reasoning models like OpenAI's `o1`, where the "chain of thought" is intended to be internal and ephemeral. diff --git a/docs/features/memory.mdx b/docs/features/memory.mdx index 6ce168ce..070a565d 100644 --- a/docs/features/memory.mdx +++ b/docs/features/memory.mdx @@ -42,7 +42,7 @@ Autonomous memory management works best with frontier models (GPT-5, Claude 4.5+ ## Enabling Memory Tools -1. **Global Toggle**: Ensure Memory is enabled in your user profile settings. +1. **Administrative Enablement**: Ensure the Memory feature is [enabled globally](#administrative-controls) by an administrator and that you have the required permissions. 2. **Native Mode (Agentic Mode)**: Enable **Native Function Calling** in the model's advanced parameters (**Admin Panel > Settings > Models > Model Specific Settings > Advanced Parameters**). 3. **Quality Models Required**: To unlock these features effectively, use frontier models with strong reasoning capabilities (e.g., GPT-5, Claude 4.5 Sonnet, Gemini 3 Flash, MiniMax M2.1) for the best experience. Small local models may not effectively manage memories autonomously. @@ -50,6 +50,20 @@ Autonomous memory management works best with frontier models (GPT-5, Claude 4.5+ For complete details on all built-in agentic tools (including memory, web search, and knowledge bases) and how to configure them, see the [**Native/Agentic Mode Tools Guide**](/features/plugin/tools#built-in-system-tools-nativeagentic-mode). ::: +## Administrative Controls + +Administrators have full control over the Memory feature, including the ability to disable it globally or restrict it to specific user groups. + +### Global Toggle +The Memory feature can be toggled on or off for the entire instance. When disabled, the "Personalization" tab is hidden from all users, and the memory-related API endpoints are blocked. +- **Admin UI**: Admin Panel > Settings > General > Features > **Memories** +- **Environment Variable**: [`ENABLE_MEMORIES`](/getting-started/env-configuration#enable_memories) (Default: `True`) + +### Granular Permissions +Administrators can also control Memory access on a per-role or per-group basis from the Permissions interface. +- **Admin UI**: Admin Panel > Users > Permissions > Features > **Memories** +- **Environment Variable**: [`USER_PERMISSIONS_FEATURES_MEMORIES`](/getting-started/env-configuration#user_permissions_features_memories) (Default: `True`) + ## Privacy & Security Memories are stored locally in your Open WebUI database and are specific to your user account. They are never shared across users, and you can clear your entire memory bank at any time. diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index dee9d4d4..c3f05aa4 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -207,6 +207,13 @@ is also being used and set to `True`. **Never disable this if OAUTH/SSO is not b - Description: Enables or disables the notes feature, allowing users to create and manage personal notes within Open WebUI. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_MEMORIES` + +- Type: `bool` +- Default: `True` +- Description: Enables or disables the [memory feature](/features/memory), allowing models to store and retrieve long-term information about users. +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `WEBHOOK_URL` - Type: `str` @@ -4962,6 +4969,13 @@ This is useful when you need a JWT access token for downstream validation or whe - Description: Enables or disables user permission to use code interpreter feature. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `USER_PERMISSIONS_FEATURES_MEMORIES` + +- Type: `str` +- Default: `True` +- Description: Enables or disables user permission to use the [memory feature](/features/memory). +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `USER_PERMISSIONS_FEATURES_FOLDERS` - Type: `str`